@crewhaus/cloud-adapter-heroku 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crewhaus/cloud-adapter-heroku",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "One-click deploy adapter for Heroku — generates a heroku.yml + app.json + Dockerfile and wraps the Heroku Platform API for daemon target shapes (Section 44)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/docker-images": "0.0.0",
+    "@crewhaus/errors": "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/cloud-adapter-heroku"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/cloud-adapter-heroku#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,260 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  HEROKU_DEFAULT_API_BASE,
+  HEROKU_TARGET_SHAPES,
+  HerokuAdapterError,
+  appJsonFor,
+  deployToHeroku,
+  herokuDockerfileFor,
+  herokuYmlFor,
+  isHerokuTargetShape,
+  scrubApiKey,
+} from "./index";
+
+const API_KEY_ENV = "HEROKU_API_KEY";
+
+describe("isHerokuTargetShape", () => {
+  test("accepts daemon shapes", () => {
+    for (const shape of HEROKU_TARGET_SHAPES) {
+      expect(isHerokuTargetShape(shape)).toBe(true);
+    }
+  });
+  test("rejects one-shot shapes", () => {
+    for (const shape of ["cli", "workflow", "eval", "graph", "pipeline", "crew", "research"]) {
+      expect(isHerokuTargetShape(shape)).toBe(false);
+    }
+  });
+});
+
+describe("herokuYmlFor", () => {
+  test("web shape gets web process", () => {
+    const yml = herokuYmlFor({ target: "channel" });
+    expect(yml).toContain("build:");
+    expect(yml).toContain("docker:");
+    expect(yml).toContain("web: Dockerfile.heroku");
+    expect(yml).toContain("run:");
+    expect(yml).toContain("web: bun run start");
+  });
+
+  test("batch shape gets worker process", () => {
+    const yml = herokuYmlFor({ target: "batch" });
+    expect(yml).toContain("worker: Dockerfile.heroku");
+    expect(yml).toContain("worker: bun run start");
+    expect(yml).not.toContain("web:");
+  });
+
+  test("respects dockerfile path override", () => {
+    const yml = herokuYmlFor({ target: "channel", dockerfilePath: "Dockerfile.prod" });
+    expect(yml).toContain("web: Dockerfile.prod");
+  });
+
+  test("rejects unsupported shapes", () => {
+    expect(() => herokuYmlFor({ target: "cli" })).toThrow(HerokuAdapterError);
+  });
+});
+
+describe("appJsonFor", () => {
+  test("emits container stack with formation", () => {
+    const parsed = JSON.parse(appJsonFor({ target: "channel", name: "my-bot" }));
+    expect(parsed.stack).toBe("container");
+    expect(parsed.name).toBe("my-bot");
+    expect(parsed.formation.web).toEqual({ quantity: 1, size: "basic" });
+  });
+
+  test("worker shape gets worker formation", () => {
+    const parsed = JSON.parse(appJsonFor({ target: "batch", name: "my-worker" }));
+    expect(parsed.formation.worker).toEqual({ quantity: 1, size: "basic" });
+    expect(parsed.formation.web).toBeUndefined();
+  });
+
+  test("env vars are sorted deterministically", () => {
+    const a = appJsonFor({
+      target: "channel",
+      name: "my-bot",
+      envVars: {
+        ZETA: { value: "1" },
+        ALPHA: { value: "2" },
+      },
+    });
+    const b = appJsonFor({
+      target: "channel",
+      name: "my-bot",
+      envVars: {
+        ALPHA: { value: "2" },
+        ZETA: { value: "1" },
+      },
+    });
+    expect(a).toBe(b);
+    expect(a.indexOf('"ALPHA"')).toBeLessThan(a.indexOf('"ZETA"'));
+  });
+
+  test("respects dyno size and quantity", () => {
+    const parsed = JSON.parse(
+      appJsonFor({
+        target: "channel",
+        name: "my-bot",
+        dynoSize: "performance-m",
+        quantity: 3,
+      }),
+    );
+    expect(parsed.formation.web.size).toBe("performance-m");
+    expect(parsed.formation.web.quantity).toBe(3);
+  });
+
+  test("rejects invalid app names", () => {
+    expect(() => appJsonFor({ target: "channel", name: "MyBot" })).toThrow(HerokuAdapterError);
+    expect(() => appJsonFor({ target: "channel", name: "ab" })).toThrow(HerokuAdapterError);
+    expect(() => appJsonFor({ target: "channel", name: "1starts-with-digit" })).toThrow(
+      HerokuAdapterError,
+    );
+    expect(() => appJsonFor({ target: "channel", name: "trailing-" })).toThrow(HerokuAdapterError);
+  });
+
+  test("rejects unsupported shapes", () => {
+    expect(() => appJsonFor({ target: "cli", name: "my-bot" })).toThrow(HerokuAdapterError);
+  });
+});
+
+describe("herokuDockerfileFor", () => {
+  test("binds to runtime PORT", () => {
+    const df = herokuDockerfileFor({ target: "channel", baseImage: "crewhaus/channel:0.1.0" });
+    expect(df).toContain("FROM crewhaus/channel:0.1.0");
+    expect(df).toContain("ENV PORT=${PORT:-8080}");
+    expect(df).not.toContain("EXPOSE");
+  });
+
+  test("rejects unsupported shapes", () => {
+    expect(() => herokuDockerfileFor({ target: "cli", baseImage: "x" })).toThrow(
+      HerokuAdapterError,
+    );
+  });
+});
+
+describe("scrubApiKey", () => {
+  test("redacts the key", () => {
+    expect(scrubApiKey("auth hrk_abcdefghij12345 denied", "hrk_abcdefghij12345")).toBe(
+      "auth [REDACTED:HEROKU_API_KEY] denied",
+    );
+  });
+  test("ignores short keys", () => {
+    expect(scrubApiKey("untouched", "abc")).toBe("untouched");
+  });
+});
+
+describe("deployToHeroku", () => {
+  const ORIGINAL_KEY = process.env[API_KEY_ENV];
+  afterEach(() => {
+    if (ORIGINAL_KEY === undefined) delete process.env[API_KEY_ENV];
+    else process.env[API_KEY_ENV] = ORIGINAL_KEY;
+  });
+
+  test("creates an app with container stack", async () => {
+    let observed: { url: string; init: RequestInit } | undefined;
+    const fetchImpl = (async (url: string | URL, init?: RequestInit) => {
+      observed = { url: String(url), init: init ?? {} };
+      return new Response(
+        JSON.stringify({
+          id: "app-uuid-123",
+          name: "my-bot",
+          web_url: "https://my-bot.herokuapp.com/",
+        }),
+        { status: 201 },
+      );
+    }) as unknown as typeof fetch;
+    const record = await deployToHeroku({
+      appName: "my-bot",
+      apiKey: "hrk_testkey_abcdef",
+      fetchImpl,
+    });
+    expect(observed?.url).toBe(`${HEROKU_DEFAULT_API_BASE}/apps`);
+    const body = JSON.parse(String(observed?.init.body));
+    expect(body.stack).toBe("container");
+    expect(body.region).toBe("us");
+    expect((observed?.init.headers as Record<string, string>)["Accept"]).toBe(
+      "application/vnd.heroku+json; version=3",
+    );
+    expect(record.appId).toBe("app-uuid-123");
+    expect(record.appName).toBe("my-bot");
+    expect(record.webUrl).toBe("https://my-bot.herokuapp.com/");
+  });
+
+  test("respects region override", async () => {
+    let body: Record<string, unknown> = {};
+    const fetchImpl = (async (_url: string | URL, init?: RequestInit) => {
+      body = JSON.parse(String(init?.body));
+      return new Response(JSON.stringify({ id: "x", name: "my-bot" }), { status: 201 });
+    }) as unknown as typeof fetch;
+    await deployToHeroku({
+      appName: "my-bot",
+      region: "eu",
+      apiKey: "hrk_testkey_abcdef",
+      fetchImpl,
+    });
+    expect(body["region"]).toBe("eu");
+  });
+
+  test("scrubs API key from error bodies", async () => {
+    const fetchImpl = (async () =>
+      new Response("unauthorized — key hrk_leakingkey_full denied", {
+        status: 401,
+        statusText: "Unauthorized",
+      })) as unknown as typeof fetch;
+    let caught: Error | undefined;
+    try {
+      await deployToHeroku({
+        appName: "my-bot",
+        apiKey: "hrk_leakingkey_full",
+        fetchImpl,
+      });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught?.message).not.toContain("hrk_leakingkey_full");
+    expect(caught?.message).toContain("[REDACTED:HEROKU_API_KEY]");
+  });
+
+  test("throws clearly when no API key configured", async () => {
+    delete process.env[API_KEY_ENV];
+    let caught: Error | undefined;
+    try {
+      await deployToHeroku({ appName: "my-bot" });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeInstanceOf(HerokuAdapterError);
+    expect(caught?.message).toContain("HEROKU_API_KEY is required");
+  });
+
+  test("validates app name before network call", async () => {
+    let called = false;
+    const fetchImpl = (async () => {
+      called = true;
+      return new Response("", { status: 201 });
+    }) as unknown as typeof fetch;
+    let caught: Error | undefined;
+    try {
+      await deployToHeroku({
+        appName: "BadCaps",
+        apiKey: "hrk_testkey_abcdef",
+        fetchImpl,
+      });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeInstanceOf(HerokuAdapterError);
+    expect(called).toBe(false);
+  });
+
+  test("derives web_url when API omits it", async () => {
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({ id: "x", name: "my-bot" }), {
+        status: 201,
+      })) as unknown as typeof fetch;
+    const record = await deployToHeroku({
+      appName: "my-bot",
+      apiKey: "hrk_testkey_abcdef",
+      fetchImpl,
+    });
+    expect(record.webUrl).toBe("https://my-bot.herokuapp.com/");
+  });
+});

