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

package/dist/commands/migrate-openspec/materialize/stage.js

@@ -0,0 +1,143 @@
+/**
+ * Every refusal that stands between a finished migration plan and the disk.
+ *
+ * Three questions, one module because all three are answered at the same
+ * moment and none of them may be skipped: may the target hold these bytes at
+ * all (it must be empty, not a symlink, outside the OpenSpec source and outside
+ * any live loam fleet), do two planned writes claim one path once portable
+ * case/Unicode folding is applied, and would the requirements about to be
+ * serialized still parse as a loam spec.
+ *
+ * They sit beside the writers rather than under `../openspec/` because they
+ * grade the *output*: `../openspec/paths.ts` holds the path arithmetic they are
+ * built from, and knows nothing about a plan.
+ */
+import { existsSync } from "node:fs";
+import { lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { findConfigPath, parseConfig } from "../../../core/envelope/config.js";
+import { docsDirOf } from "../../../core/kernel/ids/dirs.js";
+import { CAPABILITY_LINE_RE, requirementIdProblems } from "../../../core/document/spec.js";
+import { decodeDocument } from "../../../core/kernel/document-bytes.js";
+import { isPathInside } from "../../../core/kernel/path-safety.js";
+import {} from "../../../core/openspec/model/model.js";
+import {} from "../../../core/staging/writes.js";
+import { OpenSpecCommandError } from "../openspec/error.js";
+import { canonicalForCreate } from "../openspec/paths.js";
+/**
+ * The other half of "never writes into … live loam docs". Overlap with the
+ * OpenSpec source was the only thing checked, so `--target <docs>/features` on a
+ * fresh fleet passed and put phantom features into every `loam list`.
+ *
+ * The line is the docs tree, not the repository: every enumerating command reads
+ * `<docsDir>/services` and `<docsDir>/features`, so a target under docsDir joins
+ * the live fleet, while a sibling of it is merely a directory. A config that
+ * governs the target but cannot be parsed is refused too — an unreadable
+ * docsDir cannot be shown to be somewhere else.
+ */
+async function assertOutsideLoamDocs(stage) {
+    const canonicalStage = await canonicalForCreate(stage);
+    const governing = findConfigPath(canonicalStage);
+    if (governing !== null) {
+        const docsDir = await governingDocsDir(governing);
+        if (docsDir === null || isPathInside(docsDir, canonicalStage)) {
+            throw new OpenSpecCommandError("invalid-option", `Refusing to stage a migration inside the live loam docs ${docsDir ?? `governed by ${governing}`}: ${stage}. Migrate into a standalone directory and cut over after review.`);
+        }
+    }
+    // A docs repo checked out without its loam.json — the landscape is the file
+    // no docs repo is without, and `loam init` scaffolds it before anything else.
+    for (let dir = canonicalStage;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "architecture", "landscape.likec4"))) {
+            throw new OpenSpecCommandError("invalid-option", `Refusing to stage a migration inside a loam docs repository: ${join(dir, "architecture", "landscape.likec4")} is above ${stage}. Migrate into a standalone directory and cut over after review.`);
+        }
+        if (dirname(dir) === dir)
+            return;
+    }
+}
+/**
+ * Canonical docsDir of the config at `path`, or null when it cannot be read —
+ * including "read as UTF-8 it would have said something else", which is why the
+ * bytes go through `decodeDocument`. Null is the conservative answer here: the
+ * caller refuses to stage rather than accept a docsDir it cannot establish.
+ */
+async function governingDocsDir(path) {
+    try {
+        // Re-branded after canonicalization: the path came out of `parseConfig`
+        // already resolved (a `DocsDir`), and `canonicalForCreate` only follows
+        // symlinks — same root, same provenance, canonical spelling.
+        return docsDirOf(await canonicalForCreate(parseConfig(decodeDocument(await readFile(path), path), dirname(path)).docsDir));
+    }
+    catch {
+        return null;
+    }
+}
+export async function assertEmptyNonOverlappingStage(inventory, stage) {
+    const canonicalStage = await canonicalForCreate(stage);
+    const canonicalSource = await realpath(inventory.inputRoot);
+    if (isPathInside(canonicalSource, canonicalStage) || isPathInside(canonicalStage, canonicalSource)) {
+        throw new OpenSpecCommandError("invalid-option", `Staging directory must not overlap the OpenSpec source workspace: ${stage}`);
+    }
+    await assertOutsideLoamDocs(stage);
+    try {
+        if ((await lstat(stage)).isSymbolicLink()) {
+            throw new OpenSpecCommandError("invalid-option", `Staging target must not be a symbolic link: ${stage}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof OpenSpecCommandError)
+            throw error;
+        const code = typeof error === "object" && error !== null && "code" in error ? error.code : null;
+        if (code !== "ENOENT")
+            throw error;
+    }
+    if (!existsSync(stage))
+        return;
+    const info = await stat(stage);
+    if (!info.isDirectory() || (await readdir(stage)).length > 0) {
+        throw new OpenSpecCommandError("already-exists", `Staging target must be absent or an empty directory: ${stage}`);
+    }
+}
+export function assertDistinctPlannedPaths(writes) {
+    const writePaths = new Map();
+    for (const write of writes) {
+        const collisionKey = resolve(write.path).normalize("NFC").toLowerCase();
+        const existing = writePaths.get(collisionKey);
+        if (existing !== undefined) {
+            throw new OpenSpecCommandError("invalid-option", `Migration paths '${existing}' and '${write.path}' collide after portable case/Unicode normalization; refine mappings before apply.`);
+        }
+        writePaths.set(collisionKey, write.path);
+    }
+}
+/**
+ * The requirement with a `Capability: <id>` body line — the join that keeps
+ * the source capability's identity on every requirement it routed, instead of
+ * dissolving it into service files and leaving the id only in legacy/. The
+ * serializeRequirements Requirement-ID pattern: never a second line when the
+ * author already wrote one (a rare but legal delta authored against a loam
+ * target), and appended after the body the way active.ts appends its
+ * OpenSpec-Living-Source annotation, so a MODIFIED requirement's wholesale
+ * replace carries the line into the living document rather than stripping it.
+ */
+export function requirementWithCapability(requirement, capabilityId) {
+    if (requirement.text.some((line) => CAPABILITY_LINE_RE.test(line)))
+        return requirement;
+    const line = `Capability: ${capabilityId}`;
+    return {
+        ...requirement,
+        capabilities: [capabilityId],
+        text: requirement.text.length === 0 ? [line] : [...requirement.text, "", line],
+    };
+}
+export function assertMaterializedRequirementIds(where, requirements) {
+    const problems = requirementIdProblems(requirements);
+    if (problems.length === 0)
+        return;
+    const first = problems[0];
+    const detail = first.kind === "invalid"
+        ? `requirement '${first.requirement}' has invalid Requirement-ID '${first.value}'`
+        : first.kind === "repeated"
+            ? `requirement '${first.requirement}' declares Requirement-ID ${first.values.length} times`
+            : `Requirement-ID '${first.id}' is shared by ${first.requirements.map((name) => `'${name}'`).join(", ")}`;
+    throw new OpenSpecCommandError("invalid-option", `${where} would materialize an invalid loam spec: ${detail}. Repair the source or refine routing before apply.`);
+}
+//# sourceMappingURL=stage.js.map

package/dist/commands/migrate-openspec/materialize/stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/materialize/stage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every refusal that stands between a finished migration plan and the disk.\n *\n * Three questions, one module because all three are answered at the same\n * moment and none of them may be skipped: may the target hold these bytes at\n * all (it must be empty, not a symlink, outside the OpenSpec source and outside\n * any live loam fleet), do two planned writes claim one path once portable\n * case/Unicode folding is applied, and would the requirements about to be\n * serialized still parse as a loam spec.\n *\n * They sit beside the writers rather than under `../openspec/` because they\n * grade the *output*: `../openspec/paths.ts` holds the path arithmetic they are\n * built from, and knows nothing about a plan.\n */\nimport { existsSync } from \"node:fs\";\nimport { lstat, readFile, readdir, realpath, stat } from \"node:fs/promises\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { findConfigPath, parseConfig } from \"../../../core/envelope/config.js\";\nimport { docsDirOf, type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { CAPABILITY_LINE_RE, requirementIdProblems, type Requirement } from \"../../../core/document/spec.js\";\nimport { decodeDocument } from \"../../../core/kernel/document-bytes.js\";\nimport { isPathInside } from \"../../../core/kernel/path-safety.js\";\nimport { type OpenSpecInventory } from \"../../../core/openspec/model/model.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { OpenSpecCommandError } from \"../openspec/error.js\";\nimport { canonicalForCreate } from \"../openspec/paths.js\";\n\n/**\n * The other half of \"never writes into … live loam docs\". Overlap with the\n * OpenSpec source was the only thing checked, so `--target <docs>/features` on a\n * fresh fleet passed and put phantom features into every `loam list`.\n *\n * The line is the docs tree, not the repository: every enumerating command reads\n * `<docsDir>/services` and `<docsDir>/features`, so a target under docsDir joins\n * the live fleet, while a sibling of it is merely a directory. A config that\n * governs the target but cannot be parsed is refused too — an unreadable\n * docsDir cannot be shown to be somewhere else.\n */\nasync function assertOutsideLoamDocs(stage: string): Promise<void> {\n  const canonicalStage = await canonicalForCreate(stage);\n  const governing = findConfigPath(canonicalStage);\n  if (governing !== null) {\n    const docsDir = await governingDocsDir(governing);\n    if (docsDir === null || isPathInside(docsDir, canonicalStage)) {\n      throw new OpenSpecCommandError(\n        \"invalid-option\",\n        `Refusing to stage a migration inside the live loam docs ${docsDir ?? `governed by ${governing}`}: ${stage}. Migrate into a standalone directory and cut over after review.`,\n      );\n    }\n  }\n  // A docs repo checked out without its loam.json — the landscape is the file\n  // no docs repo is without, and `loam init` scaffolds it before anything else.\n  for (let dir = canonicalStage; ; dir = dirname(dir)) {\n    if (existsSync(join(dir, \"architecture\", \"landscape.likec4\"))) {\n      throw new OpenSpecCommandError(\n        \"invalid-option\",\n        `Refusing to stage a migration inside a loam docs repository: ${join(dir, \"architecture\", \"landscape.likec4\")} is above ${stage}. Migrate into a standalone directory and cut over after review.`,\n      );\n    }\n    if (dirname(dir) === dir) return;\n  }\n}\n\n/**\n * Canonical docsDir of the config at `path`, or null when it cannot be read —\n * including \"read as UTF-8 it would have said something else\", which is why the\n * bytes go through `decodeDocument`. Null is the conservative answer here: the\n * caller refuses to stage rather than accept a docsDir it cannot establish.\n */\nasync function governingDocsDir(path: string): Promise<DocsDir | null> {\n  try {\n    // Re-branded after canonicalization: the path came out of `parseConfig`\n    // already resolved (a `DocsDir`), and `canonicalForCreate` only follows\n    // symlinks — same root, same provenance, canonical spelling.\n    return docsDirOf(await canonicalForCreate(\n      parseConfig(decodeDocument(await readFile(path), path), dirname(path)).docsDir,\n    ));\n  } catch {\n    return null;\n  }\n}\n\nexport async function assertEmptyNonOverlappingStage(inventory: OpenSpecInventory, stage: string): Promise<void> {\n  const canonicalStage = await canonicalForCreate(stage);\n  const canonicalSource = await realpath(inventory.inputRoot);\n  if (isPathInside(canonicalSource, canonicalStage) || isPathInside(canonicalStage, canonicalSource)) {\n    throw new OpenSpecCommandError(\n      \"invalid-option\",\n      `Staging directory must not overlap the OpenSpec source workspace: ${stage}`,\n    );\n  }\n  await assertOutsideLoamDocs(stage);\n  try {\n    if ((await lstat(stage)).isSymbolicLink()) {\n      throw new OpenSpecCommandError(\n        \"invalid-option\",\n        `Staging target must not be a symbolic link: ${stage}`,\n      );\n    }\n  } catch (error) {\n    if (error instanceof OpenSpecCommandError) throw error;\n    const code = typeof error === \"object\" && error !== null && \"code\" in error ? error.code : null;\n    if (code !== \"ENOENT\") throw error;\n  }\n  if (!existsSync(stage)) return;\n  const info = await stat(stage);\n  if (!info.isDirectory() || (await readdir(stage)).length > 0) {\n    throw new OpenSpecCommandError(\"already-exists\", `Staging target must be absent or an empty directory: ${stage}`);\n  }\n}\n\nexport function assertDistinctPlannedPaths(writes: PlannedWrite[]): void {\n  const writePaths = new Map<string, string>();\n  for (const write of writes) {\n    const collisionKey = resolve(write.path).normalize(\"NFC\").toLowerCase();\n    const existing = writePaths.get(collisionKey);\n    if (existing !== undefined) {\n      throw new OpenSpecCommandError(\n        \"invalid-option\",\n        `Migration paths '${existing}' and '${write.path}' collide after portable case/Unicode normalization; refine mappings before apply.`,\n      );\n    }\n    writePaths.set(collisionKey, write.path);\n  }\n}\n\n/**\n * The requirement with a `Capability: <id>` body line — the join that keeps\n * the source capability's identity on every requirement it routed, instead of\n * dissolving it into service files and leaving the id only in legacy/. The\n * serializeRequirements Requirement-ID pattern: never a second line when the\n * author already wrote one (a rare but legal delta authored against a loam\n * target), and appended after the body the way active.ts appends its\n * OpenSpec-Living-Source annotation, so a MODIFIED requirement's wholesale\n * replace carries the line into the living document rather than stripping it.\n */\nexport function requirementWithCapability(requirement: Requirement, capabilityId: string): Requirement {\n  if (requirement.text.some((line) => CAPABILITY_LINE_RE.test(line))) return requirement;\n  const line = `Capability: ${capabilityId}`;\n  return {\n    ...requirement,\n    capabilities: [capabilityId],\n    text: requirement.text.length === 0 ? [line] : [...requirement.text, \"\", line],\n  };\n}\n\nexport function assertMaterializedRequirementIds(where: string, requirements: Requirement[]): void {\n  const problems = requirementIdProblems(requirements);\n  if (problems.length === 0) return;\n  const first = problems[0]!;\n  const detail = first.kind === \"invalid\"\n    ? `requirement '${first.requirement}' has invalid Requirement-ID '${first.value}'`\n    : first.kind === \"repeated\"\n      ? `requirement '${first.requirement}' declares Requirement-ID ${first.values.length} times`\n      : `Requirement-ID '${first.id}' is shared by ${first.requirements.map((name) => `'${name}'`).join(\", \")}`;\n  throw new OpenSpecCommandError(\n    \"invalid-option\",\n    `${where} would materialize an invalid loam spec: ${detail}. Repair the source or refine routing before apply.`,\n  );\n}\n"]}

package/dist/commands/migrate-openspec/materialize/target.js

@@ -0,0 +1,219 @@
+/**
+ * The staged target: plan every byte first, then land them all or none.
+ *
+ * The two halves are one module because they are one transaction. Planning
+ * reads the whole source corpus, so `writeMigrationTarget` re-hashes it
+ * afterwards and refuses a snapshot that moved mid-flight; the plan then
+ * becomes an exclusive staged write set that rolls back as a unit. Splitting
+ * the planner from the writer would put that re-hash on one side of a module
+ * boundary and the reads it guards on the other.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { openspecRequirements } from "../../../core/openspec/scan/shape.js";
+import {} from "../../../core/document/spec.js";
+import { DOCS_SUBDIRS, docsRepoFiles } from "../../../core/docs.js";
+import { compareIds } from "../../../core/repo/entries.js";
+import { ownValue } from "../../../core/kernel/records.js";
+import { inventoryOpenSpec } from "../../../core/openspec/inventory.js";
+import {} from "../../../core/openspec/model/mapping.js";
+import {} from "../../../core/openspec/model/model.js";
+import { rollbackError, rollbackStaged, stageWrites, swapStaged } from "../../../core/staging/commit.js";
+import { planWrite } from "../../../core/staging/writes.js";
+import { normalizedMapping } from "../openspec/decisions.js";
+import { OpenSpecCommandError } from "../openspec/error.js";
+import { safeArtifactRelative } from "../openspec/paths.js";
+import { readSourceArtifact } from "../openspec/read.js";
+import { materializeActiveChanges } from "./active.js";
+import { materializeLivingSpecs } from "./living.js";
+import { assertDistinctPlannedPaths, assertEmptyNonOverlappingStage } from "./stage.js";
+export async function planMigrationWrites(inventory, mapping, target) {
+    // One reading of the living corpus for both materializers. They each read and
+    // parsed the whole of it independently, which is twice the work and, worse,
+    // two readings: a rename resolved against one of them was written beside a
+    // living spec built from the other.
+    const livingByCapability = new Map();
+    for (const capability of inventory.living.capabilities) {
+        livingByCapability.set(capability.id, openspecRequirements(await readSourceArtifact(inventory.root, capability.files[0])));
+    }
+    const livingWrites = await materializeLivingSpecs(inventory, mapping, target, livingByCapability);
+    const vocabulary = capabilitiesVocabularyWrite(inventory, target);
+    if (vocabulary !== null)
+        livingWrites.push(vocabulary);
+    const activeWrites = await materializeActiveChanges(inventory, mapping, target, livingByCapability);
+    const legacyWrites = await copyLivingTree(inventory, target);
+    assertDistinctPlannedPaths([...livingWrites, ...activeWrites, ...legacyWrites]);
+    return { livingWrites, activeWrites, legacyWrites };
+}
+/**
+ * The staged fleet's capability vocabulary: the union of living and
+ * active-horizon capability ids, each declared with an EMPTY body — no
+ * description is invented, because the authored `## Purpose` prose stays
+ * verbatim under legacy/ (the no-prose-moves rule), and an empty mapping is a
+ * legal declaration. Keys sorted with compareIds over an insertion-ordered
+ * object, so the bytes are machine-independent; nested ids stay one flat key
+ * (`payments/refunds`), never collapsed. Null when the corpus names no
+ * capability at all — an empty vocabulary FILE would opt the staged fleet into
+ * an axis it has nothing to say on. assertDistinctPlannedPaths guards the path
+ * against every other planned write; the docs scaffold does not write it.
+ */
+function capabilitiesVocabularyWrite(inventory, target) {
+    const ids = new Set(inventory.living.capabilities.map((capability) => capability.id));
+    for (const change of inventory.changes.active) {
+        for (const spec of change.specs)
+            ids.add(spec.capability);
+    }
+    if (ids.size === 0)
+        return null;
+    const capabilities = Object.fromEntries([...ids].sort(compareIds).map((id) => [id, {}]));
+    return planWrite(join(target, "architecture", "capabilities.yaml"), "# Declared by `loam migrate-openspec`: every living and active-horizon OpenSpec\n" +
+        "# capability id, so capability identity survives migration as a checkable name\n" +
+        "# (each routed requirement carries a matching `Capability:` line). Descriptions\n" +
+        "# are deliberately absent — the authored Purpose prose is verbatim under\n" +
+        "# legacy/openspec/specs/, and no prose moves.\n" +
+        stringifyYaml({ capabilities }, { lineWidth: 0 }));
+}
+/**
+ * The living tree, byte for byte, the way each change tree already gets
+ * `legacy/openspec/`.
+ *
+ * `materializeLivingSpecs` emits frontmatter plus serialized requirements, so
+ * everything a living spec holds AROUND its requirements has nowhere to land:
+ * `## Purpose`, prose between `## Requirements` and the first requirement, and
+ * the whole of `specs/<capability>/design.md` — which the summary counts under
+ * `review-as-service-adr` while FOLLOW-UP.md tells the migrator to review prose
+ * that had been written nowhere. (Prose inside a requirement body survives
+ * serialization and is not the subject here.)
+ */
+async function copyLivingTree(inventory, target) {
+    const writes = [];
+    for (const artifact of inventory.artifacts) {
+        if (artifact.scope !== "living")
+            continue;
+        const segments = safeArtifactRelative(artifact.path, "specs/", "The OpenSpec living tree");
+        writes.push(planWrite(join(target, "legacy", "openspec", "specs", ...segments), await readSourceArtifact(inventory.root, artifact.path)));
+    }
+    return writes;
+}
+export async function writeMigrationTarget(inventory, mapping, target, planned) {
+    await assertEmptyNonOverlappingStage(inventory, target);
+    // All migration content was read while planning. Re-hash after those reads so
+    // a source edit between audit and materialization cannot produce a mixed snapshot.
+    const refreshed = await inventoryOpenSpec(inventory.inputRoot, { mapping });
+    if (!refreshed.ready || refreshed.inventoryDigest !== inventory.inventoryDigest) {
+        throw new OpenSpecCommandError("invalid-option", "OpenSpec source changed while the migration plan was being materialized; re-audit and review a new mapping.");
+    }
+    const followUpBlockers = [
+        "Model every staged service in architecture/landscape.likec4 and bind it with metadata { service '<id>' }; the scaffolded landscape is deliberately empty.",
+        "Add each service model.likec4 and OpenAPI contract; migrated requirements have no Operations/Covers links yet unless authored upstream.",
+        "Set truthful sources from each service repository, validate, and have a human run loam vouch; staged specs remain status: draft.",
+        ...(inventory.changes.active.length === 0
+            ? []
+            : [
+                `Review ${inventory.changes.active.length} staged feature(s), add their LikeC4/OpenAPI deltas, and resolve any retained or manual-review OpenSpec artifacts recorded in migration-plan.json.`,
+                // OpenSpec has no equivalent of `Based-On:`, so every migrated
+                // MODIFIED/REMOVED requirement arrives unpinned (`delta.baseline-missing`,
+                // a warning that GATES archive — unpinned is the shape that reverts
+                // someone else's landed change). The corpus is not stranded: one
+                // rebase per staged feature pins everything, which is exactly the
+                // step this line asks for.
+                "Run `loam rebase <FEAT>` per staged feature: OpenSpec deltas carry no Based-On, so no MODIFIED/REMOVED requirement is pinned to the living text it was written against.",
+            ]),
+        "Review config context/rules, Stores/references, custom schemas, and every artifact disposition in migration-plan.json.",
+        "Review the verbatim OpenSpec living tree under legacy/openspec/specs/: Purpose prose, section prose, and capability design.md have no loam equivalent and were copied, not converted.",
+        // The cutover was undocumented, which is how a staged target that cannot
+        // answer `loam validate` reads as finished work. Naming the two halves —
+        // what is fleet content and what is review residue — is the whole procedure.
+        "Cut over only once `loam validate --all` here is green: services/ and features/ are the fleet content, while legacy/, mapping.yaml, migration-plan.json, FOLLOW-UP.md, and this repository's own loam.json/AGENTS.md are review residue that does not move.",
+    ];
+    const plan = {
+        version: 1,
+        generatedBy: "loam migrate-openspec",
+        source: { inputRoot: inventory.inputRoot, root: inventory.root },
+        baselines: inventory.baselines,
+        readiness: inventory.readiness,
+        mapping: normalizedMapping(inventory, mapping),
+        living: inventory.living,
+        activeChanges: inventory.changes.active,
+        archiveDiagnostics: inventory.archiveDiagnostics,
+        artifactDisposition: inventory.artifacts.map((artifact) => ({
+            ...artifact,
+            disposition: ownValue(mapping.artifacts, artifact.path) ?? artifact.disposition,
+            selectedDisposition: ownValue(mapping.artifacts, artifact.path) ?? null,
+        })),
+        followUpBlockers,
+        note: "Staged migration docs only. Living specs and mapped active changes were materialized without changing the OpenSpec source or live loam docs. The result is intentionally not expected to validate green until the listed architecture, API, provenance, and review work is completed.",
+    };
+    const writes = [
+        planWrite(join(target, "migration-plan.json"), `${JSON.stringify(plan, null, 2)}\n`),
+        planWrite(join(target, "mapping.yaml"), stringifyYaml(normalizedMapping(inventory, mapping), { lineWidth: 0 })),
+        planWrite(join(target, "FOLLOW-UP.md"), renderFollowUp(followUpBlockers)),
+        ...docsRepoScaffold(target),
+        ...planned.livingWrites,
+        ...planned.activeWrites,
+        ...planned.legacyWrites,
+    ];
+    assertDistinctPlannedPaths(writes);
+    for (const write of writes)
+        write.exclusive = true;
+    const staged = await stageWrites(writes);
+    if (staged.some((item) => item.before !== null)) {
+        await rollbackStaged(staged);
+        throw new OpenSpecCommandError("already-exists", "Staging target changed after its emptiness check; refusing to overwrite a concurrently created file.");
+    }
+    try {
+        await swapStaged(staged);
+    }
+    catch (error) {
+        const failures = await rollbackStaged(staged);
+        const code = typeof error === "object" && error !== null && "code" in error ? error.code : null;
+        if (code === "EEXIST" && failures.length === 0) {
+            throw new OpenSpecCommandError("already-exists", "Staging target changed during apply; the migration was rolled back without overwriting the concurrent file.");
+        }
+        throw rollbackError(error, failures);
+    }
+    // The skeleton `loam init` lays down, after the content that fills it. A docs
+    // repo is recognised by `services/` plus AGENTS.md, and until now `services/`
+    // existed only if some capability happened to route there: migrate a corpus
+    // whose requirements all live under `changes/` — legitimate, and the shape a
+    // greenfield OpenSpec workspace has — and the target came out with no
+    // `services/` at all, so `loam init --docs <target> --service <id>` answered
+    // "not a docs repo" and every read command refused it as `services-missing`.
+    // Empty directories, created after the swap so a rolled-back apply leaves the
+    // target as empty as it found it.
+    for (const dir of DOCS_SUBDIRS)
+        await mkdir(join(target, dir), { recursive: true });
+    return { directory: target, files: writes.map((write) => write.path), followUpBlockers };
+}
+/**
+ * The staged target is a real docs repo, not a folder of markdown.
+ *
+ * FOLLOW-UP.md tells the migrator to validate, rebase and vouch against this
+ * directory, and every one of those commands resolves its fleet from loam.json:
+ * without these three files none of the instructions it gives can be executed,
+ * and the reviewer has no way to see what is still missing. The landscape is
+ * laid down EMPTY for the same reason `loam init` lays it down empty — an absent
+ * landscape silences every cross-service check, and a generated one would be a
+ * guess presented as the map. Each staged service then shows up as exactly one
+ * `landscape.service-unmodelled` error, which is the first follow-up item.
+ *
+ * The bytes come from `docs.ts`, so this IS the repo `loam init` makes rather
+ * than a lookalike. Only the landscape's opening comment differs, and it differs
+ * through a parameter: the migrator needs to be told why their map is empty,
+ * and everything after that sentence is advice that does not depend on how the
+ * repo was created.
+ */
+function docsRepoScaffold(target) {
+    return docsRepoFiles({
+        landscapePreamble: "// Fleet map for a staged OpenSpec migration. It arrives EMPTY because\n"
+            + "// OpenSpec has no topology: loam has nothing to read here and will not\n"
+            + "// guess \"who calls whom\" into the source of truth. Every services/<id>/\n"
+            + "// staged beside this file needs an element and a binding below — until\n"
+            + "// then each one is a `landscape.service-unmodelled` error.",
+    }).map(([rel, content]) => planWrite(join(target, rel), content));
+}
+function renderFollowUp(blockers) {
+    return `# Staged OpenSpec migration: required follow-up\n\nThis target contains migrated living requirements, mapped active feature deltas, preserved source artifacts, and a review plan. It is deliberately not presented as a fully valid loam fleet. Complete every item before moving it into live docs.\n\n${blockers.map((item) => `- [ ] ${item}`).join("\n")}\n`;
+}
+//# sourceMappingURL=target.js.map

package/dist/commands/migrate-openspec/materialize/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/materialize/target.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The staged target: plan every byte first, then land them all or none.\n *\n * The two halves are one module because they are one transaction. Planning\n * reads the whole source corpus, so `writeMigrationTarget` re-hashes it\n * afterwards and refuses a snapshot that moved mid-flight; the plan then\n * becomes an exclusive staged write set that rolls back as a unit. Splitting\n * the planner from the writer would put that re-hash on one side of a module\n * boundary and the reads it guards on the other.\n */\nimport { mkdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { stringify as stringifyYaml } from \"yaml\";\nimport { openspecRequirements } from \"../../../core/openspec/scan/shape.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { DOCS_SUBDIRS, docsRepoFiles } from \"../../../core/docs.js\";\nimport { compareIds } from \"../../../core/repo/entries.js\";\nimport { ownValue } from \"../../../core/kernel/records.js\";\nimport { inventoryOpenSpec } from \"../../../core/openspec/inventory.js\";\nimport { type OpenSpecMapping } from \"../../../core/openspec/model/mapping.js\";\nimport { type OpenSpecInventory } from \"../../../core/openspec/model/model.js\";\nimport { rollbackError, rollbackStaged, stageWrites, swapStaged } from \"../../../core/staging/commit.js\";\nimport { planWrite, type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { normalizedMapping } from \"../openspec/decisions.js\";\nimport { OpenSpecCommandError } from \"../openspec/error.js\";\nimport { safeArtifactRelative } from \"../openspec/paths.js\";\nimport { readSourceArtifact } from \"../openspec/read.js\";\nimport { materializeActiveChanges } from \"./active.js\";\nimport { materializeLivingSpecs } from \"./living.js\";\nimport { assertDistinctPlannedPaths, assertEmptyNonOverlappingStage } from \"./stage.js\";\n\nexport async function planMigrationWrites(\n  inventory: OpenSpecInventory,\n  mapping: OpenSpecMapping,\n  target: string,\n): Promise<{ livingWrites: PlannedWrite[]; activeWrites: PlannedWrite[]; legacyWrites: PlannedWrite[] }> {\n  // One reading of the living corpus for both materializers. They each read and\n  // parsed the whole of it independently, which is twice the work and, worse,\n  // two readings: a rename resolved against one of them was written beside a\n  // living spec built from the other.\n  const livingByCapability = new Map<string, Requirement[]>();\n  for (const capability of inventory.living.capabilities) {\n    livingByCapability.set(\n      capability.id,\n      openspecRequirements(await readSourceArtifact(inventory.root, capability.files[0]!)),\n    );\n  }\n  const livingWrites = await materializeLivingSpecs(inventory, mapping, target, livingByCapability);\n  const vocabulary = capabilitiesVocabularyWrite(inventory, target);\n  if (vocabulary !== null) livingWrites.push(vocabulary);\n  const activeWrites = await materializeActiveChanges(inventory, mapping, target, livingByCapability);\n  const legacyWrites = await copyLivingTree(inventory, target);\n  assertDistinctPlannedPaths([...livingWrites, ...activeWrites, ...legacyWrites]);\n  return { livingWrites, activeWrites, legacyWrites };\n}\n\n/**\n * The staged fleet's capability vocabulary: the union of living and\n * active-horizon capability ids, each declared with an EMPTY body — no\n * description is invented, because the authored `## Purpose` prose stays\n * verbatim under legacy/ (the no-prose-moves rule), and an empty mapping is a\n * legal declaration. Keys sorted with compareIds over an insertion-ordered\n * object, so the bytes are machine-independent; nested ids stay one flat key\n * (`payments/refunds`), never collapsed. Null when the corpus names no\n * capability at all — an empty vocabulary FILE would opt the staged fleet into\n * an axis it has nothing to say on. assertDistinctPlannedPaths guards the path\n * against every other planned write; the docs scaffold does not write it.\n */\nfunction capabilitiesVocabularyWrite(inventory: OpenSpecInventory, target: string): PlannedWrite | null {\n  const ids = new Set<string>(inventory.living.capabilities.map((capability) => capability.id));\n  for (const change of inventory.changes.active) {\n    for (const spec of change.specs) ids.add(spec.capability);\n  }\n  if (ids.size === 0) return null;\n  const capabilities = Object.fromEntries([...ids].sort(compareIds).map((id) => [id, {}]));\n  return planWrite(\n    join(target, \"architecture\", \"capabilities.yaml\"),\n    \"# Declared by `loam migrate-openspec`: every living and active-horizon OpenSpec\\n\" +\n      \"# capability id, so capability identity survives migration as a checkable name\\n\" +\n      \"# (each routed requirement carries a matching `Capability:` line). Descriptions\\n\" +\n      \"# are deliberately absent — the authored Purpose prose is verbatim under\\n\" +\n      \"# legacy/openspec/specs/, and no prose moves.\\n\" +\n      stringifyYaml({ capabilities }, { lineWidth: 0 }),\n  );\n}\n\n/**\n * The living tree, byte for byte, the way each change tree already gets\n * `legacy/openspec/`.\n *\n * `materializeLivingSpecs` emits frontmatter plus serialized requirements, so\n * everything a living spec holds AROUND its requirements has nowhere to land:\n * `## Purpose`, prose between `## Requirements` and the first requirement, and\n * the whole of `specs/<capability>/design.md` — which the summary counts under\n * `review-as-service-adr` while FOLLOW-UP.md tells the migrator to review prose\n * that had been written nowhere. (Prose inside a requirement body survives\n * serialization and is not the subject here.)\n */\nasync function copyLivingTree(inventory: OpenSpecInventory, target: string): Promise<PlannedWrite[]> {\n  const writes: PlannedWrite[] = [];\n  for (const artifact of inventory.artifacts) {\n    if (artifact.scope !== \"living\") continue;\n    const segments = safeArtifactRelative(artifact.path, \"specs/\", \"The OpenSpec living tree\");\n    writes.push(planWrite(\n      join(target, \"legacy\", \"openspec\", \"specs\", ...segments),\n      await readSourceArtifact(inventory.root, artifact.path),\n    ));\n  }\n  return writes;\n}\n\nexport async function writeMigrationTarget(\n  inventory: OpenSpecInventory,\n  mapping: OpenSpecMapping,\n  target: string,\n  planned: { livingWrites: PlannedWrite[]; activeWrites: PlannedWrite[]; legacyWrites: PlannedWrite[] },\n): Promise<{ directory: string; files: string[]; followUpBlockers: string[] }> {\n  await assertEmptyNonOverlappingStage(inventory, target);\n  // All migration content was read while planning. Re-hash after those reads so\n  // a source edit between audit and materialization cannot produce a mixed snapshot.\n  const refreshed = await inventoryOpenSpec(inventory.inputRoot, { mapping });\n  if (!refreshed.ready || refreshed.inventoryDigest !== inventory.inventoryDigest) {\n    throw new OpenSpecCommandError(\n      \"invalid-option\",\n      \"OpenSpec source changed while the migration plan was being materialized; re-audit and review a new mapping.\",\n    );\n  }\n  const followUpBlockers = [\n    \"Model every staged service in architecture/landscape.likec4 and bind it with metadata { service '<id>' }; the scaffolded landscape is deliberately empty.\",\n    \"Add each service model.likec4 and OpenAPI contract; migrated requirements have no Operations/Covers links yet unless authored upstream.\",\n    \"Set truthful sources from each service repository, validate, and have a human run loam vouch; staged specs remain status: draft.\",\n    ...(inventory.changes.active.length === 0\n      ? []\n      : [\n          `Review ${inventory.changes.active.length} staged feature(s), add their LikeC4/OpenAPI deltas, and resolve any retained or manual-review OpenSpec artifacts recorded in migration-plan.json.`,\n          // OpenSpec has no equivalent of `Based-On:`, so every migrated\n          // MODIFIED/REMOVED requirement arrives unpinned (`delta.baseline-missing`,\n          // a warning that GATES archive — unpinned is the shape that reverts\n          // someone else's landed change). The corpus is not stranded: one\n          // rebase per staged feature pins everything, which is exactly the\n          // step this line asks for.\n          \"Run `loam rebase <FEAT>` per staged feature: OpenSpec deltas carry no Based-On, so no MODIFIED/REMOVED requirement is pinned to the living text it was written against.\",\n        ]),\n    \"Review config context/rules, Stores/references, custom schemas, and every artifact disposition in migration-plan.json.\",\n    \"Review the verbatim OpenSpec living tree under legacy/openspec/specs/: Purpose prose, section prose, and capability design.md have no loam equivalent and were copied, not converted.\",\n    // The cutover was undocumented, which is how a staged target that cannot\n    // answer `loam validate` reads as finished work. Naming the two halves —\n    // what is fleet content and what is review residue — is the whole procedure.\n    \"Cut over only once `loam validate --all` here is green: services/ and features/ are the fleet content, while legacy/, mapping.yaml, migration-plan.json, FOLLOW-UP.md, and this repository's own loam.json/AGENTS.md are review residue that does not move.\",\n  ];\n  const plan = {\n    version: 1,\n    generatedBy: \"loam migrate-openspec\",\n    source: { inputRoot: inventory.inputRoot, root: inventory.root },\n    baselines: inventory.baselines,\n    readiness: inventory.readiness,\n    mapping: normalizedMapping(inventory, mapping),\n    living: inventory.living,\n    activeChanges: inventory.changes.active,\n    archiveDiagnostics: inventory.archiveDiagnostics,\n    artifactDisposition: inventory.artifacts.map((artifact) => ({\n      ...artifact,\n      disposition: ownValue(mapping.artifacts, artifact.path) ?? artifact.disposition,\n      selectedDisposition: ownValue(mapping.artifacts, artifact.path) ?? null,\n    })),\n    followUpBlockers,\n    note: \"Staged migration docs only. Living specs and mapped active changes were materialized without changing the OpenSpec source or live loam docs. The result is intentionally not expected to validate green until the listed architecture, API, provenance, and review work is completed.\",\n  };\n  const writes: PlannedWrite[] = [\n    planWrite(join(target, \"migration-plan.json\"), `${JSON.stringify(plan, null, 2)}\\n`),\n    planWrite(join(target, \"mapping.yaml\"), stringifyYaml(normalizedMapping(inventory, mapping), { lineWidth: 0 })),\n    planWrite(join(target, \"FOLLOW-UP.md\"), renderFollowUp(followUpBlockers)),\n    ...docsRepoScaffold(target),\n    ...planned.livingWrites,\n    ...planned.activeWrites,\n    ...planned.legacyWrites,\n  ];\n  assertDistinctPlannedPaths(writes);\n  for (const write of writes) write.exclusive = true;\n  const staged = await stageWrites(writes);\n  if (staged.some((item) => item.before !== null)) {\n    await rollbackStaged(staged);\n    throw new OpenSpecCommandError(\n      \"already-exists\",\n      \"Staging target changed after its emptiness check; refusing to overwrite a concurrently created file.\",\n    );\n  }\n  try {\n    await swapStaged(staged);\n  } catch (error) {\n    const failures = await rollbackStaged(staged);\n    const code = typeof error === \"object\" && error !== null && \"code\" in error ? error.code : null;\n    if (code === \"EEXIST\" && failures.length === 0) {\n      throw new OpenSpecCommandError(\n        \"already-exists\",\n        \"Staging target changed during apply; the migration was rolled back without overwriting the concurrent file.\",\n      );\n    }\n    throw rollbackError(error, failures);\n  }\n  // The skeleton `loam init` lays down, after the content that fills it. A docs\n  // repo is recognised by `services/` plus AGENTS.md, and until now `services/`\n  // existed only if some capability happened to route there: migrate a corpus\n  // whose requirements all live under `changes/` — legitimate, and the shape a\n  // greenfield OpenSpec workspace has — and the target came out with no\n  // `services/` at all, so `loam init --docs <target> --service <id>` answered\n  // \"not a docs repo\" and every read command refused it as `services-missing`.\n  // Empty directories, created after the swap so a rolled-back apply leaves the\n  // target as empty as it found it.\n  for (const dir of DOCS_SUBDIRS) await mkdir(join(target, dir), { recursive: true });\n  return { directory: target, files: writes.map((write) => write.path), followUpBlockers };\n}\n\n/**\n * The staged target is a real docs repo, not a folder of markdown.\n *\n * FOLLOW-UP.md tells the migrator to validate, rebase and vouch against this\n * directory, and every one of those commands resolves its fleet from loam.json:\n * without these three files none of the instructions it gives can be executed,\n * and the reviewer has no way to see what is still missing. The landscape is\n * laid down EMPTY for the same reason `loam init` lays it down empty — an absent\n * landscape silences every cross-service check, and a generated one would be a\n * guess presented as the map. Each staged service then shows up as exactly one\n * `landscape.service-unmodelled` error, which is the first follow-up item.\n *\n * The bytes come from `docs.ts`, so this IS the repo `loam init` makes rather\n * than a lookalike. Only the landscape's opening comment differs, and it differs\n * through a parameter: the migrator needs to be told why their map is empty,\n * and everything after that sentence is advice that does not depend on how the\n * repo was created.\n */\nfunction docsRepoScaffold(target: string): PlannedWrite[] {\n  return docsRepoFiles({\n    landscapePreamble: \"// Fleet map for a staged OpenSpec migration. It arrives EMPTY because\\n\"\n      + \"// OpenSpec has no topology: loam has nothing to read here and will not\\n\"\n      + \"// guess \\\"who calls whom\\\" into the source of truth. Every services/<id>/\\n\"\n      + \"// staged beside this file needs an element and a binding below — until\\n\"\n      + \"// then each one is a `landscape.service-unmodelled` error.\",\n  }).map(([rel, content]) => planWrite(join(target, rel), content));\n}\n\nfunction renderFollowUp(blockers: string[]): string {\n  return `# Staged OpenSpec migration: required follow-up\\n\\nThis target contains migrated living requirements, mapped active feature deltas, preserved source artifacts, and a review plan. It is deliberately not presented as a fully valid loam fleet. Complete every item before moving it into live docs.\\n\\n${blockers.map((item) => `- [ ] ${item}`).join(\"\\n\")}\\n`;\n}\n"]}

package/dist/commands/migrate-openspec/migrate-openspec.js

@@ -0,0 +1,142 @@
+/**
+ * The two verbs of the OpenSpec on-ramp, and nothing else.
+ *
+ * They are one module because they are two halves of one procedure and share
+ * the failure mapping below: `audit-openspec` reads a workspace and offers the
+ * decision skeleton, `migrate-openspec` takes that skeleton back filled in and
+ * — only with `--apply` — materializes a staged target. Finding
+ * incompatibilities is a successful audit, so exit status is decided here and
+ * only here; every phase under `./openspec/` and `./materialize/` refuses by
+ * throwing `OpenSpecCommandError` and never touches `process.exitCode`.
+ */
+import { dirname, join, resolve } from "node:path";
+import { fail, emitJson } from "../../core/envelope/json.js";
+import { inventoryOpenSpec } from "../../core/openspec/inventory.js";
+import { createOpenSpecMappingSkeleton } from "../../core/openspec/model/mapping.js";
+import { OpenSpecRootError } from "../../core/openspec/model/model.js";
+import { writeMappingSkeleton } from "./openspec/decisions.js";
+import { OpenSpecCommandError } from "./openspec/error.js";
+import { readMapping } from "./openspec/mapping.js";
+import { planMigrationWrites, writeMigrationTarget } from "./materialize/target.js";
+import { printInventory } from "./print.js";
+/** Registers the read-only audit and the separate, mapping-driven migration planner. */
+export function registerMigrateOpenSpec(program) {
+    program
+        .command("audit-openspec")
+        .argument("<root>", "OpenSpec root, Store checkout, or workspace containing openspec/")
+        .description("Audit an OpenSpec workspace without treating human mapping decisions as command failure")
+        .option("--write-mapping <path>", "write a non-overwriting, digest-bound decision skeleton outside the source workspace")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (root, opts) => {
+        const json = opts.json === true;
+        try {
+            const inventory = await inventoryOpenSpec(root);
+            const skeleton = createOpenSpecMappingSkeleton(inventory);
+            const mappingWritten = opts.writeMapping === undefined
+                ? null
+                : await writeMappingSkeleton(inventory, opts.writeMapping, skeleton);
+            if (json) {
+                emitJson({
+                    command: "audit-openspec",
+                    readOnly: mappingWritten === null,
+                    mappingWritten,
+                    mappingSkeleton: skeleton,
+                    ...inventory,
+                });
+            }
+            else {
+                printInventory(inventory, "audit");
+                if (mappingWritten !== null)
+                    console.log(`\n  mapping skeleton  ${mappingWritten}`);
+                else
+                    console.log("\n  read-only audit: no files were created or changed");
+            }
+            // Finding incompatibilities is a successful audit result. Root/YAML/IO
+            // failures still exit 1 through the catch below; migration readiness has
+            // its own boolean and migrate-openspec exit status.
+        }
+        catch (error) {
+            reportCommandError(json, error);
+        }
+    });
+    program
+        .command("migrate-openspec")
+        .argument("<root>", "OpenSpec root, Store checkout, or workspace containing openspec/")
+        .description("Validate explicit migration mappings and optionally materialize staged migration docs")
+        .option("--map <path>", "YAML mapping created from `audit-openspec --write-mapping`")
+        .option("--mapping <path>", "deprecated alias for --map")
+        .option("--apply", "materialize staged migration docs; dry-run is the default")
+        .option("--target <directory>", "empty standalone target for --apply; never writes into the OpenSpec source or live loam docs")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (root, opts) => {
+        const json = opts.json === true;
+        try {
+            if (opts.map !== undefined && opts.mapping !== undefined) {
+                throw new OpenSpecCommandError("invalid-option", "Pass --map or its deprecated --mapping alias, not both.");
+            }
+            const mapArg = opts.map ?? opts.mapping;
+            if (mapArg === undefined) {
+                throw new OpenSpecCommandError("invalid-option", "migrate-openspec requires --map <path>; run `loam audit-openspec <root> --write-mapping <path>` first.");
+            }
+            if (opts.apply === true && opts.target === undefined) {
+                throw new OpenSpecCommandError("invalid-option", "--apply requires an explicit --target <empty-directory>.");
+            }
+            if (opts.apply !== true && opts.target !== undefined) {
+                throw new OpenSpecCommandError("invalid-option", "--target only has effect with explicit --apply.");
+            }
+            const mappingPath = resolve(mapArg);
+            const mapping = await readMapping(mappingPath);
+            // Re-audit the source at the point of use. inventoryOpenSpec compares
+            // the fresh digest and canonical root to the binding in the mapping.
+            const inventory = await inventoryOpenSpec(root, { mapping });
+            const target = opts.apply === true
+                ? resolve(opts.target)
+                : join(dirname(mappingPath), ".loam-openspec-dry-run-target");
+            const planned = inventory.ready
+                ? await planMigrationWrites(inventory, mapping, target)
+                : null;
+            let applied = null;
+            if (opts.apply === true) {
+                if (!inventory.ready || planned === null) {
+                    throw new OpenSpecCommandError("invalid-option", "Migration cannot be applied until living/active shapes, capability mappings, change-to-feature decisions, active RENAMED identities, authored artifact dispositions, and source digest binding are resolved.");
+                }
+                applied = await writeMigrationTarget(inventory, mapping, target, planned);
+            }
+            if (json) {
+                emitJson({
+                    command: "migrate-openspec",
+                    dryRun: applied === null,
+                    mappingPath,
+                    applied,
+                    ...inventory,
+                });
+            }
+            else {
+                printInventory(inventory, "migration");
+                if (applied === null)
+                    console.log("\n  dry-run: no files were created or changed");
+                else {
+                    console.log(`\n  staged migration docs  ${applied.directory}`);
+                    console.log(`  follow-up blockers      ${applied.followUpBlockers.length} (see FOLLOW-UP.md)`);
+                }
+            }
+            if (!inventory.ready)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            reportCommandError(json, error);
+        }
+    });
+}
+function reportCommandError(json, error) {
+    if (error instanceof OpenSpecRootError) {
+        fail(json, "unknown-target", error.message);
+        return;
+    }
+    if (error instanceof OpenSpecCommandError) {
+        fail(json, error.code, error.message);
+        return;
+    }
+    throw error;
+}
+//# sourceMappingURL=migrate-openspec.js.map

package/dist/commands/migrate-openspec/migrate-openspec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-openspec.js","sourceRoot":"","sources":["../../../src/commands/migrate-openspec/migrate-openspec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The two verbs of the OpenSpec on-ramp, and nothing else.\n *\n * They are one module because they are two halves of one procedure and share\n * the failure mapping below: `audit-openspec` reads a workspace and offers the\n * decision skeleton, `migrate-openspec` takes that skeleton back filled in and\n * — only with `--apply` — materializes a staged target. Finding\n * incompatibilities is a successful audit, so exit status is decided here and\n * only here; every phase under `./openspec/` and `./materialize/` refuses by\n * throwing `OpenSpecCommandError` and never touches `process.exitCode`.\n */\nimport { dirname, join, resolve } from \"node:path\";\nimport type { Command } from \"commander\";\nimport { fail, emitJson } from \"../../core/envelope/json.js\";\nimport { inventoryOpenSpec } from \"../../core/openspec/inventory.js\";\nimport { createOpenSpecMappingSkeleton } from \"../../core/openspec/model/mapping.js\";\nimport { OpenSpecRootError } from \"../../core/openspec/model/model.js\";\nimport { writeMappingSkeleton } from \"./openspec/decisions.js\";\nimport { OpenSpecCommandError } from \"./openspec/error.js\";\nimport { readMapping } from \"./openspec/mapping.js\";\nimport { planMigrationWrites, writeMigrationTarget } from \"./materialize/target.js\";\nimport { printInventory } from \"./print.js\";\n\ninterface AuditOpenSpecOptions {\n  json?: boolean;\n  writeMapping?: string;\n}\n\ninterface MigrateOpenSpecOptions {\n  json?: boolean;\n  map?: string;\n  mapping?: string;\n  apply?: boolean;\n  target?: string;\n}\n\n/** Registers the read-only audit and the separate, mapping-driven migration planner. */\nexport function registerMigrateOpenSpec(program: Command): void {\n  program\n    .command(\"audit-openspec\")\n    .argument(\"<root>\", \"OpenSpec root, Store checkout, or workspace containing openspec/\")\n    .description(\"Audit an OpenSpec workspace without treating human mapping decisions as command failure\")\n    .option(\"--write-mapping <path>\", \"write a non-overwriting, digest-bound decision skeleton outside the source workspace\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (root: string, opts: AuditOpenSpecOptions) => {\n      const json = opts.json === true;\n      try {\n        const inventory = await inventoryOpenSpec(root);\n        const skeleton = createOpenSpecMappingSkeleton(inventory);\n        const mappingWritten = opts.writeMapping === undefined\n          ? null\n          : await writeMappingSkeleton(inventory, opts.writeMapping, skeleton);\n        if (json) {\n          emitJson({\n            command: \"audit-openspec\",\n            readOnly: mappingWritten === null,\n            mappingWritten,\n            mappingSkeleton: skeleton,\n            ...inventory,\n          });\n        } else {\n          printInventory(inventory, \"audit\");\n          if (mappingWritten !== null) console.log(`\\n  mapping skeleton  ${mappingWritten}`);\n          else console.log(\"\\n  read-only audit: no files were created or changed\");\n        }\n        // Finding incompatibilities is a successful audit result. Root/YAML/IO\n        // failures still exit 1 through the catch below; migration readiness has\n        // its own boolean and migrate-openspec exit status.\n      } catch (error) {\n        reportCommandError(json, error);\n      }\n    });\n\n  program\n    .command(\"migrate-openspec\")\n    .argument(\"<root>\", \"OpenSpec root, Store checkout, or workspace containing openspec/\")\n    .description(\"Validate explicit migration mappings and optionally materialize staged migration docs\")\n    .option(\"--map <path>\", \"YAML mapping created from `audit-openspec --write-mapping`\")\n    .option(\"--mapping <path>\", \"deprecated alias for --map\")\n    .option(\"--apply\", \"materialize staged migration docs; dry-run is the default\")\n    .option(\"--target <directory>\", \"empty standalone target for --apply; never writes into the OpenSpec source or live loam docs\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (root: string, opts: MigrateOpenSpecOptions) => {\n      const json = opts.json === true;\n      try {\n        if (opts.map !== undefined && opts.mapping !== undefined) {\n          throw new OpenSpecCommandError(\"invalid-option\", \"Pass --map or its deprecated --mapping alias, not both.\");\n        }\n        const mapArg = opts.map ?? opts.mapping;\n        if (mapArg === undefined) {\n          throw new OpenSpecCommandError(\n            \"invalid-option\",\n            \"migrate-openspec requires --map <path>; run `loam audit-openspec <root> --write-mapping <path>` first.\",\n          );\n        }\n        if (opts.apply === true && opts.target === undefined) {\n          throw new OpenSpecCommandError(\"invalid-option\", \"--apply requires an explicit --target <empty-directory>.\");\n        }\n        if (opts.apply !== true && opts.target !== undefined) {\n          throw new OpenSpecCommandError(\"invalid-option\", \"--target only has effect with explicit --apply.\");\n        }\n        const mappingPath = resolve(mapArg);\n        const mapping = await readMapping(mappingPath);\n        // Re-audit the source at the point of use. inventoryOpenSpec compares\n        // the fresh digest and canonical root to the binding in the mapping.\n        const inventory = await inventoryOpenSpec(root, { mapping });\n        const target = opts.apply === true\n          ? resolve(opts.target!)\n          : join(dirname(mappingPath), \".loam-openspec-dry-run-target\");\n        const planned = inventory.ready\n          ? await planMigrationWrites(inventory, mapping, target)\n          : null;\n        let applied: { directory: string; files: string[]; followUpBlockers: string[] } | null = null;\n        if (opts.apply === true) {\n          if (!inventory.ready || planned === null) {\n            throw new OpenSpecCommandError(\n              \"invalid-option\",\n              \"Migration cannot be applied until living/active shapes, capability mappings, change-to-feature decisions, active RENAMED identities, authored artifact dispositions, and source digest binding are resolved.\",\n            );\n          }\n          applied = await writeMigrationTarget(inventory, mapping, target, planned);\n        }\n\n        if (json) {\n          emitJson({\n            command: \"migrate-openspec\",\n            dryRun: applied === null,\n            mappingPath,\n            applied,\n            ...inventory,\n          });\n        } else {\n          printInventory(inventory, \"migration\");\n          if (applied === null) console.log(\"\\n  dry-run: no files were created or changed\");\n          else {\n            console.log(`\\n  staged migration docs  ${applied.directory}`);\n            console.log(`  follow-up blockers      ${applied.followUpBlockers.length} (see FOLLOW-UP.md)`);\n          }\n        }\n        if (!inventory.ready) process.exitCode = 1;\n      } catch (error) {\n        reportCommandError(json, error);\n      }\n    });\n}\n\nfunction reportCommandError(json: boolean, error: unknown): void {\n  if (error instanceof OpenSpecRootError) {\n    fail(json, \"unknown-target\", error.message);\n    return;\n  }\n  if (error instanceof OpenSpecCommandError) {\n    fail(json, error.code, error.message);\n    return;\n  }\n  throw error;\n}\n"]}