alpha-gate 0.1.0

package/src/deploy/commands/teardown.ts

@@ -0,0 +1,159 @@
+import { parseTeardownArgs } from "../core/args";
+import type { Palette } from "../core/colors";
+import { resourceName } from "../core/plan";
+import type { ApplyStep } from "../core/types";
+import { renderDestroy, renderHeader } from "../core/ui";
+import type { FileSystem } from "../seams/files";
+import type { Prompt } from "../seams/io";
+import type { Wrangler } from "../seams/wrangler";
+
+// The `teardown` command (§21): archive D1 first (unless --no-archive), then delete both Workers + the
+// database. The R2 bucket and the Cloudflare Access app can't be removed with pure wrangler (no bulk
+// R2 list; no Access API), so it deletes the bucket only if already empty and prints the manual steps.
+// Destructive — confirmed by typing the instance name (or --yes). All I/O via injected seams.
+
+export interface TeardownEnv {
+  wrangler: Wrangler;
+  prompt: Prompt;
+  fs: FileSystem;
+  palette: Palette;
+  out: (line: string) => void;
+  rootDir: string;
+  /** Where this instance's state lives — must match deploy (see core/paths). */
+  stateDir: string;
+  nowStamp: () => string;
+  interactive: boolean;
+}
+
+function fail(env: TeardownEnv, reason: string, hint: string): number {
+  env.out(env.palette.red(`teardown: ${reason}`));
+  if (hint) env.out(`  → ${hint}`);
+  return 1;
+}
+
+export async function runTeardown(argv: readonly string[], env: TeardownEnv): Promise<number> {
+  const parsed = parseTeardownArgs(argv);
+  if (!parsed.ok) return fail(env, parsed.error, parsed.hint ?? "");
+  const args = parsed.value;
+  const res = resourceName(args.instance);
+  const deployDir = env.stateDir;
+  const archiveDir = args.archiveDir ?? deployDir;
+  const archiveFile = `${archiveDir}/${args.instance}-${env.nowStamp()}.sql`;
+  const wr = env.wrangler;
+
+  env.out(renderHeader(args.instance, env.palette));
+
+  if (!args.dryRun) {
+    const who = await wr.run(["whoami"]);
+    if (!who.ok)
+      return fail(env, "not authenticated to Cloudflare", "run once: npx wrangler login");
+  }
+
+  // The destructive plan, shown before anything runs.
+  const plan: ApplyStep[] = [];
+  if (args.archive) {
+    plan.push({
+      kind: "create",
+      what: "archive D1",
+      why: "",
+      command: `wrangler d1 export ${res} --remote`,
+    });
+  }
+  plan.push({
+    kind: "delete",
+    what: "app Worker",
+    why: "",
+    command: `wrangler delete --name ${res}`,
+  });
+  plan.push({
+    kind: "delete",
+    what: "admin Worker",
+    why: "",
+    command: `wrangler delete --name ${res}-admin`,
+  });
+  plan.push({ kind: "delete", what: "database", why: "", command: `wrangler d1 delete ${res}` });
+  plan.push({
+    kind: "delete",
+    what: "R2 bucket",
+    why: "only if already empty",
+    command: `wrangler r2 bucket delete ${res}`,
+  });
+  env.out(renderDestroy(plan, env.palette));
+
+  // Confirm by typing the instance name (or --yes). Non-interactive without --yes → refuse, don't hang.
+  if (!args.dryRun && !args.yes) {
+    if (!env.interactive) {
+      return fail(env, "destructive run isn't interactive", "re-run with --yes to confirm");
+    }
+    const typed = await env.prompt.ask(`Type the instance name "${args.instance}" to confirm: `);
+    if (typed !== args.instance) {
+      env.out("aborted — nothing was deleted.");
+      return 1;
+    }
+  }
+
+  env.out("");
+  env.out(env.palette.bold("Tearing down…"));
+  const startStep = (label: string): void => env.out(env.palette.dim(`  → ${label}…`));
+  const doneStep = (label: string, extra = ""): void =>
+    env.out(env.palette.green(`  ✓ ${label}${extra === "" ? "" : `  ${extra}`}`));
+
+  // 1. Archive D1 BEFORE destroying (it must still exist). Abort on failure unless --no-archive.
+  if (args.archive) {
+    startStep("archive database");
+    const exported = await wr.run(["d1", "export", res, "--remote", "--output", archiveFile]);
+    if (!args.dryRun && !exported.ok) {
+      return fail(
+        env,
+        "D1 export failed — nothing was destroyed",
+        "fix the error above, or re-run with --no-archive to destroy without a backup",
+      );
+    }
+    doneStep("archive", archiveFile);
+  }
+
+  // 2. Delete both Workers (tolerate already-gone — re-runs/partial teardown are fine).
+  startStep("delete app Worker");
+  await wr.run(["delete", "--name", res]);
+  doneStep("app Worker");
+  startStep("delete admin Worker");
+  await wr.run(["delete", "--name", `${res}-admin`]);
+  doneStep("admin Worker");
+
+  // 3. R2 — deletes only if empty (pure wrangler can't list/empty a bucket); report if it survives.
+  startStep("delete R2 bucket");
+  const r2 = await wr.run(["r2", "bucket", "delete", res]);
+  const r2Left = !args.dryRun && !r2.ok;
+  if (r2Left) env.out(env.palette.yellow(`  ! R2 bucket ${res} not deleted (likely non-empty)`));
+  else doneStep("R2 bucket");
+
+  // 4. D1 database.
+  startStep("delete database");
+  await wr.run(["d1", "delete", res, "--skip-confirmation"]);
+  doneStep("database");
+
+  // 5. Local config + state (real runs only — dry-run must not touch the filesystem).
+  if (!args.dryRun) {
+    await env.fs.remove(`${deployDir}/${args.instance}.app.toml`);
+    await env.fs.remove(`${deployDir}/${args.instance}.admin.toml`);
+    await env.fs.remove(`${deployDir}/${args.instance}.state.json`);
+  }
+
+  env.out("");
+  env.out(
+    env.palette.green(`Removed ${args.instance}: both Workers and the D1 database are gone.`),
+  );
+  if (args.archive) {
+    env.out(`  Database archived → ${archiveFile}  (contains live tokens — store it safely)`);
+  }
+  env.out("Finish by hand (pure wrangler can't):");
+  if (r2Left) {
+    env.out(
+      `  - Empty + delete the R2 bucket '${res}' in the dashboard (R2 → the bucket → delete).`,
+    );
+  }
+  env.out(
+    `  - Remove the Cloudflare Access app for '${res}-admin' (Zero Trust → Access → Applications).`,
+  );
+  return 0;
+}

