speculos-toolkit 1.1.0 → 1.1.2

package/README.md

@@ -17,9 +17,21 @@ host never runs your build.
 
 > **Frontend hosting is free; every Speculos account includes one backend app free.** Sign in
 > once with `speculos-toolkit login` and a detected backend deploys too (sign up at
-> https://deploy.speculos.ai). Without an account the backend is skipped and the frontend still
+> https://unified.speculos.ai). Without an account the backend is skipped and the frontend still
 > ships free.
 
+## Who can see your app
+
+| | |
+|---|---|
+| **No account** | the app is **public** — anyone with the link. A private app checks who the visitor is when they open it, and there is no account to check against yet. |
+| **Signed in** | a new app is **private** by default. `--public` shares it, `--org` opens it to your org. |
+| **Already deployed anonymously?** | `speculos-toolkit login` links this machine and your existing apps come with it — then redeploy with `--private`, or flip it on the [dashboard](https://unified.speculos.ai/?tab=deploys). |
+
+`--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.
+
 ## What it prints
 
 The last line of stdout is a single JSON object:
@@ -67,6 +79,6 @@ speculos-toolkit teardown --slug <s>   remove a deployment
 --env KEY=VAL   --env-file <file>   --api <url>   --timeout <sec>   --json
 ```
 
-Docs: https://deploy.speculos.ai · Source: https://github.com/speculosai/agent_deploy_infra
+Docs: https://unified.speculos.ai · Source: https://github.com/speculosai/unified_platform
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speculos-toolkit",
-  "version": "1.1.0",
-  "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.",
+  "version": "1.1.2",
+  "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"
   },
@@ -28,9 +28,10 @@
     "speculos"
   ],
   "license": "MIT",
-  "homepage": "https://deploy.speculos.ai",
+  "homepage": "https://unified.speculos.ai",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/speculosai/agent_deploy_infra.git"
+    "url": "git+https://github.com/speculosai/unified_platform.git",
+    "directory": "deploy_plane/packages/cli"
   }
 }

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: speculos-toolkit
-description: Deploy the current project to a live public URL with Speculos, and build against the user's linked data sources (connectors). Builds the frontend locally, hosts it, wires its API calls to the deployed backend, and reports the URLs. Use when the user says "deploy", "ship it", "publish", "put it live", "get me a URL", "deploy to speculos", "deploy the frontend/backend", or wants an app built on their connected data (BigQuery, Postgres, Snowflake, Salesforce, ...). Handles plain static sites and Vite / Next / CRA / Angular / Svelte frontends; deploys Node/Python/Bun backends once the user has signed in (`speculos-toolkit login`) — one backend app is included with every Speculos account (frontend-only needs no account).
+description: Deploy the current project to a live URL with Speculos (public by default with no account; private once signed in), and build against the user's linked data sources (connectors). Builds the frontend locally, hosts it, wires its API calls to the deployed backend, and reports the URLs. Use when the user says "deploy", "ship it", "publish", "put it live", "get me a URL", "deploy to speculos", "deploy the frontend/backend", or wants an app built on their connected data (BigQuery, Postgres, Snowflake, Salesforce, ...). Handles plain static sites and Vite / Next / CRA / Angular / Svelte frontends; deploys Node/Python/Bun backends once the user has signed in (`speculos-toolkit login`) — one backend app is included with every Speculos account (frontend-only needs no account).
 ---
 
 # Speculos Toolkit
