speculos-toolkit 1.0.0

package/src/index.js

@@ -0,0 +1,547 @@
+// speculos-toolkit CLI. Machine-readable JSON on stdout, human progress on stderr.
+//
+// Flow: allocate identity + slugUuid -> deploy backend to Daytona (if any) ->
+// build the frontend locally with the backend URL baked in -> upload the static
+// output to the host. Backends run on Daytona; frontends are hosted on EC2 at
+// user-deployed.speculos.ai/<userId>/<slugUuid>/.
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const { detect } = require("./detect");
+const { packDir, BACKEND_DIRS } = require("./pack");
+const { runBuild } = require("./build");
+const client = require("./client");
+const creds = require("./creds");
+
+const VERSION = require("../package.json").version;
+
+// ---- arg parsing --------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = { env: {}, _: [] };
+  const valueFlags = {
+    "--frontend": "frontend", "--backend": "backend", "--slug": "slug",
+    "--start": "start", "--runtime": "runtime", "--output": "output",
+    "--api": "api", "--timeout": "timeout", "--env-file": "envFile",
+    "--override": "override",
+    "--connector": "connector", "--tool": "tool", "--args": "args", "--args-file": "argsFile",
+    "--token": "pasteToken",
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--env") { const kv = argv[++i] || ""; const j = kv.indexOf("="); if (j > 0) opts.env[kv.slice(0, j)] = kv.slice(j + 1); }
+    else if (valueFlags[a]) opts[valueFlags[a]] = argv[++i];
+    else if (a === "--build") opts.build = true;
+    else if (a === "--static" || a === "--no-build") opts.static = true;
+    else if (a === "--relink" || a === "--force") opts.relink = true;
+    else if (a === "--project") opts.project = true;
+    else if (a === "--no-backend") opts.noBackend = true;
+    else if (a === "--no-frontend") opts.noFrontend = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--help" || a === "-h") opts.help = true;
+    else if (a === "--version" || a === "-v") opts.version = true;
+    else opts._.push(a);
+  }
+  if (opts.envFile) {
+    // Surface a bad --env-file instead of silently shipping the backend with no
+    // env — a missing/unreadable file otherwise fails later as an opaque timeout.
+    try {
+      for (const line of fs.readFileSync(opts.envFile, "utf8").split("\n")) {
+        const t = line.trim(); if (!t || t.startsWith("#")) continue;
+        const j = t.indexOf("="); if (j > 0) opts.env[t.slice(0, j).trim()] = t.slice(j + 1).trim();
+      }
+    } catch (e) { opts.envFileError = `could not read --env-file ${opts.envFile}: ${e.message}`; }
+  }
+  return opts;
+}
+
+function log(opts, msg) { if (!opts.json) process.stderr.write(msg + "\n"); }
+function emit(obj) { process.stdout.write(JSON.stringify(obj) + "\n"); }
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+const HELP = `speculos-toolkit v${VERSION} — deploy + data connectors for coding agents
+
+USAGE
+  npx speculos-toolkit [deploy]        detect, build, and deploy ./ (frontend and/or backend)
+  npx speculos-toolkit detect          show what would be deployed (no upload)
+  npx speculos-toolkit status <jobId>  poll a backend deployment
+  npx speculos-toolkit teardown --slug <slug>
+  npx speculos-toolkit login           link this machine to your Speculos account
+                                       (browser approve) so backend deploys just work
+                                       --token <spec_tok_…>  link with a token you already
+                                         have (no browser); add --relink to move a device
+                                         already linked to a different/personal account
+  npx speculos-toolkit logout          unlink this machine (revoke its token)
+  npx speculos-toolkit install-skill   install the Claude Code /speculos-toolkit skill
+                                       (+ allow the deploy command once, no more prompts)
+  npx speculos-toolkit connectors [list]
+                                      show the data sources linked to your account/org
+                                      (with their tools) — needs login
+  npx speculos-toolkit connectors exec --connector <alias> --tool <TOOL> \\
+                                      [--args '<json>' | --args-file <path>]
+                                      run one connector tool through the broker
+                                      (read-only discovery, live queries)
+
+Frontends are hosted FREE at user-deployed.speculos.ai/<userId>/<slugUuid>.
+Every Speculos account includes one backend app free (an isolated sandbox per app) —
+sign up at https://deploy.speculos.ai and run 'speculos-toolkit login'.
+Without an account a detected backend is skipped (frontend still ships free).
+
+OPTIONS
+  --frontend <dir>   frontend dir (auto-detected: frontend/web/client/… or ./ if index.html)
+  --backend <dir>    backend dir  (auto-detected: backend/api/server/…) — needs --override
+  --slug <slug>      deployment slug (default: <folder>-<hash>)
+  --runtime <r>      backend runtime: node | python | bun (auto-detected)
+  --start <cmd>      backend start command (auto-detected; must bind 0.0.0.0:$PORT)
+  --build            force the frontend through its build step (vs serve as static)
+  --static           serve the frontend dir as-is even if it has a build script
+  --no-backend       frontend-only: skip backend even if one is detected
+  --no-frontend      backend-only: skip frontend even if one is detected
+  --output <dir>     frontend build output dir (dist/build/out — auto-detected)
+  --override <pw>    admin override password to deploy a backend without an account
+                     (also via SPECULOS_OVERRIDE env)
+  --env KEY=VAL      backend env var (repeatable)
+  --env-file <file>  load backend env vars from a file
+  --connector <a>    connectors exec: the source alias from \`connectors list\`
+  --tool <TOOL>      connectors exec: the tool slug to run
+  --args <json>      connectors exec: tool arguments as inline JSON
+  --args-file <f>    connectors exec: tool arguments from a JSON file (preferred
+                     in agents — inline JSON with $ ( ) etc. may need approval)
+  --api <url>        orchestrator base url (default https://deploy-orch-38hd4.speculos.ai)
+  --timeout <sec>    max seconds to wait for the backend (default 600)
+  --json             machine-readable only (auto-on when non-TTY/CI)
+
+Identity: the first deploy mints a machine-global { userId, userKey } saved to
+~/.speculos/identity.json — keep it to retain ownership of your URLs. Each project
+records its slug's stable id in .speculos.json (gitignored).
+
+The frontend is automatically pointed at the deployed backend URL via
+VITE_API_URL / NEXT_PUBLIC_API_URL / API_URL (build) or window.SPECULOS_API_URL.`;
+
+// ---- commands -----------------------------------------------------------
+
+async function cmdDetect(root, opts) {
+  const d = detect(root, opts);
+  if (!opts.json) {
+    log(opts, `slug: ${d.slug}`);
+    log(opts, `frontend: ${d.frontend ? `${path.relative(root, d.frontend.dir) || "."} (${d.frontend.kind}${d.frontend.framework ? "/" + d.frontend.framework : ""})` : "none"}`);
+    log(opts, `backend:  ${d.backend ? `${path.relative(root, d.backend.dir) || "."} (${d.backend.runtime}: ${d.backend.startCmd})` : "none"}`);
+  }
+  emit({ ok: true, detected: d });
+  return 0;
+}
+
+async function pollBackend(jobId, creds, opts) {
+  // Default wait exceeds the server-side install timeout so we don't give up
+  // while a slow install is still legitimately running.
+  const timeoutMs = (Number(opts.timeout) || 960) * 1000;
+  const t0 = Date.now();
+  let lastPhase = "";
+  while (Date.now() - t0 < timeoutMs) {
+    await sleep(3000);
+    let st;
+    try { st = await client.backendStatus(jobId, creds, opts); }
+    catch (e) { log(opts, `   (status check retry: ${e.message})`); continue; }
+    if (st.phase && st.phase !== lastPhase) { log(opts, `   … backend ${st.phase}`); lastPhase = st.phase; }
+    if (st.done) return st;
+  }
+  return { done: true, status: "error", jobId, error: `backend still starting after ${Math.round(timeoutMs / 1000)}s — it may finish shortly; check with \`speculos-toolkit status ${jobId}\`` };
+}
+
+async function cmdDeploy(root, opts) {
+  const d = detect(root, opts);
+  // Backend hosting needs either an admin --override OR a signed-in account
+  // (speculos-toolkit login) — one backend app included free. Frontend is always free.
+  const override = opts.override || process.env.SPECULOS_OVERRIDE || null;
+  let identity = creds.loadIdentity();
+  const accountToken = identity && identity.accountToken;
+  if (accountToken) opts.token = accountToken; // sent as Bearer on allocate/backend
+  const hadBackend = !!d.backend;
+  if (d.backend && !override && !accountToken) {
+    log(opts, `↪ backend detected but skipped — sign in to deploy it (every Speculos account includes one free backend app). Run \`speculos-toolkit login\`, then re-deploy. Shipping the frontend only for now.`);
+    d.backend = null;
+  }
+  if (!d.frontend && !d.backend) {
+    if (hadBackend) { emit({ ok: false, error: `nothing to deploy: Speculos hosts frontends free, but this project is backend-only — sign in to deploy the backend (every Speculos account includes one free backend app). Run \`speculos-toolkit login\` (https://deploy.speculos.ai), or add a frontend.`, code: "BETA_BACKEND_ONLY" }); return 2; }
+    emit({ ok: false, error: `could not detect a frontend in ${root}. Pass --frontend <dir>.`, code: "DETECT" });
+    return 2;
+  }
+  // reuse this project's saved slug when present
+  const saved = creds.load(root);
+  if (!opts.slug && saved && saved.slug) d.slug = saved.slug;
+  log(opts, `slug: ${d.slug}`);
+  const parts = [d.frontend ? `frontend (${d.frontend.kind})` : null, d.backend ? "backend" : null].filter(Boolean).join(" + ");
+  log(opts, `deploying: ${parts}`);
+
+  // ---- identity + slug allocation (mints a machine identity on first use) ----
+  let alloc;
+  try {
+    alloc = await client.allocate({ userId: identity && identity.userId, userKey: identity && identity.userKey, slug: d.slug }, opts);
+  } catch (e) { emit({ ok: false, error: e.message, code: e.code || "ALLOCATE" }); return 1; }
+  if (alloc.userKey) { // freshly minted on the server
+    identity = { userId: alloc.userId, userKey: alloc.userKey };
+    creds.saveIdentity(identity);
+    log(opts, `→ new device identity ${alloc.userId} (saved to ~/.speculos/identity.json — keep it)`);
+  }
+  const userId = alloc.userId, userKey = identity.userKey, slugUuid = alloc.slugUuid;
+  creds.save(root, { slug: d.slug, slugUuid });
+
+  // ---- backend first (so its URL can be baked into the frontend) ----
+  let backendUrl = null, backendNote = null;
+  if (d.backend) {
+    if (opts.envFileError) { emit({ ok: false, error: opts.envFileError, code: "ENV_FILE" }); log(opts, `✗ ${opts.envFileError}`); return 1; }
+    log(opts, `→ packing backend (${path.relative(root, d.backend.dir) || "."}, ${d.backend.runtime})`);
+    const backendTar = packDir(d.backend.dir, { dropBuildOutput: false });
+    log(opts, `→ deploying backend (${Math.round(backendTar.bytes / 1024)} KB) to an isolated sandbox`);
+    let created;
+    try {
+      created = await client.startBackend({
+        userId, userKey, slug: d.slug, slugUuid, override,
+        backend: { tarB64: backendTar.base64, runtime: d.backend.runtime, startCmd: d.backend.startCmd, env: opts.env },
+      }, opts);
+    } catch (e) {
+      // Backends not enabled (or the account is at its limit) — don't fail the
+      // deploy; ship the frontend so the user still gets a live URL, and surface
+      // how to proceed. Only genuine backend build/start errors fail the deploy.
+      if (e.code === "BACKEND_DISABLED" || e.code === "TOO_MANY") { log(opts, `↪ backend skipped — ${e.message}`); d.backend = null; backendNote = e.message; }
+      else { emit({ ok: false, error: e.message, code: e.code || "BACKEND" }); return 1; }
+    }
+    if (created) {
+      const st = await pollBackend(created.jobId, { userId, userKey }, opts);
+      if (st.status !== "success" || !(st.urls && st.urls.backend)) {
+        emit({ ok: false, slug: d.slug, jobId: created.jobId, status: "error", error: st.error || "backend failed", logTail: st.logTail });
+        log(opts, `✗ backend failed: ${st.error || "unknown"}`);
+        if (st.logTail) log(opts, st.logTail);
+        return 1;
+      }
+      backendUrl = st.urls.backend;
+      log(opts, `  backend: ${backendUrl}`);
+    }
+  }
+
+  // ---- frontend: build locally (if needed), then upload static output ----
+  let frontendUrl = null;
+  if (d.frontend) {
+    let outDir = d.frontend.dir;
+    if (d.frontend.kind === "build") {
+      log(opts, `→ building frontend locally (${d.frontend.framework})`);
+      try {
+        outDir = runBuild({
+          dir: d.frontend.dir, framework: d.frontend.framework, buildCmd: d.frontend.buildCmd,
+          base: alloc.base, backendUrl,
+          connectorsUrl: alloc.connectorsUrl, connectorsToken: alloc.connectorsToken,
+          outputDir: d.frontend.outputDir, log: (m) => log(opts, m),
+        });
+      } catch (e) { emit({ ok: false, slug: d.slug, status: "error", error: e.message, code: e.code || "BUILD" }); log(opts, `✗ build failed: ${e.message}`); return 1; }
+    }
+    log(opts, `→ packing + uploading frontend (${path.relative(root, outDir) || "."})`);
+    // If a plain static site is served straight from the repo root, exclude the
+    // server code + secrets so they aren't published. Exclude the ACTUAL detected
+    // backend dir (not a hardcoded name), plus any top-level backend-NAMED dir
+    // that really looks like a backend (has package.json/requirements) — a
+    // content dir that merely shares a name (e.g. a static api/) is left in.
+    const rootStatic = path.resolve(outDir) === path.resolve(root) && d.frontend.kind === "static";
+    let excludeDirs = [];
+    if (rootStatic) {
+      const set = new Set();
+      if (d.backend && d.backend.dir) { const rel = path.relative(root, d.backend.dir); if (rel && rel !== "" && !rel.startsWith("..")) set.add(rel); }
+      const looksBackend = (p) => fs.existsSync(path.join(p, "package.json")) || fs.existsSync(path.join(p, "requirements.txt")) || fs.existsSync(path.join(p, "pyproject.toml"));
+      for (const name of BACKEND_DIRS) { const p = path.join(root, name); if (fs.existsSync(p) && looksBackend(p)) set.add(name); }
+      excludeDirs = [...set];
+      log(opts, `   note: serving the repo root — excluding secrets${excludeDirs.length ? " + " + excludeDirs.join(", ") : ""} from the public bundle`);
+    }
+    // SECRET_EXCLUDE (frontend:true) only for the root-served case — a scoped build
+    // output shouldn't have its assets stripped just because one is named like a key.
+    const feTar = packDir(outDir, { dropBuildOutput: false, frontend: rootStatic, excludeDirs });
+    let fe;
+    try { fe = await client.putFrontend({ userId, userKey, slug: d.slug, slugUuid, tarB64: feTar.base64, backendUrl }, opts); }
+    catch (e) { emit({ ok: false, error: e.message, code: e.code || "FRONTEND" }); return 1; }
+    frontendUrl = fe.frontendUrl;
+  }
+
+  const urls = {};
+  if (frontendUrl) urls.frontend = frontendUrl;
+  if (backendUrl) urls.backend = backendUrl;
+  log(opts, `✓ live`);
+  if (urls.frontend) log(opts, `  frontend: ${urls.frontend}`);
+  if (urls.backend) log(opts, `  backend:  ${urls.backend}`);
+  if (backendNote) log(opts, `  note: ${backendNote}`);
+  const out = { ok: true, slug: d.slug, userId, urls };
+  if (backendNote) out.backendNote = backendNote;
+  emit({ ...out });
+  return 0;
+}
+
+async function cmdStatus(jobId, opts) {
+  if (!jobId) { emit({ ok: false, error: "jobId required" }); return 2; }
+  const identity = creds.loadIdentity();
+  if (!identity || !identity.userId) { emit({ ok: false, error: "no identity (~/.speculos/identity.json) — cannot poll" }); return 1; }
+  const st = await client.backendStatus(jobId, { userId: identity.userId, userKey: identity.userKey }, opts);
+  // `ok` for contract-consistency with every other command (false only on a
+  // terminal failure; a still-running poll is ok:true).
+  emit({ ok: st.status !== "error", ...st });
+  // 0 = done+success, 1 = done+failed, 2 = still running
+  return st.status === "success" ? 0 : st.done ? 1 : 2;
+}
+
+async function cmdTeardown(root, opts) {
+  const saved = creds.load(root);
+  const identity = creds.loadIdentity();
+  const slug = opts.slug || (saved && saved.slug);
+  if (!slug) { emit({ ok: false, error: "--slug required (or run from the project dir with a .speculos.json)" }); return 2; }
+  if (!identity || !identity.userId) { emit({ ok: false, error: "no identity found (~/.speculos/identity.json) — nothing to tear down from this machine" }); return 1; }
+  try {
+    const r = await client.teardown({ userId: identity.userId, userKey: identity.userKey, slug }, opts);
+    if (saved && saved.slug === slug) creds.remove(root);
+    emit({ ok: true, ...r });
+    return 0;
+  } catch (e) { emit({ ok: false, error: e.message, code: e.code || "TEARDOWN" }); return 1; }
+}
+
+// ---- login: link this machine to a Speculos account via browser device flow ----
+
+async function cmdLogin(opts) {
+  // Already linked? Don't run a redundant device flow (pass --relink to switch
+  // to a different account, incl. moving a personal-linked device onto an org).
+  const existing = creds.loadIdentity();
+  if (existing && existing.accountToken && !opts.relink && !opts.pasteToken) {
+    log(opts, `✓ this device is already linked to your Speculos account. Pass --relink to link a different account. Manage deployments at https://deploy.speculos.ai/dashboard.`);
+    emit({ ok: true, alreadyLinked: true });
+    return 0;
+  }
+
+  // Paste-a-token path: a user who already has an account (and a token from the
+  // dashboard / their platform) skips the browser device flow entirely.
+  //   npx speculos-toolkit login --token spec_tok_...
+  // Combine with --relink to move a mis-linked (e.g. personal) device onto the
+  // account/org the token belongs to.
+  if (opts.pasteToken) {
+    const token = String(opts.pasteToken).trim();
+    if (!/^spec_tok_/.test(token)) { emit({ ok: false, error: "that doesn't look like a Speculos account token (expected spec_tok_…)", code: "BAD_TOKEN" }); return 1; }
+    let who;
+    try { who = await client.whoami(token, opts); }
+    catch (e) { emit({ ok: false, error: e.status === 401 ? "that token is invalid or has been revoked" : e.message, code: e.code || "LOGIN" }); return 1; }
+    creds.saveAccountToken(token);
+    let reparented = false, previousEmail = null;
+    const identity = creds.loadIdentity();
+    if (identity && identity.userId && identity.userKey) {
+      try {
+        const r = await client.linkMachine(token, { userId: identity.userId, userKey: identity.userKey }, opts);
+        reparented = !!r.reparented; previousEmail = r.previousEmail || null;
+      } catch { /* links on next deploy via the token */ }
+    }
+    if (reparented) process.stderr.write(`\n⚠ This device's deployments moved from ${previousEmail || "another account"} to ${who.email || "this account"}.\n`);
+    log(opts, `✓ this device is linked${who.email ? ` to ${who.email}` : ""}${who.org ? ` (org: ${who.org})` : ""} — manage at https://deploy.speculos.ai/dashboard.`);
+    emit({ ok: true, linked: true, account: who.email || null, org: who.org || null, reparented, previousAccount: previousEmail });
+    return 0;
+  }
+  let start;
+  try { start = await client.linkStart(opts); }
+  catch (e) { emit({ ok: false, error: e.message, code: e.code || "LOGIN" }); return 1; }
+  // Emit the approval URL on stdout IMMEDIATELY (a JSON line) so an agent that
+  // captures stdout gets the link right away — even if the poll is later killed
+  // by a command timeout. The final result is still the last stdout line.
+  emit({ ok: true, action: "login", pending: true, url: start.url, code: start.code });
+  // And on stderr (even in --json) for a human watching.
+  process.stderr.write(`\nLink this machine to your Speculos account to enable backend hosting:\n`);
+  process.stderr.write(`\n  1. Open:  ${start.url}\n`);
+  process.stderr.write(`     (or go to https://deploy.speculos.ai/link and enter code ${start.code})\n`);
+  process.stderr.write(`  2. Sign in / sign up, then click Approve.\n\n`);
+  process.stderr.write(`Waiting for approval…\n`);
+
+  const deadline = Date.now() + (start.expiresInSec || 600) * 1000;
+  let token = null, approvedEmail = null;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    let r;
+    try { r = await client.linkPoll(start.code, opts); }
+    catch (e) { emit({ ok: false, error: e.message, code: e.code || "LOGIN" }); return 1; }
+    if (r.approved && r.token) { token = r.token; approvedEmail = r.email || null; break; }
+  }
+  if (!token) { emit({ ok: false, error: "login timed out — run `speculos-toolkit login` again", code: "TIMEOUT" }); return 1; }
+
+  creds.saveAccountToken(token);
+  // Link the current machine (and its existing deploys) to the account now.
+  let linked = false, reparented = false, previousEmail = null;
+  const identity = creds.loadIdentity();
+  if (identity && identity.userId && identity.userKey) {
+    try {
+      const r = await client.linkMachine(token, { userId: identity.userId, userKey: identity.userKey }, opts);
+      linked = true; reparented = !!r.reparented; previousEmail = r.previousEmail || null;
+    } catch { /* will link on next deploy via the token */ }
+  }
+  if (reparented) {
+    process.stderr.write(`\n⚠ This device's deployments moved from ${previousEmail || "another account"} to ${approvedEmail || "this account"}. They now appear only in the new account's dashboard.\n`);
+  }
+  log(opts, `✓ this device is linked${approvedEmail ? ` to ${approvedEmail}` : ""} — manage your deployments at https://deploy.speculos.ai/dashboard.`);
+  emit({ ok: true, linked, account: approvedEmail, reparented, previousAccount: previousEmail });
+  return 0;
+}
+
+// ---- logout: revoke this device's token (server + local) ----
+async function cmdLogout(opts) {
+  const identity = creds.loadIdentity();
+  const token = identity && identity.accountToken;
+  if (!token) { emit({ ok: true, alreadyLoggedOut: true }); return 0; }
+  let revoked = false;
+  try { const r = await client.logout(token, opts); revoked = !!r.revoked; }
+  catch { /* revoke best-effort; still clear locally */ }
+  creds.clearAccountToken();
+  log(opts, `✓ this device is signed out of your Speculos account${revoked ? " (token revoked)" : ""}.`);
+  emit({ ok: true, loggedOut: true, revoked });
+  return 0;
+}
+
+// ---- connectors: list the account/org data sources; execute a tool ----------
+//
+// Access is resolved server-side ON EVERY CALL (org membership, per-member
+// grants, freshly OAuth'd sources) — nothing is cached locally, so a grant or
+// a new link made in the dashboard applies to the very next command with no
+// re-login and no session restart.
+
+async function readStdinAll() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(""));
+  });
+}
+
+async function cmdConnectors(opts) {
+  const identity = creds.loadIdentity();
+  const token = identity && identity.accountToken;
+  if (!token) {
+    emit({ ok: false, code: "NO_TOKEN", error: "not signed in — run `npx -y speculos-toolkit@latest login`, then link data sources at https://deploy.speculos.ai/dashboard" });
+    return 1;
+  }
+  const sub = opts._[1] || "list";
+
+  if (sub === "list") {
+    let r;
+    try { r = await client.connectorsList(token, opts); }
+    catch (e) { emit({ ok: false, error: e.message, code: e.code || "CONNECTORS" }); return 1; }
+    const conns = r.connectors || [];
+    if (!opts.json) {
+      if (!conns.length) log(opts, "no data sources linked — link one at https://deploy.speculos.ai/dashboard");
+      for (const c of conns) log(opts, `  ${c.alias}  (${c.name}${c.accountIdentifier ? " · " + c.accountIdentifier : ""}) — ${(c.tools || []).length} tools`);
+    }
+    emit({ ok: true, brokerUrl: client.base(opts) + "/api/connectors", connectors: conns });
+    return 0;
+  }
+
+  if (sub === "exec") {
+    if (!opts.tool) { emit({ ok: false, error: "--tool required (pick one from `connectors list`)", code: "BAD_ARGS" }); return 2; }
+    // arguments: --args-file wins, then --args, then piped stdin, then {}
+    let args = {};
+    try {
+      if (opts.argsFile) args = JSON.parse(fs.readFileSync(opts.argsFile, "utf8"));
+      else if (opts.args) args = JSON.parse(opts.args);
+      else if (!process.stdin.isTTY) { const raw = (await readStdinAll()).trim(); if (raw) args = JSON.parse(raw); }
+    } catch (e) {
+      emit({ ok: false, error: `couldn't read tool arguments: ${e.message}`, code: "BAD_ARGS" });
+      return 2;
+    }
+    let r;
+    try { r = await client.connectorsExec(token, { connector: opts.connector, tool: opts.tool, arguments: args }, opts); }
+    catch (e) { emit({ ok: false, error: e.message, code: e.code || "EXEC" }); return 1; }
+    emit(r);
+    return r.ok ? 0 : 1;
+  }
+
+  emit({ ok: false, error: `unknown connectors subcommand "${sub}" — use list or exec` });
+  return 2;
+}
+
+// ---- install-skill: drop the Claude Code skill + allow the deploy command once ----
+
+const SKILL_PERMISSIONS = [
+  "Bash(npx -y speculos-toolkit@latest:*)",
+  "Bash(npx speculos-toolkit@latest:*)",
+  "Bash(npx -y speculos-toolkit:*)",
+  "Bash(npx speculos-toolkit:*)",
+];
+
+function cmdInstallSkill(opts) {
+  // user-level (~/.claude) by default so it's available in every project; --project for ./.claude
+  const base = opts.project ? path.join(process.cwd(), ".claude") : path.join(os.homedir(), ".claude");
+  const skillDir = path.join(base, "skills", "speculos-toolkit");
+  const settingsPath = path.join(base, "settings.json");
+  const src = path.join(__dirname, "..", "skill", "SKILL.md");
+
+  if (!fs.existsSync(src)) { emit({ ok: false, error: "bundled SKILL.md not found in this package", code: "NO_SKILL" }); return 1; }
+
+  // 0) remove any stale old-name skill dir so the renamed skill doesn't compete
+  // with the old one. Clean BOTH the user-level and project locations regardless
+  // of --project, since the old skill could have been installed in either.
+  for (const b of new Set([path.join(os.homedir(), ".claude"), path.join(process.cwd(), ".claude")])) {
+    const stale = path.join(b, "skills", "speculos-deploy");
+    try {
+      if (fs.existsSync(stale)) { fs.rmSync(stale, { recursive: true, force: true }); log(opts, `✓ removed stale skill → ${stale}`); }
+    } catch { /* best effort */ }
+  }
+
+  // 1) install the skill file
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.copyFileSync(src, path.join(skillDir, "SKILL.md"));
+  log(opts, `✓ installed skill → ${path.join(skillDir, "SKILL.md")}`);
+
+  // 2) grant the deploy command once (merge into settings.json, never clobber)
+  let settings = {}, settingsOk = true, added = 0;
+  try {
+    const raw = fs.existsSync(settingsPath) ? fs.readFileSync(settingsPath, "utf8") : "";
+    if (raw.trim()) settings = JSON.parse(raw);
+  } catch { settingsOk = false; }
+
+  if (settingsOk) {
+    // guard against a non-object `permissions` (e.g. an array) — assigning
+    // `.allow` to it would be silently dropped by JSON.stringify.
+    if (!settings.permissions || typeof settings.permissions !== "object" || Array.isArray(settings.permissions)) settings.permissions = {};
+    const allow = Array.isArray(settings.permissions.allow) ? settings.permissions.allow : [];
+    const set = new Set(allow);
+    for (const r of SKILL_PERMISSIONS) if (!set.has(r)) { set.add(r); added++; }
+    settings.permissions.allow = [...set];
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    log(opts, `✓ allowed the deploy command in ${settingsPath} (${added} rule(s) added — no more prompts)`);
+  } else {
+    log(opts, `! ${settingsPath} isn't valid JSON — add these to permissions.allow yourself:`);
+    for (const r of SKILL_PERMISSIONS) log(opts, `    ${r}`);
+  }
+
+  log(opts, `→ restart Claude Code (or reload skills) and run /speculos-toolkit in any project.`);
+  emit({ ok: true, skill: path.join(skillDir, "SKILL.md"), settings: settingsOk ? settingsPath : null, permissionsAdded: added, permissions: SKILL_PERMISSIONS });
+  return 0;
+}
+
+async function main(argv) {
+  const opts = parseArgs(argv);
+  // Node < 18 has no global fetch — every network command would die with a
+  // confusing "fetch is not defined". Fail fast with a clear message instead.
+  const major = parseInt(process.versions.node, 10);
+  if (major < 18) { emit({ ok: false, error: `Node ${process.versions.node} is too old — Speculos deploy needs Node 18+ (global fetch).`, code: "NODE_TOO_OLD" }); return 1; }
+  const isTTY = process.stdout.isTTY && !process.env.CI && !process.env.SPECULOS_NONINTERACTIVE;
+  if (!isTTY && opts.json === undefined) opts.json = true; // non-TTY/CI: machine-readable (stdout stays a clean JSON channel; the login URL still prints to stderr)
+  if (opts.version) { emit({ version: VERSION }); return 0; }
+  if (opts.help) { process.stderr.write(HELP + "\n"); return 0; }
+  const cmd = opts._[0] || "deploy";
+  const root = process.cwd();
+  try {
+    if (cmd === "deploy") return await cmdDeploy(root, opts);
+    if (cmd === "detect") return await cmdDetect(root, opts);
+    if (cmd === "status") return await cmdStatus(opts._[1], opts);
+    if (cmd === "teardown") return await cmdTeardown(root, opts);
+    if (cmd === "login") return await cmdLogin(opts);
+    if (cmd === "logout") return await cmdLogout(opts);
+    if (cmd === "connectors") return await cmdConnectors(opts);
+    if (cmd === "install-skill") return cmdInstallSkill(opts);
+    emit({ ok: false, error: "unknown command: " + cmd });
+    return 2;
+  } catch (e) {
+    emit({ ok: false, error: e.message, code: e.code || "FATAL" });
+    return 1;
+  }
+}
+
+module.exports = { main, parseArgs };

