speculos-toolkit 1.2.6 → 1.2.8

package/README.md

@@ -61,10 +61,24 @@ The first deploy mints a machine-global `~/.speculos/identity.json` (`{ userId,
 that owns every URL deployed from this machine; each project records its slug id in a
 gitignored `.speculos.json`. Keep both to retain ownership.
 
+Set `SPECULOS_CONFIG_DIR` to an absolute directory path to use a separate identity
+and account token stored at `<directory>/identity.json`. For example,
+`SPECULOS_CONFIG_DIR=/absolute/path/to/profile speculos-toolkit login` signs into
+that profile. Leave the variable unset to use `~/.speculos`. Relative paths,
+unexpanded `~` paths, and empty values fail with `CREDENTIALS` before any API call
+or credential write. Each project's `.speculos.json` stays in its project directory.
+The credentials directory is excluded from frontend and backend upload archives.
+It cannot also be selected as the deployment source or frontend build output.
+
 If either identity file is unreadable or damaged, the CLI stops so you can restore it
 before deploying. A failed login or logout reports the failure; rerun the same command
 to retry linking or revoking the device.
 
+`logout` signs the terminal out and revokes its account token. Existing apps, URLs,
+and their account ownership stay in place. The signed-out terminal cannot deploy,
+change, remove, or poll those apps until an explicit `login` succeeds again. If the
+server cannot confirm sign-out, the CLI keeps its credential so you can retry.
+
 ## Conventions
 
 - **Backend** listens on `process.env.PORT`, binds `0.0.0.0`. Node or Python.
@@ -80,7 +94,7 @@ 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 logout                sign out (preserves apps and URLs)
 speculos-toolkit connectors [list|exec]  your linked data sources, and one tool call
 speculos-toolkit install-skill         install the Claude Code skill
 
@@ -103,3 +117,21 @@ configuration into the CLI process itself.
 Docs: https://unified.speculos.ai · Source: https://github.com/speculosai/unified_platform
 
 MIT
+
+### Deployment consistency (1.2.8)
+
+An existing application's visibility changes only when the requested release is
+published. Allocation or a backend quota refusal preserves the live audience.
+Private code closes the frontend/backend gates before upload. A definitive bad
+frontend archive restores the prior audience; an ambiguous network failure keeps
+the application private until you retry. Use `npx -y speculos-toolkit@latest` for
+visibility changes to existing applications; older clients receive an upgrade
+message before any visibility change.
+
+The CLI carries an app-specific deployment ID through backend and frontend
+publication. Retried requests cannot publish different content under an already
+used ID. A backend release reserves its matching frontend while that release is
+unfinished, and a later dashboard visibility change invalidates an earlier
+allocation. After linking an anonymous terminal, its anonymous deployment and
+usage history is adopted into the verified account; pending adoption retries on
+history reads.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speculos-toolkit",
-  "version": "1.2.6",
-  "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.",
+  "version": "1.2.8",
+  "description": "The Speculos toolkit for coding agents — deploy any frontend/backend to a live URL and build against your linked data connectors (BigQuery, Postgres, Snowflake, Salesforce, …). Built for Claude Code, Codex, Cursor, and friends.",
   "bin": {
     "speculos-toolkit": "bin/speculos-toolkit.js"
   },

package/skill/SKILL.md

@@ -292,8 +292,9 @@ Builds run locally (this machine already has the toolchain); only static output
   link from that first line and **relay it to the user** — ask them to open it, sign in, and
   click Approve. It links this machine to their account (already linked? it no-ops — pass
   `--relink` to switch accounts). Backend deploys then work with no password — **every
-  account includes one backend app free**, so there's no enablement wait. Unlink with
-  `speculos-toolkit logout`.
+  account includes one backend app free**, so there's no enablement wait. Sign out with
+  `speculos-toolkit logout`. Apps and URLs stay owned by the account; run `login`
+  again before this terminal can manage them.
 - **Frontend + backend (signed in):** just run the normal deploy — the saved sign-in
   authorizes the backend:
   ```bash

package/src/client.js

@@ -48,7 +48,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); }
-// The machine identity rides along so the server can unlink it too.
+// The machine identity rides along so the server can revoke its authority while
+// preserving account ownership of its published applications.
 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

