carboncanvas-cli 0.1.1 → 0.1.2

package/CONTRACT.md

@@ -92,3 +92,115 @@ re-checks (a hand-crafted request can skip the CLI):
   server should still enforce (→ 400 / 413).
 - **Static-ness:** `index.html` at root, no server manifest (`.next/standalone`,
   `.output/server`, `functions/`, `server.js`/`server.mjs`, `_worker.js`).
+
+---
+
+# CLI auth contract (`/api/cli-auth/*` — device-code flow)
+
+Added 2026-07-08 (Wave B). Source of truth for `carboncanvas login`'s
+browser-approval flow; the server half must match byte-for-byte. The paste-token
+path (dashboard reveal panel → interactive prompt) remains as the fallback.
+Designed to be reused by a future MCP grant flow — nothing in it is CLI-specific.
+
+Works everywhere the CLI runs (laptop, Replit/Bolt cloud shell, container): the
+CLI never receives a browser callback — it POLLS. The user approves in their
+signed-in dashboard at `/activate`.
+
+## 1. `POST {serviceUrl}/api/cli-auth/start` — begin a grant (public, rate-limited)
+
+Request body: `{}` (no fields yet; senders MUST send valid JSON).
+
+`200` →
+```json
+{
+  "deviceCode": "dc_<high-entropy secret, CLI-side only, never shown to the user>",
+  "userCode":   "ABCD-1234",
+  "verifyUrl":  "https://<host>/activate",
+  "expiresIn":  900,
+  "interval":   5
+}
+```
+`userCode`: 8 chars from an unambiguous uppercase alphabet (no `0/O/1/I`),
+displayed and compared case-insensitively, hyphen optional on entry. Single-use,
+expires with the grant. The server stores only a hash of `deviceCode`.
+
+## 2. `POST {serviceUrl}/api/cli-auth/poll` — CLI polls (public, rate-limited)
+
+Request body: `{ "deviceCode": "dc_…" }`.
+
+`200` responses by grant state:
+- `{ "status": "pending" }` — keep polling at `interval` seconds.
+- `{ "status": "approved", "token": "<session bearer token>" }` — ONE-SHOT: the
+  token is minted at claim time and the grant is consumed; a second poll after
+  this returns `{ "status": "expired" }`.
+- `{ "status": "expired" }` — grant expired/denied/already-claimed; CLI restarts
+  or falls back to paste-token.
+
+`429` → slow down; CLI doubles its interval for the next poll. Body error code:
+`slow_down` on poll (device-flow convention); `start` uses the codebase-standard
+`rate_limited`. The CLI branches only on the 429 status, never the code.
+Unknown/garbage `deviceCode` → `{ "status": "expired" }` (no oracle).
+
+## 3. `POST {serviceUrl}/api/cli-auth/approve` — dashboard approves (session-authed)
+
+Called by the `/activate` dashboard page with the signed-in CREATOR's bearer
+session (`Authorization: Bearer <token>`). Guest/reviewer sessions are rejected.
+
+Request body: `{ "userCode": "ABCD-1234" }` (case-insensitive, hyphen optional).
+
+- `200 { "ok": true }` — grant bound to this account; the CLI's next poll claims it.
+- `404 { error, message }` — unknown, expired, or already-used code.
+- `401 / 403` — no session / not a creator session.
+
+All error bodies use the `{ error, message }` shape.
+
+## CLI behavior (`carboncanvas login`)
+
+1. `start` → print `verifyUrl` + `userCode` prominently; attempt to open the
+   browser locally (best-effort, never fail on error — cloud shells have no
+   browser); poll per `interval` until `approved`/`expired` (honor 429 backoff).
+2. On `approved`: store the token in the token store keyed by `serviceUrl`
+   (existing mechanism), verify with `GET /api/entitlements`, greet.
+3. On `expired` or user abort: offer the paste-token fallback.
+
+## `carboncanvas init` (companion command; no new server surface)
+
+Requires a stored token (runs the login flow inline if absent), then:
+1. Chooses the canvas (amended 2026-07-08 — `--canvas` / `--new` / picker):
+   - `--canvas <cnv_…>` — link an EXISTING canvas instead of creating. Verified
+     against `GET /api/canvases?includeArchived=1` (existing endpoint →
+     `{ canvases: CanvasView[] }`), matched on `id`. Not in the account → exit 1
+     ("check the ID in your dashboard"); archived → exit 1 (activate it first);
+     id without the `cnv_` prefix → exit 1 before any network call. Never POSTs.
+   - Plain `init`, account owns 0 non-archived canvases → create (step 1b), no
+     prompt — TTY or not (first-time fast path).
+   - Plain `init`, account owns ≥1 non-archived canvas (same GET, archived
+     excluded):
+     - TTY (stdin AND stdout): interactive picker — numbered `name  id` list;
+       Enter = create new named `<resolved name>`, a number = link that one.
+     - non-TTY (agents/CI): NEVER guesses — prints the canvases (one
+       `<id>  <name>` line each, stderr) and exits 1 telling the caller to
+       re-run with `--canvas <id>` or `--new`. Prevents surprise duplicates.
+   - `--new` — always create; skips the GET/picker/stop entirely. `--canvas`
+     and `--new` are mutually exclusive (exit 1).
+   1b. Create: `POST /api/canvases { name }` (name from `--name` or
+   package.json `name`) — existing endpoint, existing auth. `402/403` →
+   surface `message` (plan gate).
+   Auto-relogin (amended 2026-07-08): a `401` from either call above triggers
+   ONE inline device-code login ("Your sign-in expired — let's renew it."),
+   then a single retry of the failed call; a second `401` surfaces the error.
+   One relogin per run, never a loop.
+2. Write `VITE_CC_CANVAS_ID=<id>` + `VITE_CC_BACKEND=<serviceUrl>` into `.env`
+   (create or append; NEVER overwrite an existing `VITE_CC_CANVAS_ID` — the id
+   is write-once; print the existing one and exit 1 instead), mirror the keys
+   into `.env.example` with placeholder values, ensure `.gitignore` covers `.env`.
+   Identical for created AND linked canvases (the write-once guard still runs
+   first, before any network call).
+3. Print: the canvas id/name, what was written, and "tell your coding agent the
+   canvas is registered — it wires the comments prop from these env vars
+   (see <serviceUrl>/skill.md)". The id is the one machine-readable stdout line.
+
+Sibling command (added 2026-07-08): `carboncanvas canvases` — lists the
+account's canvases via the same `GET /api/canvases?includeArchived=1` (same
+auth + one-shot relogin); one `<id>  <name>` line per canvas on stdout, with a
+trailing `  [archived]` marker on soft-archived ones. No new server surface.

