forma-arch 0.1.0

package/lib/gen.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// gen-c4-model.mjs — emit docs/architecture/c4-model.json from real code + curated topology.
+// Leaves are walked LIVE from src/ (always current). Topology/context/runtime-edges are curated.
+// Usage: node gen-c4-model.mjs [--repo <path>] [--topology <path>] [--out <path>]
+import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { join, dirname, basename, relative } from 'node:path'
+import { execSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
+const REPO = arg('--repo', process.cwd())
+const TOPO = arg('--topology', join(REPO, 'docs/architecture/c4-topology.json'))
+const OUT = arg('--out', join(REPO, 'docs/architecture/c4-model.json'))
+const SCHEMA_VERSION = '1.1.0'
+
+const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
+const rp = (p) => join(REPO, p)
+const fail = (m) => { console.error('[gen-c4] FAIL: ' + m); process.exit(1) }
+
+function walk(spec) {
+  const dir = rp(spec.dir)
+  if (!existsSync(dir)) fail(`leafSource dir missing: ${spec.dir}`)
+  const re = new RegExp(spec.match), ex = spec.exclude ? new RegExp(spec.exclude) : null
+  return readdirSync(dir).filter((f) => {
+    const full = join(dir, f)
+    if (spec.filesOnly !== false && statSync(full).isDirectory()) return false
+    if (!re.test(f)) return false
+    if (ex && ex.test(f)) return false
+    return true
+  }).sort()
+}
+function countMatches(file, pattern, unique) {
+  const p = rp(file)
+  if (!existsSync(p)) fail(`countFrom file missing: ${file}`)
+  const txt = readFileSync(p, 'utf-8')
+  const m = txt.match(new RegExp(pattern, 'g')) || []
+  return unique ? new Set(m).size : m.length
+}
+
+const nodes = []
+const byId = new Map()
+const add = (n) => { if (byId.has(n.id)) fail('dup node id ' + n.id); byId.set(n.id, n); nodes.push(n) }
+
+// 1) curated non-leaf nodes (context/container/component)
+for (const n of topo.nodes) add({ status: 'current', ...n })
+
+// 2) live leaves from src/
+for (const spec of topo.leafSources) {
+  if (!byId.has(spec.parent)) fail('leafSource parent unknown: ' + spec.parent)
+  const files = walk(spec)
+  if (files.length === 0) fail(`leafSource matched 0 files (phantom node?): ${spec.dir}`)
+  for (const f of files) {
+    add({
+      id: `${spec.parent}__${f.replace(/[^a-z0-9]+/gi, '_')}`,
+      level: 'leaf', parent: spec.parent, kind: 'leaf',
+      name: f.replace(/\.[a-z0-9]+$/i, ''), status: 'current',
+      evidence: [{ type: 'path', ref: `${spec.dir}/${f}` }],
+    })
+  }
+  // attach glob count to the parent (drift anchor)
+  const parent = byId.get(spec.parent)
+  parent.evidence = [...(parent.evidence || []), { type: 'glob', ref: spec.dir, count: files.length }]
+}
+
+// 3) curated leaves (mixed-location, with optional computed counts)
+for (const l of topo.curatedLeaves || []) {
+  if (!byId.has(l.parent)) fail('curatedLeaf parent unknown: ' + l.parent)
+  if (l.evidence && !existsSync(rp(l.evidence))) fail('curatedLeaf evidence missing: ' + l.evidence)
+  let tech = l.tech
+  if (l.countFrom) { const c = countMatches(l.countFrom.file, l.countFrom.pattern, l.countFrom.unique); tech = `${c} ${l.tech || ''}`.trim() }
+  add({ id: l.id, level: 'leaf', parent: l.parent, kind: 'leaf', name: l.name, tech, status: 'current',
+        evidence: l.evidence ? [{ type: 'path', ref: l.evidence }] : [] })
+}
+
+// 4) planned leaves — verify their premise still holds in the docs (non-vacuous)
+for (const p of topo.plannedLeaves || []) {
+  if (!byId.has(p.parent)) fail('plannedLeaf parent unknown: ' + p.parent)
+  if (p.sourceRef && !existsSync(rp(p.sourceRef))) fail('plannedLeaf sourceRef missing: ' + p.sourceRef)
+  if (p.sourceMustContain) {
+    const txt = readFileSync(rp(p.sourceRef), 'utf-8')
+    if (!txt.includes(p.sourceMustContain)) fail(`planned "${p.name}" premise changed — "${p.sourceMustContain}" not in ${p.sourceRef}. Update the roadmap/model.`)
+  }
+  add({ id: p.id, level: 'leaf', parent: p.parent, kind: 'leaf', name: p.name, tech: p.tech, status: 'planned',
+        status2: p.status2, completion: p.completion, current: p.current, target: p.target, verify: p.verify,
+        evidence: [{ type: 'doc', ref: p.sourceRef }] })
+}
+
+// enrich: fill hologram defaults (category, 5-status, completion, current/target) where absent
+for (const n of nodes) {
+  const par = n.parent ? byId.get(n.parent) : null
+  if (!n.category) n.category = n.kind === 'leaf' ? (par && par.category) || 'leaf' : n.kind
+  if (!n.status2) n.status2 = n.status === 'planned' ? 'planned' : 'done'
+  if (n.completion == null) n.completion = n.status === 'planned' ? 0 : 100
+  if (!n.current) { const pth = (n.evidence || []).find((e) => e.type === 'path'); n.current = pth ? `Exists: ${pth.ref}` : (n.tech || '') }
+  if (n.target == null) n.target = ''
+}
+
+// func: plain-language "what it does" (non-dev). Leaves from the descriptions map; else the description.
+const D = topo.descriptions || {}
+for (const n of nodes) {
+  const key = n.parent ? `${n.parent}/${String(n.name).replace(/\.\w+$/, '').replace(/ .*/, '')}` : null
+  n.func = (key && D[key]) || n.description || (n.kind === 'leaf' ? `Component of module ${(byId.get(n.parent) || {}).name || n.parent}.` : '')
+}
+
+// 4b) derive container↔container edges from REAL code references (deterministic, additive).
+// Auto-walk gives structure (containers+leaves) but not relationships. Here we recover them from the
+// code itself: for each container, count how many of ANOTHER container's exposed leaf names (class/
+// module names) appear as whole-word references in this container's files. count>0 ⇒ a real edge.
+// Language-agnostic (matches symbol names, not import syntax). Additive: never removes curated edges.
+if (!process.argv.includes('--no-auto-edges')) {
+  const STOP = new Set(['index', 'main', 'app', 'utils', 'util', 'types', 'model', 'base', 'core', 'const', 'style', 'theme'])
+  const srcs = (topo.leafSources || []).filter((s) => byId.has(s.parent))
+  const exposes = new Map(), text = new Map()
+  for (const s of srcs) {
+    exposes.set(s.parent, [...new Set(nodes.filter((n) => n.parent === s.parent && n.kind === 'leaf')
+      .map((n) => String(n.name)).filter((nm) => nm.length >= 5 && !STOP.has(nm.toLowerCase())))])
+    let t = ''; const dir = rp(s.dir)
+    try { for (const f of readdirSync(dir)) { const fp = join(dir, f); if (statSync(fp).isFile()) t += '\n' + readFileSync(fp, 'utf-8') } } catch {}
+    text.set(s.parent, t)
+  }
+  const have = new Set((topo.edges || []).flatMap((e) => [e.from + '|' + e.to, e.to + '|' + e.from]))
+  const derived = []
+  for (const from of exposes.keys()) {
+    const t = text.get(from) || ''
+    for (const to of exposes.keys()) {
+      if (to === from || have.has(from + '|' + to)) continue
+      let c = 0
+      for (const nm of exposes.get(to)) { if (new RegExp('\\b' + nm.replace(/[^\w]/g, '') + '\\b').test(t)) c++ }
+      if (c > 0) { derived.push({ from, to, label: c + '×', kind: 'import', estatus: 'active' }); have.add(from + '|' + to); have.add(to + '|' + from) }
+    }
+  }
+  topo.edges = [...(topo.edges || []), ...derived]
+  if (derived.length) console.log(`[gen-c4] auto-edges: +${derived.length} container edge(s) derived from code references`)
+}
+
+// 5) validate edges resolve
+for (const e of topo.edges) { if (!byId.has(e.from)) fail('edge from unknown: ' + e.from); if (!byId.has(e.to)) fail('edge to unknown: ' + e.to) }
+
+// 6) provenance
+let commit = 'unknown', branch = 'unknown'
+const gitOpts = { cwd: REPO, stdio: ['ignore', 'pipe', 'ignore'] }
+try { commit = execSync('git rev-parse HEAD', gitOpts).toString().trim() } catch {}
+try { branch = execSync('git rev-parse --abbrev-ref HEAD', gitOpts).toString().trim() } catch {}
+
+const model = {
+  schemaVersion: SCHEMA_VERSION,
+  generatedAt: new Date().toISOString(),
+  source: { repo: topo.meta.repo, commit, branch, docPath: topo.docPath, generator: 'gen-c4-model@' + SCHEMA_VERSION },
+  meta: { ...topo.meta, verifiedAt: new Date().toISOString(), verifyMethod: 'code+topology (gh re-verify optional)' },
+  levels: topo.levels,
+  nodes,
+  edges: topo.edges.map((e) => ({ status: 'current', estatus: e.estatus || 'active', ...e })),
+}
+// --from-docs (optional): derive the TARGET layer from documentation (PRD→docs), not code.
+// Surfaces project-status milestones + ADR statuses so "stato finito" is doc-driven. Best-effort.
+if (process.argv.includes('--from-docs')) {
+  try {
+    const ps = existsSync(rp('docs/project-status.md')) ? readFileSync(rp('docs/project-status.md'), 'utf-8') : ''
+    const planned = [...ps.matchAll(/\|\s*(M\d+)\s*\|\s*PLANNED\s*\|[^|]*\|\s*([^|]+?)\s*\|/g)].map((m) => `${m[1]}: ${m[2].trim()}`)
+    let accepted = 0, adrs = 0
+    const adrDir = rp('docs/adr')
+    if (existsSync(adrDir)) for (const f of readdirSync(adrDir)) if (/\.md$/.test(f) && !/template/i.test(f)) { adrs++; if (/Status[:*\s]+Accepted/i.test(readFileSync(join(adrDir, f), 'utf-8'))) accepted++ }
+    model.meta.docTargets = planned
+    model.meta.adr = { total: adrs, accepted }
+    model.meta.verifyMethod = 'from-docs (project-status milestones + ADR statuses)'
+    console.log(`[gen-c4] --from-docs: ${planned.length} planned milestone(s), ${accepted}/${adrs} ADR accepted`)
+  } catch (e) { model.meta.verifyError = 'from-docs: ' + String((e && e.message) || e) }
+}
+writeFileSync(OUT, JSON.stringify(model, null, 2) + '\n')
+const counts = { total: nodes.length, leaves: nodes.filter((n) => n.kind === 'leaf').length, planned: nodes.filter((n) => n.status === 'planned').length }
+console.log(`[gen-c4] wrote ${OUT}`)
+console.log(`[gen-c4] nodes=${counts.total} leaves=${counts.leaves} planned=${counts.planned} edges=${model.edges.length} commit=${commit.slice(0,8)}`)

package/lib/init.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// forma init — seed a c4-topology.json from the repo's real source directories.
+// BEST-EFFORT: gives a valid, non-empty starting point (no cold-start). The human/agent then
+// curates groupings, context externals, and plain-language descriptions. Never overwrites an
+// existing topology unless --force.
+import { readdirSync, statSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, relative, basename } from 'node:path'
+
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
+const REPO = arg('--repo', process.cwd())
+const OUT = arg('--out', join(REPO, 'docs/architecture/c4-topology.json'))
+const FORCE = process.argv.includes('--force')
+const IGNORE = new Set(['node_modules', '.git', 'dist', 'build', 'target', 'out', 'vendor', 'coverage', '.next', '.gradle', 'bin', 'obj'])
+const EXT = { ts: 'TypeScript', tsx: 'TypeScript', js: 'JavaScript', jsx: 'JavaScript', mjs: 'JavaScript', cjs: 'JavaScript', mts: 'TypeScript', cts: 'TypeScript', py: 'Python', go: 'Go', java: 'Java', rs: 'Rust', rb: 'Ruby', php: 'PHP', cs: 'C#', kt: 'Kotlin', swift: 'Swift', cpp: 'C++', c: 'C' }
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '') || 'x'
+
+if (existsSync(OUT) && !FORCE) { console.error(`[forma init] ${relative(REPO, OUT)} already exists — use --force to reseed.`); process.exit(1) }
+
+// 1) detect dominant language by extension count (skipping ignored dirs)
+const counts = {}
+;(function walk(dir, depth) {
+  if (depth > 12) return
+  let ents; try { ents = readdirSync(dir) } catch { return }
+  for (const e of ents) {
+    if (IGNORE.has(e) || e.startsWith('.')) continue
+    const p = join(dir, e)
+    let st; try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) walk(p, depth + 1)
+    else { const m = e.match(/\.([a-z0-9]+)$/i); if (m && EXT[m[1].toLowerCase()]) counts[m[1].toLowerCase()] = (counts[m[1].toLowerCase()] || 0) + 1 }
+  }
+})(REPO, 0)
+const ext = Object.entries(counts).sort((a, b) => b[1] - a[1])[0]
+if (!ext) { console.error('[forma init] no recognised source files found under ' + REPO); process.exit(1) }
+const lang = EXT[ext[0]]
+const matchRe = `\\.${ext[0]}$`
+
+// 2) find the source root
+function javaBase() {
+  let d = join(REPO, 'src/main/java')
+  if (!existsSync(d)) return null
+  // descend while there is exactly one subdir (the package chain) until it branches
+  for (;;) {
+    const subs = readdirSync(d).filter((x) => { try { return statSync(join(d, x)).isDirectory() } catch { return false } })
+    const files = readdirSync(d).some((x) => new RegExp(matchRe).test(x))
+    if (subs.length === 1 && !files) d = join(d, subs[0]); else break
+  }
+  return d
+}
+const root = ext[0] === 'java' ? (javaBase() || REPO) : (existsSync(join(REPO, 'src')) ? join(REPO, 'src') : REPO)
+
+// 3) build nodes + leafSources: one container per immediate subdir that holds source files directly
+const sysId = slug(basename(REPO))
+const nodes = [{ id: sysId, level: 'context', kind: 'system', name: basename(REPO), tech: lang, description: `${basename(REPO)} — drill for containers.` }]
+const leafSources = []
+const hasSrc = (dir) => { try { return readdirSync(dir).some((f) => { const p = join(dir, f); return statSync(p).isFile() && new RegExp(matchRe).test(f) }) } catch { return false } }
+
+// Recurse to the SHALLOWEST dirs that directly contain source files → each is a container.
+// (A dir with direct sources is a container; a dir with none is descended into. Works for nested
+// layouts like src/app/routes/*.ts or Python packages, not just one level.)
+const seen = new Set()
+;(function findContainers(dir, depth) {
+  if (depth > 10) return
+  let ents; try { ents = readdirSync(dir) } catch { return }
+  for (const e of ents.filter((x) => !IGNORE.has(x) && !x.startsWith('.')).sort()) {
+    const p = join(dir, e)
+    let st; try { st = statSync(p) } catch { continue }
+    if (!st.isDirectory()) continue
+    if (hasSrc(p)) {
+      const rel = relative(root, p) || e
+      let id = slug(rel.replace(/[\\/]+/g, '_'))
+      if (seen.has(id)) id = slug(id + '_' + leafSources.length)
+      seen.add(id)
+      nodes.push({ id, level: 'container', kind: 'container', parent: sysId, name: e, tech: lang })
+      leafSources.push({ parent: id, dir: relative(REPO, p), match: matchRe })
+    } else findContainers(p, depth + 1)
+  }
+})(root, 0)
+// loose files directly in root → an entry container
+if (hasSrc(root)) { nodes.push({ id: 'app', level: 'container', kind: 'container', parent: sysId, name: 'app', tech: lang, description: 'Entry point / loose top-level sources.' }); leafSources.push({ parent: 'app', dir: relative(REPO, root) || '.', match: matchRe }) }
+
+if (leafSources.length === 0) { console.error('[forma init] found a source root but no directory with source files directly in it. Add leafSources manually.'); process.exit(1) }
+
+const topo = {
+  meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init' },
+  docPath: 'docs/architecture/ARCHITECTURE.md',
+  levels: ['context', 'container', 'component', 'leaf'],
+  nodes,
+  leafSources,
+  edges: [],
+  descriptions: {},
+}
+// ensure output dir exists
+mkdirSync(join(OUT, '..'), { recursive: true })
+writeFileSync(OUT, JSON.stringify(topo, null, 2) + '\n')
+console.log(`[forma init] wrote ${relative(REPO, OUT)} — ${lang}, ${leafSources.length} container(s) seeded from ${relative(REPO, root) || '.'}/`)
+console.log('[forma init] NEXT: curate names/descriptions + add context externals + run `forma gen`.')

