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

package/dist/commands/gherkin/commit.js

@@ -0,0 +1,146 @@
+/**
+ * The emission's commit window: lock the owned root, recover a predecessor,
+ * stage every write and delete, prove the tree still matches what reconcile
+ * graded, and land it through the journaled transaction.
+ *
+ * Split from gherkin.ts so the lock's extent is visible in the code shape,
+ * exactly as vouch's commitStamp is — and because this is the writer the
+ * roadmap named: a kill inside the old write/delete loop left a half-old,
+ * half-new suite with no marker, in the one repo (the service's own) where
+ * nothing else of loam's ever looked.
+ */
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { quietRmdir, rollbackStaged, stageWrites } from "../../core/staging/commit.js";
+import { COMMIT_INTENT, InterruptedCommitError } from "../../core/staging/interrupted.js";
+import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import {} from "../../core/staging/writes.js";
+import {} from "./reconcile.js";
+/**
+ * Roll a predecessor's interrupted emission forward before ANYTHING reads the
+ * suite — reconcile grades the very bytes a half-commit corrupts. Cheap when
+ * there is nothing to do: no journal, no lock, no I/O beyond one existsSync.
+ */
+export async function recoverEmissionRoot(root) {
+    if (!existsSync(join(root, COMMIT_INTENT)))
+        return { ok: true, recovered: null };
+    let release;
+    try {
+        release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);
+    }
+    catch (err) {
+        if (err instanceof DocsBusyError)
+            return { ok: false, code: "docs-busy", message: err.message };
+        throw err;
+    }
+    try {
+        return { ok: true, recovered: await recoverInterruptedCommit(root) };
+    }
+    catch (err) {
+        if (err instanceof InterruptedCommitError)
+            return { ok: false, code: "commit-interrupted", message: err.message };
+        throw err;
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * Stage, compare, journal, swap. The compare is against the bytes RECONCILE
+ * read: a `.feature` that changed (or appeared) between the grading and this
+ * commit is refused by name, never buried — the suite is code somebody may be
+ * editing, and "refused, not buried" is the no-clobber rule the roadmap
+ * spells for exactly this writer.
+ */
+export async function commitEmission(spec, plan) {
+    const { root, service, scope } = spec;
+    // The lock file lives in the root, so the root must exist first. If the
+    // commit then fails having created it, the empty directory is removed
+    // again — an empty loam/ flips the repo into "opted in" and tells
+    // `loam validate` the whole living suite is missing.
+    const rootExisted = existsSync(root);
+    await mkdir(root, { recursive: true });
+    let release;
+    try {
+        release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);
+    }
+    catch (err) {
+        if (!rootExisted)
+            await quietRmdir(root);
+        if (err instanceof DocsBusyError)
+            return { ok: false, code: "docs-busy", message: err.message };
+        throw err;
+    }
+    try {
+        // A writer can have crashed between the command-start recovery and this
+        // window; the re-check is one existsSync when nothing happened.
+        let recovered;
+        try {
+            recovered = await recoverInterruptedCommit(root);
+        }
+        catch (err) {
+            if (err instanceof InterruptedCommitError)
+                return { ok: false, code: "commit-interrupted", message: err.message };
+            throw err;
+        }
+        const planned = [
+            // A "written" row was graded against an ABSENT file, so its create is
+            // exclusive: a file appearing after planning loses the link(2) race and
+            // the run refuses rather than overwriting it.
+            ...plan.writes.map((a) => a.action === "written" ? { path: a.path, content: a.content, exclusive: true } : { path: a.path, content: a.content }),
+            ...plan.orphans.map((o) => ({ path: o.path, content: null })),
+        ];
+        const staged = await stageWrites(planned);
+        // The bytes reconcile graded must be the bytes this commit replaces or
+        // deletes. `swapStaged` re-checks against ITS read just before each
+        // rename; this compare closes the other half of the window, from the
+        // grading to the staging.
+        const graded = new Map();
+        for (const a of plan.writes)
+            if (a.action === "replaced")
+                graded.set(a.path, a.raw);
+        for (const o of plan.orphans)
+            graded.set(o.path, o.raw);
+        const moved = staged
+            .filter((s) => {
+            const raw = graded.get(s.write.path);
+            return raw !== undefined && (s.before === null || !s.before.equals(raw));
+        })
+            .map((s) => s.write.path);
+        if (moved.length > 0) {
+            await rollbackStaged(staged);
+            return {
+                ok: false,
+                code: "merge-failed",
+                message: `the suite changed while this emission was being planned — ${moved.join(", ")} ` +
+                    `no longer holds the bytes the plan was graded against. Nothing was written: re-run.`,
+            };
+        }
+        const committed = await commitStaged({
+            root,
+            command: "gherkin",
+            rerun: scope.mode === "feature" ? `loam gherkin ${scope.featureId}` : "loam gherkin",
+            target: service,
+        }, staged, "emitted");
+        if (!committed.ok) {
+            return committed.raced
+                ? {
+                    ok: false,
+                    code: "merge-failed",
+                    message: "a .feature file appeared after planning and the emission refused to overwrite it — " +
+                        `${committed.message}. Nothing else was written: re-run to grade the new file.`,
+                }
+                : { ok: false, code: committed.code, message: committed.message };
+        }
+        return { ok: true, recovered };
+    }
+    finally {
+        await release();
+        if (!rootExisted && !existsSync(join(root, COMMIT_INTENT)))
+            await quietRmdir(root);
+    }
+}
+//# sourceMappingURL=commit.js.map

