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

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"]}

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

@@ -0,0 +1,49 @@
+/**
+ * Bytes out of somebody else's repository, decoded or refused by name.
+ *
+ * Every other phase reads its input through here rather than calling `readFile`
+ * itself, which is the point: the encoding rule below is one line of code, and
+ * the defect it prevents is a migration that reports success over requirements
+ * it silently dropped. A read added later to a materializer has to come through
+ * this module to reach the source at all.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { decodeDocument, NotUtf8DocumentError } from "../../../core/kernel/document-bytes.js";
+import { OpenSpecCommandError } from "./error.js";
+/**
+ * A document this command is about to migrate, decoded or refused BY NAME.
+ *
+ * Every other read on this path used `readFile(…, "utf8")`, which never fails:
+ * bytes that are not UTF-8 become U+FFFD and a UTF-16 spec.md becomes text with
+ * no headings in it. Downstream that is not a wrong answer but a silent one —
+ * `parseRequirements` returns [], the capability materializes as a `spec.md`
+ * with an empty `## Requirements`, and the migration reports success over a file
+ * whose every requirement was dropped. Migration is the one command whose input
+ * is somebody else's repository, written by tooling loam does not control, so
+ * this is where lossy decoding is both most likely and least acceptable.
+ *
+ * The ingest scan already refuses non-UTF-8 artifacts up front
+ * (`openspec.non-utf8-artifact`); holding the same rule at the point of use
+ * means a read added later cannot quietly skip it, and it is what catches the
+ * encoding the scan's `isUtf8` cannot see — UTF-16 written without a BOM, whose
+ * bytes are valid UTF-8 with a NUL between every character.
+ */
+export function decodeSource(bytes, path, label) {
+    try {
+        return decodeDocument(bytes, path);
+    }
+    catch (error) {
+        if (!(error instanceof NotUtf8DocumentError))
+            throw error;
+        // `error.message` already opens with the path; the label says which of the
+        // two inputs it is — the corpus being migrated, or the mapping about it.
+        throw new OpenSpecCommandError("invalid-option", `${label}: ${error.message}`);
+    }
+}
+/** A path under the audited OpenSpec root, decoded the same way. */
+export async function readSourceArtifact(root, artifactPath) {
+    const absolute = join(root, artifactPath);
+    return decodeSource(await readFile(absolute), absolute, "OpenSpec source artifact");
+}
+//# sourceMappingURL=read.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,IAAY,EAAE,KAAa;IACrE,IAAI,CAAC;QACH,OAAO,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,oBAAoB,CAAC;YAAE,MAAM,KAAK,CAAC;QAC1D,2EAA2E;QAC3E,yEAAyE;QACzE,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY,EAAE,YAAoB;IACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC1C,OAAO,YAAY,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,0BAA0B,CAAC,CAAC;AACtF,CAAC","sourcesContent":["/**\n * Bytes out of somebody else's repository, decoded or refused by name.\n *\n * Every other phase reads its input through here rather than calling `readFile`\n * itself, which is the point: the encoding rule below is one line of code, and\n * the defect it prevents is a migration that reports success over requirements\n * it silently dropped. A read added later to a materializer has to come through\n * this module to reach the source at all.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../../../core/kernel/document-bytes.js\";\nimport { OpenSpecCommandError } from \"./error.js\";\n\n/**\n * A document this command is about to migrate, decoded or refused BY NAME.\n *\n * Every other read on this path used `readFile(…, \"utf8\")`, which never fails:\n * bytes that are not UTF-8 become U+FFFD and a UTF-16 spec.md becomes text with\n * no headings in it. Downstream that is not a wrong answer but a silent one —\n * `parseRequirements` returns [], the capability materializes as a `spec.md`\n * with an empty `## Requirements`, and the migration reports success over a file\n * whose every requirement was dropped. Migration is the one command whose input\n * is somebody else's repository, written by tooling loam does not control, so\n * this is where lossy decoding is both most likely and least acceptable.\n *\n * The ingest scan already refuses non-UTF-8 artifacts up front\n * (`openspec.non-utf8-artifact`); holding the same rule at the point of use\n * means a read added later cannot quietly skip it, and it is what catches the\n * encoding the scan's `isUtf8` cannot see — UTF-16 written without a BOM, whose\n * bytes are valid UTF-8 with a NUL between every character.\n */\nexport function decodeSource(bytes: Buffer, path: string, label: string): string {\n  try {\n    return decodeDocument(bytes, path);\n  } catch (error) {\n    if (!(error instanceof NotUtf8DocumentError)) throw error;\n    // `error.message` already opens with the path; the label says which of the\n    // two inputs it is — the corpus being migrated, or the mapping about it.\n    throw new OpenSpecCommandError(\"invalid-option\", `${label}: ${error.message}`);\n  }\n}\n\n/** A path under the audited OpenSpec root, decoded the same way. */\nexport async function readSourceArtifact(root: string, artifactPath: string): Promise<string> {\n  const absolute = join(root, artifactPath);\n  return decodeSource(await readFile(absolute), absolute, \"OpenSpec source artifact\");\n}\n"]}