package/src/deploy/core/args.ts

@@ -0,0 +1,205 @@
+import { err, ok, type Result } from "./result";
+import type { Role } from "./types";
+
+// Pure flag parsing + validation for the `deploy` command — the same rules the bash deploy.sh enforced
+// (slug charset, email pairing, Access pairing), now typed and unit-tested instead of scattered shell
+// checks. Returns a Result; the command layer renders an error like the preflight (reason + hint).
+
+export type EmailProvider = "none" | "cloudflare";
+
+export interface DeployArgs {
+  instance: string;
+  appName: string | null;
+  activateScheme: string | null;
+  blurb: string | null;
+  accent: string | null;
+  accessTeamDomain: string | null;
+  accessAud: string | null;
+  emailProvider: EmailProvider;
+  emailFrom: string | null;
+  dryRun: boolean;
+  yes: boolean;
+}
+
+// Lowercase letters, digits and hyphens; no leading/trailing hyphen (doubles allowed, as in deploy.sh).
+const SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+const VALUE_FLAGS = new Set([
+  "--instance",
+  "--app-name",
+  "--activate-scheme",
+  "--blurb",
+  "--accent",
+  "--access-team-domain",
+  "--access-aud",
+  "--email-provider",
+  "--email-from",
+]);
+
+/** Strip a pasted scheme/trailing slash so the in-app issuer check can't silently fail on a URL form. */
+export function normalizeTeamDomain(raw: string): string {
+  return raw.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+
+export function parseDeployArgs(argv: readonly string[]): Result<DeployArgs> {
+  const values: Record<string, string> = {};
+  let dryRun = false;
+  let yes = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === undefined) continue;
+    if (flag === "--dry-run") {
+      dryRun = true;
+    } else if (flag === "--yes") {
+      yes = true;
+    } else if (VALUE_FLAGS.has(flag)) {
+      const value = argv[i + 1];
+      if (value === undefined) return err(`${flag} needs a value`);
+      values[flag] = value;
+      i++;
+    } else {
+      return err(`unknown flag: ${flag}`, "run `deploy --help` for the supported flags");
+    }
+  }
+
+  const instance = values["--instance"];
+  if (instance === undefined || instance === "") {
+    return err("--instance is required", "e.g. --instance myalpha");
+  }
+  if (!SLUG.test(instance)) {
+    return err(
+      `invalid --instance '${instance}'`,
+      "lowercase letters, digits and hyphens only (no leading/trailing hyphen)",
+    );
+  }
+
+  const emailProvider = values["--email-provider"] ?? "none";
+  if (emailProvider !== "none" && emailProvider !== "cloudflare") {
+    return err(`invalid --email-provider '${emailProvider}'`, "expected 'none' or 'cloudflare'");
+  }
+  const emailFrom = values["--email-from"] ?? null;
+  if (emailProvider === "cloudflare" && (emailFrom === null || emailFrom === "")) {
+    return err(
+      "--email-from is required when --email-provider is cloudflare",
+      "pass --email-from alpha@<your-sending-domain>",
+    );
+  }
+
+  const rawTeam = values["--access-team-domain"] ?? null;
+  const accessAud = values["--access-aud"] ?? null;
+  if ((rawTeam === null) !== (accessAud === null)) {
+    return err(
+      "--access-team-domain and --access-aud must be provided together",
+      "both are on the Access app's Overview page in Cloudflare Zero Trust",
+    );
+  }
+
+  return ok({
+    instance,
+    appName: values["--app-name"] ?? null,
+    activateScheme: values["--activate-scheme"] ?? null,
+    blurb: values["--blurb"] ?? null,
+    accent: values["--accent"] ?? null,
+    accessTeamDomain: rawTeam === null ? null : normalizeTeamDomain(rawTeam),
+    accessAud,
+    emailProvider,
+    emailFrom,
+    dryRun,
+    yes,
+  });
+}
+
+export interface TeardownArgs {
+  instance: string;
+  archive: boolean;
+  archiveDir: string | null;
+  yes: boolean;
+  dryRun: boolean;
+}
+
+const TEARDOWN_VALUE_FLAGS = new Set(["--instance", "--archive-dir"]);
+
+export function parseTeardownArgs(argv: readonly string[]): Result<TeardownArgs> {
+  const values: Record<string, string> = {};
+  let archive = true;
+  let yes = false;
+  let dryRun = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === undefined) continue;
+    if (flag === "--no-archive") {
+      archive = false;
+    } else if (flag === "--yes") {
+      yes = true;
+    } else if (flag === "--dry-run") {
+      dryRun = true;
+    } else if (TEARDOWN_VALUE_FLAGS.has(flag)) {
+      const value = argv[i + 1];
+      if (value === undefined) return err(`${flag} needs a value`);
+      values[flag] = value;
+      i++;
+    } else {
+      return err(`unknown flag: ${flag}`, "run `teardown --help` for the supported flags");
+    }
+  }
+
+  const instance = values["--instance"];
+  if (instance === undefined || instance === "") {
+    return err("--instance is required", "e.g. --instance myalpha");
+  }
+  if (!SLUG.test(instance)) {
+    return err(
+      `invalid --instance '${instance}'`,
+      "lowercase letters, digits and hyphens only (no leading/trailing hyphen)",
+    );
+  }
+
+  return ok({ instance, archive, archiveDir: values["--archive-dir"] ?? null, yes, dryRun });
+}
+
+export interface DevArgs {
+  role: Role;
+  port: number;
+  seed: boolean;
+  reset: boolean;
+}
+
+export function parseDevArgs(argv: readonly string[]): Result<DevArgs> {
+  let role: Role = "app";
+  let port = 8787;
+  let seed = true;
+  let reset = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === undefined) continue;
+    if (flag === "--no-seed") {
+      seed = false;
+    } else if (flag === "--reset") {
+      reset = true;
+    } else if (flag === "--role") {
+      const value = argv[i + 1];
+      i++;
+      if (value !== "app" && value !== "admin") {
+        return err(`invalid --role '${value ?? ""}'`, "expected 'app' or 'admin'");
+      }
+      role = value;
+    } else if (flag === "--port") {
+      const value = argv[i + 1];
+      i++;
+      const parsed = value === undefined ? Number.NaN : Number.parseInt(value, 10);
+      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        return err(`invalid --port '${value ?? ""}'`, "expected a port number 1–65535");
+      }
+      port = parsed;
+    } else {
+      return err(`unknown flag: ${flag}`, "run `dev --help` for the supported flags");
+    }
+  }
+
+  return ok({ role, port, seed, reset });
+}
+
+export type { Role };