package/dist/commands/gherkin/commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/commands/gherkin/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The emission's commit window: lock the owned root, recover a predecessor,\n * stage every write and delete, prove the tree still matches what reconcile\n * graded, and land it through the journaled transaction.\n *\n * Split from gherkin.ts so the lock's extent is visible in the code shape,\n * exactly as vouch's commitStamp is — and because this is the writer the\n * roadmap named: a kill inside the old write/delete loop left a half-old,\n * half-new suite with no marker, in the one repo (the service's own) where\n * nothing else of loam's ever looked.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { quietRmdir, rollbackStaged, stageWrites } from \"../../core/staging/commit.js\";\nimport { COMMIT_INTENT, type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { type ActionRow, type Scope } from \"./reconcile.js\";\n\nexport type EmissionCommit =\n  | { ok: true; recovered: CommitRecovery | null }\n  | { ok: false; code: \"docs-busy\" | \"commit-interrupted\" | \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * Roll a predecessor's interrupted emission forward before ANYTHING reads the\n * suite — reconcile grades the very bytes a half-commit corrupts. Cheap when\n * there is nothing to do: no journal, no lock, no I/O beyond one existsSync.\n */\nexport async function recoverEmissionRoot(root: string): Promise<EmissionCommit> {\n  if (!existsSync(join(root, COMMIT_INTENT))) return { ok: true, recovered: null };\n  let release: () => Promise<void>;\n  try {\n    release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);\n  } catch (err) {\n    if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n    throw err;\n  }\n  try {\n    return { ok: true, recovered: await recoverInterruptedCommit(root) };\n  } catch (err) {\n    if (err instanceof InterruptedCommitError) return { ok: false, code: \"commit-interrupted\", message: err.message };\n    throw err;\n  } finally {\n    await release();\n  }\n}\n\n/**\n * Stage, compare, journal, swap. The compare is against the bytes RECONCILE\n * read: a `.feature` that changed (or appeared) between the grading and this\n * commit is refused by name, never buried — the suite is code somebody may be\n * editing, and \"refused, not buried\" is the no-clobber rule the roadmap\n * spells for exactly this writer.\n */\nexport async function commitEmission(\n  spec: { root: string; service: string; scope: Scope },\n  plan: { writes: ActionRow[]; orphans: { path: string; raw: Buffer }[] },\n): Promise<EmissionCommit> {\n  const { root, service, scope } = spec;\n  // The lock file lives in the root, so the root must exist first. If the\n  // commit then fails having created it, the empty directory is removed\n  // again — an empty loam/ flips the repo into \"opted in\" and tells\n  // `loam validate` the whole living suite is missing.\n  const rootExisted = existsSync(root);\n  await mkdir(root, { recursive: true });\n  let release: () => Promise<void>;\n  try {\n    release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);\n  } catch (err) {\n    if (!rootExisted) await quietRmdir(root);\n    if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n    throw err;\n  }\n  try {\n    // A writer can have crashed between the command-start recovery and this\n    // window; the re-check is one existsSync when nothing happened.\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(root);\n    } catch (err) {\n      if (err instanceof InterruptedCommitError) return { ok: false, code: \"commit-interrupted\", message: err.message };\n      throw err;\n    }\n\n    const planned: PlannedWrite[] = [\n      // A \"written\" row was graded against an ABSENT file, so its create is\n      // exclusive: a file appearing after planning loses the link(2) race and\n      // the run refuses rather than overwriting it.\n      ...plan.writes.map((a): PlannedWrite =>\n        a.action === \"written\" ? { path: a.path, content: a.content, exclusive: true } : { path: a.path, content: a.content },\n      ),\n      ...plan.orphans.map((o): PlannedWrite => ({ path: o.path, content: null })),\n    ];\n    const staged = await stageWrites(planned);\n\n    // The bytes reconcile graded must be the bytes this commit replaces or\n    // deletes. `swapStaged` re-checks against ITS read just before each\n    // rename; this compare closes the other half of the window, from the\n    // grading to the staging.\n    const graded = new Map<string, Buffer>();\n    for (const a of plan.writes) if (a.action === \"replaced\") graded.set(a.path, a.raw);\n    for (const o of plan.orphans) graded.set(o.path, o.raw);\n    const moved = staged\n      .filter((s) => {\n        const raw = graded.get(s.write.path);\n        return raw !== undefined && (s.before === null || !s.before.equals(raw));\n      })\n      .map((s) => s.write.path);\n    if (moved.length > 0) {\n      await rollbackStaged(staged);\n      return {\n        ok: false,\n        code: \"merge-failed\",\n        message:\n          `the suite changed while this emission was being planned — ${moved.join(\", \")} ` +\n          `no longer holds the bytes the plan was graded against. Nothing was written: re-run.`,\n      };\n    }\n\n    const committed = await commitStaged(\n      {\n        root,\n        command: \"gherkin\",\n        rerun: scope.mode === \"feature\" ? `loam gherkin ${scope.featureId}` : \"loam gherkin\",\n        target: service,\n      },\n      staged,\n      \"emitted\",\n    );\n    if (!committed.ok) {\n      return committed.raced\n        ? {\n            ok: false,\n            code: \"merge-failed\",\n            message:\n              \"a .feature file appeared after planning and the emission refused to overwrite it — \" +\n              `${committed.message}. Nothing else was written: re-run to grade the new file.`,\n          }\n        : { ok: false, code: committed.code, message: committed.message };\n    }\n    return { ok: true, recovered };\n  } finally {\n    await release();\n    if (!rootExisted && !existsSync(join(root, COMMIT_INTENT))) await quietRmdir(root);\n  }\n}\n\n"]}

