feat(docs-site): HTML documentation-site generator wired as meta docs --site

[dmealing]

Intent

Bring a proven HTML documentation-site generator into the metaobjects monorepo as @metaobjectsdev/docs-site, wired as a 'meta docs --site' surface, in three phases on this branch.

Phase 1 (port): new server/typescript/packages/docs-site package (loader, link-graph, page builders, mermaid emitters, site orchestrator, link-check) + templates + assets + a generic 'acme' fixture + golden test. CLI: a --site surface on 'meta docs' that is ADDITIVE to the markdown --model/--api surfaces (when --site is the only surface flag, markdown is deliberately suppressed via an explicit empty surface list; combined with --model/--api both emit). The site has its OWN model loader, so a site-only run returns before the sdk loadMemory path. Strict-mode type fixes were needed because the monorepo tsconfig is stricter than the source project (exactOptionalPropertyTypes/noUncheckedIndexedAccess) — these are type-only, golden byte-identical.

Phase 2 (shared relationship IR): re-source the site's relationship diagram edges from the metadata relationship PRIMITIVES (deriveM2MFields, findReferenceBetween, MetaRelationship getters), keeping LinkGraph as the graph shell. Deliberate design decisions (approved by the user): the M:N-through junction is KEPT as its own node AND a distinct logical M:N edge is added (faithfulness over decluttering); relationship-vs-bare-FK double edges are de-duplicated (richer relationship edge wins); M:N renders as mermaid }o--o{ (ER) / dashed (flowchart); onDelete/junction fold into the edge label. This surfaced and fixed a REAL bug in the shared SSOT: deriveM2MFields resolved the @through junction by bare name only while @through is written fully-qualified — now FQN-aware (mirrors the existing meta-identity idiom) + a regression test. Verified this was a TS-ONLY deviation: the Python and Java/Kotlin ports already handle FQN @through, so the fix brings TS into sync (ports-sync doctrine satisfied). The acme fixture was deliberately extended with M:N + directed/symmetric self-joins + onDelete, so its golden regenerates.

Phase 3 (scaffold-and-own, ADR-0034): 'meta docs --scaffold-site' copies the site templates+assets into codegen/docs-site/ write-only-if-absent (never clobbers edits); generateSite gains an assetsDir override so owned CSS/JS win; 'meta docs --site' auto-detects codegen/docs-site/ and uses the owned copies (bundled fallback). Deliberately genericized the mermaid CURATED palette: dropped the hardcoded domain-name->color map (a vocabulary carryover from the source project) for a neutral hashed palette — golden stayed byte-identical.

Constraints held throughout: metaobjects is PUBLIC (no private/downstream names, no absolute local paths in anything committed); determinism (byte-identical golden across two regenerations) + link-check (throws on dangling) gates; no new package dependency (primitives come from @metaobjectsdev/metadata, already a dep). Validated end-to-end via the real meta CLI (scaffold->edit->owned-copy-wins) + a scale smoke on an in-repo conformance model (20 pages, 0 dangling). Suites green: docs-site 40/0, cli 366/0, metadata 2097/0, all typecheck clean.

What Changed

