create-mailslot 0.0.1 → 0.1.0

package/README.md

@@ -1,11 +1,43 @@
 # create-mailslot
 
 Deploy [Mailslot](https://github.com/mailslot/mailslot) — a self-hosted email
-inbox for AI agents — to your own Cloudflare account.
+inbox for AI agents — to your own Cloudflare account, interactively.
 
 > Your agent's email shouldn't come with a landlord.
 
-The wizard is **not released yet**; this package currently points you to the
-[manual setup guide](https://github.com/mailslot/mailslot#quick-start)
-(~10 minutes). When released, `npx create-mailslot` will handle Email Routing,
-storage, secrets, and a live round-trip test end to end.
+```sh
+npx create-mailslot
+```
+
+The wizard:
+
+1. **Scaffolds a project you own** — a thin worker depending on
+   `@mailslot/core`, deployed from your machine with wrangler
+2. **Guards your existing mail** — if the domain's apex already receives
+   mail elsewhere (Google Workspace, Lark, O365…), the wizard tells you the
+   truth: Email Routing is zone-level, so that domain can't host Mailslot —
+   not even on a subdomain — without breaking its mail. It steers you to a
+   different domain instead of letting you find out the hard way
+3. **Provisions everything** — R2 bucket, generated API token (secret),
+   worker deploy with your domain baked in
+4. **Sets up Email Routing** — fully automatic with a Cloudflare API token
+   (`Zone → Email Routing Rules → Edit`), or guided dashboard steps with
+   live DNS verification if you'd rather click
+5. **Proves it works** — ends with a live round-trip: send an email from
+   your phone, watch it appear in your terminal
+
+## Flags (all optional — omitted values are prompted)
+
+```
+--dir <path>           project directory            (default: mailslot)
+--domain <domain>      email domain on Cloudflare   (e.g. mail.example.com)
+--worker-name <name>   worker name                  (default: mailslot)
+--cf-token <token>     Cloudflare API token for Email Routing setup
+--core-spec <spec>     @mailslot/core version/spec  (default: ^0.0.2)
+--skip-install / --skip-routing / --skip-test
+```
+
+`CLOUDFLARE_API_TOKEN` in the environment is also honored.
+
+Requirements: Node 18+, a Cloudflare account (free tier works), a domain on
+Cloudflare.

package/index.js

@@ -1,13 +1,7 @@
 #!/usr/bin/env node
+import { run } from "./lib/run.js";
 
-console.log(`
-  Mailslot — self-hosted email inbox for AI agents,
-  on your own Cloudflare account, on your own domain.
-
-  The deploy wizard isn't released yet. Manual setup
-  takes ~10 minutes today:
-
-    https://github.com/mailslot/mailslot#quick-start
-
-  Star/watch the repo to catch the wizard release.
-`);
+run(process.argv.slice(2)).catch((e) => {
+  console.error(`\ncreate-mailslot failed: ${e.message}`);
+  process.exit(1);
+});

package/lib/cf-api.js

@@ -0,0 +1,47 @@
+const API = "https://api.cloudflare.com/client/v4";
+
+async function cf(token, path, init = {}) {
+  const res = await fetch(API + path, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json",
+      ...init.headers
+    }
+  });
+  const body = await res.json().catch(() => null);
+  if (!body?.success) {
+    const msg = body?.errors?.map((e) => e.message).join("; ") || `HTTP ${res.status}`;
+    const err = new Error(msg);
+    err.status = res.status;
+    throw err;
+  }
+  return body.result;
+}
+
+export async function zoneId(token, zoneName) {
+  const zones = await cf(token, `/zones?name=${encodeURIComponent(zoneName)}`);
+  return zones?.[0]?.id ?? null;
+}
+
+export function routingStatus(token, zid) {
+  return cf(token, `/zones/${zid}/email/routing`);
+}
+
+/** Enable Email Routing on the zone apex (adds MX/SPF). Best-effort. */
+export function enableRouting(token, zid) {
+  return cf(token, `/zones/${zid}/email/routing/enable`, { method: "POST" });
+}
+
+/** Point the zone's catch-all rule at a Worker. */
+export function setCatchAllToWorker(token, zid, workerName) {
+  return cf(token, `/zones/${zid}/email/routing/rules/catch_all`, {
+    method: "PUT",
+    body: JSON.stringify({
+      name: "mailslot catch-all",
+      enabled: true,
+      matchers: [{ type: "all" }],
+      actions: [{ type: "worker", value: [workerName] }]
+    })
+  });
+}