package/README.md

@@ -19,20 +19,101 @@ npx carboncanvas publish
 
 ## `carboncanvas login`
 
-Verifies a creator API token (from the dashboard → Settings → API tokens) against
-the backend and stores it in `~/.carboncanvas/config.json` (mode `0600`), keyed by
-backend URL.
+Signs you in via your **browser** (device-code flow): the CLI prints an
+activation link + a short code, opens the browser when it can, and waits while
+you approve the sign-in on the dashboard's `/activate` page. This works from
+anywhere — laptops, cloud shells (Replit/Bolt), containers — because the CLI
+only polls; it never needs a callback. The resulting token is verified and
+stored in `~/.carboncanvas/config.json` (mode `0600`), keyed by backend URL.
 
 ```bash
-carboncanvas login                 # prompts for a token (hidden input)
-carboncanvas login --token cc_xxx  # non-interactive
+carboncanvas login                 # browser approval (link + code)
+carboncanvas login --token cc_xxx  # paste-token, non-interactive
 ```
 
+- **Paste-token fallback:** if the browser flow expires, is denied, or the
+  backend doesn't support it, the CLI falls back to the classic hidden prompt
+  for a creator API token (dashboard → Settings → API tokens). `--token`
+  skips the browser flow entirely.
 - `CARBON_TOKEN` overrides the stored token at use time.
 - `--service-url <url>` / `CARBON_SERVICE_URL` selects the backend
-  (default `https://quilt-production-65f6.up.railway.app`).
+  (default `https://app.carboncanvas.design`).
 - `carboncanvas logout` removes the stored token; `carboncanvas whoami` checks it.
 
