@bigrandall/rrangler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Randall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# rrangler
+
+A **wrangler-compatible CLI for RandallFlare** — the edge platform inside
+bigrandall.io. Where `wrangler` talks to Cloudflare, `rrangler` talks to your
+RandallFlare account's edge API (`/api/edge/v1/*`). Same command shape, so
+muscle memory (and `wrangler.toml`) carry over.
+
+Zero dependencies — plain Node ≥ 20 ESM.
+
+## Install
+
+```bash
+npm i -g @bigrandall/rrangler    # published package (the command is `rrangler`)
+rrangler --version
+```
+
+Or run without installing:
+
+```bash
+npx @bigrandall/rrangler whoami
+```
+
+From a checkout of this repo:
+
+```bash
+npm i -g ./rrangler          # or `npm link` inside rrangler/
+# or directly: node rrangler/bin/rrangler.mjs <command>
+```
+
+Zero runtime dependencies — just Node ≥ 20.
+
+## Auth
+
+Create an **API token** in bigrandall.io → `/me/edge` → API tokens (pick the
+scopes you need: `worker:*`, `d1:*`, `r2:*`, `kv:*`, or `*`). Then:
+
+```bash
+rrangler login --token rft_xxx        # saved to ~/.rrangler.json (chmod 600)
+rrangler whoami
+rrangler doctor                        # connectivity + which endpoints your scopes allow
+```
+
+Or per-invocation: `RRANGLER_TOKEN=… rrangler …` / `--token …`.
+Point at another instance with `RRANGLER_API` / `--api https://…`.
+
+## Commands
+
+Mirrors wrangler — `publish` aliases to `deploy`, `kv:namespace` works too.
+
+| rrangler | does |
+| --- | --- |
+| `init [name]` | scaffold `rrangler.json` + `main.js` |
+| `deploy [--name s]` | push local files to a worker (reads `rrangler.json`, `rrangler.toml`, or `wrangler.toml`) |
+| `worker list` / `worker get <slug>` | list / inspect workers |
+| `tail <slug>` | stream runtime logs |
+| `worker env set <slug> K=V …` / `delete` | env vars (`--secret` to mask) |
+| `worker builds <slug>` / `build <slug> [--branch]` / `build-log <slug> <id>` | git builds |
+| `worker cron <slug> [--dlq]` / `cron replay <slug> <runId>` | cron runs + DLQ replay |
+| `secret put <KEY> --worker <slug>` | set a secret (value from `--value` or stdin) |
+| `secret list \| delete` | manage secrets |
+| `d1 list \| create <name> \| info <db>` | Durable SQLite databases |
+| `d1 execute <db> --command '<sql>'` | run SQL (`--file f.sql` too) |
+| `d1 export <db> [--output f]` | dump schema + data as SQL |
+| `d1 migrations create \| list \| apply` | file-based migrations (`--dir migrations`) |
+| `kv namespace list \| create <title>` | KV namespaces |
+| `kv key put <ns> <key> <value>` / `get` / `list` / `delete` | KV entries |
+| `kv bulk put \| delete <ns> <file.json>` | bulk KV |
+| `dev [--port]` | run the worker locally on **workerd** (prod runtime) |
+| `types [--out f]` | generate a bindings `Env` d.ts |
+| `secret bulk <file.json> --worker <slug>` | bulk secrets |
+| `r2 bucket list \| create <name> [--public]` | R2 buckets |
+| `r2 object put <bucket> <key> <file>` / `get` / `delete` | R2 objects |
+| `pages list` / `get <slug>` | Pages projects |
+| `pages env set\|delete` / `builds` / `build [--branch]` / `build-log` / `tail` | Pages ops |
+| `api <METHOD> <path> [--data '<json>']` | raw API passthrough |
+
+Global flags: `--json` (machine-readable stdout), `--api`, `--token`.
+
+## Deploy config
+
+`rrangler.json`:
+
+```json
+{
+  "name": "my-worker",
+  "main": "main.js",
+  "files": ["main.js", "lib/util.js"],
+  "compatibilityDate": "2026-07-05"
+}
+```
+
+`name` is the worker slug (create the worker once in `/me/edge`, then deploy
+to it). `files` is optional — omit it to send just `main`. A `wrangler.toml`
+with `name` / `main` is read as a fallback for drop-in compatibility.
+
+## Beyond wrangler
+
+- `doctor` — one-shot health + capability probe (what your token can actually do).
+- `api` — raw authenticated call to any `/api/edge/v1/*` endpoint for scripting.
+- `--json` on every read command for piping into `jq`.
+- Reads `rrangler.json` **or** `wrangler.toml`, so an existing CF project deploys
+  to RandallFlare without a rewrite.

