@ybotok/loam 0.0.0 → 0.1.0-beta.1

package/dist/commands/gherkin.js

@@ -0,0 +1,270 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { loadConfig } from "../core/config.js";
+import { decodeDocument, NotUtf8DocumentError } from "../core/fleet-context.js";
+import { emitJson, emitJsonError, fail, reportNoConfig } from "../core/json.js";
+import { featureSpecPaths, listFeatures, missingFeatureMessage, resolveFeature, servicePaths, SPEC_AXES, } from "../core/repo.js";
+import { parseRequirements } from "../core/spec.js";
+import { axisLabel, featureFilesUnder, gherkinRoot, parseStampedFeature, planEmission, } from "../core/gherkin.js";
+import { LOAM_VERSION } from "../core/version.js";
+import { resolveInside, UnsafePathError } from "../core/path-safety.js";
+export function registerGherkin(program) {
+    program
+        .command("gherkin")
+        .argument("[featureId]", "feature id — emit its ADDED/MODIFIED requirements; omit for the full living suite")
+        .description("Emit Gherkin .feature files from spec scenarios into this service repo's <gherkinDir>/loam/")
+        .option("--service <id>", "service to emit for (defaults to the configured service)")
+        .option("--dry-run", "print the plan (writes, replacements, deletions) and write nothing")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureArg, opts) => {
+        const json = opts.json === true;
+        const dryRun = opts.dryRun === true;
+        const config = await loadConfig();
+        if (!config) {
+            reportNoConfig(json);
+            return;
+        }
+        const service = opts.service ?? config.service;
+        if (service === undefined) {
+            return fail(json, "invalid-option", "No service. Pass --service <id> or set it in loam.json.");
+        }
+        // The emission writes into the repo loam is standing in, so it can only
+        // run where that repo is this service's — vouch's refusal, verbatim logic.
+        if (config.service !== service) {
+            const here = config.service === undefined ? "this is not a service repo" : `this repo is '${config.service}'`;
+            return fail(json, "invalid-option", `Cannot emit gherkin for '${service}' from here: ${here}. Generated .feature files land in the service's own repo — run it there.`);
+        }
+        // The repo root, not the cwd: `config.root` is the directory loam.json
+        // was actually found in, and config discovery walks upward. Taken from
+        // `process.cwd()` this emitted the whole suite into whatever directory
+        // the caller happened to stand in — `src/api/features/loam/…` inside the
+        // source tree, which the next run from the root neither finds, replaces
+        // nor deletes, and which `loam validate` grades as a suite that was never
+        // generated.
+        const repoDir = config.root ?? process.cwd();
+        let root;
+        try {
+            root = gherkinRoot(repoDir, config.gherkinDir);
+        }
+        catch (err) {
+            if (!(err instanceof UnsafePathError))
+                throw err;
+            return fail(json, "invalid-option", `Cannot emit Gherkin: ${err.message}. The output directory must stay inside the service repo.`);
+        }
+        const rel = (abs) => relative(repoDir, abs).split(/[\\/]/).join("/");
+        // The requirement set, by scope. Feature mode takes ADDED and MODIFIED —
+        // a BASE requirement is the living state quoted, a REMOVED one is being
+        // retired, and neither is behaviour anybody is about to test. Living mode
+        // takes everything the living files hold.
+        //
+        // Read through `decodeDocument`, not `readFile(…, "utf8")`, and refused
+        // rather than degraded: a spec.md saved as UTF-16 decodes to a document
+        // with no requirements in it, which here is not merely a wrong answer but
+        // a destructive one — an empty plan makes every existing .feature under
+        // loam/ an orphan, and a living run DELETES its orphans. The whole
+        // generated suite would go because a docs file was written by PowerShell.
+        let mode = "living";
+        let featureId;
+        const byAxis = [];
+        const readSpec = async (path) => parseRequirements(decodeDocument(await readFile(path), path));
+        try {
+            if (featureArg !== undefined) {
+                const feature = await resolveFeature(config.docsDir, featureArg, "exclude");
+                if (!feature) {
+                    return fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureArg));
+                }
+                mode = "feature";
+                featureId = feature.id;
+                const paths = featureSpecPaths(feature.dir, service);
+                for (const axis of SPEC_AXES) {
+                    const path = paths[axis.key];
+                    const reqs = existsSync(path)
+                        ? (await readSpec(path)).filter((r) => r.kind === "ADDED" || r.kind === "MODIFIED")
+                        : [];
+                    byAxis.push({ axis, reqs });
+                }
+            }
+            else {
+                const paths = servicePaths(config.docsDir, service);
+                if (!existsSync(paths.spec)) {
+                    return fail(json, "unknown-target", `No living spec at ${paths.spec}. Run \`loam adopt\` for '${service}' first.`);
+                }
+                for (const axis of SPEC_AXES) {
+                    const path = paths[axis.key];
+                    const reqs = existsSync(path) ? (await readSpec(path)).filter((r) => r.kind !== "REMOVED") : [];
+                    byAxis.push({ axis, reqs });
+                }
+            }
+        }
+        catch (err) {
+            if (!(err instanceof NotUtf8DocumentError))
+                throw err;
+            return fail(json, "repository-unavailable", `Cannot emit gherkin: ${err.message}`);
+        }
+        // `service` is not decoration: it salts every `@loam-digest-…` stamp, and
+        // it is the same string `loam verify` files the matching claims under.
+        const plan = planEmission(byAxis, { service, featureTag: featureId, version: LOAM_VERSION });
+        // Orphans of THIS scope, inside loam/ and nowhere else. Feature mode owns
+        // only its own emissions: stamped files carrying this feature's tag whose
+        // file is no longer in the plan (a requirement renamed or dropped).
+        // Living mode owns the whole suite — any .feature not in the plan goes —
+        // EXCEPT files tagged with a feature still in flight: those answer to
+        // their feature's delta until it archives, and `loam gherkin <FEAT>` is
+        // their regeneration.
+        const planned = new Set(plan.map((f) => f.fileName));
+        // Needed by BOTH modes now: living mode exempts in-flight files from
+        // deletion and replacement, and feature mode has to recognise another
+        // feature's in-flight file to refuse overwriting it.
+        const activeIds = new Set((await listFeatures(config.docsDir)).map((f) => f.id));
+        const orphans = [];
+        if (existsSync(root)) {
+            for (const abs of await featureFilesUnder(root)) {
+                if (planned.has(relative(root, abs).split(/[\\/]/).join("/")))
+                    continue;
+                const stamped = parseStampedFeature(await readFile(abs, "utf8"));
+                if (mode === "feature") {
+                    if (stamped !== null && stamped.tags.includes(featureId))
+                        orphans.push(abs);
+                }
+                else {
+                    if (stamped !== null && stamped.tags.some((t) => activeIds.has(t)))
+                        continue;
+                    orphans.push(abs);
+                }
+            }
+        }
+        const actions = [];
+        for (const f of plan) {
+            let path;
+            try {
+                // Check the final file as well as the owned root: a pre-planted
+                // `<slug>.feature` symlink must not turn writeFile into an overwrite
+                // outside the repository.
+                path = resolveInside(repoDir, relative(repoDir, join(root, f.fileName)), `gherkin file '${f.fileName}'`);
+            }
+            catch (err) {
+                if (!(err instanceof UnsafePathError))
+                    throw err;
+                return fail(json, "invalid-option", `Cannot emit Gherkin: ${err.message}.`);
+            }
+            if (!existsSync(path)) {
+                actions.push({ ...f, path, action: "written" });
+                continue;
+            }
+            const existing = parseStampedFeature(await readFile(path, "utf8"));
+            if (mode === "living") {
+                if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {
+                    actions.push({ ...f, path, action: "kept", kept: existing });
+                    continue;
+                }
+            }
+            else {
+                const owners = existing === null
+                    ? []
+                    : existing.tags.filter((t) => t !== featureId && activeIds.has(t));
+                if (owners.length > 0) {
+                    actions.push({ ...f, path, action: "conflict", kept: existing, owners });
+                    continue;
+                }
+            }
+            actions.push({ ...f, path, action: "replaced" });
+        }
+        // All or nothing: one conflicting file refuses the whole emission, so a
+        // half-written suite can never be the state an agent has to reason about.
+        const conflicts = actions.filter((a) => a.action === "conflict");
+        if (conflicts.length > 0) {
+            const detail = conflicts
+                .map((c) => `${rel(c.path)} is @${c.owners.join(" @")} (requirement '${c.requirement.name}')`)
+                .join("; ");
+            const message = `Cannot emit gherkin for ${featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +
+                `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \`loam verify --results\` matches on. ` +
+                `Archive (or abandon) the owning feature first, or rename the requirement in ${featureId}'s delta so the two stop sharing a file name.`;
+            if (json) {
+                emitJsonError("gherkin-conflict", message, {
+                    conflicts: conflicts.map((c) => ({
+                        path: rel(c.path),
+                        action: "conflict",
+                        requirement: c.requirement.name,
+                        inFlight: c.owners,
+                    })),
+                });
+                return;
+            }
+            return fail(json, "gherkin-conflict", message);
+        }
+        const writes = actions.filter((a) => a.action !== "kept");
+        if (!dryRun) {
+            // The root is created only when something lands in it: an emission with
+            // nothing to emit must not flip the repo into "opted in" — an empty
+            // loam/ tells `loam validate` the whole living suite is missing.
+            if (writes.length > 0)
+                await mkdir(root, { recursive: true });
+            for (const a of writes)
+                await writeFile(a.path, a.content, "utf8");
+            for (const o of orphans)
+                await unlink(o);
+        }
+        if (json) {
+            emitJson({
+                mode,
+                ...(featureId === undefined ? {} : { feature: featureId }),
+                service,
+                root: rel(root),
+                written: !dryRun,
+                files: actions.map((a) => ({
+                    path: rel(a.path),
+                    action: a.action,
+                    axis: axisLabel(a.axis),
+                    requirement: a.requirement.name,
+                    // A kept file's numbers describe what STAYS on disk (the in-flight
+                    // emission), not the emission that was withheld.
+                    scenarios: a.action === "kept" ? a.kept.scenarios.length : a.digests.length,
+                    digests: a.action === "kept" ? a.kept.scenarios.map((s) => s.digest) : a.digests,
+                    ...(a.action === "kept"
+                        ? { inFlight: a.kept.tags.filter((t) => activeIds.has(t)) }
+                        : { stepless: a.stepless }),
+                })),
+                deleted: orphans.map(rel),
+            });
+            return;
+        }
+        const head = mode === "feature" ? `${featureId} · ${service}` : `${service} (living suite)`;
+        console.log(`gherkin ${head} → ${rel(root)}/${dryRun ? "  (dry run)" : ""}\n`);
+        if (actions.length === 0) {
+            console.log(mode === "feature"
+                ? `  ${featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`
+                : `  the living specs hold no requirements for ${service} — nothing to emit.`);
+        }
+        // `conflict` never reaches here — the run refused above — but the map is
+        // total so a future action cannot silently print `undefined`.
+        const VERB = {
+            written: "write  ",
+            replaced: "replace",
+            kept: "keep   ",
+            conflict: "CONFLICT",
+        };
+        for (const a of actions) {
+            if (a.action === "kept") {
+                const owners = a.kept.tags.filter((t) => activeIds.has(t));
+                console.log(`  keep     ${a.fileName}  —  ${a.requirement.name}  (in flight: @${owners.join(" @")} — \`loam gherkin ${owners[0]}\` regenerates it)`);
+                continue;
+            }
+            const n = a.digests.length;
+            const arch = a.axis.key === "archSpec" ? ", arch" : "";
+            console.log(`  ${VERB[a.action]}  ${a.fileName}  —  ${a.requirement.name}  (${n} scenario${n === 1 ? "" : "s"}${arch})`);
+            for (const name of a.stepless) {
+                console.log(`      ⚠ scenario '${name}' has NO recognizable steps — cucumber runs it vacuously green and \`verify --results\` can never confirm it; reword its body as \`- **Given/When/Then**\` bullets`);
+            }
+        }
+        for (const o of orphans)
+            console.log(`  delete   ${relative(root, o).split(/[\\/]/).join("/")}  —  no longer in this scope`);
+        const wrote = `${writes.length} file(s)`;
+        const keptNote = actions.length > writes.length ? `, ${actions.length - writes.length} kept in flight` : "";
+        const dropped = orphans.length > 0 ? `, ${orphans.length} deletion(s)` : "";
+        console.log(dryRun
+            ? `\n  ${wrote}${keptNote}${dropped} — dry run, nothing was written.`
+            : `\n  ${wrote} written${keptNote}${dropped}. Write step definitions OUTSIDE ${rel(root)}/ — regeneration rewrites it.`);
+    });
+}
+//# sourceMappingURL=gherkin.js.map