+## `carboncanvas init`
+
+Registers (or links) a canvas for the current project and wires it into your
+env files — run it once per project, then hand off to your coding agent.
+
+```bash
+carboncanvas init                    # create or pick — see below
+carboncanvas init --name my-app      # explicit canvas name for a new canvas
+carboncanvas init --canvas cnv_xxx   # link an EXISTING canvas from your account
+carboncanvas init --new              # always create, never ask
+```
+
+What it does, in order:
+
+1. **Ensures you're signed in** — if there's no stored token it runs the
+   browser sign-in inline first. If a stored token turns out to be expired
+   (the API answers 401), `init` renews it automatically: it runs the browser
+   sign-in once ("Your sign-in expired — let's renew it.") and retries the
+   failed call once; a second 401 surfaces as an error.
+2. **Chooses the canvas:**
+   - `--canvas <cnv_…>` — links that existing canvas instead of creating one.
+     It must be in *your* account (checked against `GET /api/canvases`); an id
+     that isn't yours, an archived canvas, or a malformed id (no `cnv_` prefix)
+     exits 1 with a clear message. Nothing is created.
+   - Plain `init` when your account owns **no** canvases — creates one
+     (`POST /api/canvases`; the server mints the `cnv_…` id). The name comes
+     from `--name`, else the nearest `package.json` `name` (walking up from the
+     project dir), else the directory name.
+   - Plain `init` when your account **already owns canvases**:
+     - **In a terminal (TTY):** an interactive picker lists them (numbered,
+       name + id; archived ones excluded). Press Enter to create a new canvas
+       with the resolved name, or type a number to link that existing one.
+     - **Non-interactive (coding agents, CI, piped output):** `init` will
+       *not* guess. It prints your canvases (one `<id>  <name>` per line) and
+       exits 1 with instructions to re-run with `--canvas <id>` or `--new` —
+       so an agent can relay the choice instead of minting a surprise
+       duplicate. First-time accounts (zero canvases) still create
+       deterministically with no prompt.
+   - `--new` — always create; skips the picker and the non-interactive stop
+     entirely (no canvas listing round-trip).
+3. **Writes the env wiring** — carefully:
+   - `.env` — appends `VITE_CC_CANVAS_ID=<id>` and `VITE_CC_BACKEND=<url>`
+     (creates the file if absent, preserves everything already in it).
+     **Write-once:** if `VITE_CC_CANVAS_ID` already has a value, `init` touches
+     nothing, prints the existing id, and exits 1 — comments and review history
+     live on that id.
+   - `.env.example` — mirrors the two keys with placeholder values (skips keys
+     already present).
+   - `.gitignore` — adds a `.env` rule if none covers it.
+4. **Prints the handoff** — tell your coding agent the canvas is registered; it
+   wires the `comments` prop from these env vars (instructions at
+   `<serviceUrl>/skill.md`). The canvas id is the one machine-readable line on
+   stdout.
+
+Flags: `--name <name>`, `--dir <dir>` (project directory, default cwd),
+`--canvas <cnv_…>` (link an existing canvas), `--new` (always create), plus the
+common `--service-url` / `--token`. `--canvas` and `--new` are mutually
+exclusive.
+
+## `carboncanvas canvases`
+
+Lists the canvases in your account — so you (or your coding agent) can pick an
+id for `init --canvas` or `publish --canvas` at any time.
+
+```bash
+carboncanvas canvases
+```
+
+One canvas per stdout line, machine-readable: `<id>  <name>` (two spaces;
+`(unnamed)` if the canvas has no name), with a trailing `  [archived]` marker
+on soft-archived ones. Headers and the empty-account message go to stderr, so
+`carboncanvas canvases | grep cnv_` sees only canvas lines. Uses the same
+sign-in as `init`, including the automatic renewal on an expired token.
+
 ## `carboncanvas publish`
 
 Runs, in order:

package/dist/canvasApi.js

