@topogram/cli 0.3.34

package/ARCHITECTURE.md

@@ -0,0 +1,67 @@
+# Topogram Architecture
+
+Topogram turns a `.tg` workspace into generated artifacts and apps through five layers:
+
+1. `Topogram graph`
+2. `realization`
+3. normalized `contracts`
+4. generator manifest + adapter
+5. optional implementation provider
+
+## Flow
+
+1. `engine/src/parser` reads `.tg` files into an AST.
+2. `engine/src/validator` validates statements and projection semantics.
+3. `engine/src/resolver` produces a resolved semantic graph.
+4. `engine/src/realization` derives target-ready realization objects from that graph.
+5. `engine/src/generator` builds normalized contracts and resolves topology-bound generator manifests.
+6. Bundled or package-backed generator adapters render stack-specific files.
+7. Workspace `implementation/` modules supply project-specific reference behavior that should not live in the generic engine.
+
+## Boundaries
+
+`engine/src/realization`
+- Owns normalized semantic interpretation.
+- Converts projections into stable realization objects.
+- Should be domain-agnostic and projection-driven.
+
+`engine/src/generator`
+- Owns contract emission, generator manifest validation, and file emission.
+- Dispatches through topology-bound generator adapters.
+- Should be contract-aware and stack-adapter-aware, not example-aware.
+
+Generator adapters
+- Own stack-specific realization such as React, SvelteKit, Hono, Express,
+  Postgres, SQLite, Prisma, Drizzle, SwiftUI, or future Android files.
+- Consume normalized contracts, topology component metadata, and optional
+  implementation hooks.
+- Return generated files and diagnostics through the shared generator interface.
+
+Workspace `implementation/`
+- Owns project-specific runtime/reference behavior.
+- Can include seed data, custom page renderers, repository implementations, and runtime-check specifics.
+- Must not be treated as engine contracts.
+
+`component` statements live in the semantic graph beside entities, capabilities,
+shapes, and projections. They produce `componentContract` resolver enrichment
+and can be emitted through the `ui-component-contract` generator target without
+requiring an implementation provider.
+
+## Stable Internal Contracts
+
+The engine currently treats these realization types as stable internal interfaces:
+
+- `ApiRealization`
+- `DbRealization`
+- `UiSharedRealization`
+- `WebAppRealization`
+- `BackendRuntimeRealization`
+
+Renderers should consume these contracts instead of rediscovering domain meaning from raw statements.
+
+## Active Proof Targets
+
+The active repo proof target is intentionally small:
+
+- `engine/tests/fixtures/workspaces/app-basic`: engine-owned authoring-to-app fixture
+- Private `topogram-demo-todo` repo: package-consumer generated app demo

package/CHANGELOG.md