package/lib/dns.js

@@ -0,0 +1,67 @@
+const DOH = "https://cloudflare-dns.com/dns-query";
+const TYPE_IDS = { A: 1, NS: 2, MX: 15 };
+
+/** Resolve via DNS-over-HTTPS (no system dig dependency). */
+export async function dohResolve(name, type) {
+  const res = await fetch(`${DOH}?name=${encodeURIComponent(name)}&type=${type}`, {
+    headers: { accept: "application/dns-json" }
+  });
+  if (!res.ok) throw new Error(`DNS lookup failed (${res.status})`);
+  const data = await res.json();
+  return (data.Answer ?? [])
+    .filter((a) => a.type === TYPE_IDS[type])
+    .map((a) => String(a.data).toLowerCase());
+}
+
+export const mxRecords = (domain, resolve = dohResolve) => resolve(domain, "MX");
+
+export function isCloudflareMx(records) {
+  return records.some((r) => r.includes("mx.cloudflare.net"));
+}
+
+export function isCloudflareNs(records) {
+  return records.some((r) => r.includes("ns.cloudflare.com"));
+}
+
+/**
+ * Zone-level Email Routing state, inferred from the APEX MX records.
+ *
+ * Email Routing is a zone-level feature: subdomains can only be enrolled
+ * AFTER the zone has Email Routing enabled, and enabling it requires
+ * Cloudflare to own the apex MX. Consequences:
+ *   "cloudflare" — routing enabled; apex and subdomains both usable
+ *   "none"       — no mail yet; routing can be enabled cleanly
+ *   "foreign"    — apex mail lives elsewhere (Google/Lark/O365…); the zone
+ *                  CANNOT be used for Mailslot — not even via a subdomain —
+ *                  without deleting the provider's MX (breaking that mail)
+ */
+export function zoneRoutingState(apexMxRecords) {
+  if (apexMxRecords.length === 0) return "none";
+  return isCloudflareMx(apexMxRecords) ? "cloudflare" : "foreign";
+}
+
+/**
+ * Walk labels upward until a zone apex (has NS records) is found.
+ * mail.foo.example.com → example.com (where NS answers).
+ */
+export async function findZone(domain, resolve = dohResolve) {
+  const labels = domain.split(".").filter(Boolean);
+  for (let i = 0; i <= labels.length - 2; i++) {
+    const candidate = labels.slice(i).join(".");
+    const ns = await resolve(candidate, "NS");
+    if (ns.length > 0) return { zone: candidate, ns };
+  }
+  return null;
+}
+
+/** Poll until the domain's MX records point at Cloudflare, or time out. */
+export async function waitForCloudflareMx(domain, { timeoutMs = 300_000, intervalMs = 5_000, onTick } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const mx = await mxRecords(domain).catch(() => []);
+    if (isCloudflareMx(mx)) return true;
+    onTick?.();
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}

package/lib/run.js

