Topocode | Topocode

Story navigation and details

Source-grounded

The command interface and five modules re-exported by @topo/cli's package root. Arrows mean bin/export/type/dependency references, not a call sequence. This is a private workspace boundary bundled into @jdylanmc/topo-code, not a separately published or stable public SDK. Implementation helpers are deliberately omitted. Unlabelled spokes from the package box to API/utility boxes mean root exports; labelled edges distinguish other references.

topo commands Open Dependency context by role: Build, test, docs Open Dependency context by role: Development tools Open @topo/diagram-core: public surface: @topo/cli Open Topocode internal modules: @topo/cli Open From idea to architecture: Topocode CLI

The manifest exposes topo -> dist/main.js. Commands: init, scan, story validate, story preview (and preview), serve, bundle, ingest, enrich. Inputs: repository paths, authored stories, report files, and documented options. Outputs: diagnostics, generated storybook files, local URLs, and static bundles. scan supplies deterministic evidence; it does not invoke a model. runCli is exported by main.ts but is NOT re-exported from the package root.

packages/cli/package.json:1-40

{
  "name": "@topo/cli",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "bin": {
    "topo": "./dist/main.js"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b && node ../../scripts/package-skills.mjs",
    "typecheck": "tsc -b --pretty false",
    "test": "vitest run --no-file-parallelism"
  },
  "dependencies": {
    "@topo/diagram-core": "workspace:*",
    "@topo/enrichment": "workspace:*",
    "@topo/graph": "workspace:*",
    "@topo/languages": "workspace:*",
    "@topo/modules": "workspace:*",
    "@topo/reports": "workspace:*",
    "@topo/scanner": "workspace:*",
    "@topo/schema": "workspace:*",
    "@topo/site": "workspace:*",
    "@topo/story": "workspace:*",
    "@topo/views": "workspace:*",
    "@topo/workspace": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^22.20.1",
    "typescript": "^7.0.2",
    "vite": "8.2.2",
    "vitest": "^5.0.0"
  }
}

packages/cli/src/main.ts:21-39

HELP = `Topocode: local, deterministic repository maps

  topo init [repository] [--skills]
  topo scan [repository] [--allow-partial] [--responsibilities path]
  topo ingest <repository> <report.json> [more.json ...]
  topo enrich [repository]
  topo preview <repository> <story>
  topo story validate <repository> <story>
  topo story preview <repository> <story>
  topo serve [repository] [--port 4173]
  topo bundle [repository] [--output directory] [--base-path /path/]

Requires a Git repository and Node.js 22 or newer.
Scan is strict by default. --allow-partial publishes a visibly incomplete
preview and exits 2; it never turns partial evidence into success.
Serve binds only to 127.0.0.1. Config and authored metadata are never overwritten.
Init creates a ready-to-serve diagram home without scanning or opening a browser.
Scan adds repository exploration; story preview refreshes all committed stories.
`

Generation API
Root exports from pipeline.ts: generateArtifacts(root, graph, siteAssets, logicalArchitecture?, catalogue?) -> Promise<ArtifactGenerationResult> ingestReports(root, inputPaths, siteAssets, expectedRevision?, catalogue?) -> Promise<ReportIngestionResult> ArtifactGenerationResult: layout, optional dashboard, warnings. ReportIngestionResult: dashboard, warnings. Generation takes an already-supplied GraphDocument; do not confuse this API with the topo scan command. Referenced contracts include @topo/schema, @topo/graph and @topo/reports. BuiltCatalogue appears in signatures but is not itself a root re-export.
packages/cli/src/index.ts:1-5
```
export * from "./server.js";
export * from "./bundle.js";
export * from "./pipeline.js";
export * from "./enrichment.js";
export * from "./views.js";
```
packages/cli/src/pipeline.ts:186-192
```
export async function generateArtifacts(
  root: string,
  graph: GraphDocument,
  siteAssets: string,
  logicalArchitecture?: LogicalArchitectureDocument,
  catalogue?: BuiltCatalogue,
): Promise<ArtifactGenerationResult> {
```
packages/cli/src/pipeline.ts:180-184
```
export interface ArtifactGenerationResult {
  layout: LayoutResult;
  dashboard: DashboardDocument | null;
  warnings: string[];
}
```
packages/cli/src/pipeline.ts:245-251
```
export async function ingestReports(
  root: string,
  inputPaths: string[],
  siteAssets: string,
  expectedRevision?: string,
  catalogue?: BuiltCatalogue,
): Promise<ReportIngestionResult> {
```
packages/cli/src/pipeline.ts:240-243
```
export interface ReportIngestionResult {
  dashboard: DashboardDocument;
  warnings: string[];
}
```

