@shortlink-org/portolan 0.2.4 → 0.4.0

package/scripts/README.md

@@ -1,8 +1,8 @@
 # Host
 
 The side of portolan that runs. `npm run gen` reads the manifest, runs every
-plugin it names, stamps and writes what comes back, merges the sources into
-one estate and validates the union. Nothing here draws anything.
+plugin it names, writes what comes back, merges the sources into one estate
+and validates the union. Nothing here draws anything.
 
 ## What it does
 
@@ -10,21 +10,25 @@ one estate and validates the union. Nothing here draws anything.
   the schema `npm run schema` composes out of what every declared plugin says
   it can be told.
 - Runs three phases in order, extract, verify, generate, and hands each
-  plugin one JSON message: the input root, output directory and stamp for an
+  plugin one JSON message: the input root and output directory for an
   extractor, the merged catalog for a verifier or a generator, the step's
   options unread. The output path lets a fragment point at a companion file
   returned in the same response without letting the plugin write it itself.
-- Stamps a fragment from the last commit that touched its input, never from a
-  clock, so a committed fragment changes exactly when its subject does
-  (portolan.0002).
+- Writes no provenance into a fragment. When a source last changed, and in
+  which commit, is read from the history of the checkout wherever the catalog
+  is read - here, by the LikeC4 generator, by the architecture diff and by
+  the site as Vite builds it - so a fragment is content and nothing else, and
+  regenerating from the same sources changes no byte (portolan.0010).
 - Writes the files a plugin named, refuses a name that climbs out of the
   step's output directory, keeps a listing per step of what it wrote, and
   deletes what stopped being generated (portolan.0001).
 - Merges every source the manifest's globs find and validates the union with
   the code the site runs: `src/merge.ts`, `src/catalog.ts`, `src/enrich.ts`.
 - In `--check` mode writes nothing and fails on the first file that differs
-  from disk. Either way it leaves `.portolan/build-report.json` for the
-  Settings page.
+  from disk, saying where the file first differs and what changed among the
+  step's inputs since its output was last committed - the history is the
+  record of the last generation, so nothing else has to be. Either way it
+  leaves `.portolan/build-report.json` for the Settings page.
 
 ## What it does not do
 
@@ -33,7 +37,9 @@ one estate and validates the union. Nothing here draws anything.
 - Read a plugin's stdout for anything but the one message, or its stderr for
   anything but notes; a warning is kept beside the step in the build report.
 - Draw the C4 model: `gen-likec4.mjs` writes `likec4/` from the same merged
-  catalog, and the site draws.
+  catalog, and the site draws. It runs as the last step of `gen.mjs` -
+  written, or in check mode held to the catalog like every generated page -
+  and on its own before `dev`.
 
 ## Files
 
@@ -47,7 +53,9 @@ one estate and validates the union. Nothing here draws anything.
   that report put on the pull request as one comment kept current;
   `forge-release.mjs`, the same report as one section of a release's notes;
   `forge.mjs`, what those two share - which forge the CI is, and how to talk
-  to it; `vendor-lock.mjs`,
-  the commit a fetched copy is of; `site-docs.mjs`, generated documentation
-  put into the built site; `local-api.mjs`, what the dev server answers the
-  site with.
+  to it; `history.mjs`, what the checkout's history says about every file,
+  for a plugin that asks and for the provenance of every source;
+  `provenance.mjs`, that provenance handed to the site as one virtual module;
+  `output-diff.mjs`, where a generated file first differs from what the
+  generator produces; `site-docs.mjs`, generated documentation put into the
+  built site; `local-api.mjs`, what the dev server answers the site with.

package/scripts/catalog-sources.mjs

@@ -14,6 +14,7 @@ import { validateCatalog } from "../src/catalog.ts";
 import { filterCatalogForProfile } from "../src/catalog-profile.ts";
 import { enrichCatalog } from "../src/enrich.ts";
 import { mergeCatalogs } from "../src/merge.ts";