@@ -0,0 +1,339 @@
+import { randomBytes } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import * as p from "@clack/prompts";
+import { sh, shInteractive, sleep } from "./sh.js";
+import { mxRecords, isCloudflareMx, isCloudflareNs, findZone, waitForCloudflareMx, zoneRoutingState } from "./dns.js";
+import { templates, writeScaffold } from "./scaffold.js";
+import { zoneId, routingStatus, enableRouting, setCatchAllToWorker } from "./cf-api.js";
+
+export function parseArgs(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+function bail(value) {
+  if (p.isCancel(value)) {
+    p.cancel("Setup cancelled — nothing was deployed.");
+    process.exit(0);
+  }
+  return value;
+}
+
+export async function run(argv) {
+  const flags = parseArgs(argv);
+
+  p.intro("create-mailslot — your agent's inbox, on your own Cloudflare account");
+
+  // ---- gather inputs ----
+  const dir = resolve(
+    flags.dir ??
+      bail(await p.text({ message: "Project directory", initialValue: "mailslot", validate: (v) => (v.trim() ? undefined : "required") }))
+  );
+
+  let domain = String(
+    flags.domain ??
+      bail(
+        await p.text({
+          message: "Email domain for agent addresses (on Cloudflare)",
+          placeholder: "mail.example.com",
+          validate: (v) => (/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(v.trim()) ? undefined : "enter a domain like mail.example.com")
+        })
+      )
+  )
+    .trim()
+    .toLowerCase();
+
+  const workerName = String(
+    flags["worker-name"] ??
+      bail(await p.text({ message: "Worker name", initialValue: "mailslot", validate: (v) => (/^[a-z0-9-]+$/.test(v) ? undefined : "lowercase letters, digits, dashes") }))
+  );
+
+  // ---- DNS analysis & the zone-routing reality check ----
+  // Email Routing is zone-level: a subdomain only works once the ZONE has
+  // Email Routing enabled, and enabling it requires Cloudflare to own the
+  // apex MX. A zone whose apex mail lives elsewhere cannot host Mailslot
+  // at all (not even via a subdomain) without breaking that mail.
+  const s = p.spinner();
+  let apex;
+  let zoneState; // "cloudflare" | "none" | "foreign" (foreign only if user forces)
+  for (;;) {
+    s.start("Checking DNS");
+    const zone = await findZone(domain).catch(() => null);
+    if (!zone) {
+      s.stop("DNS check failed");
+      throw new Error(`could not find a DNS zone for ${domain} — is the domain registered and on Cloudflare?`);
+    }
+    apex = zone.zone;
+    const onCloudflare = isCloudflareNs(zone.ns);
+    const apexMx = await mxRecords(apex).catch(() => []);
+    zoneState = zoneRoutingState(apexMx);
+    s.stop(`Zone: ${apex}${onCloudflare ? " (Cloudflare ✓)" : ""} — email routing: ${zoneState}`);
+
+    if (!onCloudflare) {
+      p.log.warn(`${apex} does not appear to use Cloudflare nameservers.\nMailslot requires the zone to be on Cloudflare (free plan is fine).`);
+      const cont = bail(await p.confirm({ message: "Continue anyway?", initialValue: false }));
+      if (!cont) return p.outro("Add the domain to Cloudflare first, then re-run.");
+    }
+
+    if (zoneState !== "foreign") break;
+
+    p.log.error(
+      `${apex} already receives mail elsewhere (MX: ${apexMx[0]} …).\n\n` +
+        `Cloudflare Email Routing is zone-level: enabling it requires replacing\n` +
+        `the apex MX records, and subdomains can only be added AFTER the zone\n` +
+        `has Email Routing enabled. This domain cannot host Mailslot — not even\n` +
+        `on a subdomain — without breaking its existing email.`
+    );
+    if (flags.domain) {
+      throw new Error(`${apex} has a third-party mail provider — use a different domain (zone) for Mailslot`);
+    }
+    const choice = bail(
+      await p.select({
+        message: "What now?",
+        options: [
+          { value: "different", label: "Use a different domain (recommended — a spare domain or a fresh one)" },
+          { value: "force", label: `Proceed with ${apex} anyway (I will delete my provider's MX — BREAKS existing mail)` },
+          { value: "abort", label: "Abort" }
+        ]
+      })
+    );
+    if (choice === "abort") return p.outro("No changes made. A dedicated domain for agent mail is cheap and clean.");
+    if (choice === "force") {
+      const sure = bail(await p.confirm({ message: `Really proceed? Mail to @${apex} will stop working until you reconfigure it.`, initialValue: false }));
+      if (sure) break;
+      continue;
+    }
+    domain = String(
+      bail(
+        await p.text({
+          message: "Email domain for agent addresses (on Cloudflare)",
+          placeholder: "agentmail-domain.com",
+          validate: (v) => (/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(v.trim()) ? undefined : "enter a valid domain")
+        })
+      )
+    )
+      .trim()
+      .toLowerCase();
+  }
+
+  const domainMx = await mxRecords(domain).catch(() => []);
+  const routingReady = isCloudflareMx(domainMx);
+
+  // ---- scaffold ----
+  const coreSpec = flags["core-spec"] ?? "^0.0.2";
+  const files = templates({ workerName, coreSpec });
+  await writeScaffold(dir, files);
+  p.log.success(`Scaffolded ${dir}`);
+
+  if (!flags["skip-install"]) {
+    p.log.step("Installing dependencies…");
+    const code = await shInteractive("npm", ["install", "--no-fund", "--no-audit"], { cwd: dir });
+    if (code !== 0) throw new Error("npm install failed");
+  }
+
+  const wrangler = (args, opts = {}) => sh("npx", ["wrangler", ...args], { cwd: dir, ...opts });
+
+  // ---- wrangler auth ----
+  const who = await wrangler(["whoami"]);
+  if (!/You are logged in/i.test(who.all)) {
+    p.log.step("Logging in to Cloudflare (browser will open)…");
+    const code = await shInteractive("npx", ["wrangler", "login"], { cwd: dir });
+    if (code !== 0) throw new Error("wrangler login failed");
+  }
+
+  // ---- provision: bucket, token, deploy ----
+  s.start("Creating R2 bucket");
+  const bucket = await wrangler(["r2", "bucket", "create", `${workerName}-raw`]);
+  if (bucket.code !== 0 && !/already exists/i.test(bucket.all)) {
+    s.stop("R2 bucket failed");
+    throw new Error(`could not create R2 bucket: ${bucket.err.slice(0, 300)}`);
+  }
+  s.stop("R2 bucket ready");
+
+  const token = randomBytes(24).toString("hex");
+  s.start("Setting MAILSLOT_TOKEN secret");
+  const secret = await wrangler(["secret", "put", "MAILSLOT_TOKEN"], { input: token + "\n" });
+  if (secret.code !== 0) {
+    s.stop("Secret failed");
+    throw new Error(`could not set secret: ${secret.err.slice(0, 300)}`);
+  }
+  s.stop("Token secret set");
+
+  s.start("Deploying worker");
+  const deploy = await wrangler(["deploy", "--var", `EMAIL_DOMAIN:${domain}`]);
+  if (deploy.code !== 0) {
+    s.stop("Deploy failed");
+    throw new Error(`wrangler deploy failed:\n${deploy.all.slice(-600)}`);
+  }
+  const workerUrl = deploy.all.match(/https:\/\/[a-z0-9.-]+\.workers\.dev/i)?.[0] ?? null;
+  s.stop(`Deployed${workerUrl ? `: ${workerUrl}` : ""}`);
+
+  await writeFile(join(dir, ".dev.vars"), `MAILSLOT_TOKEN=${token}\nEMAIL_DOMAIN=${domain}\n`);
+
+  if (workerUrl) {
+    const health = await fetch(`${workerUrl}/v1/health`).then((r) => r.ok).catch(() => false);
+    if (health) p.log.success("Health check passed");
+  }
+
+  // ---- email routing ----
+  if (!flags["skip-routing"]) {
+    await setupRouting({ apex, domain, workerName, routingReady, zoneState, flags });
+  }
+
+  // ---- round-trip finale ----
+  if (!flags["skip-test"] && workerUrl) {
+    await roundTrip({ workerUrl, token, domain });
+  }
+
+  p.note(
+    [
+      `Worker      ${workerUrl ?? "(see wrangler output)"}`,
+      `Domain      ${domain}`,
+      `API token   ${dir}/.dev.vars (keep it safe)`,
+      ``,
+      `Connect an agent (MCP):`,
+      `  claude mcp add mailslot ${workerUrl ?? "<worker-url>"}/mcp \\`,
+      `    --transport http --header "Authorization: Bearer <token>"`,
+      ``,
+      `Mint an address:`,
+      `  curl -X POST ${workerUrl ?? "<worker-url>"}/v1/addresses \\`,
+      `    -H "Authorization: Bearer <token>"`
+    ].join("\n"),
+    "Your agent has email now"
+  );
+  p.outro("Docs & issues: https://github.com/mailslot/mailslot");
+}
+
+async function setupRouting({ apex, domain, workerName, routingReady, zoneState, flags }) {
+  const isSubdomain = domain !== apex;
+  let token = flags["cf-token"] ?? process.env.CLOUDFLARE_API_TOKEN ?? null;
+  if (!token) {
+    const entered = bail(
+      await p.password({
+        message:
+          "Cloudflare API token for Email Routing setup (Enter to skip and use guided steps).\n" +
+          "  Create one at dash.cloudflare.com → My Profile → API Tokens with:\n" +
+          "  Zone → Email Routing Rules → Edit, Zone → Zone → Read (this zone)",
+        mask: "•"
+      })
+    );
+    token = entered && String(entered).trim() ? String(entered).trim() : null;
+  }
+
+  if (token) {
+    try {
+      const zid = await zoneId(token, apex);
+      if (!zid) throw new Error(`zone ${apex} not visible to this token`);
+
+      // Zone-level enable comes first — subdomains can only be enrolled
+      // once the zone has Email Routing.
+      if (zoneState !== "cloudflare") {
+        const status = await routingStatus(token, zid).catch(() => null);
+        if (status?.enabled !== true) await enableRouting(token, zid);
+        await waitForCloudflareMx(apex, { timeoutMs: 120_000 });
+        p.log.success(`Email Routing enabled on ${apex}`);
+      }
+
+      if (!routingReady && isSubdomain) {
+        // No public API for subdomain enrollment — guided step, then verify.
+        await guidedSubdomain(apex, domain);
+      }
+
+      await setCatchAllToWorker(token, zid, workerName);
+      p.log.success(`Catch-all rule → worker "${workerName}"`);
+      return;
+    } catch (e) {
+      p.log.warn(`API setup incomplete (${e.message}) — falling back to guided steps.`);
+    }
+  }
+
+  // Guided path
+  if (!routingReady) {
+    if (zoneState !== "cloudflare") {
+      p.note(
+        [
+          `1. dash.cloudflare.com → ${apex} → Email Routing`,
+          ...(zoneState === "foreign"
+            ? [`2. Delete the existing third-party MX records when prompted`, `   (this is the step that breaks your old mail — you chose this)`, `3. Enable Email Routing (accept the MX/SPF records)`]
+            : [`2. Enable Email Routing (accept the MX/SPF records)`])
+        ].join("\n"),
+        `Enable Email Routing on ${apex}`
+      );
+      await waitForMxInteractive(apex);
+    }
+    if (isSubdomain) await guidedSubdomain(apex, domain);
+  }
+  p.note(
+    [
+      `1. ${apex} → Email Routing → Routing rules`,
+      `2. Catch-all address → Edit`,
+      `3. Action: "Send to a Worker" → ${workerName}`,
+      `4. Toggle: Enabled  ← easy to miss`
+    ].join("\n"),
+    "Point mail at the worker"
+  );
+  bail(await p.confirm({ message: "Catch-all rule set and enabled?", initialValue: true }));
+}
+
+async function guidedSubdomain(apex, domain) {
+  const sub = domain.slice(0, -(apex.length + 1));
+  p.note(
+    [
+      `(requires Email Routing already enabled on ${apex})`,
+      `1. dash.cloudflare.com → ${apex} → Email Routing → Settings`,
+      `2. Subdomains → add "${sub}"`,
+      `3. Cloudflare writes MX/SPF records on ${domain}`
+    ].join("\n"),
+    "Add the subdomain to Email Routing"
+  );
+  await waitForMxInteractive(domain);
+}
+
+async function waitForMxInteractive(domain) {
+  const s = p.spinner();
+  s.start(`Waiting for Cloudflare MX records on ${domain}`);
+  const ok = await waitForCloudflareMx(domain, { timeoutMs: 300_000 });
+  if (ok) s.stop(`MX records live on ${domain}`);
+  else {
+    s.stop("Timed out waiting for MX records");
+    throw new Error(`MX records for ${domain} did not appear — complete the dashboard step and re-run`);
+  }
+}
+
+async function roundTrip({ workerUrl, token, domain }) {
+  const local = `welcome-${randomBytes(3).toString("hex")}`;
+  const address = `${local}@${domain}`;
+  p.log.step(`Round-trip test — send any email to:  ${address}`);
+  const s = p.spinner();
+  s.start("Waiting for your email (up to 5 minutes, Ctrl+C to skip)");
+  const deadline = Date.now() + 300_000;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(
+        `${workerUrl}/v1/inboxes/${encodeURIComponent(address)}/wait?timeout_s=50&since_s=600`,
+        { headers: { authorization: `Bearer ${token}` } }
+      );
+      const data = await res.json();
+      if (data.message) {
+        s.stop(`Received: "${data.message.subject}" from ${data.message.from} ✓`);
+        return;
+      }
+    } catch {
+      await sleep(3000);
+    }
+  }
+  s.stop("No email arrived — check the catch-all rule, then test manually (see README).");
+}

