@crewhaus/migration-runner 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Section 28 — `migration-runner`. Walks every spec in a `spec-registry`,
+ * applies the registered migration chain, and writes new versions while
+ * leaving old versions intact for rollback. Dry-run mode shows the diff
+ * per spec before any write happens.
+ *
+ * Re-running with the same `(fromVersion, toVersion)` is a no-op once the
+ * target version exists in the registry — the runner skips specs whose
+ * latest version is already at or beyond `toVersion`.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import type { MigrationEngine, SpecObject } from "@crewhaus/migration-engine";
+import type { RegistryAdapter } from "@crewhaus/spec-registry";
+export declare class MigrationRunnerError extends CrewhausError {
+    readonly name = "MigrationRunnerError";
+    constructor(message: string, cause?: unknown);
+}
+export type MigrationPlanItem = {
+    readonly name: string;
+    readonly latestVersion: string;
+    readonly action: "skip" | "migrate" | "validate-fail";
+    readonly newVersion?: string;
+    readonly diff?: {
+        fromVersion: number;
+        toVersion: number;
+    };
+    readonly error?: string;
+};
+export type MigrateAllOptions = {
+    readonly registry: RegistryAdapter;
+    readonly engine: MigrationEngine;
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    /** When true, no writes happen — only the plan is returned. */
+    readonly dryRun?: boolean;
+    /**
+     * Optional post-migration validator. If provided, the runner refuses to
+     * write a spec that fails validation; the plan item carries the error.
+     */
+    readonly validate?: (spec: SpecObject, name: string) => void;
+    /** Custom new-version naming. Default: append `-vN`. */
+    readonly newVersionName?: (latest: string, toVersion: number) => string;
+};
+export type MigrateAllResult = {
+    readonly plan: ReadonlyArray<MigrationPlanItem>;
+    readonly migrated: number;
+    readonly skipped: number;
+    readonly failed: number;
+};
+export declare function migrateAll(opts: MigrateAllOptions): Promise<MigrateAllResult>;

package/dist/index.js

