@newly/cli 0.1.1 → 0.1.27

package/README.md

@@ -14,10 +14,12 @@ Installs the `newly` binary. Requires **Node ≥ 20**.
 
 ```bash
 newly login              # authenticate in the browser
-newly pull <project-id>  # download project code + link this directory
+newly create my-api      # create and deploy production, then select it
+newly env create checkout-fix # fork production into a new environment
+newly env use checkout-fix # select it for this working directory
 # edit code…
-newly deploy             # deploy to dev
-newly deploy --env prod  # ship to prod
+newly deploy             # deploy all declared services to the selected environment
+newly deploy api         # deploy only the api service
 newly services list      # inspect backend services
 newly email status       # inspect Newly Email setup
 ```
@@ -40,16 +42,15 @@ Most commands target the project linked to the current directory, so you don't p
 - `newly link <project-id>` links a directory without downloading anything.
 - Pass `--project <id>` to any command to override the link.
 
-## Dev vs prod deploys
+## Selected-environment deploys
 
-| | Source | Notes |
-|---|---|---|
-| `newly deploy` (dev) | **your local code** | Fast inner loop. Ephemeral — overwritten the next time the project is built on the Newly platform. Not a rollback target. |
-| `newly deploy --env prod` | **project code at HEAD** | Runs server-side, ignores local edits. Push your changes into the project first. |
+`newly deploy` always uses the environment selected by `newly env use <name>`.
+It never falls back to dev or production and has no `--env` option. Deployments
+use local backend code and are immutable attempts; a failed attempt leaves the
+previous active deployment and route untouched.
 
-Prod actions prompt for confirmation. Pass `--yes` to skip it in scripts.
-
-> Only projects on the Newly backend stack are CLI-deployable. Run `newly stack` to check. Other projects must be deployed from the Newly web app.
+Service names are positional. With no names, every service in
+`backend/newly.services.json` is deployed.
 
 ## Commands
 
@@ -59,8 +60,11 @@ Download the project working tree (app + backend) into the current directory and
 - `--force` — overwrite a non-empty directory (discards local changes).
 
 ### `newly create [name]`
-Create a new backend-only project here, scaffold `backend/`, and link the directory. Provisions the dev backend by default.
-- `--no-provision` — create without provisioning.
+Create a project, provision its production PostgreSQL primary and standby,
+scaffold `backend/`, select production, and deploy the starter Worker.
+- `--no-deploy` — provision and select production without deploying the starter Worker.
+
+Production starts with 2 GiB of storage.
 
 Run in a directory with no `backend/` and no existing link.
 
@@ -76,13 +80,9 @@ Show which backend stack the project uses and whether it's CLI-deployable.
 - `--project <id>`
 
 ### `newly deploy`
-Provision the backend if needed, then deploy.
-- `--env <dev|prod>` (default `dev`)
-- `--region <region>` — region for first-time dev provisioning (default `auto`)
+Deploy local backend services to the selected environment.
 - `--project <id>`
-- `--service <names>` — comma-separated service names from `backend/newly.services.json`
-- `--git-sha <sha>` — prod git revision to deploy (default `HEAD`)
-- `--yes` — skip the prod confirmation prompt
+- `[services...]` — optional service names from `backend/newly.services.json`
 
 ### `newly services list`
 List backend services from `backend/newly.services.json`.
@@ -171,3 +171,4 @@ newly-dev deploy
 - `~/.newly/credentials` — session token (mode `600`). Override the directory with `NEWLY_HOME`.
 - `~/.newly-dev/credentials` — `newly-dev` session token. Override the directory with `NEWLY_DEV_HOME`.
 - `.newly/project.json` — per-directory project link.
+- `.newly/environment.json` — per-directory selected environment; ignored by Git.

package/README.runcloud.md