package/bin/rrangler.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// rrangler — a wrangler-compatible CLI for RandallFlare (bigrandall.io).
+//
+// Usage: rrangler <command> [subcommand] [args] [--flags]
+// See `rrangler help`.
+
+import * as cmd from "../commands/index.mjs";
+import { style, fail } from "../lib/ui.mjs";
+import { ApiError } from "../lib/api.mjs";
+
+const ROUTES = {
+  login: cmd.login,
+  logout: cmd.logout,
+  whoami: cmd.whoami,
+  doctor: cmd.doctor,
+  init: cmd.init,
+  deploy: cmd.deploy,
+  dev: cmd.dev,
+  tail: cmd.tail,
+  types: cmd.types,
+  api: cmd.apiPassthrough,
+  "deployments list": cmd.workerBuilds,
+  "versions list": cmd.workerBuilds,
+
+  "worker list": cmd.workerList,
+  "worker get": cmd.workerGet,
+  "worker builds": cmd.workerBuilds,
+  "worker build": cmd.workerBuild,
+  "worker build-log": cmd.workerBuildLog,
+  "worker env set": cmd.workerEnvSet,
+  "worker env delete": cmd.workerEnvDelete,
+  "worker cron": cmd.workerCron,
+  "worker cron replay": cmd.workerCronReplay,
+
+  "secret put": cmd.secretPut,
+  "secret list": cmd.secretList,
+  "secret delete": cmd.secretDelete,
+  "secret bulk": cmd.secretBulk,
+
+  "d1 list": cmd.d1List,
+  "d1 create": cmd.d1Create,
+  "d1 execute": cmd.d1Execute,
+  "d1 export": cmd.d1Export,
+  "d1 info": cmd.d1Info,
+  "d1 migrations create": cmd.d1MigrationsCreate,
+  "d1 migrations list": cmd.d1MigrationsList,
+  "d1 migrations apply": cmd.d1MigrationsApply,
+
+  "kv namespace list": cmd.kvNamespaceList,
+  "kv namespace create": cmd.kvNamespaceCreate,
+  "kv key get": cmd.kvKeyGet,
+  "kv key put": cmd.kvKeyPut,
+  "kv key list": cmd.kvKeyList,
+  "kv key delete": cmd.kvKeyDelete,
+  "kv bulk put": cmd.kvBulkPut,
+  "kv bulk delete": cmd.kvBulkDelete,
+
+  "r2 bucket list": cmd.r2BucketList,
+  "r2 bucket create": cmd.r2BucketCreate,
+  "r2 object get": cmd.r2ObjectGet,
+  "r2 object put": cmd.r2ObjectPut,
+  "r2 object delete": cmd.r2ObjectDelete,
+
+  "pages list": cmd.pagesList,
+  "pages project list": cmd.pagesList,
+  "pages deployment list": cmd.pagesBuilds,
+  "pages deploy": cmd.pagesBuild,
+  "pages get": cmd.pagesGet,
+  "pages env set": cmd.pagesEnvSet,
+  "pages env delete": cmd.pagesEnvDelete,
+  "pages builds": cmd.pagesBuilds,
+  "pages build": cmd.pagesBuild,
+  "pages build-log": cmd.pagesBuildLog,
+  "pages tail": cmd.pagesTail,
+};
+
+// wrangler-compat rewrites applied to the raw command tokens.
+function normalize(tokens) {
+  return tokens
+    .flatMap((t) => t.split(":")) // kv:namespace → kv namespace
+    .map((t) => {
+      if (t === "publish") return "deploy"; // wrangler alias
+      if (t === "ls") return "list";
+      if (t === "rm" || t === "del") return "delete";
+      if (t === "buckets") return "bucket";
+      if (t === "namespaces") return "namespace";
+      return t;
+    });
+}
+
+function parseArgs(argv) {
+  const pos = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--")) flags[key] = true;
+        else {
+          flags[key] = next;
+          i++;
+        }
+      }
+    } else {
+      pos.push(a);
+    }
+  }
+  return { pos, flags };
+}
+
+const HELP = `${style.bold("rrangler")} — wrangler-compatible CLI for RandallFlare (bigrandall.io)
+
+${style.bold("auth")}
+  rrangler login --token <t>        save an API token (from /me/edge → API tokens)
+  rrangler logout
+  rrangler whoami                   identity + scopes
+  rrangler doctor                   check token, connectivity, allowed endpoints
+
+${style.bold("workers")}
+  rrangler init [name]              scaffold rrangler.json + main.js
+  rrangler deploy [--name s]        push local files to a worker (reads wrangler.toml too)
+  rrangler worker list
+  rrangler worker get <slug>
+  rrangler tail <slug>              stream runtime logs
+  rrangler worker env set <slug> K=V ... [--secret]
+  rrangler worker env delete <slug> K ...
+  rrangler worker builds <slug>
+  rrangler worker build <slug> [--branch b]        trigger a git build
+  rrangler worker build-log <slug> <buildId> [--tail N]
+  rrangler worker cron <slug> [--dlq] [--limit N]
+  rrangler worker cron replay <slug> <runId>
+  rrangler secret put <KEY> --worker <slug> [--value v]
+  rrangler secret list --worker <slug>
+  rrangler secret delete <KEY> --worker <slug>
+  rrangler secret bulk <file.json> --worker <slug>
+
+${style.bold("dev")}
+  rrangler dev [--port 8787]        run the worker locally on workerd (prod runtime)
+  rrangler types [--out f]          generate a bindings Env d.ts
+
+${style.bold("d1")}
+  rrangler d1 list | create <name> | info <db>
+  rrangler d1 execute <db> (--command '<sql>' | --file <f.sql>)
+  rrangler d1 export <db> [--output f] [--no-data]
+  rrangler d1 migrations create <name> | list <db> | apply <db>   [--dir migrations]
+
+${style.bold("kv")}
+  rrangler kv namespace list|create <title>
+  rrangler kv key put <ns> <key> <value> [--ttl s]
+  rrangler kv key get|delete <ns> <key>
+  rrangler kv key list <ns> [--prefix p]
+  rrangler kv bulk put|delete <ns> <file.json>
+
+${style.bold("r2")}
+  rrangler r2 bucket list|create <name> [--public]
+  rrangler r2 object put <bucket> <key> <file>
+  rrangler r2 object get <bucket> <key> [--output f]
+  rrangler r2 object delete <bucket> <key>
+
+${style.bold("pages")}
+  rrangler pages list
+  rrangler pages get <slug>
+  rrangler pages env set <slug> K=V ... [--secret]
+  rrangler pages env delete <slug> K ...
+  rrangler pages builds <slug>
+  rrangler pages build <slug> [--branch b]
+  rrangler pages build-log <slug> <buildId>
+  rrangler pages tail <slug>
+
+${style.bold("power")}
+  rrangler api <METHOD> <path> [--data '<json>']   raw API call
+
+${style.bold("global flags")}: --json (machine output)  --api <url>  --token <t>
+env: RRANGLER_TOKEN, RRANGLER_API`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+    process.stdout.write(HELP + "\n");
+    return;
+  }
+  if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+    process.stdout.write("rrangler 0.1.0\n");
+    return;
+  }
+
+  const { pos: rawPos, flags } = parseArgs(argv);
+  const tokens = normalize(rawPos);
+
+  for (let len = 3; len >= 1; len--) {
+    const key = tokens.slice(0, len).join(" ");
+    if (ROUTES[key]) {
+      const handler = ROUTES[key];
+      const pos = tokens.slice(len);
+      // let --token / --api flags override the stored config for this call
+      if (flags.token) process.env.RRANGLER_TOKEN = String(flags.token);
+      if (flags.api) process.env.RRANGLER_API = String(flags.api);
+      await handler({ pos, flags });
+      return;
+    }
+  }
+  fail(`unknown command: ${style.bold(tokens.join(" "))}`);
+  process.stderr.write(`run ${style.cyan("rrangler help")} for usage\n`);
+  process.exitCode = 1;
+}
+
+main().catch((e) => {
+  if (e instanceof ApiError) {
+    fail(e.message);
+    if (e.status === 401 || e.status === 403) {
+      process.stderr.write(style.dim("  → check your token + its scopes (rrangler whoami)\n"));
+    }
+  } else {
+    fail(String(e?.message || e));
+  }
+  process.exitCode = 1;
+});

package/commands/index.mjs