package/src/deploy/core/colors.ts

@@ -0,0 +1,49 @@
+// ANSI color, kept behind a Palette so the renderers stay pure and testable: callers pass a palette
+// in, and the "should we actually emit color?" decision (TTY / NO_COLOR) lives at the edge (the CLI),
+// never in a render function. Tests use plainPalette for stable, code-free assertions.
+
+export interface Palette {
+  green(s: string): string;
+  red(s: string): string;
+  yellow(s: string): string;
+  cyan(s: string): string;
+  dim(s: string): string;
+  bold(s: string): string;
+}
+
+// Close with the attribute-specific reset (39 = default fg, 22 = normal intensity) rather than 0, so
+// nesting one style inside another doesn't wipe the outer style.
+function sgr(open: number, close: number): (s: string) => string {
+  return (s) => `\x1b[${open}m${s}\x1b[${close}m`;
+}
+
+export const colorPalette: Palette = {
+  green: sgr(32, 39),
+  red: sgr(31, 39),
+  yellow: sgr(33, 39),
+  cyan: sgr(36, 39),
+  dim: sgr(2, 22),
+  bold: sgr(1, 22),
+};
+
+const identity = (s: string): string => s;
+export const plainPalette: Palette = {
+  green: identity,
+  red: identity,
+  yellow: identity,
+  cyan: identity,
+  dim: identity,
+  bold: identity,
+};
+
+export function selectPalette(useColor: boolean): Palette {
+  return useColor ? colorPalette : plainPalette;
+}
+
+/** Honor NO_COLOR / FORCE_COLOR, else color only when stdout is a TTY. Pure over its inputs (testable). */
+export function shouldColor(env: NodeJS.ProcessEnv, isTty: boolean): boolean {
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== "") return false;
+  if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0")
+    return true;
+  return isTty;
+}