@@ -0,0 +1,240 @@
+# Changelog
+
+## Unreleased
+
+- Install package-backed generator dependencies during `topogram template check`
+  before starter validation.
+
+## 0.3.16 - 2026-05-03
+
+- Install package-backed generator dependencies during `topogram template check`
+  before starter validation.
+
+## 0.3.15 - 2026-05-03
+
+- Carry package-backed generator dependencies from template packages into
+  generated starter package devDependencies.
+
+## 0.3.14 - 2026-05-03
+
+- Add the bundled generator manifest/adapter interface so first-party stack
+  generators dispatch through topology-bound generator manifests.
+- Add explicit package-backed generator loading for installed packages with
+  `topogram-generator.json` manifests and synchronous adapter exports.
+- Document generator packs as the long-term boundary for reusable stack
+  realization while templates compose generator IDs and optional implementation
+  customizations.
+- Make SvelteKit route generation contract-complete by default: generic route
+  files are generated from the Topogram contract first, and template
+  implementation providers may override specific route files.
+- Emit SvelteKit `src/lib/topogram/generation-coverage.json` so generated apps
+  record routed-screen coverage, implementation-vs-generator ownership,
+  component rendering coverage, and diagnostics when projection intent is not
+  realized.
+- Emit the same generation coverage artifact for React apps so web generators
+  share a common route and component coverage contract.
+
+## 0.3.13 - 2026-05-01
+
+- Add `topogram component check` as a user-facing alias for component
+  conformance reports. The command prints a human summary by default, supports
+  `--projection`, `--component`, and `--json`, and exits non-zero when
+  conformance errors are present.
+
+## 0.3.12 - 2026-05-01
+
+- Add `component-conformance-report` generator target. The report compares
+  `projection.ui_components` usage against component contracts, includes
+  inherited shared-UI usages for concrete web projections, supports
+  `--projection` and `--component` filters, and reports repair-oriented checks
+  for missing required props, event action context, component status, approvals,
+  write scope, and projection/component impact.
+
+## 0.3.11 - 2026-05-01
+
+- Add `domain` statement kind for grouping the spec by business slice
+  (FIS, RNF, DrugTrac, etc.). Identifier prefix `dom_`. Required fields:
+  `name`, `description`, `status`. Optional: `in_scope`, `out_of_scope`,
+  `owners`, `parent_domain`, `aliases`. Validator enforces identifier
+  prefix, scope-list shapes, owner refs (`actor`|`role`), parent_domain
+  refs, and parent-domain cycle detection.
+- Add optional singular `domain` field on `capability`, `entity`, `rule`,
+  `verification`, `orchestration`, `operation`, and `decision`. Cross-kind
+  validator hard-errors on unknown ids and wrong-kind references.
+- Resolver populates `resolvedDomain` on each tagged statement and a
+  reverse-indexed `members` block on each `domain` (capabilities,
+  entities, rules, verifications, orchestrations, operations, decisions).
+- `context-slice --domain <id>` returns a focused subgraph
+  (`focus.kind === "domain"`, members summarized, projections that
+  realize any of its capabilities, plus a `domain_surface` review
+  boundary). The same `--domain` selector flows through
+  `verification-targets`, `change-plan`, `review-packet`, and the rest
+  of the query family.
+- `query domain-coverage --domain <id>` emits a per-platform realization
+  matrix (capabilities × platforms) plus the projections involved.
+- `query domain-list` lists all domains with member counts for navigation.
+- New `domain-coverage` and `domain-page` generator targets. The latter
+  emits markdown summaries at `topogram/docs-generated/domains/{slug}.md`
+  per domain (members, in/out-of-scope, per-platform coverage table).
+- `context-diff` now emits a `domains` section.
+- `workspace-docs` recognizes a singular `domain:` frontmatter field on
+  documents; the validator checks the reference.
+- New docs: `docs/domains.md` (full guide); `docs/grammar.md` updated
+  with the `domain` row and the optional-field paragraph;
+  `docs/topogram-workspace-layout.md` appends a "Domain organization"
+  subsection.
+- New fixture `engine/tests/fixtures/domains/feedlot/` (3 domains,
+  10 capabilities, 12 entities, 4 cross-platform projections) and
+  golden tests at `engine/tests/active/domain-kind.test.js`.
+
+### SDLC layer (Phase 2)
+
+- Add five new SDLC statement kinds: `pitch` (`pitch_`), `requirement`
+  (`req_`), `acceptance_criterion` (`ac_`), `task` (`task_`), and `bug`
+  (`bug_`). Plus a markdown-only `document` (`doc_`) kind via
+  `workspace-docs.js`. Each kind has its own status set, identifier
+  pattern, required/allowed fields, and per-kind validator.
+- Generalize `validateStatus` into a per-kind status table
+  (`STATUS_SETS_BY_KIND`) so `decision` (existing) and the new SDLC
+  kinds (`pitch`, `requirement`, `acceptance_criterion`, `task`, `bug`)
+  each enforce their own status sequences.
+- Extend existing kinds: `verification` gains `requirement_refs`,
+  `acceptance_refs`, `fixes_bugs`; `decision` gains `pitch`,
+  `supersedes`; `rule` gains `from_requirement`. All validate via the
+  generalized cross-reference checker.
+- Resolver builds 20+ new SDLC back-link arrays
+  (`pitch.requirements`, `requirement.acceptanceCriteria`,
+  `acceptance_criterion.tasks`, `task.blockingMe`, `bug.verifiedBy`,
+  `rule.introducedByRequirements`, `rule.violatedByBugs`,
+  `decision.introducedByTasks`, `capability.affectedByPitches`,
+  `capability.affectedByRequirements`, `capability.affectedByTasks`,
+  `capability.affectedByBugs`, etc.) so consumers can traverse the
+  shape-the-work → ship → defect → verification chain without
+  re-walking the graph.
+- Extend `domain.members` with SDLC arrays (`pitches`, `requirements`,
+  `tasks`, `bugs`, `documents`).
+- Six new `context-slice` selectors: `--pitch`, `--requirement`,
+  `--acceptance`, `--task`, `--bug`, `--document`. Each returns the
+  same shape as existing slices (focus + summary + depends_on + related
+  + verification + write_scope + review_boundary) with kind-appropriate
+  review-boundary reasons (`pitch_scope`, `requirement_scope`,
+  `task_scope`, `bug_scope`, `document_scope`).
+- `context-diff` folds SDLC artifact changes into a new `sdlc` section
+  covering pitch/requirement/AC/task/bug deltas.
+- New `engine/src/sdlc/` core module: per-kind state machines under
+  `transitions/`, per-kind DoD checks under `dod/`, history sidecar
+  (`.topogram-sdlc-history.json`) for transition records, default-active
+  status filtering, and a top-level orchestrator that surgically rewrites
+  `.tg` `status` fields without disturbing surrounding formatting.
+- New `engine/src/archive/` module: year-bucketed JSONL archive
+  (`topogram/_archive/{kind}s-{year}.jsonl`), resolver bridge that
+  auto-loads frozen entries at workspace-parse time so traceability
+  still sees them, plus `archive` / `unarchive` / `compact` operations.
+- New CLI subcommand group: `topogram sdlc transition <id> <status>`,
+  `sdlc check`, `sdlc explain <id>` (with structured `next_action`
+  output), `sdlc archive`, `sdlc unarchive`, `sdlc compact`,
+  `sdlc new <kind> <slug>`, `sdlc adopt`, plus `topogram release`
+  for atomic changelog assembly + document `app_version` stamping +
+  archive trigger (with `--dry-run`).
+- Four new generator targets: `sdlc-board` (kanban with `--kind`
+  filter), `sdlc-doc-page` (rendered markdown per document with
+  cross-ref sidebar), `sdlc-release-notes` (assembled from approved
+  pitches + done tasks + verified bugs in a release window), and
+  `sdlc-traceability-matrix` (pitch → req → AC → task/bug →
+  verification table with gap detection).
+- `workspace-docs` extended: 7 new `DOC_KINDS` (`user-guide`, `api`,
+  `architecture`, `operations`, `getting-started`, `reference`,
+  `development`); 3 new `DOC_STATUSES` (`review`, `published`,
+  `archived`); `app_version`, `audience`, `priority`, `version`,
+  `affects`, `satisfies`, `approvals` frontmatter fields.
+- New docs: `docs/sdlc.md` (kinds, lifecycles, slices, release flow,
+  agent-loop pattern), `docs/lifecycles.md` (per-kind state diagrams
+  and DoD reference), and the SDLC layout subsection in
+  `docs/topogram-workspace-layout.md`.
+- New fixture `engine/tests/fixtures/workspaces/app-basic/` with one
+  pitch + requirement + AC + task + bug + archived JSONL bug, plus 21
+  golden tests at `engine/tests/active/sdlc-kinds.test.js` covering
+  validators, resolver back-links, six new slice selectors, three
+  generators (board/release-notes/traceability), state-machine
+  transitions, DoD rules, archive load/save, transition round-trips
+  (rewrite + history sidecar), and release dry-run output.
+- Add `projection.ui_components` so projections explicitly own component
+  placement and wiring. Component usage validates screen, region, component,
+  prop, event, data-source, and event-target references.
+- Remove `component.consumers` from the component grammar before external
+  adoption; component usage now flows from projections instead of components
+  self-registering consumers.
+- Add structured component `behaviors { ... }` alongside the shorthand
+  `behavior [...]`, with validation for supported stack-agnostic behavior
+  kinds and behavior references to component props/events.
+- Emit `approvals` and normalized `behaviors` in `ui-component-contract`
+  artifacts.
+- Include component usage metadata in generated UI contracts. Concrete web
+  projections that realize a shared UI projection now inherit the shared
+  projection's component usages and component contracts.
+- Fix component diff impact for removed components by resolving projection
+  impact from the baseline graph.
+
+## 0.3.0 - 2026-05-01
+
+- Add `component` statement kind for reusable UI/service component contracts
+  (props, events, slots, patterns, regions, dependencies, consumers).
+- Add `ui-component-contract` generator target that emits stable JSON per
+  component or for the whole workspace; selectable via `--component <id>`.
+- `context-diff` now emits a `components` section, and changed components
+  fan out into `affected_generated_surfaces.projections` so consumer
+  projections show up in diff payloads.
+- `context-slice --component <id>` returns a first-class component slice with
+  `focus.kind === "component"`, dependent shapes/projections/verifications,
+  and a `component_surface` review boundary; the same selector flows through
+  `verification-targets`, `change-plan`, `risk-summary`, `review-packet`,
+  `proceed-decision`, `next-action`, `single-agent-plan`, and
+  `resolved-workflow-context`.
+- `topogram generate ... --generate ui-component-contract --component <id>`
+  now errors loudly when the id does not match any component (previously it
+  wrote a `null` artifact).
+- Component prop defaults preserve real values: `default true`, `default false`,
+  `default null`, integers, floats, quoted strings, and `default []` are all
+  surfaced in the generated contract instead of collapsing to `null`.
+- Add `docs/grammar.md` as the first authoritative reference for `.tg`
+  statement kinds.
+
+## 0.2.22 - 2026-04-29
+
+- Record catalog provenance when `topogram new --template <catalog-id>` resolves
+  a template alias to a package-backed template.
+- Preserve the catalog alias/source in project template metadata, template file
+  baselines, and executable implementation trust records.
+
+## 0.2.21 - 2026-04-29
+
+- Add private catalog commands: `topogram catalog list`, `catalog check`, and
+  `catalog copy`.
+- Include catalog template aliases in `topogram template list`.
+- Allow `topogram new --template <catalog-id>` to resolve package-backed
+  template entries from the catalog.
+- Keep pure topogram catalog entries non-executable in v1.
+
+## 0.1.0 - 2026-04-15
+
+Initial `v0.1` release candidate for the Topogram reference toolchain.
+
+Highlights:
+
+- parser, validator, and semantic resolver for the Topogram DSL
+- typed semantic graph for the Todo reference domain
+- JSON Schema, docs, API contract, OpenAPI, UI contract, DB contract, and debug generators
+- shared UI semantics plus web realization and SvelteKit scaffold generation
+- Postgres and SQLite DB projections
+- DB schema snapshots, additive migration planning, Prisma and Drizzle schema generation
+- repository scaffolds and Hono server generation
+- DB lifecycle automation for greenfield bootstrap and brownfield migration
+- local environment, deployment, smoke-test, compile-check, and polished app-bundle generation
+- seeded demo data path for the generated Todo app golden path
+
+Known boundaries:
+
+- Prisma is the most complete generated runtime profile
+- Drizzle runtime implementations remain scaffolds
+- destructive or ambiguous DB migrations are intentionally manual
+- deployment bundles are strong starting points, not turnkey production infrastructure

