speculos-toolkit 1.2.1 → 1.2.3

package/README.md

@@ -73,12 +73,22 @@ speculos-toolkit [deploy]              detect, pack, deploy ./
 speculos-toolkit detect                show what would deploy (no upload)
 speculos-toolkit status <jobId>        poll a deployment
 speculos-toolkit teardown --slug <s>   remove a deployment
+speculos-toolkit login [--token …]     link this machine (browser approval at
+                                       https://unified.speculos.ai/link)
+speculos-toolkit logout                unlink it (revokes this device's token)
+speculos-toolkit connectors [list|exec]  your linked data sources, and one tool call
+speculos-toolkit install-skill         install the Claude Code skill
 
 --frontend <dir>   --backend <dir>   --slug <name>
---runtime node|python   --start "<cmd>"   --build   --output <dir>
+--runtime node|python|bun   --start "<cmd>"   --build   --static   --output <dir>
+--private | --org | --public
 --env KEY=VAL   --env-file <file>   --api <url>   --timeout <sec>   --json
 ```
 
+`--api` defaults to `https://unified-api.speculos.ai/toolkit` (the platform gateway,
+which proxies to the deploy orchestrator and records the deploy in the console's
+history); `SPECULOS_API` overrides it.
+
 Docs: https://unified.speculos.ai · Source: https://github.com/speculosai/unified_platform
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speculos-toolkit",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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

@@ -222,6 +222,11 @@ export async function connector(alias, tool, args) {
 }
 ```
 
+(The `x-speculos-gate` line is belt-and-braces: the deployed page also loads an
+injected `speculos-env.js` that patches `fetch`/`XMLHttpRequest` to add that header
+on every call to the backend or broker origin, so an app written WITHOUT this helper
+still works when it is private. Keeping it costs nothing and makes the flow explicit.)
+
 Rules (and state to the user):
 - **Read-only only.** The broker rejects any non-read tool on this path (`WRITE_BLOCKED`).
   Use `LIST_`/`GET_`/`SEARCH_`/`QUERY` tools; `POSTGRES_QUERY` runs in a read-only transaction.

package/src/client.js

@@ -36,7 +36,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

@@ -100,14 +100,16 @@ 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).
 
 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
+  --backend <dir>    backend dir  (auto-detected: backend/api/server/…) — needs a linked
+                     account (one backend app is included) or --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)
@@ -130,7 +132,7 @@ OPTIONS
   --args-file <f>    connectors exec: tool arguments from a JSON file (preferred
                      in agents — inline JSON with $ ( ) etc. may need approval)
   --api <url>        platform API base (default https://unified-api.speculos.ai/toolkit)
-  --timeout <sec>    max seconds to wait for the backend (default 600)
+  --timeout <sec>    max seconds to wait for the backend (default 960)
   --json             machine-readable only (auto-on when non-TTY/CI)
 
 Identity: the first deploy mints a machine-global { userId, userKey } saved to
@@ -184,11 +186,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;
@@ -220,7 +227,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})`);
@@ -240,6 +247,8 @@ async function cmdDeploy(root, opts) {
       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 });
@@ -290,6 +299,7 @@ async function cmdDeploy(root, opts) {
     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;
+    if (fe.historyId) historyIds.push(fe.historyId);
   }
 
   const urls = {};
@@ -309,6 +319,10 @@ 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 (historyIds.length) out.historyIds = historyIds;
   if (visibility) out.visibility = visibility;
   if (alloc && alloc.visibilityNote) out.visibilityNote = alloc.visibilityNote;
   if (backendNote) out.backendNote = backendNote;
@@ -338,8 +352,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; }
 }
 
@@ -428,12 +443,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;
 }
 
@@ -471,9 +488,10 @@ async function cmdConnectors(opts) {
     if (!opts.json) {
       if (!conns.length) log(opts, "no data sources linked — link one at https://unified.speculos.ai/?tab=deploys");
       for (const c of conns) {
-        // Say which product a source came from: the deploy plane and the
-        // Cloud console hold separate connections, often to the same SaaS,
-        // and running a tool against the wrong one is silent and wrong.
+        // Mark the org-wide sources: a person in an org sees those plus their
+        // own, and which one a tool runs against matters. (Console and toolkit
+        // now share ONE Composio workspace, so there is no "which product"
+        // left to disambiguate — a source linked in the console is this source.)
         const scope = c.orgWide ? " · org" : "";
         log(opts, `  ${c.alias}  (${c.name}${c.accountIdentifier ? " · " + c.accountIdentifier : ""}${scope}) — ${(c.tools || []).length} tools`);
       }