package/src/pack.js

@@ -0,0 +1,46 @@
+// Pack a directory into a base64 gzipped tar, excluding junk (node_modules, .git,
+// secrets, build artifacts). Uses the system `tar` (present on macOS/Linux/CI).
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const ALWAYS_EXCLUDE = [
+  ".git", "node_modules", ".env", ".env.*", "*.log", ".DS_Store",
+  ".vercel", ".cache", "__pycache__", ".venv", "venv", ".pytest_cache",
+  ".idea", ".vscode", "*.tgz", "coverage", ".speculos.json", ".gitignore",
+];
+// for "build" frontends the server rebuilds, so drop prebuilt output too
+const BUILD_EXCLUDE = ["dist", "build", "out", ".next", ".nuxt", ".svelte-kit", ".output"];
+// A frontend bundle is served PUBLICLY, so never ship credentials in it — this
+// matters most when a plain static site is served straight from the repo root
+// (a sibling secret file would otherwise be downloadable). Applied to frontend
+// packs only, NOT backends (a backend may legitimately ship a cert/key).
+const SECRET_EXCLUDE = [
+  "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa", "id_rsa.*", "id_ed25519", "id_ed25519.*",
+  "id_dsa", "credentials.json", "credentials.yaml", "credentials.yml",
+  "secrets.json", "secrets.yaml", "secrets.yml", "service-account*.json",
+  ".npmrc", ".netrc", ".pgpass", ".ssh", ".aws", ".gcloud",
+];
+// backend source dirs — excluded when the frontend IS the repo root, so serving
+// a root static site doesn't publish the server code sitting next to it.
+const BACKEND_DIRS = ["backend", "api", "server", "svc", "service"];
+
+function packDir(dir, { dropBuildOutput = false, frontend = false, excludeDirs = [] } = {}) {
+  const excludes = ALWAYS_EXCLUDE
+    .concat(dropBuildOutput ? BUILD_EXCLUDE : [])
+    .concat(frontend ? SECRET_EXCLUDE : []);
+  const tmp = path.join(os.tmpdir(), `speculos-${Date.now()}-${Math.floor(process.hrtime()[1] % 1e6)}.tgz`);
+  const args = ["czf", tmp];
+  for (const e of excludes) args.push("--exclude=" + e);
+  // excludeDirs are TOP-LEVEL paths (e.g. a backend dir) — anchor with ./ so they
+  // exclude only that top-level dir, never a same-named dir nested in the site.
+  for (const e of (excludeDirs || [])) args.push("--exclude=./" + String(e).replace(/^\.?\/*/, "").replace(/\/+$/, ""));
+  args.push("-C", dir, ".");
+  execFileSync("tar", args, { stdio: ["ignore", "ignore", "pipe"] });
+  const buf = fs.readFileSync(tmp);
+  fs.unlinkSync(tmp);
+  return { base64: buf.toString("base64"), bytes: buf.length };
+}
+
+module.exports = { packDir, BACKEND_DIRS };