speculos-toolkit 1.2.5 → 1.2.7

package/README.md

@@ -30,7 +30,8 @@ host never runs your build.
 
 `--private` or `--org` without an account fails the deploy (`LOGIN_REQUIRED`)
 rather than publishing something public that you asked to keep private.
-A redeploy never changes the visibility of an app that is already live.
+A redeploy without a visibility flag preserves the app's current visibility.
+An explicit `--private`, `--org`, or `--public` changes it.
 
 ## What it prints
 
@@ -60,6 +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.
@@ -75,20 +94,26 @@ 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
 
 --frontend <dir>   --backend <dir>   --slug <name>
 --runtime node|python|bun   --start "<cmd>"   --build   --static   --output <dir>
 --private | --org | --public
---env KEY=VAL   --env-file <file>   --api <url>   --timeout <sec>   --json
+--env KEY=VAL   --backend-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.
 
+Use `--backend-env-file` for backend configuration. The legacy `--env-file` alias
+still works when invoking Node with a delimiter, such as
+`node -- /path/to/speculos-toolkit.js deploy --env-file .env.backend`.
+Node 24/25 otherwise consume that flag before the CLI starts and can load backend
+configuration into the CLI process itself.
+
 Docs: https://unified.speculos.ai · Source: https://github.com/speculosai/unified_platform
 
 MIT

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "speculos-toolkit",
-  "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.",
+  "version": "1.2.7",
+  "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"
   },
   "type": "commonjs",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=18"
   },

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
@@ -304,7 +305,11 @@ Builds run locally (this machine already has the toolchain); only static output
   (Admins/CI can instead pass `--override <password>` to bypass account auth.)
 - If `detect` got the folders wrong, add `--frontend ./web` and/or `--backend ./api`.
 - Useful flags: `--slug <name>`, `--env KEY=VAL` (repeatable, backend env), `--build`
-  (force the frontend through its build step), `--env-file <file>`.
+  (force the frontend through its build step), `--backend-env-file <file>`.
+  Prefer `--backend-env-file` over the legacy `--env-file` alias: recent Node
+  versions consume the legacy flag before the CLI starts and can load backend
+  configuration into the CLI process. Direct legacy invocations require
+  `node -- /path/to/speculos-toolkit.js deploy --env-file <file>`.
 
 ### Who can see the deployed app
 

package/src/build.js

@@ -75,13 +75,21 @@ function setupNextConfig(dir, base, log) {
     const esm = pkgEsm;
     const file = path.join(dir, esm ? "next.config.mjs" : "next.config.js");
     const body = `{ ${over}, images: { unoptimized: true } }`;
-    fs.writeFileSync(file, esm ? `export default ${body};\n` : `module.exports = ${body};\n`);
+    fs.writeFileSync(file, esm ? `export default ${body};\n` : `module.exports = ${body};\n`, { flag: "wx" });
     log && log(`   next: wrote ${path.basename(file)} (basePath=${base.replace(/\/$/, "")})`);
-    return () => { try { fs.unlinkSync(file); } catch { /* ignore */ } };
+    return () => { try { fs.unlinkSync(file); } catch (e) { if (e.code !== "ENOENT") throw e; } };
   }
 
   // existing config -> back it up under a name Next won't load, write a wrapper
   const bak = path.join(dir, `next.config.__speculos_orig__.${found.ext}`);
+  // A previous interrupted build may have left the only copy of the user's
+  // config here. Never replace that recovery copy with our generated wrapper.
+  try {
+    fs.lstatSync(bak);
+    const e = new Error(`Cannot wrap ${path.basename(found.p)}: ${path.basename(bak)} already exists. Restore or move that backup before building again.`);
+    e.code = "NEXT_CONFIG_BACKUP";
+    throw e;
+  } catch (e) { if (e.code !== "ENOENT") throw e; }
   fs.renameSync(found.p, bak);
   const imp = `./next.config.__speculos_orig__.${found.ext}`;
   const esm = found.ext === "mjs" || found.ext === "ts" || (found.ext === "js" && pkgEsm);