@@ -0,0 +1,253 @@
+# runcloud
+
+Create and control **remote mobile simulators** and **cloud sandboxes** from your terminal.
+
+- **Simulators** — boot real iOS simulators and Android emulators in the cloud, install your app, open deep links, and tunnel a local dev server into them.
+- **Sandboxes** — start a fresh, isolated Linux environment in seconds, run commands in it, snapshot a ready setup, and restore it later as a warm start.
+
+Everything the CLI creates also shows up at [run.cloud/dashboard](https://run.cloud/dashboard):
+
+![The run.cloud dashboard: fleet totals, reserved vCPU and memory, billed uptime, estimated spend, and recent sandboxes.](https://run.cloud/media/dashboard.png)
+
+## Install
+
+```bash
+npm i -g runcloud
+```
+
+Installs the `runcloud` binary. Requires **Node ≥ 20**.
+
+Or take the standalone binary — no Node, no sudo. It installs to `~/.run-cloud/bin`
+and hands the terminal to `runcloud login` when it finishes:
+
+```bash
+curl -fsSL https://run.cloud/install | sh
+```
+
+## Log in
+
+```bash
+runcloud login   # sign in with email, Google, or GitHub; stores a token in ~/.run-cloud/credentials
+runcloud logout  # delete the stored credential
+runcloud account        # show your entitlement and metered balance
+```
+
+Email signs you in without leaving the terminal. Google and GitHub open a browser and
+show a short code to confirm, so login works over SSH and on headless machines too —
+pick with `--email`, `--google`, `--github`, or `--browser` to skip the prompt.
+
+The token expires — re-run `runcloud login` when a command reports you're logged out.
+
+## Remote simulators
+
+```bash
+# iOS
+runcloud ios create --model iphone --install ./MyApp.app   # boot a simulator and install an app
+runcloud ios list                                          # list active sessions
+runcloud ios get <id>                                      # inspect a session (viewer URL, status)
+runcloud ios open-url myapp://path --id <id>               # open a URL or deep link
+runcloud ios delete <id>                                   # release the session
+
+# Android works the same under `runcloud android …`
+runcloud android create --model pixel
+```
+
+Useful `create` flags: `--region`, `--display-name`, `--inactivity-timeout 3m`,
+`--hard-timeout 1h`, `--install-asset <name-or-id>`, `--rm` (release when the
+command exits), `--json`.
+
+### Tunnel a local dev server into a simulator
+
+```bash
+runcloud ios tunnel <id> --local-port 8081   # expose local Metro to the remote session
+runcloud ios tunnel-status
+```
+
+### Reusable app assets
+
+Upload an app once, install it into as many sessions as you like:
+
+```bash
+runcloud asset push ./MyApp.app --name my-app
+runcloud asset list
+runcloud ios create --install-asset my-app
+runcloud asset pull <id> --output ./MyApp.app
+runcloud asset delete <id>
+```
+
+## Sandboxes
+
+```bash
+runcloud sandbox create                          # start a sandbox (default image: runcloud/agent-base)
+runcloud sandbox create --cpu 0.5 --memory 1024  # allocate CPU cores and memory in MiB
+runcloud sandbox create --disk 80                # request an 80 GiB root filesystem
+runcloud sandbox exec <id> npm run build         # run a command inside it
+runcloud sandbox shell <id>                      # interactive shell, streamed over the API
+runcloud sandbox logs <id> --lines 200           # tail its logs
+runcloud sandbox metrics <id> --range 24h        # CPU, memory, network, and disk usage
+runcloud sandbox pause <id>                      # park it; `resume` brings it back warm
+runcloud sandbox list
+runcloud sandbox rm <id>                          # destroy it
+```
+
+### Browser desktops and computer use
+
+Create a desktop sandbox, then open its short-lived signed noVNC URL:
+
+```bash
+SANDBOX_ID=$(runcloud sandbox create --image runcloud/desktop --json | jq -r '.id')
+
+runcloud sandbox desktop "$SANDBOX_ID"               # open the desktop in a browser
+runcloud sandbox desktop "$SANDBOX_ID" --url         # print the signed URL
+runcloud sandbox desktop "$SANDBOX_ID" --view-only   # open without keyboard or pointer input
+```
+
+Agents can capture and control the same desktop:
+
+```bash
+runcloud sandbox screenshot "$SANDBOX_ID" --output screen.png
+runcloud sandbox click "$SANDBOX_ID" 420 300
+runcloud sandbox type "$SANDBOX_ID" "hello world"
+runcloud sandbox key "$SANDBOX_ID" "ctrl+l"
+```
+
+Treat a signed desktop URL as a secret. It grants temporary access to that
+desktop without asking the browser to send your CLI credential.
+
+### Lifetime, pausing, and a public hostname
+
+Two clocks stop a sandbox, and the first one bites after five minutes:
+
+- `--timeout <seconds>` — maximum lifetime, wall-clock from boot or the last
+  resume, busy or not. **Defaults to 300**; `0` removes the limit.
+- `--idle-pause <seconds>` — pause after that much inactivity.
+
+Both *pause* rather than destroy. `runcloud sandbox resume <id>` brings a
+sandbox back warm with its filesystem intact, and a paused sandbox is destroyed
+after 48 hours. `--persistent` stops both clocks; `--expose` implies it and
+publishes a guest port at a stable `<name>-box.run.cloud` hostname.
+
+```bash
+runcloud sandbox create --timeout 3600                      # an hour of wall clock, then pause
+runcloud sandbox create --idle-pause 600                    # pause after 10 idle minutes
+runcloud sandbox create --name my-project --persistent      # never pauses
+runcloud sandbox create --name my-project --expose 3000     # persistent + https://my-project-box.run.cloud
+runcloud sandbox expose <id> --port 8080                    # expose later, or move the published port
+runcloud sandbox get <id>                                   # inspect, including the hostname
+```
+
+The CLI only sets the timer at create time. To extend it on a running sandbox —
+what a long job or a live agent session needs — call
+`sandbox.setTimeout(id, seconds)` from [`@run-cloud/sdk`](https://www.npmjs.com/package/@run-cloud/sdk).
+
+`--expose` needs `--name` — that name is the hostname prefix, and it is fixed
+once minted.
+
+Exposed sandboxes support SSH, file transfer, VS Code, and custom domains:
+
+```bash
+runcloud sandbox ssh my-project                  # shell over authenticated SSH (no public port 22)
+runcloud sandbox cp my-project ./f :/workspace/f # scp; prefix the remote path with :
+runcloud sandbox code my-project                 # VS Code Remote SSH
+runcloud sandbox domain add my-project app.example.com
+```
+
+`runcloud box …` from earlier releases keeps working as a deprecated alias for
+these commands.
+
+### Snapshot warm-start
+
+Freeze a "repo + deps ready" sandbox, then fork a new one from it in a fraction of a second instead of re-cloning and re-installing:
+
+```bash
+runcloud sandbox snapshot create <id> --label warm   # snapshot a sandbox
+runcloud sandbox snapshot list --sandbox <id>
+runcloud sandbox restore <snapshot-id> --name fork   # fork a NEW sandbox from the snapshot
+runcloud sandbox snapshot rm <snapshot-id>
+```
+
+### Secrets
+
+Store secrets in a named group, then attach the group when you create a sandbox:
+
+```bash
+runcloud secret-group create aws --key AWS_ACCESS_KEY_ID --key AWS_SECRET_ACCESS_KEY
+runcloud secret-group create prod --from-dotenv ./.env.production
+runcloud secret-group list
+runcloud secret-group show aws                              # names only, never values
+runcloud secrets set DATABASE_URL --group prod              # hidden prompt, or --stdin
+runcloud secrets set-file sa.json --group prod --path .config/gcloud/sa.json --from-file ./sa.json
+
+runcloud sandbox create --secret-group prod --env LOG_LEVEL=debug
+runcloud sandbox create --secret prod/DATABASE_URL          # one secret out of a group
+runcloud sandbox create --no-secrets                        # state explicitly that it holds none
+```
+
+`--secret-group`, `--secret`, and `--env` are repeatable and **order matters** —
+a later one wins a name collision, and `--env` is applied last.
+
+`runcloud sandbox secrets <id>` re-attaches on a running sandbox. It *replaces*
+the whole set rather than merging, which is how a credential gets revoked:
+passing no flags at all takes them all back.
+
+A value can never be passed as a command argument — it would land in your shell
+history, in `ps` output, and in CI logs. Use a hidden prompt, a file, or stdin.
+
+## Custom images
+
+A sandbox boots an OCI image. Register your own once, then create sandboxes from
+it:
+
+```bash
+runcloud image create --ref python:3.12-slim   # registers, and waits for the build
+runcloud image list
+runcloud image refresh python:3.12-slim        # re-pin the tag to its current upstream digest
+runcloud sandbox create --image python:3.12-slim
+```
+
+Built in: `runcloud/agent-base` (the default), `runcloud/desktop`, and
+`runcloud/box` (the default with `--expose`).
+
+## Demos
+
+```bash
+runcloud demo run --open                         # run the default mosaic from any directory
+runcloud demo run live-camera-relay --open       # run the camera relay from any directory
+runcloud demo init eight-device-mosaic           # optionally scaffold a standalone project
+```
+
+Bundled demos: `eight-device-mosaic`, `live-camera-relay`.
+
+## Onboarding sample apps
+
+Download checksum-verified apps that are ready for the remote runtimes:
+
+```bash
+runcloud sample download ios
+runcloud ios create --install ./run-cloud-sample-ios.app.tar.gz
+
+runcloud sample download android
+runcloud android create --install ./run-cloud-sample-android.apk
+```
+
+## AI coding agents
+
+```bash
+runcloud skills install                    # install run.cloud skills into this project
+runcloud skills install --agents claude --scope global
+```
+
+Supported agents: `claude`, `codex`, `cursor`.
+
+Every command accepts `--json` for scripting. For programmatic use from
+TypeScript, see [`@run-cloud/sdk`](https://www.npmjs.com/package/@run-cloud/sdk).
+
+## Credentials & environment
+
+- `~/.run-cloud/credentials` — your session token (mode `600`).
+
+| Env var | Effect |
+|---|---|
+| `RUN_CLOUD_API_TOKEN` / `RUN_CLOUD_API_KEY` | Use this token instead of the stored credential (CI / headless). |
+| `RUN_CLOUD_API_URL` | Override the control-plane API base URL. |
+| `RUN_CLOUD_APP_URL` | Override the web app URL used for browser login (default `https://run.cloud`). |

package/dist/api.js

@@ -1,12 +1,31 @@
+import { loginCommandName } from './config.js';
 export class ApiError extends Error {
     status;
     detail;
-    constructor(status, detail) {
+    path;
+    constructor(status, detail, path) {
         super(`API ${status}: ${detail}`);
         this.status = status;
         this.detail = detail;
+        this.path = path;
     }
 }
+function parsedErrorDetail(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const detail = parsed.detail ?? parsed.error ?? parsed.message;
+        if (typeof detail === 'string')
+            return detail;
+        if (detail !== undefined)
+            return JSON.stringify(detail);
+    }
+    catch {
+    }
+    if (/<(?:!doctype|html)\b/i.test(body)) {
+        return 'the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer command';
+    }
+    return body;
+}
 export class ApiClient {
     baseUrl;
     token;
@@ -24,13 +43,8 @@ export class ApiClient {
             body: body !== undefined ? JSON.stringify(body) : undefined,
         });
         if (!res.ok) {
-            let detail = await res.text();
-            try {
-                detail = JSON.parse(detail).detail ?? detail;
-            }
-            catch {
-            }
-            throw new ApiError(res.status, detail);
+            const detail = parsedErrorDetail(await res.text());
+            throw new ApiError(res.status, detail, path);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -38,9 +52,33 @@ export class ApiClient {
     get(path) {
         return this.request('GET', path);
     }
+    async getText(path) {
+        const response = await this.request('GET', path);
+        return response.text();
+    }
     post(path, body) {
         return this.request('POST', path, body);
     }
+    async postWithHeaders(path, body, headers) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+                ...headers,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const detail = parsedErrorDetail(await res.text());
+            throw new ApiError(res.status, detail, path);
+        }
+        const contentType = res.headers.get('content-type') ?? '';
+        return contentType.includes('application/json') ? res.json() : res;
+    }
+    put(path, body) {
+        return this.request('PUT', path, body);
+    }
     patch(path, body) {
         return this.request('PATCH', path, body);
     }
@@ -57,13 +95,8 @@ export class ApiClient {
             body: body,
         });
         if (!res.ok) {
-            let detail = await res.text();
-            try {
-                detail = JSON.parse(detail).detail ?? detail;
-            }
-            catch {
-            }
-            throw new ApiError(res.status, detail);
+            const detail = parsedErrorDetail(await res.text());
+            throw new ApiError(res.status, detail, path);
         }
         const contentType_ = res.headers.get('content-type') ?? '';
         return contentType_.includes('application/json') ? res.json() : res;
@@ -77,13 +110,8 @@ export class ApiClient {
             body: form,
         });
         if (!res.ok) {
-            let detail = await res.text();
-            try {
-                detail = JSON.parse(detail).detail ?? detail;
-            }
-            catch {
-            }
-            throw new ApiError(res.status, detail);
+            const detail = parsedErrorDetail(await res.text());
+            throw new ApiError(res.status, detail, path);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -95,7 +123,7 @@ export class ApiClient {
         });
         if (!res.ok) {
             const detail = await res.text().catch(() => '');
-            throw new ApiError(res.status, detail || res.statusText);
+            throw new ApiError(res.status, detail || res.statusText, path);
         }
         return Buffer.from(await res.arrayBuffer());
     }
@@ -105,13 +133,8 @@ export class ApiClient {
             headers: { Authorization: `Bearer ${this.token}`, Accept: 'text/event-stream' },
         });
         if (!res.ok) {
-            let detail = await res.text().catch(() => '');
-            try {
-                detail = JSON.parse(detail).detail ?? detail;
-            }
-            catch {
-            }
-            throw new ApiError(res.status, detail || res.statusText);
+            const detail = parsedErrorDetail(await res.text().catch(() => ''));
+            throw new ApiError(res.status, detail || res.statusText, path);
         }
         const decoder = new TextDecoder();
         for await (const chunk of res.body) {
@@ -122,18 +145,75 @@ export class ApiClient {
             yield tail;
     }
 }
