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

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 { parseRequirements } from \"../../../core/document/parse.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      parseRequirements(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"]}

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

@@ -0,0 +1,91 @@
+/**
+ * The mapping document on the way out: the blank skeleton `audit-openspec`
+ * offers, the normalized record `migrate-openspec --apply` writes beside the
+ * staged docs, and the one query that reads a decision back.
+ *
+ * `selectedServices` belongs here rather than beside either materializer
+ * because it is the single spelling of the routing rule. It was written out
+ * twice once — once on the living side and once on the delta side — and the two
+ * copies drifted, so a split capability routed a living requirement and its own
+ * delta to different services. Both materializers now call this one.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { dictionary, ownValue } from "../../../core/kernel/records.js";
+import {} from "../../../core/openspec/model/mapping.js";
+import {} from "../../../core/openspec/model/model.js";
+import { OpenSpecCommandError } from "./error.js";
+import { canonicalForCreate, contains } from "./paths.js";
+export async function writeMappingSkeleton(inventory, outputArg, skeleton) {
+    const output = resolve(outputArg);
+    const canonicalOutput = await canonicalForCreate(output);
+    const canonicalSource = await realpath(inventory.inputRoot);
+    if (contains(canonicalSource, canonicalOutput)) {
+        throw new OpenSpecCommandError("invalid-option", `Refusing to write the mapping inside the OpenSpec source workspace: ${output}`);
+    }
+    if (existsSync(output)) {
+        throw new OpenSpecCommandError("already-exists", `Mapping output already exists; refusing to overwrite it: ${output}`);
+    }
+    await mkdir(dirname(output), { recursive: true });
+    try {
+        await writeFile(output, stringifyYaml(skeleton, { lineWidth: 0 }), { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (existsSync(output)) {
+            throw new OpenSpecCommandError("already-exists", `Mapping output already exists; refusing to overwrite it: ${output}`);
+        }
+        throw error;
+    }
+    return output;
+}
+export function normalizedMapping(inventory, mapping) {
+    return {
+        version: 1,
+        source: { root: inventory.root, inventoryDigest: inventory.inventoryDigest },
+        capabilities: Object.fromEntries(inventory.mappingDecisions.map((decision) => [
+            decision.capability,
+            {
+                services: ownValue(mapping.capabilities, decision.capability)?.services ?? [],
+                requirementServices: ownValue(mapping.capabilities, decision.capability)?.requirementServices ?? dictionary(),
+            },
+        ])),
+        changes: Object.fromEntries(inventory.changeDecisions.map((decision) => [
+            decision.change,
+            {
+                feature: ownValue(mapping.changes, decision.change)?.feature ?? null,
+                // The decision's title, which is the mapping's own title trimmed.
+                // `readMapping` (`./mapping.ts`) trims `feature` but not `title`, and
+                // materialization writes the trimmed one into the frontmatter, the H1
+                // and the directory slug — so recording the raw one made the plan
+                // disagree with the files beside it about what the feature is called.
+                title: decision.title,
+            },
+        ])),
+        renames: Object.fromEntries(inventory.renamed
+            .filter((rename) => rename.scope === "active")
+            .map((rename) => [rename.key, {
+                from: rename.from,
+                to: rename.to,
+                existingRequirementId: rename.existingRequirementId,
+                requirementId: rename.requirementId,
+            }])),
+        artifacts: Object.fromEntries(inventory.artifactDecisions.map((decision) => [
+            decision.path,
+            {
+                kind: decision.kind,
+                disposition: ownValue(mapping.artifacts, decision.path) ?? null,
+            },
+        ])),
+    };
+}
+export function selectedServices(mapping, capability, requirement) {
+    const selected = ownValue(mapping.capabilities, capability);
+    if (selected === undefined)
+        return [];
+    return selected.services.length === 1
+        ? selected.services
+        : ownValue(selected.requirementServices, requirement) ?? [];
+}
+//# sourceMappingURL=decisions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/decisions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The mapping document on the way out: the blank skeleton `audit-openspec`\n * offers, the normalized record `migrate-openspec --apply` writes beside the\n * staged docs, and the one query that reads a decision back.\n *\n * `selectedServices` belongs here rather than beside either materializer\n * because it is the single spelling of the routing rule. It was written out\n * twice once — once on the living side and once on the delta side — and the two\n * copies drifted, so a split capability routed a living requirement and its own\n * delta to different services. Both materializers now call this one.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir, realpath, writeFile } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { stringify as stringifyYaml } from \"yaml\";\nimport { dictionary, ownValue } from \"../../../core/kernel/records.js\";\nimport { type OpenSpecMapping, type OpenSpecMappingSkeleton } from \"../../../core/openspec/model/mapping.js\";\nimport { type OpenSpecInventory } from \"../../../core/openspec/model/model.js\";\nimport { OpenSpecCommandError } from \"./error.js\";\nimport { canonicalForCreate, contains } from \"./paths.js\";\n\nexport async function writeMappingSkeleton(\n  inventory: OpenSpecInventory,\n  outputArg: string,\n  skeleton: OpenSpecMappingSkeleton,\n): Promise<string> {\n  const output = resolve(outputArg);\n  const canonicalOutput = await canonicalForCreate(output);\n  const canonicalSource = await realpath(inventory.inputRoot);\n  if (contains(canonicalSource, canonicalOutput)) {\n    throw new OpenSpecCommandError(\n      \"invalid-option\",\n      `Refusing to write the mapping inside the OpenSpec source workspace: ${output}`,\n    );\n  }\n  if (existsSync(output)) {\n    throw new OpenSpecCommandError(\"already-exists\", `Mapping output already exists; refusing to overwrite it: ${output}`);\n  }\n  await mkdir(dirname(output), { recursive: true });\n  try {\n    await writeFile(output, stringifyYaml(skeleton, { lineWidth: 0 }), { encoding: \"utf8\", flag: \"wx\" });\n  } catch (error) {\n    if (existsSync(output)) {\n      throw new OpenSpecCommandError(\"already-exists\", `Mapping output already exists; refusing to overwrite it: ${output}`);\n    }\n    throw error;\n  }\n  return output;\n}\n\nexport function normalizedMapping(inventory: OpenSpecInventory, mapping: OpenSpecMapping): Record<string, unknown> {\n  return {\n    version: 1,\n    source: { root: inventory.root, inventoryDigest: inventory.inventoryDigest },\n    capabilities: Object.fromEntries(inventory.mappingDecisions.map((decision) => [\n      decision.capability,\n      {\n        services: ownValue(mapping.capabilities, decision.capability)?.services ?? [],\n        requirementServices: ownValue(mapping.capabilities, decision.capability)?.requirementServices ?? dictionary(),\n      },\n    ])),\n    changes: Object.fromEntries(inventory.changeDecisions.map((decision) => [\n      decision.change,\n      {\n        feature: ownValue(mapping.changes, decision.change)?.feature ?? null,\n        // The decision's title, which is the mapping's own title trimmed.\n        // `readMapping` (`./mapping.ts`) trims `feature` but not `title`, and\n        // materialization writes the trimmed one into the frontmatter, the H1\n        // and the directory slug — so recording the raw one made the plan\n        // disagree with the files beside it about what the feature is called.\n        title: decision.title,\n      },\n    ])),\n    renames: Object.fromEntries(\n      inventory.renamed\n        .filter((rename) => rename.scope === \"active\")\n        .map((rename) => [rename.key, {\n          from: rename.from,\n          to: rename.to,\n          existingRequirementId: rename.existingRequirementId,\n          requirementId: rename.requirementId,\n        }]),\n    ),\n    artifacts: Object.fromEntries(inventory.artifactDecisions.map((decision) => [\n      decision.path,\n      {\n        kind: decision.kind,\n          disposition: ownValue(mapping.artifacts, decision.path) ?? null,\n      },\n    ])),\n  };\n}\n\nexport function selectedServices(\n  mapping: OpenSpecMapping,\n  capability: string,\n  requirement: string,\n): string[] {\n  const selected = ownValue(mapping.capabilities, capability);\n  if (selected === undefined) return [];\n  return selected.services.length === 1\n    ? selected.services\n    : ownValue(selected.requirementServices, requirement) ?? [];\n}\n"]}

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

@@ -0,0 +1,19 @@
+import {} from "../../../core/envelope/json.js";
+/**
+ * The one refusal shape both verbs raise, in a module of its own.
+ *
+ * It cannot live beside the commander wiring that catches it: every phase of a
+ * migration throws it, and a phase that imported the wiring to reach it would
+ * put the command's registration on the evaluation path of the modules being
+ * registered. So the error is the package's lowest leaf, and the wiring — which
+ * maps it onto an exit code in `reportCommandError` — sits above everything.
+ */
+export class OpenSpecCommandError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "OpenSpecCommandError";
+    }
+}
+//# sourceMappingURL=error.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,MAAM,gCAAgC,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACxB,IAAI;IAAzB,YAAqB,IAAe,EAAE,OAAe;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;oBADI,IAAI;QAEvB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF","sourcesContent":["import { type ErrorCode } from \"../../../core/envelope/json.js\";\n\n/**\n * The one refusal shape both verbs raise, in a module of its own.\n *\n * It cannot live beside the commander wiring that catches it: every phase of a\n * migration throws it, and a phase that imported the wiring to reach it would\n * put the command's registration on the evaluation path of the modules being\n * registered. So the error is the package's lowest leaf, and the wiring — which\n * maps it onto an exit code in `reportCommandError` — sits above everything.\n */\nexport class OpenSpecCommandError extends Error {\n  constructor(readonly code: ErrorCode, message: string) {\n    super(message);\n    this.name = \"OpenSpecCommandError\";\n  }\n}\n"]}

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