package/lib/scaffold.js

@@ -0,0 +1,109 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+/** Render the files of a scaffolded Mailslot project. */
+export function templates({ workerName, coreSpec = "^0.0.2" }) {
+  const pkg = {
+    name: workerName,
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "wrangler dev",
+      deploy: "wrangler deploy",
+      "cf-typegen": "wrangler types"
+    },
+    dependencies: {
+      "@mailslot/core": coreSpec
+    },
+    devDependencies: {
+      wrangler: "^4.0.0"
+    }
+  };
+
+  const wranglerConfig = `{
+  "$schema": "https://unpkg.com/wrangler/config-schema.json",
+  "name": ${JSON.stringify(workerName)},
+  "main": "src/index.ts",
+  "compatibility_date": "2026-04-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      { "name": "Inbox", "class_name": "Inbox" },
+      { "name": "MailslotMcp", "class_name": "MailslotMcp" }
+    ]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["Inbox", "MailslotMcp"] }
+  ],
+  "r2_buckets": [
+    { "binding": "RAW", "bucket_name": ${JSON.stringify(`${workerName}-raw`)} }
+  ],
+  "vars": {
+    "FORWARD_MODE": "none"
+  },
+  // Instance values (EMAIL_DOMAIN var, MAILSLOT_TOKEN secret) are set by the
+  // wizard and survive deploys thanks to keep_vars.
+  "keep_vars": true,
+  "alias": {
+    // Optional dep of the agents SDK, dynamically imported in unused paths
+    "ai": "./src/shims/ai.ts"
+  },
+  "observability": { "enabled": true }
+}
+`;
+
+  const indexTs = `export { Inbox, MailslotMcp } from "@mailslot/core";
+export { default } from "@mailslot/core";
+`;
+
+  const aiShim = `/** Stub for the agents SDK's optional dynamic import("ai"). Unused by Mailslot. */
+export function jsonSchema(): never {
+  throw new Error("The 'ai' package is not installed — this code path is unused by Mailslot.");
+}
+`;
+
+  const devVarsExample = `# Copy to .dev.vars for local development (never commit .dev.vars)
+MAILSLOT_TOKEN=replace-me
+EMAIL_DOMAIN=mail.example.com
+`;
+
+  const gitignore = `node_modules/
+.wrangler/
+.dev.vars
+`;
+
+  const readme = `# ${workerName}
+
+A self-hosted [Mailslot](https://github.com/mailslot/mailslot) instance —
+email inbox for AI agents on your own Cloudflare account.
+
+Created with \`npx create-mailslot\`. Deploy updates with \`npm run deploy\`;
+upgrade by bumping \`@mailslot/core\`.
+
+Your API/MCP token is in \`.dev.vars\` (gitignored). MCP endpoint: \`/mcp\`.
+`;
+
+  return {
+    "package.json": JSON.stringify(pkg, null, 2) + "\n",
+    "wrangler.jsonc": wranglerConfig,
+    "src/index.ts": indexTs,
+    "src/shims/ai.ts": aiShim,
+    ".dev.vars.example": devVarsExample,
+    ".gitignore": gitignore,
+    "README.md": readme
+  };
+}
+
+/** Write scaffold files. Refuses to write into a non-empty directory. */
+export async function writeScaffold(dir, files) {
+  await mkdir(dir, { recursive: true });
+  const existing = await readdir(dir);
+  if (existing.length > 0) {
+    throw new Error(`directory "${dir}" is not empty — pick a fresh directory`);
+  }
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(dir, rel);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content);
+  }
+}