+import { stampsFor } from "./history.mjs";
 import { readManifest } from "./manifest.mjs";
 
 /**
@@ -48,10 +49,15 @@ export async function loadCatalog(manifestPath = "portolan.json", { exclude = []
     );
   }
 
+  // A source is dated by the history, not by itself (portolan.0010): the
+  // commit that last changed the file, and its date, read here and never
+  // written into the file.
+  const stamps = stampsFor(process.cwd(), paths);
   const merged = mergeCatalogs(
     paths.map((path) => ({
       path,
       catalog: JSON.parse(readFileSync(path, "utf8")),
+      stamp: stamps.get(path),
     })),
   );
   if (paths.length === 0) {

package/scripts/delivery-presets.mjs

@@ -23,7 +23,10 @@ const GITLAB_START = "# >>> Portolan delivery preset >>>";
 const GITLAB_END = "# <<< Portolan delivery preset <<<";
 const PROVIDERS = new Set(["github", "gitlab"]);
 const FEATURE_IDS = ["check", "diff", "sarif", "pages"];
-const DEFAULT_FEATURES = ["check", "pages"];
+const DEFAULT_FEATURES = {
+  github: ["check", "pages"],
+  gitlab: ["pages"],
+};
 const FEATURE_DETAILS = {
   check: {
     label: "Architecture check",
@@ -76,11 +79,23 @@ function repositoryName(remote, workspace) {
   return clean.split(/[/:]/).filter(Boolean).pop() || relative(dirname(workspace), workspace) || "repository";
 }
 
+// One ref listing answers three questions (where origin/HEAD points, whether
+// main or master exists) instead of one git process per question: a preview
+// spawns git while the test suite and the site build are already competing
+// for the machine, and every spawn costs seconds there.
 function defaultBranch(workspace) {
-  const remoteHead = git(workspace, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
-  if (remoteHead.startsWith("origin/")) return remoteHead.slice("origin/".length);
+  const refs = new Map();
+  for (const line of git(workspace, [
+    "for-each-ref", "--format=%(refname)%09%(symref)",
+    "refs/remotes/origin/HEAD", "refs/heads/main", "refs/heads/master",
+  ]).split("\n")) {
+    const [name, symref = ""] = line.split("\t");
+    if (name) refs.set(name, symref);
+  }
+  const remoteHead = refs.get("refs/remotes/origin/HEAD") ?? "";
+  if (remoteHead.startsWith("refs/remotes/origin/")) return remoteHead.slice("refs/remotes/origin/".length);
   for (const candidate of ["main", "master"]) {
-    if (git(workspace, ["rev-parse", "--verify", `refs/heads/${candidate}`])) return candidate;
+    if (refs.has(`refs/heads/${candidate}`)) return candidate;
   }
   return git(workspace, ["branch", "--show-current"]) || "main";
 }
@@ -225,7 +240,9 @@ ${upload}`;
 
 function gitlabCheck() {
   return `"portolan:check":
-  stage: .pre
+  stage: test
+  tags:
+    - runner-type:docker
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
     entrypoint: [""]
@@ -242,7 +259,9 @@ function gitlabCheck() {
 function gitlabDiff({ pages }) {
   const site = pages ? ' --site "$CI_PAGES_URL"' : "";
   return `"portolan:review":
-  stage: .pre
+  stage: test
+  tags:
+    - runner-type:docker
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
     entrypoint: [""]
@@ -259,8 +278,10 @@ function gitlabDiff({ pages }) {
 }
 
 function gitlabPages() {
-  return `"portolan:pages":
-  stage: .post
+  return `pages:
+  stage: deploy
+  tags:
+    - runner-type:docker
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
     entrypoint: [""]
@@ -268,9 +289,10 @@ function gitlabPages() {
     GIT_DEPTH: "0"
   script:
     - BASE_PATH="$(node -p 'new URL(process.env.CI_PAGES_URL).pathname.replace(/\\/?$/, "/") || "/"')"
-    - portolan build --output dist --base "$BASE_PATH"
-  pages:
-    publish: dist
+    - portolan build --output public --base "$BASE_PATH"
+  artifacts:
+    paths:
+      - public
   rules:
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
 `;
@@ -299,15 +321,36 @@ function mergeGitlab(existing, features) {
       .replace(/^\n+|\n+$/g, "");
     return { content: content ? `${content}\n` : "" };
   }
-  if (/^[ \t]*["']?portolan:(?:check|review|pages)["']?\s*:/m.test(existing)) {
+  if (/^(?:["']?portolan:(?:check|review|pages)["']?|["']?pages["']?)\s*:/m.test(existing)) {
     return { conflict: "This pipeline already declares a Portolan job outside the managed region." };
   }
   const block = gitlabBlock(features);
   return { content: block ? `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}` : existing };
 }
 
+// A file that is entirely new or entirely gone needs no diff algorithm: every
+// line is added or removed. Writing that hunk here saves a git process per
+// file, and a GitHub preset is mostly such files.
+function wholeFileDiff(path, content, sign) {
+  const body = content.endsWith("\n") ? content.slice(0, -1) : content;
+  const lines = body.split("\n");
+  const count = lines.length === 1 ? "1" : `1,${lines.length}`;
+  const range = sign === "+" ? `-0,0 +${count}` : `-${count} +0,0`;
+  return [
+    `diff --git a/${path} b/${path}`,
+    `--- a/${path}`,
+    `+++ b/${path}`,
+    `@@ ${range} @@`,
+    ...lines.map((line) => `${sign}${line}`),
+    ...(content.endsWith("\n") ? [] : ["\"]),
+    "",
+  ].join("\n");
+}
+
 function textDiff(path, before, after) {
   if (before === after) return "";
+  if (before === "") return wholeFileDiff(path, after, "+");
+  if (after === "") return wholeFileDiff(path, before, "-");
   const holder = mkdtempSync(join(tmpdir(), "portolan-preset-diff-"));
   const left = join(holder, "before");
   const right = join(holder, "after");
@@ -421,14 +464,14 @@ function installedFeatures(workspace, provider) {
   );
   if (/^[ \t]*["']?portolan:check["']?\s*:/m.test(managed)) selected.add("check");
   if (/^[ \t]*["']?portolan:review["']?\s*:/m.test(managed)) selected.add("diff");
-  if (/^[ \t]*["']?portolan:pages["']?\s*:/m.test(managed)) selected.add("pages");
+  if (/^(?:["']?portolan:pages["']?|["']?pages["']?)\s*:/m.test(managed)) selected.add("pages");
   return selected;
 }
 
 function selectedFeatures(workspace, request, provider) {
   const installed = request.features == null ? installedFeatures(workspace, provider) : null;
   const raw = request.features == null
-    ? installed.size > 0 ? [...installed] : DEFAULT_FEATURES
+    ? installed.size > 0 ? [...installed] : DEFAULT_FEATURES[provider]
     : Array.isArray(request.features)
       ? request.features
       : String(request.features).split(",").filter(Boolean);

package/scripts/diff.mjs

@@ -157,8 +157,12 @@ function catalogAt(ref) {
     throw new Error(ref + " holds no catalog sources matching " + JSON.stringify(manifest.sources));
   }
 
+  // The base is one commit, and a commit is its own provenance: every source
+  // there is dated by it (portolan.0010), whatever an older fragment says.
+  const [commit = "", generatedAt = ""] = git(["log", "-1", "--format=%h %cI", ref]).split(" ");
+  const stamp = { commit, generatedAt };
   const merged = mergeCatalogs(
-    paths.map((path) => ({ path, catalog: JSON.parse(git(["show", ref + ":" + path])) })),
+    paths.map((path) => ({ path, catalog: JSON.parse(git(["show", ref + ":" + path])), stamp })),
   );
 
   // Enriched before it is compared, exactly as the app and the generators see

package/scripts/django-aggregates.test.mjs

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { djangoAggregateProposals, saveDjangoAggregates } from "./local-api.mjs";
+
+const roots = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), "portolan-aggregates-")); roots.push(root);
+  const manifest = { sources: ["data/*.json"], extract: ["one", "two"].map((name) => ({ plugin: "django-domain", in: name, out: `data/${name}`, options: { context: name, service: name, aggregates: { existing: "Existing" }, apps: ["billing.records"] } })) };
+  const text = JSON.stringify(manifest);
+  writeFileSync(join(root, "portolan.json"), text);
+  const message = `billing/records: no model called Records, and 2 models to choose from: name the root in the aggregates option; aggregate candidates: ${JSON.stringify({ app: "billing.records", models: [{ name: "Entry", path: "billing/records/models.py", line: 1 }, { name: "Audit", path: "billing/records/models.py", line: 10 }] })}`;
+  const report = { status: "ok", manifestSha256: createHash("sha256").update(text).digest("hex"), steps: manifest.extract.map((step) => ({ phase: "extract", plugin: step.plugin, input: step.in, output: step.out, warnings: [message] })) };
+  mkdirSync(join(root, ".portolan")); writeFileSync(join(root, ".portolan/build-report.json"), JSON.stringify(report));
+  return { root, manifest, report };
+}
+
+describe("saving Django aggregate roots", () => {
+  it("targets the precise step and dotted app, preserving unrelated options", () => {
+    const { root, manifest } = fixture();
+    const proposals = djangoAggregateProposals(root);
+    expect(proposals.stale).toBe(false);
+    expect(proposals.proposals).toHaveLength(2);
+    saveDjangoAggregates(root, { revision: proposals.revision, selections: [{ id: "1:billing.records", model: "Entry" }] });
+    const saved = JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"));
+    expect(saved.extract[0]).toEqual(manifest.extract[0]);
+    expect(saved.extract[1].options).toEqual({ ...manifest.extract[1].options, aggregates: { existing: "Existing", "billing.records": "Entry" } });
+    expect(djangoAggregateProposals(root).stale).toBe(true);
+  });
+
+  it("saves a batch atomically and rejects forged, duplicate, or stale choices", () => {
+    const { root } = fixture();
+    const { revision } = djangoAggregateProposals(root);
+    const original = readFileSync(join(root, "portolan.json"), "utf8");
+    for (const selections of [[], [{ id: "0:billing.records", model: "Proxy" }], [{ id: "no-such-step", model: "Entry" }], [{ id: "0:billing.records", model: "Entry" }, { id: "1:billing.records", model: "Invalid" }], [{ id: "0:billing.records", model: "Entry" }, { id: "0:billing.records", model: "Audit" }]]) {
+      expect(() => saveDjangoAggregates(root, { revision, selections })).toThrow();
+      expect(readFileSync(join(root, "portolan.json"), "utf8")).toBe(original);
+    }
+    const selections = [{ id: "0:billing.records", model: "Entry" }, { id: "1:billing.records", model: "Audit" }];
+    expect(() => saveDjangoAggregates(root, { revision: "old", selections })).toThrow(/changed/);
+    expect(saveDjangoAggregates(root, { revision, selections })).toEqual({ saved: 2 });
+    expect(() => saveDjangoAggregates(root, { revision, selections })).toThrow(/changed/);
+  });
+
+  it("requires fresh report evidence and refuses ambiguous step bindings", () => {
+    const { root, manifest, report } = fixture();
+    manifest.extract.push(manifest.extract[0]);
+    writeFileSync(join(root, "portolan.json"), JSON.stringify(manifest));
+    expect(djangoAggregateProposals(root).proposals.map((p) => p.id)).toEqual(["1:billing.records"]);
+    expect(djangoAggregateProposals(root).stale).toBe(true);
+    report.steps = [];
+    writeFileSync(join(root, ".portolan/build-report.json"), JSON.stringify(report));
+    expect(djangoAggregateProposals(root).proposals).toEqual([]);
+  });
+});

package/scripts/gen-likec4.mjs

@@ -7,16 +7,24 @@
 //
 //   node scripts/gen-likec4.mjs
 
-import { writeFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, mkdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { loadCatalog } from "./catalog-sources.mjs";
 import reserved from "../src/likec4/reserved.json" with { type: "json" };
 import { catalogProfiles } from "../src/catalog-profile.ts";
+import { allDeployments, deploys, environmentOf } from "../src/catalog-model.ts";
 
 // Every source, not one file: a service that publishes its own facts gets a
 // C4 view like any other, and generating from a single file would leave it out
 // of the pictures while the rest of the app knows about it.
-const { catalog, manifest } = await loadCatalog();
+//
+// The sources come back as files rather than being written here, so that
+// `gen` can settle them the way it settles every generated page - written,
+// or in check mode compared and reported as drift - and `likec4:gen` can
+// still write them on its own before the dev server starts.
+export async function likec4Sources({ catalog, manifest }) {
 const profiles = catalogProfiles(manifest);
 
 // --- ids (mirrors src/likec4/ids.ts; kept in step by src/likec4/ids.test.ts) ---
@@ -36,6 +44,8 @@ const flowCrossViewId = (flow) => `${flowViewId(flow)}_cross`;
 const contextViewId = (c) => `ctx_${safeId(c.id)}`;
 const serviceViewId = (s) => `svc_${safeId(s.id)}`;
 const serviceInsideViewId = (s) => `${serviceViewId(s)}_inside`;
+const deploymentViewId = (environment) => `deploy_${safeId(environment)}`;
+const serviceDeployViewId = (s) => `deploy_svc_${safeId(s.id)}`;
 const LANDSCAPE_VIEW = "landscape";
 const CONTAINERS_VIEW = "containers";
 const profileLandscapeViewId = (profile) =>
@@ -248,6 +258,18 @@ spec.push("  element unknown {");
 spec.push("    style { shape rectangle  color unresolved  border dashed }");
 spec.push("  }");
 spec.push("");
+// Where a service runs (portolan.0012): three nested places, drawn as
+// frames around the instances they hold, from the deployer's snapshot.
+spec.push("  deploymentNode environment {");
+spec.push("    style { shape rectangle  opacity 5%  border dashed }");
+spec.push("  }");
+spec.push("  deploymentNode cluster {");
+spec.push("    style { shape rectangle  opacity 10%  border dashed  color muted }");
+spec.push("  }");
+spec.push("  deploymentNode namespace {");
+spec.push("    style { shape rectangle  opacity 15%  color muted }");
+spec.push("  }");
+spec.push("");
 for (const kind of RELATION_KINDS) spec.push(`  relationship ${kind}`);
 spec.push("}");
 
@@ -278,7 +300,7 @@ for (const context of catalog.contexts) {
     model.push(`      style { color ${contextColorName(context.id)} }`);
     for (const aggregate of service.aggregates) {
       model.push(
-        `      ${safeId(aggregate.slug)} = aggregate ${q(aggregate.name)} {`,
+        `      ${safeId(aggregate.slug)} = aggregate ${q(aggregate.kind === "model-group" ? `${aggregate.name} (model group)` : aggregate.name)} {`,
       );
       for (const event of aggregate.events) {
         const latest = event.versions[event.versions.length - 1];
@@ -1050,20 +1072,131 @@ for (const flow of catalog.flows) {
   views.push("  }");
   views.push("");
 }
+// ---------------------------------------------------------------------------
+// deployment: where the services run (portolan.0012)
+// ---------------------------------------------------------------------------
+// One tree per environment, the cluster and the namespace as frames inside
+// it, and an instance of the service in the namespace it stands in. The
+// relations are the model's own: LikeC4 draws between two instances what the
+// model declares between their elements, so an environment's picture shows
+// the calls both ends of which are deployed there, and nothing a reader
+// would have to fold by hand. One view per environment, and one per service
+// that runs somewhere: its instances with the frames around them.
+const deployment = [];
+const deployTree = new Map(); // environment -> cluster -> namespace -> Map(service id -> {service, deployment})
+const placesOfService = new Map(); // service id -> [fqn of instance]
+const framesOfEnvironment = new Map(); // environment -> Set(fqn of every node under it)
+for (const placed of allDeployments(catalog)) {
+  for (const service of allServices) {
+    if (!deploys(placed, service)) continue;
+    const env = environmentOf(placed);
+    const clusters = deployTree.get(env) ?? new Map();
+    deployTree.set(env, clusters);
+    const namespaces = clusters.get(placed.cluster) ?? new Map();
+    clusters.set(placed.cluster, namespaces);
+    const instances = namespaces.get(placed.namespace) ?? new Map();
+    namespaces.set(placed.namespace, instances);
+    // Two Applications of one service in one place is one instance: the
+    // picture is about where it runs, and it runs there once.
+    if (!instances.has(service.id)) instances.set(service.id, { service, deployment: placed });
+  }
+}
+const environments = [...deployTree.keys()].sort();
+const sorted = (map) => [...map.keys()].sort();
+if (environments.length > 0) {
+  deployment.push("deployment {");
+  for (const env of environments) {
+    const envId = safeId(env);
+    deployment.push(`  environment ${envId} ${q(env)} {`);
+    const clusters = deployTree.get(env);
+    for (const cluster of sorted(clusters)) {
+      const path = [envId];
+      let indent = "    ";
+      if (cluster) {
+        path.push(safeId(cluster));
+        deployment.push(`${indent}cluster ${safeId(cluster)} ${q(cluster)} {`);
+        indent += "  ";
+      }
+      const namespaces = clusters.get(cluster);
+      for (const namespace of sorted(namespaces)) {
+        const nsPath = [...path];
+        let nsIndent = indent;
+        if (namespace) {
+          nsPath.push(safeId(namespace));
+          deployment.push(`${nsIndent}namespace ${safeId(namespace)} ${q(namespace)} {`);
+          nsIndent += "  ";
+        }
+        const instances = namespaces.get(namespace);
+        for (const serviceId of sorted(instances)) {
+          const { service, deployment: placed } = instances.get(serviceId);
+          const instanceId = safeId(service.id);
+          const revision = /^[0-9a-f]{40}$/.test(placed.revision) ? placed.revision.slice(0, 7) : placed.revision;
+          const about = [placed.name, revision ? `at ${revision}` : ""].filter(Boolean).join(" ");
+          deployment.push(`${nsIndent}${instanceId} = instanceOf ${fqn(service.id)} {`);
+          deployment.push(`${nsIndent}  description ${q(about)}`);
+          deployment.push(`${nsIndent}}`);
+          const places = placesOfService.get(service.id) ?? [];
+          places.push([...nsPath, instanceId].join("."));
+          placesOfService.set(service.id, places);
+          const frames = framesOfEnvironment.get(env) ?? new Set();
+          for (let depth = 2; depth <= nsPath.length; depth += 1) frames.add(nsPath.slice(0, depth).join("."));
+          frames.add([...nsPath, instanceId].join("."));
+          framesOfEnvironment.set(env, frames);
+        }
+        if (namespace) deployment.push(`${indent}}`);
+      }
+      if (cluster) deployment.push("    }");
+    }
+    deployment.push("  }");
+  }
+  deployment.push("}");
+
+  views.push("");
+  for (const env of environments) {
+    // Every frame under the environment, named one by one rather than as
+    // `env.**`: a descendant wildcard draws the instances alone and folds
+    // the cluster and namespace away, and where a thing runs is the point.
+    views.push(`  deployment view ${deploymentViewId(env)} {`);
+    views.push(`    title ${q(`${env} — deployed`)}`);
+    views.push(`    include ${[...framesOfEnvironment.get(env)].join(", ")}`);
+    views.push("  }");
+  }
+  for (const service of allServices) {
+    const places = placesOfService.get(service.id);
+    if (!places) continue;
+    // The frames around each instance, named one by one: a node named with
+    // its children is drawn as the frame it is, and a reader can tell the
+    // two boxes apart by where they sit.
+    const frames = new Set();
+    for (const place of places) {
+      const segments = place.split(".");
+      for (let depth = 1; depth <= segments.length; depth += 1) frames.add(segments.slice(0, depth).join("."));
+    }
+    views.push(`  deployment view ${serviceDeployViewId(service)} {`);
+    views.push(`    title ${q(`${service.name} — where it runs`)}`);
+    views.push(`    include ${[...frames].join(", ")}`);
+    views.push("  }");
+  }
+}
 views.push("}");
 
-mkdirSync("likec4", { recursive: true });
-writeFileSync("likec4/spec.c4", `${spec.join("\n")}\n`);
-writeFileSync(
-  "likec4/model.c4",
-  `// GENERATED — do not edit.\n${model.join("\n")}\n`,
-);
-writeFileSync(
-  "likec4/views.c4",
-  `// GENERATED — do not edit.\n${views.join("\n")}\n`,
-);
+return [
+  { name: "deployment.c4", contents: `// GENERATED — do not edit.\n${deployment.join("\n")}\n` },
+  { name: "spec.c4", contents: `${spec.join("\n")}\n` },
+  { name: "model.c4", contents: `// GENERATED — do not edit.\n${model.join("\n")}\n` },
+  { name: "views.c4", contents: `// GENERATED — do not edit.\n${views.join("\n")}\n` },
+];
+}
 
-console.log(
-  `wrote likec4/spec.c4, likec4/model.c4, likec4/views.c4 ` +
-    `(${catalog.flows.length * 2} dynamic views, ${relations.length} relations)`,
-);
+// Run as a script - `npm run likec4:gen`, before the dev server starts - the
+// sources are written under likec4/ here and now.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const bundle = await loadCatalog();
+  const files = await likec4Sources(bundle);
+  mkdirSync("likec4", { recursive: true });
+  for (const file of files) writeFileSync(join("likec4", file.name), file.contents);
+  console.log(
+    `wrote ${files.map((file) => `likec4/${file.name}`).join(", ")} ` +
+      `(${bundle.catalog.flows.length * 2} dynamic views)`,
+  );
+}

package/scripts/gen-likec4.test.mjs

@@ -6,6 +6,8 @@ import { execFileSync } from "node:child_process";
 
 import { describe, expect, it } from "vitest";
 
+import { likec4Sources } from "./gen-likec4.mjs";
+
 const generator = fileURLToPath(new URL("./gen-likec4.mjs", import.meta.url));
 const likec4 = join(
   dirname(dirname(generator)),
@@ -38,9 +40,22 @@ function generate(catalog) {
     spec: readFileSync(join(root, "likec4", "spec.c4"), "utf8"),
     model: readFileSync(join(root, "likec4", "model.c4"), "utf8"),
     views: readFileSync(join(root, "likec4", "views.c4"), "utf8"),
+    deployment: readFileSync(join(root, "likec4", "deployment.c4"), "utf8"),
   };
 }
 
+describe("the LikeC4 generator as a step of gen", () => {
+  it("hands back the four sources as files rather than writing them, so gen can settle them", async () => {
+    const files = await likec4Sources({
+      catalog: { generatedAt: "2026-09-06T00:00:00Z", commit: "0", adrs: [], defs: {}, contexts: [], flows: [] },
+      manifest: { sources: ["data/*.json"] },
+    });
+    expect(files.map((file) => file.name)).toEqual(["deployment.c4", "spec.c4", "model.c4", "views.c4"]);
+    expect(files.find((file) => file.name === "views.c4")?.contents).toContain("view landscape");
+    expect(files.every((file) => file.contents.endsWith("\n"))).toBe(true);
+  });
+});
+
 describe("the LikeC4 generator", () => {
   it("emits valid fallback views for an empty catalog", () => {
     const { model, views } = generate({ contexts: [], flows: [] });
@@ -432,4 +447,85 @@ describe("the LikeC4 generator", () => {
       /view svc_shop_oms of shop\.oms \{\n    title[^\n]*\n    include \*, -> \*, \* ->\n  \}/,
     );
   });
+
+  it("places every deployed service in its environment, cluster and namespace, and draws the frames by name", () => {
+    const service = (slug, path) => ({
+      id: `shop.${slug}`,
+      slug,
+      name: slug,
+      repo: "github.com/acme/shop",
+      path,
+      readme: "",
+      provides: [],
+      consumes: [],
+      aggregates: [],
+    });
+    const placed = (name, environment, cluster, namespace, path) => ({
+      id: `argocd/${name}`,
+      name,
+      project: "shop",
+      environment,
+      cluster,
+      namespace,
+      repo: "github.com/acme/shop",
+      path,
+      targetRevision: "main",
+      revision: "a".repeat(40),
+      tool: "kustomize",
+      url: `https://argocd.example.com/applications/argocd/${name}`,
+    });
+    const { spec, deployment, views } = generate({
+      contexts: [
+        {
+          id: "shop",
+          slug: "shop",
+          name: "Shop",
+          summary: "",
+          services: [service("cart", "services/cart"), service("oms", "services/oms")],
+        },
+      ],
+      flows: [],
+      deployments: [
+        placed("cart", "prod", "in-cluster", "shop", "services/cart/deploy"),
+        placed("cart-staging", "staging", "staging-eu", "shop", "services/cart/deploy"),
+        placed("oms", "prod", "in-cluster", "shop", "services/oms/deploy"),
+        // Deploys a repository nobody in the estate claims: placed nowhere.
+        placed("grafana", "prod", "in-cluster", "monitoring", "charts/grafana"),
+      ],
+    });
+    expect(spec).toContain("deploymentNode environment");
+    expect(deployment).toContain(
+      "  environment prod 'prod' {\n" +
+        "    cluster in_cluster 'in-cluster' {\n" +
+        "      namespace shop 'shop' {\n" +
+        "        shop_cart = instanceOf shop.cart {\n" +
+        "          description 'cart at aaaaaaa'\n" +
+        "        }\n" +
+        "        shop_oms = instanceOf shop.oms {",
+    );
+    expect(deployment).toContain("environment staging 'staging'");
+    expect(deployment).not.toContain("grafana");
+    expect(deployment).not.toContain("monitoring");
+    // The environment view names every frame under it; a descendant wildcard
+    // would fold the cluster and the namespace away.
+    expect(views).toContain(
+      "  deployment view deploy_prod {\n" +
+        "    title 'prod — deployed'\n" +
+        "    include prod.in_cluster, prod.in_cluster.shop, prod.in_cluster.shop.shop_cart, prod.in_cluster.shop.shop_oms\n" +
+        "  }",
+    );
+    expect(views).toContain(
+      "  deployment view deploy_svc_shop_cart {\n" +
+        "    title 'cart — where it runs'\n" +
+        "    include prod, prod.in_cluster, prod.in_cluster.shop, prod.in_cluster.shop.shop_cart, staging, staging.staging_eu, staging.staging_eu.shop, staging.staging_eu.shop.shop_cart\n" +
+        "  }",
+    );
+    expect(views).not.toContain("deploy_svc_shop_grafana");
+  });
+
+  it("writes an empty deployment file and no deployment view when nothing is placed", () => {
+    const { deployment, views } = generate({ contexts: [], flows: [] });
+    expect(deployment.trim()).toBe("// GENERATED — do not edit.");
+    expect(views).not.toContain("deployment view");
+  });
 });