speculos-toolkit 1.2.2 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speculos-toolkit",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "The Speculos toolkit for coding agents \u2014 deploy any frontend/backend to a live URL and build against your linked data connectors (BigQuery, Postgres, Snowflake, Salesforce, \u2026). Built for Claude Code, Codex, Cursor, and friends.",
   "bin": {
     "speculos-toolkit": "bin/speculos-toolkit.js"

package/skill/SKILL.md

@@ -149,6 +149,14 @@ The last stdout line is `{ ok, brokerUrl, connectors: [{ alias, name, kind, acco
 - `ok:false` + `code:"LOGIN_REQUIRED"` on a deploy → `--private`/`--org` was asked for on a
   machine with no account. Nothing was published. Either run `login` and deploy again, or
   drop the flag (the app ships public) and lock it down after linking.
+- `ok:false` + `code:"ALREADY_DEPLOYING"` (with `jobId`) → another deploy of this app is
+  still installing. Nothing was written. Watch it with `status <jobId>` and re-run after,
+  rather than racing it - two concurrent full-stack deploys used to clobber each other
+  inside the sandbox and leave the backend failed.
+- **A frontend-only deploy keeps the app's backend.** `--no-backend` (or a repo where the
+  backend did not change) redeploys the frontend against the SAME backend URL and says so
+  (`backendKept: true`); it used to silently bake `null` and the live app started 404ing
+  its own API. Pass `--unset-backend` to actually detach it.
 - `ok:true` with empty `connectors` → nothing linked (or nothing granted to this user).
   If the app clearly wants external data, tell the user to link a source (or ask their org
   admin for access) at **https://unified.speculos.ai/?tab=deploys**, then **re-run the list** —

package/src/client.js

@@ -13,7 +13,8 @@ async function post(url, body, token) {
   if (token) headers["Authorization"] = "Bearer " + token;
   const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) { const e = new Error(data.error || `HTTP ${res.status}`); e.code = data.code; e.status = res.status; throw e; }
+  // Some refusals name a job to follow (ALREADY_DEPLOYING); keep it on the error.
+  if (!res.ok) { const e = new Error(data.error || `HTTP ${res.status}`); e.code = data.code; e.status = res.status; e.jobId = data.jobId || null; throw e; }
   return data;
 }
 async function get(url, token, extra) {
@@ -36,7 +37,8 @@ async function linkPoll(code, opts = {}) { return post(base(opts) + "/api/cli/li
 // verify a pasted account token (login --token) and get its account/org
 async function whoami(token, opts = {}) { return get(base(opts) + "/api/account/whoami", token); }
 async function linkMachine(token, payload, opts = {}) { return post(base(opts) + "/api/account/link", payload, token); }
-async function logout(token, opts = {}) { return post(base(opts) + "/api/account/logout", {}, token); }
+// The machine identity rides along so the server can unlink it too.
+async function logout(token, machine = {}, opts = {}) { return post(base(opts) + "/api/account/logout", { userId: machine.userId, userKey: machine.userKey }, token); }
 // poll a backend job (owner-authenticated)
 // The machine credentials travel as headers, not a query string: a query
 // string is written to every access log between here and the orchestrator.

package/src/index.js

@@ -41,6 +41,9 @@ function parseArgs(argv) {
     else if (a === "--org") opts.visibility = "org";
     else if (a === "--public") opts.visibility = "public";
     else if (a === "--no-backend") opts.noBackend = true;
+    // Explicitly clear the app's saved backend URL. A deploy that simply ships
+    // no backend KEEPS it (see cmdDeploy) — this is how you say "no backend".
+    else if (a === "--unset-backend") opts.unsetBackend = 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;
@@ -100,7 +103,8 @@ WHO CAN SEE IT
                apps come with it — then deploy again with --private, or flip it
                on https://unified.speculos.ai/?tab=deploys.
 
-A redeploy never changes the visibility of an app that is already live.
+A redeploy with no visibility flag never changes a live app's visibility;
+an explicit --private / --org / --public applies immediately, both ways.
 Every Speculos account includes one backend app free (an isolated sandbox per app) —
 sign up at https://unified.speculos.ai and run 'speculos-toolkit login'.
 Without an account a detected backend is skipped (frontend still ships free).
@@ -114,7 +118,10 @@ OPTIONS
   --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-backend       frontend-only: skip backend even if one is detected (the app
+                     keeps pointing at the backend it already has)
+  --unset-backend    clear this app's backend URL: the frontend stops calling a
+                     backend (the sandbox itself stays up — use teardown for that)
   --private          only you can open the deployed app (needs an account;
                      the DEFAULT for a new app once this machine is linked)
   --org              anyone in your org can open it (needs an account)
@@ -185,11 +192,16 @@ async function cmdDeploy(root, opts) {
   const accountToken = identity && identity.accountToken;
   if (accountToken) opts.token = accountToken; // sent as Bearer on allocate/backend
   const hadBackend = !!d.backend;
+  let backendNote = null;
   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.`);
