alpha-gate 0.1.0

package/src/deploy/core/plan.ts

@@ -0,0 +1,138 @@
+import type { DeployArgs } from "./args";
+import type { ApplyStep, Finding, InspectStep } from "./types";
+
+// Pure planning: from the parsed args + what INSPECT learned, compute the read-only inspect commands,
+// the findings to echo, and the APPLY steps (with skips). This is the brain the orchestration (#28)
+// renders + executes; keeping it pure means idempotency and the skip logic are unit-tested with no I/O.
+
+export interface Inspection {
+  /** Existing D1 uuid, or null when it must be created. */
+  d1Id: string | null;
+  bucketExists: boolean;
+  accessConfigured: boolean;
+  /** Whether app config (meta.app_name) is already set — we don't reseed over admin edits. */
+  seeded: boolean;
+}
+
+export function resourceName(instance: string): string {
+  return `alpha-gate-${instance}`;
+}
+
+export function inspectSteps(args: DeployArgs): InspectStep[] {
+  const res = resourceName(args.instance);
+  return [
+    { why: "account & login", command: "wrangler whoami" },
+    { why: "database exists?", command: "wrangler d1 list --json" },
+    { why: "bucket exists?", command: `wrangler r2 bucket info ${res}` },
+    {
+      why: "Access wired?",
+      command: `wrangler secret list --config .deploy/${args.instance}.admin.toml --format json`,
+    },
+  ];
+}
+
+export function inspectionFindings(ins: Inspection): Finding[] {
+  return [
+    { label: "database", value: ins.d1Id ? `exists (${ins.d1Id.slice(0, 8)}…)` : "not found" },
+    { label: "bucket", value: ins.bucketExists ? "exists" : "not found" },
+    { label: "Access", value: ins.accessConfigured ? "configured" : "not configured" },
+  ];
+}
+
+// The app-config values seeded into `meta` on a first init (only the ones actually provided).
+const SEED_KEYS: ReadonlyArray<readonly [keyof DeployArgs, string]> = [
+  ["appName", "app_name"],
+  ["activateScheme", "activate_scheme"],
+  ["blurb", "blurb"],
+  ["accent", "accent"],
+];
+
+export function seedValues(args: DeployArgs): { key: string; value: string }[] {
+  const out: { key: string; value: string }[] = [];
+  for (const [argKey, metaKey] of SEED_KEYS) {
+    const value = args[argKey];
+    if (typeof value === "string" && value.length > 0) out.push({ key: metaKey, value });
+  }
+  return out;
+}
+
+/** The seed SQL (INSERT OR IGNORE — never clobbers admin edits), or null when there's nothing to seed. */
+export function buildSeedSql(args: DeployArgs): string | null {
+  const values = seedValues(args);
+  if (values.length === 0) return null;
+  return values
+    .map(({ key, value }) => {
+      const escaped = value.replace(/'/g, "''");
+      return `INSERT OR IGNORE INTO meta (key, value) VALUES ('${key}', '${escaped}');`;
+    })
+    .join("");
+}
+
+/** True when the operator must enable Cloudflare Access by hand (no creds given, none configured yet). */
+export function accessManualNeeded(args: DeployArgs, ins: Inspection): boolean {
+  const haveCreds = args.accessTeamDomain !== null && args.accessAud !== null;
+  return !haveCreds && !ins.accessConfigured;
+}
+
+export function buildApplyPlan(args: DeployArgs, ins: Inspection): ApplyStep[] {
+  const res = resourceName(args.instance);
+  const steps: ApplyStep[] = [];
+
+  steps.push(
+    ins.d1Id === null
+      ? { kind: "create", what: "database", why: "", command: `wrangler d1 create ${res}` }
+      : { kind: "skip", what: "database", why: "exists — skipping", command: "" },
+  );
+  steps.push(
+    ins.bucketExists
+      ? { kind: "skip", what: "bucket", why: "exists — skipping", command: "" }
+      : { kind: "create", what: "bucket", why: "", command: `wrangler r2 bucket create ${res}` },
+  );
+  steps.push({
+    kind: "update",
+    what: "migrations",
+    why: "",
+    command: `wrangler d1 migrations apply ${res} --remote`,
+  });
+
+  const seeds = seedValues(args);
+  if (ins.seeded || seeds.length === 0) {
+    steps.push({
+      kind: "skip",
+      what: "app config",
+      why: ins.seeded ? "already set — skipping" : "nothing to seed",
+      command: "",
+    });
+  } else {
+    steps.push({
+      kind: "create",
+      what: "app config",
+      why: "",
+      command: `wrangler d1 execute ${res} --remote  (seed: ${seeds.map((s) => s.key).join(", ")})`,
+    });
+  }
+
+  steps.push({
+    kind: "update",
+    what: "deploy app",
+    why: "",
+    command: `wrangler deploy -c .deploy/${args.instance}.app.toml`,
+  });
+  steps.push({
+    kind: "update",
+    what: "deploy admin",
+    why: "",
+    command: `wrangler deploy -c .deploy/${args.instance}.admin.toml`,
+  });
+
+  if (args.accessTeamDomain !== null && args.accessAud !== null) {
+    steps.push({
+      kind: "update",
+      what: "Access secrets",
+      why: "",
+      command: "wrangler deploy admin --secrets-file (ACCESS_TEAM_DOMAIN, ACCESS_AUD)",
+    });
+  }
+
+  return steps;
+}

package/src/deploy/core/result.ts

@@ -0,0 +1,13 @@
+// A tiny Result type so the pure validators/parsers report failure as data (with a fix-it hint) rather
+// than throwing — the command layer turns an error Result into the same "→ what to do" output as the
+// preflight, and tests assert on it directly.
+
+export type Result<T> = { ok: true; value: T } | { ok: false; error: string; hint?: string };
+
+export function ok<T>(value: T): Result<T> {
+  return { ok: true, value };
+}
+
+export function err<T>(error: string, hint?: string): Result<T> {
+  return hint === undefined ? { ok: false, error } : { ok: false, error, hint };
+}

package/src/deploy/core/state.ts

@@ -0,0 +1,64 @@
+// The per-instance state ledger (.deploy/<instance>.state.json). It records the resource id + URLs
+// plus the remembered inputs. The ON-DISK shape keeps deploy.sh's snake_case keys
+// (instance/app_url/admin_url/d1_id) so the existing publish.sh/teardown.sh keep reading it unchanged.
+// parseState is tolerant: a missing/corrupt file (or unknown keys, e.g. the retired `phases` array
+// from older versions) yields a clean state rather than throwing.
+
+export interface DeployState {
+  instance: string;
+  d1Id: string | null;
+  appUrl: string | null;
+  adminUrl: string | null;
+  // Remembered inputs so a bare re-run (`deploy --instance X`) preserves them instead of silently
+  // reverting to defaults — the classic "email turned itself off on the next deploy" bug.
+  emailProvider: string | null;
+  emailFrom: string | null;
+  accessTeamDomain: string | null;
+  accessAud: string | null;
+}
+
+export function emptyState(instance: string): DeployState {
+  return {
+    instance,
+    d1Id: null,
+    appUrl: null,
+    adminUrl: null,
+    emailProvider: null,
+    emailFrom: null,
+    accessTeamDomain: null,
+    accessAud: null,
+  };
+}
+
+export function serializeState(state: DeployState): string {
+  const onDisk = {
+    instance: state.instance,
+    app_url: state.appUrl,
+    admin_url: state.adminUrl,
+    d1_id: state.d1Id,
+    email_provider: state.emailProvider,
+    email_from: state.emailFrom,
+    access_team_domain: state.accessTeamDomain,
+    access_aud: state.accessAud,
+  };
+  return `${JSON.stringify(onDisk, null, 2)}\n`;
+}
+
+export function parseState(json: string, instance: string): DeployState {
+  try {
+    const obj = JSON.parse(json) as Record<string, unknown>;
+    const str = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v : null);
+    return {
+      instance: str(obj.instance) ?? instance,
+      d1Id: str(obj.d1_id),
+      appUrl: str(obj.app_url),
+      adminUrl: str(obj.admin_url),
+      emailProvider: str(obj.email_provider),
+      emailFrom: str(obj.email_from),
+      accessTeamDomain: str(obj.access_team_domain),
+      accessAud: str(obj.access_aud),
+    };
+  } catch {
+    return emptyState(instance);
+  }
+}