@@ -0,0 +1,170 @@
+/**
+ * The mapping document on the way in: YAML a human edited, graded into an
+ * `OpenSpecMapping` or refused with the line to fix.
+ *
+ * Split from `./decisions.ts`, which is the same document on the way out — the
+ * blank skeleton, the normalized record written beside a migration, and the
+ * routing query. Reading is where every refusal lives and writing is where none
+ * do, so the two halves have almost no vocabulary in common beyond the type.
+ */
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { serviceIdProblem } from "../../../core/kernel/ids/service.js";
+import { asRecord, dictionary } from "../../../core/kernel/records.js";
+import {} from "../../../core/openspec/model/mapping.js";
+import { message } from "../../../core/staging/commit.js";
+import { OpenSpecCommandError } from "./error.js";
+import { decodeSource } from "./read.js";
+/**
+ * `Array.isArray` narrows an `unknown` to `any[]`, so the element check below it
+ * proved nothing to tsc and the elements had to be asserted back to `string` at
+ * the point of use. One predicate makes the narrowing carry the check.
+ */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function stringList(value, label) {
+    if (typeof value === "string")
+        return value.trim() === "" ? [] : [value.trim()];
+    if (!isStringArray(value)) {
+        throw new OpenSpecCommandError("invalid-option", `${label} must be a string or an array of service ids.`);
+    }
+    return [...new Set(value.map((item) => item.trim()).filter(Boolean))];
+}
+/**
+ * The service ids a mapping may name, checked against the ONE grammar.
+ *
+ * This used to carry its own copy of the rule — the same alphabet regex, the
+ * `.`/`..` tests, the trailing dot and the Windows device names — which is how
+ * the two spellings drifted apart to begin with: for a while migrate was the
+ * STRICTER of the two, so the primary authoring path accepted ids a migration
+ * refused. ids.ts owns the grammar now, so a mapping can only ever name a
+ * `services/<id>/` the authoring commands can still address.
+ *
+ * The refusal keeps migrate's own shape — `OpenSpecCommandError` with
+ * `invalid-option`, not an `Issue` — and `serviceIdProblem`'s label carries the
+ * mapping key, so the message still points at the line of the YAML to edit.
+ */
+function serviceList(value, label) {
+    const services = stringList(value, label);
+    for (const service of services) {
+        const problem = serviceIdProblem(service, label);
+        if (problem !== null)
+            throw new OpenSpecCommandError("invalid-option", problem);
+    }
+    return services;
+}
+export async function readMapping(path) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch (error) {
+        throw new OpenSpecCommandError("unknown-target", `Cannot read OpenSpec mapping ${path}: ${message(error)}`);
+    }
+    // Decoded rather than assumed: a mapping saved as UTF-16 parses as YAML with
+    // no capabilities block, and the refusal would name a missing decision
+    // instead of the encoding that hid it.
+    const raw = decodeSource(bytes, path, "OpenSpec mapping");
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (error) {
+        throw new OpenSpecCommandError("invalid-option", `OpenSpec mapping ${path} is invalid YAML: ${message(error)}`);
+    }
+    const document = asRecord(parsed);
+    if (document === null || document.version !== 1) {
+        throw new OpenSpecCommandError("invalid-option", `OpenSpec mapping ${path} must be a YAML mapping with version: 1.`);
+    }
+    const sourceNode = asRecord(document.source);
+    const source = sourceNode !== null
+        && typeof sourceNode.root === "string"
+        && typeof sourceNode.inventoryDigest === "string"
+        ? { root: sourceNode.root, inventoryDigest: sourceNode.inventoryDigest }
+        : null;
+    const capabilitiesNode = asRecord(document.capabilities);
+    if (capabilitiesNode === null) {
+        throw new OpenSpecCommandError("invalid-option", `OpenSpec mapping ${path} must contain a capabilities mapping.`);
+    }
+    const capabilities = dictionary();
+    for (const [capability, value] of Object.entries(capabilitiesNode)) {
+        const record = asRecord(value);
+        const services = serviceList(record?.services ?? value, `capabilities.${capability}.services`);
+        const requirementServices = dictionary();
+        if (record?.requirementServices !== undefined) {
+            const allocations = asRecord(record.requirementServices);
+            if (allocations === null) {
+                throw new OpenSpecCommandError("invalid-option", `capabilities.${capability}.requirementServices must be a mapping.`);
+            }
+            for (const [requirement, selected] of Object.entries(allocations)) {
+                requirementServices[requirement] = serviceList(selected, `capabilities.${capability}.requirementServices.${requirement}`);
+            }
+        }
+        capabilities[capability] = { services, requirementServices };
+    }
+    const changesNode = asRecord(document.changes);
+    if (changesNode === null) {
+        throw new OpenSpecCommandError("invalid-option", `OpenSpec mapping ${path} must contain a changes mapping.`);
+    }
+    const changes = dictionary();
+    for (const [change, value] of Object.entries(changesNode)) {
+        const record = asRecord(value);
+        if (record === null) {
+            throw new OpenSpecCommandError("invalid-option", `changes.${change} must be a mapping with explicit feature and title fields.`);
+        }
+        const featureValue = record.feature;
+        if (featureValue !== null && typeof featureValue !== "string") {
+            throw new OpenSpecCommandError("invalid-option", `changes.${change}.feature must be a string or null.`);
+        }
+        if (typeof record.title !== "string") {
+            throw new OpenSpecCommandError("invalid-option", `changes.${change}.title must be a string.`);
+        }
+        changes[change] = {
+            feature: typeof featureValue === "string" && featureValue.trim() !== "" ? featureValue.trim() : null,
+            title: record.title,
+        };
+    }
+    const renames = dictionary();
+    if (document.renames !== undefined) {
+        const renamesNode = asRecord(document.renames);
+        if (renamesNode === null) {
+            throw new OpenSpecCommandError("invalid-option", `OpenSpec mapping ${path} renames must be a mapping.`);
+        }
+        for (const [key, value] of Object.entries(renamesNode)) {
+            const record = asRecord(value);
+            const requirementId = record !== null && "requirementId" in record ? record.requirementId : value;
+            // A freshly generated skeleton deliberately uses null: it remains a
+            // needsIdentity decision rather than becoming a malformed mapping.
+            if (requirementId === null || requirementId === "")
+                continue;
+            if (typeof requirementId !== "string") {
+                throw new OpenSpecCommandError("invalid-option", `renames.${key}.requirementId must be a string or null.`);
+            }
+            renames[key] = requirementId.trim();
+        }
+    }
+    // Recorded as written. Naming the disposition union here only meant asserting
+    // an unreviewed string into it: `mapping.invalid-artifact-disposition` is what
+    // actually grades this value, and it has to see what the human typed to be
+    // able to name it back to them.
+    const artifacts = dictionary();
+    if (document.artifacts !== undefined) {
+        const artifactsNode = asRecord(document.artifacts);
+        if (artifactsNode === null) {
+            throw new OpenSpecCommandError("invalid-option", `OpenSpec mapping ${path} artifacts must be a mapping.`);
+        }
+        for (const [artifactPath, value] of Object.entries(artifactsNode)) {
+            const record = asRecord(value);
+            const disposition = record !== null && "disposition" in record ? record.disposition : value;
+            if (disposition === null || disposition === "")
+                continue;
+            if (typeof disposition !== "string") {
+                throw new OpenSpecCommandError("invalid-option", `artifacts.${artifactPath}.disposition must be a string or null.`);
+            }
+            artifacts[artifactPath] = disposition;
+        }
+    }
+    return { source, capabilities, changes, renames, artifacts };
+}
+//# sourceMappingURL=mapping.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/mapping.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The mapping document on the way in: YAML a human edited, graded into an\n * `OpenSpecMapping` or refused with the line to fix.\n *\n * Split from `./decisions.ts`, which is the same document on the way out — the\n * blank skeleton, the normalized record written beside a migration, and the\n * routing query. Reading is where every refusal lives and writing is where none\n * do, so the two halves have almost no vocabulary in common beyond the type.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYaml } from \"yaml\";\nimport { serviceIdProblem } from \"../../../core/kernel/ids/service.js\";\nimport { asRecord, dictionary } from \"../../../core/kernel/records.js\";\nimport { type OpenSpecMapping } from \"../../../core/openspec/model/mapping.js\";\nimport { message } from \"../../../core/staging/commit.js\";\nimport { OpenSpecCommandError } from \"./error.js\";\nimport { decodeSource } from \"./read.js\";\n\n/**\n * `Array.isArray` narrows an `unknown` to `any[]`, so the element check below it\n * proved nothing to tsc and the elements had to be asserted back to `string` at\n * the point of use. One predicate makes the narrowing carry the check.\n */\nfunction isStringArray(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === \"string\");\n}\n\nfunction stringList(value: unknown, label: string): string[] {\n  if (typeof value === \"string\") return value.trim() === \"\" ? [] : [value.trim()];\n  if (!isStringArray(value)) {\n    throw new OpenSpecCommandError(\"invalid-option\", `${label} must be a string or an array of service ids.`);\n  }\n  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];\n}\n\n/**\n * The service ids a mapping may name, checked against the ONE grammar.\n *\n * This used to carry its own copy of the rule — the same alphabet regex, the\n * `.`/`..` tests, the trailing dot and the Windows device names — which is how\n * the two spellings drifted apart to begin with: for a while migrate was the\n * STRICTER of the two, so the primary authoring path accepted ids a migration\n * refused. ids.ts owns the grammar now, so a mapping can only ever name a\n * `services/<id>/` the authoring commands can still address.\n *\n * The refusal keeps migrate's own shape — `OpenSpecCommandError` with\n * `invalid-option`, not an `Issue` — and `serviceIdProblem`'s label carries the\n * mapping key, so the message still points at the line of the YAML to edit.\n */\nfunction serviceList(value: unknown, label: string): string[] {\n  const services = stringList(value, label);\n  for (const service of services) {\n    const problem = serviceIdProblem(service, label);\n    if (problem !== null) throw new OpenSpecCommandError(\"invalid-option\", problem);\n  }\n  return services;\n}\n\nexport async function readMapping(path: string): Promise<OpenSpecMapping> {\n  let bytes: Buffer;\n  try {\n    bytes = await readFile(path);\n  } catch (error) {\n    throw new OpenSpecCommandError(\"unknown-target\", `Cannot read OpenSpec mapping ${path}: ${message(error)}`);\n  }\n  // Decoded rather than assumed: a mapping saved as UTF-16 parses as YAML with\n  // no capabilities block, and the refusal would name a missing decision\n  // instead of the encoding that hid it.\n  const raw = decodeSource(bytes, path, \"OpenSpec mapping\");\n  let parsed: unknown;\n  try {\n    parsed = parseYaml(raw);\n  } catch (error) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} is invalid YAML: ${message(error)}`);\n  }\n  const document = asRecord(parsed);\n  if (document === null || document.version !== 1) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must be a YAML mapping with version: 1.`);\n  }\n  const sourceNode = asRecord(document.source);\n  const source = sourceNode !== null\n    && typeof sourceNode.root === \"string\"\n    && typeof sourceNode.inventoryDigest === \"string\"\n    ? { root: sourceNode.root, inventoryDigest: sourceNode.inventoryDigest }\n    : null;\n  const capabilitiesNode = asRecord(document.capabilities);\n  if (capabilitiesNode === null) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must contain a capabilities mapping.`);\n  }\n  const capabilities = dictionary<OpenSpecMapping[\"capabilities\"][string]>();\n  for (const [capability, value] of Object.entries(capabilitiesNode)) {\n    const record = asRecord(value);\n    const services = serviceList(record?.services ?? value, `capabilities.${capability}.services`);\n    const requirementServices = dictionary<string[]>();\n    if (record?.requirementServices !== undefined) {\n      const allocations = asRecord(record.requirementServices);\n      if (allocations === null) {\n        throw new OpenSpecCommandError(\n          \"invalid-option\",\n          `capabilities.${capability}.requirementServices must be a mapping.`,\n        );\n      }\n      for (const [requirement, selected] of Object.entries(allocations)) {\n        requirementServices[requirement] = serviceList(\n          selected,\n          `capabilities.${capability}.requirementServices.${requirement}`,\n        );\n      }\n    }\n    capabilities[capability] = { services, requirementServices };\n  }\n\n  const changesNode = asRecord(document.changes);\n  if (changesNode === null) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must contain a changes mapping.`);\n  }\n  const changes = dictionary<OpenSpecMapping[\"changes\"][string]>();\n  for (const [change, value] of Object.entries(changesNode)) {\n    const record = asRecord(value);\n    if (record === null) {\n      throw new OpenSpecCommandError(\n        \"invalid-option\",\n        `changes.${change} must be a mapping with explicit feature and title fields.`,\n      );\n    }\n    const featureValue = record.feature;\n    if (featureValue !== null && typeof featureValue !== \"string\") {\n      throw new OpenSpecCommandError(\"invalid-option\", `changes.${change}.feature must be a string or null.`);\n    }\n    if (typeof record.title !== \"string\") {\n      throw new OpenSpecCommandError(\"invalid-option\", `changes.${change}.title must be a string.`);\n    }\n    changes[change] = {\n      feature: typeof featureValue === \"string\" && featureValue.trim() !== \"\" ? featureValue.trim() : null,\n      title: record.title,\n    };\n  }\n\n  const renames = dictionary<string>();\n  if (document.renames !== undefined) {\n    const renamesNode = asRecord(document.renames);\n    if (renamesNode === null) {\n      throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} renames must be a mapping.`);\n    }\n    for (const [key, value] of Object.entries(renamesNode)) {\n      const record = asRecord(value);\n      const requirementId = record !== null && \"requirementId\" in record ? record.requirementId : value;\n      // A freshly generated skeleton deliberately uses null: it remains a\n      // needsIdentity decision rather than becoming a malformed mapping.\n      if (requirementId === null || requirementId === \"\") continue;\n      if (typeof requirementId !== \"string\") {\n        throw new OpenSpecCommandError(\"invalid-option\", `renames.${key}.requirementId must be a string or null.`);\n      }\n      renames[key] = requirementId.trim();\n    }\n  }\n  // Recorded as written. Naming the disposition union here only meant asserting\n  // an unreviewed string into it: `mapping.invalid-artifact-disposition` is what\n  // actually grades this value, and it has to see what the human typed to be\n  // able to name it back to them.\n  const artifacts = dictionary<string>();\n  if (document.artifacts !== undefined) {\n    const artifactsNode = asRecord(document.artifacts);\n    if (artifactsNode === null) {\n      throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} artifacts must be a mapping.`);\n    }\n    for (const [artifactPath, value] of Object.entries(artifactsNode)) {\n      const record = asRecord(value);\n      const disposition = record !== null && \"disposition\" in record ? record.disposition : value;\n      if (disposition === null || disposition === \"\") continue;\n      if (typeof disposition !== \"string\") {\n        throw new OpenSpecCommandError(\"invalid-option\", `artifacts.${artifactPath}.disposition must be a string or null.`);\n      }\n      artifacts[artifactPath] = disposition;\n    }\n  }\n  return { source, capabilities, changes, renames, artifacts };\n}\n"]}

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