+    // Said in the JSON too: an agent reads only stdout, and "ok: true" with a
+    // frontend URL used to hide that the API it built never shipped.
+    backendNote = "backend detected but skipped: this machine is not linked to a Speculos account (every account includes one backend app). Run `speculos-toolkit login`, then deploy again.";
+    log(opts, `↪ ${backendNote}`);
     d.backend = null;
   }
   if (!d.frontend && !d.backend) {
+    if (opts.noFrontend && opts.noBackend) { emit({ ok: false, error: "both --no-frontend and --no-backend were given - nothing to deploy", code: "NOTHING_SELECTED" }); return 2; }
     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://unified.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;
@@ -221,7 +233,7 @@ async function cmdDeploy(root, opts) {
   creds.save(root, { slug: d.slug, slugUuid });
 
   // ---- backend first (so its URL can be baked into the frontend) ----
-  let backendUrl = null, backendNote = null;
+  let backendUrl = null, jobId = null, historyIds = [];
   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})`);
@@ -238,9 +250,19 @@ async function cmdDeploy(root, opts) {
       // 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; }
+      // Another deploy of THIS app is still installing. Both would overwrite
+      // each other's files inside the sandbox, so stop and say so plainly —
+      // with the job to follow — rather than shipping a half-deploy.
+      else if (e.code === "ALREADY_DEPLOYING") {
+        log(opts, `✗ ${e.message}`);
+        emit({ ok: false, slug: d.slug, status: "error", error: e.message, code: "ALREADY_DEPLOYING", ...(e.jobId ? { jobId: e.jobId } : {}) });
+        return 1;
+      }
       else { emit({ ok: false, error: e.message, code: e.code || "BACKEND" }); return 1; }
     }
     if (created) {
+      jobId = created.jobId;
+      if (created.historyId) historyIds.push(created.historyId);
       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 });
@@ -253,6 +275,20 @@ async function cmdDeploy(root, opts) {
     }
   }
 
+  // A deploy that ships no backend this time is NOT a deploy of an app with no
+  // backend: `--no-backend` (or a skipped/absent backend) keeps the app pointed
+  // at the backend it already has, which allocate reports. Without this, the
+  // rebuilt bundle and the regenerated speculos-env.js both said "no backend"
+  // and a live app started 404ing its own API. --unset-backend is the explicit
+  // way to clear it (the backend sandbox itself stays up; `teardown` removes it).
+  let keptBackendUrl = null;
+  const liveBackendUrl = (alloc && alloc.backendUrl) || null;
+  if (!backendUrl && liveBackendUrl) {
+    if (opts.unsetBackend) log(opts, `↪ clearing this app's backend URL (--unset-backend) — the backend itself stays up`);
+    else { keptBackendUrl = liveBackendUrl; log(opts, `↪ keeping this app's existing backend: ${keptBackendUrl} (--unset-backend to clear it)`); }
+  }
+  const feBackendUrl = backendUrl || keptBackendUrl;
+
   // ---- frontend: build locally (if needed), then upload static output ----
   let frontendUrl = null;
   if (d.frontend) {
@@ -262,7 +298,7 @@ async function cmdDeploy(root, opts) {
       try {
         outDir = runBuild({
           dir: d.frontend.dir, framework: d.frontend.framework, buildCmd: d.frontend.buildCmd,
-          base: alloc.base, backendUrl,
+          base: alloc.base, backendUrl: feBackendUrl,
           connectorsUrl: alloc.connectorsUrl, connectorsToken: alloc.connectorsToken,
           outputDir: d.frontend.outputDir, log: (m) => log(opts, m),
         });
@@ -288,17 +324,18 @@ async function cmdDeploy(root, opts) {
     // 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); }
+    try { fe = await client.putFrontend({ userId, userKey, slug: d.slug, slugUuid, tarB64: feTar.base64, backendUrl: feBackendUrl, unsetBackend: !!opts.unsetBackend }, opts); }
     catch (e) { emit({ ok: false, error: e.message, code: e.code || "FRONTEND" }); return 1; }
     frontendUrl = fe.frontendUrl;
+    if (fe.historyId) historyIds.push(fe.historyId);
   }
 
   const urls = {};
   if (frontendUrl) urls.frontend = frontendUrl;
-  if (backendUrl) urls.backend = backendUrl;
+  if (feBackendUrl) urls.backend = feBackendUrl;
   log(opts, `✓ live`);
   if (urls.frontend) log(opts, `  frontend: ${urls.frontend}`);
-  if (urls.backend) log(opts, `  backend:  ${urls.backend}`);
+  if (urls.backend) log(opts, `  backend:  ${urls.backend}${keptBackendUrl ? " (kept — not redeployed this time)" : ""}`);
   if (backendNote) log(opts, `  note: ${backendNote}`);
   // Say who can open it. A new app is private now, and a URL printed with no
   // word about visibility is the kind of thing people paste into Slack and
@@ -310,6 +347,11 @@ async function cmdDeploy(root, opts) {
   else if (visibility === "public") log(opts, `  visibility: public — anyone with the link.`);
   if (alloc && alloc.visibilityNote) log(opts, `  note: ${alloc.visibilityNote}`);
   const out = { ok: true, slug: d.slug, userId, urls };
+  // What an agent needs to follow up without a second lookup: the backend
+  // job id for `status`, and the console history ids the gateway filed.
+  if (jobId) out.jobId = jobId;
+  if (keptBackendUrl) out.backendKept = true; // the URL above is the live one, not a new deploy
+  if (historyIds.length) out.historyIds = historyIds;
   if (visibility) out.visibility = visibility;
   if (alloc && alloc.visibilityNote) out.visibilityNote = alloc.visibilityNote;
   if (backendNote) out.backendNote = backendNote;
@@ -339,8 +381,9 @@ async function cmdTeardown(root, opts) {
     if (identity.accountToken) opts.token = identity.accountToken;
     const r = await client.teardown({ userId: identity.userId, userKey: identity.userKey, slug }, opts);
     if (saved && saved.slug === slug) creds.remove(root);
+    if (r.notFound) log(opts, `! nothing was deployed under "${slug}" from this machine - nothing to tear down`);
     emit({ ok: true, ...r });
-    return 0;
+    return r.notFound ? 3 : 0;
   } catch (e) { emit({ ok: false, error: e.message, code: e.code || "TEARDOWN" }); return 1; }
 }
 
@@ -429,12 +472,14 @@ 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 */ }
+  let revoked = false, unlinked = false;
+  try {
+    const r = await client.logout(token, { userId: identity.userId, userKey: identity.userKey }, opts);
+    revoked = !!r.revoked; unlinked = !!r.unlinked;
+  } 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 });
+  log(opts, `✓ this device is signed out of your Speculos account${revoked ? " (token revoked)" : ""}${unlinked ? "; the machine is no longer linked to it - `login` links it again" : ""}.`);
+  emit({ ok: true, loggedOut: true, revoked, unlinked });
   return 0;
 }