package/dist/commands/gherkin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin.js","sourceRoot":"","sources":["../../src/commands/gherkin.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam gherkin` — the third writer in the CLI (after archive and vouch), and\n * the only one that writes into the SERVICE repo, never the docs repo: the\n * docs state what must be true, the tests live with the code that makes it so.\n *\n * Two scopes, one emitter. `loam gherkin <FEAT>` emits the feature's ADDED and\n * MODIFIED requirements for this service — both spec axes — as the acceptance\n * skeleton to implement against, each file tagged with the feature id.\n * `loam gherkin --service <id>` (no feature) emits the full living suite from\n * spec.md + arch.spec.md: the regression skeleton a legacy service gets at\n * adoption. Either way the output is `<gherkinDir>/loam/` inside this repo,\n * a directory loam owns outright: the scope's files are rewritten, the scope's\n * orphans are deleted (and reported), and nothing outside `loam/` is touched —\n * except that a living run neither deletes NOR overwrites a file tagged with a\n * feature still in flight: it answers to that feature's delta until it\n * archives, and is reported as kept. A FEATURE run cannot keep — the file it\n * wants holds one feature's delta — so when the file it would write belongs to\n * a different feature still in flight, the whole run refuses (`gherkin-conflict`)\n * and names the owner rather than reverting it.\n *\n * It refuses to run anywhere but the service's own repo — vouch's discipline,\n * for vouch's reason: the output lands in the repo loam is standing in, and\n * from anywhere else that repo is somebody else's.\n */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { mkdir, readFile, unlink, writeFile } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport { loadConfig } from \"../core/config.js\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../core/fleet-context.js\";\nimport { emitJson, emitJsonError, fail, reportNoConfig } from \"../core/json.js\";\nimport {\n  featureSpecPaths,\n  listFeatures,\n  missingFeatureMessage,\n  resolveFeature,\n  servicePaths,\n  SPEC_AXES,\n  type SpecAxis,\n} from \"../core/repo.js\";\nimport { parseRequirements, type Requirement } from \"../core/spec.js\";\nimport {\n  axisLabel,\n  featureFilesUnder,\n  gherkinRoot,\n  parseStampedFeature,\n  planEmission,\n  type PlannedFeature,\n  type StampedFeature,\n} from \"../core/gherkin.js\";\nimport { LOAM_VERSION } from \"../core/version.js\";\nimport { resolveInside, UnsafePathError } from \"../core/path-safety.js\";\n\ninterface GherkinOptions {\n  service?: string;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\nexport function registerGherkin(program: Command): void {\n  program\n    .command(\"gherkin\")\n    .argument(\"[featureId]\", \"feature id — emit its ADDED/MODIFIED requirements; omit for the full living suite\")\n    .description(\n      \"Emit Gherkin .feature files from spec scenarios into this service repo's <gherkinDir>/loam/\",\n    )\n    .option(\"--service <id>\", \"service to emit for (defaults to the configured service)\")\n    .option(\"--dry-run\", \"print the plan (writes, replacements, deletions) and write nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: GherkinOptions) => {\n      const json = opts.json === true;\n      const dryRun = opts.dryRun === true;\n\n      const config = await loadConfig();\n      if (!config) {\n        reportNoConfig(json);\n        return;\n      }\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", \"No service. Pass --service <id> or set it in loam.json.\");\n      }\n      // The emission writes into the repo loam is standing in, so it can only\n      // run where that repo is this service's — vouch's refusal, verbatim logic.\n      if (config.service !== service) {\n        const here =\n          config.service === undefined ? \"this is not a service repo\" : `this repo is '${config.service}'`;\n        return fail(\n          json,\n          \"invalid-option\",\n          `Cannot emit gherkin for '${service}' from here: ${here}. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n\n      // The repo root, not the cwd: `config.root` is the directory loam.json\n      // was actually found in, and config discovery walks upward. Taken from\n      // `process.cwd()` this emitted the whole suite into whatever directory\n      // the caller happened to stand in — `src/api/features/loam/…` inside the\n      // source tree, which the next run from the root neither finds, replaces\n      // nor deletes, and which `loam validate` grades as a suite that was never\n      // generated.\n      const repoDir = config.root ?? process.cwd();\n      let root: string;\n      try {\n        root = gherkinRoot(repoDir, config.gherkinDir);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(\n          json,\n          \"invalid-option\",\n          `Cannot emit Gherkin: ${err.message}. The output directory must stay inside the service repo.`,\n        );\n      }\n      const rel = (abs: string): string => relative(repoDir, abs).split(/[\\\\/]/).join(\"/\");\n\n      // The requirement set, by scope. Feature mode takes ADDED and MODIFIED —\n      // a BASE requirement is the living state quoted, a REMOVED one is being\n      // retired, and neither is behaviour anybody is about to test. Living mode\n      // takes everything the living files hold.\n      //\n      // Read through `decodeDocument`, not `readFile(…, \"utf8\")`, and refused\n      // rather than degraded: a spec.md saved as UTF-16 decodes to a document\n      // with no requirements in it, which here is not merely a wrong answer but\n      // a destructive one — an empty plan makes every existing .feature under\n      // loam/ an orphan, and a living run DELETES its orphans. The whole\n      // generated suite would go because a docs file was written by PowerShell.\n      let mode: \"feature\" | \"living\" = \"living\";\n      let featureId: string | undefined;\n      const byAxis: Array<{ axis: SpecAxis; reqs: Requirement[] }> = [];\n      const readSpec = async (path: string): Promise<Requirement[]> =>\n        parseRequirements(decodeDocument(await readFile(path), path));\n      try {\n        if (featureArg !== undefined) {\n          const feature = await resolveFeature(config.docsDir, featureArg, \"exclude\");\n          if (!feature) {\n            return fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg));\n          }\n          mode = \"feature\";\n          featureId = feature.id;\n          const paths = featureSpecPaths(feature.dir, service);\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path)\n              ? (await readSpec(path)).filter((r) => r.kind === \"ADDED\" || r.kind === \"MODIFIED\")\n              : [];\n            byAxis.push({ axis, reqs });\n          }\n        } else {\n          const paths = servicePaths(config.docsDir, service);\n          if (!existsSync(paths.spec)) {\n            return fail(\n              json,\n              \"unknown-target\",\n              `No living spec at ${paths.spec}. Run \\`loam adopt\\` for '${service}' first.`,\n            );\n          }\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path) ? (await readSpec(path)).filter((r) => r.kind !== \"REMOVED\") : [];\n            byAxis.push({ axis, reqs });\n          }\n        }\n      } catch (err) {\n        if (!(err instanceof NotUtf8DocumentError)) throw err;\n        return fail(json, \"repository-unavailable\", `Cannot emit gherkin: ${err.message}`);\n      }\n\n      // `service` is not decoration: it salts every `@loam-digest-…` stamp, and\n      // it is the same string `loam verify` files the matching claims under.\n      const plan = planEmission(byAxis, { service, featureTag: featureId, version: LOAM_VERSION });\n\n      // Orphans of THIS scope, inside loam/ and nowhere else. Feature mode owns\n      // only its own emissions: stamped files carrying this feature's tag whose\n      // file is no longer in the plan (a requirement renamed or dropped).\n      // Living mode owns the whole suite — any .feature not in the plan goes —\n      // EXCEPT files tagged with a feature still in flight: those answer to\n      // their feature's delta until it archives, and `loam gherkin <FEAT>` is\n      // their regeneration.\n      const planned = new Set(plan.map((f) => f.fileName));\n      // Needed by BOTH modes now: living mode exempts in-flight files from\n      // deletion and replacement, and feature mode has to recognise another\n      // feature's in-flight file to refuse overwriting it.\n      const activeIds = new Set((await listFeatures(config.docsDir)).map((f) => f.id));\n      const orphans: string[] = [];\n      if (existsSync(root)) {\n        for (const abs of await featureFilesUnder(root)) {\n          if (planned.has(relative(root, abs).split(/[\\\\/]/).join(\"/\"))) continue;\n          const stamped = parseStampedFeature(await readFile(abs, \"utf8\"));\n          if (mode === \"feature\") {\n            if (stamped !== null && stamped.tags.includes(featureId!)) orphans.push(abs);\n          } else {\n            if (stamped !== null && stamped.tags.some((t) => activeIds.has(t))) continue;\n            orphans.push(abs);\n          }\n        }\n      }\n\n      // The in-flight exemption guards the OVERWRITE path too, not only the\n      // orphan scan above: files are named by requirement slug in both modes,\n      // so a MODIFIED requirement's living emission always collides with the\n      // active feature's file — and replacing it reverted the delta's wording\n      // mid-flight, feature tag and new digest stamps destroyed, invisibly\n      // (the reverted file grades current against the living spec). A planned\n      // path whose existing content is stamped and tagged with a feature still\n      // in flight is KEPT and reported as such; it answers to its feature's\n      // delta until the feature archives, and then living regeneration\n      // replaces it normally.\n      //\n      // FEATURE mode has the same collision and cannot solve it by keeping:\n      // two features in flight against one requirement slug want the same\n      // file, and whichever runs second used to `replace` — silently reverting\n      // the other feature's wording, feature tag and digest stamps, so its\n      // `verify --results` could never confirm a scenario again. Nothing loam\n      // can write is right here (the file holds ONE feature's delta), so the\n      // run refuses and names the owner: the two features have to be sequenced,\n      // or the requirement renamed.\n      type Action = \"written\" | \"replaced\" | \"kept\" | \"conflict\";\n      const actions: Array<\n        PlannedFeature & { path: string; action: Action; kept?: StampedFeature; owners?: string[] }\n      > = [];\n      for (const f of plan) {\n        let path: string;\n        try {\n          // Check the final file as well as the owned root: a pre-planted\n          // `<slug>.feature` symlink must not turn writeFile into an overwrite\n          // outside the repository.\n          path = resolveInside(\n            repoDir,\n            relative(repoDir, join(root, f.fileName)),\n            `gherkin file '${f.fileName}'`,\n          );\n        } catch (err) {\n          if (!(err instanceof UnsafePathError)) throw err;\n          return fail(json, \"invalid-option\", `Cannot emit Gherkin: ${err.message}.`);\n        }\n        if (!existsSync(path)) {\n          actions.push({ ...f, path, action: \"written\" });\n          continue;\n        }\n        const existing = parseStampedFeature(await readFile(path, \"utf8\"));\n        if (mode === \"living\") {\n          if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {\n            actions.push({ ...f, path, action: \"kept\", kept: existing });\n            continue;\n          }\n        } else {\n          const owners =\n            existing === null\n              ? []\n              : existing.tags.filter((t) => t !== featureId && activeIds.has(t));\n          if (owners.length > 0) {\n            actions.push({ ...f, path, action: \"conflict\", kept: existing!, owners });\n            continue;\n          }\n        }\n        actions.push({ ...f, path, action: \"replaced\" });\n      }\n\n      // All or nothing: one conflicting file refuses the whole emission, so a\n      // half-written suite can never be the state an agent has to reason about.\n      const conflicts = actions.filter((a) => a.action === \"conflict\");\n      if (conflicts.length > 0) {\n        const detail = conflicts\n          .map((c) => `${rel(c.path)} is @${c.owners!.join(\" @\")} (requirement '${c.requirement.name}')`)\n          .join(\"; \");\n        const message =\n          `Cannot emit gherkin for ${featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +\n          `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \\`loam verify --results\\` matches on. ` +\n          `Archive (or abandon) the owning feature first, or rename the requirement in ${featureId}'s delta so the two stop sharing a file name.`;\n        if (json) {\n          emitJsonError(\"gherkin-conflict\", message, {\n            conflicts: conflicts.map((c) => ({\n              path: rel(c.path),\n              action: \"conflict\",\n              requirement: c.requirement.name,\n              inFlight: c.owners,\n            })),\n          });\n          return;\n        }\n        return fail(json, \"gherkin-conflict\", message);\n      }\n\n      const writes = actions.filter((a) => a.action !== \"kept\");\n\n      if (!dryRun) {\n        // The root is created only when something lands in it: an emission with\n        // nothing to emit must not flip the repo into \"opted in\" — an empty\n        // loam/ tells `loam validate` the whole living suite is missing.\n        if (writes.length > 0) await mkdir(root, { recursive: true });\n        for (const a of writes) await writeFile(a.path, a.content, \"utf8\");\n        for (const o of orphans) await unlink(o);\n      }\n\n      if (json) {\n        emitJson({\n          mode,\n          ...(featureId === undefined ? {} : { feature: featureId }),\n          service,\n          root: rel(root),\n          written: !dryRun,\n          files: actions.map((a) => ({\n            path: rel(a.path),\n            action: a.action,\n            axis: axisLabel(a.axis),\n            requirement: a.requirement.name,\n            // A kept file's numbers describe what STAYS on disk (the in-flight\n            // emission), not the emission that was withheld.\n            scenarios: a.action === \"kept\" ? a.kept!.scenarios.length : a.digests.length,\n            digests: a.action === \"kept\" ? a.kept!.scenarios.map((s) => s.digest) : a.digests,\n            ...(a.action === \"kept\"\n              ? { inFlight: a.kept!.tags.filter((t) => activeIds.has(t)) }\n              : { stepless: a.stepless }),\n          })),\n          deleted: orphans.map(rel),\n        });\n        return;\n      }\n\n      const head = mode === \"feature\" ? `${featureId} · ${service}` : `${service} (living suite)`;\n      console.log(`gherkin ${head} → ${rel(root)}/${dryRun ? \"  (dry run)\" : \"\"}\\n`);\n      if (actions.length === 0) {\n        console.log(\n          mode === \"feature\"\n            ? `  ${featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`\n            : `  the living specs hold no requirements for ${service} — nothing to emit.`,\n        );\n      }\n      // `conflict` never reaches here — the run refused above — but the map is\n      // total so a future action cannot silently print `undefined`.\n      const VERB: Record<Action, string> = {\n        written: \"write  \",\n        replaced: \"replace\",\n        kept: \"keep   \",\n        conflict: \"CONFLICT\",\n      };\n      for (const a of actions) {\n        if (a.action === \"kept\") {\n          const owners = a.kept!.tags.filter((t) => activeIds.has(t));\n          console.log(\n            `  keep     ${a.fileName}  —  ${a.requirement.name}  (in flight: @${owners.join(\" @\")} — \\`loam gherkin ${owners[0]}\\` regenerates it)`,\n          );\n          continue;\n        }\n        const n = a.digests.length;\n        const arch = a.axis.key === \"archSpec\" ? \", arch\" : \"\";\n        console.log(\n          `  ${VERB[a.action]}  ${a.fileName}  —  ${a.requirement.name}  (${n} scenario${n === 1 ? \"\" : \"s\"}${arch})`,\n        );\n        for (const name of a.stepless) {\n          console.log(\n            `      ⚠ scenario '${name}' has NO recognizable steps — cucumber runs it vacuously green and \\`verify --results\\` can never confirm it; reword its body as \\`- **Given/When/Then**\\` bullets`,\n          );\n        }\n      }\n      for (const o of orphans) console.log(`  delete   ${relative(root, o).split(/[\\\\/]/).join(\"/\")}  —  no longer in this scope`);\n      const wrote = `${writes.length} file(s)`;\n      const keptNote = actions.length > writes.length ? `, ${actions.length - writes.length} kept in flight` : \"\";\n      const dropped = orphans.length > 0 ? `, ${orphans.length} deletion(s)` : \"\";\n      console.log(\n        dryRun\n          ? `\\n  ${wrote}${keptNote}${dropped} — dry run, nothing was written.`\n          : `\\n  ${wrote} written${keptNote}${dropped}. Write step definitions OUTSIDE ${rel(root)}/ — regeneration rewrites it.`,\n      );\n    });\n}\n"]}

