@crewhaus/deployment-controller 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Section 28 — `deployment-controller`. Promote / rollback over the
+ * §28 spec-registry. Records every action to the §20 audit-log under
+ * `kind: "deployment_action"` so the chain becomes the deploy history.
+ *
+ *   promote(name, fromEnv, toEnv)  copies the source-env's pinned
+ *                                  version to the destination env.
+ *   rollback(name, env, version)   re-pins the env to a known prior version.
+ *
+ * Both throw cleanly when the source pin doesn't exist or the rollback
+ * version isn't in the registry.
+ */
+import type { AuditLog } from "@crewhaus/audit-log";
+import { CrewhausError } from "@crewhaus/errors";
+import type { RegistryAdapter } from "@crewhaus/spec-registry";
+export declare class DeploymentError extends CrewhausError {
+    readonly name = "DeploymentError";
+    constructor(message: string, cause?: unknown);
+}
+export type DeploymentRecordPayload = {
+    readonly action: "promote" | "rollback";
+    readonly name: string;
+    readonly fromEnv?: string;
+    readonly toEnv?: string;
+    readonly env?: string;
+    readonly fromVersion?: string;
+    readonly toVersion: string;
+    readonly tenantId?: string;
+    readonly actor?: string;
+    readonly ts: number;
+};
+export type DeploymentControllerOptions = {
+    readonly registry: RegistryAdapter;
+    readonly auditLog?: AuditLog;
+    /** Optional tenant scope. */
+    readonly tenantId?: string;
+    /** Identifier (user / service) audit-logged with each action. */
+    readonly actor?: string;
+};
+export interface DeploymentController {
+    promote(name: string, fromEnv: string, toEnv: string): Promise<DeploymentRecordPayload>;
+    rollback(name: string, env: string, version: string): Promise<DeploymentRecordPayload>;
+}
+export declare function createDeploymentController(opts: DeploymentControllerOptions): DeploymentController;

package/dist/index.js