• Added a new @metaobjectsdev/docs-site package (loader, link-graph, page builders, mermaid emitters, site orchestrator, link-check, templates, assets, and an acme golden fixture) that emits a static HTML documentation site from metadata.
• Wired a --site surface onto meta docs that is additive to the markdown --model/--api surfaces (site-only runs suppress markdown), plus a --scaffold-site command that copies templates/assets into codegen/docs-site/ write-only-if-absent and a generateSite assetsDir override so owned CSS/JS win over the bundled defaults (ADR-0034 scaffold-and-own); --site auto-detects the owned copies.
• Re-sourced the relationship diagram edges from the metadata relationship primitives (deriveM2MFields/findReferenceBetween), rendering M:N as ER }o--o{/dashed flowchart edges with onDelete/junction labels, and fixed deriveM2MFields to resolve a fully-qualified @through junction by FQN as well as bare name (with a regression test) — bringing TS in line with the Python/Java ports. A Node crash from Bun-only import.meta.dir in site.ts/scaffold.ts was corrected via the fileURLToPath idiom during review.

Risk Assessment

✅ Low: A large but well-bounded new package addition guarded by byte-identical golden tests and a link-check gate, with the only prior error (Node import.meta.dir crash) already fixed and the shared metadata M2M change correctly scoped, tested, and consistent with the other language ports.

Testing

Ran the branch's own gate suites (docs-site 40/0, cli 367/0, metadata M:N regression 15/0), then drove the real meta docs CLI end-to-end against the generic acme fixture to produce a 22-page HTML site. Captured reviewer-visible screenshots via headless Chrome of the home page (Core ERD with the neutral hashed palette), the Order entity page (Fields/Indexes/Validators/Relationships/Inheritance plus the Neighborhood ER diagram rendering the Phase-2 M:N-via-junction edge and onDelete label), the shop package index, and the coverage page. Additionally verified determinism (two regenerations byte-identical), the additive-surface semantics (site-only suppresses markdown; --site --model emits both), and the Phase-3 scaffold-and-own loop (scaffold → owned-CSS-wins → re-scaffold preserves the edit). All checks passed; the worktree stayed clean (all generated output written under /tmp). One background test task showed exit 143, but that was an initial run terminated by a working-directory issue and was superseded by a successful foreground re-run of the same suite.

• Evidence: Site home page — Core ERD + stats + package cards (meta docs --site) (local file: /tmp/no-mistakes-evidence/01KWQK9VTJYWAPC4PTNESX4SCA/home.png)
• Evidence: Order entity page — Neighborhood ER diagram showing Phase-2 M:N-via-OrderProduct edge + onDelete label (local file: /tmp/no-mistakes-evidence/01KWQK9VTJYWAPC4PTNESX4SCA/order-entity.png)
• Evidence: Shop package index page (local file: /tmp/no-mistakes-evidence/01KWQK9VTJYWAPC4PTNESX4SCA/shop-package.png)
• Evidence: Coverage page — rendered node kinds & attributes (local file: /tmp/no-mistakes-evidence/01KWQK9VTJYWAPC4PTNESX4SCA/coverage.png)

Evidence: Scaffold-and-own + determinism CLI transcript

meta docs --scaffold-site — 11 created, 0 preserved
(edit owned assets/site.css)
meta docs --site — wrote 22 page(s)
generated site.css carries OWNED-THEME-MARKER-EVIDENCE → OWNED CSS WON
meta docs --scaffold-site — 0 created, 11 preserved → PRESERVED hand-edit
Determinism: diff -rq of two regenerations → IDENTICAL (byte-for-byte)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed ✅

• 🚨 server/typescript/packages/docs-site/src/site.ts:63 - docs-site resolves its bundled templates/assets with import.meta.dir, a Bun-only global that is undefined under Node. resolve(import.meta.dir, "../templates") therefore becomes resolve(undefined, ...) and throws TypeError: The "path" argument must be of type string. Received undefined when the CLI runs from its published Node build (dist/bin/meta.js, produced by tsc, which imports docs-site's dist/index.js default export). Both meta docs --site and meta docs --scaffold-site crash for Node consumers. Tests don't catch it because they run under bun test, which resolves the package's bun export condition to src where import.meta.dir works. The repo's established Node-safe idiom is dirname(fileURLToPath(import.meta.url)) (used in codegen-ts for exactly this Node/compiled-binary compatibility). Affects site.ts:63, site.ts:73, and scaffold.ts:22.
• ℹ️ server/typescript/packages/docs-site/src/builders/index-data.ts:11 - SiteOptions.core / CoreConfig (pin/exclude/n) is accepted, typed, and threaded through to buildIndexPage(..., { core: opts.core, ... }), but buildIndexPage never reads opts.core — the core-map size (CORE_MAX=28) and seed counts (8/5/3) are hardcoded. The CLI's core: { n: 15 } in emitSite is therefore dead config. Either wire it into buildIndexPage or drop the option to avoid implying it has effect.

🔧 Fix: fix Node import.meta.dir crash and wire docs-site core config
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bun test packages/docs-site/test → 40 pass / 0 fail (loader, link-graph, mermaid, golden byte-identical, scaffold, link-check)
• bun test packages/cli/test → 367 pass / 2 skip / 0 fail (docs command surface)
• bun test packages/metadata/test/relationship-m2m.test.ts → 15 pass / 0 fail (FQN @through junction regression)
• meta docs <acme> --site via real CLI run() → wrote 22 pages, exit 0; captured screenshots of home/index, Order entity (M:N ER diagram), shop package, coverage
• Determinism: regenerated the site twice and diff -rq reported byte-identical output
• Phase 3: meta docs --scaffold-site (11 created) → edited owned assets/site.css → re-ran --site and grepped the generated site.css for the owned marker (owned CSS won) → re-scaffolded and confirmed the hand-edit preserved (0 created / 11 preserved)
• Additive surfaces: site-only run emits no markdown at the out root; --site --model emits 16 markdown pages AND the site/index.html

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.