speculos-toolkit 1.1.0 → 1.1.1

package/README.md

@@ -20,6 +20,18 @@ host never runs your build.
 > https://deploy.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://deploy.speculos.ai/dashboard). |
+
+`--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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speculos-toolkit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "The Speculos toolkit for coding agents — deploy any frontend/backend to a live URL and build against your linked data connectors (BigQuery, Postgres, Snowflake, Salesforce, …). Built for Claude Code, Codex, Cursor, and friends.",
   "bin": {
     "speculos-toolkit": "bin/speculos-toolkit.js"

package/skill/SKILL.md

@@ -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
@@ -146,6 +146,9 @@ 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** —
@@ -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://deploy.speculos.ai/dashboard.
+- 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" } }

package/src/index.js

@@ -87,9 +87,20 @@ 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://deploy.speculos.ai/dashboard.
+
+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'.
 Without an account a detected backend is skipped (frontend still ships free).
@@ -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)
@@ -187,7 +199,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);