@@ -0,0 +1,106 @@
+/**
+ * Section 28 — `migration-runner`. Walks every spec in a `spec-registry`,
+ * applies the registered migration chain, and writes new versions while
+ * leaving old versions intact for rollback. Dry-run mode shows the diff
+ * per spec before any write happens.
+ *
+ * Re-running with the same `(fromVersion, toVersion)` is a no-op once the
+ * target version exists in the registry — the runner skips specs whose
+ * latest version is already at or beyond `toVersion`.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+export class MigrationRunnerError extends CrewhausError {
+    name = "MigrationRunnerError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+const DEFAULT_NEW_VERSION = (latest, toVersion) => {
+    const m = latest.match(/^v(\d+)$/);
+    if (m)
+        return `v${(Number.parseInt(m[1] ?? "0", 10) || 0) + 1}`;
+    return `${latest}-v${toVersion}`;
+};
+export async function migrateAll(opts) {
+    const newVersionName = opts.newVersionName ?? DEFAULT_NEW_VERSION;
+    const specs = await opts.registry.listSpecs();
+    const plan = [];
+    for (const name of specs) {
+        const versions = [...(await opts.registry.list(name))].sort();
+        if (versions.length === 0)
+            continue;
+        const latest = versions[versions.length - 1];
+        if (!latest)
+            continue;
+        const yaml = await opts.registry.get(name, latest);
+        let parsed;
+        try {
+            parsed = parseYaml(yaml);
+        }
+        catch (err) {
+            plan.push({
+                name,
+                latestVersion: latest,
+                action: "validate-fail",
+                error: `parse error: ${err.message}`,
+            });
+            continue;
+        }
+        const currentVersion = (parsed.version ?? 0) | 0;
+        if (currentVersion >= opts.toVersion) {
+            plan.push({ name, latestVersion: latest, action: "skip" });
+            continue;
+        }
+        let migrated;
+        try {
+            migrated = opts.engine.migrate(parsed, opts.toVersion);
+        }
+        catch (err) {
+            plan.push({
+                name,
+                latestVersion: latest,
+                action: "validate-fail",
+                error: `migration error: ${err.message}`,
+            });
+            continue;
+        }
+        if (opts.validate) {
+            try {
+                opts.validate(migrated, name);
+            }
+            catch (err) {
+                plan.push({
+                    name,
+                    latestVersion: latest,
+                    action: "validate-fail",
+                    error: `validation: ${err.message}`,
+                });
+                continue;
+            }
+        }
+        const newVersion = newVersionName(latest, opts.toVersion);
+        plan.push({
+            name,
+            latestVersion: latest,
+            action: "migrate",
+            newVersion,
+            diff: { fromVersion: currentVersion, toVersion: opts.toVersion },
+        });
+        if (!opts.dryRun) {
+            const migratedYaml = stringifyYaml(migrated);
+            await opts.registry.put(name, newVersion, migratedYaml);
+        }
+    }
+    // Refuse to apply if any spec failed validation in non-dry-run mode.
+    const failed = plan.filter((p) => p.action === "validate-fail").length;
+    if (failed > 0 && !opts.dryRun) {
+        throw new MigrationRunnerError(`${failed} spec(s) failed migration; run with dryRun: true to inspect`);
+    }
+    return {
+        plan,
+        migrated: plan.filter((p) => p.action === "migrate").length,
+        skipped: plan.filter((p) => p.action === "skip").length,
+        failed,
+    };
+}

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@crewhaus/migration-runner",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Batch-migrate every spec in a registry: dry-run + write, idempotent re-runs",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4",
-    "@crewhaus/migration-engine": "0.1.4",
-    "@crewhaus/spec-registry": "0.1.4",
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/migration-engine": "0.1.5",
+    "@crewhaus/spec-registry": "0.1.5",
     "yaml": "^2.6.0"
   },
   "license": "Apache-2.0",
@@ -35,5 +38,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.coverage.test.ts

@@ -1,204 +0,0 @@
-/**
- * Supplementary coverage for `migration-runner` exercising the branches the
- * happy-path file-backed suite (`index.test.ts`) does not reach:
- *  - the default `-vN` naming fallback for a non-`vN` latest version,
- *  - a custom `newVersionName`,
- *  - the YAML parse-error plan item,
- *  - the engine-migration-error plan item,
- *  - the non-dry-run refusal that throws `MigrationRunnerError`,
- *  - specs with no versions / empty latest being skipped.
- *
- * Everything runs against a pure in-memory `RegistryAdapter` — no filesystem,
- * no network, no timers, no real clock — so it is fully deterministic and
- * leaks no handles.
- */
-import { describe, expect, test } from "bun:test";
-import { createDefaultEngine } from "@crewhaus/migration-engine";
-import type { MigrationEngine, SpecObject } from "@crewhaus/migration-engine";
-import type { RegistryAdapter } from "@crewhaus/spec-registry";
-import { MigrationRunnerError, migrateAll } from "./index";
-
-/**
- * Minimal in-memory registry. `data` maps spec name -> (version -> yaml).
- * Versions returned by `list` preserve insertion order; `migrateAll` sorts
- * them itself.
- */
-function memRegistry(initial: Record<string, Record<string, string>> = {}): RegistryAdapter & {
-  data: Map<string, Map<string, string>>;
-} {
-  const data = new Map<string, Map<string, string>>();
-  for (const [name, versions] of Object.entries(initial)) {
-    data.set(name, new Map(Object.entries(versions)));
-  }
-  // `migrateAll` only ever touches listSpecs/list/get/put; the remaining
-  // RegistryAdapter members are intentionally absent (never called here).
-  return {
-    data,
-    async listSpecs() {
-      return [...data.keys()];
-    },
-    async list(name: string) {
-      return [...(data.get(name)?.keys() ?? [])];
-    },
-    async get(name: string, version: string) {
-      const v = data.get(name)?.get(version);
-      if (v === undefined) throw new Error(`ENOENT ${name}@${version}`);
-      return v;
-    },
-    async put(name: string, version: string, yaml: string) {
-      const m = data.get(name) ?? new Map<string, string>();
-      m.set(version, yaml);
-      data.set(name, m);
-    },
-  } as unknown as RegistryAdapter & { data: Map<string, Map<string, string>> };
-}
-
-describe("migration-runner — default new-version naming fallback", () => {
-  test("non-vN latest version names the new version `<latest>-v<toVersion>`", async () => {
-    // latest is "release-2024" which does NOT match /^v(\d+)$/, so the
-    // DEFAULT_NEW_VERSION fallback branch runs.
-    const reg = memRegistry({
-      a: { "release-2024": "name: a\ntarget: cli\nversion: 0\n" },
-    });
-    const engine = createDefaultEngine();
-    const result = await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    expect(result.migrated).toBe(1);
-    expect(result.plan[0]?.newVersion).toBe("release-2024-v1");
-    // The write landed under the fallback name, preserving the original.
-    expect([...(reg.data.get("a")?.keys() ?? [])].sort()).toEqual([
-      "release-2024",
-      "release-2024-v1",
-    ]);
-  });
-});
-
-describe("migration-runner — custom newVersionName", () => {
-  test("a caller-supplied namer overrides the default", async () => {
-    const reg = memRegistry({
-      a: { v1: "name: a\ntarget: cli\nversion: 0\n" },
-    });
-    const engine = createDefaultEngine();
-    const seen: Array<{ latest: string; to: number }> = [];
-    const result = await migrateAll({
-      registry: reg,
-      engine,
-      fromVersion: 0,
-      toVersion: 1,
-      newVersionName: (latest, to) => {
-        seen.push({ latest, to });
-        return `${latest}__migrated`;
-      },
-    });
-    expect(result.migrated).toBe(1);
-    expect(result.plan[0]?.newVersion).toBe("v1__migrated");
-    expect(seen).toEqual([{ latest: "v1", to: 1 }]);
-  });
-});
-
-describe("migration-runner — parse-error plan item", () => {
-  test("a spec whose latest YAML does not parse becomes a validate-fail (dry-run)", async () => {
-    const reg = memRegistry({
-      broken: { v1: "{ this is not valid yaml" },
-    });
-    const engine = createDefaultEngine();
-    const result = await migrateAll({
-      registry: reg,
-      engine,
-      fromVersion: 0,
-      toVersion: 1,
-      dryRun: true,
-    });
-    expect(result.failed).toBe(1);
-    expect(result.plan[0]?.action).toBe("validate-fail");
-    expect(result.plan[0]?.error).toContain("parse error:");
-  });
-});
-
-describe("migration-runner — engine migration error plan item", () => {
-  test("an unregistered migration step becomes a validate-fail (dry-run)", async () => {
-    const reg = memRegistry({
-      a: { v1: "name: a\ntarget: cli\nversion: 0\n" },
-    });
-    // Engine with NO steps registered -> migrate(0 -> 2) throws inside migrateAll.
-    const emptyEngine = createDefaultEngine();
-    emptyEngine.clear();
-    const result = await migrateAll({
-      registry: reg,
-      engine: emptyEngine,
-      fromVersion: 0,
-      toVersion: 2,
-      dryRun: true,
-    });
-    expect(result.failed).toBe(1);
-    expect(result.plan[0]?.action).toBe("validate-fail");
-    expect(result.plan[0]?.error).toContain("migration error:");
-  });
-});
-
-describe("migration-runner — non-dry-run refusal", () => {
-  test("write mode throws MigrationRunnerError when any spec fails", async () => {
-    const reg = memRegistry({
-      good: { v1: "name: good\ntarget: cli\nversion: 0\n" },
-      bad: { v1: "{ broken yaml" },
-    });
-    const engine = createDefaultEngine();
-    await expect(
-      migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 }),
-    ).rejects.toBeInstanceOf(MigrationRunnerError);
-  });
-
-  test("the thrown error names how many specs failed", async () => {
-    const reg = memRegistry({
-      bad: { v1: "{ broken yaml" },
-    });
-    const engine = createDefaultEngine();
-    let caught: Error | undefined;
-    try {
-      await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(MigrationRunnerError);
-    expect(caught?.message).toContain("1 spec(s) failed migration");
-  });
-});
-
-describe("migration-runner — skip already-migrated and empty specs", () => {
-  test("a spec already at/above the target version is skipped", async () => {
-    const reg = memRegistry({
-      a: { v1: "name: a\ntarget: cli\nversion: 5\n" },
-    });
-    const engine = createDefaultEngine();
-    const result = await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    expect(result.skipped).toBe(1);
-    expect(result.migrated).toBe(0);
-    expect(result.plan[0]?.action).toBe("skip");
-  });
-
-  test("a spec with no versions at all is skipped silently (no plan item)", async () => {
-    const reg = memRegistry();
-    // Register the spec name but give it zero versions.
-    reg.data.set("empty", new Map());
-    const engine = createDefaultEngine();
-    const result = await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    expect(result.plan.length).toBe(0);
-    expect(result.migrated).toBe(0);
-    expect(result.skipped).toBe(0);
-    expect(result.failed).toBe(0);
-  });
-
-  test("a spec whose sorted latest is an empty-string version is skipped", async () => {
-    // versions === [""] -> latest === "" which is falsy, so the `!latest`
-    // guard `continue`s before any get/parse.
-    const reg = memRegistry();
-    reg.data.set("blank", new Map([["", "name: blank\n"]]));
-    const engine = createDefaultEngine();
-    const result = await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    expect(result.plan.length).toBe(0);
-  });
-});
-
-// Keep a no-op reference to the imported types so the file documents intent
-// without unused-import noise.
-const _typeRefs: { e?: MigrationEngine; s?: SpecObject } = {};
-void _typeRefs;