Referenced contracts

The exposed functions reference GraphDocument and LogicalArchitectureDocument (@topo/schema), LayoutResult (@topo/graph), DashboardDocument (@topo/reports), CuratedViewsSnapshot / SaveCuratedViewRequest (@topo/views), Node's Server, and AbortSignal. These are signature dependencies, not claims that @topo/cli re-exports all those types. Named result/option interfaces defined in the five exported modules are root exports.

packages/cli/src/pipeline.ts:186-192

export async function generateArtifacts(
  root: string,
  graph: GraphDocument,
  siteAssets: string,
  logicalArchitecture?: LogicalArchitectureDocument,
  catalogue?: BuiltCatalogue,
): Promise<ArtifactGenerationResult> {

packages/cli/src/pipeline.ts:180-184

export interface ArtifactGenerationResult {
  layout: LayoutResult;
  dashboard: DashboardDocument | null;
  warnings: string[];
}

packages/cli/src/pipeline.ts:240-243

export interface ReportIngestionResult {
  dashboard: DashboardDocument;
  warnings: string[];
}

packages/cli/src/server.ts:150-150

export async function serveSite(root: string, port = 4173): Promise<{ server: Server; url: string }> {

packages/cli/src/enrichment.ts:43-45

export interface EnrichmentRunOptions {
  signal?: AbortSignal;
}

packages/cli/src/views.ts:235-239

export async function saveCuratedView(
  root: string,
  request: SaveCuratedViewRequest,
  loadGraph: () => Promise<GraphDocument>,
): Promise<CuratedViewsSnapshot> {

packages/cli/src/views.ts:37-43

export interface CuratedViewsBuild {
  snapshot: CuratedViewsSnapshot;
  evaluations: Array<{
    id: string;
    evaluation: CuratedViewEvaluation;
  }>;
}

Serving API
Root exports from server.ts: serveSite(root, port?) -> Promise<{ server: Server; url: string }> composeSiteData(root, input) -> Promise<string | undefined> serveSite exposes a loopback HTTP server over the generated site; it does not author architecture. composeSiteData composes site data for consumers. Source-backed diagrams and website assets remain separate from these function signatures.
packages/cli/src/index.ts:1-5
```
export * from "./server.js";
export * from "./bundle.js";
export * from "./pipeline.js";
export * from "./enrichment.js";
export * from "./views.js";
```
packages/cli/src/server.ts:150-150
```
export async function serveSite(root: string, port = 4173): Promise<{ server: Server; url: string }> {
```
packages/cli/src/server.ts:137-140
```
export async function composeSiteData(
  root: string,
  input: unknown,
): Promise<string | undefined> {
```

@topo/cli Open Dependency context by role: Build, test, docs Open Dependency context by role: Development tools Open @topo/diagram-core: public surface: @topo/cli Open Topocode internal modules: @topo/cli Open From idea to architecture: Topocode CLI

Two entry surfaces: the topo binary and the package-root index.ts barrel. The barrel re-exports server, bundle, pipeline, enrichment, and views. Declared runtime module references: @topo/diagram-core: workspace:* @topo/enrichment: workspace:* @topo/graph: workspace:* @topo/languages: workspace:* @topo/modules: workspace:* @topo/reports: workspace:* @topo/scanner: workspace:* @topo/schema: workspace:* @topo/site: workspace:* @topo/story: workspace:* @topo/views: workspace:* @topo/workspace: workspace:* The diagram singles out diagram-core so you can continue into its exposed rendering contract. Catalogue, snapshot, skills, and repository-generation helpers are not root exports and are not expanded here.

packages/cli/package.json:1-40

{
  "name": "@topo/cli",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "bin": {
    "topo": "./dist/main.js"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b && node ../../scripts/package-skills.mjs",
    "typecheck": "tsc -b --pretty false",
    "test": "vitest run --no-file-parallelism"
  },
  "dependencies": {
    "@topo/diagram-core": "workspace:*",
    "@topo/enrichment": "workspace:*",
    "@topo/graph": "workspace:*",
    "@topo/languages": "workspace:*",
    "@topo/modules": "workspace:*",
    "@topo/reports": "workspace:*",
    "@topo/scanner": "workspace:*",
    "@topo/schema": "workspace:*",
    "@topo/site": "workspace:*",
    "@topo/story": "workspace:*",
    "@topo/views": "workspace:*",
    "@topo/workspace": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^22.20.1",
    "typescript": "^7.0.2",
    "vite": "8.2.2",
    "vitest": "^5.0.0"
  }
}

packages/cli/src/index.ts:1-5

export * from "./server.js";
export * from "./bundle.js";
export * from "./pipeline.js";
export * from "./enrichment.js";
export * from "./views.js";

Bundling API

Root exports from bundle.ts: bundleSite(rootInput, outputInput, options?) -> Promise<BundleSiteResult> BundleSiteOptions: optional basePath. BundleSiteResult: basePath, outputDirectory, siteDirectory. Produces a static site directory. Deployment, a domain, and publication approval are not implied by this API.

packages/cli/src/index.ts:1-5

export * from "./server.js";
export * from "./bundle.js";
export * from "./pipeline.js";
export * from "./enrichment.js";
export * from "./views.js";

packages/cli/src/bundle.ts:189-193

export async function bundleSite(
  rootInput: string,
  outputInput: string,
  options: BundleSiteOptions = {},
): Promise<BundleSiteResult> {

packages/cli/src/bundle.ts:23-25

export interface BundleSiteOptions {
  readonly basePath?: string;
}

packages/cli/src/bundle.ts:27-31

export interface BundleSiteResult {
  readonly basePath: string;
  readonly outputDirectory: string;
  readonly siteDirectory: string;
}

Enrichment API
Root exports from enrichment.ts: runEnrichment(root, options?) -> Promise<EnrichmentRunResult> buildEnrichmentPrompt(inputPath, outputPath, analysisHash, customPrompt?) -> string EnrichmentRunOptions: optional AbortSignal. EnrichmentRunResult: analysisHash and comments count. This is the explicit configured provider-command workflow. It is not automatically called by scan, and it is not the same thing as an agent independently interpreting evidence while authoring a story.
packages/cli/src/index.ts:1-5
```
export * from "./server.js";
export * from "./bundle.js";
export * from "./pipeline.js";
export * from "./enrichment.js";
export * from "./views.js";
```
packages/cli/src/enrichment.ts:234-237
```
export async function runEnrichment(
  root: string,
  options: EnrichmentRunOptions = {},
): Promise<EnrichmentRunResult> {
```
packages/cli/src/enrichment.ts:57-62
```
export function buildEnrichmentPrompt(
  inputPath: string,
  outputPath: string,
  analysisHash: string,
  customPrompt?: string,
): string {
```
packages/cli/src/enrichment.ts:43-45
```
export interface EnrichmentRunOptions {
  signal?: AbortSignal;
}
```
packages/cli/src/enrichment.ts:38-41
```
export interface EnrichmentRunResult {
  analysisHash: string;
  comments: number;
}
```

Curated-view API

Root exports from views.ts: buildCuratedViews; saveCuratedView; graphHash; parseSaveCuratedViewRequest; serializeCuratedViewsSnapshot; serializeCuratedViewDeltas; graphFromSiteBundle; augmentSiteBundle. Contracts: CuratedViewsBuild, CuratedViewConflictError, CuratedViewMetadataError. Save requests and returned snapshots use @topo/views types; graph inputs use @topo/schema. This is the exposed path-based curated-view surface, not arbitrary diagram authoring or a private implementation map.

packages/cli/src/index.ts:1-5

export * from "./server.js";
export * from "./bundle.js";
export * from "./pipeline.js";
export * from "./enrichment.js";
export * from "./views.js";

packages/cli/src/views.ts:156-159

export async function buildCuratedViews(
  root: string,
  graph: GraphDocument,
): Promise<CuratedViewsBuild> {

packages/cli/src/views.ts:235-239

export async function saveCuratedView(
  root: string,
  request: SaveCuratedViewRequest,
  loadGraph: () => Promise<GraphDocument>,
): Promise<CuratedViewsSnapshot> {

packages/cli/src/views.ts:37-43

export interface CuratedViewsBuild {
  snapshot: CuratedViewsSnapshot;
  evaluations: Array<{
    id: string;
    evaluation: CuratedViewEvaluation;
  }>;
}

packages/cli/src/views.ts:195-195

export function parseSaveCuratedViewRequest(input: unknown): SaveCuratedViewRequest {

packages/cli/src/views.ts:49-49

export function graphHash(graph: GraphDocument): string {

packages/cli/src/views.ts:183-183

export function serializeCuratedViewsSnapshot(snapshot: CuratedViewsSnapshot): string {

packages/cli/src/views.ts:187-187

export function serializeCuratedViewDeltas(build: CuratedViewsBuild): string {

packages/cli/src/views.ts:288-288

export function graphFromSiteBundle(input: unknown): GraphDocument {

packages/cli/src/views.ts:297-297

export function augmentSiteBundle(input: unknown, snapshot: CuratedViewsSnapshot): string {

packages/cli/src/views.ts:34-34

export class CuratedViewConflictError extends Error {}

packages/cli/src/views.ts:35-35

export class CuratedViewMetadataError extends Error {}

@topo/diagram-core Open @topo/diagram-core: public surface Open Dependency context by role: Build, test, docs Open Dependency context by role: Development tools Open Topocode internal modules: @topo/cli Open From idea to architecture: Topocode CLI Open Dependency context by role: Rendering Open Dependency context by role: Archify and Graphviz Open Topocode internal modules: @topo/diagram-core

A declared workspace dependency of @topo/cli. It exposes renderers that consume resolved stories and return HTML artifacts with provenance. Click to open its public-surface diagram. This is a dependency reference, not a claim that the CLI barrel re-exports diagram-core's APIs.

packages/cli/package.json:1-40

{
  "name": "@topo/cli",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "bin": {
    "topo": "./dist/main.js"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b && node ../../scripts/package-skills.mjs",
    "typecheck": "tsc -b --pretty false",
    "test": "vitest run --no-file-parallelism"
  },
  "dependencies": {
    "@topo/diagram-core": "workspace:*",
    "@topo/enrichment": "workspace:*",
    "@topo/graph": "workspace:*",
    "@topo/languages": "workspace:*",
    "@topo/modules": "workspace:*",
    "@topo/reports": "workspace:*",
    "@topo/scanner": "workspace:*",
    "@topo/schema": "workspace:*",
    "@topo/site": "workspace:*",
    "@topo/story": "workspace:*",
    "@topo/views": "workspace:*",
    "@topo/workspace": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^22.20.1",
    "typescript": "^7.0.2",
    "vite": "8.2.2",
    "vitest": "^5.0.0"
  }
}

packages/diagram-core/package.json:1-34

{
  "name": "@topo/diagram-core",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "files": [
    "dist",
    "archify-pin.json",
    "LICENSE",
    "THIRD_PARTY_NOTICES.md"
  ],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b",
    "typecheck": "tsc -b --pretty false",
    "test": "tsc -b && node --test test/*.test.mjs"
  },
  "dependencies": {
    "@topo/story": "workspace:*",
    "@viz-js/viz": "3.30.0"
  },
  "peerDependencies": {
    "@jdylanmc/topo-archify": "0.1.0"
  },
  "devDependencies": {
    "@types/node": "^22",
    "typescript": "^7.0.2"
  }
}