package/src/deploy/core/table.ts

@@ -0,0 +1,49 @@
+import type { Palette } from "./colors";
+
+// A pure box-drawing table renderer. Column widths are measured on PLAIN text and the cell is padded
+// BEFORE any color style is applied, so ANSI codes never throw the alignment off. (Our cell text is
+// all single-width — box chars, ✓/✗/·, …, ASCII — so String.length is the right measure.)
+
+export interface Cell {
+  text: string;
+  /** Applied after padding (e.g. palette.green); alignment is preserved. */
+  style?: (s: string) => string;
+}
+
+export interface TableOptions {
+  head?: string[];
+}
+
+export function renderTable(rows: Cell[][], palette: Palette, options: TableOptions = {}): string {
+  const cols = rows.reduce((max, row) => Math.max(max, row.length), options.head?.length ?? 0);
+  const widths: number[] = [];
+  for (let c = 0; c < cols; c++) {
+    let width = options.head?.[c]?.length ?? 0;
+    for (const row of rows) width = Math.max(width, row[c]?.text.length ?? 0);
+    widths.push(width);
+  }
+
+  const bar = (left: string, mid: string, right: string): string =>
+    palette.dim(left + widths.map((w) => "─".repeat(w + 2)).join(mid) + right);
+
+  const sep = palette.dim("│");
+  const renderRow = (cells: Cell[]): string => {
+    const inner = widths
+      .map((w, i) => {
+        const cell = cells[i] ?? { text: "" };
+        const padded = ` ${cell.text}${" ".repeat(w - cell.text.length)} `;
+        return cell.style ? cell.style(padded) : padded;
+      })
+      .join(sep);
+    return `${sep}${inner}${sep}`;
+  };
+
+  const lines = [bar("┌", "┬", "┐")];
+  if (options.head) {
+    lines.push(renderRow(options.head.map((h) => ({ text: h, style: palette.bold }))));
+    lines.push(bar("├", "┼", "┤"));
+  }
+  for (const row of rows) lines.push(renderRow(row));
+  lines.push(bar("└", "┴", "┘"));
+  return lines.join("\n");
+}