@@ -0,0 +1,76 @@
+import { CrewhausError } from "@crewhaus/errors";
+export class DeploymentError extends CrewhausError {
+    name = "DeploymentError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export function createDeploymentController(opts) {
+    async function audit(payload) {
+        if (!opts.auditLog)
+            return;
+        await opts.auditLog.append({
+            kind: "deployment_action",
+            payload,
+        });
+    }
+    return {
+        async promote(name, fromEnv, toEnv) {
+            const sourceVersion = opts.tenantId
+                ? await opts.registry.aliasForTenant(opts.tenantId, name, fromEnv)
+                : await opts.registry.aliasFor(name, fromEnv);
+            if (!sourceVersion) {
+                throw new DeploymentError(`cannot promote ${name}: ${fromEnv} has no pin to copy from`);
+            }
+            const previousTo = opts.tenantId
+                ? await opts.registry.aliasForTenant(opts.tenantId, name, toEnv)
+                : await opts.registry.aliasFor(name, toEnv);
+            if (opts.tenantId) {
+                await opts.registry.pinForTenant(opts.tenantId, name, toEnv, sourceVersion);
+            }
+            else {
+                await opts.registry.pin(name, toEnv, sourceVersion);
+            }
+            const record = {
+                action: "promote",
+                name,
+                fromEnv,
+                toEnv,
+                ...(previousTo !== undefined ? { fromVersion: previousTo } : {}),
+                toVersion: sourceVersion,
+                ...(opts.tenantId !== undefined ? { tenantId: opts.tenantId } : {}),
+                ...(opts.actor !== undefined ? { actor: opts.actor } : {}),
+                ts: Date.now(),
+            };
+            await audit(record);
+            return record;
+        },
+        async rollback(name, env, version) {
+            const all = await opts.registry.list(name);
+            if (!all.includes(version)) {
+                throw new DeploymentError(`cannot rollback ${name} ${env} → ${version}: version not in registry`);
+            }
+            const previous = opts.tenantId
+                ? await opts.registry.aliasForTenant(opts.tenantId, name, env)
+                : await opts.registry.aliasFor(name, env);
+            if (opts.tenantId) {
+                await opts.registry.pinForTenant(opts.tenantId, name, env, version);
+            }
+            else {
+                await opts.registry.pin(name, env, version);
+            }
+            const record = {
+                action: "rollback",
+                name,
+                env,
+                ...(previous !== undefined ? { fromVersion: previous } : {}),
+                toVersion: version,
+                ...(opts.tenantId !== undefined ? { tenantId: opts.tenantId } : {}),
+                ...(opts.actor !== undefined ? { actor: opts.actor } : {}),
+                ts: Date.now(),
+            };
+            await audit(record);
+            return record;
+        },
+    };
+}

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@crewhaus/deployment-controller",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Version pinning + promotion: promote(name, fromEnv, toEnv) / rollback. Records every action to audit-log.",
-  "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/audit-log": "0.1.3",
-    "@crewhaus/errors": "0.1.3",
-    "@crewhaus/spec-registry": "0.1.3"
+    "@crewhaus/audit-log": "0.1.5",
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/spec-registry": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -34,5 +37,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,221 +0,0 @@
-/**
- * Section 28 — `deployment-controller` tests:
- *  - T3 promote + rollback round-trip with audit-log assertions
- *  - tenant-scoped promote/rollback overlay isolation
- *  - audit-after-pin ordering + payload-shape regression guards (mocked)
- */
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { AppendInput, AuditLog, AuditRecord } from "@crewhaus/audit-log";
-import { openAuditLog } from "@crewhaus/audit-log";
-import type { RegistryAdapter } from "@crewhaus/spec-registry";
-import { createFileBackedRegistry } from "@crewhaus/spec-registry";
-import { DeploymentError, createDeploymentController } from "./index";
-
-let tmpRoot = "";
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), "deploy-test-"));
-});
-
-afterEach(() => {
-  rmSync(tmpRoot, { recursive: true, force: true });
-});
-
-async function readAudit(rootDir: string): Promise<AuditRecord[]> {
-  const log = await openAuditLog({ rootDir });
-  const out: AuditRecord[] = [];
-  for await (const r of log.read()) out.push(r);
-  return out;
-}
-
-describe("deployment-controller — T3 promote/rollback", () => {
-  test("promote copies pin from staging to prod", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    await reg.put("hello", "v2", "y");
-    await reg.pin("hello", "staging", "v2");
-    const audit = await openAuditLog({ rootDir: join(tmpRoot, "audit") });
-    const ctrl = createDeploymentController({ registry: reg, auditLog: audit, actor: "alice" });
-    const rec = await ctrl.promote("hello", "staging", "prod");
-    expect(rec.action).toBe("promote");
-    expect(rec.toVersion).toBe("v2");
-    expect(rec.fromVersion).toBeUndefined();
-    expect(await reg.aliasFor("hello", "prod")).toBe("v2");
-    const records = await readAudit(join(tmpRoot, "audit"));
-    expect(records.length).toBe(1);
-    expect(records[0]?.kind).toBe("deployment_action");
-  });
-
-  test("promote captures previous prod pin in fromVersion", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    await reg.put("hello", "v2", "y");
-    await reg.pin("hello", "staging", "v2");
-    await reg.pin("hello", "prod", "v1");
-    const ctrl = createDeploymentController({ registry: reg });
-    const rec = await ctrl.promote("hello", "staging", "prod");
-    expect(rec.fromVersion).toBe("v1");
-    expect(rec.toVersion).toBe("v2");
-  });
-
-  test("rollback re-pins to a known prior version", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    await reg.put("hello", "v2", "y");
-    await reg.pin("hello", "prod", "v2");
-    const audit = await openAuditLog({ rootDir: join(tmpRoot, "audit") });
-    const ctrl = createDeploymentController({ registry: reg, auditLog: audit });
-    const rec = await ctrl.rollback("hello", "prod", "v1");
-    expect(rec.action).toBe("rollback");
-    expect(rec.fromVersion).toBe("v2");
-    expect(rec.toVersion).toBe("v1");
-    expect(await reg.aliasFor("hello", "prod")).toBe("v1");
-  });
-
-  test("promote without source pin throws", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    const ctrl = createDeploymentController({ registry: reg });
-    expect(ctrl.promote("hello", "staging", "prod")).rejects.toBeInstanceOf(DeploymentError);
-  });
-
-  test("rollback to unknown version throws", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    const ctrl = createDeploymentController({ registry: reg });
-    expect(ctrl.rollback("hello", "prod", "v999")).rejects.toBeInstanceOf(DeploymentError);
-  });
-
-  test("tenant-scoped controller writes only tenant overlay, not global", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    await reg.put("hello", "v2", "y");
-    await reg.pin("hello", "staging", "v2");
-    await reg.pin("hello", "prod", "v1");
-    const ctrl = createDeploymentController({ registry: reg, tenantId: "tenant-a" });
-    await ctrl.promote("hello", "staging", "prod");
-    // Global prod stays at v1; tenant-a overlay points to v2.
-    expect(await reg.aliasFor("hello", "prod")).toBe("v1");
-    expect(await reg.aliasForTenant("tenant-a", "hello", "prod")).toBe("v2");
-  });
-
-  test("tenant-scoped rollback re-pins only the tenant overlay and tags the record", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    await reg.put("hello", "v2", "y");
-    await reg.pin("hello", "prod", "v2"); // global prod = v2
-    await reg.pinForTenant("tenant-a", "hello", "prod", "v2"); // tenant prod = v2
-    const ctrl = createDeploymentController({
-      registry: reg,
-      tenantId: "tenant-a",
-      actor: "bob",
-    });
-    const rec = await ctrl.rollback("hello", "prod", "v1");
-    expect(rec.action).toBe("rollback");
-    expect(rec.fromVersion).toBe("v2"); // previous tenant alias captured
-    expect(rec.toVersion).toBe("v1");
-    expect(rec.tenantId).toBe("tenant-a");
-    expect(rec.actor).toBe("bob");
-    // Global prod is untouched; only the tenant overlay rolled back.
-    expect(await reg.aliasFor("hello", "prod")).toBe("v2");
-    expect(await reg.aliasForTenant("tenant-a", "hello", "prod")).toBe("v1");
-  });
-
-  test("rollback with no prior pin omits fromVersion", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    // No pin for `prod` yet.
-    const ctrl = createDeploymentController({ registry: reg });
-    const rec = await ctrl.rollback("hello", "prod", "v1");
-    expect(rec.fromVersion).toBeUndefined();
-    expect(rec.toVersion).toBe("v1");
-    expect(await reg.aliasFor("hello", "prod")).toBe("v1");
-  });
-
-  test("promote audit payload carries tenantId + actor and the deployment_action kind", async () => {
-    const reg = createFileBackedRegistry({ rootDir: join(tmpRoot, "specs") });
-    await reg.put("hello", "v1", "x");
-    await reg.pin("hello", "staging", "v1");
-    const appended: AppendInput[] = [];
-    const auditLog: AuditLog = {
-      append: mock(async (input: AppendInput): Promise<AuditRecord> => {
-        appended.push(input);
-        return {
-          ts: 0,
-          version: 1,
-          kind: input.kind,
-          seq: 0,
-          payload: input.payload,
-          prevHash: "",
-          hash: "",
-        };
-      }),
-      read: () => {
-        throw new Error("read should not be called");
-      },
-    };
-    const ctrl = createDeploymentController({
-      registry: reg,
-      auditLog,
-      tenantId: "tenant-a",
-      actor: "carol",
-    });
-    const rec = await ctrl.promote("hello", "staging", "prod");
-    expect(appended.length).toBe(1);
-    expect(appended[0]?.kind).toBe("deployment_action");
-    expect(appended[0]?.payload).toBe(rec); // the exact record is audit-logged
-    expect(rec.tenantId).toBe("tenant-a");
-    expect(rec.actor).toBe("carol");
-  });
-
-  test("audit is appended only AFTER the registry pin succeeds (no misleading history)", async () => {
-    const calls: string[] = [];
-    const pinError = new Error("pin failed: storage down");
-    // Minimal RegistryAdapter mock; only the methods promote() touches are real.
-    const reg: RegistryAdapter = {
-      aliasFor: mock(async (): Promise<string | undefined> => {
-        calls.push("aliasFor");
-        return "v2";
-      }),
-      pin: mock(async (): Promise<void> => {
-        calls.push("pin");
-        throw pinError;
-      }),
-      // Unused by this path — present to satisfy the interface.
-      put: async () => {},
-      get: async () => "",
-      list: async () => [],
-      listSpecs: async () => [],
-      delete: async () => {},
-      manifest: async () => ({ versions: [], pins: {} }),
-      pinForTenant: async () => {},
-      aliasForTenant: async () => undefined,
-    };
-    const auditAppend = mock(async (input: AppendInput): Promise<AuditRecord> => {
-      calls.push("audit");
-      return {
-        ts: 0,
-        version: 1,
-        kind: input.kind,
-        seq: 0,
-        payload: input.payload,
-        prevHash: "",
-        hash: "",
-      };
-    });
-    const auditLog: AuditLog = {
-      append: auditAppend,
-      read: () => {
-        throw new Error("read should not be called");
-      },
-    };
-    const ctrl = createDeploymentController({ registry: reg, auditLog });
-    await expect(ctrl.promote("hello", "staging", "prod")).rejects.toBe(pinError);
-    // The pin threw, so NO audit record was written for the failed deploy.
-    expect(auditAppend).not.toHaveBeenCalled();
-    expect(calls).toEqual(["aliasFor", "aliasFor", "pin"]);
-  });
-});

