@remotedraw/cli 0.1.2 → 0.2.0

package/dist/cloud.d.ts

@@ -40,6 +40,19 @@ export type ProvisionedProject = {
 };
 export declare function remoteDrawApiBaseUrl(env: Record<string, string | undefined>, requested?: string): string;
 export declare function globalConfigPath(runtime: CloudRuntime): string;
+/**
+ * The stored CLI language, or undefined when the reader has never chosen one.
+ * A damaged or unreadable config never blocks a command here — the caller
+ * simply falls back to English — because the language is a preference, not a
+ * credential.
+ */
+export declare function readStoredLanguage(runtime: CloudRuntime): Promise<string | undefined>;
+/**
+ * Persists the language into the same config.json (and same 0600 directory)
+ * that already holds the CLI credential, so there is one user-config file to
+ * find, back up, or delete.
+ */
+export declare function writeStoredLanguage(runtime: CloudRuntime, language: string): Promise<void>;
 export declare function currentCliAccount(runtime: CloudRuntime, apiBaseUrl: string): Promise<CliAccount | undefined>;
 export declare function loginToRemoteDraw(runtime: CloudRuntime, apiBaseUrl: string, options?: {
     openBrowser?: boolean;

package/dist/cloud.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":"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"}

package/dist/cloud.js

@@ -1,5 +1,7 @@
 import { homedir } from "node:os";
 import path from "node:path";
+import { cliError } from "./errors.js";
+import { t } from "./i18n.js";
 export const DEFAULT_REMOTEDRAW_API_BASE_URL = "https://api.remotedraw.com";
 function normalizedOrigin(value) {
     const url = new URL(value.trim());
@@ -9,7 +11,7 @@ function normalizedOrigin(value) {
         url.pathname !== "/" ||
         url.search ||
         url.hash) {
-        throw new Error(`Expected an HTTP API origin, received ${value}.`);
+        throw new Error(t("cloud.error.badOrigin", { value }));
     }
     return url.origin;
 }
@@ -59,12 +61,47 @@ async function readStoredConfig(runtime) {
                 ? parsed.activeApiBaseUrl
                 : "",
             profiles,
+            ...(typeof parsed.language === "string"
+                ? { language: parsed.language }
+                : {}),
         };
     }
     catch {
-        throw new Error(`Could not read RemoteDraw CLI credentials from ${configPath}. Remove or repair that file.`);
+        throw new Error(t("cloud.error.configUnreadable", { path: configPath }));
     }
 }