+function rootCause(err) {
+    const cause = err?.cause;
+    if (cause && typeof cause === 'object' && Array.isArray(cause.errors)) {
+        return cause.errors[0] ?? cause;
+    }
+    return cause ?? err;
+}
+function networkError(err) {
+    const inner = rootCause(err);
+    const code = inner?.code;
+    if (!code)
+        return null;
+    const hints = {
+        ECONNREFUSED: 'the server refused the connection — is it running, and is the URL/port right?',
+        ENOTFOUND: 'the host could not be resolved (DNS) — check the URL',
+        EAI_AGAIN: 'temporary DNS failure — check your network connection',
+        ETIMEDOUT: 'the connection timed out — the server may be down or unreachable',
+        ECONNRESET: 'the connection was reset by the server',
+        CERT_HAS_EXPIRED: "the server's TLS certificate has expired",
+    };
+    const detail = inner instanceof Error ? inner.message : String(inner);
+    return `Could not reach the server (${code}): ${detail}${hints[code] ? ` — ${hints[code]}` : ''}`;
+}
+function detailSuffix(err) {
+    const stack = err instanceof Error && err.stack ? err.stack : String(err);
+    const cause = err?.cause;
+    return `\n${stack}${cause ? `\nCaused by: ${cause instanceof Error ? (cause.stack ?? cause.message) : String(cause)}` : ''}`;
+}
+function headline(err) {
+    if (err instanceof ApiError) {
+        if (err.status === 401) {
+            const command = loginCommandName();
+            return `Session expired or invalid — run \`${command}\`.`;
+        }
+        if (err.status === 403)
+            return err.detail ? `Forbidden: ${err.detail}` : 'Forbidden.';
+        if (err.status === 404) {
+            const snapshotRestoreMatch = err.path?.match(/^\/run-cloud\/snapshots\/([^/]+)\/restore$/);
+            if (snapshotRestoreMatch) {
+                const id = decodeURIComponent(snapshotRestoreMatch[1]);
+                if (/^sb(?:x)?_/.test(id)) {
+                    return `Snapshot ID not found: ${id}. \`sandbox restore\` expects a snapshot ID; to restart this sandbox, run \`runcloud sandbox resume ${id}\`.`;
+                }
+                return `Snapshot ID not found: ${id}.`;
+            }
+            const sandboxMatch = err.path?.match(/^\/run-cloud\/sandboxes\/([^/]+)/);
+            if (sandboxMatch) {
+                return `Sandbox ID not found: ${decodeURIComponent(sandboxMatch[1])}.`;
+            }
+            if (err.path?.startsWith('/run-cloud/images')) {
+                return 'Image not found — check the reference, and that it has been registered.';
+            }
+            if (!err.detail || /^not found$/i.test(err.detail.trim())) {
+                return err.path
+                    ? "This version of the CLI asked for something the server doesn't have."
+                    : 'Resource not found.';
+            }
+            return err.detail;
+        }
+        if (err.status === 409)
+            return err.detail;
+        if (err.status === 503)
+            return 'The platform is at capacity right now — please try again in a few minutes.';
+        return err.message;
+    }
+    return networkError(err) ?? (err instanceof Error ? err.message : String(err));
+}
 export function friendlyApiError(err) {
-    if (!(err instanceof ApiError))
-        return String(err);
-    if (err.status === 401)
-        return 'Session expired or invalid — run `newly login`.';
-    if (err.status === 403)
-        return err.detail ? `Forbidden: ${err.detail}` : 'Forbidden.';
-    if (err.status === 404)
-        return `Not found: ${err.detail}`;
-    if (err.status === 409)
-        return err.detail;
-    if (err.status === 503)
-        return 'The platform is at capacity right now — please try again in a few minutes.';
-    return err.message;
+    const message = headline(err);
+    const debug = process.env.RUNCLOUD_DEBUG === '1' || process.env.NEWLY_DEBUG === '1';
+    return !debug || err instanceof ApiError ? message : `${message}${detailSuffix(err)}`;
 }