package/src/creds.js

@@ -14,7 +14,12 @@ function credentialError(message, cause) {
 
 // ---- machine-global identity --------------------------------------------
 
-function identityDir() { return path.join(os.homedir(), ".speculos"); }
+function identityDir() {
+  const configured = process.env.SPECULOS_CONFIG_DIR;
+  if (configured === undefined) return path.join(os.homedir(), ".speculos");
+  if (!path.isAbsolute(configured)) throw credentialError("SPECULOS_CONFIG_DIR must be an absolute path");
+  return configured;
+}
 function identityFile() { return path.join(identityDir(), "identity.json"); }
 
 function loadIdentity() {
@@ -58,11 +63,15 @@ function saveAccountToken(accountToken) {
   const cur = loadIdentity() || {};
   writeIdentity({ ...cur, accountToken });
 }
-function clearAccountToken() {
+function clearAccountToken(expectedToken) {
   const cur = loadIdentity();
-  if (!cur) return;
+  if (!cur) return true;
+  // A login can finish while an earlier logout request is in flight. Never
+  // erase that newer credential when the old request eventually responds.
+  if (arguments.length && cur.accountToken !== expectedToken) return false;
   delete cur.accountToken;
   writeIdentity(cur);
+  return true;
 }
 
 // ---- per-project slug record --------------------------------------------
@@ -112,4 +121,4 @@ function ensureGitignored(root) {
   } catch { /* best effort */ }
 }
 
-module.exports = { loadIdentity, saveIdentity, saveAccountToken, clearAccountToken, load, save, remove, file };
+module.exports = { identityDir, loadIdentity, saveIdentity, saveAccountToken, clearAccountToken, load, save, remove, file };

package/src/index.js

@@ -96,7 +96,7 @@ USAGE
                                        --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 logout          sign this terminal out (keep its apps and URLs)
   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]
@@ -163,7 +163,8 @@ OPTIONS
   --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
+~/.speculos/identity.json (or an absolute SPECULOS_CONFIG_DIR) — 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
@@ -210,7 +211,22 @@ async function cmdDeploy(root, opts) {
   // Keep the source directory even if an anonymous/frontend-only deploy skips
   // running it. Skipping its sandbox must never publish its source as frontend.
   const backendSourceDir = (d.backend && d.backend.dir) || (opts.backend && path.resolve(root, opts.backend));
-  if (d.frontend && d.frontend.kind === "static" && backendSourceDir && path.resolve(d.frontend.dir) === path.resolve(backendSourceDir)) {
+  const canonicalPath = (dir) => { try { return fs.realpathSync(dir); } catch { return path.resolve(dir); } };
+  const credentialDir = creds.identityDir();
+  const privateDirExclusions = (archiveDir, privateDir) => {
+    const paths = new Set();
+    for (const [base, target] of [[path.resolve(archiveDir), path.resolve(privateDir)], [canonicalPath(archiveDir), canonicalPath(privateDir)]]) {
+      const rel = path.relative(base, target);
+      if (rel && rel !== ".." && !rel.startsWith(".." + path.sep) && !path.isAbsolute(rel)) paths.add(rel);
+    }
+    return paths;
+  };
+  const isCredentialDir = (dir) => canonicalPath(dir) === canonicalPath(credentialDir);
+  if ([d.frontend && d.frontend.dir, d.backend && d.backend.dir].filter(Boolean).some(isCredentialDir)) {
+    emit({ ok: false, error: "the deployment source is the credentials directory; select a separate frontend or backend directory", code: "CREDENTIALS_SCOPE" });
+    return 2;
+  }
+  if (d.frontend && d.frontend.kind === "static" && backendSourceDir && canonicalPath(d.frontend.dir) === canonicalPath(backendSourceDir)) {
     emit({ ok: false, error: "the static frontend and backend share a directory; select a separate frontend directory or build output so backend source is not published", code: "FRONTEND_SCOPE" });
     return 2;
   }
@@ -245,7 +261,7 @@ async function cmdDeploy(root, opts) {
   // ---- 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, visibility: opts.visibility }, opts);
+    alloc = await client.allocate({ userId: identity && identity.userId, userKey: identity && identity.userKey, slug: d.slug, visibility: opts.visibility, deploymentProtocol: 2 }, opts);
   } catch (e) {
     // Readable first: emit() is JSON for the agent case, but a person who typed
     // --private with no account needs to see WHY in plain words.
@@ -256,7 +272,7 @@ async function cmdDeploy(root, opts) {
   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)`);
+    log(opts, `→ new device identity ${alloc.userId} (saved to ${path.join(credentialDir, "identity.json")} — keep it)`);
   }
   const userId = alloc.userId, userKey = identity.userKey, slugUuid = alloc.slugUuid;
   creds.save(root, { slug: d.slug, slugUuid });
@@ -265,12 +281,13 @@ async function cmdDeploy(root, opts) {
   let backendUrl = null, jobId = null, historyIds = [];
   if (d.backend) {
     log(opts, `→ packing backend (${path.relative(root, d.backend.dir) || "."}, ${d.backend.runtime})`);
-    const backendTar = packDir(d.backend.dir, { dropBuildOutput: false });
+    const backendTar = packDir(d.backend.dir, { dropBuildOutput: false, excludeDirs: [...privateDirExclusions(d.backend.dir, credentialDir)] });
     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,
+        deploymentId: alloc.deploymentId, finalizeVisibility: !d.frontend,
         backend: { tarB64: backendTar.base64, runtime: d.backend.runtime, startCmd: d.backend.startCmd, env: opts.env },
       }, opts);
     } catch (e) {
@@ -343,29 +360,37 @@ async function cmdDeploy(root, opts) {
         });
       } 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; }
     }
+    if (isCredentialDir(outDir)) {
+      emit({ ok: false, error: "the frontend output is the credentials directory; select a separate build output directory", code: "CREDENTIALS_SCOPE" });
+      return 2;
+    }
     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 = [];
+    // Any static frontend can contain the selected backend, including a custom
+    // frontend directory. Exclude both the selected path and its real location
+    // so a symlink to the backend does not leave the source in the public bundle.
+    const set = privateDirExclusions(outDir, credentialDir);
+    if (d.frontend.kind === "static" && backendSourceDir) {
+      for (const rel of privateDirExclusions(outDir, backendSourceDir)) set.add(rel);
+    }
+    // Serving the repo root also excludes other top-level backend-looking dirs.
+    // Keep this heuristic at the repo root so ordinary static api/ content stays.
+    const rootStatic = d.frontend.kind === "static" && canonicalPath(outDir) === canonicalPath(root);
     if (rootStatic) {
-      const set = new Set();
-      if (backendSourceDir) { const rel = path.relative(root, backendSourceDir); if (rel && rel !== ".." && !rel.startsWith(".." + path.sep) && !path.isAbsolute(rel)) 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];
+    }
+    const excludeDirs = [...set];
+    if (rootStatic) {
       log(opts, `   note: serving the repo root — excluding secrets${excludeDirs.length ? " + " + excludeDirs.join(", ") : ""} from the public bundle`);
     }
     // Every frontend bundle is downloadable, including explicitly selected
     // directories and build output that copied a public/ credential file.
     const feTar = packDir(outDir, { dropBuildOutput: false, frontend: true, excludeDirs });
     let fe;
-    try { fe = await client.putFrontend({ userId, userKey, slug: d.slug, slugUuid, tarB64: feTar.base64, backendUrl: feBackendUrl, unsetBackend: !!opts.unsetBackend }, opts); }
+    try { fe = await client.putFrontend({ userId, userKey, slug: d.slug, slugUuid, deploymentId: alloc.deploymentId, 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.visibility) alloc.visibility = fe.visibility;
     if (fe.historyId) historyIds.push(fe.historyId);
   }
 
@@ -401,7 +426,7 @@ async function cmdDeploy(root, opts) {
 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; }
+  if (!identity || !identity.userId) { emit({ ok: false, error: `no identity (${path.join(creds.identityDir(), "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).
@@ -415,7 +440,7 @@ async function cmdTeardown(root, opts) {
   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; }
+  if (!identity || !identity.userId) { emit({ ok: false, error: `no identity found (${path.join(creds.identityDir(), "identity.json")}) — nothing to tear down from this machine` }); return 1; }
   try {
     if (identity.accountToken) opts.token = identity.accountToken;
     const r = await client.teardown({ userId: identity.userId, userKey: identity.userKey, slug }, opts);
@@ -528,24 +553,38 @@ async function cmdLogin(opts) {
   return 0;
 }
 
-// ---- logout: revoke this device's token (server + local) ----
+// ---- logout: revoke this terminal's authority, preserve its published apps ----
 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, unlinked = false;
+  if (!token && !(identity && identity.userId)) { emit({ ok: true, alreadyLoggedOut: true }); return 0; }
+  let revoked = false, unlinked = false, signedOut = false, ownershipPreserved = false, alreadyRevoked = false, tokenAbsent = false;
   try {
     const r = await client.logout(token, { userId: identity.userId, userKey: identity.userKey }, opts);
-    revoked = !!r.revoked; unlinked = !!r.unlinked;
+    const hasMachine = !!(identity.userId || identity.userKey);
+    // Older servers can return HTTP 200 after swallowing revocation/unlink
+    // failures. Success must establish both token revocation and (when there
+    // is a machine) loss of machine authority before discarding our retry key.
+    if (r.ok !== true || !(r.revoked === true || r.alreadyRevoked === true || (!token && r.tokenAbsent === true)) ||
+        (hasMachine && r.signedOut !== true && r.unlinked !== true)) {
+      throw Object.assign(new Error("the server did not confirm that this terminal was signed out"), { code: "LOGOUT_INCOMPLETE" });
+    }
+    revoked = r.revoked === true; alreadyRevoked = r.alreadyRevoked === true;
+    tokenAbsent = r.tokenAbsent === true;
+    unlinked = r.unlinked === true; signedOut = r.signedOut === true || unlinked;
+    ownershipPreserved = r.ownershipPreserved === true;
   } catch (e) {
-    // Keep the token so a retry can revoke it and unlink the machine. Clearing
+    // Keep the token so a retry can revoke it and sign the machine out. Clearing
     // it during an outage makes an active server credential unrecoverable.
     emit({ ok: false, loggedOut: false, error: `could not sign out: ${e.message}; retry logout when the service is reachable`, code: e.code || "LOGOUT" });
     return 1;
   }
-  creds.clearAccountToken();
-  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 });
+  if (!creds.clearAccountToken(token)) {
+    emit({ ok: false, loggedOut: false, revoked, code: "LOGOUT_SUPERSEDED", error: "the saved sign-in changed while logout was pending; the newer credential was kept" });
+    return 1;
+  }
+  log(opts, `✓ this terminal is signed out of your Speculos account.${ownershipPreserved ? " Its apps and URLs are preserved; run `login` to manage them again." : ""}`);
+  emit({ ok: true, loggedOut: true, revoked, alreadyRevoked, tokenAbsent, signedOut, ownershipPreserved, unlinked });
   return 0;
 }
 

package/src/pack.js

@@ -39,7 +39,12 @@ function packDir(dir, { dropBuildOutput = false, frontend = false, excludeDirs =
   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(/^\/+/, "").replace(/\/+$/, ""));
+  for (const e of (excludeDirs || [])) {
+    // These are literal paths, unlike the wildcard patterns above. A custom
+    // credentials directory may itself contain brackets, stars or question marks.
+    const literal = String(e).replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "").replace(/[\\*?\[\]]/g, (character) => "\\" + character);
+    args.push("--exclude=./" + literal);
+  }
   args.push("-C", dir, ".");
   try {
     execFileSync("tar", args, { stdio: ["ignore", "ignore", "pipe"] });