package/src/index.test.ts

@@ -1,118 +0,0 @@
-/**
- * Section 28 — `migration-runner` tests:
- *  - T3 dry-run + write cycle on fixture registry
- *  - T9 idempotence (re-running yields zero changes)
- */
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createDefaultEngine } from "@crewhaus/migration-engine";
-import { createFileBackedRegistry } from "@crewhaus/spec-registry";
-import { migrateAll } from "./index";
-
-let tmpRoot = "";
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), "migration-runner-test-"));
-});
-
-afterEach(() => {
-  rmSync(tmpRoot, { recursive: true, force: true });
-});
-
-describe("migration-runner — T3 dry-run + write cycle", () => {
-  test("plan includes every spec at the source version", async () => {
-    const reg = createFileBackedRegistry({ rootDir: tmpRoot });
-    const engine = createDefaultEngine();
-    await reg.put(
-      "a",
-      "v1",
-      "name: a\ntarget: cli\nversion: 0\nagent:\n  model: x\n  instructions: y\n",
-    );
-    await reg.put(
-      "b",
-      "v1",
-      "name: b\ntarget: cli\nversion: 0\nagent:\n  model: x\n  instructions: y\n",
-    );
-    const result = await migrateAll({
-      registry: reg,
-      engine,
-      fromVersion: 0,
-      toVersion: 1,
-      dryRun: true,
-    });
-    expect(result.migrated).toBe(2);
-    expect(result.plan.every((p) => p.action === "migrate")).toBe(true);
-  });
-
-  test("dry-run does not write new versions", async () => {
-    const reg = createFileBackedRegistry({ rootDir: tmpRoot });
-    const engine = createDefaultEngine();
-    await reg.put(
-      "a",
-      "v1",
-      "name: a\ntarget: cli\nversion: 0\nagent:\n  model: x\n  instructions: y\n",
-    );
-    await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1, dryRun: true });
-    expect(await reg.list("a")).toEqual(["v1"]);
-  });
-
-  test("write mode adds a new version while preserving old", async () => {
-    const reg = createFileBackedRegistry({ rootDir: tmpRoot });
-    const engine = createDefaultEngine();
-    await reg.put(
-      "a",
-      "v1",
-      "name: a\ntarget: cli\nversion: 0\nagent:\n  model: x\n  instructions: y\n",
-    );
-    await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    const versions = [...(await reg.list("a"))].sort();
-    expect(versions).toEqual(["v1", "v2"]);
-    const v2 = await reg.get("a", "v2");
-    expect(v2).toContain("version: 1");
-  });
-
-  test("validate hook can reject migrated spec", async () => {
-    const reg = createFileBackedRegistry({ rootDir: tmpRoot });
-    const engine = createDefaultEngine();
-    await reg.put(
-      "good",
-      "v1",
-      "name: good\ntarget: cli\nversion: 0\nagent:\n  model: x\n  instructions: y\n",
-    );
-    await reg.put(
-      "bad",
-      "v1",
-      "name: bad\ntarget: cli\nversion: 0\nagent:\n  model: x\n  instructions: y\n",
-    );
-    const result = await migrateAll({
-      registry: reg,
-      engine,
-      fromVersion: 0,
-      toVersion: 1,
-      dryRun: true,
-      validate: (_spec, name) => {
-        if (name === "bad") throw new Error("forbidden");
-      },
-    });
-    expect(result.failed).toBe(1);
-    expect(result.migrated).toBe(1);
-  });
-});
-
-describe("migration-runner — T9 idempotence", () => {
-  test("re-running with same target version skips already-migrated specs", async () => {
-    const reg = createFileBackedRegistry({ rootDir: tmpRoot });
-    const engine = createDefaultEngine();
-    await reg.put(
-      "a",
-      "v1",
-      "name: a\ntarget: cli\nversion: 0\nagent:\n  model: x\n  instructions: y\n",
-    );
-    await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    const second = await migrateAll({ registry: reg, engine, fromVersion: 0, toVersion: 1 });
-    expect(second.migrated).toBe(0);
-    expect(second.skipped).toBe(1);
-  });
-});