package/dist/commands/gherkin/gherkin.js

@@ -0,0 +1,246 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { loadConfig } from "../../core/envelope/config.js";
+import { decodeDocument, NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { emitJson, emitJsonError, fail, NO_SERVICE_MESSAGE, reportNoConfig, } from "../../core/envelope/json.js";
+import { featureSpecPaths, SPEC_AXES } from "../../core/repo/paths.js";
+import { locateServicePaths } from "../../core/repo/service-target.js";
+import { listFeatures, missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
+import { parseRequirements } from "../../core/document/parse.js";
+import {} from "../../core/document/spec.js";
+import { axisLabel, planEmission } from "../../core/gherkin/emit.js";
+import { gherkinRoot } from "../../core/gherkin/stamp.js";
+import { LOAM_VERSION } from "../../core/envelope/version.js";
+import { UnsafePathError } from "../../core/kernel/path-safety.js";
+import { commitEmission, recoverEmissionRoot } from "./commit.js";
+import { reconcile } from "./reconcile.js";
+import { render } from "./render.js";
+import { sayRecovered } from "../policy/format.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 — beyond first finishing a predecessor's interrupted commit, exactly as a real run would")
+        .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 loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const config = loaded.config;
+        const service = opts.service ?? config.service;
+        if (service === undefined) {
+            return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
+        }
+        // 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.
+        //
+        // TWO conditions, two codes, and the split is the whole point. Both used
+        // to answer `invalid-option`, whose `loam explain` row says the
+        // invocation itself is wrong — contradictory flags, a mistyped one, a
+        // value that cannot be right. Here the invocation is perfectly correct
+        // and the REPOSITORY is the wrong one, so that code sent a user whose
+        // flags were fine off to re-read their flags, and left CI and agents
+        // unable to tell "run this in the service repo" from "you typed the flag
+        // wrong". `loam verify --record --service` already draws exactly this
+        // line for exactly this reason (see commands/verify/verify.ts); gherkin
+        // and vouch now answer the same pair, so a caller branching on
+        // `error.code` gets one answer from all three. The messages are
+        // unchanged — only the code moved.
+        if (config.service === undefined) {
+            return fail(json, "repository-unavailable", `Cannot emit gherkin for '${service}' from here: this is not a service repo. Generated .feature files land in the service's own repo — run it there.`);
+        }
+        if (config.service !== service) {
+            return fail(json, "service-mismatch", `Cannot emit gherkin for '${service}' from here: this repo is '${config.service}'. 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("/");
+        // A predecessor's interrupted emission is rolled forward before ANY
+        // read — and before the feature argument resolves: reconcile grades the
+        // very bytes a half-commit corrupts, and the journal's stored rerun may
+        // name a feature that has since ARCHIVED, whose recovery must still
+        // work. `new` fixed the same ordering and documented it; refusing
+        // unknown-target over a wedged root left doctor printing a repair that
+        // could never run.
+        const early = await recoverEmissionRoot(root);
+        if (!early.ok)
+            return fail(json, early.code, early.message);
+        let recovered = early.recovered;
+        const feature = featureArg === undefined ? null : await resolveFeature(config.docsDir, featureArg, "exclude");
+        if (featureArg !== undefined && feature === null) {
+            return fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureArg));
+        }
+        const scope = feature === null ? { mode: "living" } : { mode: "feature", featureId: feature.id };
+        // 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.
+        const byAxis = [];
+        const readSpec = async (path) => parseRequirements(decodeDocument(await readFile(path), path));
+        try {
+            if (feature !== null) {
+                // `config.service`, not `service`: the guard above proved they are
+                // the same id, and only the config's copy carries the load-time
+                // parse, so it is the pathable spelling — same as the else arm.
+                const paths = featureSpecPaths(feature.dir, config.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 {
+                // The guard above proved `service` IS `config.service`; only the
+                // latter carries the load-time parse, so it is the pathable spelling.
+                const paths = await locateServicePaths(config.docsDir, config.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: scope.mode === "feature" ? scope.featureId : undefined,
+            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).
+        // `Set<string>`, not the ids' own brand: this set answers membership
+        // questions for tags read out of .feature files — document text.
+        const activeIds = new Set((await listFeatures(config.docsDir)).map((f) => f.id));
+        let reconciled;
+        try {
+            reconciled = await reconcile(plan, { root, repoDir }, scope, activeIds);
+        }
+        catch (err) {
+            if (!(err instanceof UnsafePathError))
+                throw err;
+            return fail(json, "invalid-option", `Cannot emit Gherkin: ${err.message}.`);
+        }
+        const { actions, orphans, conflicts } = reconciled;
+        // 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.
+        // Only a feature run can conflict — living mode keeps the in-flight file
+        // rather than refusing — and standing inside that scope is also how the
+        // message names the feature without asserting there is one.
+        if (scope.mode === "feature" && 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 ${scope.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 ${scope.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 && (writes.length > 0 || orphans.length > 0)) {
+            // The commit window: locked, journaled, compared against the bytes
+            // reconcile graded. A zero-op run takes no lock and creates no root —
+            // an emission with nothing to emit must not flip the repo into
+            // "opted in", where an empty loam/ tells `loam validate` the whole
+            // living suite is missing.
+            const committed = await commitEmission({ root, service, scope }, { writes, orphans });
+            if (!committed.ok)
+                return fail(json, committed.code, committed.message);
+            recovered = committed.recovered ?? recovered;
+        }
+        if (json) {
+            emitJson({
+                command: "gherkin",
+                mode: scope.mode,
+                ...(scope.mode === "feature" ? { feature: scope.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,
+                            malformedExamples: a.malformedExamples,
+                            strandedBlocks: a.strandedBlocks,
+                        }),
+                })),
+                deleted: orphans.map((o) => rel(o.path)),
+                ...(recovered === null ? {} : { recovered }),
+            });
+            return;
+        }
+        if (recovered !== null)
+            console.log(`${sayRecovered(recovered)}\n`);
+        render(actions, {
+            service,
+            root: rel(root),
+            absRoot: root,
+            featureId: scope.mode === "feature" ? scope.featureId : null,
+            dryRun,
+            activeIds,
+            writes: writes.length,
+            orphans: orphans.map((o) => o.path),
+        });
+    });
+}
+//# sourceMappingURL=gherkin.js.map

package/dist/commands/gherkin/gherkin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin.js","sourceRoot":"","sources":["../../../src/commands/gherkin/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 { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport {\n  emitJson,\n  emitJsonError,\n  fail,\n  NO_SERVICE_MESSAGE,\n  reportNoConfig,\n} from \"../../core/envelope/json.js\";\nimport { featureSpecPaths, SPEC_AXES, type SpecAxis } from \"../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { listFeatures, missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { parseRequirements } from \"../../core/document/parse.js\";\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { axisLabel, planEmission } from \"../../core/gherkin/emit.js\";\nimport { gherkinRoot } from \"../../core/gherkin/stamp.js\";\nimport { LOAM_VERSION } from \"../../core/envelope/version.js\";\nimport { UnsafePathError } from \"../../core/kernel/path-safety.js\";\nimport { commitEmission, recoverEmissionRoot } from \"./commit.js\";\nimport { reconcile, type Scope } from \"./reconcile.js\";\nimport { render } from \"./render.js\";\nimport { sayRecovered } from \"../policy/format.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(\n      \"--dry-run\",\n      \"print the plan (writes, replacements, deletions) and write nothing — beyond first finishing a predecessor's interrupted commit, exactly as a real run would\",\n    )\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 loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\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      //\n      // TWO conditions, two codes, and the split is the whole point. Both used\n      // to answer `invalid-option`, whose `loam explain` row says the\n      // invocation itself is wrong — contradictory flags, a mistyped one, a\n      // value that cannot be right. Here the invocation is perfectly correct\n      // and the REPOSITORY is the wrong one, so that code sent a user whose\n      // flags were fine off to re-read their flags, and left CI and agents\n      // unable to tell \"run this in the service repo\" from \"you typed the flag\n      // wrong\". `loam verify --record --service` already draws exactly this\n      // line for exactly this reason (see commands/verify/verify.ts); gherkin\n      // and vouch now answer the same pair, so a caller branching on\n      // `error.code` gets one answer from all three. The messages are\n      // unchanged — only the code moved.\n      if (config.service === undefined) {\n        return fail(\n          json,\n          \"repository-unavailable\",\n          `Cannot emit gherkin for '${service}' from here: this is not a service repo. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n      if (config.service !== service) {\n        return fail(\n          json,\n          \"service-mismatch\",\n          `Cannot emit gherkin for '${service}' from here: this repo is '${config.service}'. 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      // A predecessor's interrupted emission is rolled forward before ANY\n      // read — and before the feature argument resolves: reconcile grades the\n      // very bytes a half-commit corrupts, and the journal's stored rerun may\n      // name a feature that has since ARCHIVED, whose recovery must still\n      // work. `new` fixed the same ordering and documented it; refusing\n      // unknown-target over a wedged root left doctor printing a repair that\n      // could never run.\n      const early = await recoverEmissionRoot(root);\n      if (!early.ok) return fail(json, early.code, early.message);\n      let recovered = early.recovered;\n\n      const feature =\n        featureArg === undefined ? null : await resolveFeature(config.docsDir, featureArg, \"exclude\");\n      if (featureArg !== undefined && feature === null) {\n        return fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg));\n      }\n      const scope: Scope =\n        feature === null ? { mode: \"living\" } : { mode: \"feature\", featureId: feature.id };\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      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 (feature !== null) {\n          // `config.service`, not `service`: the guard above proved they are\n          // the same id, and only the config's copy carries the load-time\n          // parse, so it is the pathable spelling — same as the else arm.\n          const paths = featureSpecPaths(feature.dir, config.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          // The guard above proved `service` IS `config.service`; only the\n          // latter carries the load-time parse, so it is the pathable spelling.\n          const paths = await locateServicePaths(config.docsDir, config.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, {\n        service,\n        featureTag: scope.mode === \"feature\" ? scope.featureId : undefined,\n        version: LOAM_VERSION,\n      });\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\n      // `Set<string>`, not the ids' own brand: this set answers membership\n      // questions for tags read out of .feature files — document text.\n      const activeIds = new Set<string>((await listFeatures(config.docsDir)).map((f) => f.id));\n      let reconciled;\n      try {\n        reconciled = await reconcile(plan, { root, repoDir }, scope, activeIds);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(json, \"invalid-option\", `Cannot emit Gherkin: ${err.message}.`);\n      }\n      const { actions, orphans, conflicts } = reconciled;\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      // Only a feature run can conflict — living mode keeps the in-flight file\n      // rather than refusing — and standing inside that scope is also how the\n      // message names the feature without asserting there is one.\n      if (scope.mode === \"feature\" && 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 ${scope.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 ${scope.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 && (writes.length > 0 || orphans.length > 0)) {\n        // The commit window: locked, journaled, compared against the bytes\n        // reconcile graded. A zero-op run takes no lock and creates no root —\n        // an emission with nothing to emit must not flip the repo into\n        // \"opted in\", where an empty loam/ tells `loam validate` the whole\n        // living suite is missing.\n        const committed = await commitEmission({ root, service, scope }, { writes, orphans });\n        if (!committed.ok) return fail(json, committed.code, committed.message);\n        recovered = committed.recovered ?? recovered;\n      }\n\n      if (json) {\n        emitJson({\n          command: \"gherkin\",\n          mode: scope.mode,\n          ...(scope.mode === \"feature\" ? { feature: scope.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              : {\n                  stepless: a.stepless,\n                  malformedExamples: a.malformedExamples,\n                  strandedBlocks: a.strandedBlocks,\n                }),\n          })),\n          deleted: orphans.map((o) => rel(o.path)),\n          ...(recovered === null ? {} : { recovered }),\n        });\n        return;\n      }\n\n      if (recovered !== null) console.log(`${sayRecovered(recovered)}\\n`);\n      render(actions, {\n        service,\n        root: rel(root),\n        absRoot: root,\n        featureId: scope.mode === \"feature\" ? scope.featureId : null,\n        dryRun,\n        activeIds,\n        writes: writes.length,\n        orphans: orphans.map((o) => o.path),\n      });\n    });\n}\n"]}

package/dist/commands/gherkin/reconcile.js

@@ -0,0 +1,149 @@
+/**
+ * The plan against what is already on disk: which files are orphans, which are
+ * written, replaced, kept, or owned by another feature.
+ *
+ * A module of its own because it is the only part of `loam gherkin` that
+ * DELETES, and the reasoning that makes deletion safe is all here: a candidate
+ * is an orphan only when its containing directory really resolves inside the
+ * owned root, and a root that does not resolve proves nothing about what lives
+ * beneath it, so nothing is collected. Leaving an orphan behind is
+ * self-repairing — `loam validate` grades it and the next run removes it — and a
+ * deletion taken on an unproven path is not.
+ *
+ * The in-flight exemption is here for the same reason: files are named by
+ * requirement slug in both modes, so a MODIFIED requirement's living emission
+ * always collides with the active feature's file, and replacing it reverted the
+ * delta's wording mid-flight with its digest stamps destroyed.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import {} from "../../core/gherkin/emit.js";
+import { parseStampedFeature } from "../../core/gherkin/read.js";
+import { featureFilesUnder } from "../../core/gherkin/stale.js";
+import { isPathInside, resolveInside, UnsafePathError } from "../../core/kernel/path-safety.js";
+export async function reconcile(plan, where, scope, activeIds) {
+    const { root, repoDir } = where;
+    // 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));
+    // "Inside loam/" has to hold after the links are resolved, not merely in
+    // the spelling of the path. `featureFilesUnder` FOLLOWS symlinks and
+    // recurses with the LINK's path, so a planted `<gherkinDir>/loam/sub ->
+    // /outside` hands back candidates that read as ours while `unlink`
+    // resolves them and destroys files that were never in this repo. Planned
+    // names are flat, so nothing nested is ever spared by `planned.has(...)`,
+    // and deletion is the one irreversible thing this command does: a
+    // candidate is an orphan only when its CONTAINING directory really
+    // resolves inside the owned root. The write path below refuses the same
+    // attack for the same reason.
+    //
+    // The candidate FILE is deliberately NOT resolved. A symlinked .feature
+    // sitting directly in loam/ is loam's to remove — unlinking it takes the
+    // link and leaves its target alone — so only the directory chain has to
+    // be ours.
+    const realOrNull = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return null;
+        }
+    };
+    // A root that does not resolve — absent, dangling, or vanished mid-run —
+    // proves nothing about what lives beneath it, so nothing is collected.
+    // Leaving an orphan behind is self-repairing (`loam validate` grades it
+    // `gherkin.orphaned` and the next run removes it); a deletion taken on an
+    // unproven path is not.
+    const rootReal = realOrNull(root);
+    const orphans = [];
+    if (rootReal !== null) {
+        for (const abs of await featureFilesUnder(root)) {
+            if (planned.has(relative(root, abs).split(/[\\/]/).join("/")))
+                continue;
+            const holder = realOrNull(dirname(abs));
+            if (holder === null || !isPathInside(rootReal, holder))
+                continue;
+            const raw = await readFile(abs);
+            const stamped = parseStampedFeature(raw.toString("utf8"));
+            if (scope.mode === "feature") {
+                if (stamped !== null && stamped.tags.includes(scope.featureId))
+                    orphans.push({ path: abs, raw });
+            }
+            else {
+                if (stamped !== null && stamped.tags.some((t) => activeIds.has(t)))
+                    continue;
+                orphans.push({ path: abs, raw });
+            }
+        }
+    }
+    // The in-flight exemption guards the OVERWRITE path too, not only the
+    // orphan scan above: files are named by requirement slug in both modes,
+    // so a MODIFIED requirement's living emission always collides with the
+    // active feature's file — and replacing it reverted the delta's wording
+    // mid-flight, feature tag and new digest stamps destroyed, invisibly
+    // (the reverted file grades current against the living spec). A planned
+    // path whose existing content is stamped and tagged with a feature still
+    // in flight is KEPT and reported as such; it answers to its feature's
+    // delta until the feature archives, and then living regeneration
+    // replaces it normally.
+    //
+    // FEATURE mode has the same collision and cannot solve it by keeping:
+    // two features in flight against one requirement slug want the same
+    // file, and whichever runs second used to `replace` — silently reverting
+    // the other feature's wording, feature tag and digest stamps, so its
+    // `verify --results` could never confirm a scenario again. Nothing loam
+    // can write is right here (the file holds ONE feature's delta), so the
+    // run refuses and names the owner: the two features have to be sequenced,
+    // or the requirement renamed.
+    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;
+            throw err;
+        }
+        if (!existsSync(path)) {
+            actions.push({ ...f, path, action: "written" });
+            continue;
+        }
+        const raw = await readFile(path);
+        const existing = parseStampedFeature(raw.toString("utf8"));
+        if (scope.mode === "living") {
+            if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {
+                actions.push({ ...f, path, action: "kept", kept: existing });
+                continue;
+            }
+        }
+        else if (existing !== null) {
+            // An unstamped file is nobody's delta — it owns nothing, so it is
+            // replaced like any other, which is what the empty owner list used
+            // to say the long way round.
+            const owners = existing.tags.filter((t) => t !== scope.featureId && activeIds.has(t));
+            if (owners.length > 0) {
+                actions.push({ ...f, path, action: "conflict", kept: existing, owners });
+                continue;
+            }
+        }
+        actions.push({ ...f, path, action: "replaced", raw });
+    }
+    // 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.
+    // Only a feature run can conflict — living mode keeps the in-flight file
+    // rather than refusing — and standing inside that scope is also how the
+    // message names the feature without asserting there is one.
+    const conflicts = scope.mode === "feature"
+        ? actions.filter((a) => a.action === "conflict")
+        : [];
+    return { orphans, actions, conflicts };
+}
+//# sourceMappingURL=reconcile.js.map