@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.1

package/dist/commands/new/templates.js

@@ -0,0 +1,355 @@
+/**
+ * The six files `loam new` scaffolds, and what each one says.
+ *
+ * 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
+ * teach the grammar `core/document/parse.ts` matches on, and the intent's
+ * frontmatter is serialized rather than interpolated because a title is free
+ * text somebody types — `Checkout: split payments` reopens the mapping and the
+ * 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("");
+    let id = base;
+    for (let n = 2; taken.has(id); n += 1)
+        id = `${base}${n}`;
+    taken.add(id);
+    return id;
+}
+/** `FEAT-101` -> `feat_101`: LikeC4 view names take no dashes. */
+function viewName(featureId) {
+    return featureId.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+}
+/* ------------------------------------------------------------------ */
+/* Templates                                                           */
+/* ------------------------------------------------------------------ */
+export function intentTemplate(featureId, title) {
+    const heading = title ?? featureId;
+    // The frontmatter is SERIALIZED, never interpolated. A title is free text a
+    // person types — `Checkout: split payments` used to be pasted straight after
+    // `title: `, where the colon reopens the mapping and the file stops parsing;
+    // `Orders #42 rework` lost everything from the `#` as a YAML comment, so the
+    // feature quietly answered to a title nobody wrote. The yaml serializer is the
+    // only thing that knows every case, and it is already how migrate-openspec
+    // writes the same three keys.
+    //
+    // `owner` is deliberately NOT a key here. Scaffolding `owner:` writes an
+    // 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.
+    const frontmatter = stringifyYaml({ feature: featureId, ...(title === undefined ? {} : { title }), status: "proposed" }, { lineWidth: 0 }).trimEnd();
+    return `---
+${frontmatter}
+# owner: <the team or person who answers for this>
+---
+
+# ${heading}
+
+## Why
+
+<!-- The problem in business terms. This is what a reviewer reads first, and what
+     the requirement deltas below have to be justified by. -->
+
+## Scope
+
+<!-- Which services this touches — and, more usefully, which it deliberately does not. -->
+`;
+}
+export function deltaTemplate(featureId, touched, created) {
+    const taken = new Set();
+    const touchedIds = touched.map((s) => [identifier(s, taken), s]);
+    const createdIds = created.map((s) => [identifier(s, taken), s]);
+    const lines = [];
+    if (touchedIds.length > 0) {
+        // Context elements ship COMMENTED OUT, exactly like the example edge below.
+        // Declared-and-untagged is the one shape `delta.nothing-tagged` exists to
+        // refuse (an author who forgot the tags), so writing these live made every
+        // `loam new --touches X` fail its own validator on the very first run —
+        // 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(`  // only #${featureId} is the change, and everything else here is context.`);
+        for (const [id, name] of touchedIds)
+            lines.push(`  // ${id} = softwareSystem '${name}'`);
+        lines.push("");
+    }
+    if (createdIds.length > 0) {
+        lines.push("  // Services this feature introduces. The tag is what `loam archive` folds");
+        lines.push("  // into the living landscape.");
+        for (const [id, name] of createdIds) {
+            lines.push(`  ${id} = softwareSystem '${name}' {`);
+            lines.push(`    #${featureId}`);
+            // Interpolated from sentinels.ts, never spelled here: the placeholder
+            // gate refuses this exact string at archive, and a second spelling is
+            // how a template rewording silently retires the check that guards it.
+            lines.push(`    description '${SERVICE_DESCRIPTION_SENTINEL}'`);
+            lines.push("  }");
+        }
+        lines.push("");
+    }
+    // The example edge uses identifiers already declared above when there are two
+    // to join; otherwise placeholders, so it never invents a service.
+    const from = touchedIds[0]?.[0] ?? createdIds[0]?.[0] ?? "consumer";
+    const to = createdIds[0]?.[0] ?? touchedIds[1]?.[0] ?? "provider";
+    lines.push("  // New calls. `metadata { op }` is the spine: it names the OpenAPI operationId");
+    lines.push("  // the call uses, and `loam validate` checks it against the target's contract.");
+    lines.push("  // Uncomment and adjust (both endpoints have to be declared above):");
+    lines.push("  //");
+    lines.push(`  // ${from} -> ${to} 'Calls createSplit' {`);
+    lines.push(`  //   #${featureId}`);
+    lines.push("  //   metadata { op 'createSplit' }");
+    lines.push("  // }");
+    return `// ${featureId} — architecture delta.
+//
+// Everything tagged #${featureId} is exactly what \`loam archive\` folds into
+// architecture/landscape.likec4. Everything else here is context for the diagram.
+//
+// If ${featureId} changes no architecture, DELETE this file: a requirements-only
+// feature is complete without it, and an empty \`model {}\` is just as legal.
+
+specification {
+  element softwareSystem
+  tag ${featureId}
+}
+
+model {
+${lines.join("\n")}
+}
+
+views {
+  view ${viewName(featureId)} {
+    include *
+  }
+}
+`;
+}
+/**
+ * The business axis, scaffolded with its example INSIDE the comment — the same
+ * mechanism as `archSpecTemplate` below, for the same reason: this template
+ * used to ship a live `### Requirement: TODO — name the behaviour` that
+ * parsed as a real requirement, validated clean, and archived a literal TODO
+ * into the living spec at exit 0. The indented headings sit past the
+ * line-anchored patterns core/document/parse.ts matches on, so the scaffold
+ * declares nothing until a person copies the block out and writes over the
+ * fill-ins — and `scaffold.placeholder` gates the archive if the fill-ins
+ * survive the copy.
+ *
+ * No nested HTML comments: the `Operations:` guidance that used to be its own
+ * comment lives in this one's prose, because an inner `-->` would end the
+ * outer comment early and re-expose the example to the parser.
+ */
+export function specTemplate(featureId, service) {
+    return `# ${service} — requirement delta for ${featureId}
+
+<!-- Sections: ADDED / MODIFIED / REMOVED. Delete the ones you do not need.
+     A MODIFIED requirement carries its full new text, not a diff.
+     Every requirement needs at least one scenario — \`loam validate\` gates on it.
+
+     An \`Operations:\` body line names the operationIds the requirement
+     governs. \`loam validate\` checks each one against the service's OpenAPI,
+     and \`loam archive\` refuses to merge a requirement that governs an
+     operation nobody defines — add the line once the contract exists.
+
+     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.
+
+     Copy the block below out of this comment, unindent it, and replace the
+     TODOs and every <angle-bracket> fill-in — \`loam archive\` refuses the
+     scaffold's own wording (\`scaffold.placeholder\`):
+
+    ## ADDED Requirements
+
+    ### Requirement: ${REQUIREMENT_SENTINEL}
+    Requirement-ID: ${featureId}.${service}.requirement
+
+    The service SHALL ${SHALL_SENTINEL}.
+
+    #### Scenario: ${SCENARIO_SENTINEL}
+    - **Given** ${GIVEN_SENTINEL}
+    - **When** ${WHEN_SENTINEL}
+    - **Then** ${THEN_SENTINEL}
+-->
+`;
+}
+/**
+ * The architecture axis, scaffolded EMPTY on purpose.
+ *
+ * Same grammar as spec.md, so the template body has to be unparseable as
+ * requirements or the scaffold would ship a requirement nobody wrote — the
+ * headings are therefore indented inside an HTML comment, which puts them past
+ * the line-anchored `## ADDED Requirements` / `### Requirement:` patterns
+ * core/document/parse.ts matches on. Copy the block out of the comment and unindent it.
+ */
+export function archSpecTemplate(featureId, service) {
+    return `# ${service} — architecture requirement delta for ${featureId}
+
+<!-- The architecture axis: the obligations no business scenario was ever going
+     to mention — the outbox, the retries, the timeouts, the alerts.
+
+     \`Covers:\` is to an arch requirement what \`Operations:\` is to a business
+     one — it names the MODEL OBJECTS the scenarios below exercise, so coverage
+     is derived instead of trusted. Three forms, comma-separated:
+
+       Covers: ${service}                 a C4 element — its id, or the service a
+                                          bound/titled element stands for
+       Covers: consumer -> ${service}     an edge, each side resolved the same way
+       Covers: alert:<id>, sli:<id>       a signal declared in health.yaml
+
+     Every tagged element and edge in delta.likec4 wants one (\`c4.uncovered\`).
+     Delete this file if ${featureId} adds no architectural obligation.
+
+     Copy the block below out of this comment and unindent it:
+
+    ## ADDED Requirements
+
+    ### Requirement: ${ARCH_REQUIREMENT_SENTINEL}
+    Requirement-ID: ${featureId}.${service}.arch
+
+    The service SHALL ${ARCH_SHALL_SENTINEL}.
+
+    Covers: ${service}
+
+    #### Scenario: ${SCENARIO_SENTINEL}
+    - **Given** ${GIVEN_SENTINEL}
+    - **When** ${WHEN_SENTINEL}
+    - **Then** ${THEN_SENTINEL}
+-->
+`;
+}
+/**
+ * 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:
+  title: ${service}
+  version: "0.1"
+
+# The operations this feature adds. \`operationId\` is the token the C4 edge
+# (metadata { op }) and the requirement (Operations:) both point at — keep the
+# three spellings identical or \`loam validate\` will say so.
+paths: {}
+#  /splits:
+#    post:
+#      operationId: createSplit
+#      responses:
+#        "201":
+#          description: Created
+`;
+}
+//# sourceMappingURL=templates.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/commands/new/templates.ts"],"names":[],"mappings":"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","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"]}

package/dist/commands/open.js

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

package/dist/commands/open.js.map

@@ -0,0 +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"]}