@@ -0,0 +1,631 @@
+// rrangler command implementations. Each command is an async fn taking
+// ({ pos, flags }) — positionals array + parsed flags object. Grouped by
+// resource, mirroring wrangler's command tree.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { getConfig, loadStore, saveStore, requireToken } from "../lib/config.mjs";
+import { api, resolveWorker, resolveD1, resolveKv, resolvePages } from "../lib/api.mjs";
+import { loadProjectConfig } from "../lib/project-config.mjs";
+import { style, ok, info, warn, fail, printJson, table, withSpinner } from "../lib/ui.mjs";
+
+const asJson = (flags) => flags.json === true;
+
+// ── auth / meta ────────────────────────────────────────────────────
+
+export async function login({ flags }) {
+  const token = flags.token || process.env.RRANGLER_TOKEN;
+  if (!token) throw new Error("provide a token: rrangler login --token <token>");
+  const store = loadStore();
+  store.token = token;
+  if (flags.api) store.api = String(flags.api).replace(/\/$/, "");
+  saveStore(store);
+  // Verify it works.
+  const me = await api("GET", "/api/edge/v1", { token });
+  ok(`logged in as ${style.bold(me.me?.username ?? "?")} (scopes: ${me.scopes?.join(", ") ?? "*"})`);
+  info(`saved to ${getConfig().configPath}`);
+}
+
+export async function logout() {
+  const store = loadStore();
+  delete store.token;
+  saveStore(store);
+  ok("logged out (token removed)");
+}
+
+export async function whoami({ flags }) {
+  const me = await api("GET", "/api/edge/v1");
+  if (asJson(flags)) return printJson(me);
+  info(`${style.bold(me.me?.name ?? me.me?.username ?? "?")}  @${me.me?.username}  <${me.me?.email}>`);
+  info(`role:   ${me.me?.role}${me.isAdmin ? style.dim(" (admin)") : ""}`);
+  info(`auth:   ${me.authMode}${me.tokenId ? ` · token ${me.tokenId}` : ""}`);
+  info(`scopes: ${me.scopes ? me.scopes.join(", ") : style.green("* (full)")}`);
+  info(`api:    ${getConfig().api}`);
+}
+
+export async function doctor({ flags }) {
+  const cfg = getConfig();
+  info(`api:   ${cfg.api}`);
+  info(`token: ${cfg.token ? style.green("present") : style.red("missing")}`);
+  if (!cfg.token) return fail("no token — run `rrangler login --token <token>`");
+  try {
+    const me = await withSpinner("probing api…", () => api("GET", "/api/edge/v1"));
+    ok(`reachable — ${me.me?.username}, scopes: ${me.scopes?.join(", ") ?? "*"}`);
+    const cando = Object.entries(me.endpoints || {})
+      .filter(([, v]) => (v.scopes || []).every((s) => !me.scopes || me.scopes.includes("*") || me.scopes.includes(s)))
+      .length;
+    info(`you can call ${cando}/${Object.keys(me.endpoints || {}).length} endpoints with this token`);
+  } catch (e) {
+    fail(String(e.message || e));
+  }
+}
+
+/** Raw API passthrough: rrangler api GET /api/edge/v1/workers */
+export async function apiPassthrough({ pos, flags }) {
+  const [method = "GET", path] = pos;
+  if (!path) throw new Error("usage: rrangler api <METHOD> <path> [--data '<json>']");
+  const json = flags.data ? JSON.parse(flags.data) : undefined;
+  const out = await api(method.toUpperCase(), path, { json });
+  printJson(out);
+}
+
+// ── workers ────────────────────────────────────────────────────────
+
+export async function workerList({ flags }) {
+  const list = await api("GET", "workers");
+  const workers = list.workers || list || [];
+  if (asJson(flags)) return printJson(workers);
+  table(["SLUG", "TITLE", "VERSION", "CREATED"], workers.map((w) => [w.slug, w.title ?? "", w.version ?? "", (w.createdAt ?? "").slice(0, 10)]));
+}
+
+export async function workerGet({ pos, flags }) {
+  const w = await resolveWorker(pos[0]);
+  const detail = await api("GET", `workers/${w.id}`);
+  printJson(detail);
+}
+
+/**
+ * deploy — push local files to a worker. Config (rrangler.json /
+ * wrangler.toml) supplies `name` (worker slug) and `main` (entry).
+ * `files` (rrangler.json array) lists extra modules; otherwise just
+ * the entry is sent.
+ */
+export async function deploy({ flags }) {
+  requireToken();
+  const cfg = loadProjectConfig();
+  if (!cfg) throw new Error("no rrangler.json / rrangler.toml / wrangler.toml in this directory");
+  const slug = flags.name || cfg.name;
+  const main = flags.main || cfg.main || "main.js";
+  if (!slug) throw new Error("missing worker `name` in config (or pass --name)");
+  if (!existsSync(main)) throw new Error(`entry file not found: ${main}`);
+
+  const paths = Array.isArray(cfg.files) && cfg.files.length ? cfg.files : [main];
+  const files = paths.map((p) => ({ path: basename(p), content: readFileSync(p, "utf8") }));
+  const entryFile = basename(main);
+
+  const worker = await resolveWorker(slug);
+  const res = await withSpinner(`deploying ${style.bold(slug)} (${files.length} file${files.length > 1 ? "s" : ""})…`, () =>
+    api("PUT", `workers/${worker.id}/files`, { json: { files, entryFile } }),
+  );
+  ok(`deployed ${style.bold(slug)} → version ${res.version ?? "?"}`);
+  if (worker.hostname || res.hostname) info(`  https://${res.hostname || worker.hostname}`);
+}
+
+export async function tail({ pos, flags }) {
+  const w = await resolveWorker(pos[0]);
+  await streamLogs(`workers/${w.id}/logs`, w.slug, flags);
+}
+
+/** Shared log tail loop for workers + pages (same log shape). */
+async function streamLogs(logPath, name, flags) {
+  info(style.dim(`tailing ${name} — Ctrl-C to stop`));
+  let since = Date.now();
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      const out = await api("GET", logPath, { query: { since } });
+      const logs = out.logs || out.lines || [];
+      for (const l of logs) {
+        const t = new Date(l.time || l.calledAt || Date.now()).toISOString().slice(11, 23);
+        const status = l.statusCode ? style.dim(`${l.statusCode}`) : "";
+        info(`${style.gray(t)}  ${l.method || ""} ${l.path || l.message || ""} ${status}`);
+      }
+      if (out.now) since = out.now;
+      else if (logs.length) since = Date.now();
+    } catch (e) {
+      warn(String(e.message || e));
+    }
+    await sleep(Number(flags.interval) || 2000);
+  }
+}
+
+// ── worker builds / env / cron ─────────────────────────────────────
+
+export async function workerBuilds({ pos, flags }) {
+  const w = await resolveWorker(pos[0]);
+  const out = await api("GET", `workers/${w.id}/builds`);
+  const builds = out.builds || out || [];
+  if (asJson(flags)) return printJson(builds);
+  table(["ID", "STATUS", "BRANCH", "AT"], builds.map((b) => [b.id, b.status, b.branch ?? "", (b.createdAt ?? b.startedAt ?? "").slice(0, 19)]));
+}
+
+export async function workerBuild({ pos, flags }) {
+  const w = await resolveWorker(pos[0]);
+  const out = await api("POST", `workers/${w.id}/builds`, { json: flags.branch ? { branch: flags.branch } : {} });
+  ok(`build triggered for ${w.slug}${out.build?.id ? ` (id ${out.build.id})` : ""}`);
+}
+
+export async function workerBuildLog({ pos, flags }) {
+  const w = await resolveWorker(pos[0]);
+  const buildId = pos[1];
+  if (!buildId) throw new Error("usage: rrangler worker build-log <slug> <buildId> [--tail N]");
+  const out = await api("GET", `workers/${w.id}/builds/${buildId}`, { query: { logTail: flags.tail } });
+  if (asJson(flags)) return printJson(out);
+  info(`status: ${out.status}`);
+  process.stdout.write((out.log || out.logs || "") + "\n");
+}
+
+function parseKvPairs(pairs) {
+  const set = {};
+  for (const p of pairs) {
+    const i = p.indexOf("=");
+    if (i < 0) throw new Error(`bad KEY=VALUE: ${p}`);
+    set[p.slice(0, i)] = p.slice(i + 1);
+  }
+  return set;
+}
+
+export async function workerEnvSet({ pos, flags }) {
+  const w = await resolveWorker(pos[0]);
+  const set = parseKvPairs(pos.slice(1));
+  if (!Object.keys(set).length) throw new Error("usage: rrangler worker env set <slug> KEY=VAL ...");
+  await api("POST", `workers/${w.id}/env`, { json: { set, secretKeys: flags.secret ? Object.keys(set) : [] } });
+  ok(`set ${Object.keys(set).join(", ")} on ${w.slug}`);
+}
+
+export async function workerEnvDelete({ pos }) {
+  const w = await resolveWorker(pos[0]);
+  const del = pos.slice(1);
+  await api("POST", `workers/${w.id}/env`, { json: { delete: del } });
+  ok(`deleted ${del.join(", ")} from ${w.slug}`);
+}
+
+export async function workerCron({ pos, flags }) {
+  const w = await resolveWorker(pos[0]);
+  const out = await api("GET", `workers/${w.id}/cron-runs`, { query: { dlq: flags.dlq ? 1 : undefined, limit: flags.limit } });
+  const runs = out.runs || out || [];
+  if (asJson(flags)) return printJson(runs);
+  table(["ID", "STATUS", "EXPR", "AT"], runs.map((r) => [r.id, r.status, r.expression ?? r.cron ?? "", (r.firedAt ?? r.createdAt ?? "").slice(0, 19)]));
+}
+
+export async function workerCronReplay({ pos }) {
+  const w = await resolveWorker(pos[0]);
+  const runId = pos[1];
+  if (!runId) throw new Error("usage: rrangler worker cron replay <slug> <runId>");
+  await api("POST", `workers/${w.id}/cron-runs/${runId}/replay`);
+  ok(`replayed cron run ${runId}`);
+}
+
+// ── pages ──────────────────────────────────────────────────────────
+
+export async function pagesGet({ pos }) {
+  const p = await resolvePages(pos[0]);
+  printJson(await api("GET", `pages/${p.id}`));
+}
+
+export async function pagesEnvSet({ pos, flags }) {
+  const p = await resolvePages(pos[0]);
+  const set = parseKvPairs(pos.slice(1));
+  await api("POST", `pages/${p.id}/env`, { json: { set, secretKeys: flags.secret ? Object.keys(set) : [] } });
+  ok(`set ${Object.keys(set).join(", ")} on ${p.slug}`);
+}
+
+export async function pagesEnvDelete({ pos }) {
+  const p = await resolvePages(pos[0]);
+  await api("POST", `pages/${p.id}/env`, { json: { delete: pos.slice(1) } });
+  ok(`deleted ${pos.slice(1).join(", ")} from ${p.slug}`);
+}
+
+export async function pagesBuilds({ pos, flags }) {
+  const p = await resolvePages(pos[0]);
+  const out = await api("GET", `pages/${p.id}/builds`);
+  const builds = out.builds || out || [];
+  if (asJson(flags)) return printJson(builds);
+  table(["ID", "STATUS", "BRANCH", "AT"], builds.map((b) => [b.id, b.status, b.branch ?? "", (b.createdAt ?? "").slice(0, 19)]));
+}
+
+export async function pagesBuild({ pos, flags }) {
+  const p = await resolvePages(pos[0]);
+  await api("POST", `pages/${p.id}/builds`, { json: flags.branch ? { branch: flags.branch } : {} });
+  ok(`build triggered for ${p.slug}`);
+}
+
+export async function pagesBuildLog({ pos, flags }) {
+  const p = await resolvePages(pos[0]);
+  const out = await api("GET", `pages/${p.id}/builds/${pos[1]}`, { query: { logTail: flags.tail } });
+  if (asJson(flags)) return printJson(out);
+  info(`status: ${out.status}`);
+  process.stdout.write((out.log || out.logs || "") + "\n");
+}
+
+export async function pagesTail({ pos, flags }) {
+  const p = await resolvePages(pos[0]);
+  await streamLogs(`pages/${p.id}/logs`, p.slug, flags);
+}
+
+// ── secrets (worker env) ───────────────────────────────────────────
+
+export async function secretPut({ pos, flags }) {
+  const key = pos[0];
+  if (!key) throw new Error("usage: rrangler secret put <KEY> --worker <slug> [--value <v>]");
+  const w = await resolveWorker(flags.worker || flags.name);
+  const value = flags.value != null ? String(flags.value) : (await readStdin()).trim();
+  await api("POST", `workers/${w.id}/env`, { json: { set: { [key]: value }, secretKeys: [key] } });
+  ok(`secret ${style.bold(key)} set on ${w.slug}`);
+}
+
+export async function secretList({ flags }) {
+  const w = await resolveWorker(flags.worker || flags.name);
+  const detail = await api("GET", `workers/${w.id}`);
+  const keys = detail.envSecretKeys || detail.secretKeys || [];
+  if (asJson(flags)) return printJson(keys);
+  keys.length ? keys.forEach((k) => info(k)) : info(style.dim("(no secrets)"));
+}
+
+export async function secretDelete({ pos, flags }) {
+  const key = pos[0];
+  const w = await resolveWorker(flags.worker || flags.name);
+  await api("POST", `workers/${w.id}/env`, { json: { delete: [key] } });
+  ok(`secret ${key} deleted from ${w.slug}`);
+}
+
+// ── D1 ─────────────────────────────────────────────────────────────
+
+export async function d1List({ flags }) {
+  const list = await api("GET", "d1");
+  const dbs = list.databases || list || [];
+  if (asJson(flags)) return printJson(dbs);
+  table(["NAME", "ID"], dbs.map((d) => [d.name, d.id]));
+}
+
+export async function d1Create({ pos }) {
+  const name = pos[0];
+  if (!name) throw new Error("usage: rrangler d1 create <name>");
+  const out = await api("POST", "d1", { json: { name } });
+  ok(`D1 database ${style.bold(name)} created (id ${out.id || out.database?.id})`);
+}
+
+export async function d1Execute({ pos, flags }) {
+  const db = await resolveD1(pos[0]);
+  let sql = flags.command;
+  if (flags.file) sql = readFileSync(flags.file, "utf8");
+  if (!sql) throw new Error("usage: rrangler d1 execute <db> (--command '<sql>' | --file <f.sql>)");
+  // Multi-statement / DDL → /exec; single SELECT → /query.
+  const multi = /;\s*\S/.test(sql.trim().replace(/;\s*$/, ""));
+  const endpoint = multi || !/^\s*select/i.test(sql) ? "exec" : "query";
+  const out = await api("POST", `d1/${db.id}/${endpoint}`, { json: { sql } });
+  printJson(out);
+}
+
+// ── KV ─────────────────────────────────────────────────────────────
+
+export async function kvNamespaceList({ flags }) {
+  const list = await api("GET", "kv");
+  const ns = list.namespaces || list || [];
+  if (asJson(flags)) return printJson(ns);
+  table(["TITLE", "ID"], ns.map((n) => [n.title || n.name, n.id]));
+}
+
+export async function kvNamespaceCreate({ pos }) {
+  const title = pos[0];
+  if (!title) throw new Error("usage: rrangler kv namespace create <title>");
+  const out = await api("POST", "kv", { json: { title } });
+  ok(`KV namespace ${style.bold(title)} created (id ${out.id || out.namespace?.id})`);
+}
+
+export async function kvKeyPut({ pos, flags }) {
+  const [nsName, key] = pos;
+  const value = pos[2] != null ? pos[2] : flags.value;
+  if (!nsName || !key || value == null) throw new Error("usage: rrangler kv key put <ns> <key> <value>");
+  const ns = await resolveKv(nsName);
+  await api("PUT", `kv/${ns.id}/${encodeURIComponent(key)}`, {
+    headers: { "content-type": "text/plain" },
+    body: String(value),
+    query: flags.ttl ? { expiration_ttl: flags.ttl } : undefined,
+  });
+  ok(`kv ${nsName}/${key} set`);
+}
+
+export async function kvKeyGet({ pos }) {
+  const [nsName, key] = pos;
+  const ns = await resolveKv(nsName);
+  const res = await api("GET", `kv/${ns.id}/${encodeURIComponent(key)}`, { raw: true });
+  if (!res.ok) throw new Error(`kv get ${res.status}`);
+  process.stdout.write((await res.text()) + "\n");
+}
+
+export async function kvKeyList({ pos, flags }) {
+  const ns = await resolveKv(pos[0]);
+  const out = await api("GET", `kv/${ns.id}`, { query: { prefix: flags.prefix } });
+  printJson(out.keys || out.items || out);
+}
+
+export async function kvKeyDelete({ pos }) {
+  const [nsName, key] = pos;
+  const ns = await resolveKv(nsName);
+  await api("DELETE", `kv/${ns.id}/${encodeURIComponent(key)}`);
+  ok(`kv ${nsName}/${key} deleted`);
+}
+
+// ── R2 ─────────────────────────────────────────────────────────────
+
+export async function r2BucketList({ flags }) {
+  const list = await api("GET", "r2");
+  const buckets = list.buckets || list || [];
+  if (asJson(flags)) return printJson(buckets);
+  table(["NAME", "ID"], buckets.map((b) => [b.name, b.id]));
+}
+
+export async function r2BucketCreate({ pos, flags }) {
+  const name = pos[0];
+  if (!name) throw new Error("usage: rrangler r2 bucket create <name> [--public]");
+  const out = await api("POST", "r2", { json: { name, publicAccess: !!flags.public } });
+  ok(`R2 bucket ${style.bold(name)} created (id ${out.id || out.bucket?.id})`);
+}
+
+export async function r2ObjectPut({ pos }) {
+  const [bucket, key, file] = pos;
+  if (!bucket || !key || !file) throw new Error("usage: rrangler r2 object put <bucket> <key> <file>");
+  const body = readFileSync(file);
+  await api("PUT", `r2/${encodeURIComponent(bucket)}/${key}`, { body });
+  ok(`r2 ${bucket}/${key} uploaded (${body.length} bytes)`);
+}
+
+export async function r2ObjectGet({ pos, flags }) {
+  const [bucket, key] = pos;
+  const res = await api("GET", `r2/${encodeURIComponent(bucket)}/${key}`, { raw: true });
+  if (!res.ok) throw new Error(`r2 get ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (flags.output) {
+    writeFileSync(flags.output, buf);
+    ok(`saved ${buf.length} bytes → ${flags.output}`);
+  } else {
+    process.stdout.write(buf);
+  }
+}
+
+export async function r2ObjectDelete({ pos }) {
+  const [bucket, key] = pos;
+  await api("DELETE", `r2/${encodeURIComponent(bucket)}/${key}`);
+  ok(`r2 ${bucket}/${key} deleted`);
+}
+
+// ── pages ──────────────────────────────────────────────────────────
+
+export async function pagesList({ flags }) {
+  const list = await api("GET", "pages");
+  const projects = list.projects || list || [];
+  if (asJson(flags)) return printJson(projects);
+  table(["SLUG", "NAME"], projects.map((p) => [p.slug, p.name ?? ""]));
+}
+
+// ── init (scaffold) ────────────────────────────────────────────────
+
+export async function init({ pos }) {
+  const name = pos[0] || basename(process.cwd());
+  if (!existsSync("rrangler.json")) {
+    writeFileSync("rrangler.json", JSON.stringify({ name, main: "main.js", compatibilityDate: new Date().toISOString().slice(0, 10) }, null, 2) + "\n");
+    ok("wrote rrangler.json");
+  }
+  if (!existsSync("main.js")) {
+    writeFileSync("main.js", `export default {\n  async fetch(request, env, ctx) {\n    return new Response("hello from ${name}");\n  },\n};\n`);
+    ok("wrote main.js");
+  }
+  info(`next: create the worker in bigrandall.io → /me/edge, then \`rrangler deploy\``);
+}
+
+// ── d1: export / info / migrations ─────────────────────────────────
+
+/** Run a SQL statement on a D1 db, returning the rows array. */
+async function d1q(id, sql, params) {
+  const out = await api("POST", `d1/${id}/query`, { json: { sql, ...(params ? { params } : {}) } });
+  return out.results || out.rows || out.result?.rows || out.result || [];
+}
+
+function sqlLiteral(v) {
+  if (v === null || v === undefined) return "NULL";
+  if (typeof v === "number") return Number.isFinite(v) ? String(v) : "NULL";
+  if (typeof v === "boolean") return v ? "1" : "0";
+  return "'" + String(v).replace(/'/g, "''") + "'";
+}
+
+export async function d1Export({ pos, flags }) {
+  const db = await resolveD1(pos[0]);
+  const tables = await d1q(db.id, "SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name");
+  let dump = `-- rrangler d1 export of ${db.name}\nPRAGMA foreign_keys=OFF;\nBEGIN TRANSACTION;\n`;
+  for (const t of tables) {
+    const name = t.name;
+    if (t.sql) dump += `${t.sql};\n`;
+    const rows = flags["no-data"] ? [] : await d1q(db.id, `SELECT * FROM "${name}"`);
+    for (const row of rows) {
+      const cols = Object.keys(row);
+      dump += `INSERT INTO "${name}" (${cols.map((c) => `"${c}"`).join(", ")}) VALUES (${cols.map((c) => sqlLiteral(row[c])).join(", ")});\n`;
+    }
+  }
+  dump += "COMMIT;\n";
+  if (flags.output) {
+    writeFileSync(flags.output, dump);
+    ok(`exported ${db.name} → ${flags.output} (${tables.length} tables)`);
+  } else {
+    process.stdout.write(dump);
+  }
+}
+
+export async function d1Info({ pos, flags }) {
+  const db = await resolveD1(pos[0]);
+  const tables = await d1q(db.id, "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'");
+  const info2 = { name: db.name, id: db.id, tables: tables.map((t) => t.name) };
+  if (asJson(flags)) return printJson(info2);
+  info(`${style.bold(db.name)}  (${db.id})`);
+  info(`tables: ${info2.tables.join(", ") || "(none)"}`);
+}
+
+function migrationsDir(flags) {
+  return flags.dir || "migrations";
+}
+function readSqlDir(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".sql")).sort();
+}
+
+export async function d1MigrationsCreate({ pos, flags }) {
+  const name = pos[1] || pos[0];
+  const dir = migrationsDir(flags);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+  const file = join(dir, `${stamp}_${(name || "migration").replace(/\W+/g, "_")}.sql`);
+  writeFileSync(file, "-- migration\n");
+  ok(`created ${file}`);
+}
+
+export async function d1MigrationsList({ pos, flags }) {
+  const db = await resolveD1(pos[0]);
+  const dir = migrationsDir(flags);
+  const files = readSqlDir(dir);
+  let applied = new Set();
+  try {
+    const rows = await d1q(db.id, "SELECT name FROM d1_migrations");
+    applied = new Set(rows.map((r) => r.name));
+  } catch {
+    /* table not created yet */
+  }
+  if (asJson(flags)) return printJson(files.map((f) => ({ name: f, applied: applied.has(f) })));
+  files.forEach((f) => info(`${applied.has(f) ? style.green("✔") : style.dim("·")} ${f}`));
+  if (!files.length) info(style.dim(`(no .sql files in ${dir})`));
+}
+
+export async function d1MigrationsApply({ pos, flags }) {
+  const db = await resolveD1(pos[0]);
+  const dir = migrationsDir(flags);
+  const files = readSqlDir(dir);
+  await api("POST", `d1/${db.id}/exec`, { json: { sql: "CREATE TABLE IF NOT EXISTS d1_migrations (id INTEGER PRIMARY KEY, name TEXT UNIQUE, applied_at TEXT)" } });
+  const appliedRows = await d1q(db.id, "SELECT name FROM d1_migrations");
+  const applied = new Set(appliedRows.map((r) => r.name));
+  let n = 0;
+  for (const f of files) {
+    if (applied.has(f)) continue;
+    const sql = readFileSync(join(dir, f), "utf8");
+    await withSpinner(`applying ${f}…`, () => api("POST", `d1/${db.id}/exec`, { json: { sql } }));
+    await api("POST", `d1/${db.id}/exec`, { json: { sql: "INSERT INTO d1_migrations (name, applied_at) VALUES (?, ?)", params: [f, new Date().toISOString()] } });
+    ok(`applied ${f}`);
+    n++;
+  }
+  info(n ? `${n} migration(s) applied` : "already up to date");
+}
+
+// ── kv / secret bulk ───────────────────────────────────────────────
+
+export async function kvBulkPut({ pos }) {
+  const ns = await resolveKv(pos[0]);
+  const entries = JSON.parse(readFileSync(pos[1], "utf8"));
+  for (const e of entries) {
+    await api("PUT", `kv/${ns.id}/${encodeURIComponent(e.key)}`, {
+      headers: { "content-type": "text/plain" },
+      body: String(e.value),
+      query: e.expiration_ttl ? { expiration_ttl: e.expiration_ttl } : undefined,
+    });
+  }
+  ok(`put ${entries.length} keys into ${pos[0]}`);
+}
+
+export async function kvBulkDelete({ pos }) {
+  const ns = await resolveKv(pos[0]);
+  const keys = JSON.parse(readFileSync(pos[1], "utf8"));
+  for (const k of keys) await api("DELETE", `kv/${ns.id}/${encodeURIComponent(k)}`);
+  ok(`deleted ${keys.length} keys from ${pos[0]}`);
+}
+
+export async function secretBulk({ pos, flags }) {
+  const w = await resolveWorker(flags.worker || flags.name);
+  const set = JSON.parse(readFileSync(pos[0], "utf8"));
+  await api("POST", `workers/${w.id}/env`, { json: { set, secretKeys: Object.keys(set) } });
+  ok(`set ${Object.keys(set).length} secrets on ${w.slug}`);
+}
+
+// ── types (generate bindings d.ts) ─────────────────────────────────
+
+export async function types({ pos, flags }) {
+  const cfg = loadProjectConfig();
+  const slug = flags.name || cfg?.name || pos[0];
+  if (!slug) throw new Error("no worker name (config or --name)");
+  const w = await resolveWorker(slug);
+  const detail = await api("GET", `workers/${w.id}`);
+  const lines = ["interface Env {"];
+  for (const b of detail.kvBindings || []) lines.push(`  ${b.bindingName}: KVNamespace;`);
+  for (const b of detail.d1Bindings || []) lines.push(`  ${b.bindingName}: D1Database;`);
+  for (const b of detail.r2Bindings || []) lines.push(`  ${b.bindingName}: R2Bucket;`);
+  for (const b of detail.doBindings || []) lines.push(`  ${b.bindingName}: DurableObjectNamespace;`);
+  for (const k of Object.keys(detail.envJson || {})) lines.push(`  ${k}: string;`);
+  for (const k of detail.envSecretKeys || []) lines.push(`  ${k}: string;`);
+  lines.push("}");
+  const out = lines.join("\n") + "\n";
+  const dest = flags.out || "worker-configuration.d.ts";
+  writeFileSync(dest, out);
+  ok(`wrote ${dest}`);
+}
+
+// ── dev (local workerd) ────────────────────────────────────────────
+
+export async function dev({ flags }) {
+  const cp = await import("node:child_process");
+  const workerd = flags.workerd || whichWorkerd(cp);
+  if (!workerd) {
+    fail("workerd not found on PATH.");
+    info("install it (`npm i -g workerd`) or pass --workerd <path>. `rrangler dev` runs your worker on the same runtime as production.");
+    return;
+  }
+  const cfg = loadProjectConfig() || {};
+  const main = flags.main || cfg.main || "main.js";
+  if (!existsSync(main)) throw new Error(`entry not found: ${main}`);
+  const port = Number(flags.port) || 8787;
+  const paths = Array.isArray(cfg.files) && cfg.files.length ? cfg.files : [main];
+  const modules = paths.map((p) => `    (name = "${basename(p)}", esModule = embed "${p}")`).join(",\n");
+  const capnp = `using Workerd = import "/workerd/workerd.capnp";
+const config :Workerd.Config = (
+  services = [ (name = "main", worker = .mainWorker) ],
+  sockets = [ (name = "http", address = "*:${port}", http = (), service = "main") ],
+);
+const mainWorker :Workerd.Worker = (
+  modules = [
+${modules}
+  ],
+  compatibilityDate = "${cfg.compatibilityDate || "2024-11-01"}",
+);
+`;
+  const tmp = join(process.cwd(), ".rrangler-dev.capnp");
+  writeFileSync(tmp, capnp);
+  ok(`workerd serving ${style.bold(main)} on http://127.0.0.1:${port}  (Ctrl-C to stop)`);
+  const child = cp.spawn(workerd, ["serve", tmp], { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+function whichWorkerd(cp) {
+  try {
+    return cp.execSync("command -v workerd", { encoding: "utf8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// ── helpers ────────────────────────────────────────────────────────
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => resolve(data));
+  });
+}

package/lib/api.mjs

@@ -0,0 +1,88 @@
+// API client for the RandallFlare edge REST API (/api/edge/v1/*).
+// Bearer-token auth; friendly errors. Node's global fetch (>=18).
+
+import { getConfig } from "./config.mjs";
+
+export class ApiError extends Error {
+  constructor(status, body, path) {
+    super(
+      `API ${status} on ${path}` +
+        (body?.error ? `: ${body.error}` : body ? `: ${JSON.stringify(body).slice(0, 200)}` : ""),
+    );
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * Call the edge API.
+ *   method  - GET/POST/PUT/DELETE
+ *   path    - "/api/edge/v1/..." (leading slash) OR "workers" shorthand
+ *   opts    - { json, body, query, headers, raw, token, api }
+ *
+ * Returns parsed JSON by default; { raw:true } returns the Response.
+ */
+export async function api(method, path, opts = {}) {
+  const cfg = getConfig();
+  const token = opts.token || cfg.token;
+  const base = (opts.api || cfg.api).replace(/\/$/, "");
+  let p = path.startsWith("/") ? path : `/api/edge/v1/${path}`;
+  if (opts.query) {
+    const qs = new URLSearchParams(
+      Object.entries(opts.query).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]),
+    ).toString();
+    if (qs) p += (p.includes("?") ? "&" : "?") + qs;
+  }
+
+  const headers = { accept: "application/json", ...(opts.headers || {}) };
+  if (token) headers.authorization = `Bearer ${token}`;
+  let body = opts.body;
+  if (opts.json !== undefined) {
+    headers["content-type"] = "application/json";
+    body = JSON.stringify(opts.json);
+  }
+
+  const res = await fetch(base + p, { method, headers, body });
+  if (opts.raw) return res;
+
+  const ct = res.headers.get("content-type") || "";
+  const parsed = ct.includes("json") ? await res.json().catch(() => null) : await res.text();
+  if (!res.ok) throw new ApiError(res.status, parsed, p);
+  return parsed;
+}
+
+/** Resolve a worker slug → id (list + match). Accepts an id directly too. */
+export async function resolveWorker(slugOrId) {
+  const list = await api("GET", "workers");
+  const workers = list.workers || list.items || list || [];
+  const hit = workers.find((w) => w.slug === slugOrId || w.id === slugOrId);
+  if (!hit) throw new Error(`worker "${slugOrId}" not found (yours: ${workers.map((w) => w.slug).join(", ") || "none"})`);
+  return hit;
+}
+
+/** Resolve a D1 database name → id. */
+export async function resolveD1(nameOrId) {
+  const list = await api("GET", "d1");
+  const dbs = list.databases || list.items || list || [];
+  const hit = dbs.find((d) => d.name === nameOrId || d.id === nameOrId);
+  if (!hit) throw new Error(`D1 database "${nameOrId}" not found`);
+  return hit;
+}
+
+/** Resolve a KV namespace name/title → id. */
+export async function resolveKv(nameOrId) {
+  const list = await api("GET", "kv");
+  const ns = list.namespaces || list.items || list || [];
+  const hit = ns.find((n) => n.title === nameOrId || n.name === nameOrId || n.id === nameOrId);
+  if (!hit) throw new Error(`KV namespace "${nameOrId}" not found`);
+  return hit;
+}
+
+/** Resolve a Pages project slug/name → id. */
+export async function resolvePages(slugOrId) {
+  const list = await api("GET", "pages");
+  const projects = list.projects || list.items || list || [];
+  const hit = projects.find((p) => p.slug === slugOrId || p.name === slugOrId || p.id === slugOrId);
+  if (!hit) throw new Error(`Pages project "${slugOrId}" not found`);
+  return hit;
+}

package/lib/config.mjs

@@ -0,0 +1,55 @@
+// Config + credentials resolution.
+//
+// Precedence (highest first):
+//   1. env RRANGLER_TOKEN / RRANGLER_API
+//   2. ~/.rrangler.json  (written by `rrangler login`)
+//   3. defaults
+//
+// The token is a RandallFlare EdgeAccessToken (created in the
+// bigrandall.io backend → /me/edge → API tokens). Scopes on the token
+// gate what commands work.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, chmodSync, existsSync } from "node:fs";
+
+const CONFIG_PATH = join(homedir(), ".rrangler.json");
+const DEFAULT_API = "https://bigrandall.io";
+
+export function loadStore() {
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    }
+  } catch {
+    /* corrupt config → treat as empty */
+  }
+  return {};
+}
+
+export function saveStore(store) {
+  writeFileSync(CONFIG_PATH, JSON.stringify(store, null, 2) + "\n");
+  try {
+    chmodSync(CONFIG_PATH, 0o600); // token is a secret
+  } catch {
+    /* best effort */
+  }
+}
+
+export function getConfig() {
+  const store = loadStore();
+  const api = (process.env.RRANGLER_API || store.api || DEFAULT_API).replace(/\/$/, "");
+  const token = process.env.RRANGLER_TOKEN || store.token || null;
+  return { api, token, configPath: CONFIG_PATH };
+}
+
+export function requireToken() {
+  const cfg = getConfig();
+  if (!cfg.token) {
+    throw new Error(
+      "not logged in — run `rrangler login --token <token>` or set RRANGLER_TOKEN.\n" +
+        "Create a token in bigrandall.io → /me/edge → API tokens.",
+    );
+  }
+  return cfg;
+}

package/lib/project-config.mjs

@@ -0,0 +1,53 @@
+// Read a project's deploy config from the current directory.
+//
+// Supports (in order): rrangler.json, rrangler.toml, wrangler.toml
+// (wrangler compat — we read the fields we need: name, main,
+// compatibility_date). Full TOML isn't parsed; a small line reader
+// pulls the top-level scalars, which covers the deploy path.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+function readMiniToml(text) {
+  const out = {};
+  let section = "";
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, "").trim();
+    if (!line) continue;
+    if (line.startsWith("[")) {
+      section = line.replace(/[[\]]/g, "");
+      continue;
+    }
+    const m = /^([A-Za-z0-9_]+)\s*=\s*(.+)$/.exec(line);
+    if (!m || section) continue; // only top-level scalars
+    let v = m[2].trim();
+    if (/^".*"$/.test(v) || /^'.*'$/.test(v)) v = v.slice(1, -1);
+    else if (v === "true" || v === "false") v = v === "true";
+    else if (/^-?\d+$/.test(v)) v = Number(v);
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+export function loadProjectConfig(dir = process.cwd()) {
+  const jsonPath = join(dir, "rrangler.json");
+  if (existsSync(jsonPath)) {
+    return { source: "rrangler.json", ...JSON.parse(readFileSync(jsonPath, "utf8")) };
+  }
+  for (const [file, label] of [
+    ["rrangler.toml", "rrangler.toml"],
+    ["wrangler.toml", "wrangler.toml"],
+  ]) {
+    const p = join(dir, file);
+    if (existsSync(p)) {
+      const t = readMiniToml(readFileSync(p, "utf8"));
+      return {
+        source: label,
+        name: t.name,
+        main: t.main,
+        compatibilityDate: t.compatibility_date,
+      };
+    }
+  }
+  return null;
+}

