@crewhaus/deployment-controller 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crewhaus/deployment-controller",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/audit-log": "0.0.0",
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/spec-registry": "0.0.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/deployment-controller"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/deployment-controller#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,100 @@
+/**
+ * Section 28 — `deployment-controller` tests:
+ *  - T3 promote + rollback round-trip with audit-log assertions
+ */
+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 { type AuditRecord, openAuditLog } from "@crewhaus/audit-log";
+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");
+  });
+});

package/src/index.ts

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