@@ -0,0 +1,102 @@
+// Canvas registration + listing for `carboncanvas init` — POST /api/canvases
+// and GET /api/canvases (existing endpoints, existing bearer auth; no new
+// server surface — see CONTRACT.md "carboncanvas init"). The server mints the
+// opaque `cnv_…` id on create; GET returns `{ canvases: CanvasView[] }`
+// (server/src/routes/canvases.ts), non-archived unless `includeArchived`.
+//
+// Both calls throw AuthExpiredError on 401 so initCommand can run the
+// device-code login once and retry (see initCommand's relogin wrapper).
+import { AuthExpiredError, UserError } from './errors.js';
+async function readErrorBody(res) {
+    try {
+        return (await res.json());
+    }
+    catch {
+        return {};
+    }
+}
+function unreachable(base, err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return new UserError(`Could not reach the Carbon Canvas backend at ${base} (${detail}). ` +
+        'Check your network and --service-url, then retry.');
+}
+export async function createCanvas(serviceUrl, token, name, fetchImpl = fetch) {
+    const base = serviceUrl.replace(/\/+$/, '');
+    let res;
+    try {
+        res = await fetchImpl(`${base}/api/canvases`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ name }),
+        });
+    }
+    catch (err) {
+        throw unreachable(base, err);
+    }
+    if (res.status === 200 || res.status === 201) {
+        const body = (await res.json());
+        if (!body.id) {
+            throw new UserError('The server accepted the canvas but returned no id. Try again.');
+        }
+        return { id: body.id, name: body.name ?? null };
+    }
+    const body = await readErrorBody(res);
+    switch (res.status) {
+        case 401:
+            throw new AuthExpiredError();
+        case 402:
+            throw new UserError(body.message ?? 'Creating another canvas is not included in your current plan.', 'Upgrade your plan on the dashboard (or archive a canvas), then retry.');
+        case 403:
+            throw new UserError(body.message ?? 'Your account is not allowed to create canvases.');
+        default:
+            throw new UserError(body.message ?? `Canvas registration failed with HTTP ${res.status}.`);
+    }
+}
+/**
+ * The account's own canvases (GET /api/canvases). Non-archived by default;
+ * `includeArchived` adds soft-archived ones (each carries `archivedAt`) so the
+ * `--canvas` link path can tell "archived" apart from "not yours".
+ */
+export async function listCanvases(serviceUrl, token, fetchImpl = fetch, includeArchived = false) {
+    const base = serviceUrl.replace(/\/+$/, '');
+    const url = `${base}/api/canvases${includeArchived ? '?includeArchived=1' : ''}`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${token}` },
+        });
+    }
+    catch (err) {
+        throw unreachable(base, err);
+    }
+    if (res.status === 200) {
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            throw new UserError('The server returned an unreadable canvas list. Try again.');
+        }
+        if (!Array.isArray(body.canvases)) {
+            throw new UserError('The server returned an unreadable canvas list. Try again.');
+        }
+        return body.canvases
+            .filter((c) => typeof c.id === 'string')
+            .map((c) => ({
+            id: c.id,
+            name: typeof c.name === 'string' ? c.name : null,
+            archivedAt: typeof c.archivedAt === 'string' ? c.archivedAt : null,
+        }));
+    }
+    if (res.status === 401) {
+        await readErrorBody(res); // drain
+        throw new AuthExpiredError();
+    }
+    const body = await readErrorBody(res);
+    throw new UserError(body.message ?? `Listing your canvases failed with HTTP ${res.status}.`);
+}
+//# sourceMappingURL=canvasApi.js.map

package/dist/canvasApi.js.map

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

package/dist/canvasesCommand.js

@@ -0,0 +1,25 @@
+// `carboncanvas canvases` — list the account's canvases so a user (or their
+// coding agent) can pick an id for `init --canvas` / `publish --canvas` at any
+// time. Same GET /api/canvases the init picker uses, same inline sign-in and
+// one-shot relogin (session.ts).
+//
+// Output contract: ONE canvas per stdout line — `<id>  <name>` (two spaces),
+// `(unnamed)` when the canvas has no name, a trailing `  [archived]` marker on
+// soft-archived ones. Headers/empty-state go to stderr, so
+// `carboncanvas canvases | grep …` sees only canvas lines.
+import * as log from './logger.js';
+import { listCanvases } from './canvasApi.js';
+import { openSession } from './session.js';
+export async function canvasesCommand(opts) {
+    const session = await openSession(opts, '`carboncanvas canvases`');
+    const owned = await session.withRelogin((tok) => listCanvases(opts.serviceUrl, tok, opts.fetchImpl, true));
+    if (owned.length === 0) {
+        log.info(`No canvases on ${opts.serviceUrl} yet. Run \`carboncanvas init\` to create one.`);
+        return;
+    }
+    log.info(`Canvases on ${opts.serviceUrl} — <id>  <name>:`);
+    for (const c of owned) {
+        log.out(`${c.id}  ${c.name ?? '(unnamed)'}${c.archivedAt ? '  [archived]' : ''}`);
+    }
+}
+//# sourceMappingURL=canvasesCommand.js.map