@@ -29,7 +29,7 @@ with `--frontend`/`--backend` in step 4 (or force a build dir to serve as-is wit
 ### If the project has a backend, ASK the user how to deploy (before you build)
 
 Frontends are **free** and need no account; **every Speculos account includes one backend
-app free** (sign in at https://deploy.speculos.ai). So when `detect` finds a backend, DON'T silently
+app free** (sign in at https://unified.speculos.ai). So when `detect` finds a backend, DON'T silently
 skip it — ask the user with your question UI (e.g. AskUserQuestion). Tailor the “what won't
 work” line to THIS app (a counter button, a form, login, saved data…). For example:
 
@@ -146,9 +146,12 @@ npx -y speculos-toolkit@latest connectors list --json
 The last stdout line is `{ ok, brokerUrl, connectors: [{ alias, name, kind, accountIdentifier, tools: [...] }] }`.
 
 - `ok:false` + `code:"NO_TOKEN"` → the device isn't logged in; run `login` (step 4) first.
+- `ok:false` + `code:"LOGIN_REQUIRED"` on a deploy → `--private`/`--org` was asked for on a
+  machine with no account. Nothing was published. Either run `login` and deploy again, or
+  drop the flag (the app ships public) and lock it down after linking.
 - `ok: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://deploy.speculos.ai/dashboard**, then **re-run the list** —
+  admin for access) at **https://unified.speculos.ai/?tab=deploys**, then **re-run the list** —
   access is resolved server-side on every call, so a source linked or granted seconds ago
   shows up immediately with no re-login and no session restart. Never block a deploy on this.
 - A `403 NO_ACCESS` on execute means an org admin hasn't granted that source to this user —
@@ -289,6 +292,23 @@ Builds run locally (this machine already has the toolchain); only static output
 - Useful flags: `--slug <name>`, `--env KEY=VAL` (repeatable, backend env), `--build`
   (force the frontend through its build step), `--env-file <file>`.
 
+### Who can see the deployed app
+
+- **No account -> the app is PUBLIC**, anyone with the link. That is the only
+  thing it can be: a private app checks who the visitor is when they open it,
+  and there is no account to check against yet. Frontend-only deploys need no
+  account and this is the normal path.
+- **Once the machine is linked** (`speculos-toolkit login`), a NEW app is
+  **private by default**. Pass `--public` to share it, `--org` for the whole org.
+- `--private` / `--org` from an UNLINKED machine **fails the deploy** with
+  `code:"LOGIN_REQUIRED"` before anything is published. It does not quietly
+  deploy something public that the user asked to be private. Recovery: run
+  `speculos-toolkit login`, then deploy again.
+- Already deployed anonymously and now want it private? `speculos-toolkit login`
+  links this machine and its existing apps come with it — then redeploy with
+  `--private`, or flip it at https://unified.speculos.ai/?tab=deploys.
+- A redeploy never changes the visibility of an app that is already live.
+
 The **last line of stdout is one JSON object**:
 ```json
 { "ok": true, "userId": "...", "urls": { "frontend": "https://user-deployed.speculos.ai/...", "backend": "https://...daytonaproxy01.net" } }
@@ -300,16 +320,16 @@ On `ok:false`, read `error`/`logTail`, fix the cause **once**, and re-run. Do no
 > limit (one is included; more come with Team plans). In both cases the deploy still **ships
 > the frontend** and returns `ok:true` with a `backendNote` — so the user already has a live
 > URL. To ship the backend: for `BACKEND_DISABLED`, sign in; for `TOO_MANY`, take an app
-> offline at https://deploy.speculos.ai/dashboard, redeploy an existing backend app, or talk
+> offline at https://unified.speculos.ai/?tab=deploys, redeploy an existing backend app, or talk
 > to our team at https://calendar.app.google/VMGTvK3FmyDMAsix6 about more capacity. Always write the URL as
-> **https://deploy.speculos.ai** — never `speculos.ai`. Don't retry the backend; once signed
+> **https://unified.speculos.ai** — never `speculos.ai`. Don't retry the backend; once signed
 > in / under the limit, re-running `deploy` ships it. Redeploying an app that already has a
 > backend never counts against the limit (it reuses its sandbox).
 
 ## 5. Report + verify
 
 - Give the user `urls.frontend` (and `urls.backend` if deployed). They can manage their
-  published apps and take them offline anytime at https://deploy.speculos.ai/dashboard. The public URL is
+  published apps and take them offline anytime at https://unified.speculos.ai/?tab=deploys. The public URL is
   `user-deployed.speculos.ai/<username>/<app-slug>/`, and BOTH segments are renameable there:
   "Edit link" changes an app's slug (the second segment), and the account's "your link name"
   changes the first segment (default a random id) for every app on that device. Accounts on
@@ -329,10 +349,10 @@ On `ok:false`, read `error`/`logTail`, fix the cause **once**, and re-run. Do no
 ## Notes
 
 - Until the user signs in, the backend is skipped (frontend-only). Run `speculos-toolkit login`,
-  or point users to https://deploy.speculos.ai.
+  or point users to https://unified.speculos.ai.
 - Permission is granted once at skill install, so the deploy command runs without prompting.
 - To remove a deployment: `npx -y speculos-toolkit@latest teardown --slug <slug>` (or use the
-  dashboard at https://deploy.speculos.ai/dashboard).
+  dashboard at https://unified.speculos.ai/?tab=deploys).
 - **Already have this skill from before connectors existed?** Re-run
   `npx -y speculos-toolkit@latest install-skill` to refresh it (safe to run repeatedly — it
   overwrites the skill file and re-grants the command). The CLI itself is always current

package/src/index.js

@@ -87,11 +87,22 @@ USAGE
                                       run one connector tool through the broker
                                       (read-only discovery, live queries)
 
-Frontends are hosted FREE at user-deployed.speculos.ai/<userId>/<slugUuid>.
-A NEW app is PRIVATE — deploy with --public (or flip it on the dashboard) to
-share it. A redeploy never changes the visibility of an app that is already live.
+Frontends are hosted FREE at user-deployed.speculos.ai/<userId>/<slugUuid>,
+with no account and no sign-up.
+
+WHO CAN SEE IT
+  No account   the app is PUBLIC — anyone with the link. That is the only thing
+               it can be: a private app checks who you are when someone opens
+               it, and there is no account to check against yet.
+  Linked       a NEW app is PRIVATE by default. --public to share it.
+  Already
+  deployed?    run 'speculos-toolkit login' to link this machine — your existing
+               apps come with it — then deploy again with --private, or flip it
+               on https://unified.speculos.ai/?tab=deploys.
+
+A redeploy never changes the visibility of an app that is already live.
 Every Speculos account includes one backend app free (an isolated sandbox per app) —
-sign up at https://deploy.speculos.ai and run 'speculos-toolkit login'.
+sign up at https://unified.speculos.ai and run 'speculos-toolkit login'.
 Without an account a detected backend is skipped (frontend still ships free).
 
 OPTIONS
@@ -103,8 +114,9 @@ OPTIONS
   --build            force the frontend through its build step (vs serve as static)
   --static           serve the frontend dir as-is even if it has a build script
   --no-backend       frontend-only: skip backend even if one is detected
-  --private          only you can open the deployed app (DEFAULT for a new app)
-  --org              anyone in your org can open it
+  --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)
   --public           anyone with the link can open it, no sign-in
   --no-frontend      backend-only: skip frontend even if one is detected
   --output <dir>     frontend build output dir (dist/build/out — auto-detected)
@@ -132,6 +144,11 @@ VITE_API_URL / NEXT_PUBLIC_API_URL / API_URL (build) or window.SPECULOS_API_URL.
 
 async function cmdDetect(root, opts) {
   const d = detect(root, opts);
+  // `detect` derives a slug from the directory name; a project that has already
+  // been deployed has its real slug in .speculos.json, and deploy honours it.
+  // Reporting the derived one made `detect` disagree with what `deploy` would do.
+  const saved = creds.load(root);
+  if (!opts.slug && saved && saved.slug) d.slug = saved.slug;
   if (!opts.json) {
     log(opts, `slug: ${d.slug}`);
     log(opts, `frontend: ${d.frontend ? `${path.relative(root, d.frontend.dir) || "."} (${d.frontend.kind}${d.frontend.framework ? "/" + d.frontend.framework : ""})` : "none"}`);
@@ -172,7 +189,7 @@ async function cmdDeploy(root, opts) {
     d.backend = null;
   }
   if (!d.frontend && !d.backend) {
-    if (hadBackend) { emit({ ok: false, error: `nothing to deploy: Speculos hosts frontends free, but this project is backend-only — sign in to deploy the backend (every Speculos account includes one free backend app). Run \`speculos-toolkit login\` (https://deploy.speculos.ai), or add a frontend.`, code: "BETA_BACKEND_ONLY" }); return 2; }
+    if (hadBackend) { emit({ ok: false, error: `nothing to deploy: Speculos hosts frontends free, but this project is backend-only — sign in to deploy the backend (every Speculos account includes one free backend app). Run \`speculos-toolkit login\` (https://unified.speculos.ai), or add a frontend.`, code: "BETA_BACKEND_ONLY" }); return 2; }
     emit({ ok: false, error: `could not detect a frontend in ${root}. Pass --frontend <dir>.`, code: "DETECT" });
     return 2;
   }
@@ -187,7 +204,13 @@ async function cmdDeploy(root, opts) {
   let alloc;
   try {
     alloc = await client.allocate({ userId: identity && identity.userId, userKey: identity && identity.userKey, slug: d.slug, visibility: opts.visibility }, opts);
-  } catch (e) { emit({ ok: false, error: e.message, code: e.code || "ALLOCATE" }); return 1; }
+  } 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.
+    log(opts, `\u2717 ${e.message}`);
+    emit({ ok: false, error: e.message, code: e.code || "ALLOCATE" });
+    return 1;
+  }
   if (alloc.userKey) { // freshly minted on the server
     identity = { userId: alloc.userId, userKey: alloc.userKey };
     creds.saveIdentity(identity);
@@ -287,6 +310,7 @@ async function cmdDeploy(root, opts) {
   if (alloc && alloc.visibilityNote) log(opts, `  note: ${alloc.visibilityNote}`);
   const out = { ok: true, slug: d.slug, userId, urls };
   if (visibility) out.visibility = visibility;
+  if (alloc && alloc.visibilityNote) out.visibilityNote = alloc.visibilityNote;
   if (backendNote) out.backendNote = backendNote;
   emit({ ...out });
   return 0;
@@ -325,7 +349,7 @@ async function cmdLogin(opts) {
   // to a different account, incl. moving a personal-linked device onto an org).
   const 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://deploy.speculos.ai/dashboard.`);
+    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;
   }
@@ -351,7 +375,7 @@ async function cmdLogin(opts) {
       } catch { /* links on next deploy via the token */ }
     }
     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://deploy.speculos.ai/dashboard.`);
+    log(opts, `✓ this device is linked${who.email ? ` to ${who.email}` : ""}${who.org ? ` (org: ${who.org})` : ""} — manage at https://unified.speculos.ai/?tab=deploys.`);
     emit({ ok: true, linked: true, account: who.email || null, org: who.org || null, reparented, previousAccount: previousEmail });
     return 0;
   }
@@ -365,7 +389,7 @@ async function cmdLogin(opts) {
   // And on stderr (even in --json) for a human watching.
   process.stderr.write(`\nLink this machine to your Speculos account to enable backend hosting:\n`);
   process.stderr.write(`\n  1. Open:  ${start.url}\n`);
-  process.stderr.write(`     (or go to https://deploy.speculos.ai/link and enter code ${start.code})\n`);
+  process.stderr.write(`     (or go to https://unified.speculos.ai/link and enter code ${start.code})\n`);
   process.stderr.write(`  2. Sign in / sign up, then click Approve.\n\n`);
   process.stderr.write(`Waiting for approval…\n`);
 
@@ -393,7 +417,7 @@ async function cmdLogin(opts) {
   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`);
   }
-  log(opts, `✓ this device is linked${approvedEmail ? ` to ${approvedEmail}` : ""} — manage your deployments at https://deploy.speculos.ai/dashboard.`);
+  log(opts, `✓ this device is linked${approvedEmail ? ` to ${approvedEmail}` : ""} — manage your deployments at https://unified.speculos.ai/?tab=deploys.`);
   emit({ ok: true, linked, account: approvedEmail, reparented, previousAccount: previousEmail });
   return 0;
 }
@@ -433,7 +457,7 @@ async function cmdConnectors(opts) {
   const identity = creds.loadIdentity();
   const token = identity && identity.accountToken;
   if (!token) {
-    emit({ ok: false, code: "NO_TOKEN", error: "not signed in — run `npx -y speculos-toolkit@latest login`, then link data sources at https://deploy.speculos.ai/dashboard" });
+    emit({ ok: false, code: "NO_TOKEN", error: "not signed in — run `npx -y speculos-toolkit@latest login`, then link data sources at https://unified.speculos.ai/?tab=deploys" });
     return 1;
   }
   const sub = opts._[1] || "list";
@@ -444,8 +468,14 @@ async function cmdConnectors(opts) {
     catch (e) { emit({ ok: false, error: e.message, code: e.code || "CONNECTORS" }); return 1; }
     const conns = r.connectors || [];
     if (!opts.json) {
-      if (!conns.length) log(opts, "no data sources linked — link one at https://deploy.speculos.ai/dashboard");
-      for (const c of conns) log(opts, `  ${c.alias}  (${c.name}${c.accountIdentifier ? " · " + c.accountIdentifier : ""}) — ${(c.tools || []).length} tools`);
+      if (!conns.length) log(opts, "no data sources linked — link one at https://unified.speculos.ai/?tab=deploys");
+      for (const c of conns) {
+        // Say which product a source came from: the deploy plane and the
+        // Cloud console hold separate connections, often to the same SaaS,
+        // and running a tool against the wrong one is silent and wrong.
+        const scope = c.orgWide ? " · org" : "";
+        log(opts, `  ${c.alias}  (${c.name}${c.accountIdentifier ? " · " + c.accountIdentifier : ""}${scope}) — ${(c.tools || []).length} tools`);
+      }
     }
     emit({ ok: true, brokerUrl: client.base(opts) + "/api/connectors", connectors: conns });
     return 0;