package/dist/commands/init.js

@@ -0,0 +1,250 @@
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CONFIG_FILENAME, findConfigPath, loadConfig, localConfigPath, saveConfig, } from "../core/config.js";
+import { emitJson, fail } from "../core/json.js";
+import { plannedDocsFiles, scaffoldDocs } from "../core/docs.js";
+import { docsRepoState, listServices } from "../core/repo.js";
+import { InvalidIdError, assertServiceId } from "../core/ids.js";
+import { AGENT_TOOLS, detectAgentTools, plannedCommandFiles, scaffoldAgentCommands, } from "../core/agent.js";
+/**
+ * Resolve --tools to registry ids, or null after reporting the refusal. The
+ * default (the cwd scan) lives at the call site, not in commander, so an
+ * explicit `--tools` is distinguishable from none — which is what lets both the
+ * autodetection fallback and the `--no-*` contradiction be decided instead of
+ * silently arbitrated.
+ */
+function resolveTools(raw, json) {
+    const supported = Object.keys(AGENT_TOOLS);
+    if (raw === "all")
+        return supported;
+    const ids = [...new Set(raw.split(",").map((t) => t.trim()).filter((t) => t !== ""))];
+    const unknown = ids.filter((t) => !(t in AGENT_TOOLS));
+    if (ids.length === 0 || unknown.length > 0) {
+        fail(json, "invalid-option", (ids.length === 0
+            ? "--tools names no tool."
+            : `--tools does not recognize: ${unknown.join(", ")}.`) +
+            ` Supported: ${supported.join(", ")} — or "all".`);
+        return null;
+    }
+    return ids;
+}
+/**
+ * `--docs` exactly as the caller wrote it, with separators normalised.
+ *
+ * Stored verbatim on purpose. `init` used to resolve it and write the absolute
+ * result, which meant a committed loam.json named a directory that existed on
+ * one laptop: every teammate who cloned the service repo got a docsDir under
+ * someone else's home directory, and `loam list` reported an empty fleet
+ * instead of saying so. `loadConfig` resolves relative paths against the config
+ * file's own directory, so `../docs` keeps meaning "next to this repo" wherever
+ * the pair is checked out. An absolute `--docs` is still stored absolute — that
+ * is the caller's explicit choice, and `loam doctor` warns about it.
+ *
+ * Backslashes become forward slashes so a config written on Windows resolves on
+ * POSIX; a trailing separator is dropped so the stored spelling is stable.
+ */
+function storedDocsDir(raw) {
+    const slashed = raw.split("\\").join("/");
+    if (slashed.length <= 1)
+        return slashed;
+    const trimmed = slashed.replace(/\/+$/, "");
+    return trimmed === "" ? "/" : trimmed;
+}
+/**
+ * Does this directory already hold a docs repo? `services/` plus `AGENTS.md` —
+ * the two things every docs repo has and no service repo does. The pair is the
+ * whole point: a single marker would make `init --docs ../srv` (a typo for
+ * `../docs`) look like a join and adopt the service repo as the fleet.
+ */
+function isDocsRepo(dir) {
+    return docsRepoState(dir).kind === "ok" && existsSync(join(dir, "AGENTS.md"));
+}
+export function registerInit(program) {
+    program
+        .command("init")
+        .description("Initialize loam: create/point at the shared docs repo and write local config")
+        .option("--docs <dir>", "path to the shared docs repo (the source of truth)", ".loam-docs")
+        .option("--service <id>", "canonical id of the service in this repo")
+        .option("--create", "create a new docs repo at --docs instead of joining an existing one")
+        .option("--force", `write ${CONFIG_FILENAME} here even though one governs a parent directory`)
+        .option("--tools <ids>", "agent tools to generate for, overriding the scan of this directory: " +
+        `comma-separated (${Object.keys(AGENT_TOOLS).join(", ")}) or "all"`)
+        .option("--no-commands", "skip the slash commands for this repo entirely")
+        .option("--no-skills", "skip the agent skills for this repo entirely")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (opts, command) => {
+        const json = opts.json === true;
+        const cwd = process.cwd();
+        // The id becomes services/<id>/ in the shared repo, so it is validated
+        // before anything is written — by the same rule adopt, vouch and gherkin
+        // use, never by a guard invented here.
+        if (opts.service !== undefined) {
+            try {
+                assertServiceId(opts.service);
+            }
+            catch (err) {
+                if (!(err instanceof InvalidIdError))
+                    throw err;
+                fail(json, "invalid-option", err.message);
+                return;
+            }
+        }
+        // A loam.json in an ancestor already governs this directory: every command
+        // run from here resolves to it. Writing a second one below it would shadow
+        // the first for this subtree only — the kind of split-brain nobody
+        // discovers until two commands disagree about which docs repo is the fleet.
+        const governing = findConfigPath(cwd);
+        if (governing !== null && governing !== localConfigPath(cwd) && opts.force !== true) {
+            fail(json, "already-exists", `${governing} already governs this directory. ` +
+                `Run loam from ${resolve(governing, "..")}, or pass --force to give this ` +
+                `subdirectory its own ${CONFIG_FILENAME}.`);
+            return;
+        }
+        // Only THIS directory's config is spread forward. Under --force there is
+        // a config in an ancestor too, and inheriting its `service` would bind
+        // this repo to a service somebody else's repo declared.
+        const existing = existsSync(localConfigPath(cwd)) ? await loadConfig(cwd) : null;
+        // A re-run must not move a committed pointer. `--docs` has a default
+        // (`.loam-docs`), so an init invoked for any OTHER reason — `--service`,
+        // a new `--tools`, the fix `doctor.agent-files-missing` prints — used to
+        // arrive here carrying a docsDir nobody typed: the default then named no
+        // docs repo, the refusal steered the caller to `--create`, and `--create`
+        // rewrote `docsDir` in the committed loam.json to a freshly scaffolded
+        // empty one. `validate --all` went green over an empty fleet, which is
+        // the exact outcome `--create` exists to prevent. So the flag wins only
+        // when it was actually passed; otherwise the file this repo already
+        // committed does.
+        const committedDocs = existing?.docsDirAsWritten;
+        const docsTyped = command.getOptionValueSource("docs") !== "default";
+        const docsSource = docsTyped ? "flag" : committedDocs === undefined ? "default" : "config";
+        const docsOption = !docsTyped && committedDocs !== undefined ? committedDocs : opts.docs;
+        const docsDir = resolve(cwd, docsOption);
+        // The one predictable failure: --docs naming a file. Refused here so the
+        // caller gets a clean envelope/message instead of mkdir's ENOTDIR throw.
+        if (existsSync(docsDir) && !statSync(docsDir).isDirectory()) {
+            fail(json, "invalid-option", `--docs points at a file, not a directory: ${docsDir}`);
+            return;
+        }
+        // Joining an existing docs repo and creating a new one are different
+        // intentions, and `init` used to perform the second one whenever the first
+        // was misspelled: `--docs ../dcos` scaffolded a second, empty docs repo
+        // beside the real one, and the fleet quietly split in two. Creation is now
+        // something the caller asks for.
+        const joining = isDocsRepo(docsDir);
+        if (!joining && opts.create !== true) {
+            fail(json, "invalid-option", docsRepoState(docsDir).kind === "missing"
+                ? `--docs points at a directory that does not exist: ${docsDir}. ` +
+                    "If that is a typo, fix it; to create a new docs repo there, pass --create."
+                : `--docs points at ${docsDir}, which is not a docs repo ` +
+                    "(a docs repo has services/ and AGENTS.md). " +
+                    "Point --docs at the shared docs repo, or pass --create to make a new one here.");
+            return;
+        }
+        // --tools selects the files to write; --no-commands and --no-skills each
+        // say write none of that kind. Together they contradict — refused, not
+        // arbitrated, in either combination.
+        const suppressed = [
+            ...(opts.commands ? [] : ["--no-commands"]),
+            ...(opts.skills ? [] : ["--no-skills"]),
+        ];
+        if (opts.tools !== undefined && suppressed.length > 0) {
+            fail(json, "invalid-option", `--tools contradicts ${suppressed.join(" and ")}: ` +
+                "one selects the files to generate, the other suppresses them.");
+            return;
+        }
+        const delivery = [
+            ...(opts.commands ? ["commands"] : []),
+            ...(opts.skills ? ["skills"] : []),
+        ];
+        // Without --tools the repo decides: whichever tools have left their own
+        // dot-directories here. Falling back to claude keeps a bare repo behaving
+        // exactly as it did before the scan existed. `detected` is reported either
+        // way — what the scan saw is a fact about the repo, not about the flags.
+        const detected = detectAgentTools(cwd);
+        const scanned = detected.length > 0 ? detected : ["claude"];
+        const tools = opts.tools === undefined ? scanned : resolveTools(opts.tools, json);
+        if (tools === null)
+            return;
+        // `skipped` is the other half of the never-overwrite contract: the
+        // scaffolds return only what they created, so what they left alone is
+        // probed here, before they run — in the order they would create it, so
+        // created + skipped is the same list on every repo. Both halves come from
+        // the scaffolds' own planned-file lists, so the probe cannot drift from
+        // what is actually written.
+        const agentFiles = delivery.length > 0 ? plannedCommandFiles(cwd, tools, delivery) : [];
+        const candidates = [...plannedDocsFiles(docsDir), ...agentFiles.map((f) => f.path)];
+        const skipped = candidates.filter((p) => existsSync(p));
+        // Joining touches the docs repo not at all: it is somebody's committed
+        // repository, and "point at it" must never mean "write to it".
+        const created = joining && opts.create !== true ? [] : (await scaffoldDocs(docsDir)).created;
+        const generatedFor = delivery.length > 0 ? tools : [];
+        if (delivery.length > 0) {
+            created.push(...(await scaffoldAgentCommands(cwd, tools, delivery)));
+        }
+        const stored = storedDocsDir(docsOption);
+        // Union, not replacement: this run's files join the ones earlier runs left
+        // on disk, and `agentTools` is a record of what the repo HOLDS. A run that
+        // generated nothing adds nothing and erases nothing.
+        const recordedTools = [...new Set([...(existing?.agentTools ?? []), ...generatedFor])];
+        const config = {
+            ...existing,
+            docsDir: stored,
+            ...(opts.service ? { service: opts.service } : {}),
+            ...(recordedTools.length > 0 ? { agentTools: recordedTools } : {}),
+        };
+        const configFile = await saveConfig(config, cwd);
+        const serviceCount = (await listServices(docsDir)).length;
+        if (json) {
+            // `docsDir` stays the resolved absolute path — it is what a consumer
+            // needs to find the repo. `docsDirStored` is what was written to
+            // loam.json, which is the fact this command is now careful about.
+            // `tools` names what files were generated FOR — empty when every
+            // delivery was suppressed and none were. `detected` is the separate
+            // question of what the scan SAW, which `--tools` overrides without
+            // changing: an agent comparing the two learns whether its selection
+            // matches the repo.
+            emitJson({
+                docsDir,
+                docsDirStored: stored,
+                // Where the pointer came from: `flag` (a --docs somebody typed),
+                // `config` (the one this repo already committed — a re-run cannot
+                // move it), or `default` (nothing said, nothing committed).
+                docsDirSource: docsSource,
+                docsRepo: joining ? "existing" : "created",
+                services: serviceCount,
+                created,
+                skipped,
+                tools: generatedFor,
+                detected,
+            });
+            return;
+        }
+        console.log("loam initialized.");
+        if (joining) {
+            console.log(`  docs repo: ${docsDir}`);
+            console.log(`             pointing at existing docs repo (${serviceCount} services)`);
+        }
+        else {
+            console.log(`  docs repo: ${docsDir}  (created)`);
+        }
+        console.log(`  docsDir:   ${stored}  (as stored in ${CONFIG_FILENAME}`
+            + (docsSource === "config" ? " — kept; no --docs was passed" : "") + ")");
+        if (config.service)
+            console.log(`  service:   ${config.service}`);
+        console.log(`  config:    ${configFile}`);
+        console.log(`             commit ${CONFIG_FILENAME} — docsDir is resolved relative to it`);
+        if (opts.tools === undefined && detected.length > 0) {
+            console.log(`  detected:  ${detected.join(", ")}`);
+        }
+        if (opts.commands)
+            console.log(`  commands:  ${tools.join(", ")}`);
+        if (opts.skills)
+            console.log(`  skills:    ${tools.join(", ")}`);
+        if (created.length > 0) {
+            console.log("  scaffolded:");
+            for (const c of created)
+                console.log(`    + ${c}`);
+        }
+    });
+}
+//# sourceMappingURL=init.js.map