speculos-toolkit 1.2.3 → 1.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speculos-toolkit",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "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,15 @@ 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 — that sticks: the app
+  stays detached until a deploy actually ships a backend again.
 - `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) {

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;
@@ -115,7 +118,11 @@ 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).
+                     It stays cleared until you deploy a backend again
   --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)
@@ -244,6 +251,14 @@ 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) {
@@ -261,6 +276,22 @@ 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, and the orchestrator remembers that: later frontend-only
+  // deploys stay detached (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) — it stays cleared until you deploy a backend again; 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) {
@@ -270,7 +301,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),
         });
@@ -296,7 +327,7 @@ 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);
@@ -304,10 +335,10 @@ async function cmdDeploy(root, opts) {
 
   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
@@ -322,6 +353,7 @@ async function cmdDeploy(root, opts) {
   // 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;