package/src/deploy/core/types.ts

@@ -0,0 +1,39 @@
+// Shared data shapes for the deploy CLI. Kept free of I/O so the planner, the renderer, and the
+// validators are all pure functions over plain data (mirrors the app's pure-core discipline).
+
+export type Role = "app" | "admin";
+
+/** A read-only command the CLI will run during the INSPECT phase, with the reason it's needed. */
+export interface InspectStep {
+  /** Short, human reason shown to the operator (the "why"). */
+  why: string;
+  /** The exact command, shown verbatim so nothing runs unseen. */
+  command: string;
+}
+
+/** A fact learned during INSPECT, echoed back before planning the APPLY phase. */
+export interface Finding {
+  label: string;
+  value: string;
+}
+
+export type ApplyKind = "create" | "update" | "skip" | "delete";
+
+/** A single change the APPLY phase will make (or skip), with its reason and exact command. */
+export interface ApplyStep {
+  kind: ApplyKind;
+  /** Short label for the thing being changed, e.g. "database". */
+  what: string;
+  /** The reason / detail (also the displayed text for a `skip`). */
+  why: string;
+  /** The exact command; empty for a `skip` (nothing runs). */
+  command: string;
+}
+
+/** Result of a single preflight tool/auth check. */
+export interface PreflightItem {
+  name: string;
+  ok: boolean;
+  /** What to show — the version/account on success, or the fix-it hint on failure. */
+  detail: string;
+}