+/**
+ * The stored CLI language, or undefined when the reader has never chosen one.
+ * A damaged or unreadable config never blocks a command here — the caller
+ * simply falls back to English — because the language is a preference, not a
+ * credential.
+ */
+export async function readStoredLanguage(runtime) {
+    try {
+        return (await readStoredConfig(runtime)).language;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persists the language into the same config.json (and same 0600 directory)
+ * that already holds the CLI credential, so there is one user-config file to
+ * find, back up, or delete.
+ */
+export async function writeStoredLanguage(runtime, language) {
+    let config;
+    try {
+        config = await readStoredConfig(runtime);
+    }
+    catch {
+        // A corrupt credential file must not make the language unsettable; the
+        // login flow reports that failure on its own terms.
+        config = { version: 1, activeApiBaseUrl: "", profiles: {} };
+    }
+    config.language = language;
+    await writeStoredConfig(runtime, config);
+}
 async function writeStoredConfig(runtime, config) {
     const configPath = globalConfigPath(runtime);
     await runtime.mkdir(path.dirname(configPath));
@@ -89,7 +126,7 @@ async function storedToken(runtime, apiBaseUrl) {
 }
 async function fetchJson(runtime, apiBaseUrl, pathname, options = {}) {
     if (!runtime.fetch)
-        throw new Error("This runtime cannot access RemoteDraw.");
+        throw new Error(t("cloud.error.noFetch"));
     let response;
     try {
         response = await runtime.fetch(`${apiBaseUrl}${pathname}`, {
@@ -102,7 +139,10 @@ async function fetchJson(runtime, apiBaseUrl, pathname, options = {}) {
         });
     }
     catch (error) {
-        throw new Error(`Could not reach ${apiBaseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(t("cloud.error.unreachable", {
+            url: apiBaseUrl,
+            reason: error instanceof Error ? error.message : String(error),
+        }));
     }
     const raw = await response.text();
     let payload;
@@ -111,16 +151,20 @@ async function fetchJson(runtime, apiBaseUrl, pathname, options = {}) {
     }
     catch {
         if (response.status === 404) {
-            throw new Error(`RemoteDraw CLI endpoint ${pathname} was not found at ${apiBaseUrl}. Set REMOTEDRAW_API_BASE_URL to a deployment with the latest CLI auth functions.`);
+            throw new Error(t("cloud.error.endpointMissing", {
+                path: pathname,
+                url: apiBaseUrl,
+                defaultUrl: DEFAULT_REMOTEDRAW_API_BASE_URL,
+            }));
         }
-        throw new Error(`RemoteDraw returned an invalid response (${response.status}).`);
+        throw new Error(t("cloud.error.invalidResponse", { status: response.status }));
     }
     if (!response.ok) {
         const message = isRecord(payload) &&
             isRecord(payload.error) &&
             typeof payload.error.message === "string"
             ? payload.error.message
-            : `RemoteDraw request failed (${response.status}).`;
+            : t("cloud.error.requestFailed", { status: response.status });
         throw new Error(message);
     }
     return payload;
@@ -146,14 +190,17 @@ export async function loginToRemoteDraw(runtime, apiBaseUrl, options = {}) {
     const request = await fetchJson(runtime, normalized, "/v1/cli/auth/start", {
         body: { deviceName: options.deviceName ?? "RemoteDraw CLI" },
     });
-    runtime.notify?.(`Authorize this CLI at ${request.verificationUrl}\nConfirmation code: ${request.userCode}`);
+    runtime.notify?.(t("cloud.authorize", {
+        url: request.verificationUrl,
+        code: request.userCode,
+    }));
     if (options.openBrowser !== false && runtime.openUrl) {
         try {
             await runtime.openUrl(request.verificationUrl);
-            runtime.notify?.("Opened the browser. Waiting for authorization...");
+            runtime.notify?.(t("cloud.browserOpened"));
         }
         catch {
-            runtime.notify?.("Could not open the browser automatically; use the URL above.");
+            runtime.notify?.(t("cloud.browserFailed"));
         }
     }
     const sleep = runtime.sleep ??
@@ -166,7 +213,7 @@ export async function loginToRemoteDraw(runtime, apiBaseUrl, options = {}) {
         if (result.status === "pending")
             continue;
         if (result.status !== "authorized") {
-            throw new Error(`CLI authorization ${result.status}. Run remotedraw login again.`);
+            throw new Error(t("cloud.error.authStatus", { status: result.status }));
         }
         const config = await readStoredConfig(runtime);
         config.activeApiBaseUrl = normalized;
@@ -179,7 +226,7 @@ export async function loginToRemoteDraw(runtime, apiBaseUrl, options = {}) {
         await writeStoredConfig(runtime, config);
         return { account: result.account, alreadyLoggedIn: false };
     }
-    throw new Error("CLI authorization expired. Run remotedraw login again.");
+    throw new Error(t("cloud.error.authExpired"));
 }
 export async function logoutFromRemoteDraw(runtime, apiBaseUrl) {
     const normalized = normalizedOrigin(apiBaseUrl);
@@ -214,7 +261,7 @@ export async function provisionRemoteDrawProject(runtime, apiBaseUrl, input) {
         }
     }
     if (!token) {
-        throw new Error("Not logged in. Run remotedraw login, or set REMOTEDRAW_CLI_TOKEN for non-interactive use.");
+        throw cliError("AUTH_REQUIRED", "cloud.error.notLoggedIn");
     }
     return await fetchJson(runtime, normalized, "/v1/cli/projects", { body: input, token });
 }
@@ -246,7 +293,7 @@ export function updateEnvContents(contents, values, force = false) {
             existing !== value &&
             !isReplaceableEnvValue(name, existing) &&
             !force) {
-            throw new Error(`${name} is already set in .env.local. Pass --force to replace it or use --offline to keep setup local-only.`);
+            throw new Error(t("cloud.error.envConflict", { name }));
         }
         const pattern = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=.*$`, "m");
         if (pattern.test(next)) {

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+import { type MessageId, type MessageParams } from "./i18n.js";
+/**
+ * The machine-readable classification carried by `--format json` failures.
+ * Codes used to be inferred from English substrings in the message, which
+ * quietly stopped working the moment a message could be Dutch. They are now
+ * declared where the error is raised, so the JSON contract is independent of
+ * the reader's language.
+ */
+export type CliErrorCode = "MISSING_ARGUMENT" | "INVALID_ARGUMENT" | "INVALID_COMBINATION" | "FILE_CONFLICT" | "AUTH_REQUIRED" | "COMMAND_FAILED";
+export declare class CliError extends Error {
+    readonly code: CliErrorCode;
+    constructor(message: string, code: CliErrorCode);
+}
+/** Raises a localized message with a stable, language-independent code. */
+export declare function cliError(code: CliErrorCode, id: MessageId, params?: MessageParams): CliError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAK,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,qBAAqB,GACrB,eAAe,GACf,eAAe,GACf,gBAAgB,CAAC;AAErB,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY;CAKhD;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CACtB,IAAI,EAAE,YAAY,EAClB,EAAE,EAAE,SAAS,EACb,MAAM,CAAC,EAAE,aAAa,YAGvB"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+import { t } from "./i18n.js";
+export class CliError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+    }
+}
+/** Raises a localized message with a stable, language-independent code. */
+export function cliError(code, id, params) {
+    return new CliError(t(id, params), code);
+}

package/dist/generated/agent-skill.d.ts

@@ -0,0 +1,2 @@
+export declare const AGENT_SKILL_MARKDOWN = "---\nname: remotedraw\ndescription: Add RemoteDraw phone input to customer apps with the RemoteDraw CLI, public API, React SDK, raw HTTP, or customer-owned iOS sender flow.\n---\n\n# RemoteDraw Agent Skill\n\nUse this skill when a user asks to create, initialize, debug, or review a RemoteDraw integration.\n\n## Decision Flow\n\n1. Identify the receiver surface: web app, desktop app, iOS app, or headless/backend workflow.\n2. Identify the sender surface: RemoteDraw iOS app, embedded web sender, customer-owned iOS sender, or raw/headless sender.\n3. Pick the SDK path:\n   - React SDK: web receiver and optional embedded web sender.\n   - Plain JavaScript/raw HTTP: non-React web, desktop, backend, or custom clients.\n   - Swift: customer-owned iOS sender apps.\n4. Pick a supported starter: `signature` for a bounded signature-field target,\n   or `sketch` for a free-form receiver surface \u2014 both render through the\n   `RemoteDrawReceiver` foundation, with the surrounding UI owned by the\n   integrating app. Configure the target kind and descriptor directly for\n   photos, PDFs, maps, screens, and other custom surfaces.\n\n## Endpoint, Key, and Packages\n\nRemoteDraw is hosted. There is nothing for the customer to run or self-host.\n\n- API base URL: `https://api.remotedraw.com`\n- Public docs: `https://docs.remotedraw.com/docs`\n- API keys are created in the console at\n  `https://dashboard.remotedraw.com/api/keys` and belong in `.env.local` as\n  `REMOTEDRAW_API_KEY`, alongside\n  `REMOTEDRAW_API_BASE_URL=https://api.remotedraw.com`.\n\nPublished npm packages \u2014 install only what the chosen path needs:\n\n| Package | Install | Use it for |\n| --- | --- | --- |\n| `@remotedraw/cli` | `npm install -g @remotedraw/cli` (or `npx @remotedraw/cli@latest`) | Scaffolding, doctor, and test sessions. |\n| `@remotedraw/react` | `npm install @remotedraw/react` | React receiver, pairing, and headless sender. Peers on `react`/`react-dom` >= 18. |\n| `@remotedraw/svelte` | `npm install @remotedraw/svelte` | Svelte receiver store over the framework-free client. |\n| `@remotedraw/client` | `npm install @remotedraw/client` | Framework-free receiver/sender/API clients for any JS runtime. |\n| `@remotedraw/protocol` | `npm install @remotedraw/protocol` | Shared schemas, types, and limits for raw-HTTP integrations. |\n| `@remotedraw/geometry` | `npm install @remotedraw/geometry` | Normalized stroke geometry, shape assist, hit testing, export. |\n\n`@remotedraw/react` already depends on `client`, `protocol`, and `geometry`, so\ndo not add those separately for a React app. There is no published Swift\npackage: `remotedraw init --sdk swift` writes one self-contained\n`RemoteDrawIntegration.swift` against the public HTTP routes.\n\n## CLI First\n\nRead the machine-readable option catalog before choosing a plan:\n\n```sh\nremotedraw options --format json\n```\n\nInitialize a project with the closest supported path:\n\n```sh\nremotedraw init --target web --sender remotedraw-ios --sdk react --preset signature\nremotedraw init --target web --sender embedded-web --sdk react --preset sketch\nremotedraw init --target desktop --sender remotedraw-ios --sdk js --preset sketch\nremotedraw init --target ios --sender own-ios --sdk swift --preset sketch\n```\n\nBy default, `new` and `init` create the dashboard project and a project-scoped\ndevelopment API key, then write `REMOTEDRAW_API_BASE_URL`,\n`REMOTEDRAW_PROJECT_ID`, and `REMOTEDRAW_API_KEY` to a gitignored `.env.local`.\nUse `--offline` only when cloud setup is intentionally out of scope.\n\n`--sender own-ios` requires `--sdk swift`; every other combination of\n`--target`, `--sender`, and `--sdk` is accepted. Invalid combinations fail with\n`INVALID_COMBINATION` rather than guessing.\n\nAgents must use explicit non-interactive dry runs before changing a project:\n\n```sh\nremotedraw init --non-interactive --offline --dry-run --format json --target web --sender remotedraw-ios --sdk react --preset signature --package-manager npm\n# Inspect plan, files, defaultsApplied, and warnings before applying.\nremotedraw init --non-interactive --offline --format json --target web --sender remotedraw-ios --sdk react --preset signature --package-manager npm\nremotedraw doctor --format json\nremotedraw create-input --preset signature --json\n```\n\nDo not use the interactive wizard, synthesize arrow-key input, or scrape\nhuman-formatted output. If receiver, sender, or preset intent is ambiguous, ask\nthe user instead of guessing. Never pass `--force` unless overwrite scope was\nexplicitly approved.\n\n## Security Rules\n\n- Keep `rd_sk_...` API keys in trusted backend secrets only.\n- Keep the account-level `rd_cli_...` credential in the user config directory; never copy it into a project. Use `REMOTEDRAW_CLI_TOKEN` only as an explicitly managed CI secret.\n- Never place API keys in browser bundles, mobile clients, screenshots, logs, or generated examples.\n- Public clients should receive only `joinUrl`, `joinToken`, `receiverToken`, or `senderToken` values scoped to the session.\n- Production QR codes should use HTTPS `joinUrl` values. Do not make the custom scheme the primary QR target.\n\n## API Contract\n\n- Backend creates sessions with `POST /v1/sessions`.\n- Receiver clients read `POST /v1/receiver/session`, `/drawings`, `/drafts`, and `/senders` with a receiver token.\n- Sender clients join with `POST /v1/join`, stream mutable drafts to `/v1/sender/draft`, commit durable strokes to `/v1/sender/commit`, and finish with `/v1/sender/submit`.\n- Custom senders should throttle draft updates, coalesce to the latest pending preview, and commit one durable stroke on pointer-up with a stable `clientStrokeId`.\n\n## AI Actions\n\nReach for AI when the product needs something _from_ the finished drawing:\na generated image, a description, or structured data to branch on. Backend only\n(`aiActions:*` scopes on an `rd_sk_...` key). Never wire it to a commit,\nsubmit, or presence event \u2014 AI runs only on an explicit `POST /v1/ai-actions`\ncall the user asked for. Run it after the user is done; the route accepts\n`active` and `ended` sessions.\n\nMinimal request per outcome (`POST /v1/ai-actions`, plus optional\n`quality: \"fast\" | \"balanced\" | \"max\"`, default `balanced`):\n\n```jsonc\n{ \"sessionId\": \"...\", \"request\": \"image\", \"prompt\": \"...\" }                        // image back in the response\n{ \"sessionId\": \"...\", \"request\": \"image\", \"prompt\": \"...\", \"deliver\": [\"result\", \"board\"] } // and onto the board\n{ \"sessionId\": \"...\", \"request\": \"text\",  \"prompt\": \"Describe this drawing.\" }     // text back\n{ \"sessionId\": \"...\", \"request\": \"text\",  \"prompt\": \"...\", \"text\": { \"schema\": { /* JSON Schema */ } } } // typed JSON\n```\n\nThe response is asynchronous: `create` returns `status: \"queued\"`. Poll\n`POST /v1/ai-actions/get` until `status` is `succeeded`, `failed`, or\n`canceled`, or use the helper on the API client\n(`createHttpRemoteDrawApiClient` from `@remotedraw/client`, re-exported by\n`@remotedraw/react`). This client holds the `rd_sk_` key, so it only ever runs\non the backend:\n\n```ts\nconst action = await client.createAiAction({\n  sessionId,\n  request: \"image\",\n  prompt,\n});\nconst finished = await client.waitForAiAction({ aiActionId: action.id });\n// finished.result: generatedImageUrl | generatedText | generatedData | boardDrawingIds\n```\n\nThere is no completion webhook. Results are RemoteDraw-hosted asset URLs, not\nprovider URLs. See https://docs.remotedraw.com/docs/api#ai for the full\nrequest, credit, and legacy-mapping tables.\n\n## Verification\n\nAfter changes, verify against the customer's project \u2014 never assume RemoteDraw's\nown repo scripts exist here.\n\n```sh\nremotedraw doctor                    # config, SDK deps, REMOTEDRAW_* env\nremotedraw create-input --execute    # open a real session, print the join URL\n```\n\nThen run whatever type check and test command the project already defines (for\nexample `npm run typecheck` and `npm test`). Do not invent script names, and do\nnot run `bun run test:api`, `bun run typecheck`, or `bun run ios:kit:test` \u2014\nthose are RemoteDraw's internal monorepo scripts and will not exist in a\ncustomer project.";
+//# sourceMappingURL=agent-skill.d.ts.map

package/dist/generated/agent-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skill.d.ts","sourceRoot":"","sources":["../../src/generated/agent-skill.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,oBAAoB,6nQAAomQ,CAAC"}

package/dist/generated/agent-skill.js

@@ -0,0 +1,4 @@
+// GENERATED FILE — do not edit.
+// Source: docs/agents/remotedraw/SKILL.md
+// Regenerate: bun run --cwd packages/cli generate:skill
+export const AGENT_SKILL_MARKDOWN = "---\nname: remotedraw\ndescription: Add RemoteDraw phone input to customer apps with the RemoteDraw CLI, public API, React SDK, raw HTTP, or customer-owned iOS sender flow.\n---\n\n# RemoteDraw Agent Skill\n\nUse this skill when a user asks to create, initialize, debug, or review a RemoteDraw integration.\n\n## Decision Flow\n\n1. Identify the receiver surface: web app, desktop app, iOS app, or headless/backend workflow.\n2. Identify the sender surface: RemoteDraw iOS app, embedded web sender, customer-owned iOS sender, or raw/headless sender.\n3. Pick the SDK path:\n   - React SDK: web receiver and optional embedded web sender.\n   - Plain JavaScript/raw HTTP: non-React web, desktop, backend, or custom clients.\n   - Swift: customer-owned iOS sender apps.\n4. Pick a supported starter: `signature` for a bounded signature-field target,\n   or `sketch` for a free-form receiver surface — both render through the\n   `RemoteDrawReceiver` foundation, with the surrounding UI owned by the\n   integrating app. Configure the target kind and descriptor directly for\n   photos, PDFs, maps, screens, and other custom surfaces.\n\n## Endpoint, Key, and Packages\n\nRemoteDraw is hosted. There is nothing for the customer to run or self-host.\n\n- API base URL: `https://api.remotedraw.com`\n- Public docs: `https://docs.remotedraw.com/docs`\n- API keys are created in the console at\n  `https://dashboard.remotedraw.com/api/keys` and belong in `.env.local` as\n  `REMOTEDRAW_API_KEY`, alongside\n  `REMOTEDRAW_API_BASE_URL=https://api.remotedraw.com`.\n\nPublished npm packages — install only what the chosen path needs:\n\n| Package | Install | Use it for |\n| --- | --- | --- |\n| `@remotedraw/cli` | `npm install -g @remotedraw/cli` (or `npx @remotedraw/cli@latest`) | Scaffolding, doctor, and test sessions. |\n| `@remotedraw/react` | `npm install @remotedraw/react` | React receiver, pairing, and headless sender. Peers on `react`/`react-dom` >= 18. |\n| `@remotedraw/svelte` | `npm install @remotedraw/svelte` | Svelte receiver store over the framework-free client. |\n| `@remotedraw/client` | `npm install @remotedraw/client` | Framework-free receiver/sender/API clients for any JS runtime. |\n| `@remotedraw/protocol` | `npm install @remotedraw/protocol` | Shared schemas, types, and limits for raw-HTTP integrations. |\n| `@remotedraw/geometry` | `npm install @remotedraw/geometry` | Normalized stroke geometry, shape assist, hit testing, export. |\n\n`@remotedraw/react` already depends on `client`, `protocol`, and `geometry`, so\ndo not add those separately for a React app. There is no published Swift\npackage: `remotedraw init --sdk swift` writes one self-contained\n`RemoteDrawIntegration.swift` against the public HTTP routes.\n\n## CLI First\n\nRead the machine-readable option catalog before choosing a plan:\n\n```sh\nremotedraw options --format json\n```\n\nInitialize a project with the closest supported path:\n\n```sh\nremotedraw init --target web --sender remotedraw-ios --sdk react --preset signature\nremotedraw init --target web --sender embedded-web --sdk react --preset sketch\nremotedraw init --target desktop --sender remotedraw-ios --sdk js --preset sketch\nremotedraw init --target ios --sender own-ios --sdk swift --preset sketch\n```\n\nBy default, `new` and `init` create the dashboard project and a project-scoped\ndevelopment API key, then write `REMOTEDRAW_API_BASE_URL`,\n`REMOTEDRAW_PROJECT_ID`, and `REMOTEDRAW_API_KEY` to a gitignored `.env.local`.\nUse `--offline` only when cloud setup is intentionally out of scope.\n\n`--sender own-ios` requires `--sdk swift`; every other combination of\n`--target`, `--sender`, and `--sdk` is accepted. Invalid combinations fail with\n`INVALID_COMBINATION` rather than guessing.\n\nAgents must use explicit non-interactive dry runs before changing a project:\n\n```sh\nremotedraw init --non-interactive --offline --dry-run --format json --target web --sender remotedraw-ios --sdk react --preset signature --package-manager npm\n# Inspect plan, files, defaultsApplied, and warnings before applying.\nremotedraw init --non-interactive --offline --format json --target web --sender remotedraw-ios --sdk react --preset signature --package-manager npm\nremotedraw doctor --format json\nremotedraw create-input --preset signature --json\n```\n\nDo not use the interactive wizard, synthesize arrow-key input, or scrape\nhuman-formatted output. If receiver, sender, or preset intent is ambiguous, ask\nthe user instead of guessing. Never pass `--force` unless overwrite scope was\nexplicitly approved.\n\n## Security Rules\n\n- Keep `rd_sk_...` API keys in trusted backend secrets only.\n- Keep the account-level `rd_cli_...` credential in the user config directory; never copy it into a project. Use `REMOTEDRAW_CLI_TOKEN` only as an explicitly managed CI secret.\n- Never place API keys in browser bundles, mobile clients, screenshots, logs, or generated examples.\n- Public clients should receive only `joinUrl`, `joinToken`, `receiverToken`, or `senderToken` values scoped to the session.\n- Production QR codes should use HTTPS `joinUrl` values. Do not make the custom scheme the primary QR target.\n\n## API Contract\n\n- Backend creates sessions with `POST /v1/sessions`.\n- Receiver clients read `POST /v1/receiver/session`, `/drawings`, `/drafts`, and `/senders` with a receiver token.\n- Sender clients join with `POST /v1/join`, stream mutable drafts to `/v1/sender/draft`, commit durable strokes to `/v1/sender/commit`, and finish with `/v1/sender/submit`.\n- Custom senders should throttle draft updates, coalesce to the latest pending preview, and commit one durable stroke on pointer-up with a stable `clientStrokeId`.\n\n## AI Actions\n\nReach for AI when the product needs something _from_ the finished drawing:\na generated image, a description, or structured data to branch on. Backend only\n(`aiActions:*` scopes on an `rd_sk_...` key). Never wire it to a commit,\nsubmit, or presence event — AI runs only on an explicit `POST /v1/ai-actions`\ncall the user asked for. Run it after the user is done; the route accepts\n`active` and `ended` sessions.\n\nMinimal request per outcome (`POST /v1/ai-actions`, plus optional\n`quality: \"fast\" | \"balanced\" | \"max\"`, default `balanced`):\n\n```jsonc\n{ \"sessionId\": \"...\", \"request\": \"image\", \"prompt\": \"...\" }                        // image back in the response\n{ \"sessionId\": \"...\", \"request\": \"image\", \"prompt\": \"...\", \"deliver\": [\"result\", \"board\"] } // and onto the board\n{ \"sessionId\": \"...\", \"request\": \"text\",  \"prompt\": \"Describe this drawing.\" }     // text back\n{ \"sessionId\": \"...\", \"request\": \"text\",  \"prompt\": \"...\", \"text\": { \"schema\": { /* JSON Schema */ } } } // typed JSON\n```\n\nThe response is asynchronous: `create` returns `status: \"queued\"`. Poll\n`POST /v1/ai-actions/get` until `status` is `succeeded`, `failed`, or\n`canceled`, or use the helper on the API client\n(`createHttpRemoteDrawApiClient` from `@remotedraw/client`, re-exported by\n`@remotedraw/react`). This client holds the `rd_sk_` key, so it only ever runs\non the backend:\n\n```ts\nconst action = await client.createAiAction({\n  sessionId,\n  request: \"image\",\n  prompt,\n});\nconst finished = await client.waitForAiAction({ aiActionId: action.id });\n// finished.result: generatedImageUrl | generatedText | generatedData | boardDrawingIds\n```\n\nThere is no completion webhook. Results are RemoteDraw-hosted asset URLs, not\nprovider URLs. See https://docs.remotedraw.com/docs/api#ai for the full\nrequest, credit, and legacy-mapping tables.\n\n## Verification\n\nAfter changes, verify against the customer's project — never assume RemoteDraw's\nown repo scripts exist here.\n\n```sh\nremotedraw doctor                    # config, SDK deps, REMOTEDRAW_* env\nremotedraw create-input --execute    # open a real session, print the join URL\n```\n\nThen run whatever type check and test command the project already defines (for\nexample `npm run typecheck` and `npm test`). Do not invent script names, and do\nnot run `bun run test:api`, `bun run typecheck`, or `bun run ios:kit:test` —\nthose are RemoteDraw's internal monorepo scripts and will not exist in a\ncustomer project.";

package/dist/i18n.d.ts

@@ -0,0 +1,74 @@
+import { LOCALES, SOURCE_LOCALE, SUPPORTED_LOCALES, type Locale, type MessageId } from "./locales/index.js";
+export type { Locale, MessageId };
+export { LOCALES, SOURCE_LOCALE, SUPPORTED_LOCALES };
+export type MessageParams = Record<string, string | number>;
+export type Translate = (id: MessageId, params?: MessageParams) => string;
+/** Env vars that pick the CLI language without a flag or a prompt. */
+export declare const LANGUAGE_ENV_VARS: readonly ["REMOTEDRAW_LANGUAGE", "REMOTEDRAW_LANG"];
+/** Where the resolved locale came from — doctor and `language` report it. */
+export type LocaleSource = "flag" | "env" | "config" | "prompt" | "default";
+export declare function isLocale(value: string): value is Locale;
+/**
+ * Accepts what a human or a CI job would actually type: a code (`nl`), a
+ * BCP-47 tag (`nl-BE`, `nl_BE.UTF-8`), an endonym (`Nederlands`), or an
+ * English name (`Dutch`). Returns undefined for anything unrecognized so the
+ * caller can fail loudly instead of silently falling back.
+ */
+export declare function normalizeLocale(value: string | undefined): Locale | undefined;
+export declare function localeEndonym(locale: Locale): string;
+/** `en, nl` — for "supported languages" error text. */
+export declare function supportedLocaleList(): string;
+/**
+ * A missing key renders the English string; a key missing from English too
+ * renders the id, which only happens for a typo and is loud in review.
+ */
+export declare function createTranslator(locale: Locale): Translate;
+export declare function setActiveLocale(locale: Locale): void;
+export declare function activeLocale(): Locale;
+export declare const t: Translate;
+/**
+ * The picker question is built from every installed locale's own word for
+ * "Language", so it reads for a Dutch speaker and an English speaker alike
+ * and grows automatically when a locale is added.
+ */
+export declare function languagePromptMessage(): string;
+export declare function languageChoices(): {
+    value: "en" | "nl";
+    label: string;
+    hint: "en" | "nl";
+}[];
+/**
+ * Only used to preselect a row in the picker. The user still confirms, so a
+ * wrong guess costs an arrow key rather than an unreadable CLI.
+ */
+export declare function systemLocaleHint(env: Record<string, string | undefined>): Locale | undefined;
+export type LocaleResolution = {
+    ok: true;
+    locale: Locale;
+    source: LocaleSource;
+    needsPrompt: boolean;
+} | {
+    ok: false;
+    value: string;
+    variable: string;
+};
+/**
+ * Precedence: explicit flag, environment, stored choice, then unresolved.
+ * "Unresolved" is not an error — it means the CLI may ask, and must default
+ * to English when it cannot (no TTY, piped stdin, CI, an agent shelling out).
+ */
+export declare function resolveLocale(inputs: {
+    flag?: string | undefined;
+    env: Record<string, string | undefined>;
+    stored?: string | undefined;
+}): LocaleResolution;
+/**
+ * Pulls `--language <code>` / `--lang=<code>` out of argv before per-command
+ * flag parsing, which rejects options it does not declare. Returns the value
+ * and the remaining arguments.
+ */
+export declare function extractLanguageFlag(args: readonly string[]): {
+    value?: string;
+    rest: string[];
+};
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,KAAK,MAAM,EACX,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,SAAS,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,aAAa,KAAK,MAAM,CAAC;AAE1E,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,qDAGpB,CAAC;AAEX,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,MAAM,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAkB7E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,UAE3C;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,WAIlC;AAUD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAK1D;AAYD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,QAG7C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,eAAO,MAAM,CAAC,EAAE,SAAwD,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,qBAAqB,WAOpC;AAED,wBAAgB,eAAe;;;;IAM9B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,MAAM,GAAG,SAAS,CAMpB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,GACxE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,GAAG,gBAAgB,CA4BnB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CA0BA"}

package/dist/i18n.js

@@ -0,0 +1,178 @@
+import { LOCALES, SOURCE_LOCALE, SUPPORTED_LOCALES, } from "./locales/index.js";
+export { LOCALES, SOURCE_LOCALE, SUPPORTED_LOCALES };
+/** Env vars that pick the CLI language without a flag or a prompt. */
+export const LANGUAGE_ENV_VARS = [
+    "REMOTEDRAW_LANGUAGE",
+    "REMOTEDRAW_LANG",
+];
+export function isLocale(value) {
+    return SUPPORTED_LOCALES.includes(value);
+}
+/**
+ * Accepts what a human or a CI job would actually type: a code (`nl`), a
+ * BCP-47 tag (`nl-BE`, `nl_BE.UTF-8`), an endonym (`Nederlands`), or an
+ * English name (`Dutch`). Returns undefined for anything unrecognized so the
+ * caller can fail loudly instead of silently falling back.
+ */
+export function normalizeLocale(value) {
+    if (value == null)
+        return undefined;
+    const cleaned = value.trim().toLowerCase().split(".")[0]?.replace("_", "-");
+    if (!cleaned)
+        return undefined;
+    const base = cleaned.split("-")[0] ?? cleaned;
+    for (const locale of SUPPORTED_LOCALES) {
+        const definition = LOCALES[locale];
+        if (locale === cleaned ||
+            locale === base ||
+            definition.tags.includes(base) ||
+            definition.aliases.includes(cleaned) ||
+            definition.endonym.toLowerCase() === cleaned) {
+            return locale;
+        }
+    }
+    return undefined;
+}
+export function localeEndonym(locale) {
+    return LOCALES[locale].endonym;
+}
+/** `en, nl` — for "supported languages" error text. */
+export function supportedLocaleList() {
+    return SUPPORTED_LOCALES.map((locale) => `${locale} (${localeEndonym(locale)})`).join(", ");
+}
+function interpolate(template, params) {
+    if (!params)
+        return template;
+    return template.replaceAll(/\{(\w+)\}/g, (match, key) => {
+        const value = params[key];
+        return value == null ? match : String(value);
+    });
+}
+/**
+ * A missing key renders the English string; a key missing from English too
+ * renders the id, which only happens for a typo and is loud in review.
+ */
+export function createTranslator(locale) {
+    const catalog = LOCALES[locale].catalog;
+    const fallback = LOCALES[SOURCE_LOCALE].catalog;
+    return (id, params) => interpolate(catalog[id] ?? fallback[id] ?? id, params);
+}
+/**
+ * The CLI is one process running one command for one reader, so the active
+ * locale is process state rather than an argument threaded through ~120 text
+ * builders. `runCli` sets it deterministically on entry from flag/env/config,
+ * which is what keeps repeated in-process runs (the test suite) from leaking
+ * a locale into each other.
+ */
+let activeLocaleValue = SOURCE_LOCALE;
+let activeTranslator = createTranslator(SOURCE_LOCALE);
+export function setActiveLocale(locale) {
+    activeLocaleValue = locale;
+    activeTranslator = createTranslator(locale);
+}
+export function activeLocale() {
+    return activeLocaleValue;
+}
+export const t = (id, params) => activeTranslator(id, params);
+/**
+ * The picker question is built from every installed locale's own word for
+ * "Language", so it reads for a Dutch speaker and an English speaker alike
+ * and grows automatically when a locale is added.
+ */
+export function languagePromptMessage() {
+    const words = [];
+    for (const locale of SUPPORTED_LOCALES) {
+        const word = createTranslator(locale)("language.word");
+        if (!words.includes(word))
+            words.push(word);
+    }
+    return words.join(" / ");
+}
+export function languageChoices() {
+    return SUPPORTED_LOCALES.map((locale) => ({
+        value: locale,
+        label: localeEndonym(locale),
+        hint: locale,
+    }));
+}
+/**
+ * Only used to preselect a row in the picker. The user still confirms, so a
+ * wrong guess costs an arrow key rather than an unreadable CLI.
+ */
+export function systemLocaleHint(env) {
+    for (const name of ["LC_ALL", "LC_MESSAGES", "LANG", "LANGUAGE"]) {
+        const guess = normalizeLocale(env[name]?.split(":")[0]);
+        if (guess)
+            return guess;
+    }
+    return undefined;
+}
+/**
+ * Precedence: explicit flag, environment, stored choice, then unresolved.
+ * "Unresolved" is not an error — it means the CLI may ask, and must default
+ * to English when it cannot (no TTY, piped stdin, CI, an agent shelling out).
+ */
+export function resolveLocale(inputs) {
+    if (inputs.flag != null) {
+        // A present-but-empty flag (`--language` with nothing after it) is a
+        // mistake worth reporting, not a silent fall-through to the environment.
+        const locale = normalizeLocale(inputs.flag);
+        return locale
+            ? { ok: true, locale, source: "flag", needsPrompt: false }
+            : { ok: false, value: inputs.flag.trim(), variable: "--language" };
+    }
+    for (const name of LANGUAGE_ENV_VARS) {
+        const raw = inputs.env[name]?.trim();
+        if (!raw)
+            continue;
+        const locale = normalizeLocale(raw);
+        return locale
+            ? { ok: true, locale, source: "env", needsPrompt: false }
+            : { ok: false, value: raw, variable: name };
+    }
+    const stored = normalizeLocale(inputs.stored);
+    if (stored) {
+        return { ok: true, locale: stored, source: "config", needsPrompt: false };
+    }
+    // Nothing chosen yet: English until the reader says otherwise.
+    return {
+        ok: true,
+        locale: SOURCE_LOCALE,
+        source: "default",
+        needsPrompt: true,
+    };
+}
+/**
+ * Pulls `--language <code>` / `--lang=<code>` out of argv before per-command
+ * flag parsing, which rejects options it does not declare. Returns the value
+ * and the remaining arguments.
+ */
+export function extractLanguageFlag(args) {
+    const rest = [];
+    let value;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg == null)
+            continue;
+        const match = /^--(language|lang)(?:=(.*))?$/.exec(arg);
+        if (!match) {
+            rest.push(arg);
+            continue;
+        }
+        if (match[2] != null) {
+            value = match[2];
+            continue;
+        }
+        const next = args[index + 1];
+        if (next != null && !next.startsWith("--")) {
+            value = next;
+            index += 1;
+        }
+        else {
+            // `--language` with nothing after it: treat as an empty request so the
+            // caller reports an unknown language instead of eating the next flag.
+            value = "";
+        }
+    }
+    return value == null ? { rest } : { value, rest };
+}

package/dist/index.js

@@ -1,8 +1,41 @@
 #!/usr/bin/env node
-import { createNodeRuntime, runCli } from "./cli.js";
-const result = await runCli(process.argv.slice(2), createNodeRuntime());
+import process from "node:process";
+import { CLI_VERSION, createNodeRuntime, runCli } from "./cli.js";
+import { nodeTelemetryEnvironment, reportCliCrash } from "./telemetry.js";
+import { checkForUpdate, detectInstallMethod, updateNotice } from "./update.js";
+// `runCli` reports whatever it catches; the handlers below cover the thin shell
+// around it — building the runtime, writing to a closed stdout, a rejection that
+// escapes a detached promise — which would otherwise crash with a bare Node
+// stack trace we never hear about.
+//
+// Installing them replaces Node's default crash behavior, so this has to restore
+// it: print the error, then exit non-zero. The report is awaited first because
+// `process.exit` would drop the in-flight request.
+async function reportAndCrash(error) {
+    await reportCliCrash(error, process.argv[2] ?? "help", nodeTelemetryEnvironment(CLI_VERSION));
+    process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exit(1);
+}
+process.on("uncaughtException", (error) => void reportAndCrash(error));
+process.on("unhandledRejection", (reason) => void reportAndCrash(reason));
+const runtime = createNodeRuntime();
+const result = await runCli(process.argv.slice(2), runtime);
 if (result.stdout)
     process.stdout.write(result.stdout);
 if (result.stderr)
     process.stderr.write(result.stderr);
 process.exitCode = result.exitCode;
+// Only a human at a terminal sees this. Piped output, CI, and machine-readable
+// runs stay byte-for-byte what the command produced.
+if (process.stderr.isTTY && process.argv[2] !== "update") {
+    try {
+        const check = await checkForUpdate(runtime, CLI_VERSION);
+        if (check?.updateAvailable) {
+            const method = detectInstallMethod(runtime.binPath ?? "");
+            process.stderr.write(`\n${updateNotice(check, method)}\n`);
+        }
+    }
+    catch {
+        // A failed update check never changes the outcome of the real command.
+    }
+}

package/dist/locales/catalog.d.ts

@@ -0,0 +1,21 @@
+import type { en } from "./en.js";
+/** Every translatable string in the CLI is addressed by one of these ids. */
+export type MessageId = keyof typeof en;
+/**
+ * A translation is a partial overlay on the English source catalog: anything
+ * a locale does not define renders in English instead of leaking a raw id.
+ */
+export type LocaleCatalog = Partial<Record<MessageId, string>>;
+export type LocaleDefinition = {
+    /**
+     * The language's own name for itself. The language picker lists endonyms so
+     * it is readable no matter which language the reader speaks.
+     */
+    endonym: string;
+    /** BCP-47 prefixes that map to this locale (`nl-BE` -> `nl`). */
+    tags: readonly string[];
+    /** Extra spellings accepted from --language / the environment. */
+    aliases: readonly string[];
+    catalog: LocaleCatalog;
+};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/locales/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/locales/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,EAAE,CAAC;AAExC;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,kEAAkE;IAClE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC"}

package/dist/locales/catalog.js

@@ -0,0 +1 @@
+export {};