package/src/deploy/core/config.ts

@@ -0,0 +1,65 @@
+import type { Role } from "./types";
+
+// Renders a Worker's wrangler.toml in TS — replaces the old envsubst-over-a-template step (decision
+// 0009). Building it directly (not string-substituting an external template) means there's no
+// "unsubstituted ${VAR}" failure mode, values are escaped, and the output is unit-tested. This function
+// is the single source of truth for the rendered wrangler config shape.
+
+export interface ConfigVars {
+  instance: string;
+  d1Id: string;
+  role: Role;
+  name: string;
+  emailProvider: "none" | "cloudflare";
+  emailFrom: string;
+  toolVersion: string;
+  updateManifestUrl: string;
+  /** Worker entry — an ABSOLUTE path into the package src, so the config resolves it wherever the
+      rendered .toml lives (repo `.deploy/`, or `~/.alpha-gate` for an npm install). */
+  main: string;
+  /** ABSOLUTE path to the migrations dir (same reason as `main`). */
+  migrationsDir: string;
+}
+
+function tomlString(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+export function renderConfig(v: ConfigVars): string {
+  const q = (s: string): string => `"${tomlString(s)}"`;
+  const lines: string[] = [
+    `name = ${q(v.name)}`,
+    `main = ${q(v.main)}`,
+    `compatibility_date = "2025-01-01"`,
+    `workers_dev = true`,
+    "",
+    "[[d1_databases]]",
+    `binding = "DB"`,
+    `database_name = ${q(`alpha-gate-${v.instance}`)}`,
+    `database_id = ${q(v.d1Id)}`,
+    // Absolute path into the package, so `wrangler d1 migrations apply` finds it no matter where the
+    // rendered config lives (repo `.deploy/` or the relocated `~/.alpha-gate`).
+    `migrations_dir = ${q(v.migrationsDir)}`,
+    "",
+    "[[r2_buckets]]",
+    `binding = "BUILDS"`,
+    `bucket_name = ${q(`alpha-gate-${v.instance}`)}`,
+    "",
+    "[vars]",
+    `INSTANCE = ${q(v.instance)}`,
+    `ROLE = ${q(v.role)}`,
+    `EMAIL_PROVIDER = ${q(v.emailProvider)}`,
+    `EMAIL_FROM = ${q(v.emailFrom)}`,
+    `TOOL_VERSION = ${q(v.toolVersion)}`,
+    `UPDATE_MANIFEST_URL = ${q(v.updateManifestUrl)}`,
+  ];
+
+  // The Cloudflare Email Service binding goes on the ADMIN Worker only, and only when email is on —
+  // the public app Worker never sends mail, so it must not carry the binding.
+  if (v.role === "admin" && v.emailProvider === "cloudflare") {
+    lines.push("", "[[send_email]]", `name = "EMAIL"`);
+  }
+
+  lines.push("", "[triggers]", `crons = ["0 12 * * *"]`, "");
+  return lines.join("\n");
+}

package/src/deploy/core/parse.ts

@@ -0,0 +1,51 @@
+// Pure parsers/validators for wrangler's output. Centralizing them (vs. inline grep/jq in bash) means
+// every value pulled from a command is validated before use — an empty/garbled result becomes null/[]
+// here and the command layer fails loudly rather than writing poison into the state file.
+
+/** The D1 uuid for `dbName` from `wrangler d1 list --json`, or null if absent/garbled. */
+export function parseD1Id(listJson: string, dbName: string): string | null {
+  try {
+    const list: unknown = JSON.parse(listJson);
+    if (!Array.isArray(list)) return null;
+    for (const item of list) {
+      if (
+        item !== null &&
+        typeof item === "object" &&
+        (item as { name?: unknown }).name === dbName
+      ) {
+        const id = (item as { uuid?: unknown }).uuid;
+        return typeof id === "string" && id.length > 0 ? id : null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Secret names from `wrangler secret list --format json` (e.g. to check ACCESS_TEAM_DOMAIN is set). */
+export function secretNames(listJson: string): string[] {
+  try {
+    const list: unknown = JSON.parse(listJson);
+    if (!Array.isArray(list)) return [];
+    const names: string[] = [];
+    for (const item of list) {
+      const name =
+        item !== null && typeof item === "object" ? (item as { name?: unknown }).name : undefined;
+      if (typeof name === "string") names.push(name);
+    }
+    return names;
+  } catch {
+    return [];
+  }
+}
+
+export function accessConfigured(secretListJson: string): boolean {
+  return secretNames(secretListJson).includes("ACCESS_TEAM_DOMAIN");
+}
+
+/** The one unavoidable scrape: the workers.dev URL from `wrangler deploy` stdout (no --json for it). */
+export function extractDeployUrl(stdout: string): string | null {
+  const match = stdout.match(/https:\/\/[a-z0-9.-]+\.workers\.dev/i);
+  return match ? match[0] : null;
+}

package/src/deploy/core/paths.ts

@@ -0,0 +1,27 @@
+// Where the per-instance deploy state (.deploy/<slug>.state.json + the rendered wrangler configs)
+// lives. Two modes, so the CLI works whether it was `git clone`d or installed from npm:
+//
+//   - a git checkout (contributor) → `<packageRoot>/.deploy`, exactly as before, so existing
+//     deployments keep finding their state.
+//   - an npm install / npx run → `~/.alpha-gate`, because the package files sit in the (versioned,
+//     ephemeral) npm cache — state written there would vanish on the next `npx alpha-gate@newer`.
+//
+// $ALPHA_GATE_HOME overrides both. Pure over its inputs (env + a "does <root>/.git exist" probe) so
+// it's unit-testable without touching the filesystem.
+
+export interface StateDirInputs {
+  packageRoot: string;
+  /** $ALPHA_GATE_HOME, if set. */
+  home: string | undefined;
+  /** $HOME (for the ~/.alpha-gate default). */
+  userHome: string | undefined;
+  /** Whether `<packageRoot>/.git` exists — the signal for "running from a checkout". */
+  isGitCheckout: boolean;
+}
+
+export function resolveStateDir(inputs: StateDirInputs): string {
+  if (inputs.home !== undefined && inputs.home !== "") return inputs.home;
+  if (inputs.isGitCheckout) return `${inputs.packageRoot}/.deploy`;
+  const base = inputs.userHome !== undefined && inputs.userHome !== "" ? inputs.userHome : ".";
+  return `${base}/.alpha-gate`;
+}