package/src/deploy/core/ui.ts

@@ -0,0 +1,107 @@
+import type { Palette } from "./colors";
+import { type Cell, renderTable } from "./table";
+import type { ApplyStep, Finding, InspectStep, PreflightItem } from "./types";
+
+// The "grouped panels" console UI: phased, table-formatted, color when the terminal supports it. Pure
+// — every function returns the string to print and takes the Palette in, so wording/alignment/markers
+// are unit-tested and color is a presentation detail decided at the edge. Transparency contract holds:
+// the operator always sees the phase, the reason ("why"), and the exact command before anything runs.
+
+export function renderHeader(instance: string, palette: Palette): string {
+  return palette.bold(`Alpha Gate deploy · ${instance}`);
+}
+
+/** Preflight tool/auth checks as a table: ✓ green / ✗ red with the detail or fix-it hint. */
+export function renderPreflight(items: readonly PreflightItem[], palette: Palette): string {
+  const rows: Cell[][] = items.map((item) => [
+    { text: item.name },
+    {
+      text: `${item.ok ? "✓" : "✗"} ${item.detail}`,
+      style: item.ok ? palette.green : palette.red,
+    },
+  ]);
+  return renderTable(rows, palette, { head: ["Check", "Result"] });
+}
+
+/** Read-only INSPECT phase: a Why | Command table; commands dimmed. */
+export function renderInspect(steps: readonly InspectStep[], palette: Palette): string {
+  const rows: Cell[][] = steps.map((s) => [
+    { text: s.why },
+    { text: s.command, style: palette.dim },
+  ]);
+  return [
+    palette.bold("1 · INSPECT") + palette.dim("  read-only — learn current state"),
+    renderTable(rows, palette, { head: ["Why", "Command"] }),
+  ].join("\n");
+}
+
+/** The facts learned during INSPECT, echoed before the APPLY plan. */
+export function renderFindings(findings: readonly Finding[], palette: Palette): string {
+  const rows: Cell[][] = findings.map((f) => [
+    { text: f.label },
+    { text: f.value, style: palette.cyan },
+  ]);
+  return renderTable(rows, palette, { head: ["Resource", "State"] });
+}
+
+const MARK: Record<ApplyStep["kind"], string> = {
+  create: "+",
+  update: "~",
+  delete: "-",
+  skip: "·",
+};
+
+/** A Δ | Resource | Command-or-reason table under a heading; marker colored by change kind. Shared by
+ * the deploy APPLY phase and the teardown DESTROY plan. */
+function renderStepTable(heading: string, steps: readonly ApplyStep[], palette: Palette): string {
+  const markStyle: Record<ApplyStep["kind"], (s: string) => string> = {
+    create: palette.green,
+    update: palette.cyan,
+    delete: palette.red,
+    skip: palette.dim,
+  };
+  const rows: Cell[][] = steps.map((s) => [
+    { text: MARK[s.kind], style: markStyle[s.kind] },
+    { text: s.what },
+    { text: s.kind === "skip" ? s.why : s.command, style: palette.dim },
+  ]);
+  return [
+    heading,
+    renderTable(rows, palette, { head: ["Δ", "Resource", "Command / reason"] }),
+  ].join("\n");
+}
+
+/** Mutating APPLY phase (deploy). */
+export function renderApply(steps: readonly ApplyStep[], palette: Palette): string {
+  return renderStepTable(
+    palette.bold("2 · APPLY") + palette.dim("  creates/changes resources"),
+    steps,
+    palette,
+  );
+}
+
+/** Destructive plan (teardown). */
+export function renderDestroy(steps: readonly ApplyStep[], palette: Palette): string {
+  return renderStepTable(
+    palette.bold("DESTROY") + palette.dim("  this permanently deletes resources"),
+    steps,
+    palette,
+  );
+}
+
+/**
+ * A step only the operator can do (e.g. enabling Cloudflare Access in the dashboard). The CLI shows
+ * this, then BLOCKS on a prompt seam until the operator confirms it's done — see seams/io waitForDone.
+ */
+export function renderManualStep(
+  title: string,
+  steps: readonly string[],
+  palette: Palette,
+): string {
+  const lines = [
+    palette.yellow(`⚙ MANUAL STEP — only you can do this`),
+    title,
+    ...steps.map((s, i) => `  ${i + 1}. ${s}`),
+  ];
+  return lines.join("\n");
+}