@@ -92,9 +100,18 @@ function setupNextConfig(dir, base, log) {
   const wrapper = esm
     ? `import orig from ${JSON.stringify(imp)};\nexport default async (phase, ctx) => {\n${merge}};\n`
     : `const orig = require(${JSON.stringify(imp)});\nmodule.exports = async (phase, ctx) => {\n${merge}};\n`;
-  fs.writeFileSync(found.p, wrapper);
+  try { fs.writeFileSync(found.p, wrapper, { flag: "wx" }); }
+  catch (e) {
+    // setup itself happens before the build's finally block. Restore here too
+    // when the wrapper could not be written (for example, a full disk).
+    try { fs.renameSync(bak, found.p); }
+    catch (restoreError) { throw new AggregateError([e, restoreError], `Could not write or restore ${path.basename(found.p)}; original config is at ${bak}`); }
+    throw e;
+  }
   log && log(`   next: set basePath/assetPrefix=${base.replace(/\/$/, "")} (wrapped ${path.basename(found.p)})`);
-  return () => { try { fs.unlinkSync(found.p); fs.renameSync(bak, found.p); } catch { /* ignore */ } };
+  // Rename replaces the wrapper atomically and retains the original file mode.
+  // A failed restore must fail the deploy instead of silently changing source.
+  return () => fs.renameSync(bak, found.p);
 }
 
 // Frameworks prefix THEIR OWN bundled assets under the sub-path, but root-absolute
@@ -107,6 +124,7 @@ function setupNextConfig(dir, base, log) {
 function rewritePublicAssetPaths(outDir, base, log) {
   const noSlash = base.replace(/\/$/, "");
   const TEXT = /\.(html?|js|mjs|cjs|css|json|txt|xml|svg|webmanifest)$/i;
+  const root = fs.realpathSync(outDir);
 
   // 1) collect root-absolute paths of real asset files (skip _next/* — already
   //    prefixed by assetPrefix — and route .html files).
@@ -114,9 +132,19 @@ function rewritePublicAssetPaths(outDir, base, log) {
   (function walk(d, rel) {
     for (const name of fs.readdirSync(d)) {
       const abs = path.join(d, name), r = rel + "/" + name;
-      let st; try { st = fs.statSync(abs); } catch { continue; }
+      let st; try { st = fs.lstatSync(abs); } catch { continue; }
+      if (st.isSymbolicLink()) {
+        // The host supports symlinks to files inside the bundle. Include their
+        // public URLs, but never follow directory links or edit through links.
+        try {
+          const target = fs.realpathSync(abs), relTarget = path.relative(root, target);
+          if (relTarget === ".." || relTarget.startsWith(".." + path.sep) || path.isAbsolute(relTarget)) continue;
+          if (fs.statSync(target).isFile() && !/\.html?$/i.test(name)) assets.push(r);
+        } catch { /* dangling/cyclic link */ }
+        continue;
+      }
       if (st.isDirectory()) { if (r === "/_next") continue; walk(abs, r); }
-      else if (!/\.html?$/i.test(name)) assets.push(r);
+      else if (st.isFile() && !/\.html?$/i.test(name)) assets.push(r);
     }
   })(outDir, "");
   if (!assets.length) return;
@@ -132,9 +160,10 @@ function rewritePublicAssetPaths(outDir, base, log) {
   (function walk2(d) {
     for (const name of fs.readdirSync(d)) {
       const abs = path.join(d, name);
-      let st; try { st = fs.statSync(abs); } catch { continue; }
+      let st; try { st = fs.lstatSync(abs); } catch { continue; }
+      if (st.isSymbolicLink()) continue;
       if (st.isDirectory()) walk2(abs);
-      else if (TEXT.test(name)) {
+      else if (st.isFile() && TEXT.test(name)) {
         const s = fs.readFileSync(abs, "utf8");
         const n = s.replace(re, (_m, d1, a) => d1 + noSlash + a);
         if (n !== s) { fs.writeFileSync(abs, n); changed++; }
@@ -144,11 +173,28 @@ function rewritePublicAssetPaths(outDir, base, log) {
   log && log(`   rewrote root-absolute refs to ${assets.length} public asset(s) under the sub-path (${changed} file(s))`);
 }
 
-function findOutput(dir, preferred) {
-  const candidates = [preferred, "dist", "build", "out", ".output/public", ".svelte-kit/output/client", "_site"].filter(Boolean);
+function findOutput(dir, preferred, framework) {
+  // A requested/framework-specific output is authoritative. Falling back to a
+  // stale directory from a previous build can publish an entirely different app.
+  const candidates = preferred ? [preferred] : ["dist", "build", "out", ".output/public", ".svelte-kit/output/client", "_site"];
   for (const c of candidates) {
-    const p = path.join(dir, c);
-    try { if (fs.statSync(p).isDirectory() && fs.readdirSync(p).length) return p; } catch { /* next */ }
+    const p = path.resolve(dir, c);
+    try {
+      if (!fs.lstatSync(p).isDirectory() || !fs.readdirSync(p).length) continue;
+      if (framework !== "angular" || fs.existsSync(path.join(p, "index.html"))) return p;
+      // Angular's application builder writes dist/<project>/browser, while
+      // older builders write dist/<project>. Upload the browser entry directory,
+      // never the parent containing server bundles or multiple applications.
+      const nested = [path.join(p, "browser")];
+      for (const name of fs.readdirSync(p)) {
+        const child = path.join(p, name);
+        if (fs.lstatSync(child).isDirectory()) nested.push(child, path.join(child, "browser"));
+      }
+      const matches = [...new Set(nested)].filter((d) => {
+        try { return fs.lstatSync(d).isDirectory() && fs.lstatSync(path.join(d, "index.html")).isFile(); } catch { return false; }
+      });
+      if (matches.length === 1) return matches[0];
+    } catch { /* next */ }
   }
   return null;
 }
@@ -163,7 +209,7 @@ function runBuild({ dir, framework, buildCmd, base, backendUrl, connectorsUrl, c
   const installEnv = Object.assign({}, process.env); delete installEnv.NODE_ENV;
   const lock = fs.existsSync(path.join(dir, "package-lock.json"));
   log && log(`   installing dependencies…`);
-  run(npm, [lock ? "ci" : "install", "--no-audit", "--no-fund"], dir, installEnv);
+  run(npm, [lock ? "ci" : "install", "--include=dev", "--no-audit", "--no-fund"], dir, installEnv);
 
   // 2) build with base path + backend URL baked in
   const bc = baseConfig(framework, base);
@@ -181,7 +227,7 @@ function runBuild({ dir, framework, buildCmd, base, backendUrl, connectorsUrl, c
   }
 
   // 3) locate the output
-  const out = findOutput(dir, outputDir);
+  const out = findOutput(dir, outputDir, framework);
   if (!out) {
     if (framework === "next") { const e = new Error("Next.js produced no static export (out/). The app likely uses server features (SSR/API routes/server actions) that a static host can't run."); e.code = "NEXT_NOT_EXPORTED"; throw e; }
     const e = new Error(`build finished but no output dir found (looked for ${outputDir || "dist/build/out"})`); e.code = "BUILD_OUTPUT"; throw e;

package/src/client.js

@@ -8,22 +8,33 @@ const DEFAULT_API = process.env.SPECULOS_API || "https://unified-api.speculos.ai
 
 function base(opts) { return (opts.api || DEFAULT_API).replace(/\/$/, ""); }
 
+async function responseData(res) {
+  let data;
+  try { data = await res.json(); } catch { /* report a bounded, non-secret error below */ }
+  if (!res.ok) {
+    const error = data && typeof data === "object" ? data : {};
+    const e = new Error(typeof error.error === "string" ? error.error : `HTTP ${res.status}`);
+    e.code = error.code; e.status = res.status; e.jobId = error.jobId || null;
+    throw e;
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw Object.assign(new Error("the API returned an invalid JSON response"), { code: "BAD_RESPONSE", status: res.status });
+  }
+  return data;
+}
+
 async function post(url, body, token) {
   const headers = { "Content-Type": "application/json" };
   if (token) headers["Authorization"] = "Bearer " + token;
   const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
-  const data = await res.json().catch(() => ({}));
   // 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;
+  return responseData(res);
 }
 async function get(url, token, extra) {
   const headers = Object.assign({}, extra || {});
   if (token) headers["Authorization"] = "Bearer " + token;
   const res = await fetch(url, { headers });
-  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; }
-  return data;
+  return responseData(res);
 }
 
 // establish identity (mint on first call) + allocate the slug's stable uuid.
@@ -37,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

@@ -6,34 +6,52 @@
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
+const crypto = require("crypto");
+
+function credentialError(message, cause) {
+  return Object.assign(new Error(message), { code: "CREDENTIALS", 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() {
   const f = identityFile();
   let raw;
-  try { raw = fs.readFileSync(f, "utf8"); } catch { return null; } // no file yet
-  try { return JSON.parse(raw); }
-  catch {
-    // The file EXISTS but is corrupt/truncated. Don't silently treat it as
-    // "missing" — that would mint a fresh identity and overwrite it, orphaning
-    // the URLs it owned. Preserve it under .corrupt for recovery and warn.
-    try { fs.renameSync(f, f + ".corrupt"); process.stderr.write(`! ${f} was unreadable — backed up to ${f}.corrupt; minting a fresh identity.\n`); } catch { /* ignore */ }
-    return null;
+  try { raw = fs.readFileSync(f, "utf8"); }
+  catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw credentialError(`could not read ${f}; restore access before continuing`, e);
   }
+  let value;
+  try { value = JSON.parse(raw); } catch (e) { throw credentialError(`${f} contains invalid JSON; restore the identity file before continuing`, e); }
+  const hasMachine = value && (value.userId !== undefined || value.userKey !== undefined);
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+      (hasMachine && (typeof value.userId !== "string" || typeof value.userKey !== "string" || !/^[a-z0-9]{6,24}$/.test(value.userId) || !/^[A-Za-z0-9_-]{16,128}$/.test(value.userKey))) ||
+      (value.accountToken !== undefined && (typeof value.accountToken !== "string" || !value.accountToken.startsWith("spec_tok_")))) {
+    throw credentialError(`${f} contains an invalid identity; restore the identity file before continuing`);
+  }
+  return value;
 }
 // Merge-write so we never drop a field the other writer set (e.g. accountToken).
 // Atomic (tmp + rename) so a crash/full-disk mid-write can't truncate the file.
 function writeIdentity(obj) {
+  const tmp = identityFile() + `.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`;
   try {
-    fs.mkdirSync(identityDir(), { recursive: true });
-    const tmp = identityFile() + ".tmp";
-    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 });
+    fs.mkdirSync(identityDir(), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600, flag: "wx" });
     fs.renameSync(tmp, identityFile());
-  } catch { /* best effort */ }
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* no temporary file */ }
+    throw credentialError(`could not save ${identityFile()}; deployment ownership was not saved`, e);
+  }
 }
 function saveIdentity({ userId, userKey }) {
   const cur = loadIdentity() || {};
@@ -45,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 --------------------------------------------
@@ -57,10 +79,29 @@ function clearAccountToken() {
 function file(root) { return path.join(root, ".speculos.json"); }
 
 function load(root) {
-  try { return JSON.parse(fs.readFileSync(file(root), "utf8")); } catch { return null; }
+  let raw;
+  try { raw = fs.readFileSync(file(root), "utf8"); }
+  catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw Object.assign(new Error(`could not read ${file(root)}; restore access before continuing`), { code: "PROJECT_STATE", cause: e });
+  }
+  let value;
+  try { value = JSON.parse(raw); } catch { /* rejected below */ }
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+      typeof value.slug !== "string" || !/^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/.test(value.slug)) {
+    throw Object.assign(new Error(`${file(root)} contains an invalid project record; restore it before continuing`), { code: "PROJECT_STATE" });
+  }
+  return value;
 }
 function save(root, data) {
-  fs.writeFileSync(file(root), JSON.stringify(data, null, 2) + "\n");
+  const tmp = file(root) + `.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+    fs.renameSync(tmp, file(root));
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* no temporary file */ }
+    throw Object.assign(new Error(`could not save ${file(root)}; project ownership was not saved`), { code: "PROJECT_STATE", cause: e });
+  }
   ensureGitignored(root);
 }
 function remove(root) {
@@ -80,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/detect.js

@@ -30,6 +30,9 @@ function classifyFrontend(dir, opts = {}) {
     const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
     let outputDir = null, framework = "other";
     if (deps.next) { outputDir = "out"; framework = "next"; }            // next export; SSR not covered by a static host
+    // SvelteKit also depends on Vite, but its static adapter writes build/ and
+    // owns routing/base configuration. Treating it as plain Vite looks in dist/.
+    else if (deps["@sveltejs/kit"]) { outputDir = "build"; framework = "svelte"; }
     else if (deps.vite || deps["@vitejs/plugin-react"]) { outputDir = "dist"; framework = "vite"; }
     else if (deps["react-scripts"]) { outputDir = "build"; framework = "cra"; }
     else if (deps["@angular/core"]) { outputDir = "dist"; framework = "angular"; }

package/src/index.js

@@ -19,27 +19,38 @@ const VERSION = require("../package.json").version;
 
 function parseArgs(argv) {
   const opts = { env: {}, _: [] };
+  const bad = (message) => { opts.argError ||= message; };
   const valueFlags = {
     "--frontend": "frontend", "--backend": "backend", "--slug": "slug",
     "--start": "start", "--runtime": "runtime", "--output": "output",
-    "--api": "api", "--timeout": "timeout", "--env-file": "envFile",
+    "--api": "api", "--timeout": "timeout", "--backend-env-file": "envFile", "--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];
+    if (a === "--env" || valueFlags[a]) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) { bad(`${a} requires a value`); continue; }
+      i++;
+      if (a === "--env") {
+        const j = value.indexOf("=");
+        if (j < 1 || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value.slice(0, j))) bad("--env requires KEY=VALUE");
+        else opts.env[value.slice(0, j)] = value.slice(j + 1);
+      } else opts[valueFlags[a]] = value;
+    }
     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;
     // Who can open the deployed app. A new app is private unless told
     // otherwise; these also re-set an existing app on redeploy.
-    else if (a === "--private") opts.visibility = "private";
-    else if (a === "--org") opts.visibility = "org";
-    else if (a === "--public") opts.visibility = "public";
+    else if (["--private", "--org", "--public"].includes(a)) {
+      const visibility = a.slice(2);
+      if (opts.visibility && opts.visibility !== visibility) bad("choose only one of --private, --org, or --public");
+      opts.visibility = visibility;
+    }
     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".
@@ -48,17 +59,23 @@ function parseArgs(argv) {
     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 if (a.startsWith("-")) bad(`unknown option: ${a}`);
     else opts._.push(a);
   }
+  if (opts.timeout !== undefined && (!Number.isFinite(Number(opts.timeout)) || Number(opts.timeout) <= 0)) bad("--timeout must be a positive finite number of seconds");
+  if (opts.build && opts.static) bad("choose either --build or --static");
+  if (opts.runtime && !["node", "python", "bun"].includes(opts.runtime)) bad("--runtime must be node, python, or bun");
   if (opts.envFile) {
-    // Surface a bad --env-file instead of silently shipping the backend with no
+    // Surface a bad --backend-env-file instead of silently shipping the backend with no
     // env — a missing/unreadable file otherwise fails later as an opaque timeout.
     try {
+      const fromFile = {};
       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();
+        const j = t.indexOf("="); if (j > 0) fromFile[t.slice(0, j).trim()] = t.slice(j + 1).trim();
       }
-    } catch (e) { opts.envFileError = `could not read --env-file ${opts.envFile}: ${e.message}`; }
+      opts.env = { ...fromFile, ...opts.env };
+    } catch (e) { opts.envFileError = `could not read --backend-env-file ${opts.envFile}: ${e.message}`; }
   }
   return opts;
 }
@@ -79,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]
@@ -132,7 +149,10 @@ OPTIONS
   --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
+  --backend-env-file <file>
+                     load backend env vars from a file
+  --env-file <file>  legacy alias; prefer --backend-env-file because recent Node
+                     versions consume --env-file before the CLI starts
   --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
@@ -143,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
@@ -185,7 +206,30 @@ async function pollBackend(jobId, creds, opts) {
 }
 
 async function cmdDeploy(root, opts) {
+  if (opts.envFileError) { emit({ ok: false, error: opts.envFileError, code: "ENV_FILE" }); log(opts, `✗ ${opts.envFileError}`); return 1; }
   const d = detect(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));
+  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;
+  }
   // 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;
@@ -228,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 });
@@ -236,9 +280,8 @@ async function cmdDeploy(root, opts) {
   // ---- backend first (so its URL can be baked into the frontend) ----
   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})`);
-    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 {
@@ -247,10 +290,19 @@ async function cmdDeploy(root, opts) {
         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; }
+      // A refused backend can still ship its frontend. With no frontend there
+      // is no deployment to report as successful; keep the actionable refusal
+      // code and identify an existing backend without claiming it was deployed.
+      if (e.code === "BACKEND_DISABLED" || e.code === "TOO_MANY") {
+        log(opts, `↪ backend skipped — ${e.message}`);
+        if (!d.frontend) {
+          emit({ ok: false, slug: d.slug, status: "error", error: e.message, code: e.code,
+            urls: alloc.backendUrl ? { backend: alloc.backendUrl } : {},
+            ...(alloc.backendUrl ? { backendKept: true } : {}) });
+          return 1;
+        }
+        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.
@@ -307,25 +359,32 @@ 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 (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];
+    }
+    const excludeDirs = [...set];
+    if (rootStatic) {
       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 });
+    // 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); }
     catch (e) { emit({ ok: false, error: e.message, code: e.code || "FRONTEND" }); return 1; }
@@ -365,7 +424,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).
@@ -379,7 +438,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);
@@ -395,11 +454,27 @@ async function cmdTeardown(root, opts) {
 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();
+  let 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://unified.speculos.ai/?tab=deploys.`);
-    emit({ ok: true, alreadyLinked: true });
-    return 0;
+    try {
+      const who = await client.whoami(existing.accountToken, opts);
+      let reparented = false, previousAccount = null;
+      // The dashboard may have removed the machine since the last login, or a
+      // previous link request may have failed after the token was saved.
+      if (existing.userId && existing.userKey) {
+        const linked = await client.linkMachine(existing.accountToken, { userId: existing.userId, userKey: existing.userKey }, opts);
+        reparented = !!linked.reparented; previousAccount = linked.previousEmail || null;
+      }
+      if (reparented) process.stderr.write(`\n⚠ This device's deployments moved from ${previousAccount || "another account"} to ${who.email || "this account"}.\n`);
+      log(opts, `✓ this device is linked${who.email ? ` to ${who.email}` : ""}. Manage deployments at https://unified.speculos.ai/?tab=deploys.`);
+      emit({ ok: true, alreadyLinked: true, account: who.email || null, org: who.org || null, reparented, previousAccount });
+      return 0;
+    } catch (e) {
+      if (e.status !== 401) { emit({ ok: false, linked: false, error: e.message, code: e.code || "LOGIN" }); return 1; }
+      creds.clearAccountToken();
+      existing = creds.loadIdentity();
+      log(opts, "Your saved account token expired or was revoked; starting a new login.");
+    }
   }
 
   // Paste-a-token path: a user who already has an account (and a token from the
@@ -420,7 +495,10 @@ async function cmdLogin(opts) {
       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 */ }
+      } catch (e) {
+        emit({ ok: false, linked: false, error: `account verified, but this machine's apps could not be linked: ${e.message}. Run login again to retry.`, code: e.code || "LINK_MACHINE" });
+        return 1;
+      }
     }
     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://unified.speculos.ai/?tab=deploys.`);
@@ -460,7 +538,10 @@ async function cmdLogin(opts) {
     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 */ }
+    } catch (e) {
+      emit({ ok: false, linked: false, error: `account approved, but this machine's apps could not be linked: ${e.message}. Run login again to retry.`, code: e.code || "LINK_MACHINE" });
+      return 1;
+    }
   }
   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`);
@@ -470,19 +551,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;
-  } catch { /* revoke best-effort; still clear locally */ }
-  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 });
+    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 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;
+  }
+  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;
 }
 
@@ -544,6 +644,10 @@ async function cmdConnectors(opts) {
       emit({ ok: false, error: `couldn't read tool arguments: ${e.message}`, code: "BAD_ARGS" });
       return 2;
     }
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+      emit({ ok: false, error: "tool arguments must be a JSON object", 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; }
@@ -626,6 +730,7 @@ async function main(argv) {
   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; }
+  if (opts.argError) { emit({ ok: false, error: opts.argError, code: "BAD_ARGS" }); return 2; }
   const cmd = opts._[0] || "deploy";
   const root = process.cwd();
   try {

package/src/pack.js

@@ -20,7 +20,8 @@ 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",
+  ".npmrc", ".netrc", ".pgpass", ".ssh", ".aws", ".gcloud", ".speculos",
+  ".git-credentials", ".envrc", "*.env", "*.env.*", "id_ecdsa", "id_ecdsa.*", "id_dsa.*",
 ];
 // 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.
@@ -30,17 +31,28 @@ 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`);
+  // A private directory prevents collisions or symlink replacement of a
+  // predictable temporary archive, which may contain private backend source.
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "speculos-pack-"));
+  const tmp = path.join(tmpDir, "bundle.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(/\/+$/, ""));
+  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, ".");
-  execFileSync("tar", args, { stdio: ["ignore", "ignore", "pipe"] });
-  const buf = fs.readFileSync(tmp);
-  fs.unlinkSync(tmp);
-  return { base64: buf.toString("base64"), bytes: buf.length };
+  try {
+    execFileSync("tar", args, { stdio: ["ignore", "ignore", "pipe"] });
+    const buf = fs.readFileSync(tmp);
+    return { base64: buf.toString("base64"), bytes: buf.length };
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
 }
 
 module.exports = { packDir, BACKEND_DIRS };