package/dist/canvasesCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasesCommand.js","sourceRoot":"","sources":["../src/canvasesCommand.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAC7E,iCAAiC;AACjC,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,2DAA2D;AAC3D,2DAA2D;AAE3D,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAC;AAI7D,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAqB;IACzD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,EAAE,CAC9C,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CACzD,CAAC;IAEF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,GAAG,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,UAAU,gDAAgD,CAAC,CAAC;QAC5F,OAAO;IACT,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,UAAU,kBAAkB,CAAC,CAAC;IAC3D,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,IAAI,WAAW,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpF,CAAC;AACH,CAAC"}

package/dist/constants.js

@@ -1,9 +1,15 @@
 // Shared constants for the Carbon Canvas CLI.
 //
-// The prod backend URL is the same Railway service the comments client talks to
-// (server/README.md: "running on Railway at https://quilt-production-65f6.up.railway.app").
-// It can be overridden per-invocation with `--service-url` or `CARBON_SERVICE_URL`.
-export const DEFAULT_SERVICE_URL = 'https://quilt-production-65f6.up.railway.app';
+// The prod backend is the hosted Carbon Canvas service (a custom domain in front
+// of the same Railway deployment the comments client talks to). It can be
+// overridden per-invocation with `--service-url` or `CARBON_SERVICE_URL`.
+export const DEFAULT_SERVICE_URL = 'https://app.carboncanvas.design';
+// LEGACY: the Railway-generated URL the service shipped on before the
+// app.carboncanvas.design custom domain existed. It still resolves (same
+// backend), and tokens stored under this key by older CLI versions are honored
+// via a read-time fallback in tokenStore — but it must never be presented to
+// customers as the service URL, and writes never use this key.
+export const LEGACY_SERVICE_URL = 'https://quilt-production-65f6.up.railway.app';
 // The command name a user types (bin name), used in help/error text.
 export const BIN_NAME = 'carboncanvas';
 // Client-side size caps (the server re-validates — these mirror plan §6b/B.3).

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,gFAAgF;AAChF,4FAA4F;AAC5F,oFAAoF;AACpF,MAAM,CAAC,MAAM,mBAAmB,GAAG,8CAA8C,CAAC;AAElF,qEAAqE;AACrE,MAAM,CAAC,MAAM,QAAQ,GAAG,cAAc,CAAC;AAEvC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,2BAA2B;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,iFAAiF;AACjF,0EAA0E;AAC1E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,mBAAmB,GAAG,iCAAiC,CAAC;AAErE,sEAAsE;AACtE,yEAAyE;AACzE,+EAA+E;AAC/E,6EAA6E;AAC7E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,8CAA8C,CAAC;AAEjF,qEAAqE;AACrE,MAAM,CAAC,MAAM,QAAQ,GAAG,cAAc,CAAC;AAEvC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,2BAA2B;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC"}

package/dist/deviceAuth.js