package/src/deploy/seams/clock.ts

@@ -0,0 +1,10 @@
+// The deploy CLI's one sanctioned use of Date (allow-listed in biome.json, like src/lib/clock.ts):
+// a filesystem-safe UTC stamp for the teardown archive filename, e.g. "20260614T120000Z". Injected as
+// a seam so tests pass a fixed value.
+
+export function nowStamp(): string {
+  return new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\.\d+Z$/, "Z");
+}

package/src/deploy/seams/files.ts

@@ -0,0 +1,52 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+
+// The filesystem seam — rendering configs, the state ledger, and the temp secrets file. Behind an
+// interface so the command orchestration is tested against an in-memory fake. read() returns null for
+// a missing file (callers treat that as "first run") rather than throwing.
+
+export interface FileSystem {
+  read(path: string): Promise<string | null>;
+  write(path: string, data: string): Promise<void>;
+  mkdirp(path: string): Promise<void>;
+  remove(path: string): Promise<void>;
+}
+
+export function createFileSystem(): FileSystem {
+  return {
+    async read(path) {
+      try {
+        return await readFile(path, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    async write(path, data) {
+      await writeFile(path, data, "utf8");
+    },
+    async mkdirp(path) {
+      await mkdir(path, { recursive: true });
+    },
+    async remove(path) {
+      await rm(path, { force: true, recursive: true });
+    },
+  };
+}
+
+export function createFakeFileSystem(
+  seed: Record<string, string> = {},
+): FileSystem & { files: Map<string, string> } {
+  const files = new Map<string, string>(Object.entries(seed));
+  return {
+    files,
+    read: (path) => Promise.resolve(files.get(path) ?? null),
+    write: (path, data) => {
+      files.set(path, data);
+      return Promise.resolve();
+    },
+    mkdirp: () => Promise.resolve(),
+    remove: (path) => {
+      files.delete(path);
+      return Promise.resolve();
+    },
+  };
+}

package/src/deploy/seams/io.ts

@@ -0,0 +1,56 @@
+import { createInterface } from "node:readline/promises";
+
+// The interactive seam. Kept behind an interface so the command orchestration is testable with a fake
+// (canned answers) — the real implementation uses node:readline. This is where requirement #3 lives:
+// a manual step the CLI can't perform is shown, then waitForDone BLOCKS until the operator confirms.
+
+export interface Prompt {
+  /** Ask a free-text question; returns the trimmed answer ("" if the operator just pressed Enter). */
+  ask(question: string): Promise<string>;
+  /** Yes/No, defaulting to NO — used for the APPLY confirmation gate. */
+  confirm(question: string): Promise<boolean>;
+  /** Block until the operator acknowledges a manual step is finished (Enter to continue). */
+  waitForDone(question: string): Promise<void>;
+}
+
+export function createPrompt(): Prompt {
+  async function ask(question: string): Promise<string> {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      return (await rl.question(question)).trim();
+    } finally {
+      rl.close();
+    }
+  }
+  return {
+    ask,
+    async confirm(question) {
+      const answer = (await ask(`${question} [y/N] `)).toLowerCase();
+      return answer === "y" || answer === "yes";
+    },
+    async waitForDone(question) {
+      await ask(`${question} `);
+    },
+  };
+}
+
+/** A scripted prompt for tests: each call consumes the next canned answer (default "" when exhausted). */
+export function createFakePrompt(answers: readonly string[]): Prompt & { asked: string[] } {
+  const queue = [...answers];
+  const asked: string[] = [];
+  async function ask(question: string): Promise<string> {
+    asked.push(question);
+    return queue.shift() ?? "";
+  }
+  return {
+    asked,
+    ask,
+    async confirm(question) {
+      const answer = (await ask(question)).toLowerCase();
+      return answer === "y" || answer === "yes";
+    },
+    async waitForDone(question) {
+      await ask(question);
+    },
+  };
+}

package/src/deploy/seams/wrangler.ts

@@ -0,0 +1,100 @@
+import { execFile, spawn } from "node:child_process";
+
+// The wrangler seam: the ONLY place the CLI shells out. Commands are passed as an argv array (never a
+// shell string), so there's no quoting/injection surface. run() resolves with the exit code + captured
+// output — it does NOT reject on a non-zero exit, so the command layer decides what a failure means
+// and can surface a clear message. A dry-run variant logs the intended command and no-ops; tests use a
+// programmable fake.
+
+export interface RunResult {
+  ok: boolean;
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface RunOptions {
+  /** Written to the process stdin (used for `wrangler secret put`). */
+  input?: string;
+}
+
+export interface Wrangler {
+  run(args: readonly string[], opts?: RunOptions): Promise<RunResult>;
+  /** Spawn a long-running command with inherited stdio (e.g. `wrangler dev`); resolves on exit. */
+  exec(args: readonly string[]): Promise<number>;
+}
+
+export interface WranglerOptions {
+  /** When true, log the command and return success without running anything. */
+  dryRun?: boolean;
+  /** Sink for the dry-run echo / live command echo (defaults to console.error). */
+  log?: (line: string) => void;
+  /** Directory to run `npx wrangler` from — set to the package root so the bundled wrangler (a
+      dependency) resolves even when the user's CWD has no node_modules (an npx install). */
+  cwd?: string;
+}
+
+export function createWrangler(options: WranglerOptions = {}): Wrangler {
+  const log = options.log ?? ((line) => console.error(line));
+  const cwd = options.cwd;
+  return {
+    run(args, opts = {}) {
+      if (options.dryRun) {
+        log(`[dry-run] wrangler ${args.join(" ")}`);
+        return Promise.resolve({ ok: true, code: 0, stdout: "", stderr: "" });
+      }
+      return new Promise<RunResult>((resolve) => {
+        const child = execFile(
+          "npx",
+          ["wrangler", ...args],
+          { maxBuffer: 64 * 1024 * 1024, cwd },
+          (error, stdout, stderr) => {
+            const code = error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+            resolve({ ok: code === 0, code, stdout, stderr });
+          },
+        );
+        if (opts.input !== undefined) {
+          child.stdin?.end(opts.input);
+        }
+      });
+    },
+    exec(args) {
+      if (options.dryRun) {
+        log(`[dry-run] wrangler ${args.join(" ")}`);
+        return Promise.resolve(0);
+      }
+      return new Promise<number>((resolve) => {
+        const child = spawn("npx", ["wrangler", ...args], { stdio: "inherit", cwd });
+        child.on("exit", (code) => resolve(code ?? 0));
+        child.on("error", () => resolve(1));
+      });
+    },
+  };
+}
+
+/**
+ * A programmable fake for orchestration tests: `handler` returns the result for a given argv (defaults
+ * to success). Every call is recorded in `calls` so tests assert the command sequence.
+ */
+export function createFakeWrangler(
+  handler: (args: readonly string[], input?: string) => Partial<RunResult> = () => ({}),
+): Wrangler & { calls: string[][] } {
+  const calls: string[][] = [];
+  return {
+    calls,
+    run(args, opts = {}) {
+      calls.push([...args]);
+      const partial = handler(args, opts.input);
+      return Promise.resolve({
+        ok: partial.ok ?? (partial.code === undefined || partial.code === 0),
+        code: partial.code ?? 0,
+        stdout: partial.stdout ?? "",
+        stderr: partial.stderr ?? "",
+      });
+    },
+    exec(args) {
+      calls.push([...args]);
+      return Promise.resolve(0);
+    },
+  };
+}