package/lib/ui.mjs

@@ -0,0 +1,62 @@
+// Tiny terminal UI helpers — colors, tables, spinners. Zero deps.
+
+const TTY = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code) => (s) => (TTY ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const style = {
+  bold: c("1"),
+  dim: c("2"),
+  red: c("31"),
+  green: c("32"),
+  yellow: c("33"),
+  blue: c("34"),
+  magenta: c("35"),
+  cyan: c("36"),
+  gray: c("90"),
+};
+
+export function info(msg) {
+  process.stderr.write(msg + "\n");
+}
+export function ok(msg) {
+  process.stderr.write(style.green("✔ ") + msg + "\n");
+}
+export function warn(msg) {
+  process.stderr.write(style.yellow("▲ ") + msg + "\n");
+}
+export function fail(msg) {
+  process.stderr.write(style.red("✘ ") + msg + "\n");
+}
+
+/** Print JSON to stdout (the machine-readable channel). */
+export function printJson(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+
+/** Simple left-aligned column table for stdout. rows: string[][]. */
+export function table(headers, rows) {
+  const all = [headers, ...rows];
+  const widths = headers.map((_, i) =>
+    Math.max(...all.map((r) => String(r[i] ?? "").length)),
+  );
+  const line = (r) =>
+    r.map((cell, i) => String(cell ?? "").padEnd(widths[i])).join("  ");
+  process.stdout.write(style.bold(line(headers)) + "\n");
+  for (const r of rows) process.stdout.write(line(r) + "\n");
+}
+
+/** A minimal indeterminate spinner around an async task. */
+export async function withSpinner(label, fn) {
+  if (!TTY) return fn();
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let i = 0;
+  const t = setInterval(() => {
+    process.stderr.write(`\r${style.cyan(frames[i++ % frames.length])} ${label}`);
+  }, 80);
+  try {
+    return await fn();
+  } finally {
+    clearInterval(t);
+    process.stderr.write("\r\x1b[2K");
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@bigrandall/rrangler",
+  "version": "0.1.0",
+  "description": "wrangler-compatible CLI for RandallFlare — the self-hosted Cloudflare-Workers edge platform in bigrandall.io. Deploy workers, manage D1/KV/R2, tail logs, run locally on workerd.",
+  "type": "module",
+  "bin": {
+    "rrangler": "bin/rrangler.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "commands",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node bin/rrangler.mjs --version",
+    "prepublishOnly": "node bin/rrangler.mjs --version"
+  },
+  "keywords": [
+    "rrangler",
+    "wrangler",
+    "cloudflare",
+    "workers",
+    "workerd",
+    "edge",
+    "serverless",
+    "cli",
+    "randallflare",
+    "bigrandall",
+    "d1",
+    "kv",
+    "r2",
+    "durable-objects"
+  ],
+  "author": "Randall <me@bigrandall.io>",
+  "license": "MIT",
+  "homepage": "https://github.com/RandallAnjie/bigrandall.io/tree/main/rrangler#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RandallAnjie/bigrandall.io.git",
+    "directory": "rrangler"
+  },
+  "bugs": {
+    "url": "https://github.com/RandallAnjie/bigrandall.io/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}