package/README.md

@@ -0,0 +1,223 @@
+# Topogram Engine
+
+This folder contains the Topogram implementation: parser, validator, resolver, generators, runtime bundle emitters, and CLI.
+
+The active product workflow is authoring-to-generated-app. Engine development should stay separate from user-facing demos.
+
+## Package Shape
+
+The engine is the publishable private CLI package:
+
+```json
+{
+  "name": "@topogram/cli",
+  "bin": {
+    "topogram": "./src/cli.js"
+  }
+}
+```
+
+This lets source checkouts and private-package consumers call:
+
+```bash
+topogram new ../my-app
+topogram version
+topogram version --json
+topogram doctor
+topogram check
+topogram generate
+topogram catalog list
+topogram catalog show todo
+topogram catalog check topograms.catalog.json
+topogram catalog copy hello ../hello-topogram
+topogram import ../existing-app --out ../imported-topogram
+topogram import check ../imported-topogram
+topogram release status
+topogram package update-cli --latest
+topogram source status ../hello-topogram --local
+topogram source status ../hello-topogram --remote
+topogram template list
+topogram template explain
+topogram template status
+topogram template policy check
+topogram template policy pin @scope/template@0.2.0
+topogram template check ../my-template
+topogram template update --plan
+topogram trust template
+```
+
+Publishing is manual through the repo-level `Publish CLI Package` workflow. Create generated projects outside `engine/`; this directory is source and test code.
+
+From the repo root, prefer:
+
+```bash
+npm run smoke:test-app
+npm run cli:check
+npm run new -- ./my-topogram-app
+```
+
+## Layout
+
+- `src/` - engine source
+- `tests/active/` - retained active engine tests
+- `tests/fixtures/templates/` - local template fixtures used by engine tests
+- `tests/fixtures/workspaces/` - engine-owned Topogram workspaces
+- `tests/fixtures/expected/` - engine-owned golden outputs
+- `tests/fixtures/invalid/` - invalid model cases
+
+The generated Todo demo and Todo starter template live outside this repo in `topogram-demo-todo` and `topogram-template-todo`.
+
+## Active Fixture
+
+The current generated-app regression fixture is:
+
+```text
+tests/fixtures/workspaces/app-basic/
+tests/fixtures/expected/app-basic/
+```
+
+It is a fixture, not a user example.
+
+## Commands
+
+Run the engine gate:
+
+```bash
+npm run check
+```
+
+Create a starter project from the catalog-backed default `hello-web` alias:
+
+```bash
+topogram new ../my-topogram-app --template hello-web
+cd ../my-topogram-app
+npm install
+npm run doctor
+npm run check
+```
+
+Choose another catalog starter with the template commands:
+
+```bash
+topogram template list
+topogram template show web-api
+topogram new ../web-api-demo --template web-api
+```
+
+Create a starter project from a shared template package:
+
+```bash
+topogram new ../todo-demo --template @topogram/template-todo
+topogram new ../todo-demo --template todo
+```
+
+Catalog aliases resolve through the private catalog index at
+`github:attebury/topograms/topograms.catalog.json`. The catalog is package
+backed; executable starter content still lives in template packages. Use
+`topogram catalog show <id>` to inspect an entry and get the correct `new` or
+`copy` command for that kind. Use `topogram template show <id>` when the entry
+is known to be a starter template and you want the direct `topogram new` flow.
+Pure
+topogram catalog entries can be copied for editing with
+`topogram catalog copy <id> <target>`. Copied topogram projects record
+`.topogram-source.json`; inspect local drift from that import baseline with
+`topogram source status <target> --local`. This metadata is provenance only and does not
+block local edits, checks, or generation. Template baseline divergence means the
+local project owns those edits; executable implementation trust is the separate
+state that can block generation until reviewed.
+Run `topogram template detach <target>` when the project should stop tracking
+template update metadata while keeping normal check/generate behavior.
+
+Do not create generated projects under `engine/`. The CLI refuses paths inside the engine directory.
+
+Template pack authoring and trust policy are documented in `../docs/template-authoring.md`.
+Catalog layout and private access are documented in `../docs/catalog.md`.
+Projects created from executable templates include `.topogram-template-trust.json`;
+regenerate it with `topogram trust template` after reviewing copied
+`implementation/` code. Use `topogram template status` for the lifecycle
+summary, then `topogram trust status` and `topogram trust diff` to inspect
+changed files before refreshing trust.
+
+Projects also include `topogram.template-policy.json`, the allow policy used by
+template update and template check commands. It can restrict candidate template
+sources, template ids, package scopes, executable-template behavior, and pinned
+template versions:
+
+```bash
+topogram template policy check
+topogram template policy explain
+topogram template policy init
+topogram template policy pin @scope/template@0.2.0
+```
+
+Use `topogram template policy explain` for a rule-by-rule view of the current
+project template, package scope, catalog provenance, executable implementation
+setting, and pinned version state.
+
+Use `topogram template status --latest` and `topogram template update --latest`
+only for package-backed templates when an explicit registry lookup is desired.
+Plain status and update commands do not query the registry.
+
+Use `topogram template update --status [--template <spec>]` to inspect current
+template adoption state with baseline and conflict analysis. Use
+`topogram template update --recommend [--template <spec>]` for a concise
+human/agent next-step summary before applying, adopting, or deleting files. Use
+`topogram template update --plan [--template <spec>]` to compare the current
+project with a candidate template without writing files. Use
+`topogram template update --check [--template <spec>]` as the no-write CI guard;
+it exits nonzero when the project is not aligned with the recorded or supplied
+template. Any update mode can write a machine-readable review report with
+`--out <path>`. After review, `topogram template update --apply [--template
+<spec>]` writes added/changed template-owned files, records a new
+`.topogram-template-files.json` baseline, skips deletes, and refuses local
+conflicts. Existing projects can run `topogram trust template` after review to
+record the first template-owned file baseline. JSON output includes structured
+diagnostics with codes, paths, suggested fixes, and workflow steps.
+
+Single-file adoption actions are explicit and baseline-aware:
+`--accept-current <file>` records the current file as the trusted baseline,
+`--accept-candidate <file>` applies one candidate file after baseline checks,
+and `--delete-current <file>` deletes one current-only file only when it still
+matches the trusted baseline.
+
+Template authors can run `topogram template check <template-spec-or-path>` to
+validate manifest/layout, temporary starter creation, starter checks, trust
+metadata, and no-write update planning. The JSON form reports structured
+diagnostics with codes, paths, and suggested fixes for authoring feedback.
+
+Run the same gate directly:
+
+```bash
+npm test
+```
+
+Run only the active fixture validity check:
+
+```bash
+npm run fixture:check
+```
+
+Inspect the active fixture topology as JSON:
+
+```bash
+npm run fixture:check:json
+```
+
+Generate the active fixture app bundle:
+
+```bash
+npm run fixture:generate
+```
+
+Run the app-generation workflow test:
+
+```bash
+node --test ./tests/active/generated-app-workflow.test.js
+```
+
+Validate or generate through the public CLI shape:
+
+```bash
+node ./src/cli.js check ./tests/fixtures/workspaces/app-basic
+node ./src/cli.js generate ./tests/fixtures/workspaces/app-basic --out /tmp/topogram-app
+```

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@topogram/cli",
+  "version": "0.3.34",
+  "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/attebury/topogram.git",
+    "directory": "engine"
+  },
+  "type": "module",
+  "bin": {
+    "topogram": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "template-helpers",
+    "README.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "new": "node ./src/cli.js new",
+    "check": "npm test",
+    "fixture:check": "node ./src/cli.js check ./tests/fixtures/workspaces/app-basic",
+    "fixture:check:json": "node ./src/cli.js check ./tests/fixtures/workspaces/app-basic --json",
+    "fixture:generate": "node ./src/cli.js generate ./tests/fixtures/workspaces/app-basic --out ./.tmp/app-basic",
+    "check:fixture": "npm run fixture:check",
+    "parse": "node ./src/cli.js ./tests/fixtures/workspaces/app-basic",
+    "parse:json": "node ./src/cli.js ./tests/fixtures/workspaces/app-basic --json",
+    "validate": "node ./src/cli.js validate ./tests/fixtures/workspaces/app-basic",
+    "validate:bad": "node ./src/cli.js validate ./tests/fixtures/invalid/missing-reference",
+    "resolve": "node ./src/cli.js ./tests/fixtures/workspaces/app-basic --resolve",
+    "generate:app": "npm run fixture:generate",
+    "generate:app-bundle": "npm run fixture:generate",
+    "test:types": "tsc -p ./tsconfig.check.json",
+    "test:active": "npm run test:types && node --test ./tests/active/*.test.js",
+    "test": "npm run test:active"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "typescript": "^5.6.3"
+  }
+}

package/src/adoption/index.js

@@ -0,0 +1,3 @@
+export function buildAdoptionStatus(runWorkflow, inputPath, options = {}) {
+  return runWorkflow("adoption-status", inputPath, options);
+}