package/src/index.ts

@@ -0,0 +1,258 @@
+import { type TargetShape, isTargetShape } from "@crewhaus/docker-images";
+import { CrewhausError } from "@crewhaus/errors";
+
+/**
+ * Section 44 — `@crewhaus/cloud-adapter-heroku`
+ *
+ * One-click deploy adapter for [Heroku](https://heroku.com). Four surfaces:
+ *
+ *   - `herokuYmlFor({target, …})` — emits a deterministic `heroku.yml`
+ *     manifest pointing at the Container stack with a Docker build for
+ *     each process type (web for daemon shapes, worker for batch).
+ *
+ *   - `appJsonFor({target, name, …})` — emits a `app.json` Heroku Setup
+ *     manifest (`stack: container`, env vars, formation).
+ *
+ *   - `herokuDockerfileFor({target, baseImage})` — wraps the §32 base
+ *     image with a Heroku-tuned `ENV PORT=$PORT` and shell-form CMD —
+ *     Heroku injects `$PORT` at runtime and expects the container to
+ *     bind to it. No fixed `EXPOSE`.
+ *
+ *   - `deployToHeroku({apiKey, appName, …})` — creates an app via the
+ *     Heroku Platform API and sets the stack to `container`. Live
+ *     calls gated on `HEROKU_API_KEY` (or explicit `apiKey`) + an
+ *     injectable `fetchImpl`.
+ *
+ * SECURITY (T8 credential-leak guard): `scrubApiKey()` wraps every
+ * error path. Mirrors the §37 exporter-datadog approach.
+ *
+ * Targets: daemon shapes (channel, managed, batch, voice, browser).
+ */
+
+export class HerokuAdapterError extends CrewhausError {
+  override readonly name = "HerokuAdapterError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export const HEROKU_TARGET_SHAPES = [
+  "channel",
+  "managed",
+  "batch",
+  "voice",
+  "browser",
+] as const satisfies readonly TargetShape[];
+
+export type HerokuTargetShape = (typeof HEROKU_TARGET_SHAPES)[number];
+
+export function isHerokuTargetShape(value: unknown): value is HerokuTargetShape {
+  return typeof value === "string" && (HEROKU_TARGET_SHAPES as readonly string[]).includes(value);
+}
+
+export type HerokuDynoSize = "basic" | "standard-1x" | "standard-2x" | "performance-m";
+
+const PROCESS_FOR_TARGET: Readonly<Record<HerokuTargetShape, "web" | "worker">> = {
+  channel: "web",
+  managed: "web",
+  voice: "web",
+  browser: "web",
+  batch: "worker",
+};
+
+const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{2,28}[a-z0-9]$/;
+
+function assertHerokuTarget(target: TargetShape): asserts target is HerokuTargetShape {
+  if (!isHerokuTargetShape(target)) {
+    throw new HerokuAdapterError(
+      `target shape "${target}" is not supported by Heroku. Supported daemon shapes: ${HEROKU_TARGET_SHAPES.join(", ")}.`,
+    );
+  }
+}
+
+function assertAppName(name: string): void {
+  if (!APP_NAME_PATTERN.test(name)) {
+    throw new HerokuAdapterError(
+      `app name "${name}" is invalid. Must be lowercase letters/digits/hyphens, 4-30 chars, starts with a letter, no trailing hyphen.`,
+    );
+  }
+}
+
+export type HerokuYmlOptions = {
+  readonly target: TargetShape;
+  readonly dockerfilePath?: string;
+};
+
+/**
+ * Heroku.yml is YAML but small + deterministic enough to template
+ * inline. Three top-level sections: build, run, release (release omitted
+ * for now — no DB migrations in the shipped scope).
+ */
+export function herokuYmlFor(opts: HerokuYmlOptions): string {
+  if (!isTargetShape(opts.target)) {
+    throw new HerokuAdapterError(`unknown target shape "${opts.target}"`);
+  }
+  assertHerokuTarget(opts.target);
+  const dockerfilePath = opts.dockerfilePath ?? "Dockerfile.heroku";
+  const processName = PROCESS_FOR_TARGET[opts.target];
+  const lines = [
+    "# Generated by @crewhaus/cloud-adapter-heroku — do not edit by hand",
+    "build:",
+    "  docker:",
+    `    ${processName}: ${dockerfilePath}`,
+    "run:",
+    `  ${processName}: bun run start`,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+export type AppJsonOptions = {
+  readonly target: TargetShape;
+  readonly name: string;
+  readonly description?: string;
+  readonly envVars?: Readonly<Record<string, { value?: string; required?: boolean }>>;
+  readonly dynoSize?: HerokuDynoSize;
+  readonly quantity?: number;
+};
+
+/**
+ * `app.json` Heroku Setup manifest. Deterministic key order, sorted
+ * env-var keys.
+ */
+export function appJsonFor(opts: AppJsonOptions): string {
+  if (!isTargetShape(opts.target)) {
+    throw new HerokuAdapterError(`unknown target shape "${opts.target}"`);
+  }
+  assertHerokuTarget(opts.target);
+  assertAppName(opts.name);
+  const processName = PROCESS_FOR_TARGET[opts.target];
+  const formation = {
+    [processName]: {
+      quantity: opts.quantity ?? 1,
+      size: opts.dynoSize ?? "basic",
+    },
+  };
+  const env: Record<string, { value?: string; required?: boolean }> = {};
+  if (opts.envVars) {
+    for (const key of Object.keys(opts.envVars).sort()) {
+      const value = opts.envVars[key];
+      if (value === undefined) continue;
+      env[key] = value;
+    }
+  }
+  const manifest: Record<string, unknown> = {
+    name: opts.name,
+    stack: "container",
+    formation,
+  };
+  if (opts.description !== undefined) {
+    manifest["description"] = opts.description;
+  }
+  if (Object.keys(env).length > 0) {
+    manifest["env"] = env;
+  }
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+export type HerokuDockerfileOptions = {
+  readonly target: TargetShape;
+  readonly baseImage: string;
+};
+
+export function herokuDockerfileFor(opts: HerokuDockerfileOptions): string {
+  if (!isTargetShape(opts.target)) {
+    throw new HerokuAdapterError(`unknown target shape "${opts.target}"`);
+  }
+  assertHerokuTarget(opts.target);
+  // Heroku injects $PORT at runtime; container must bind to it. No EXPOSE.
+  const lines = [
+    `# Heroku-tuned wrapper around ${opts.baseImage}`,
+    `FROM ${opts.baseImage}`,
+    "ENV PORT=${PORT:-8080}",
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+export type HerokuDeployRecord = {
+  readonly appId: string;
+  readonly appName: string;
+  readonly webUrl: string;
+};
+
+export type DeployToHerokuOptions = {
+  readonly appName: string;
+  readonly region?: "us" | "eu";
+  readonly apiKey?: string;
+  readonly apiBaseUrl?: string;
+  readonly fetchImpl?: typeof fetch;
+};
+
+export const HEROKU_DEFAULT_API_BASE = "https://api.heroku.com";
+
+function resolveApiKey(provided: string | undefined): string {
+  const key = provided ?? process.env["HEROKU_API_KEY"];
+  if (key === undefined || key.length === 0) {
+    throw new HerokuAdapterError(
+      "HEROKU_API_KEY is required. Pass `apiKey` explicitly or set the env var.",
+    );
+  }
+  return key;
+}
+
+export function scrubApiKey(message: string, apiKey: string | undefined): string {
+  if (apiKey === undefined || apiKey.length < 8) return message;
+  return message.split(apiKey).join("[REDACTED:HEROKU_API_KEY]");
+}
+
+/**
+ * Create an app via Heroku Platform API. Stack is pinned to `container`
+ * so the heroku.yml + Dockerfile build path is used. All errors run
+ * through `scrubApiKey()`.
+ */
+export async function deployToHeroku(opts: DeployToHerokuOptions): Promise<HerokuDeployRecord> {
+  assertAppName(opts.appName);
+  const apiKey = resolveApiKey(opts.apiKey);
+  const baseUrl = opts.apiBaseUrl ?? HEROKU_DEFAULT_API_BASE;
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const region = opts.region ?? "us";
+
+  let response: Response;
+  try {
+    response = await fetchFn(`${baseUrl}/apps`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/vnd.heroku+json; version=3",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ name: opts.appName, stack: "container", region }),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new HerokuAdapterError(
+      `Heroku Platform API request failed: ${scrubApiKey(msg, apiKey)}`,
+      err,
+    );
+  }
+  const text = await response.text();
+  const scrubbed = scrubApiKey(text, apiKey);
+  if (!response.ok) {
+    throw new HerokuAdapterError(
+      `Heroku Platform API returned ${response.status} ${response.statusText}: ${scrubbed}`,
+    );
+  }
+  let parsed: { id?: string; name?: string; web_url?: string };
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new HerokuAdapterError(`Heroku Platform API returned non-JSON body: ${scrubbed}`, err);
+  }
+  if (typeof parsed.id !== "string" || typeof parsed.name !== "string") {
+    throw new HerokuAdapterError(`Heroku Platform API response missing id/name: ${scrubbed}`);
+  }
+  return {
+    appId: parsed.id,
+    appName: parsed.name,
+    webUrl: parsed.web_url ?? `https://${parsed.name}.herokuapp.com/`,
+  };
+}