@@ -0,0 +1,137 @@
+// Device-code login flow — the CLI half of the `/api/cli-auth/*` contract
+// (see CONTRACT.md "CLI auth contract"). THE SHAPE HERE IS FIXED; the server is
+// built to match it byte-for-byte.
+//
+//   POST {serviceUrl}/api/cli-auth/start   {}            → { deviceCode, userCode, verifyUrl, expiresIn, interval }
+//   POST {serviceUrl}/api/cli-auth/poll    { deviceCode } → { status: "pending" }
+//                                                          | { status: "approved", token }
+//                                                          | { status: "expired" }
+//   429 on poll → slow down: double the interval for the next poll.
+//
+// The CLI never receives a browser callback — it POLLS, so the flow works in
+// cloud shells (Replit/Bolt/containers) where no browser can reach us back.
+import { spawn } from 'node:child_process';
+// Hard ceiling on how long we poll, whatever `expiresIn` says (~15 min).
+export const MAX_POLL_MS = 15 * 60 * 1000;
+/**
+ * Begin a grant. Returns null when the backend doesn't speak the device-code
+ * flow (older self-hosted deploys, network trouble) so the caller can fall back
+ * to the paste-token prompt instead of dying.
+ */
+export async function startDeviceGrant(serviceUrl, fetchImpl = fetch) {
+    const base = serviceUrl.replace(/\/+$/, '');
+    let res;
+    try {
+        res = await fetchImpl(`${base}/api/cli-auth/start`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({}), // contract: senders MUST send valid JSON
+        });
+    }
+    catch {
+        return null;
+    }
+    if (res.status !== 200)
+        return null;
+    try {
+        const body = (await res.json());
+        if (!body.deviceCode || !body.userCode || !body.verifyUrl)
+            return null;
+        return {
+            deviceCode: body.deviceCode,
+            userCode: body.userCode,
+            verifyUrl: body.verifyUrl,
+            expiresIn: typeof body.expiresIn === 'number' ? body.expiresIn : 900,
+            interval: typeof body.interval === 'number' && body.interval > 0 ? body.interval : 5,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Poll `/api/cli-auth/poll` until the grant is approved or expired (or we hit
+ * the ~15 min ceiling). Honors 429 by doubling the poll interval.
+ */
+export async function pollForApproval(serviceUrl, grant, opts = {}) {
+    const base = serviceUrl.replace(/\/+$/, '');
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? realSleep;
+    const now = opts.now ?? Date.now;
+    const heartbeatEveryMs = opts.heartbeatEveryMs ?? 30_000;
+    const deadline = now() + Math.min(grant.expiresIn * 1000, MAX_POLL_MS);
+    let intervalMs = Math.max(1, grant.interval) * 1000;
+    let lastBeat = now();
+    while (now() < deadline) {
+        await sleep(intervalMs);
+        let res;
+        try {
+            res = await fetchImpl(`${base}/api/cli-auth/poll`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ deviceCode: grant.deviceCode }),
+            });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return { status: 'unavailable', detail };
+        }
+        if (res.status === 429) {
+            intervalMs *= 2; // contract: slow down
+            continue;
+        }
+        if (res.status !== 200) {
+            return { status: 'unavailable', detail: `HTTP ${res.status}` };
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            return { status: 'unavailable', detail: 'unparseable poll response' };
+        }
+        if (body.status === 'approved' && body.token) {
+            return { status: 'approved', token: body.token };
+        }
+        if (body.status === 'pending') {
+            if (opts.heartbeat && now() - lastBeat >= heartbeatEveryMs) {
+                opts.heartbeat('Still waiting for approval in the browser …');
+                lastBeat = now();
+            }
+            continue;
+        }
+        // "expired" and anything unrecognized: the grant is gone (no oracle).
+        return { status: 'expired' };
+    }
+    return { status: 'expired' };
+}
+/**
+ * Best-effort browser open. Cloud shells have no browser — every failure is
+ * swallowed silently; the printed link + code are the real UX.
+ */
+export function openBrowser(url) {
+    try {
+        let cmd;
+        let args;
+        if (process.platform === 'darwin') {
+            cmd = 'open';
+            args = [url];
+        }
+        else if (process.platform === 'win32') {
+            cmd = 'cmd';
+            args = ['/c', 'start', '""', url];
+        }
+        else {
+            cmd = 'xdg-open';
+            args = [url];
+        }
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        // No browser here — fine. The user has the link and code on screen.
+    }
+}
+//# sourceMappingURL=deviceAuth.js.map

package/dist/deviceAuth.js.map

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

package/dist/envFiles.js

