diff --git a/.agents/skills/topo-story-authoring/SKILL.md b/.agents/skills/topo-story-authoring/SKILL.md index 8a8303b..2bbf3af 100644 --- a/.agents/skills/topo-story-authoring/SKILL.md +++ b/.agents/skills/topo-story-authoring/SKILL.md @@ -46,11 +46,13 @@ Commit the source and authored story together. Build or refresh the generated site, preview the committed story, and inspect it locally: ```sh -npm exec --no -- topo scan . +npm exec --no -- topo init . npm exec --no -- topo story preview . stories/example.topo.json npm exec --no -- topo serve . ``` +Home inventories all committed supported stories, not only the preview target. +Scanning is optional for generated Repository exploration. Open `/stories//`. If source changes later, rerun validation before previewing and preserve identity plus unrelated authored intent during repairs. Humans review the authored explanation and generated view; they do not edit the @@ -58,6 +60,9 @@ renderer output in `.topo/cache/site`. Commit only when authorized by the repository owner. For a globally installed CLI, use `topo` directly instead of `npm exec --no -- topo`. +Source-grounded native rendering requires the repository's Git `origin` remote +for evidence validation. Do not invent a remote. Initialization and anchor-free +capability demos do not require one; demos must never replace factual evidence. ## Minimal source-grounded document diff --git a/.agents/skills/topo/SKILL.md b/.agents/skills/topo/SKILL.md index 0d80286..4751291 100644 --- a/.agents/skills/topo/SKILL.md +++ b/.agents/skills/topo/SKILL.md @@ -14,8 +14,10 @@ Corepack, model service, account or renderer download is needed. Use `npm exec --no -- topo init . --skills` for opt-in project context. Identical context files are preserved; differing files and symlinks fail explicitly. Do not overwrite existing skills/instructions or use a force flag. - Without `--skills`, init only initializes the workspace. -2. Run `npm exec --no -- topo scan .`. It scans TypeScript/JavaScript and renders + Both forms create a ready-to-serve diagram home without analysis, rendering + or browser/server launch, even in an empty/unborn repository. Repeated init + preserves authored context and the existing generated site. +2. Optionally run `npm exec --no -- topo scan .`. It scans TypeScript/JavaScript and renders committed stories plus Repository exploration. It never invokes a model. Unsupported/unresolved source fails; an explicitly requested `--allow-partial` preview is visibly partial and exits 2, not success. @@ -23,12 +25,17 @@ Corepack, model service, account or renderer download is needed. explanation from source evidence. Validate drafts; commit only with the repository owner's authority, then scan/preview the committed story. 4. Run `npm exec --no -- topo serve . --port 4173`. Review the printed loopback - URL: Repository canvas, story navigation, source evidence, theme and exports. + URL: Home inventory, optional Repository exploration, story navigation, + source evidence, theme and exports. Serve works immediately after init. Stop your server when finished; never kill another user's listener. 5. Run `npm exec --no -- topo bundle . --output ./site-output --base-path /architecture/`. Serve the output with a static server. Hosting, access control and uploading are separate owner decisions. Preserve all emitted license notices. +The init-first home is an unreleased source/local-candidate feature; public +npm 0.1.0 predates it. Use a candidate containing this change, not a claim that +the existing registry version was updated. + `topo enrich` is a separate, explicitly configured provider-command workflow for secondary commentary. It is not required for source-grounded story editing. Never execute an unknown enrichment command or claim inferred commentary is fact. diff --git a/CHANGELOG.md b/CHANGELOG.md index 25bbab9..0f3fd23 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,12 @@ publication remains a separate release-owner action. ### Added +- Create a ready-to-serve, branded diagram Home on plain or skills-enabled + `topo init`, including empty/unborn repositories without scanning. Reuse the + categorized inventory across Home and native story pages, keep Repository + exploration selectable and old deep links working, and bundle truthful + unscanned sites with notices. This is unreleased; public npm 0.1.0 is unchanged. + - Add GitHub-only publication of verified tarballs: normal OIDC and explicit first-package bootstrap through version/commit-bound tags, with a UI-managed token exposed only to its publish step. No local npm authentication is needed. diff --git a/README.md b/README.md index d9d987c..b1e29aa 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,12 @@ A local-first, deterministic code-architecture visualizer. ``` -scan -> generate -> publish +init -> serve -> author / scan -> bundle ``` -Scan a repository, build a canonical graph, publish a self-contained static site -into `.topo/`. No hosted service, no telemetry, no account. +Initialize a repository to create a ready-to-serve static diagram home in +`.topo/`. Add authored stories or scan supported source when needed. +No hosted service, no telemetry, no account. The goal is to put a software engineer in the human-in-the-loop position: every claim the tool makes about a codebase is backed by evidence you can follow, and @@ -24,17 +25,18 @@ everything a human adds is recorded as such. ## Install the toolbelt -After publication, install `@jdylanmc/topo-code@0.1.0` in your project, then run +The public `@jdylanmc/topo-code@0.1.0` predates the init-first home described +here. Use a locally built candidate tarball for this unreleased behavior; no +version bump or publication is implied. After installing the candidate, run `npm exec --no -- topo init . --skills`. This adds project-local Topocode skills and instructions without replacing existing files. Read -`.agents/skills/topo/SKILL.md`, scan, author/validate stories, preview and bundle -using the installed CLI. Plain `topo init` keeps workspace-only behavior. -Before publication, install both candidate tarballs in one npm command: +`.agents/skills/topo/SKILL.md`, serve, author/validate stories, preview and bundle +using the installed CLI. Plain `topo init` creates the same site without skills. +Install both candidate tarballs in one npm command: ```sh npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz npm exec --no -- topo init . --skills -npm exec --no -- topo scan . npm exec --no -- topo serve . ``` @@ -53,11 +55,14 @@ From this checkout, with Node.js 22+ and Corepack: corepack yarn install --immutable node scripts/bootstrap-renderer.mjs /path/to/jdylanmc-topo-archify-0.1.0.tgz corepack yarn build -corepack yarn topo scan /absolute/path/to/a/typescript-repository -corepack yarn topo serve /absolute/path/to/a/typescript-repository +corepack yarn topo init /absolute/path/to/a/repository +corepack yarn topo serve /absolute/path/to/a/repository ``` -Open the printed address. The default **Repository** view drills from packages +Open the printed address. **Home** is the diagram inventory, initially empty. +Initialization works with an empty/unborn Git repository, invokes no scanner, +model or native renderer, and starts no server or browser automatically. +Run `topo scan` to add **Repository** exploration, which drills from packages and directories into files, classes, functions, and other compiler declarations. Each scope is a bounded, source-backed Archify diagram; breadcrumbs, pagination, source evidence, and deep links work without a server-side query service. @@ -88,9 +93,10 @@ includes Topocode, Archify MIT, third-party, and JetBrains Mono SIL OFL 1.1 notices. Deployment, upload, public URLs, and authentication remain the hosting owner's responsibility. -`topo scan` renders every committed source-grounded story under +`topo scan` renders every supported committed story under `/stories//`; `topo story validate` checks an uncommitted authored -draft, and `topo story preview` refreshes one committed story. The retired +draft, and `topo story preview` refreshes the inventory and all committed +stories without requiring a scan. The retired WebGL explorer is not generated or bundled. See the [local agent authoring workflow](./docs/story-authoring.md), [catalogue configuration](./docs/story-catalogue.md), the @@ -129,7 +135,8 @@ node /absolute/path/to/topo-code/packages/cli/dist/main.js scan "$PWD" ``` Documentation uses `topo` as shorthand for that built entry point. The supported -input is a local Git repository containing TypeScript/JavaScript. Unknown +input for scanning is a local Git repository containing TypeScript/JavaScript. +Initialization and authored stories do not require scannable source. Unknown configuration, unresolved local/workspace imports and incomplete scans fail explicitly. An intentional `--allow-partial` preview is visibly non-authoritative and exits **2**, not success. See the [scanner contract](./docs/scanner.md). diff --git a/distribution/README.md b/distribution/README.md index b6085ab..fb1d641 100644 --- a/distribution/README.md +++ b/distribution/README.md @@ -6,18 +6,15 @@ model invocation during scanning. The exact renderer dependency is `@jdylanmc/topo-archify@0.1.0`, containing pristine upstream Archify **3.0.0**. ```sh -npm install --save-dev @jdylanmc/topo-code@0.1.0 +npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz npm exec --no -- topo init . --skills -npm exec --no -- topo scan . npm exec --no -- topo serve . npm exec --no -- topo bundle . --output ./site-output --base-path /architecture/ ``` -These registry commands apply **after publication**. For local candidates: - -```sh -npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz -``` +The init-first Home described here is **unreleased**. The already-public +`@jdylanmc/topo-code@0.1.0` predates it; use a local candidate containing this +change. No registry update or version bump is implied. Installing both tarballs in the same command satisfies the exact renderer dependency normally, without a fake registry, workspace links or source checkout. @@ -30,17 +27,21 @@ existing instructions, skills, authored stories or config. Identical files are preserved; differing destinations or symlinks fail explicitly. After a package upgrade, compare and deliberately reconcile installed context before retrying. An interrupted copy may leave new files; rerun safely, never force overwrite. -Plain `topo init` retains its existing workspace-only behavior. +Plain `topo init` creates the same ready-to-serve Home without skills. Both +forms work on empty/unborn repositories, invoke no scanner/model/native renderer, +and start no server/browser. Repeating init preserves the current site. Read the installed skills. Author `stories/**/*.topo.json` from actual source. `topo story validate . stories/example.topo.json` accepts drafts; preview requires committed stories. Preserve story/section/anchor identities when source moves. -Commit only with owner authority, then scan and +Commit only with owner authority, then run `topo story preview . stories/example.topo.json`. Validation proves structure and anchor resolution, not semantic accuracy. Before/after source-change examples ship in `examples/story-authoring/`. -The default Repository canvas exposes compiler/static evidence, not inferred +Home is the categorized diagram inventory, initially empty. Preview refreshes +all committed supported stories. Optional `topo scan .` adds a selectable +Repository canvas exposing compiler/static evidence, not inferred runtime behavior. Partial previews exit 2. `topo enrich` is a separate explicit provider-command surface, not part of scanning. Generated `.topo/cache` output is disposable; configuration and authored documents are not. diff --git a/distribution/topo.instructions.md b/distribution/topo.instructions.md index 7e1982d..4e39443 100644 --- a/distribution/topo.instructions.md +++ b/distribution/topo.instructions.md @@ -6,7 +6,9 @@ Read `.agents/skills/topo/SKILL.md` and `.agents/skills/topo-story-authoring/SKILL.md` before authoring Topocode content. Read `.agents/skills/topo-archify-maintenance/SKILL.md` before renderer maintenance. Use the installed `topo` executable (`npm exec --no -- topo ...` for a local -installation). Scan is model-free. Authored stories and configuration are source; +installation). Init creates a ready-to-serve Home inventory without scanning or +rendering; preview refreshes all committed stories. Scan adds selectable +Repository exploration and is model-free. Authored stories and configuration are source; `.topo/cache` is disposable generated output. Preserve existing story/section/ anchor identities and unrelated intent. Successful structural/anchor validation does not prove semantic truth. Never rewrite generated renderer output as source. diff --git a/docs/npm-release.md b/docs/npm-release.md index dbdedfb..4114bc8 100644 --- a/docs/npm-release.md +++ b/docs/npm-release.md @@ -3,6 +3,10 @@ Issue [#13](https://github.com/jdylanmc/topo-code/issues/13) ships one practical CLI-plus-skills toolbelt, not a public SDK. Initial candidate versions: +**Init-first Home is unreleased.** The already-public 0.1.0 predates this change. +Locally built 0.1.0 candidate tarballs can prove the change without changing +registry contents; do not republish that version or imply it contains this fix. + | npm package | Version | Upstream runtime | | --- | --- | --- | | `@jdylanmc/topo-archify` | 0.1.0 | Archify 3.0.0, `9286c3b9c2cef359e98586b420d769d87bcb163f` | @@ -68,7 +72,9 @@ composed legal notices. Debug source maps and tests do not ship. agent instructions or authored files. Differing files/symlinks are explicit conflicts; identical files allow repeat setup. It preflights all destinations before copying context. Files use exclusive creation; an interruption may leave -new files but never replaces old files. Plain init remains unchanged. +new files but never replaces old files. Both init forms now create the same +minimal branded Home with notices; skills remain opt-in. No scan, model, +source analysis, renderer invocation, server or browser launch occurs in init. ## Release owner gate diff --git a/docs/product-spec.md b/docs/product-spec.md index 812fb12..2ec4cdd 100644 --- a/docs/product-spec.md +++ b/docs/product-spec.md @@ -2,9 +2,10 @@ ## Status and provenance -Topocode is a local-first architecture storybook for a codebase. It scans a -local Git repository, checks source-grounded stories, renders them, and builds a -static site. The site has no hosted service, account, or telemetry. +Topocode is a local-first architecture storybook for a codebase. Initialization +creates a functional static Home inventory immediately; scanning and authored +story rendering add evidence and diagrams to the same shell. The site has no +hosted service, account, or telemetry. This file is the maintained product intent. GitHub issues track bounded work and keep delivery history. The original MVP specification is preserved in @@ -18,10 +19,13 @@ both surfaces, or required restoring the explorer, are superseded. Scanner, graph, layout, report, view, module, and enrichment data remain useful inputs. They are not a second visual explorer. -Issue #70's owner-aligned replacement adds a default Repository canvas in this +Issue #70's owner-aligned replacement adds a Repository canvas in this same shell: structural packages/directories, files, and compiler declarations rendered as bounded Archify views. This replaces neither authored stories nor their renderer-neutral contract and does not restore WebGL. +The approved init-first migration makes Home the default and Repository an +explicit selection. This source/local-candidate change is unreleased; public +npm 0.1.0 predates it. ## People and core workflow @@ -33,18 +37,21 @@ their renderer-neutral contract and does not restore WebGL. The normal workflow is: -1. An engineer or agent creates or updates a committed +1. `topo init` creates Home and notices, with optional `--skills` project + guidance. `topo serve` works now, even with no commit or supported source. +2. An engineer or agent creates or updates a committed `stories/**/*.topo.json` file. Humans should not need to hand-edit raw JSON. -2. `topo story validate` checks the document and its source anchors. -3. `topo scan` builds the graph, renders every committed story, and generates - the shell. -4. `topo serve` provides the local review loop. +3. `topo story validate` checks the document and its source anchors before + commit; `topo story preview` renders all committed stories into the inventory. +4. Optionally, `topo scan` builds the graph and adds Repository exploration. + `topo serve` provides the local review loop. 5. `topo bundle` emits plain static files for owner-managed hosting. These steps preserve the original author, browse, review, package, and customize scenarios. **S-1, S-2, S-3, S-4, S-5** -Scanning never invokes a model. Agent help is optional and local. `topo enrich` +Initialization invokes neither source analysis nor native rendering and starts +no server/browser. Scanning never invokes a model. Agent help is optional and local. `topo enrich` may run an explicitly configured provider command, but that is separate from scanning and structural validation. @@ -92,13 +99,17 @@ scanning and structural validation. collapsible grouping, diagram-family/category/folder/flat views, Git-backed sorting, deep links, and responsive left navigation. No hand-maintained index is required. **FR-03, AC-05** -- Repository exploration is the default landing canvas. It supports +- Home is the default categorized inventory, never an auto-selected diagram. + Topocode identity is permanent and separate from the configurable repository + title. Home and the left tree reuse one inventory and common controls. +- Repository exploration is an explicit selection. It supports package/directory-to-file-to-declaration drill-down, breadcrumbs, paginated native diagrams, source evidence and durable scope/page/focus URLs. Scanner and compiler facts remain distinct from runtime behavior; dirty, partial, stale and missing-evidence states are explicit. **#70** -- A repository with no stories still gets repository exploration and a clear - empty authored-story inventory. +- A repository with no stories gets a functional empty Home with accurate + author/validate/commit/preview steps. Unscanned state is explicit, without a + fabricated graph. Repository exploration appears after scanning. **AC-06, S-E2** - `.topo/config.json` may set the shell title, description, accent color, category order, and story category overrides. Configuration cannot load @@ -113,6 +124,9 @@ scanning and structural validation. the consumer. **FR-05, NFR-04, AC-08, S-4** - Bundles retain Topocode, Archify, third-party, and embedded JetBrains Mono notices. **NFR-01, AC-09** +- Initialized-only sites are bundleable without requiring HEAD; scanned sites + retain all existing freshness and evidence checks. Repeated init preserves + authored files and existing generated site/diagrams without downgrading them. - A local agent can create, validate, preview, and update a story without a mandatory model service. **FR-07, AC-12, S-1** @@ -167,7 +181,7 @@ This table preserves the disposition of every numbered original requirement. | --- | --- | | **FR-01; AC-01** | Shipped: committed renderer-neutral stories and runtime anchor resolution. | | **FR-02; AC-13, AC-15** | Shipped adapter and atomic failure behavior. The requirement to retain a parallel WebGL renderer is superseded by PR #71. | -| **FR-03; AC-05, AC-06** | Shipped story catalogue and empty state. The requirement to index the old explorer is superseded by PR #71. | +| **FR-03; AC-05, AC-06** | Init-first source migration: branded Home and truthful unscanned empty state; scan/preview populate one categorized inventory. Public npm 0.1.0 predates it. The old explorer requirement remains superseded by PR #71. | | **FR-04; AC-07** | Shipped through the existing serve command. | | **FR-05; NFR-04; AC-08** | Shipped host-agnostic static bundles. | | **FR-06; AC-11** | Partly shipped: bounded catalogue configuration. Broader composition/extensibility and the required manual walkthrough remain unresolved above. | @@ -203,8 +217,11 @@ sketch canvas (**N-4**), manual JSON authoring (**N-5**), an unlisted renderer fork or font changes (**N-6**), rebuilt commodity diagramming infrastructure (**N-7**), heuristic coverage gates (**N-8**), or restoration of the retired WebGL explorer. It does not authorize publishing under the `archify` name. +Rust/Tauri prototypes, Graphviz, plugin marketplaces and `.topo-view.json` +remain outside the supported core story contract; this migration integrates none. -Public npm publication remains a release-owner step in #13. The 0.1.0 candidate +Further npm publication remains a release-owner step. The existing public +0.1.0 does not contain the init-first migration. The local candidate CLI-plus-skills tarball, opt-in `topo init --skills`, exact renderer dependency, and clean installed-consumer regression are implemented; see [distribution](./npm-release.md). #57 is paused Unified Modeling diff --git a/docs/repository-exploration.md b/docs/repository-exploration.md index 930e1a5..c297965 100644 --- a/docs/repository-exploration.md +++ b/docs/repository-exploration.md @@ -1,12 +1,18 @@ # Repository exploration -`topo scan` generates the default Repository view in the existing storybook +`topo scan` generates the selectable Repository view in the existing storybook shell. It uses the scanner's file/import graph and compiler declaration inventory, not a model, an authored story, or the retired WebGL renderer. The same view works in `topo serve` and a plain static `topo bundle`. ## Explore +The root URL now opens the **Home inventory**. Select **Repository** to open +`?view=repository`. Existing root `?scope=...`, `?page=...`, and `?focus=...` +deep links still enter equivalent exploration directly, including under a static +base path. Repository breadcrumbs return to `?view=repository`; **Home** returns +to the unqualified root. Unknown selections remain explicit errors. + - Select a directory or package to drill into its children. Package names come from repository package manifests; directories retain their source paths. - Select a file to see its classes, functions and other represented compiler @@ -86,7 +92,7 @@ Generated files live under `.topo/cache/site/`: | `repository//viewer.html` | Native Archify artifact for one bounded page | | `repository-runtime/.js` / `.css` | Shared, integrity-checked native viewer runtime | | `repository-navigation.js` | Wrapper-side navigation and evidence interaction | -| `index.html` | Existing shell with repository exploration as its default canvas | +| `index.html` | Home inventory and selectable repository exploration in one shell | These are regenerable cache, not authored documents. A static bundle includes them beneath its configured base path and retains the existing notices. diff --git a/docs/story-authoring.md b/docs/story-authoring.md index 16a5a72..3e83157 100644 --- a/docs/story-authoring.md +++ b/docs/story-authoring.md @@ -7,6 +7,11 @@ document; and uses Topocode's objective validation and preview commands. No hosted model service is required, and `topo scan` never invokes an agent or model. +Start with `topo init ` and `topo serve ` for the empty Home. +After validating and committing a story, `topo story preview` populates the +same Home inventory with every supported committed story. `topo scan` is +optional for generated Repository exploration; it is not a preview prerequisite. + Source-grounded stories may select any native diagram family and must keep evidence on every section. Use `classification: "capability-demo"` only for an explicitly conceptual, anchor-free renderer demonstration; it is labelled as diff --git a/docs/story-catalogue.md b/docs/story-catalogue.md index 6353cd6..3d02dff 100644 --- a/docs/story-catalogue.md +++ b/docs/story-catalogue.md @@ -1,8 +1,12 @@ # Generated diagram catalogue -`topo scan` discovers every committed `stories/**/*.topo.json` document, +`topo init` creates a ready-to-serve empty catalogue without analysis. +`topo scan` and `topo story preview` discover every committed `stories/**/*.topo.json` document, validates and renders it through `@topo/story` and `@topo/diagram-core`, and -generates one Storybook-like application shell. Its default `/` canvas is +generate one application shell. Its default `/` is **Home**, the categorized +diagram inventory, never the first diagram or Repository canvas. Topocode +branding stays visible independently of the configured repository title. +After scanning, select **Repository** for [generated repository exploration](./repository-exploration.md). The same shell remains present on every `/stories//` page while the selected diagram renders through the pinned Archify viewer in the main iframe. @@ -41,8 +45,11 @@ reducing the viewer width. Collapsing the drawer or selecting a story exposes the readable viewer while retaining keyboard access and the saved preference. The retired WebGL repository explorer is not generated, served, or bundled. -Repositories with no stories show an explicit empty authored-diagram inventory -while retaining generated repository exploration. Scanner and compiler evidence +Repositories with no stories show accurate author/validate/commit/preview +steps. An unscanned site explicitly says so; scanning is optional for stories. +The Home list and left tree derive from the same generated entries and share +filtering, grouping and sorting. Home is reachable from every story; capability +demos stay labeled as not source-grounded. Scanner and compiler evidence drive that read-only view; layout, module, curated-view and enrichment artifacts retain their independent data contracts. @@ -68,7 +75,8 @@ Add only desired presentation and authored-category overrides to } ``` -Run `topo scan` again, then `topo serve`. Unknown keys, malformed colors, +Run `topo story preview` or `topo scan` again, then `topo serve`. Unknown keys, malformed colors, duplicate category-order entries, empty labels, and overrides for unknown story -IDs fail explicitly. Configuration changes copy and categorization only; it +IDs fail explicitly when the inventory is discovered (init does not discover +or render stories). Configuration changes copy and categorization only; it does not load executable addons or replace the pinned renderer. diff --git a/docs/story-preview.md b/docs/story-preview.md index 4982460..24f3846 100644 --- a/docs/story-preview.md +++ b/docs/story-preview.md @@ -37,10 +37,11 @@ non-factual, contain no repository anchors, and appear in the generated Wrappers preserve the classification in visible text and `data-story-classification`. -Scanning renders every committed story and composes the catalogue: +Initialize a site before preview; no scan is required: ```sh -corepack yarn topo scan /absolute/path/to/repository +corepack yarn topo init /absolute/path/to/repository +corepack yarn topo story preview /absolute/path/to/repository /absolute/path/to/repository/stories/checkout.topo.json corepack yarn topo serve /absolute/path/to/repository ``` @@ -53,7 +54,8 @@ inventory beside the main viewer iframe. Classification, summary, return, and node controls remain available without placing a second navigation card over the rendered diagram. The shell is served at `/` and on every story route; the retired repository explorer is not generated. Run -`topo preview` to refresh a specific committed story's viewer without rescanning: +`topo preview` to select a committed story while refreshing all committed +stories and the shared Home inventory without scanning: ```sh corepack yarn topo preview /absolute/path/to/repository \ @@ -76,6 +78,10 @@ The story file must be tracked, committed, and unchanged relative to `HEAD`. Source files may contain uncommitted changes: the CLI states that the preview describes the working tree while retaining the committed revision in rendered metadata. +Source-grounded native rendering also requires the repository's Git `origin` +remote for evidence validation. Initialization and anchor-free capability demos +do not require a remote. This is the existing native evidence contract, not an +instruction to invent a remote or misclassify factual stories as demos. An optional nonempty `category` field supplies the story's catalogue category. Without it, Topocode derives a category from the first directory below diff --git a/docs/workspace.md b/docs/workspace.md index 3eaab3d..7164bca 100644 --- a/docs/workspace.md +++ b/docs/workspace.md @@ -1,6 +1,10 @@ # The `.topo/` workspace -`topo scan ` initializes the workspace without replacing existing +`topo init ` initializes a ready-to-serve diagram home without +analysis, a model, native rendering, or a Git commit. `--skills` adds optional +authoring guidance; neither form launches a server/browser. Repeated init +preserves the current generated site, diagrams and authored context. +`topo scan ` also initializes the workspace without replacing existing configuration or human-authored metadata. Unknown config versions, malformed JSON and unsupported options are errors, not invitations to reset a workspace. @@ -19,6 +23,7 @@ JSON and unsupported options are errors, not invitations to reset a workspace. | `metadata/` | Human-authored notes and pins | Commit and review; never overwritten by generation | | `metadata/views/.json` | Named path view, overrides, pins, review baseline | Commit and review; explicit local saves only | | `cache/site/` | Compiled site assets and atomic data snapshot | Ignore; regenerate | +| `cache/site/site-state.json` | Explicit `unscanned` state, bound to repository ID; no graph/revision claim | Ignore; removed after scanned data is written | | `cache/site/repository.json` | Generated repository hierarchy, source evidence and page index | Ignore; regenerate with scan | | `cache/site/repository//viewer.html` | Pinned Archify views for bounded repository scopes | Ignore; included in static bundles | | `cache/enrichment-runs/` | Temporary command input, prompt and staged output | Ignore; owned run directories are cleaned after execution | @@ -65,6 +70,19 @@ Optional `catalogue` configuration changes the generated shell's title, description, accent color, category order, and per-story category overrides. It cannot add executable extensions or replace the pinned Archify renderer. See the [story catalogue walkthrough](./story-catalogue.md). +The repository title defaults to `repositoryId`; Topocode product branding +remains separate. Init does not refresh an existing site; use preview or scan. + +An initialized-only site (including an unborn Git repository) is bundleable. +It has shell assets and all legal notices, but no `data.json` or fake graph. +After story preview, it remains unscanned while carrying the full authored +inventory. Bundling refreshes committed stories when HEAD exists. Missing +scanned data cannot be bypassed with an unscanned marker; scanned bundles still +validate graph identity, revision, repository fingerprints and runtime assets. +Without HEAD, bundling requires the cached Home to match the current empty +initialized Home and no rendered stories to remain. A preview retained across +an orphan-branch switch is rejected without changing the cache or existing +bundle; restore the intended committed source before bundling. ## Layout and authored pins diff --git a/packages/cli/src/bundle.test.ts b/packages/cli/src/bundle.test.ts index f5c1bf1..4fee276 100644 --- a/packages/cli/src/bundle.test.ts +++ b/packages/cli/src/bundle.test.ts @@ -1,17 +1,20 @@ +import { deepStrictEqual } from "node:assert"; import { execFile } from "node:child_process"; import { + cp, mkdir, mkdtemp, readFile, readdir, rm, + stat, writeFile, } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { promisify } from "node:util"; -import { afterEach, describe, expect, it } from "vitest"; +import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"; import { createGraphDocument, createPathNodeId } from "@topo/schema"; import { initializeWorkspace } from "@topo/workspace"; import { bundleSite } from "./bundle.js"; @@ -33,8 +36,8 @@ async function temp(prefix: string): Promise { return directory; } -async function repository(): Promise { - const root = await temp("topo-bundle-test-"); +async function repository(directory?: string): Promise { + const root = directory ?? await temp("topo-bundle-test-"); await writeFile(join(root, "package.json"), '{"name":"fixture","type":"module"}\n'); await writeFile(join(root, "source.ts"), "export const value = 42;\n"); await execute("git", ["init", "--quiet"], { cwd: root }); @@ -53,6 +56,13 @@ async function repository(): Promise { return root; } +async function snapshotDirectory(root: string) { + return Promise.all((await readdir(root, { recursive: true })).sort().map(async (name) => { + const file = join(root, name); + return [name, (await stat(file)).isFile() ? await readFile(file) : null]; + })); +} + async function writeCachedSite(root: string): Promise { const { config } = await initializeWorkspace(root); const assets = await temp("topo-bundle-assets-"); @@ -98,6 +108,110 @@ afterEach(async () => { }); describe("static site bundle", () => { + it("bundles an initialized unborn repository without fabricating analysis", async () => { + const root = await temp("topo-bundle-unborn-"); + await execute("git", ["init", "--quiet", root]); + await execute(process.execPath, [entry, "init", root]); + const result = await bundleSite(root, join(await temp("topo-empty-output-"), "site"), { + basePath: "/docs/architecture/", + }); + expect(await readFile(join(result.siteDirectory, "index.html"), "utf8")).toContain("No diagrams yet"); + expect(await readFile(join(result.siteDirectory, "site-state.json"), "utf8")).toContain('"unscanned"'); + await expect(readFile(join(result.siteDirectory, "data.json"))).rejects.toMatchObject({ code: "ENOENT" }); + await rm(join(root, ".topo/cache/site/ARCHIFY_LICENSE.txt")); + await expect(bundleSite(root, result.outputDirectory)).rejects.toThrow("license notices are missing"); + }); + + describe("orphaned preview caches", () => { + let prepared: string | undefined; + let initializedHome: Buffer; + + beforeAll(async () => { + prepared = await mkdtemp(join(tmpdir(), "topo-orphan-preview-")); + const root = await repository(prepared); + await execute(process.execPath, [entry, "init", root]); + const site = join(root, ".topo/cache/site"); + initializedHome = await readFile(join(site, "index.html")); + await mkdir(join(root, "stories")); + await writeFile(join(root, "stories/value.topo.json"), JSON.stringify({ + schemaVersion: "1.0", + id: "value", + title: "Source value", + summary: "Explain the committed source value.", + anchors: [{ id: "value", path: "source.ts", symbol: "value" }], + sections: [{ + id: "value", title: "Value", body: "The source exports the value.", + anchorIds: ["value"], + }], + connections: [], + })); + await execute("git", ["add", "stories"], { cwd: root }); + await execute("git", [ + "-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", + "-c", "commit.gpgsign=false", "commit", "--quiet", "-m", "Source story", + ], { cwd: root }); + await execute(process.execPath, [ + entry, "story", "preview", root, join(root, "stories/value.topo.json"), + ]); + }); + + afterAll(async () => { + if (prepared !== undefined) await rm(prepared, { recursive: true, force: true }); + }); + + it.each(["complete preview", "inventory only", "rendered files only"])( + "rejects an orphan branch's cached %s without changing the existing bundle", + async (retained) => { + if (prepared === undefined) throw new Error("Native preview fixture was not prepared"); + const root = await temp("topo-orphan-case-"); + await cp(prepared, root, { recursive: true }); + const site = join(root, ".topo/cache/site"); + expect(await readFile(join(site, "index.html"), "utf8")).toContain('data-id="value"'); + expect(await readFile(join(site, "stories/value/viewer.html"), "utf8")).toContain(" { + const root = await repository(); + await execute(process.execPath, [entry, "init", root]); + await writeFile(join(root, ".topo/graph/graph.json"), "{}"); + await expect(bundleSite(root, join(await temp("topo-invalid-output-"), "site"))) + .rejects.toThrow("Scanned evidence exists"); + }); + + it("rejects an invalid initialized state rather than treating it as an empty graph", async () => { + const root = await repository(); + await execute(process.execPath, [entry, "init", root]); + await writeFile(join(root, ".topo/cache/site/site-state.json"), '{"kind":"unscanned"}'); + await expect(bundleSite(root, join(await temp("topo-invalid-output-"), "site"))) + .rejects.toThrow("Invalid unscanned site state"); + }); + it("publishes the composed site beneath the configured base path", async () => { const root = await repository(); await writeCachedSite(root); diff --git a/packages/cli/src/bundle.ts b/packages/cli/src/bundle.ts index 5612438..54fd294 100644 --- a/packages/cli/src/bundle.ts +++ b/packages/cli/src/bundle.ts @@ -1,9 +1,12 @@ import { randomUUID } from "node:crypto"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; import { cp, mkdir, mkdtemp, readFile, + readdir, rename, rm, stat, @@ -13,7 +16,7 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path"; import { BUILTIN_MODULE_MANIFESTS } from "@topo/modules"; import { parseSiteData } from "@topo/site/data"; import { isMissing, loadConfig, workspacePath } from "@topo/workspace"; -import { assertCatalogueCurrent, buildCatalogue, writeBuiltCatalogue } from "./catalogue.js"; +import { assertCatalogueCurrent, buildCatalogue, renderCataloguePage, writeBuiltCatalogue } from "./catalogue.js"; import { composeSiteData } from "./server.js"; import { assertRepositoryCurrent, readRepositoryIndex } from "./repository-generation.js"; @@ -80,14 +83,16 @@ async function readRequiredNotice( async function validateComposedSite( root: string, sourceDirectory: string, -): Promise { +): Promise { const dataPath = join(sourceDirectory, "data.json"); let value: unknown; try { value = JSON.parse(await readFile(dataPath, "utf8")) as unknown; } catch (error) { if (isMissing(error)) { - throw new Error("Site is not built; run topo scan first"); + await validateUnscannedSite(root); + await validateNotices(sourceDirectory); + return undefined; } throw new Error("Generated site data.json is invalid JSON", { cause: error, @@ -109,8 +114,62 @@ async function validateComposedSite( const repository = await readRepositoryIndex(root); if (repository !== undefined) await assertRepositoryCurrent(root, repository, catalogue.source); const config = await loadConfig(root); - await writeBuiltCatalogue(root, catalogue, config.catalogue); - const [notices, archifyLicense, fontLicense] = await Promise.all([ + await writeBuiltCatalogue(root, catalogue, { title: config.repositoryId, ...config.catalogue }); + await validateNotices(sourceDirectory); + return composed; +} + +async function validateUnscannedSite(root: string): Promise { + const config = await loadConfig(root); + let state: unknown; + try { + state = JSON.parse(await readFile(await workspacePath(root, "cache/site/site-state.json"), "utf8")) as unknown; + } catch (error) { + if (isMissing(error)) throw new Error("Site is not built; run topo init or topo scan first"); + throw error; + } + if (typeof state !== "object" || state === null || Array.isArray(state) || + !("schemaVersion" in state) || state.schemaVersion !== "1.0" || + !("kind" in state) || state.kind !== "unscanned" || + !("repositoryId" in state) || state.repositoryId !== config.repositoryId || + Object.keys(state).length !== 3) { + throw new Error("Invalid unscanned site state"); + } + for (const name of ["graph/graph.json", "cache/site/repository.json"]) { + if (await exists(await workspacePath(root, name))) { + throw new Error("Scanned evidence exists but site data.json is missing; run topo scan first"); + } + } + for (const name of ["index.html", "shell.js"]) { + if (!(await stat(await workspacePath(root, `cache/site/${name}`))).isFile()) { + throw new Error(`Missing initialized site asset: ${name}`); + } + } + // Without HEAD, cached stories cannot be revalidated against their source. + try { + await promisify(execFile)("git", ["-C", root, "rev-parse", "--verify", "--quiet", "HEAD"]); + } catch (error) { + if (error instanceof Error && "code" in error && error.code === 1) { + const initializedHome = renderCataloguePage([], { + title: config.repositoryId, ...config.catalogue, storyCategories: {}, + }); + const stories = await workspacePath(root, "cache/site/stories"); + if ( + await readFile(await workspacePath(root, "cache/site/index.html"), "utf8") !== initializedHome || + (await exists(stories) && (await readdir(stories)).length > 0) + ) { + throw new Error("Cannot bundle an unborn repository with a nonempty or unverified site cache; restore the committed source and regenerate before bundling."); + } + return; + } + throw error; + } + await writeBuiltCatalogue(root, await buildCatalogue(root), { title: config.repositoryId, ...config.catalogue }); +} + +async function validateNotices(sourceDirectory: string): Promise { + const [, notices, archifyLicense, fontLicense] = await Promise.all([ + readRequiredNotice(sourceDirectory, "LICENSE.txt"), readRequiredNotice(sourceDirectory, "THIRD_PARTY_NOTICES.txt"), readRequiredNotice(sourceDirectory, "ARCHIFY_LICENSE.txt"), readRequiredNotice(sourceDirectory, "JETBRAINS_MONO_LICENSE.txt"), @@ -125,7 +184,6 @@ async function validateComposedSite( "Built site license notices do not cover the embedded viewer and font; run corepack yarn build in the Topocode checkout.", ); } - return composed; } export async function bundleSite( @@ -165,7 +223,7 @@ export async function bundleSite( await mkdir(stagedSite, { recursive: true }); } await cp(sourceDirectory, stagedSite, { recursive: true }); - await writeFile(join(stagedSite, "data.json"), composedData); + if (composedData !== undefined) await writeFile(join(stagedSite, "data.json"), composedData); if (await exists(outputDirectory)) { await rename(outputDirectory, backup); movedExisting = true; diff --git a/packages/cli/src/catalogue.test.ts b/packages/cli/src/catalogue.test.ts index dd95b8b..865eee8 100644 --- a/packages/cli/src/catalogue.test.ts +++ b/packages/cli/src/catalogue.test.ts @@ -315,7 +315,8 @@ describe("generated catalogue", () => { (await loadConfig(root)).catalogue, ); - expect(page).toContain("System tours"); + expect(page).toContain("System tours | Topocode"); + expect(page).toContain('aria-label="Topocode home">Topocode'); expect(page).toContain("--accent: #ff5500"); expect(page).toContain("Critical paths"); expect(page).not.toContain("Dependency atlas"); diff --git a/packages/cli/src/catalogue.ts b/packages/cli/src/catalogue.ts index a9eeefa..9c6065e 100644 --- a/packages/cli/src/catalogue.ts +++ b/packages/cli/src/catalogue.ts @@ -1,6 +1,6 @@ import { createHash } from "node:crypto"; import { execFile } from "node:child_process"; -import { readFile, readdir, rm } from "node:fs/promises"; +import { readFile, readdir, rm, stat } from "node:fs/promises"; import { resolve } from "node:path"; import { promisify } from "node:util"; import { renderStory } from "@topo/diagram-core"; @@ -13,6 +13,9 @@ import { import { writeGenerated, workspacePath, + isMissing, + loadConfig, + withWorkspaceLock, type WorkspaceCatalogueConfig, } from "@topo/workspace"; import { @@ -55,6 +58,54 @@ export interface RepositoryState { const defaultRenderer: StoryRenderer = { render: renderStory }; +export const SITE_NOTICES = [ + "LICENSE.txt", "THIRD_PARTY_NOTICES.txt", "ARCHIFY_LICENSE.txt", + "JETBRAINS_MONO_LICENSE.txt", +] as const; + +/** Initialization publishes chrome only; source evidence is never synthesized. */ +export async function initializeSite(root: string, assets: string): Promise { + await withWorkspaceLock(root, async () => { + const index = await workspacePath(root, "cache/site/index.html"); + try { + if (!(await stat(index)).isFile()) throw new Error("Site index is not a file"); + return; + } catch (error) { + if (!isMissing(error)) throw error; + } + for (const name of ["graph/graph.json", "cache/site/data.json", "cache/site/repository.json"]) { + try { + await stat(await workspacePath(root, name)); + } catch (error) { + if (isMissing(error)) continue; + throw error; + } + throw new Error("Generated evidence exists without a site index; run topo scan to rebuild it."); + } + const config = await loadConfig(root); + // Category overrides are checked against the discovered inventory on preview/scan. + const presentation = { title: config.repositoryId, ...config.catalogue, storyCategories: {} }; + const files: [string, string | Buffer][] = [ + ...await Promise.all(SITE_NOTICES.map(async (name): Promise<[string, Buffer]> => + [name, await readFile(resolve(assets, name))])), + ["shell.js", SHELL_SCRIPT], + ["site-state.json", `${JSON.stringify({ + schemaVersion: "1.0", kind: "unscanned", repositoryId: config.repositoryId, + })}\n`], + ["index.html", renderCataloguePage([], presentation)], + ]; + for (const [name] of files) { + const destination = await workspacePath(root, `cache/site/${name}`); + try { + if (!(await stat(destination)).isFile()) throw new Error(`Site asset is not a file: ${name}`); + } catch (error) { + if (!isMissing(error)) throw error; + } + } + for (const [name, content] of files) await writeGenerated(root, `cache/site/${name}`, content); + }); +} + function escapeHtml(value: string): string { return value .replaceAll("&", "&") @@ -288,6 +339,7 @@ interface CatalogueEntry { readonly created: number | null; readonly modified: number | null; readonly href: string; + readonly classification: string; } interface StoryLink { @@ -450,6 +502,7 @@ const SHELL_SCRIPT = `(() => { modified: link.dataset.modified ? Number(link.dataset.modified) : null, href: link.getAttribute("href") || "", active: link.dataset.active === "true", + classification: link.dataset.classification || "Source-grounded", })); const status = document.querySelector("[data-shell-status]"); @@ -489,7 +542,18 @@ const SHELL_SCRIPT = `(() => { for (const key of ["group", "sort", "direction"]) { if (allowed[key].includes(saved[key])) controls[key].value = saved[key]; } - root.dataset.navigationCollapsed = saved.collapsed === true ? "true" : "false"; + root.dataset.navigationCollapsed = String(typeof saved.collapsed === "boolean" + ? saved.collapsed + : !document.body.dataset.storyId && window.matchMedia("(max-width: 1099px)").matches); + const params = new URLSearchParams(window.location.search); + if (!document.querySelector("[data-repository]") && !document.body.dataset.storyId && + ["view", "scope", "page", "focus"].some((key) => params.has(key))) { + const error = document.querySelector("[data-home-error]"); + if (error) { + error.hidden = false; + error.textContent = "Repository exploration is unavailable. Run topo scan to generate it."; + } + } function save() { if (!storageAvailable) return; @@ -544,10 +608,19 @@ const SHELL_SCRIPT = `(() => { return ""; } - function storyLink(entry) { + function storyLink(entry, home = false) { const link = document.createElement("a"); link.href = entry.href; link.textContent = entry.title; + if (home) { + const title = document.createElement("strong"); + title.textContent = entry.title; + const summary = document.createElement("span"); + summary.textContent = entry.summary; + const metadata = document.createElement("small"); + metadata.textContent = entry.family + " / " + entry.category + " / " + entry.classification; + link.replaceChildren(title, summary, metadata); + } link.dataset.kind = "story"; link.dataset.storyId = entry.id; if (entry.active) link.setAttribute("aria-current", "page"); @@ -572,21 +645,29 @@ const SHELL_SCRIPT = `(() => { [entry.title, entry.summary, entry.category, entry.family, entry.folder] .some((value) => value.toLocaleLowerCase().includes(query)) ).sort(compare); - list.replaceChildren(); + const homeList = document.querySelector("[data-home-inventory]"); + const count = document.querySelector("[data-inventory-count]"); + if (count) count.textContent = visible.length + " of " + entries.length + " diagrams"; + for (const target of [list, homeList].filter(Boolean)) renderInventory(target, visible); + } + + function renderInventory(target, visible) { + const home = target.hasAttribute("data-home-inventory"); + target.replaceChildren(); if (visible.length === 0) { const empty = document.createElement("p"); empty.className = "catalogue-empty"; empty.textContent = entries.length === 0 - ? "No diagrams are available." + ? "No diagrams yet." : "No diagrams match this filter."; - list.append(empty); + target.append(empty); return; } if (controls.group.value === "flat") { const flat = document.createElement("div"); flat.className = "story-links"; - for (const entry of visible) flat.append(storyLink(entry)); - list.append(flat); + for (const entry of visible) flat.append(storyLink(entry, home)); + target.append(flat); return; } const groups = new Map(); @@ -622,19 +703,20 @@ const SHELL_SCRIPT = `(() => { button.setAttribute("aria-expanded", "true"); const links = document.createElement("div"); links.className = "story-links"; - for (const entry of values) links.append(storyLink(entry)); + for (const entry of values) links.append(storyLink(entry, home)); button.addEventListener("click", () => { const expanded = button.getAttribute("aria-expanded") === "true"; button.setAttribute("aria-expanded", String(!expanded)); links.hidden = expanded; }); section.append(button, links); - list.append(section); + target.append(section); } } function updateCollapse() { const collapsed = root.dataset.navigationCollapsed === "true"; + controls.collapse.setAttribute("aria-expanded", String(!collapsed)); controls.collapse.setAttribute( "aria-label", collapsed ? "Expand diagram navigation" : "Collapse diagram navigation", @@ -729,6 +811,7 @@ export function renderStoryWrapper( links: readonly StoryLink[], config?: WorkspaceCatalogueConfig, historyIncomplete = false, + repository?: RepositoryIndex, ): string { const classification = story.document.classification ?? "source-grounded"; @@ -761,7 +844,7 @@ export function renderStoryWrapper(
    ${nodes}
