alpha-gate 0.1.0

package/src/db/client.ts

@@ -0,0 +1,80 @@
+// The thin seam over the D1 binding: typed prepared-statement helpers with parameter binding and
+// error normalization. NO ORM — every query module writes raw SQL and uses these three primitives.
+
+export class DbError extends Error {
+  constructor(
+    readonly sql: string,
+    cause: unknown,
+  ) {
+    super(`D1 query failed: ${sql}`, { cause });
+    this.name = "DbError";
+  }
+}
+
+/** First matching row, or null. */
+export async function queryOne<T>(
+  db: D1Database,
+  sql: string,
+  params: readonly unknown[] = [],
+): Promise<T | null> {
+  try {
+    return (
+      (await db
+        .prepare(sql)
+        .bind(...params)
+        .first<T>()) ?? null
+    );
+  } catch (cause) {
+    throw new DbError(sql, cause);
+  }
+}
+
+/** All matching rows. */
+export async function queryAll<T>(
+  db: D1Database,
+  sql: string,
+  params: readonly unknown[] = [],
+): Promise<T[]> {
+  try {
+    const { results } = await db
+      .prepare(sql)
+      .bind(...params)
+      .all<T>();
+    return results;
+  } catch (cause) {
+    throw new DbError(sql, cause);
+  }
+}
+
+/** A statement run for its effect (INSERT/UPDATE/DELETE without a returned row). */
+export async function execute(
+  db: D1Database,
+  sql: string,
+  params: readonly unknown[] = [],
+): Promise<void> {
+  try {
+    await db
+      .prepare(sql)
+      .bind(...params)
+      .run();
+  } catch (cause) {
+    throw new DbError(sql, cause);
+  }
+}
+
+/** Like execute, but returns the number of rows changed — for conditional/optimistic writes. */
+export async function executeWithChanges(
+  db: D1Database,
+  sql: string,
+  params: readonly unknown[] = [],
+): Promise<number> {
+  try {
+    const result = await db
+      .prepare(sql)
+      .bind(...params)
+      .run();
+    return result.meta.changes ?? 0;
+  } catch (cause) {
+    throw new DbError(sql, cause);
+  }
+}

package/src/db/clients.ts