package/lib/schema/c4-model.schema.json

@@ -0,0 +1,274 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/LucaDominici/forma/blob/main/lib/schema/c4-model.schema.json",
+  "title": "C4 model \u2014 stack-agnostic architecture graph",
+  "description": "Reusable contract for the C4 live dashboard. A generator conforms iff its output validates; the viewer renders anything that validates. Stack-specific facts live only in tech/meta.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "source",
+    "levels",
+    "nodes",
+    "edges"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semver. The viewer renders any JSON with the same MAJOR; MINOR/PATCH are additive-only."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "source": {
+      "type": "object",
+      "required": [
+        "repo",
+        "commit",
+        "generator"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "repo": {
+          "type": "string"
+        },
+        "commit": {
+          "type": "string"
+        },
+        "branch": {
+          "type": "string"
+        },
+        "docPath": {
+          "type": "string",
+          "description": "The arc42 architecture doc this model derives from."
+        },
+        "generator": {
+          "type": "string"
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "description": "Repo-level escape hatch (archetype, stack, overlays, version). Never required by the viewer.",
+      "additionalProperties": true
+    },
+    "levels": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "Ordered C4 levels present (e.g. context, container, component, code)."
+    },
+    "nodes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "level",
+          "name",
+          "kind"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable, unique, natural-key-like."
+          },
+          "level": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "person",
+              "system",
+              "external",
+              "container",
+              "component",
+              "store",
+              "boundary",
+              "leaf"
+            ]
+          },
+          "parent": {
+            "type": "string",
+            "description": "Containment / boundary node id."
+          },
+          "drill": {
+            "type": "string",
+            "description": "Level id to open when drilling into this node."
+          },
+          "tech": {
+            "type": "string",
+            "description": "Free text; NOT enumerated."
+          },
+          "description": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "current",
+              "partial",
+              "planned",
+              "deprecated",
+              "unknown"
+            ],
+            "default": "current"
+          },
+          "link": {
+            "type": "string",
+            "format": "uri"
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "type",
+                "ref"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "Open vocabulary: path|doc|adr|url|test|glob."
+                },
+                "ref": {
+                  "type": "string"
+                },
+                "count": {
+                  "type": "integer",
+                  "description": "For glob evidence: number of files matched (drift anchor)."
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "category": {
+            "type": "string",
+            "description": "Sub-type tag shown top-left (surface/core/gen/out/gate/...)."
+          },
+          "status2": {
+            "type": "string",
+            "enum": [
+              "done",
+              "in-progress",
+              "next",
+              "planned",
+              "problem"
+            ],
+            "description": "Hologram completion status (colour)."
+          },
+          "completion": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 100
+          },
+          "statusWord": {
+            "type": "string",
+            "description": "Optional badge word overriding the %."
+          },
+          "current": {
+            "type": "string",
+            "description": "STATO ATTUALE (fatti) \u2014 what is true now."
+          },
+          "target": {
+            "type": "string",
+            "description": "STATO FINITO (progetto) \u2014 where it must land."
+          },
+          "issues": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "verify": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Verification source (gh issue/PR + state + ts)."
+          },
+          "func": {
+            "type": "string",
+            "description": "Plain-language 'what it does' for non-developers."
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "from",
+          "to"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "from": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "level": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string",
+            "description": "import | runtime | ci \u2014 provenance of the relationship."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "current",
+              "planned",
+              "deprecated"
+            ]
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "type",
+                "ref"
+              ],
+              "properties": {
+                "type": {
+                  "type": "string"
+                },
+                "ref": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "estatus": {
+            "type": "string",
+            "enum": [
+              "active",
+              "to-build"
+            ],
+            "description": "active = animated flow; to-build = dashed."
+          }
+        }
+      }
+    }
+  }
+}