- `); + `, repository); } function familyLabel(story: CatalogueStory): string { @@ -802,6 +885,8 @@ function catalogueEntries( folder: folderLabel(story.documentPath), created: story.history?.created ?? null, modified: story.history?.modified ?? null, + classification: story.document.classification === "capability-demo" + ? "Capability demo - not source-grounded" : "Source-grounded", href: storyPage ? `../../stories/${encodeURIComponent(story.document.id)}/` : `./stories/${encodeURIComponent(story.document.id)}/`, @@ -817,15 +902,15 @@ function renderShellPage( repository?: RepositoryIndex, ): string { const entries = catalogueEntries(stories, config, selected !== undefined); - const title = config?.title ?? "Topocode"; + const title = config?.title ?? "Repository diagrams"; const description = config?.description ?? - "The storybook for architects: source-grounded diagrams rendered through Archify."; + "Architecture, workflows, and source-grounded explanations in one place."; const accent = config?.accentColor ?? "#7dd3fc"; const selectedClassification = selected?.document.classification ?? "source-grounded"; const template = entries.map((entry) => - `${escapeHtml(entry.title)}`, + `${escapeHtml(entry.title)}`, ).join("\n"); const historyStatus = historyIncomplete ? "Git history is incomplete. Creation date unavailable for some diagrams." @@ -837,7 +922,7 @@ function renderShellPage( - ${escapeHtml(title)} + ${escapeHtml(title)} | Topocode