@@ -0,0 +1,103 @@
+import type { Client, ClientStatus } from "../core/types";
+import { execute, queryAll, queryOne } from "./client";
+
+// Raw prepared statements for the `clients` table. Returns plain Client domain objects (camelCase)
+// for the pure core; maps the snake_case D1 row here so no other layer sees column names.
+
+interface ClientRow {
+  id: number;
+  email: string;
+  token: string;
+  status: string;
+  pinned_build_id: number | null;
+  label: string | null;
+  hidden: number;
+  created_at: string;
+  updated_at: string;
+}
+
+function toClient(row: ClientRow): Client {
+  return {
+    id: row.id,
+    email: row.email,
+    token: row.token,
+    status: row.status as ClientStatus,
+    pinnedBuildId: row.pinned_build_id,
+    label: row.label,
+    hidden: row.hidden !== 0,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export interface NewClient {
+  email: string;
+  token: string;
+  label?: string | null;
+}
+
+/** Token lookup for the public gate — by the UNIQUE-indexed column so the DB does the comparison. */
+export async function findByToken(db: D1Database, token: string): Promise<Client | null> {
+  const row = await queryOne<ClientRow>(db, "SELECT * FROM clients WHERE token = ?", [token]);
+  return row ? toClient(row) : null;
+}
+
+export async function getById(db: D1Database, id: number): Promise<Client | null> {
+  const row = await queryOne<ClientRow>(db, "SELECT * FROM clients WHERE id = ?", [id]);
+  return row ? toClient(row) : null;
+}
+
+export async function findByEmail(db: D1Database, email: string): Promise<Client | null> {
+  const row = await queryOne<ClientRow>(db, "SELECT * FROM clients WHERE email = ?", [email]);
+  return row ? toClient(row) : null;
+}
+
+export async function list(db: D1Database): Promise<Client[]> {
+  const rows = await queryAll<ClientRow>(db, "SELECT * FROM clients ORDER BY id");
+  return rows.map(toClient);
+}
+
+export async function insert(db: D1Database, input: NewClient): Promise<Client> {
+  const row = await queryOne<ClientRow>(
+    db,
+    "INSERT INTO clients (email, token, label) VALUES (?, ?, ?) RETURNING *",
+    [input.email, input.token, input.label ?? null],
+  );
+  if (row === null) throw new Error("INSERT clients returned no row");
+  return toClient(row);
+}
+
+export async function setStatus(db: D1Database, id: number, status: ClientStatus): Promise<void> {
+  await execute(db, "UPDATE clients SET status = ?, updated_at = datetime('now') WHERE id = ?", [
+    status,
+    id,
+  ]);
+}
+
+/** Re-issue: replace the token (§12 journey 5). */
+export async function setToken(db: D1Database, id: number, token: string): Promise<void> {
+  await execute(db, "UPDATE clients SET token = ?, updated_at = datetime('now') WHERE id = ?", [
+    token,
+    id,
+  ]);
+}
+
+/** Admin-list visibility (declutter only; does not affect resolution). */
+export async function setHidden(db: D1Database, id: number, hidden: boolean): Promise<void> {
+  await execute(db, "UPDATE clients SET hidden = ?, updated_at = datetime('now') WHERE id = ?", [
+    hidden ? 1 : 0,
+    id,
+  ]);
+}
+
+export async function setPinnedBuild(
+  db: D1Database,
+  id: number,
+  buildId: number | null,
+): Promise<void> {
+  await execute(
+    db,
+    "UPDATE clients SET pinned_build_id = ?, updated_at = datetime('now') WHERE id = ?",
+    [buildId, id],
+  );
+}

package/src/db/meta.ts

@@ -0,0 +1,30 @@
+import { execute, queryAll, queryOne } from "./client";
+
+// §22/§13 — the meta key-value table: branding text, the email template, and self-update bookkeeping.
+
+export async function get(db: D1Database, key: string): Promise<string | null> {
+  const row = await queryOne<{ value: string | null }>(db, "SELECT value FROM meta WHERE key = ?", [
+    key,
+  ]);
+  return row?.value ?? null;
+}
+
+export async function set(db: D1Database, key: string, value: string): Promise<void> {
+  await execute(
+    db,
+    "INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+    [key, value],
+  );
+}
+
+export async function getAll(db: D1Database): Promise<Record<string, string>> {
+  const rows = await queryAll<{ key: string; value: string | null }>(
+    db,
+    "SELECT key, value FROM meta",
+  );
+  const out: Record<string, string> = {};
+  for (const row of rows) {
+    if (row.value !== null) out[row.key] = row.value;
+  }
+  return out;
+}

package/src/db/streams.ts

@@ -0,0 +1,85 @@
+import type { Stream, UserStreamLink } from "../core/types";
+import { execute, queryAll, queryOne } from "./client";
+
+// Raw prepared statements for `streams` and the `user_streams` join (release channels and the
+// per-user assignments the resolver reads).
+
+interface StreamRow {
+  id: number;
+  name: string;
+}
+
+function toStream(row: StreamRow): Stream {
+  return { id: row.id, name: row.name };
+}
+
+export async function create(db: D1Database, name: string): Promise<Stream> {
+  const row = await queryOne<StreamRow>(db, "INSERT INTO streams (name) VALUES (?) RETURNING *", [
+    name,
+  ]);
+  if (row === null) throw new Error("INSERT streams returned no row");
+  return toStream(row);
+}
+
+/** Deletes a channel and its links first (FK-safe): build_streams + user_streams, then the row. */
+export async function remove(db: D1Database, id: number): Promise<void> {
+  await execute(db, "DELETE FROM build_streams WHERE stream_id = ?", [id]);
+  await execute(db, "DELETE FROM user_streams WHERE stream_id = ?", [id]);
+  await execute(db, "DELETE FROM streams WHERE id = ?", [id]);
+}
+
+export async function list(db: D1Database): Promise<Stream[]> {
+  const rows = await queryAll<StreamRow>(db, "SELECT * FROM streams ORDER BY id");
+  return rows.map(toStream);
+}
+
+export async function getByName(db: D1Database, name: string): Promise<Stream | null> {
+  const row = await queryOne<StreamRow>(db, "SELECT * FROM streams WHERE name = ?", [name]);
+  return row ? toStream(row) : null;
+}
+
+export async function getById(db: D1Database, id: number): Promise<Stream | null> {
+  const row = await queryOne<StreamRow>(db, "SELECT * FROM streams WHERE id = ?", [id]);
+  return row ? toStream(row) : null;
+}
+
+export async function assignUser(
+  db: D1Database,
+  clientId: number,
+  streamId: number,
+): Promise<void> {
+  await execute(db, "INSERT OR IGNORE INTO user_streams (client_id, stream_id) VALUES (?, ?)", [
+    clientId,
+    streamId,
+  ]);
+}
+
+export async function unassignUser(
+  db: D1Database,
+  clientId: number,
+  streamId: number,
+): Promise<void> {
+  await execute(db, "DELETE FROM user_streams WHERE client_id = ? AND stream_id = ?", [
+    clientId,
+    streamId,
+  ]);
+}
+
+/** All user→stream links (the resolver/no-build World input). */
+export async function listUserStreams(db: D1Database): Promise<UserStreamLink[]> {
+  const rows = await queryAll<{ client_id: number; stream_id: number }>(
+    db,
+    "SELECT client_id, stream_id FROM user_streams",
+  );
+  return rows.map((row) => ({ clientId: row.client_id, streamId: row.stream_id }));
+}
+
+/** The stream ids one client is assigned to — the slice /appcast needs for a single token. */
+export async function streamIdsForClient(db: D1Database, clientId: number): Promise<number[]> {
+  const rows = await queryAll<{ stream_id: number }>(
+    db,
+    "SELECT stream_id FROM user_streams WHERE client_id = ?",
+    [clientId],
+  );
+  return rows.map((row) => row.stream_id);
+}

package/src/deploy/cli.ts

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync } from "node:fs";
+import net from "node:net";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { type DeployEnv, runDeploy } from "./commands/deploy";
+import { type DevEnv, runDev } from "./commands/dev";
+import { runTeardown, type TeardownEnv } from "./commands/teardown";
+import { selectPalette, shouldColor } from "./core/colors";
+import { resolveStateDir } from "./core/paths";
+import { nowStamp } from "./seams/clock";
+import { createFileSystem } from "./seams/files";
+import { createPrompt } from "./seams/io";
+import { createWrangler } from "./seams/wrangler";
+
+// The deploy CLI entry: assembles the real seams (wrangler/prompt/fs/clock), picks the color palette
+// from the terminal, and dispatches to a command. Run via tsx from the thin deploy/*.sh wrappers OR
+// from the npm `bin` (npx alpha-gate …).
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(here, "../.."); // package root (src/deploy → ../../)
+
+// State lives at <root>/.deploy for a git checkout, ~/.alpha-gate for an npm install (the package
+// files are in the ephemeral npm cache; state there would vanish on the next version). See core/paths.
+const STATE_DIR = resolveStateDir({
+  packageRoot: ROOT,
+  home: process.env.ALPHA_GATE_HOME,
+  userHome: homedir(),
+  isGitCheckout: existsSync(path.join(ROOT, ".git")),
+});
+
+// The self-update manifest the daily cron polls: the npm registry's `/latest` endpoint for THIS
+// package, so the deployed Worker's banner tracks whatever version is published to npm. Derived from
+// package.json's `name`; $UPDATE_MANIFEST_URL overrides (e.g. to point at a fork's own package or a
+// static release.json). Until the package is published to npm, the fetch just 404s and the banner
+// stays quiet — a graceful no-op, same as before.
+function readPkg(): { name?: string; version?: string } {
+  try {
+    return JSON.parse(readFileSync(path.join(ROOT, "package.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function npmManifestUrl(): string {
+  if (process.env.UPDATE_MANIFEST_URL) return process.env.UPDATE_MANIFEST_URL;
+  const name = readPkg().name ?? "alpha-gate";
+  return `https://registry.npmjs.org/${name}/latest`;
+}
+
+// TOOL_VERSION baked into the deployed Worker = the version that deployed it, so the banner compares
+// like-for-like against npm's latest. package.json's `version` is the single source of truth.
+function toolVersion(): string {
+  const fromPkg = readPkg().version;
+  return typeof fromPkg === "string" && fromPkg.length > 0 ? fromPkg : "0.0.0";
+}
+
+const HELP: Record<string, string> = {
+  deploy:
+    "usage: deploy --instance <slug> [options]  (./deploy/deploy.sh or: alpha-gate deploy)\n" +
+    "  Provision D1 + R2, apply migrations, deploy both Workers (idempotent — re-run to update).\n" +
+    "  --instance <slug>            required; namespaces everything (lowercase, digits, hyphens)\n" +
+    "  --app-name / --activate-scheme / --blurb / --accent   first-init branding (prompted if unset)\n" +
+    "  --access-team-domain / --access-aud   wire Cloudflare Access (both together)\n" +
+    "  --email-provider none|cloudflare / --email-from <addr>   automated invites (remembered)\n" +
+    "  --dry-run                    rehearse with wrangler mocked (touches nothing)\n" +
+    "  --yes                        skip the confirm prompt (for non-interactive runs)",
+  dev:
+    "usage: dev [options]  (./deploy/dev.sh or: alpha-gate dev)\n" +
+    "  Run Alpha Gate locally on Miniflare (no Cloudflare account). Starts BOTH Workers by default.\n" +
+    "  --role app|admin             start only one Worker (default: both)\n" +
+    "  --port <n>                   app port (admin is port+1 when both run; default 8787)\n" +
+    "  --no-seed                    skip seeding the demo client/build\n" +
+    "  --reset                      wipe local D1/R2 state first",
+  teardown:
+    "usage: teardown --instance <slug> [options]  (./deploy/teardown.sh or: alpha-gate teardown)\n" +
+    "  Archive D1, then destroy both Workers + D1 (R2 bucket + Access app are removed manually).\n" +
+    "  --instance <slug>            required\n" +
+    "  --no-archive                 skip the D1 backup dump\n" +
+    "  --yes                        skip the type-the-name confirmation\n" +
+    "  --dry-run                    rehearse (touches nothing)",
+};
+
+// Probes whether Cloudflare Access is enabled on the admin URL. When it is, the origin 302-redirects
+// an unauthenticated request to `https://<team>.cloudflareaccess.com/cdn-cgi/access/login/…` — so one
+// GET both CONFIRMS Access is on and reveals the team domain, saving the operator a copy step and
+// catching "you pressed Enter but didn't actually enable it". Injected so the deploy flow stays
+// unit-testable offline.
+async function probeAccess(
+  adminUrl: string,
+): Promise<{ enabled: boolean; teamDomain: string | null }> {
+  try {
+    const res = await fetch(adminUrl, { method: "GET", redirect: "manual" });
+    const location = res.headers.get("location") ?? "";
+    const m = /^https?:\/\/([^/]+\.cloudflareaccess\.com)\//.exec(location);
+    if (m?.[1]) return { enabled: true, teamDomain: m[1] };
+    // A 200 (or a redirect elsewhere) means Access isn't gating this hostname yet.
+    return { enabled: false, teamDomain: null };
+  } catch {
+    return { enabled: false, teamDomain: null };
+  }
+}
+
+// True if something already listens on 127.0.0.1:port (a successful TCP connect). Used by `dev` to
+// catch a stale/orphaned server before wrangler falsely reports "Ready" on a port it doesn't own.
+function portInUse(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect({ port, host: "127.0.0.1" });
+    const done = (busy: boolean) => {
+      socket.destroy();
+      resolve(busy);
+    };
+    socket.setTimeout(1000);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+const shared = (rest: readonly string[]) => ({
+  // cwd = the package root so `npx wrangler` finds the bundled wrangler even from an npx install.
+  wrangler: createWrangler({ dryRun: rest.includes("--dry-run"), cwd: ROOT }),
+  prompt: createPrompt(),
+  fs: createFileSystem(),
+  palette: selectPalette(shouldColor(process.env, process.stdout.isTTY === true)),
+  out: (line: string) => console.log(line),
+  rootDir: ROOT,
+  stateDir: STATE_DIR,
+  interactive: process.stdin.isTTY === true,
+});
+
+async function main(): Promise<number> {
+  const [command, ...rest] = process.argv.slice(2);
+
+  // Help is a first-class exit, not an "unknown flag" error (the old circular-hint bug).
+  if (command === undefined || command === "--help" || command === "-h") {
+    console.log("usage: <deploy|dev|teardown> [options] — run with a command + --help for details");
+    return 0;
+  }
+  if ((rest.includes("--help") || rest.includes("-h")) && HELP[command]) {
+    console.log(HELP[command]);
+    return 0;
+  }
+
+  if (command === "deploy") {
+    const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    const env: DeployEnv = {
+      ...shared(rest),
+      toolVersion: toolVersion(),
+      updateManifestUrl: npmManifestUrl(),
+      nodeMajor,
+      probeAccess,
+    };
+    return runDeploy(rest, env);
+  }
+
+  if (command === "teardown") {
+    const env: TeardownEnv = { ...shared(rest), nowStamp };
+    return runTeardown(rest, env);
+  }
+
+  if (command === "dev") {
+    const env: DevEnv = {
+      ...shared(rest),
+      toolVersion: toolVersion(),
+      updateManifestUrl: npmManifestUrl(),
+      portInUse,
+    };
+    return runDev(rest, env);
+  }
+
+  console.error("usage: cli.ts <deploy|teardown|dev> [flags]");
+  return 1;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });