speculos-toolkit 1.2.4 → 1.2.6

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,10 @@ 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.
 
+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.
+
 ## Conventions
 
 - **Backend** listens on `process.env.PORT`, binds `0.0.0.0`. Node or Python.
@@ -82,13 +87,19 @@ 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.4",
+  "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.",
   "bin": {
     "speculos-toolkit": "bin/speculos-toolkit.js"
   },
   "type": "commonjs",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=18"
   },

package/skill/SKILL.md

@@ -156,7 +156,8 @@ The last stdout line is `{ ok, brokerUrl, connectors: [{ alias, name, kind, acco
 - **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.
+  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** —
@@ -303,7 +304,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.

package/src/creds.js

@@ -6,6 +6,11 @@
 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 --------------------------------------------
 
@@ -15,25 +20,33 @@ 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() || {};
@@ -57,10 +70,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) {

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;
 }
@@ -121,7 +138,8 @@ OPTIONS
   --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)
+                     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)
@@ -131,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
@@ -184,7 +205,15 @@ 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));
+  if (d.frontend && d.frontend.kind === "static" && backendSourceDir && path.resolve(d.frontend.dir) === path.resolve(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;
@@ -235,7 +264,6 @@ 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 });
     log(opts, `→ deploying backend (${Math.round(backendTar.bytes / 1024)} KB) to an isolated sandbox`);
@@ -246,10 +274,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.
@@ -280,11 +317,13 @@ async function cmdDeploy(root, opts) {
   // at the backend it already has, which allocate reports. Without this, the
   // rebuilt bundle and the regenerated speculos-env.js both said "no backend"
   // and a live app started 404ing its own API. --unset-backend is the explicit
-  // way to clear it (the backend sandbox itself stays up; `teardown` removes it).
+  // 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) — the backend itself stays up`);
+    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;
@@ -314,15 +353,15 @@ async function cmdDeploy(root, opts) {
     let excludeDirs = [];
     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); }
+      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];
       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; }
@@ -392,11 +431,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
@@ -417,7 +472,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.`);
@@ -457,7 +515,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`);
@@ -476,7 +537,12 @@ async function cmdLogout(opts) {
   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 */ }
+  } catch (e) {
+    // Keep the token so a retry can revoke it and unlink the machine. 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 });
@@ -541,6 +607,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; }
@@ -623,6 +693,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,23 @@ 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 || [])) args.push("--exclude=./" + String(e).replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, ""));
   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 };