@@ -0,0 +1,110 @@
+// Env-file surgery for `carboncanvas init`. This touches files in the
+// CUSTOMER'S repo, so the rules are strict:
+//
+//   .env           — append the two VITE_CC_* lines, preserving everything
+//                    else byte-for-byte (create if absent). If a
+//                    VITE_CC_CANVAS_ID with a value already exists, touch
+//                    NOTHING — the id is write-once (comments live on it).
+//   .env.example   — mirror the two keys with placeholder values (create or
+//                    append; keys already present are left alone).
+//   .gitignore     — ensure a `.env` rule exists (append or create).
+//
+// All functions are pure fs against a project root — no network, no prompts.
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+export const ENV_CANVAS_KEY = 'VITE_CC_CANVAS_ID';
+export const ENV_BACKEND_KEY = 'VITE_CC_BACKEND';
+async function readIfExists(p) {
+    try {
+        return await fs.readFile(p, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+// Find `KEY=value` in dotenv-style content. Returns the (unquoted, trimmed)
+// value of the first assignment, or null when the key isn't assigned at all.
+function envValue(content, key) {
+    const re = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=(.*)$`);
+    for (const line of content.split(/\r?\n/)) {
+        const m = line.match(re);
+        if (m) {
+            let value = m[1].trim();
+            if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+                (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
+                value = value.slice(1, -1);
+            }
+            return value;
+        }
+    }
+    return null;
+}
+function hasEnvKey(content, key) {
+    return envValue(content, key) !== null;
+}
+/**
+ * The write-once guard: the canvas id already wired into `.env`, if any.
+ * An assignment with an EMPTY value doesn't count — only a real id blocks init.
+ */
+export async function existingCanvasId(root) {
+    const content = await readIfExists(path.join(root, '.env'));
+    if (content === null)
+        return null;
+    const value = envValue(content, ENV_CANVAS_KEY);
+    return value ? value : null;
+}
+// Append `block` to a file, preserving existing content and making sure the
+// block starts on its own line. Returns the action taken.
+async function appendBlock(p, block) {
+    const existing = await readIfExists(p);
+    if (existing === null) {
+        await fs.writeFile(p, block);
+        return 'created';
+    }
+    const glue = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    await fs.writeFile(p, existing + glue + block);
+    return 'appended';
+}
+/**
+ * Write the canvas wiring. Throws if a canvas id is already present with a
+ * value (callers should check `existingCanvasId` first — this re-check is the
+ * last line of defense against clobbering a live canvas binding).
+ */
+export async function writeEnvFiles(root, canvasId, serviceUrl) {
+    const already = await existingCanvasId(root);
+    if (already) {
+        throw new Error(`Refusing to write: ${ENV_CANVAS_KEY} already set (${already}).`);
+    }
+    // 1. .env — the real values.
+    const envBlock = '# Carbon Canvas (added by `carboncanvas init`)\n' +
+        `${ENV_CANVAS_KEY}=${canvasId}\n` +
+        `${ENV_BACKEND_KEY}=${serviceUrl}\n`;
+    const env = await appendBlock(path.join(root, '.env'), envBlock);
+    // 2. .env.example — placeholders only, and only for keys not already there.
+    const examplePath = path.join(root, '.env.example');
+    const exampleContent = (await readIfExists(examplePath)) ?? '';
+    const missing = [];
+    if (!hasEnvKey(exampleContent, ENV_CANVAS_KEY)) {
+        missing.push(`${ENV_CANVAS_KEY}=cnv_your_canvas_id`);
+    }
+    if (!hasEnvKey(exampleContent, ENV_BACKEND_KEY)) {
+        missing.push(`${ENV_BACKEND_KEY}=${serviceUrl}`);
+    }
+    let envExample = 'unchanged';
+    if (missing.length > 0) {
+        envExample = await appendBlock(examplePath, '# Carbon Canvas (run `carboncanvas init` to fill these in)\n' + missing.join('\n') + '\n');
+    }
+    // 3. .gitignore — make sure `.env` never gets committed.
+    const gitignorePath = path.join(root, '.gitignore');
+    const gitignoreContent = await readIfExists(gitignorePath);
+    const covered = (gitignoreContent ?? '')
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .some((l) => l === '.env' || l === '/.env' || l === '.env*' || l === '*.env');
+    let gitignore = 'unchanged';
+    if (!covered) {
+        gitignore = await appendBlock(gitignorePath, '.env\n');
+    }
+    return { env, envExample, gitignore };
+}
+//# sourceMappingURL=envFiles.js.map