package/lib/sh.js

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+
+/** Run a command, capture output. Never rejects — inspect .code. */
+export function sh(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env }
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    if (opts.input !== undefined) child.stdin.write(opts.input);
+    child.stdin.end();
+    child.on("error", (e) => resolve({ code: -1, out, err: String(e), all: out + err }));
+    child.on("close", (code) => resolve({ code, out, err, all: out + err }));
+  });
+}
+
+/** Run a command with inherited stdio (interactive). Resolves with exit code. */
+export function shInteractive(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: "inherit", cwd: opts.cwd });
+    child.on("error", () => resolve(-1));
+    child.on("close", (code) => resolve(code));
+  });
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "create-mailslot",
-  "version": "0.0.1",
-  "description": "Deploy Mailslot — a self-hosted email inbox for AI agents — to your own Cloudflare account. Wizard coming soon.",
+  "version": "0.1.0",
+  "description": "Deploy Mailslot \u2014 a self-hosted email inbox for AI agents \u2014 to your own Cloudflare account.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "create-mailslot": "./index.js"
+    "create-mailslot": "index.js"
   },
   "files": [
     "index.js",
+    "lib",
     "README.md"
   ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/mailslot/mailslot"
+    "url": "git+https://github.com/mailslot/mailslot.git"
   },
   "homepage": "https://mailslot.dev",
   "keywords": [
@@ -26,6 +33,6 @@
   ],
   "scripts": {
     "typecheck": "true",
-    "test": "true"
+    "test": "node --test"
   }
 }