@@ -0,0 +1,43 @@
+/**
+ * The path arithmetic every write decision in this command rests on.
+ *
+ * Three rules, kept together because they answer one question in two
+ * directions: is a path inside a tree it must stay out of (`contains`), what
+ * tree is it really in once symlinks are resolved (`canonicalForCreate`), and
+ * does a path claimed by the OpenSpec source stay inside the directory it was
+ * listed under (`safeArtifactRelative`). `materialize/stage.ts` builds the
+ * staging refusals out of the first two; `openspec/decisions.ts` uses them to
+ * keep a mapping skeleton out of the workspace it describes.
+ */
+import { existsSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { OpenSpecCommandError } from "./error.js";
+export function contains(parent, candidate) {
+    const rel = relative(parent, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+/** Resolve symlinks in the nearest existing ancestor of a not-yet-created path. */
+export async function canonicalForCreate(path) {
+    let cursor = path;
+    const suffix = [];
+    while (!existsSync(cursor)) {
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        suffix.unshift(basename(cursor));
+        cursor = parent;
+    }
+    return resolve(await realpath(cursor), ...suffix);
+}
+export function safeArtifactRelative(artifactPath, prefix, owner) {
+    if (!artifactPath.startsWith(prefix)) {
+        throw new OpenSpecCommandError("invalid-option", `${owner} contains an artifact outside its own directory: ${artifactPath}.`);
+    }
+    const segments = artifactPath.slice(prefix.length).split("/");
+    if (segments.length === 0 || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new OpenSpecCommandError("invalid-option", `OpenSpec artifact has an unsafe relative path: ${artifactPath}.`);
+    }
+    return segments;
+}
+//# sourceMappingURL=paths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,SAAiB;IACxD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IACnD,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,MAAM;YAAE,MAAM;QAC7B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACjC,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,YAAoB,EAAE,MAAc,EAAE,KAAa;IACtF,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,oBAAoB,CAC5B,gBAAgB,EAChB,GAAG,KAAK,oDAAoD,YAAY,GAAG,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/G,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,kDAAkD,YAAY,GAAG,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The path arithmetic every write decision in this command rests on.\n *\n * Three rules, kept together because they answer one question in two\n * directions: is a path inside a tree it must stay out of (`contains`), what\n * tree is it really in once symlinks are resolved (`canonicalForCreate`), and\n * does a path claimed by the OpenSpec source stay inside the directory it was\n * listed under (`safeArtifactRelative`). `materialize/stage.ts` builds the\n * staging refusals out of the first two; `openspec/decisions.ts` uses them to\n * keep a mapping skeleton out of the workspace it describes.\n */\nimport { existsSync } from \"node:fs\";\nimport { realpath } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, relative, resolve, sep } from \"node:path\";\nimport { OpenSpecCommandError } from \"./error.js\";\n\nexport function contains(parent: string, candidate: string): boolean {\n  const rel = relative(parent, candidate);\n  return rel === \"\" || (!rel.startsWith(`..${sep}`) && rel !== \"..\" && !isAbsolute(rel));\n}\n\n/** Resolve symlinks in the nearest existing ancestor of a not-yet-created path. */\nexport async function canonicalForCreate(path: string): Promise<string> {\n  let cursor = path;\n  const suffix: string[] = [];\n  while (!existsSync(cursor)) {\n    const parent = dirname(cursor);\n    if (parent === cursor) break;\n    suffix.unshift(basename(cursor));\n    cursor = parent;\n  }\n  return resolve(await realpath(cursor), ...suffix);\n}\n\nexport function safeArtifactRelative(artifactPath: string, prefix: string, owner: string): string[] {\n  if (!artifactPath.startsWith(prefix)) {\n    throw new OpenSpecCommandError(\n      \"invalid-option\",\n      `${owner} contains an artifact outside its own directory: ${artifactPath}.`,\n    );\n  }\n  const segments = artifactPath.slice(prefix.length).split(\"/\");\n  if (segments.length === 0 || segments.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\")) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec artifact has an unsafe relative path: ${artifactPath}.`);\n  }\n  return segments;\n}\n"]}