package/lib/serve.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// forma serve — tiny static server for the interactive viewer + model. Local dev only.
+import { createServer } from 'node:http'
+import { readFileSync, existsSync } from 'node:fs'
+import { join, extname, resolve, dirname, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
+const REPO = arg('--repo', process.cwd())
+const PORT = parseInt(arg('--port', '4173'), 10)
+const HERE = dirname(fileURLToPath(import.meta.url))
+const dir = resolve(REPO, 'docs/architecture')
+const viewerFallback = join(HERE, 'viewer', 'c4-hologram.html')
+const TYPES = { '.html': 'text/html', '.json': 'application/json', '.js': 'text/javascript', '.css': 'text/css', '.svg': 'image/svg+xml' }
+
+createServer((req, res) => {
+  let p = decodeURIComponent((req.url || '/').split('?')[0])
+  if (p === '/' || p === '') p = '/c4-viewer.html'
+  // resolve within dir and refuse anything that escapes it (no path traversal)
+  const file = resolve(dir, '.' + p)
+  if (file !== dir && !file.startsWith(dir + sep)) { res.writeHead(403); return res.end('forbidden') }
+  let target = file
+  if (p === '/c4-viewer.html' && !existsSync(target)) target = viewerFallback
+  if (!existsSync(target)) { res.writeHead(404); return res.end('not found: ' + p) }
+  res.writeHead(200, { 'Content-Type': TYPES[extname(target)] || 'application/octet-stream' })
+  res.end(readFileSync(target))
+}).listen(PORT, () => console.log(`[forma] serving ${dir} → http://localhost:${PORT}/  (model: /c4-model.json)`))