@ybotok/loam 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/commands/new/templates.js

@@ -1,5 +1,6 @@
 /**
- * The six files `loam new` scaffolds, and what each one says.
+ * Five of the six files `loam new` scaffolds, and what each one says. The
+ * sixth, the `--capability` delta, is in `./capability-template.ts`.
  *
  * They are here rather than inline because every one of them is a document a
  * person edits next, and the wording IS the instruction: the delta's comments
@@ -9,20 +10,32 @@
  * file stops parsing.
  */
 import { stringify as stringifyYaml } from "yaml";
-import { REQUIREMENT_ID_RE } from "../../core/document/spec.js";
-import { ARCH_REQUIREMENT_SENTINEL, ARCH_SHALL_SENTINEL, CAPABILITY_REQUIREMENT_SENTINEL, CAPABILITY_SHALL_SENTINEL, REQUIREMENT_SENTINEL, SCENARIO_SENTINEL, SERVICE_DESCRIPTION_SENTINEL, GIVEN_SENTINEL, SHALL_SENTINEL, THEN_SENTINEL, WHEN_SENTINEL, } from "../../core/coherence/authoring/sentinels.js";
-function identifier(name, taken) {
-    const parts = name.split(/[^A-Za-z0-9]+/).filter((p) => p.length > 0);
-    const head = (parts[0] ?? "svc").replace(/^\d+/, "") || "svc";
-    const base = head[0].toLowerCase() +
-        head.slice(1) +
-        parts.slice(1).map((p) => p[0].toUpperCase() + p.slice(1)).join("");
+import { serviceElementId } from "../../core/c4/seed/template.js";
+import { ARCH_REQUIREMENT_SENTINEL, ARCH_SHALL_SENTINEL, REQUIREMENT_SENTINEL, SCENARIO_SENTINEL, SERVICE_DESCRIPTION_SENTINEL, GIVEN_SENTINEL, SHALL_SENTINEL, THEN_SENTINEL, WHEN_SENTINEL, } from "../../core/coherence/authoring/sentinels.js";
+/**
+ * The LikeC4 identifier the delta declares a service under: the id the fleet
+ * map already draws it as (`drawn`), since a context id the map lacks lines up
+ * with nothing at archive, else `serviceElementId` — seed's `svc_<id>`, where
+ * this used to camel-case the name into a third spelling beside the seed's and
+ * the map's. A collision inside one delta takes the seed's `_<n>` suffix.
+ */
+function identifier(name, taken, drawn) {
+    if (drawn !== undefined)
+        return drawn;
+    const base = serviceElementId(name);
     let id = base;
     for (let n = 2; taken.has(id); n += 1)
-        id = `${base}${n}`;
+        id = `${base}_${n}`;
     taken.add(id);
     return id;
 }
+/** One context line. A nested id (`a.b`) is no top-level declaration, so it names its parent instead. */
+function contextLine(id, name) {
+    const dot = id.lastIndexOf(".");
+    if (dot < 0)
+        return `  // ${id} = softwareSystem '${name}'`;
+    return `  // ${id.slice(dot + 1)} = softwareSystem '${name}'  // inside ${id.slice(0, dot)} { }, as the map draws it; edges name it ${id}`;
+}
 /** `FEAT-101` -> `feat_101`: LikeC4 view names take no dashes. */
 function viewName(featureId) {
     return featureId.toLowerCase().replace(/[^a-z0-9]+/g, "_");
@@ -44,6 +57,11 @@ export function intentTemplate(featureId, title) {
     // explicit null, which is a claim ("this feature has no owner") rather than
     // the truth ("nobody has said yet") — and every reader then has to tell an
     // absent key from a null one. The prompt survives as a comment.
+    //
+    // `## Open questions` is where loam-feature's analyze step writes, so it is
+    // scaffolded as a heading over a comment and nothing else. `intent.empty`
+    // (coherence/authoring/scaffold.ts) reads past the whole section, so neither
+    // the untouched comment nor a page of questions counts as the Why.
     const frontmatter = stringifyYaml({ feature: featureId, ...(title === undefined ? {} : { title }), status: "proposed" }, { lineWidth: 0 }).trimEnd();
     return `---
 ${frontmatter}
@@ -60,11 +78,18 @@ ${frontmatter}
 ## Scope
 
 <!-- Which services this touches — and, more usefully, which it deliberately does not. -->
+
+## Open questions
+
+<!-- Optional, never graded. What the documents leave open: an ambiguous SHALL, a value or
+     window two services state differently, an edge with no stated timeout, retry or
+     compensation. A person answers each by editing this section. -->
 `;
 }
-export function deltaTemplate(featureId, touched, created) {
-    const taken = new Set();
-    const touchedIds = touched.map((s) => [identifier(s, taken), s]);
+export function deltaTemplate(featureId, touched, created, drawn = new Map()) {
+    // The map's ids are claimed first: a new service's id never collides with a box quoted as context.
+    const taken = new Set(drawn.values());
+    const touchedIds = touched.map((s) => [identifier(s, taken, drawn.get(s)), s]);
     const createdIds = created.map((s) => [identifier(s, taken), s]);
     const lines = [];
     if (touchedIds.length > 0) {
@@ -75,11 +100,12 @@ export function deltaTemplate(featureId, touched, created) {
         // which teaches people that the validator is noise. Uncomment a line when an
         // edge below actually needs the identifier.
         lines.push("  // Services this feature touches, as context for the diagram. Uncomment the");
-        lines.push("  // ones an edge below names, and reuse the identifiers from");
-        lines.push("  // architecture/landscape.likec4 so the merge lines up. They stay UNTAGGED:");
+        lines.push("  // ones an edge below names. A service the fleet map already draws keeps the");
+        lines.push("  // identifier architecture/ gives it, so the merge lines up; one it does not");
+        lines.push("  // draw yet gets svc_<id>, the convention `loam seed` writes. They stay UNTAGGED:");
         lines.push(`  // only #${featureId} is the change, and everything else here is context.`);
         for (const [id, name] of touchedIds)
-            lines.push(`  // ${id} = softwareSystem '${name}'`);
+            lines.push(contextLine(id, name));
         lines.push("");
     }
     if (createdIds.length > 0) {
@@ -162,10 +188,12 @@ export function specTemplate(featureId, service) {
      A \`Publishes:\` / \`Consumes:\` body line does the same for event messages:
      it names what the requirement puts on or takes off the bus, checked
      against the service's AsyncAPI contract. If ${featureId} changes that
-     contract, hand-create specs/${service}/asyncapi.yaml — a complete
-     AsyncAPI 3.0 document, messages declared under \`components.messages\`
-     (loam scaffolds none: an event contract is genuinely optional) — and run
-     \`loam rebase ${featureId}\` so every restated slot pins as a quote.
+     contract, hand-create specs/${service}/asyncapi.yaml — an AsyncAPI 3.0
+     document holding only the slots this feature adds, changes or removes,
+     messages under \`components.messages\` (loam scaffolds none: an event
+     contract is genuinely optional) — and run \`loam rebase ${featureId}\`
+     when it edits a slot the living contract already has, so that slot pins.
+     The same holds for an openapi.yaml beside this file: only what changes.
 
      Copy the block below out of this comment, unindent it, and replace the
      TODOs and every <angle-bracket> fill-in — \`loam archive\` refuses the
@@ -230,110 +258,6 @@ export function archSpecTemplate(featureId, service) {
 -->
 `;
 }
-/**
- * The BUSINESS axis, scaffolded by `--capability`: a delta against the living
- * `capabilities/<id>/spec.md`.
- *
- * Same idiom as the two spec templates above and for the same reason — the
- * example lives INSIDE an HTML comment, indented past the line-anchored
- * `## ADDED Requirements` / `### Requirement:` patterns core/document/parse.ts
- * matches on — so the scaffold declares nothing until a person copies the block
- * out. That is what lets a freshly scaffolded feature validate clean while
- * still being refused by `loam archive` the moment the block is copied out and
- * left unedited (`scaffold.placeholder`, which reads
- * `features/<FEAT>/capabilities/` as well as `features/<FEAT>/specs/`).
- *
- * WHAT THE COMMENT TEACHES IS THE ALTITUDE, because that is the mistake this
- * document invites. A capability requirement is a promise a customer could
- * check; the four service-scoped lines (`Operations:`, `Covers:`, `Publishes:`,
- * `Consumes:`) and the axis's own two (`Capability:`, `Realizes:`) are all
- * ERRORS here — `capability.requirement-service-scoped` and
- * `capability.requirement-inert-join` — and every one of them parses, so an
- * author who is not told writes one and finds out at archive. `Requirement-ID:`
- * is spelled as mandatory for the same reason: a capability document outlives
- * every service that realizes it, so identity by heading is refused
- * (`capability.requirement-unidentified`).
- *
- * No nested HTML comments, exactly as `specTemplate` states: an inner `-->`
- * would end the outer comment early and re-expose the example to the parser.
- */
-export function capabilityDeltaTemplate(featureId, capability) {
-    return `# ${capability} — capability delta for ${featureId}
-
-<!-- The business axis. This is a DELTA against the living
-     capabilities/${capability}/spec.md, not the document itself: sections are
-     ADDED / MODIFIED / REMOVED, delete the ones you do not need, and a MODIFIED
-     requirement carries its full new text rather than a diff. If the fleet has
-     no capabilities/${capability}/spec.md yet, this feature's archive creates it.
-
-     WHAT BELONGS HERE is a promise somebody outside the fleet could check —
-     'a refund reaches the customer's card within five days'. What does NOT is
-     the mechanism: \`Operations:\`, \`Covers:\`, \`Publishes:\` and \`Consumes:\`
-     all resolve against ONE service's own contract or model, so a requirement
-     carrying one is a service requirement filed at the wrong altitude and
-     \`loam validate\` says so. \`Capability:\` and \`Realizes:\` are refused here
-     too — they are the joins written on the SERVICE requirement that keeps this
-     promise, one directory over in specs/<svc>/spec.md, as
-     \`Realizes: ${capability}#<Requirement-ID>\`.
-
-     \`Requirement-ID:\` is mandatory on every requirement below. A capability
-     document outlives the services that realize it, so its requirements are
-     addressed by a stable id rather than by their heading — rewording a heading
-     would otherwise be a removal and an addition, and every \`Realizes:\` line
-     pointed at it would break in silence.
-
-     A MODIFIED or REMOVED requirement also needs a \`Based-On:\` pin quoting the
-     living text it rewrites, so two features touching one capability collide
-     loudly instead of overwriting each other. Run \`loam rebase ${featureId}\`
-     and the pins are written for you.
-
-     Copy the block below out of this comment, unindent it, and replace the TODO
-     and every <angle-bracket> fill-in — \`loam archive\` refuses the scaffold's
-     own wording (\`scaffold.placeholder\`):
-
-    ## ADDED Requirements
-
-    ### Requirement: ${CAPABILITY_REQUIREMENT_SENTINEL}
-    Requirement-ID: ${idHint(capability)}
-
-    The fleet SHALL ${CAPABILITY_SHALL_SENTINEL}.
-
-    #### Scenario: ${SCENARIO_SENTINEL}
-    - **Given** ${GIVEN_SENTINEL}
-    - **When** ${WHEN_SENTINEL}
-    - **Then** ${THEN_SENTINEL}
--->
-`;
-}
-/**
- * A plausible `Requirement-ID:` for a capability, offered as a shape rather than
- * a name: `payments/refunds` -> `PAYMENTS-REFUNDS-1`.
- *
- * Deliberately NOT the feature id. A service requirement's scaffolded id is
- * `<FEAT>.<svc>.requirement` because that requirement is created by, and lives
- * and dies with, one feature; a capability requirement outlives every feature
- * that touches it, so an id carrying the id of the feature that happened to
- * introduce it is exactly the identity-by-accident this axis refuses. The
- * suffix is `-1` and not a count of anything: it is a placeholder digit inside
- * a placeholder id, and the author is being asked to name the promise.
- *
- * CHECKED AGAINST THE REAL GRAMMAR, never assumed to satisfy it. A capability id
- * may begin with a digit (`3ds`, `2fa`, `1099-filing` — `dirNameHazard` allows an
- * alphanumeric head) while `REQUIREMENT_ID_RE` demands a LETTER, so the obvious
- * slug hands the author `3DS-1` and `loam validate` then refuses it with
- * `delta.requirement-id-invalid` — the author refused for using the shape the
- * scaffold offered. Length is the same class of failure at 128 characters. The
- * fallback prefixes rather than truncates, because a truncated id is a plausible
- * name that means something else.
- */
-function idHint(capability) {
-    const slug = capability.toUpperCase().replace(/[^A-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-    const candidate = `${slug}-1`;
-    if (REQUIREMENT_ID_RE.test(candidate))
-        return candidate;
-    const prefixed = `CAP-${candidate}`;
-    return REQUIREMENT_ID_RE.test(prefixed) ? prefixed : "CAP-1";
-}
 export function openapiTemplate(service) {
     return `openapi: 3.1.0
 info:

package/dist/commands/new/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/commands/new/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,+BAA+B,EAC/B,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,4BAA4B,EAC5B,cAAc,EACd,cAAc,EACd,aAAa,EACb,aAAa,GACd,MAAM,6CAA6C,CAAC;AAErD,SAAS,UAAU,CAAC,IAAY,EAAE,KAAkB;IAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtE,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC;IAC9D,MAAM,IAAI,GACR,IAAI,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE;QACtB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACb,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvE,IAAI,EAAE,GAAG,IAAI,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC;QAAE,EAAE,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;IAC1D,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACd,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,kEAAkE;AAClE,SAAS,QAAQ,CAAC,SAAiB;IACjC,OAAO,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,KAAyB;IACzE,MAAM,OAAO,GAAG,KAAK,IAAI,SAAS,CAAC;IACnC,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,+EAA+E;IAC/E,2EAA2E;IAC3E,8BAA8B;IAC9B,EAAE;IACF,yEAAyE;IACzE,4EAA4E;IAC5E,2EAA2E;IAC3E,gEAAgE;IAChE,MAAM,WAAW,GAAG,aAAa,CAC/B,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EACrF,EAAE,SAAS,EAAE,CAAC,EAAE,CACjB,CAAC,OAAO,EAAE,CAAC;IACZ,OAAO;EACP,WAAW;;;;IAIT,OAAO;;;;;;;;;;CAUV,CAAC;AACF,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,OAAiB,EAAE,OAAiB;IACnF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAU,CAAC,CAAC;IAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAU,CAAC,CAAC;IAE1E,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,4EAA4E;QAC5E,0EAA0E;QAC1E,2EAA2E;QAC3E,wEAAwE;QACxE,6EAA6E;QAC7E,4CAA4C;QAC5C,KAAK,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAC;QAC5F,KAAK,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;QAC5E,KAAK,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAC;QAC5F,KAAK,CAAC,IAAI,CAAC,cAAc,SAAS,sDAAsD,CAAC,CAAC;QAC1F,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,UAAU;YAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,sBAAsB,IAAI,GAAG,CAAC,CAAC;QACzF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,6EAA6E,CAAC,CAAC;QAC1F,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QAC9C,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,UAAU,EAAE,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,sBAAsB,IAAI,KAAK,CAAC,CAAC;YACnD,KAAK,CAAC,IAAI,CAAC,QAAQ,SAAS,EAAE,CAAC,CAAC;YAChC,sEAAsE;YACtE,sEAAsE;YACtE,sEAAsE;YACtE,KAAK,CAAC,IAAI,CAAC,oBAAoB,4BAA4B,GAAG,CAAC,CAAC;YAChE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,8EAA8E;IAC9E,kEAAkE;IAClE,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC;IACpE,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC;IAClE,KAAK,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IAC/F,KAAK,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IAC/F,KAAK,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;IACpF,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnB,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,OAAO,EAAE,wBAAwB,CAAC,CAAC;IAC1D,KAAK,CAAC,IAAI,CAAC,WAAW,SAAS,EAAE,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAErB,OAAO,MAAM,SAAS;;wBAEA,SAAS;;;QAGzB,SAAS;;;;;QAKT,SAAS;;;;EAIf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;;;;SAIT,QAAQ,CAAC,SAAS,CAAC;;;;CAI3B,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,OAAe;IAC7D,OAAO,KAAK,OAAO,4BAA4B,SAAS;;;;;;;;;;;;;mDAaP,SAAS;mCACzB,OAAO;;;qBAGrB,SAAS;;;;;;;;uBAQP,oBAAoB;sBACrB,SAAS,IAAI,OAAO;;wBAElB,cAAc;;qBAEjB,iBAAiB;kBACpB,cAAc;iBACf,aAAa;iBACb,aAAa;;CAE7B,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,OAAe;IACjE,OAAO,KAAK,OAAO,yCAAyC,SAAS;;;;;;;;;iBAStD,OAAO;;6BAEK,OAAO;;;;2BAIT,SAAS;;;;;;uBAMb,yBAAyB;sBAC1B,SAAS,IAAI,OAAO;;wBAElB,mBAAmB;;cAE7B,OAAO;;qBAEA,iBAAiB;kBACpB,cAAc;iBACf,aAAa;iBACb,aAAa;;CAE7B,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAiB,EAAE,UAAkB;IAC3E,OAAO,KAAK,UAAU,2BAA2B,SAAS;;;oBAGxC,UAAU;;;uBAGP,UAAU;;;;;;;;;;mBAUd,UAAU;;;;;;;;;;mEAUsC,SAAS;;;;;;;;;uBASrD,+BAA+B;sBAChC,MAAM,CAAC,UAAU,CAAC;;sBAElB,yBAAyB;;qBAE1B,iBAAiB;kBACpB,cAAc;iBACf,aAAa;iBACb,aAAa;;CAE7B,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,MAAM,CAAC,UAAkB;IAChC,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC1F,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,CAAC;IAC9B,IAAI,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,QAAQ,GAAG,OAAO,SAAS,EAAE,CAAC;IACpC,OAAO,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO;;WAEE,OAAO;;;;;;;;;;;;;CAajB,CAAC;AACF,CAAC","sourcesContent":["/**\n * The six files `loam new` scaffolds, and what each one says.\n *\n * They are here rather than inline because every one of them is a document a\n * person edits next, and the wording IS the instruction: the delta's comments\n * teach the grammar `core/document/parse.ts` matches on, and the intent's\n * frontmatter is serialized rather than interpolated because a title is free\n * text somebody types — `Checkout: split payments` reopens the mapping and the\n * file stops parsing.\n */\nimport { stringify as stringifyYaml } from \"yaml\";\nimport { REQUIREMENT_ID_RE } from \"../../core/document/spec.js\";\nimport {\n  ARCH_REQUIREMENT_SENTINEL,\n  ARCH_SHALL_SENTINEL,\n  CAPABILITY_REQUIREMENT_SENTINEL,\n  CAPABILITY_SHALL_SENTINEL,\n  REQUIREMENT_SENTINEL,\n  SCENARIO_SENTINEL,\n  SERVICE_DESCRIPTION_SENTINEL,\n  GIVEN_SENTINEL,\n  SHALL_SENTINEL,\n  THEN_SENTINEL,\n  WHEN_SENTINEL,\n} from \"../../core/coherence/authoring/sentinels.js\";\n\nfunction identifier(name: string, taken: Set<string>): string {\n  const parts = name.split(/[^A-Za-z0-9]+/).filter((p) => p.length > 0);\n  const head = (parts[0] ?? \"svc\").replace(/^\\d+/, \"\") || \"svc\";\n  const base =\n    head[0]!.toLowerCase() +\n    head.slice(1) +\n    parts.slice(1).map((p) => p[0]!.toUpperCase() + p.slice(1)).join(\"\");\n  let id = base;\n  for (let n = 2; taken.has(id); n += 1) id = `${base}${n}`;\n  taken.add(id);\n  return id;\n}\n\n/** `FEAT-101` -> `feat_101`: LikeC4 view names take no dashes. */\nfunction viewName(featureId: string): string {\n  return featureId.toLowerCase().replace(/[^a-z0-9]+/g, \"_\");\n}\n\n/* ------------------------------------------------------------------ */\n/* Templates                                                           */\n/* ------------------------------------------------------------------ */\n\nexport function intentTemplate(featureId: string, title: string | undefined): string {\n  const heading = title ?? featureId;\n  // The frontmatter is SERIALIZED, never interpolated. A title is free text a\n  // person types — `Checkout: split payments` used to be pasted straight after\n  // `title: `, where the colon reopens the mapping and the file stops parsing;\n  // `Orders #42 rework` lost everything from the `#` as a YAML comment, so the\n  // feature quietly answered to a title nobody wrote. The yaml serializer is the\n  // only thing that knows every case, and it is already how migrate-openspec\n  // writes the same three keys.\n  //\n  // `owner` is deliberately NOT a key here. Scaffolding `owner:` writes an\n  // explicit null, which is a claim (\"this feature has no owner\") rather than\n  // the truth (\"nobody has said yet\") — and every reader then has to tell an\n  // absent key from a null one. The prompt survives as a comment.\n  const frontmatter = stringifyYaml(\n    { feature: featureId, ...(title === undefined ? {} : { title }), status: \"proposed\" },\n    { lineWidth: 0 },\n  ).trimEnd();\n  return `---\n${frontmatter}\n# owner: <the team or person who answers for this>\n---\n\n# ${heading}\n\n## Why\n\n<!-- The problem in business terms. This is what a reviewer reads first, and what\n     the requirement deltas below have to be justified by. -->\n\n## Scope\n\n<!-- Which services this touches — and, more usefully, which it deliberately does not. -->\n`;\n}\n\nexport function deltaTemplate(featureId: string, touched: string[], created: string[]): string {\n  const taken = new Set<string>();\n  const touchedIds = touched.map((s) => [identifier(s, taken), s] as const);\n  const createdIds = created.map((s) => [identifier(s, taken), s] as const);\n\n  const lines: string[] = [];\n  if (touchedIds.length > 0) {\n    // Context elements ship COMMENTED OUT, exactly like the example edge below.\n    // Declared-and-untagged is the one shape `delta.nothing-tagged` exists to\n    // refuse (an author who forgot the tags), so writing these live made every\n    // `loam new --touches X` fail its own validator on the very first run —\n    // which teaches people that the validator is noise. Uncomment a line when an\n    // edge below actually needs the identifier.\n    lines.push(\"  // Services this feature touches, as context for the diagram. Uncomment the\");\n    lines.push(\"  // ones an edge below names, and reuse the identifiers from\");\n    lines.push(\"  // architecture/landscape.likec4 so the merge lines up. They stay UNTAGGED:\");\n    lines.push(`  // only #${featureId} is the change, and everything else here is context.`);\n    for (const [id, name] of touchedIds) lines.push(`  // ${id} = softwareSystem '${name}'`);\n    lines.push(\"\");\n  }\n  if (createdIds.length > 0) {\n    lines.push(\"  // Services this feature introduces. The tag is what `loam archive` folds\");\n    lines.push(\"  // into the living landscape.\");\n    for (const [id, name] of createdIds) {\n      lines.push(`  ${id} = softwareSystem '${name}' {`);\n      lines.push(`    #${featureId}`);\n      // Interpolated from sentinels.ts, never spelled here: the placeholder\n      // gate refuses this exact string at archive, and a second spelling is\n      // how a template rewording silently retires the check that guards it.\n      lines.push(`    description '${SERVICE_DESCRIPTION_SENTINEL}'`);\n      lines.push(\"  }\");\n    }\n    lines.push(\"\");\n  }\n\n  // The example edge uses identifiers already declared above when there are two\n  // to join; otherwise placeholders, so it never invents a service.\n  const from = touchedIds[0]?.[0] ?? createdIds[0]?.[0] ?? \"consumer\";\n  const to = createdIds[0]?.[0] ?? touchedIds[1]?.[0] ?? \"provider\";\n  lines.push(\"  // New calls. `metadata { op }` is the spine: it names the OpenAPI operationId\");\n  lines.push(\"  // the call uses, and `loam validate` checks it against the target's contract.\");\n  lines.push(\"  // Uncomment and adjust (both endpoints have to be declared above):\");\n  lines.push(\"  //\");\n  lines.push(`  // ${from} -> ${to} 'Calls createSplit' {`);\n  lines.push(`  //   #${featureId}`);\n  lines.push(\"  //   metadata { op 'createSplit' }\");\n  lines.push(\"  // }\");\n\n  return `// ${featureId} — architecture delta.\n//\n// Everything tagged #${featureId} is exactly what \\`loam archive\\` folds into\n// architecture/landscape.likec4. Everything else here is context for the diagram.\n//\n// If ${featureId} changes no architecture, DELETE this file: a requirements-only\n// feature is complete without it, and an empty \\`model {}\\` is just as legal.\n\nspecification {\n  element softwareSystem\n  tag ${featureId}\n}\n\nmodel {\n${lines.join(\"\\n\")}\n}\n\nviews {\n  view ${viewName(featureId)} {\n    include *\n  }\n}\n`;\n}\n\n/**\n * The business axis, scaffolded with its example INSIDE the comment — the same\n * mechanism as `archSpecTemplate` below, for the same reason: this template\n * used to ship a live `### Requirement: TODO — name the behaviour` that\n * parsed as a real requirement, validated clean, and archived a literal TODO\n * into the living spec at exit 0. The indented headings sit past the\n * line-anchored patterns core/document/parse.ts matches on, so the scaffold\n * declares nothing until a person copies the block out and writes over the\n * fill-ins — and `scaffold.placeholder` gates the archive if the fill-ins\n * survive the copy.\n *\n * No nested HTML comments: the `Operations:` guidance that used to be its own\n * comment lives in this one's prose, because an inner `-->` would end the\n * outer comment early and re-expose the example to the parser.\n */\nexport function specTemplate(featureId: string, service: string): string {\n  return `# ${service} — requirement delta for ${featureId}\n\n<!-- Sections: ADDED / MODIFIED / REMOVED. Delete the ones you do not need.\n     A MODIFIED requirement carries its full new text, not a diff.\n     Every requirement needs at least one scenario — \\`loam validate\\` gates on it.\n\n     An \\`Operations:\\` body line names the operationIds the requirement\n     governs. \\`loam validate\\` checks each one against the service's OpenAPI,\n     and \\`loam archive\\` refuses to merge a requirement that governs an\n     operation nobody defines — add the line once the contract exists.\n\n     A \\`Publishes:\\` / \\`Consumes:\\` body line does the same for event messages:\n     it names what the requirement puts on or takes off the bus, checked\n     against the service's AsyncAPI contract. If ${featureId} changes that\n     contract, hand-create specs/${service}/asyncapi.yaml — a complete\n     AsyncAPI 3.0 document, messages declared under \\`components.messages\\`\n     (loam scaffolds none: an event contract is genuinely optional) — and run\n     \\`loam rebase ${featureId}\\` so every restated slot pins as a quote.\n\n     Copy the block below out of this comment, unindent it, and replace the\n     TODOs and every <angle-bracket> fill-in — \\`loam archive\\` refuses the\n     scaffold's own wording (\\`scaffold.placeholder\\`):\n\n    ## ADDED Requirements\n\n    ### Requirement: ${REQUIREMENT_SENTINEL}\n    Requirement-ID: ${featureId}.${service}.requirement\n\n    The service SHALL ${SHALL_SENTINEL}.\n\n    #### Scenario: ${SCENARIO_SENTINEL}\n    - **Given** ${GIVEN_SENTINEL}\n    - **When** ${WHEN_SENTINEL}\n    - **Then** ${THEN_SENTINEL}\n-->\n`;\n}\n\n/**\n * The architecture axis, scaffolded EMPTY on purpose.\n *\n * Same grammar as spec.md, so the template body has to be unparseable as\n * requirements or the scaffold would ship a requirement nobody wrote — the\n * headings are therefore indented inside an HTML comment, which puts them past\n * the line-anchored `## ADDED Requirements` / `### Requirement:` patterns\n * core/document/parse.ts matches on. Copy the block out of the comment and unindent it.\n */\nexport function archSpecTemplate(featureId: string, service: string): string {\n  return `# ${service} — architecture requirement delta for ${featureId}\n\n<!-- The architecture axis: the obligations no business scenario was ever going\n     to mention — the outbox, the retries, the timeouts, the alerts.\n\n     \\`Covers:\\` is to an arch requirement what \\`Operations:\\` is to a business\n     one — it names the MODEL OBJECTS the scenarios below exercise, so coverage\n     is derived instead of trusted. Three forms, comma-separated:\n\n       Covers: ${service}                 a C4 element — its id, or the service a\n                                          bound/titled element stands for\n       Covers: consumer -> ${service}     an edge, each side resolved the same way\n       Covers: alert:<id>, sli:<id>       a signal declared in health.yaml\n\n     Every tagged element and edge in delta.likec4 wants one (\\`c4.uncovered\\`).\n     Delete this file if ${featureId} adds no architectural obligation.\n\n     Copy the block below out of this comment and unindent it:\n\n    ## ADDED Requirements\n\n    ### Requirement: ${ARCH_REQUIREMENT_SENTINEL}\n    Requirement-ID: ${featureId}.${service}.arch\n\n    The service SHALL ${ARCH_SHALL_SENTINEL}.\n\n    Covers: ${service}\n\n    #### Scenario: ${SCENARIO_SENTINEL}\n    - **Given** ${GIVEN_SENTINEL}\n    - **When** ${WHEN_SENTINEL}\n    - **Then** ${THEN_SENTINEL}\n-->\n`;\n}\n\n/**\n * The BUSINESS axis, scaffolded by `--capability`: a delta against the living\n * `capabilities/<id>/spec.md`.\n *\n * Same idiom as the two spec templates above and for the same reason — the\n * example lives INSIDE an HTML comment, indented past the line-anchored\n * `## ADDED Requirements` / `### Requirement:` patterns core/document/parse.ts\n * matches on — so the scaffold declares nothing until a person copies the block\n * out. That is what lets a freshly scaffolded feature validate clean while\n * still being refused by `loam archive` the moment the block is copied out and\n * left unedited (`scaffold.placeholder`, which reads\n * `features/<FEAT>/capabilities/` as well as `features/<FEAT>/specs/`).\n *\n * WHAT THE COMMENT TEACHES IS THE ALTITUDE, because that is the mistake this\n * document invites. A capability requirement is a promise a customer could\n * check; the four service-scoped lines (`Operations:`, `Covers:`, `Publishes:`,\n * `Consumes:`) and the axis's own two (`Capability:`, `Realizes:`) are all\n * ERRORS here — `capability.requirement-service-scoped` and\n * `capability.requirement-inert-join` — and every one of them parses, so an\n * author who is not told writes one and finds out at archive. `Requirement-ID:`\n * is spelled as mandatory for the same reason: a capability document outlives\n * every service that realizes it, so identity by heading is refused\n * (`capability.requirement-unidentified`).\n *\n * No nested HTML comments, exactly as `specTemplate` states: an inner `-->`\n * would end the outer comment early and re-expose the example to the parser.\n */\nexport function capabilityDeltaTemplate(featureId: string, capability: string): string {\n  return `# ${capability} — capability delta for ${featureId}\n\n<!-- The business axis. This is a DELTA against the living\n     capabilities/${capability}/spec.md, not the document itself: sections are\n     ADDED / MODIFIED / REMOVED, delete the ones you do not need, and a MODIFIED\n     requirement carries its full new text rather than a diff. If the fleet has\n     no capabilities/${capability}/spec.md yet, this feature's archive creates it.\n\n     WHAT BELONGS HERE is a promise somebody outside the fleet could check —\n     'a refund reaches the customer's card within five days'. What does NOT is\n     the mechanism: \\`Operations:\\`, \\`Covers:\\`, \\`Publishes:\\` and \\`Consumes:\\`\n     all resolve against ONE service's own contract or model, so a requirement\n     carrying one is a service requirement filed at the wrong altitude and\n     \\`loam validate\\` says so. \\`Capability:\\` and \\`Realizes:\\` are refused here\n     too — they are the joins written on the SERVICE requirement that keeps this\n     promise, one directory over in specs/<svc>/spec.md, as\n     \\`Realizes: ${capability}#<Requirement-ID>\\`.\n\n     \\`Requirement-ID:\\` is mandatory on every requirement below. A capability\n     document outlives the services that realize it, so its requirements are\n     addressed by a stable id rather than by their heading — rewording a heading\n     would otherwise be a removal and an addition, and every \\`Realizes:\\` line\n     pointed at it would break in silence.\n\n     A MODIFIED or REMOVED requirement also needs a \\`Based-On:\\` pin quoting the\n     living text it rewrites, so two features touching one capability collide\n     loudly instead of overwriting each other. Run \\`loam rebase ${featureId}\\`\n     and the pins are written for you.\n\n     Copy the block below out of this comment, unindent it, and replace the TODO\n     and every <angle-bracket> fill-in — \\`loam archive\\` refuses the scaffold's\n     own wording (\\`scaffold.placeholder\\`):\n\n    ## ADDED Requirements\n\n    ### Requirement: ${CAPABILITY_REQUIREMENT_SENTINEL}\n    Requirement-ID: ${idHint(capability)}\n\n    The fleet SHALL ${CAPABILITY_SHALL_SENTINEL}.\n\n    #### Scenario: ${SCENARIO_SENTINEL}\n    - **Given** ${GIVEN_SENTINEL}\n    - **When** ${WHEN_SENTINEL}\n    - **Then** ${THEN_SENTINEL}\n-->\n`;\n}\n\n/**\n * A plausible `Requirement-ID:` for a capability, offered as a shape rather than\n * a name: `payments/refunds` -> `PAYMENTS-REFUNDS-1`.\n *\n * Deliberately NOT the feature id. A service requirement's scaffolded id is\n * `<FEAT>.<svc>.requirement` because that requirement is created by, and lives\n * and dies with, one feature; a capability requirement outlives every feature\n * that touches it, so an id carrying the id of the feature that happened to\n * introduce it is exactly the identity-by-accident this axis refuses. The\n * suffix is `-1` and not a count of anything: it is a placeholder digit inside\n * a placeholder id, and the author is being asked to name the promise.\n *\n * CHECKED AGAINST THE REAL GRAMMAR, never assumed to satisfy it. A capability id\n * may begin with a digit (`3ds`, `2fa`, `1099-filing` — `dirNameHazard` allows an\n * alphanumeric head) while `REQUIREMENT_ID_RE` demands a LETTER, so the obvious\n * slug hands the author `3DS-1` and `loam validate` then refuses it with\n * `delta.requirement-id-invalid` — the author refused for using the shape the\n * scaffold offered. Length is the same class of failure at 128 characters. The\n * fallback prefixes rather than truncates, because a truncated id is a plausible\n * name that means something else.\n */\nfunction idHint(capability: string): string {\n  const slug = capability.toUpperCase().replace(/[^A-Z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  const candidate = `${slug}-1`;\n  if (REQUIREMENT_ID_RE.test(candidate)) return candidate;\n  const prefixed = `CAP-${candidate}`;\n  return REQUIREMENT_ID_RE.test(prefixed) ? prefixed : \"CAP-1\";\n}\n\nexport function openapiTemplate(service: string): string {\n  return `openapi: 3.1.0\ninfo:\n  title: ${service}\n  version: \"0.1\"\n\n# The operations this feature adds. \\`operationId\\` is the token the C4 edge\n# (metadata { op }) and the requirement (Operations:) both point at — keep the\n# three spellings identical or \\`loam validate\\` will say so.\npaths: {}\n#  /splits:\n#    post:\n#      operationId: createSplit\n#      responses:\n#        \"201\":\n#          description: Created\n`;\n}\n"]}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/commands/new/templates.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Five of the six files `loam new` scaffolds, and what each one says. The\n * sixth, the `--capability` delta, is in `./capability-template.ts`.\n *\n * They are here rather than inline because every one of them is a document a\n * person edits next, and the wording IS the instruction: the delta's comments\n * teach the grammar `core/document/parse.ts` matches on, and the intent's\n * frontmatter is serialized rather than interpolated because a title is free\n * text somebody types — `Checkout: split payments` reopens the mapping and the\n * file stops parsing.\n */\nimport { stringify as stringifyYaml } from \"yaml\";\nimport { serviceElementId } from \"../../core/c4/seed/template.js\";\nimport {\n  ARCH_REQUIREMENT_SENTINEL,\n  ARCH_SHALL_SENTINEL,\n  REQUIREMENT_SENTINEL,\n  SCENARIO_SENTINEL,\n  SERVICE_DESCRIPTION_SENTINEL,\n  GIVEN_SENTINEL,\n  SHALL_SENTINEL,\n  THEN_SENTINEL,\n  WHEN_SENTINEL,\n} from \"../../core/coherence/authoring/sentinels.js\";\n\n/**\n * The LikeC4 identifier the delta declares a service under: the id the fleet\n * map already draws it as (`drawn`), since a context id the map lacks lines up\n * with nothing at archive, else `serviceElementId` — seed's `svc_<id>`, where\n * this used to camel-case the name into a third spelling beside the seed's and\n * the map's. A collision inside one delta takes the seed's `_<n>` suffix.\n */\nfunction identifier(name: string, taken: Set<string>, drawn?: string): string {\n  if (drawn !== undefined) return drawn;\n  const base = serviceElementId(name);\n  let id = base;\n  for (let n = 2; taken.has(id); n += 1) id = `${base}_${n}`;\n  taken.add(id);\n  return id;\n}\n\n/** One context line. A nested id (`a.b`) is no top-level declaration, so it names its parent instead. */\nfunction contextLine(id: string, name: string): string {\n  const dot = id.lastIndexOf(\".\");\n  if (dot < 0) return `  // ${id} = softwareSystem '${name}'`;\n  return `  // ${id.slice(dot + 1)} = softwareSystem '${name}'  // inside ${id.slice(0, dot)} { }, as the map draws it; edges name it ${id}`;\n}\n\n/** `FEAT-101` -> `feat_101`: LikeC4 view names take no dashes. */\nfunction viewName(featureId: string): string {\n  return featureId.toLowerCase().replace(/[^a-z0-9]+/g, \"_\");\n}\n\n/* ------------------------------------------------------------------ */\n/* Templates                                                           */\n/* ------------------------------------------------------------------ */\n\nexport function intentTemplate(featureId: string, title: string | undefined): string {\n  const heading = title ?? featureId;\n  // The frontmatter is SERIALIZED, never interpolated. A title is free text a\n  // person types — `Checkout: split payments` used to be pasted straight after\n  // `title: `, where the colon reopens the mapping and the file stops parsing;\n  // `Orders #42 rework` lost everything from the `#` as a YAML comment, so the\n  // feature quietly answered to a title nobody wrote. The yaml serializer is the\n  // only thing that knows every case, and it is already how migrate-openspec\n  // writes the same three keys.\n  //\n  // `owner` is deliberately NOT a key here. Scaffolding `owner:` writes an\n  // explicit null, which is a claim (\"this feature has no owner\") rather than\n  // the truth (\"nobody has said yet\") — and every reader then has to tell an\n  // absent key from a null one. The prompt survives as a comment.\n  //\n  // `## Open questions` is where loam-feature's analyze step writes, so it is\n  // scaffolded as a heading over a comment and nothing else. `intent.empty`\n  // (coherence/authoring/scaffold.ts) reads past the whole section, so neither\n  // the untouched comment nor a page of questions counts as the Why.\n  const frontmatter = stringifyYaml(\n    { feature: featureId, ...(title === undefined ? {} : { title }), status: \"proposed\" },\n    { lineWidth: 0 },\n  ).trimEnd();\n  return `---\n${frontmatter}\n# owner: <the team or person who answers for this>\n---\n\n# ${heading}\n\n## Why\n\n<!-- The problem in business terms. This is what a reviewer reads first, and what\n     the requirement deltas below have to be justified by. -->\n\n## Scope\n\n<!-- Which services this touches — and, more usefully, which it deliberately does not. -->\n\n## Open questions\n\n<!-- Optional, never graded. What the documents leave open: an ambiguous SHALL, a value or\n     window two services state differently, an edge with no stated timeout, retry or\n     compensation. A person answers each by editing this section. -->\n`;\n}\n\nexport function deltaTemplate(featureId: string, touched: string[], created: string[], drawn: ReadonlyMap<string, string> = new Map()): string {\n  // The map's ids are claimed first: a new service's id never collides with a box quoted as context.\n  const taken = new Set<string>(drawn.values());\n  const touchedIds = touched.map((s) => [identifier(s, taken, drawn.get(s)), s] as const);\n  const createdIds = created.map((s) => [identifier(s, taken), s] as const);\n\n  const lines: string[] = [];\n  if (touchedIds.length > 0) {\n    // Context elements ship COMMENTED OUT, exactly like the example edge below.\n    // Declared-and-untagged is the one shape `delta.nothing-tagged` exists to\n    // refuse (an author who forgot the tags), so writing these live made every\n    // `loam new --touches X` fail its own validator on the very first run —\n    // which teaches people that the validator is noise. Uncomment a line when an\n    // edge below actually needs the identifier.\n    lines.push(\"  // Services this feature touches, as context for the diagram. Uncomment the\");\n    lines.push(\"  // ones an edge below names. A service the fleet map already draws keeps the\");\n    lines.push(\"  // identifier architecture/ gives it, so the merge lines up; one it does not\");\n    lines.push(\"  // draw yet gets svc_<id>, the convention `loam seed` writes. They stay UNTAGGED:\");\n    lines.push(`  // only #${featureId} is the change, and everything else here is context.`);\n    for (const [id, name] of touchedIds) lines.push(contextLine(id, name));\n    lines.push(\"\");\n  }\n  if (createdIds.length > 0) {\n    lines.push(\"  // Services this feature introduces. The tag is what `loam archive` folds\");\n    lines.push(\"  // into the living landscape.\");\n    for (const [id, name] of createdIds) {\n      lines.push(`  ${id} = softwareSystem '${name}' {`);\n      lines.push(`    #${featureId}`);\n      // Interpolated from sentinels.ts, never spelled here: the placeholder\n      // gate refuses this exact string at archive, and a second spelling is\n      // how a template rewording silently retires the check that guards it.\n      lines.push(`    description '${SERVICE_DESCRIPTION_SENTINEL}'`);\n      lines.push(\"  }\");\n    }\n    lines.push(\"\");\n  }\n\n  // The example edge uses identifiers already declared above when there are two\n  // to join; otherwise placeholders, so it never invents a service.\n  const from = touchedIds[0]?.[0] ?? createdIds[0]?.[0] ?? \"consumer\";\n  const to = createdIds[0]?.[0] ?? touchedIds[1]?.[0] ?? \"provider\";\n  lines.push(\"  // New calls. `metadata { op }` is the spine: it names the OpenAPI operationId\");\n  lines.push(\"  // the call uses, and `loam validate` checks it against the target's contract.\");\n  lines.push(\"  // Uncomment and adjust (both endpoints have to be declared above):\");\n  lines.push(\"  //\");\n  lines.push(`  // ${from} -> ${to} 'Calls createSplit' {`);\n  lines.push(`  //   #${featureId}`);\n  lines.push(\"  //   metadata { op 'createSplit' }\");\n  lines.push(\"  // }\");\n\n  return `// ${featureId} — architecture delta.\n//\n// Everything tagged #${featureId} is exactly what \\`loam archive\\` folds into\n// architecture/landscape.likec4. Everything else here is context for the diagram.\n//\n// If ${featureId} changes no architecture, DELETE this file: a requirements-only\n// feature is complete without it, and an empty \\`model {}\\` is just as legal.\n\nspecification {\n  element softwareSystem\n  tag ${featureId}\n}\n\nmodel {\n${lines.join(\"\\n\")}\n}\n\nviews {\n  view ${viewName(featureId)} {\n    include *\n  }\n}\n`;\n}\n\n/**\n * The business axis, scaffolded with its example INSIDE the comment — the same\n * mechanism as `archSpecTemplate` below, for the same reason: this template\n * used to ship a live `### Requirement: TODO — name the behaviour` that\n * parsed as a real requirement, validated clean, and archived a literal TODO\n * into the living spec at exit 0. The indented headings sit past the\n * line-anchored patterns core/document/parse.ts matches on, so the scaffold\n * declares nothing until a person copies the block out and writes over the\n * fill-ins — and `scaffold.placeholder` gates the archive if the fill-ins\n * survive the copy.\n *\n * No nested HTML comments: the `Operations:` guidance that used to be its own\n * comment lives in this one's prose, because an inner `-->` would end the\n * outer comment early and re-expose the example to the parser.\n */\nexport function specTemplate(featureId: string, service: string): string {\n  return `# ${service} — requirement delta for ${featureId}\n\n<!-- Sections: ADDED / MODIFIED / REMOVED. Delete the ones you do not need.\n     A MODIFIED requirement carries its full new text, not a diff.\n     Every requirement needs at least one scenario — \\`loam validate\\` gates on it.\n\n     An \\`Operations:\\` body line names the operationIds the requirement\n     governs. \\`loam validate\\` checks each one against the service's OpenAPI,\n     and \\`loam archive\\` refuses to merge a requirement that governs an\n     operation nobody defines — add the line once the contract exists.\n\n     A \\`Publishes:\\` / \\`Consumes:\\` body line does the same for event messages:\n     it names what the requirement puts on or takes off the bus, checked\n     against the service's AsyncAPI contract. If ${featureId} changes that\n     contract, hand-create specs/${service}/asyncapi.yaml — an AsyncAPI 3.0\n     document holding only the slots this feature adds, changes or removes,\n     messages under \\`components.messages\\` (loam scaffolds none: an event\n     contract is genuinely optional) — and run \\`loam rebase ${featureId}\\`\n     when it edits a slot the living contract already has, so that slot pins.\n     The same holds for an openapi.yaml beside this file: only what changes.\n\n     Copy the block below out of this comment, unindent it, and replace the\n     TODOs and every <angle-bracket> fill-in — \\`loam archive\\` refuses the\n     scaffold's own wording (\\`scaffold.placeholder\\`):\n\n    ## ADDED Requirements\n\n    ### Requirement: ${REQUIREMENT_SENTINEL}\n    Requirement-ID: ${featureId}.${service}.requirement\n\n    The service SHALL ${SHALL_SENTINEL}.\n\n    #### Scenario: ${SCENARIO_SENTINEL}\n    - **Given** ${GIVEN_SENTINEL}\n    - **When** ${WHEN_SENTINEL}\n    - **Then** ${THEN_SENTINEL}\n-->\n`;\n}\n\n/**\n * The architecture axis, scaffolded EMPTY on purpose.\n *\n * Same grammar as spec.md, so the template body has to be unparseable as\n * requirements or the scaffold would ship a requirement nobody wrote — the\n * headings are therefore indented inside an HTML comment, which puts them past\n * the line-anchored `## ADDED Requirements` / `### Requirement:` patterns\n * core/document/parse.ts matches on. Copy the block out of the comment and unindent it.\n */\nexport function archSpecTemplate(featureId: string, service: string): string {\n  return `# ${service} — architecture requirement delta for ${featureId}\n\n<!-- The architecture axis: the obligations no business scenario was ever going\n     to mention — the outbox, the retries, the timeouts, the alerts.\n\n     \\`Covers:\\` is to an arch requirement what \\`Operations:\\` is to a business\n     one — it names the MODEL OBJECTS the scenarios below exercise, so coverage\n     is derived instead of trusted. Three forms, comma-separated:\n\n       Covers: ${service}                 a C4 element — its id, or the service a\n                                          bound/titled element stands for\n       Covers: consumer -> ${service}     an edge, each side resolved the same way\n       Covers: alert:<id>, sli:<id>       a signal declared in health.yaml\n\n     Every tagged element and edge in delta.likec4 wants one (\\`c4.uncovered\\`).\n     Delete this file if ${featureId} adds no architectural obligation.\n\n     Copy the block below out of this comment and unindent it:\n\n    ## ADDED Requirements\n\n    ### Requirement: ${ARCH_REQUIREMENT_SENTINEL}\n    Requirement-ID: ${featureId}.${service}.arch\n\n    The service SHALL ${ARCH_SHALL_SENTINEL}.\n\n    Covers: ${service}\n\n    #### Scenario: ${SCENARIO_SENTINEL}\n    - **Given** ${GIVEN_SENTINEL}\n    - **When** ${WHEN_SENTINEL}\n    - **Then** ${THEN_SENTINEL}\n-->\n`;\n}\n\nexport function openapiTemplate(service: string): string {\n  return `openapi: 3.1.0\ninfo:\n  title: ${service}\n  version: \"0.1\"\n\n# The operations this feature adds. \\`operationId\\` is the token the C4 edge\n# (metadata { op }) and the requirement (Operations:) both point at — keep the\n# three spellings identical or \\`loam validate\\` will say so.\npaths: {}\n#  /splits:\n#    post:\n#      operationId: createSplit\n#      responses:\n#        \"201\":\n#          description: Created\n`;\n}\n"]}

package/dist/commands/open.js

@@ -1,8 +1,7 @@
 import { statSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { loadConfig } from "../core/envelope/config.js";
-import { emitJson, fail, reportNoConfig } from "../core/envelope/json.js";
+import { configOrRefuse, emitJson, fail } from "../core/envelope/json.js";
 import { DocsRepoUnavailableError } from "../core/repo/state.js";
 import { discoverMembers } from "../core/workspace/discover.js";
 import { renderWorkspace } from "../core/workspace/render.js";
@@ -41,12 +40,9 @@ export function registerOpen(program) {
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts) => {
         const json = opts.json === true;
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const config = loaded.config;
         const { docsDir } = config;
         // "docs", not "services": this command enumerates checkouts on the LOCAL
         // filesystem, not services/ in the docs repo, and a docs repo nobody has

package/dist/commands/open.js.map

@@ -1 +1 @@
-{"version":3,"file":"open.js","sourceRoot":"","sources":["../../src/commands/open.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { statSync } from \"node:fs\";\nimport { writeFile } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { loadConfig } from \"../core/envelope/config.js\";\nimport { emitJson, fail, reportNoConfig } from \"../core/envelope/json.js\";\nimport { DocsRepoUnavailableError } from \"../core/repo/state.js\";\nimport { discoverMembers, type Discovery } from \"../core/workspace/discover.js\";\nimport { renderWorkspace, type RenderedFolder } from \"../core/workspace/render.js\";\nimport { docsRepoReady, reportDocsRepoError } from \"./policy/gate.js\";\n\ninterface OpenOptions {\n  json?: boolean;\n  /** --root, collected: each value REPLACES the default scan roots. */\n  root?: string[];\n  out?: string;\n  force?: boolean;\n}\n\n/**\n * A fixed default name, not `<basename(docsDir)>.code-workspace`: predictable\n * beats collision-proof for a file that is regenerable on demand, and `--out`\n * is the lever for anyone holding two fleets' workspaces in one directory.\n */\nconst DEFAULT_OUT = \"loam.code-workspace\";\n\n/**\n * Is there a directory at `path`? A probe that cannot answer says \"no\": for a\n * value the user typed, \"cannot be read\" earns the same `invalid-option`\n * refusal as \"is not there\" — never an `internal` escape. throwIfNoEntry folds\n * the absent case into the same answer with no window between probe and use;\n * the catch covers the errnos statSync can still raise (EACCES, ENOTDIR — a\n * path routed through a file).\n */\nfunction directoryAt(path: string): boolean {\n  try {\n    return statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;\n  } catch {\n    return false;\n  }\n}\n\n/** The write-path errnos that mean the OUT PATH is wrong, not loam. */\nconst OUT_PATH_ERRNOS = new Set([\"EISDIR\", \"EACCES\", \"EPERM\", \"ENOTDIR\", \"EINVAL\"]);\n\nexport function registerOpen(program: Command): void {\n  program\n    .command(\"open\")\n    .description(\"Write a .code-workspace joining the docs repo and every bound service checkout\")\n    .option(\n      \"--root <dir>\",\n      \"scan this directory for bound checkouts instead of the defaults; repeatable\",\n      (value: string, prev: string[] = []) => [...prev, value],\n    )\n    .option(\"--out <file>\", `workspace file to write (default ${DEFAULT_OUT} in the current directory)`)\n    .option(\"--force\", \"overwrite the workspace file if it already exists\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: OpenOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n      const { docsDir } = config;\n      // \"docs\", not \"services\": this command enumerates checkouts on the LOCAL\n      // filesystem, not services/ in the docs repo, and a docs repo nobody has\n      // run `loam adopt` against is still worth opening an editor on.\n      if (!docsRepoReady(json, docsDir, \"docs\")) return;\n\n      // Both typed paths are validated before any discovery runs: a --root or\n      // --out typo is a fact about the INVOCATION, not the fleet, and it must\n      // refuse before the scan — not after verdicts were computed over\n      // directories nobody meant, and not from the write at the very end.\n      const roots = (opts.root ?? []).map((dir) => resolve(dir));\n      for (const dir of roots) {\n        if (!directoryAt(dir)) {\n          fail(json, \"invalid-option\", `--root does not name a readable directory: ${dir}`);\n          return;\n        }\n      }\n      const out = resolve(opts.out ?? DEFAULT_OUT);\n      const parent = dirname(out);\n      if (!directoryAt(parent)) {\n        fail(json, \"invalid-option\", `--out points into a directory that does not exist: ${parent}`);\n        return;\n      }\n\n      let discovery: Discovery;\n      try {\n        discovery = await discoverMembers({\n          docsDir,\n          // parseConfig always derives `root`; the fallback only documents\n          // which absence the optional type would otherwise leave a guess.\n          configRoot: config.root ?? process.cwd(),\n          ...(config.service === undefined ? {} : { service: config.service }),\n          ...(roots.length === 0 ? {} : { roots }),\n        });\n      } catch (err) {\n        // The gate above passed, so this is the repo vanishing mid-run —\n        // the same breach the enumeration reports, spelled the same way.\n        if (!(err instanceof DocsRepoUnavailableError)) throw err;\n        reportDocsRepoError(json, err);\n        return;\n      }\n\n      // An explicit --root that cannot be LISTED refuses: the caller named the\n      // directory, so \"I could not look\" must never come back as an empty\n      // scan. The default roots keep degrading to empty — a CI sandbox that\n      // denies the docs repo's parent is survivable, and both views still\n      // report the degrade below.\n      if (roots.length > 0 && discovery.unreadableRoots.length > 0) {\n        const listing = discovery.unreadableRoots\n          .map((entry) => `${entry.root} (${entry.problem})`)\n          .join(\"; \");\n        fail(json, \"invalid-option\", `--root cannot be scanned: ${listing}`);\n        return;\n      }\n\n      if (discovery.duplicates.length > 0) {\n        const claims = discovery.duplicates.map(\n          (d) => `'${d.service}' is declared by ${d.paths.join(\" and \")}`,\n        );\n        fail(\n          json,\n          \"binding-duplicate\",\n          `Two checkouts declare the same service for this docs repo: ${claims.join(\"; \")}. ` +\n            \"loam will not guess which checkout speaks for the service — narrow the scan \" +\n            \"with --root, or fix the stray loam.json, then re-run.\",\n        );\n        return;\n      }\n      // Only reachable from the docs repo itself — a service-repo invocation\n      // always contributes its own checkout as a member. Skipped candidates\n      // ride the message: a checkout whose binding would not parse is the\n      // likeliest reason the scan came up empty, and the real fix is that\n      // file, not --root.\n      if (!discovery.members.some((member) => member.via !== \"docs-repo\")) {\n        const unread = discovery.skipped.length === 0\n          ? \"\"\n          : ` ${discovery.skipped.length} candidate binding(s) could not be read and did not` +\n            ` count: ${discovery.skipped.map((s) => `${s.path} (${s.problem})`).join(\"; \")}.`;\n        fail(\n          json,\n          \"no-members\",\n          `No service checkout bound to ${docsDir} was found under ` +\n            `${discovery.scannedRoots.join(\", \")} — the workspace would hold only the docs ` +\n            \"repo. Clone a bound service repo beside it, run `loam open` from a service \" +\n            `repo, or pass --root naming the directory the checkouts live in.${unread}`,\n        );\n        return;\n      }\n\n      const rendered = renderWorkspace(discovery.members, out);\n      try {\n        // \"wx\" makes probe-and-write one operation, so a concurrent writer\n        // cannot land between an existsSync and the write. --force is honest\n        // here where init's generated files needed skip-forever: a workspace\n        // file is wholly derived, so overwriting it loses nothing authored.\n        await writeFile(out, rendered.text, {\n          encoding: \"utf8\",\n          flag: opts.force === true ? \"w\" : \"wx\",\n        });\n      } catch (err) {\n        const e = err as NodeJS.ErrnoException;\n        if (e.code === \"EEXIST\") {\n          fail(\n            json,\n            \"already-exists\",\n            `${out} already exists. Pass --out naming another file, or --force to overwrite it.`,\n          );\n          return;\n        }\n        // The path-shaped failures: --out names a directory (EISDIR — the\n        // exact target the EEXIST remedy above just told the caller to\n        // --force), or a place this process may not write. Each is a fact\n        // about the out path, so it earns invalid-option, not internal.\n        if (typeof e.code === \"string\" && OUT_PATH_ERRNOS.has(e.code)) {\n          fail(\n            json,\n            \"invalid-option\",\n            `The workspace file cannot be written at ${out}: ${e.message}. ` +\n              \"Pass --out naming a writable file path.\",\n          );\n          return;\n        }\n        throw err;\n      }\n\n      if (json) {\n        emitJson({\n          command: \"open\",\n          docsDir,\n          out,\n          written: true,\n          members: rendered.folders.map((folder) => ({\n            path: folder.member.path,\n            // The exact spelling written into the workspace file, so a\n            // consumer never re-derives (and mis-derives) the relative form.\n            folder: folder.path,\n            name: folder.name,\n            service: folder.member.service,\n            via: folder.member.via,\n            ...(folder.member.via === \"scan\" ? { root: folder.member.root } : {}),\n          })),\n          scannedRoots: discovery.scannedRoots,\n          unreadableRoots: discovery.unreadableRoots,\n          skipped: discovery.skipped,\n        });\n        return;\n      }\n      printWorkspace(out, discovery, rendered.folders);\n    });\n}\n\nfunction viaText(folder: RenderedFolder): string {\n  const member = folder.member;\n  if (member.via === \"docs-repo\") return \"docs repo\";\n  if (member.via === \"current-repo\") return \"this repo\";\n  return `found under ${member.root}`;\n}\n\nfunction printWorkspace(out: string, discovery: Discovery, folders: RenderedFolder[]): void {\n  console.log(`workspace: ${out} (${folders.length} folders)`);\n  for (const folder of folders) {\n    console.log(`  ${folder.name}  ${folder.path}  (${viaText(folder)})`);\n  }\n  // Reported beside the result, not folded into it: an unreadable binding or\n  // an unlistable default root proves nothing, but silence about either would\n  // read as \"not bound\" / \"nothing there\".\n  for (const entry of discovery.unreadableRoots) {\n    console.log(`  ! could not scan ${entry.root}: ${entry.problem}`);\n  }\n  for (const entry of discovery.skipped) {\n    console.log(`  ! skipped ${entry.path}: ${entry.problem}`);\n  }\n}\n"]}
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../src/commands/open.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { statSync } from \"node:fs\";\nimport { writeFile } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { configOrRefuse, emitJson, fail } from \"../core/envelope/json.js\";\nimport { DocsRepoUnavailableError } from \"../core/repo/state.js\";\nimport { discoverMembers, type Discovery } from \"../core/workspace/discover.js\";\nimport { renderWorkspace, type RenderedFolder } from \"../core/workspace/render.js\";\nimport { docsRepoReady, reportDocsRepoError } from \"./policy/gate.js\";\n\ninterface OpenOptions {\n  json?: boolean;\n  /** --root, collected: each value REPLACES the default scan roots. */\n  root?: string[];\n  out?: string;\n  force?: boolean;\n}\n\n/**\n * A fixed default name, not `<basename(docsDir)>.code-workspace`: predictable\n * beats collision-proof for a file that is regenerable on demand, and `--out`\n * is the lever for anyone holding two fleets' workspaces in one directory.\n */\nconst DEFAULT_OUT = \"loam.code-workspace\";\n\n/**\n * Is there a directory at `path`? A probe that cannot answer says \"no\": for a\n * value the user typed, \"cannot be read\" earns the same `invalid-option`\n * refusal as \"is not there\" — never an `internal` escape. throwIfNoEntry folds\n * the absent case into the same answer with no window between probe and use;\n * the catch covers the errnos statSync can still raise (EACCES, ENOTDIR — a\n * path routed through a file).\n */\nfunction directoryAt(path: string): boolean {\n  try {\n    return statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;\n  } catch {\n    return false;\n  }\n}\n\n/** The write-path errnos that mean the OUT PATH is wrong, not loam. */\nconst OUT_PATH_ERRNOS = new Set([\"EISDIR\", \"EACCES\", \"EPERM\", \"ENOTDIR\", \"EINVAL\"]);\n\nexport function registerOpen(program: Command): void {\n  program\n    .command(\"open\")\n    .description(\"Write a .code-workspace joining the docs repo and every bound service checkout\")\n    .option(\n      \"--root <dir>\",\n      \"scan this directory for bound checkouts instead of the defaults; repeatable\",\n      (value: string, prev: string[] = []) => [...prev, value],\n    )\n    .option(\"--out <file>\", `workspace file to write (default ${DEFAULT_OUT} in the current directory)`)\n    .option(\"--force\", \"overwrite the workspace file if it already exists\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: OpenOptions) => {\n      const json = opts.json === true;\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      // \"docs\", not \"services\": this command enumerates checkouts on the LOCAL\n      // filesystem, not services/ in the docs repo, and a docs repo nobody has\n      // run `loam adopt` against is still worth opening an editor on.\n      if (!docsRepoReady(json, docsDir, \"docs\")) return;\n\n      // Both typed paths are validated before any discovery runs: a --root or\n      // --out typo is a fact about the INVOCATION, not the fleet, and it must\n      // refuse before the scan — not after verdicts were computed over\n      // directories nobody meant, and not from the write at the very end.\n      const roots = (opts.root ?? []).map((dir) => resolve(dir));\n      for (const dir of roots) {\n        if (!directoryAt(dir)) {\n          fail(json, \"invalid-option\", `--root does not name a readable directory: ${dir}`);\n          return;\n        }\n      }\n      const out = resolve(opts.out ?? DEFAULT_OUT);\n      const parent = dirname(out);\n      if (!directoryAt(parent)) {\n        fail(json, \"invalid-option\", `--out points into a directory that does not exist: ${parent}`);\n        return;\n      }\n\n      let discovery: Discovery;\n      try {\n        discovery = await discoverMembers({\n          docsDir,\n          // parseConfig always derives `root`; the fallback only documents\n          // which absence the optional type would otherwise leave a guess.\n          configRoot: config.root ?? process.cwd(),\n          ...(config.service === undefined ? {} : { service: config.service }),\n          ...(roots.length === 0 ? {} : { roots }),\n        });\n      } catch (err) {\n        // The gate above passed, so this is the repo vanishing mid-run —\n        // the same breach the enumeration reports, spelled the same way.\n        if (!(err instanceof DocsRepoUnavailableError)) throw err;\n        reportDocsRepoError(json, err);\n        return;\n      }\n\n      // An explicit --root that cannot be LISTED refuses: the caller named the\n      // directory, so \"I could not look\" must never come back as an empty\n      // scan. The default roots keep degrading to empty — a CI sandbox that\n      // denies the docs repo's parent is survivable, and both views still\n      // report the degrade below.\n      if (roots.length > 0 && discovery.unreadableRoots.length > 0) {\n        const listing = discovery.unreadableRoots\n          .map((entry) => `${entry.root} (${entry.problem})`)\n          .join(\"; \");\n        fail(json, \"invalid-option\", `--root cannot be scanned: ${listing}`);\n        return;\n      }\n\n      if (discovery.duplicates.length > 0) {\n        const claims = discovery.duplicates.map(\n          (d) => `'${d.service}' is declared by ${d.paths.join(\" and \")}`,\n        );\n        fail(\n          json,\n          \"binding-duplicate\",\n          `Two checkouts declare the same service for this docs repo: ${claims.join(\"; \")}. ` +\n            \"loam will not guess which checkout speaks for the service — narrow the scan \" +\n            \"with --root, or fix the stray loam.json, then re-run.\",\n        );\n        return;\n      }\n      // Only reachable from the docs repo itself — a service-repo invocation\n      // always contributes its own checkout as a member. Skipped candidates\n      // ride the message: a checkout whose binding would not parse is the\n      // likeliest reason the scan came up empty, and the real fix is that\n      // file, not --root.\n      if (!discovery.members.some((member) => member.via !== \"docs-repo\")) {\n        const unread = discovery.skipped.length === 0\n          ? \"\"\n          : ` ${discovery.skipped.length} candidate binding(s) could not be read and did not` +\n            ` count: ${discovery.skipped.map((s) => `${s.path} (${s.problem})`).join(\"; \")}.`;\n        fail(\n          json,\n          \"no-members\",\n          `No service checkout bound to ${docsDir} was found under ` +\n            `${discovery.scannedRoots.join(\", \")} — the workspace would hold only the docs ` +\n            \"repo. Clone a bound service repo beside it, run `loam open` from a service \" +\n            `repo, or pass --root naming the directory the checkouts live in.${unread}`,\n        );\n        return;\n      }\n\n      const rendered = renderWorkspace(discovery.members, out);\n      try {\n        // \"wx\" makes probe-and-write one operation, so a concurrent writer\n        // cannot land between an existsSync and the write. --force is honest\n        // here where init's generated files needed skip-forever: a workspace\n        // file is wholly derived, so overwriting it loses nothing authored.\n        await writeFile(out, rendered.text, {\n          encoding: \"utf8\",\n          flag: opts.force === true ? \"w\" : \"wx\",\n        });\n      } catch (err) {\n        const e = err as NodeJS.ErrnoException;\n        if (e.code === \"EEXIST\") {\n          fail(\n            json,\n            \"already-exists\",\n            `${out} already exists. Pass --out naming another file, or --force to overwrite it.`,\n          );\n          return;\n        }\n        // The path-shaped failures: --out names a directory (EISDIR — the\n        // exact target the EEXIST remedy above just told the caller to\n        // --force), or a place this process may not write. Each is a fact\n        // about the out path, so it earns invalid-option, not internal.\n        if (typeof e.code === \"string\" && OUT_PATH_ERRNOS.has(e.code)) {\n          fail(\n            json,\n            \"invalid-option\",\n            `The workspace file cannot be written at ${out}: ${e.message}. ` +\n              \"Pass --out naming a writable file path.\",\n          );\n          return;\n        }\n        throw err;\n      }\n\n      if (json) {\n        emitJson({\n          command: \"open\",\n          docsDir,\n          out,\n          written: true,\n          members: rendered.folders.map((folder) => ({\n            path: folder.member.path,\n            // The exact spelling written into the workspace file, so a\n            // consumer never re-derives (and mis-derives) the relative form.\n            folder: folder.path,\n            name: folder.name,\n            service: folder.member.service,\n            via: folder.member.via,\n            ...(folder.member.via === \"scan\" ? { root: folder.member.root } : {}),\n          })),\n          scannedRoots: discovery.scannedRoots,\n          unreadableRoots: discovery.unreadableRoots,\n          skipped: discovery.skipped,\n        });\n        return;\n      }\n      printWorkspace(out, discovery, rendered.folders);\n    });\n}\n\nfunction viaText(folder: RenderedFolder): string {\n  const member = folder.member;\n  if (member.via === \"docs-repo\") return \"docs repo\";\n  if (member.via === \"current-repo\") return \"this repo\";\n  return `found under ${member.root}`;\n}\n\nfunction printWorkspace(out: string, discovery: Discovery, folders: RenderedFolder[]): void {\n  console.log(`workspace: ${out} (${folders.length} folders)`);\n  for (const folder of folders) {\n    console.log(`  ${folder.name}  ${folder.path}  (${viaText(folder)})`);\n  }\n  // Reported beside the result, not folded into it: an unreadable binding or\n  // an unlistable default root proves nothing, but silence about either would\n  // read as \"not bound\" / \"nothing there\".\n  for (const entry of discovery.unreadableRoots) {\n    console.log(`  ! could not scan ${entry.root}: ${entry.problem}`);\n  }\n  for (const entry of discovery.skipped) {\n    console.log(`  ! skipped ${entry.path}: ${entry.problem}`);\n  }\n}\n"]}

package/dist/commands/policy/gate.js

@@ -13,8 +13,13 @@
  * writes to stdout or stderr and sets the exit code. That is a decision about
  * how this process ends, and core modules compute answers rather than end
  * processes.
+ *
+ * A fourth sits at the bottom for the commands that read the docs repo AT a
+ * git ref — `baseOrRefuse`, the same doctrine one step on: a ref git cannot
+ * answer for is "could not look", never an empty base.
  */
 import { fail } from "../../core/envelope/json.js";
+import { resolveBase } from "../../core/diff/base-git.js";
 import { docsRepoState } from "../../core/repo/state.js";
 /**
  * The refusal every READ command owes a `docsDir` that is not a docs repo.
@@ -101,4 +106,26 @@ export function reportRepositoryUnavailable(json, err, consequence, docsDir) {
             `A file under ${docsDir} could not be read, so ${consequence}. ${why}. ` +
                 `The failure named no path — that is how Node reports a directory sitting where a file belongs.`);
 }
+/**
+ * The resolved base, or null after refusing: `repository-unavailable` when
+ * the docs repo is not somewhere git can answer from, `unknown-target` when
+ * the ref names no commit there (an option-shaped ref included —
+ * `resolveBase` refuses it before it can reach an argv).
+ */
+export async function baseOrRefuse(json, docsDir, req) {
+    const base = await resolveBase(docsDir, req.ref);
+    if (base.kind === "no-git") {
+        fail(json, "repository-unavailable", `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +
+            `${req.reads} with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +
+            `to be a git checkout with the ${req.flag} ref present. Clone the docs repo with its history, then re-run.`);
+        return null;
+    }
+    if (base.kind === "no-ref") {
+        fail(json, "unknown-target", `${req.flag} ${req.ref} does not resolve to a commit in the docs repo at ${docsDir}` +
+            `${base.detail === "" ? "" : ` (${base.detail})`}. ` +
+            `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`);
+        return null;
+    }
+    return { docsDir, commit: base.commit, prefix: base.prefix };
+}
 //# sourceMappingURL=gate.js.map

package/dist/commands/policy/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/commands/policy/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnD,OAAO,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,OAAe,EAAE,IAAyB;IACrF,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1F,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CACF,IAAI,EACJ,cAAc,EACd,4CAA4C,KAAK,CAAC,IAAI,IAAI;YACxD,yDAAyD;YACzD,6DAA6D,CAChE,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CACF,IAAI,EACJ,kBAAkB,EAClB,GAAG,KAAK,CAAC,IAAI,uDAAuD;QAClE,wDAAwD;QACxD,uDAAuD,CAC1D,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa,EAAE,GAA6B;IAC9E,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,kBAAkB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAa,EACb,GAAY,EACZ,WAAmB,EACnB,OAAe;IAEf,MAAM,CAAC,GAAG,GAA4B,CAAC;IACvC,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,MAAM,GAAG,CAAC;IACnE,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,CACF,IAAI,EACJ,wBAAwB,EACxB,CAAC,CAAC,IAAI,KAAK,SAAS;QAClB,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,0BAA0B,WAAW,KAAK,GAAG,EAAE;QAC1D,CAAC,CAAC,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,wCAAwC;YACxC,gBAAgB,OAAO,0BAA0B,WAAW,KAAK,GAAG,IAAI;gBACxE,gGAAgG,CACrG,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The three refusals every command owes a docs repo it cannot read.\n *\n * One doctrine, three ways of reaching it: the gate a command passes before it\n * enumerates anything, the error the enumeration throws when the repo goes away\n * underneath it, and the errno that comes back when the repo is real but one\n * file under it will not open. Every command that reads a docs repo reaches\n * for one or another of them (`rg docsRepoReady` is the always-current list),\n * and the whole point of collecting them is that they all answer with the same\n * sentences.\n *\n * They live in `commands/` rather than in `core/`: each one calls `fail`, which\n * writes to stdout or stderr and sets the exit code. That is a decision about\n * how this process ends, and core modules compute answers rather than end\n * processes.\n */\nimport { fail } from \"../../core/envelope/json.js\";\nimport { docsRepoState, type DocsRepoUnavailableError } from \"../../core/repo/state.js\";\n\n/**\n * The refusal every READ command owes a `docsDir` that is not a docs repo.\n *\n * It is not a formality. `validate --all` and `list` used to answer a docsDir\n * that does not exist with a green report over zero services, which is the one\n * output a fleet gate must never produce: \"nothing is wrong\" and \"I could not\n * look\" are opposite facts, and in CI the first one merges. The two codes are\n * kept apart because the fixes point in different directions — a wrong path in\n * loam.json versus a docs repo that was never cloned or scaffolded — exactly\n * the way `no-config` and `config-invalid` are kept apart.\n *\n * \"Zero services\" stays reachable, and only from a REAL docs repo whose\n * `services/` is empty: that is a legitimate state (before the first\n * `loam adopt`) and it must keep exiting 0.\n *\n * `need` says how much of a docs repo this particular run has to have. A run\n * that only reads features genuinely does not need `services/` — repo.ts takes\n * the same position for `listFeatures` — and refusing there would turn one\n * diagnosis into two contradictory ones. A run that enumerates services needs\n * the directory that IS the list of services.\n *\n * It used to live in validate.ts, on the reasoning that validate is the fleet\n * gate this doctrine is about. Enough commands import it now that the doctrine\n * outgrew its host: `loam show` was structurally depending on the whole\n * validate implementation for twenty lines of policy. The rule is the module\n * now, and validate is one of its callers like the rest.\n */\nexport function docsRepoReady(json: boolean, docsDir: string, need: \"docs\" | \"services\"): boolean {\n  const state = docsRepoState(docsDir);\n  if (state.kind === \"ok\" || (state.kind === \"no-services\" && need === \"docs\")) return true;\n  if (state.kind === \"missing\") {\n    fail(\n      json,\n      \"docs-missing\",\n      `The configured docs repo does not exist: ${state.path}. ` +\n        \"Fix `docsDir` in loam.json, clone the docs repo there, \" +\n        \"or run `loam init --docs <dir> --create` to make a new one.\",\n    );\n    return false;\n  }\n  fail(\n    json,\n    \"services-missing\",\n    `${state.path} is not a docs repo — it has no services/ directory. ` +\n      \"Point `docsDir` in loam.json at the shared docs repo, \" +\n      \"or run `loam init --docs <dir> --create` to make one.\",\n  );\n  return false;\n}\n\n/**\n * The same refusal, reached the other way: `listServices`/`listFeatures` throw\n * `DocsRepoUnavailableError` when the repo goes away mid-run (or when a caller\n * reaches enumeration without passing the gate above). Mapping it back onto the\n * same two codes keeps one breach spelled one way, instead of surfacing as the\n * `internal` catch-all in cli.ts.\n */\nexport function reportDocsRepoError(json: boolean, err: DocsRepoUnavailableError): void {\n  fail(json, err.state.kind === \"missing\" ? \"docs-missing\" : \"services-missing\", err.message);\n}\n\n/**\n * The third refusal a reading command owes: the docs repo IS a docs repo, but\n * one file under it cannot be read. `list`, `show`, `status` and `validate` all\n * walk a directory tree to answer, so all four owe the same sentence — and all\n * four kept their own copy of it, which is exactly how three of them ended up\n * wrong. Sharing it here, beside `reportDocsRepoError`, is the same trade: one\n * breach spelled one way instead of four that drift.\n *\n * A filesystem failure is recognised by its errno, NOT by carrying a `path`.\n * Node reports EISDIR from `read()` with no path at all — the directory opened,\n * the read failed — so a guard that looked only for `path` was defeated by the\n * commonest way a malformed docs repo breaks: one directory sitting where a\n * file belongs escaped as a bare `internal: EISDIR`, naming neither the file\n * nor the target. Anything carrying no errno at all is a real bug, and still\n * escapes untouched.\n *\n * `consequence` is the clause after \"so\" — what the caller could not answer\n * because of this. It is the only part that differs between the four.\n */\nexport function reportRepositoryUnavailable(\n  json: boolean,\n  err: unknown,\n  consequence: string,\n  docsDir: string,\n): void {\n  const e = err as NodeJS.ErrnoException;\n  if (e.path === undefined && typeof e.errno !== \"number\") throw err;\n  const why = err instanceof Error ? err.message : String(err);\n  fail(\n    json,\n    \"repository-unavailable\",\n    e.path !== undefined\n      ? `${e.path} could not be read, so ${consequence}. ${why}`\n      : // Naming the target's own directory here would be a guess, and a guess\n        // that is wrong precisely when it matters: one malformed artifact makes\n        // every OTHER target's answer fail too, and each would have accused its\n        // own files. Say what is known instead.\n        `A file under ${docsDir} could not be read, so ${consequence}. ${why}. ` +\n        `The failure named no path — that is how Node reports a directory sitting where a file belongs.`,\n  );\n}\n"]}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/commands/policy/gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The three refusals every command owes a docs repo it cannot read.\n *\n * One doctrine, three ways of reaching it: the gate a command passes before it\n * enumerates anything, the error the enumeration throws when the repo goes away\n * underneath it, and the errno that comes back when the repo is real but one\n * file under it will not open. Every command that reads a docs repo reaches\n * for one or another of them (`rg docsRepoReady` is the always-current list),\n * and the whole point of collecting them is that they all answer with the same\n * sentences.\n *\n * They live in `commands/` rather than in `core/`: each one calls `fail`, which\n * writes to stdout or stderr and sets the exit code. That is a decision about\n * how this process ends, and core modules compute answers rather than end\n * processes.\n *\n * A fourth sits at the bottom for the commands that read the docs repo AT a\n * git ref — `baseOrRefuse`, the same doctrine one step on: a ref git cannot\n * answer for is \"could not look\", never an empty base.\n */\nimport { fail } from \"../../core/envelope/json.js\";\nimport { resolveBase, type ResolvedBase } from \"../../core/diff/base-git.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { docsRepoState, type DocsRepoUnavailableError } from \"../../core/repo/state.js\";\n\n/**\n * The refusal every READ command owes a `docsDir` that is not a docs repo.\n *\n * It is not a formality. `validate --all` and `list` used to answer a docsDir\n * that does not exist with a green report over zero services, which is the one\n * output a fleet gate must never produce: \"nothing is wrong\" and \"I could not\n * look\" are opposite facts, and in CI the first one merges. The two codes are\n * kept apart because the fixes point in different directions — a wrong path in\n * loam.json versus a docs repo that was never cloned or scaffolded — exactly\n * the way `no-config` and `config-invalid` are kept apart.\n *\n * \"Zero services\" stays reachable, and only from a REAL docs repo whose\n * `services/` is empty: that is a legitimate state (before the first\n * `loam adopt`) and it must keep exiting 0.\n *\n * `need` says how much of a docs repo this particular run has to have. A run\n * that only reads features genuinely does not need `services/` — repo.ts takes\n * the same position for `listFeatures` — and refusing there would turn one\n * diagnosis into two contradictory ones. A run that enumerates services needs\n * the directory that IS the list of services.\n *\n * It used to live in validate.ts, on the reasoning that validate is the fleet\n * gate this doctrine is about. Enough commands import it now that the doctrine\n * outgrew its host: `loam show` was structurally depending on the whole\n * validate implementation for twenty lines of policy. The rule is the module\n * now, and validate is one of its callers like the rest.\n */\nexport function docsRepoReady(json: boolean, docsDir: string, need: \"docs\" | \"services\"): boolean {\n  const state = docsRepoState(docsDir);\n  if (state.kind === \"ok\" || (state.kind === \"no-services\" && need === \"docs\")) return true;\n  if (state.kind === \"missing\") {\n    fail(\n      json,\n      \"docs-missing\",\n      `The configured docs repo does not exist: ${state.path}. ` +\n        \"Fix `docsDir` in loam.json, clone the docs repo there, \" +\n        \"or run `loam init --docs <dir> --create` to make a new one.\",\n    );\n    return false;\n  }\n  fail(\n    json,\n    \"services-missing\",\n    `${state.path} is not a docs repo — it has no services/ directory. ` +\n      \"Point `docsDir` in loam.json at the shared docs repo, \" +\n      \"or run `loam init --docs <dir> --create` to make one.\",\n  );\n  return false;\n}\n\n/**\n * The same refusal, reached the other way: `listServices`/`listFeatures` throw\n * `DocsRepoUnavailableError` when the repo goes away mid-run (or when a caller\n * reaches enumeration without passing the gate above). Mapping it back onto the\n * same two codes keeps one breach spelled one way, instead of surfacing as the\n * `internal` catch-all in cli.ts.\n */\nexport function reportDocsRepoError(json: boolean, err: DocsRepoUnavailableError): void {\n  fail(json, err.state.kind === \"missing\" ? \"docs-missing\" : \"services-missing\", err.message);\n}\n\n/**\n * The third refusal a reading command owes: the docs repo IS a docs repo, but\n * one file under it cannot be read. `list`, `show`, `status` and `validate` all\n * walk a directory tree to answer, so all four owe the same sentence — and all\n * four kept their own copy of it, which is exactly how three of them ended up\n * wrong. Sharing it here, beside `reportDocsRepoError`, is the same trade: one\n * breach spelled one way instead of four that drift.\n *\n * A filesystem failure is recognised by its errno, NOT by carrying a `path`.\n * Node reports EISDIR from `read()` with no path at all — the directory opened,\n * the read failed — so a guard that looked only for `path` was defeated by the\n * commonest way a malformed docs repo breaks: one directory sitting where a\n * file belongs escaped as a bare `internal: EISDIR`, naming neither the file\n * nor the target. Anything carrying no errno at all is a real bug, and still\n * escapes untouched.\n *\n * `consequence` is the clause after \"so\" — what the caller could not answer\n * because of this. It is the only part that differs between the four.\n */\nexport function reportRepositoryUnavailable(\n  json: boolean,\n  err: unknown,\n  consequence: string,\n  docsDir: string,\n): void {\n  const e = err as NodeJS.ErrnoException;\n  if (e.path === undefined && typeof e.errno !== \"number\") throw err;\n  const why = err instanceof Error ? err.message : String(err);\n  fail(\n    json,\n    \"repository-unavailable\",\n    e.path !== undefined\n      ? `${e.path} could not be read, so ${consequence}. ${why}`\n      : // Naming the target's own directory here would be a guess, and a guess\n        // that is wrong precisely when it matters: one malformed artifact makes\n        // every OTHER target's answer fail too, and each would have accused its\n        // own files. Say what is known instead.\n        `A file under ${docsDir} could not be read, so ${consequence}. ${why}. ` +\n        `The failure named no path — that is how Node reports a directory sitting where a file belongs.`,\n  );\n}\n\n/**\n * The refusals a command owes a docs-repo git ref it cannot read at.\n *\n * Two commands read the docs repo AT a ref: `loam diff --base <ref>` (the\n * whole fleet, to diff against) and `loam gate --since <ref>` (which features\n * had already shipped, so the ones archived after it are graded too). Both\n * REFUSE when git cannot answer, unlike provenance's \"git will not say\": a\n * missing base is not an empty one, and reading it as empty is a fail-open in\n * both — diff would report the whole fleet as added, gate would pass a deploy\n * over every feature archived since a ref it never resolved. One helper, so\n * the two refusals are one sentence each with the flag swapped in, rather\n * than two copies drifting.\n */\nexport interface BaseRequest {\n  /** The flag the ref arrived on, as the user typed it: `--base`, `--since`. */\n  flag: string;\n  ref: string;\n  /** What the command reads at the ref, as the subject of a sentence: \"loam diff reads the base state\". */\n  reads: string;\n}\n\n/**\n * The resolved base, or null after refusing: `repository-unavailable` when\n * the docs repo is not somewhere git can answer from, `unknown-target` when\n * the ref names no commit there (an option-shaped ref included —\n * `resolveBase` refuses it before it can reach an argv).\n */\nexport async function baseOrRefuse(\n  json: boolean,\n  docsDir: DocsDir,\n  req: BaseRequest,\n): Promise<ResolvedBase | null> {\n  const base = await resolveBase(docsDir, req.ref);\n  if (base.kind === \"no-git\") {\n    fail(\n      json,\n      \"repository-unavailable\",\n      `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +\n        `${req.reads} with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +\n        `to be a git checkout with the ${req.flag} ref present. Clone the docs repo with its history, then re-run.`,\n    );\n    return null;\n  }\n  if (base.kind === \"no-ref\") {\n    fail(\n      json,\n      \"unknown-target\",\n      `${req.flag} ${req.ref} does not resolve to a commit in the docs repo at ${docsDir}` +\n        `${base.detail === \"\" ? \"\" : ` (${base.detail})`}. ` +\n        `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,\n    );\n    return null;\n  }\n  return { docsDir, commit: base.commit, prefix: base.prefix };\n}\n"]}

package/dist/commands/rebase/plan.js

@@ -127,7 +127,7 @@ export async function planOpenapi(repo, service, openapiPath) {
         // writes one file once. Order is safe: a surface digest never includes an
         // operation pin (`restatedSurfaces` skips the methods entirely), and the
         // root record never enters an operation digest.
-        baselines = planOpenapiBaselines(plan.text ?? delta, living, service);
+        baselines = planOpenapiBaselines(plan.text ?? delta, living);
     }
     catch (err) {
         // A document loam cannot read is validate's diagnosis to make
@@ -193,7 +193,7 @@ export async function planAsyncapi(repo, service, asyncapiPath) {
         // directions: a surface digest never includes a slot pin (`asyncapiSurfaces`
         // skips `components.messages` entirely, and no other section is a
         // surface), and the root record never enters a slot digest.
-        baselines = planAsyncapiBaselines(plan.text ?? delta, living, service);
+        baselines = planAsyncapiBaselines(plan.text ?? delta, living);
     }
     catch (err) {
         // A document loam cannot read is validate's diagnosis to make