package/src/index.ts

@@ -1,142 +0,0 @@
-/**
- * Section 28 — `migration-runner`. Walks every spec in a `spec-registry`,
- * applies the registered migration chain, and writes new versions while
- * leaving old versions intact for rollback. Dry-run mode shows the diff
- * per spec before any write happens.
- *
- * Re-running with the same `(fromVersion, toVersion)` is a no-op once the
- * target version exists in the registry — the runner skips specs whose
- * latest version is already at or beyond `toVersion`.
- */
-import { CrewhausError } from "@crewhaus/errors";
-import type { MigrationEngine, SpecObject } from "@crewhaus/migration-engine";
-import type { RegistryAdapter } from "@crewhaus/spec-registry";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-
-export class MigrationRunnerError extends CrewhausError {
-  override readonly name = "MigrationRunnerError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export type MigrationPlanItem = {
-  readonly name: string;
-  readonly latestVersion: string;
-  readonly action: "skip" | "migrate" | "validate-fail";
-  readonly newVersion?: string;
-  readonly diff?: { fromVersion: number; toVersion: number };
-  readonly error?: string;
-};
-
-export type MigrateAllOptions = {
-  readonly registry: RegistryAdapter;
-  readonly engine: MigrationEngine;
-  readonly fromVersion: number;
-  readonly toVersion: number;
-  /** When true, no writes happen — only the plan is returned. */
-  readonly dryRun?: boolean;
-  /**
-   * Optional post-migration validator. If provided, the runner refuses to
-   * write a spec that fails validation; the plan item carries the error.
-   */
-  readonly validate?: (spec: SpecObject, name: string) => void;
-  /** Custom new-version naming. Default: append `-vN`. */
-  readonly newVersionName?: (latest: string, toVersion: number) => string;
-};
-
-export type MigrateAllResult = {
-  readonly plan: ReadonlyArray<MigrationPlanItem>;
-  readonly migrated: number;
-  readonly skipped: number;
-  readonly failed: number;
-};
-
-const DEFAULT_NEW_VERSION = (latest: string, toVersion: number): string => {
-  const m = latest.match(/^v(\d+)$/);
-  if (m) return `v${(Number.parseInt(m[1] ?? "0", 10) || 0) + 1}`;
-  return `${latest}-v${toVersion}`;
-};
-
-export async function migrateAll(opts: MigrateAllOptions): Promise<MigrateAllResult> {
-  const newVersionName = opts.newVersionName ?? DEFAULT_NEW_VERSION;
-  const specs = await opts.registry.listSpecs();
-  const plan: MigrationPlanItem[] = [];
-
-  for (const name of specs) {
-    const versions = [...(await opts.registry.list(name))].sort();
-    if (versions.length === 0) continue;
-    const latest = versions[versions.length - 1];
-    if (!latest) continue;
-    const yaml = await opts.registry.get(name, latest);
-    let parsed: SpecObject;
-    try {
-      parsed = parseYaml(yaml) as SpecObject;
-    } catch (err) {
-      plan.push({
-        name,
-        latestVersion: latest,
-        action: "validate-fail",
-        error: `parse error: ${(err as Error).message}`,
-      });
-      continue;
-    }
-    const currentVersion = (parsed.version ?? 0) | 0;
-    if (currentVersion >= opts.toVersion) {
-      plan.push({ name, latestVersion: latest, action: "skip" });
-      continue;
-    }
-    let migrated: SpecObject;
-    try {
-      migrated = opts.engine.migrate(parsed, opts.toVersion);
-    } catch (err) {
-      plan.push({
-        name,
-        latestVersion: latest,
-        action: "validate-fail",
-        error: `migration error: ${(err as Error).message}`,
-      });
-      continue;
-    }
-    if (opts.validate) {
-      try {
-        opts.validate(migrated, name);
-      } catch (err) {
-        plan.push({
-          name,
-          latestVersion: latest,
-          action: "validate-fail",
-          error: `validation: ${(err as Error).message}`,
-        });
-        continue;
-      }
-    }
-    const newVersion = newVersionName(latest, opts.toVersion);
-    plan.push({
-      name,
-      latestVersion: latest,
-      action: "migrate",
-      newVersion,
-      diff: { fromVersion: currentVersion, toVersion: opts.toVersion },
-    });
-    if (!opts.dryRun) {
-      const migratedYaml = stringifyYaml(migrated);
-      await opts.registry.put(name, newVersion, migratedYaml);
-    }
-  }
-
-  // Refuse to apply if any spec failed validation in non-dry-run mode.
-  const failed = plan.filter((p) => p.action === "validate-fail").length;
-  if (failed > 0 && !opts.dryRun) {
-    throw new MigrationRunnerError(
-      `${failed} spec(s) failed migration; run with dryRun: true to inspect`,
-    );
-  }
-
-  return {
-    plan,
-    migrated: plan.filter((p) => p.action === "migrate").length,
-    skipped: plan.filter((p) => p.action === "skip").length,
-    failed,
-  };
-}