@crewhaus/migration-runner 0.1.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@crewhaus/migration-runner",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Batch-migrate every spec in a registry: dry-run + write, idempotent re-runs",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/migration-engine": "0.0.0",
+    "@crewhaus/spec-registry": "0.0.0",
+    "yaml": "^2.6.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/migration-runner"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/migration-runner#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,118 @@
+/**
+ * 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

@@ -0,0 +1,142 @@
+/**
+ * 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,
+  };
+}