package/src/index.ts

@@ -1,122 +0,0 @@
-/**
- * Section 28 — `deployment-controller`. Promote / rollback over the
- * §28 spec-registry. Records every action to the §20 audit-log under
- * `kind: "deployment_action"` so the chain becomes the deploy history.
- *
- *   promote(name, fromEnv, toEnv)  copies the source-env's pinned
- *                                  version to the destination env.
- *   rollback(name, env, version)   re-pins the env to a known prior version.
- *
- * Both throw cleanly when the source pin doesn't exist or the rollback
- * version isn't in the registry.
- */
-import type { AuditLog } from "@crewhaus/audit-log";
-import { CrewhausError } from "@crewhaus/errors";
-import type { RegistryAdapter } from "@crewhaus/spec-registry";
-
-export class DeploymentError extends CrewhausError {
-  override readonly name = "DeploymentError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export type DeploymentRecordPayload = {
-  readonly action: "promote" | "rollback";
-  readonly name: string;
-  readonly fromEnv?: string;
-  readonly toEnv?: string;
-  readonly env?: string;
-  readonly fromVersion?: string;
-  readonly toVersion: string;
-  readonly tenantId?: string;
-  readonly actor?: string;
-  readonly ts: number;
-};
-
-export type DeploymentControllerOptions = {
-  readonly registry: RegistryAdapter;
-  readonly auditLog?: AuditLog;
-  /** Optional tenant scope. */
-  readonly tenantId?: string;
-  /** Identifier (user / service) audit-logged with each action. */
-  readonly actor?: string;
-};
-
-export interface DeploymentController {
-  promote(name: string, fromEnv: string, toEnv: string): Promise<DeploymentRecordPayload>;
-  rollback(name: string, env: string, version: string): Promise<DeploymentRecordPayload>;
-}
-
-export function createDeploymentController(
-  opts: DeploymentControllerOptions,
-): DeploymentController {
-  async function audit(payload: DeploymentRecordPayload): Promise<void> {
-    if (!opts.auditLog) return;
-    await opts.auditLog.append({
-      kind: "deployment_action",
-      payload,
-    });
-  }
-
-  return {
-    async promote(name, fromEnv, toEnv): Promise<DeploymentRecordPayload> {
-      const sourceVersion = opts.tenantId
-        ? await opts.registry.aliasForTenant(opts.tenantId, name, fromEnv)
-        : await opts.registry.aliasFor(name, fromEnv);
-      if (!sourceVersion) {
-        throw new DeploymentError(`cannot promote ${name}: ${fromEnv} has no pin to copy from`);
-      }
-      const previousTo = opts.tenantId
-        ? await opts.registry.aliasForTenant(opts.tenantId, name, toEnv)
-        : await opts.registry.aliasFor(name, toEnv);
-      if (opts.tenantId) {
-        await opts.registry.pinForTenant(opts.tenantId, name, toEnv, sourceVersion);
-      } else {
-        await opts.registry.pin(name, toEnv, sourceVersion);
-      }
-      const record: DeploymentRecordPayload = {
-        action: "promote",
-        name,
-        fromEnv,
-        toEnv,
-        ...(previousTo !== undefined ? { fromVersion: previousTo } : {}),
-        toVersion: sourceVersion,
-        ...(opts.tenantId !== undefined ? { tenantId: opts.tenantId } : {}),
-        ...(opts.actor !== undefined ? { actor: opts.actor } : {}),
-        ts: Date.now(),
-      };
-      await audit(record);
-      return record;
-    },
-
-    async rollback(name, env, version): Promise<DeploymentRecordPayload> {
-      const all = await opts.registry.list(name);
-      if (!all.includes(version)) {
-        throw new DeploymentError(
-          `cannot rollback ${name} ${env} → ${version}: version not in registry`,
-        );
-      }
-      const previous = opts.tenantId
-        ? await opts.registry.aliasForTenant(opts.tenantId, name, env)
-        : await opts.registry.aliasFor(name, env);
-      if (opts.tenantId) {
-        await opts.registry.pinForTenant(opts.tenantId, name, env, version);
-      } else {
-        await opts.registry.pin(name, env, version);
-      }
-      const record: DeploymentRecordPayload = {
-        action: "rollback",
-        name,
-        env,
-        ...(previous !== undefined ? { fromVersion: previous } : {}),
-        toVersion: version,
-        ...(opts.tenantId !== undefined ? { tenantId: opts.tenantId } : {}),
-        ...(opts.actor !== undefined ? { actor: opts.actor } : {}),
-        ts: Date.now(),
-      };
-      await audit(record);
-      return record;
-    },
-  };
-}