@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/README.md

@@ -1,32 +1,271 @@
 # moeicons
 
 Public CLI for the Moeicons icon library. Installs icon style groups into your
-project, manages login/tokens, generates React/Vue proxy components, and exposes
-an MCP server for AI clients.
+project, manages login/tokens, generates React/Vue proxy components, syncs the
+AI manual + icon catalog, and exposes an MCP server for AI clients.
 
 ## Commands
 
 ```text
 moeicons                    interactive guided flow (free / pro / login)
-moeicons install [group]    install an icon group
+moeicons install [group]    install an icon group (free | pro)
 moeicons login              browser login (PKCE)
 moeicons logout             clear local session
 moeicons account            show account/tier info
-moeicons groups             list available icon groups
- moeicons generate           generate target-specific project files
+moeicons generate           generate target-specific project files
+moeicons doctor --check     check configuration and integration
+moeicons recover            recover an interrupted transaction
+moeicons init               create moeicons.config.jsonc
+moeicons update metadata    sync MANUAL.md/catalog.json/manifest.json only
+moeicons update             full code + metadata update
 moeicons mcp                start the MCP stdio server
- npm install -g @moewolf/moe-icons-cli
- moeicons --version          show version
+moeicons --version          show version
 moeicons --help             show help
 ```
 
+## Requirements
+
+Node.js **22 or later**. Node 20 reached end-of-life on 2026-03-24 and is not
+on the supported line (no security patches). The CLI fails fast with an install
+link instead of a `SyntaxError` if the runtime is too old.
+
+Primary development and CI use Node 24. See https://nodejs.org/en/about/eol
+
+**Platforms:** Linux x64 and macOS ARM64 use Node 22/24 in CI. Windows x64
+verification covers Node 22/24, npm/pnpm, Free React/Vue core commands,
+production builds and interrupted-write recovery. Windows Pro authentication
+and interactive terminal/PTY behavior are outside this verified scope.
+
+## Framework support
+
+| Target | Current integration |
+| --- | --- |
+| Vite React / Vite Vue | Generated local proxies; use `init` → `install` → `generate` |
+| Tailwind CSS 3 | Content glob added to a supported static config |
+| Tailwind CSS 4 or no Tailwind | Core icon dimensions work without a Tailwind config rewrite |
+| Next App Router / Nuxt SSR | Generated local components verified with single/multiple themes, production server rendering and browser hydration |
+| Vanilla DOM | SVG factories and project runtime; bitmap style groups are unavailable |
+| Windows x64 | Free React/Vue core flow verified on Node 22/24 with npm/pnpm |
+
+Next Pages Router and custom Nuxt modules require their own integration checks.
+Custom bootstrap shapes can require manual Provider placement; `doctor --check`
+reports unsupported integration shapes.
+
+## First run
+
+On the first interactive start inside a project, the CLI offers to install the
+Free icon library plus its metadata (manual + catalog + manifest). The
+completion marker lives in the cache directory and is only written after a
+successful install; failures print a retry command and never suppress retry.
+
+For a React or Vue project, the explicit path is:
+
+```sh
+npm install -D @moewolf/moe-icons-cli
+npx moeicons init
+npx moeicons install free
+npx moeicons generate
+```
+
+Edit `moeicons.config.jsonc` before generating to select the icon IDs and
+themes you need. When changing React/Vue/Vanilla/assets target, edit the config
+first, then run `moeicons install free --target <target>` and `moeicons generate`.
+For React/Vue, installation now keeps only the configured SVG component modules
+and their required files in `.moeicons/artifact`. After adding icon IDs to the
+config, run `moeicons install` again before `moeicons generate`; generate reports
+the missing installed component if this step is skipped. New releases support
+selected-resource downloads as well as full archives; `downloadMode` controls
+this choice. Legacy releases without resource indexes still use a full archive
+in `auto` mode. See Download modes and resource selection below.
+Each theme may select a subset of the registered project icons:
+
+```json
+{
+  "icons": ["ui-search", "arrow-bold-right"],
+  "defaultTheme": "outline",
+  "missingIconPolicy": "fallback",
+  "themes": {
+    "outline": { "styleGroup": "moe-outline", "icons": ["ui-search"] },
+    "solid": { "styleGroup": "moe-solid", "icons": ["arrow-bold-right"] }
+  }
+}
+```
+
+Omitting a theme's `icons` selects all registered icons; `[]` selects none.
+Fallback searches the requested theme, then the default theme, then configured
+themes in ASCII name order. An unregistered icon or an icon unavailable in every
+selected theme fails validation/generation. `error` requires each theme to have
+every registered icon. Adding a selected variant requires installing again.
+
+Transactions preserve a recovery journal with original bytes in
+`.moeicons/.reconcile-backup-<id>/files`. After a process interruption, run `moeicons recover` at the project root
+before rerunning the original command. It reclaims a lock only when its owner
+process is dead, restores the previous state, and requires a fresh plan. If a file changed after the interruption, recovery stops and retains both
+the user's file and the backups; compare them before restoring manually. A
+completed transaction is identified by its commit marker and is never rolled
+back because backup cleanup failed. Do not delete these directories to bypass
+a recovery conflict. Recovery covers process termination, not power loss or a
+hostile filesystem replacing directories during filesystem operations.
+
+The installer rejects a target that disagrees with the config. Import generated
+PascalCase components from your configured `outputDir` (default `src/moeicons`):
+
+```tsx
+import { ArrowBoldRight, MoeiconsProvider } from './moeicons';
+
+export function App() {
+  return <MoeiconsProvider><ArrowBoldRight size={37} aria-label="Next" /></MoeiconsProvider>;
+}
+```
+
+Vue uses the same generated names and output directory. The CLI imports the
+version-pinned code in `.moeicons/artifact`; `generate` requires a completed
+`install`. After generation, install any dependencies reported by the CLI with
+your package manager before type checking or building. Commit the config,
+generated source, `.moeicons/artifact` and install metadata together if CI must
+build without downloading the library. Treat all of them as one versioned set.
+
+## Metadata
+
+Installing or updating a tier writes `<project>/.moeicons/`:
+
+```text
+.moeicons/
+├── MANUAL.md       # human/agent manual (generated by the builder)
+├── catalog.json    # machine-queryable icon catalog (JSON only)
+├── manifest.json   # schema, tier, versions, dependencies, digests
+├── install-metadata.json
+└── artifact/<target>/
+```
+
+`moeicons update metadata` re-downloads only the small metadata archive for the
+installed code version and reconciles the three files, without touching the
+code artifact.
+
+## Pro resources
+
+After an authenticated login (TTY) the CLI offers a one-time pre-download of the
+full Pro code + metadata. If skipped, the authenticated home screen shows the
+resource state and offers `Download / Update / Repair Pro resources`. Logging
+out keeps cached archives but blocks new unauthenticated installs/updates.
+
 ## Security
 
 - Tokens are stored in the OS keychain where available.
-- API keys are never logged or written in plaintext.
+- API keys are never logged, written in plaintext, passed to subprocesses, or
+  embedded in `.moeicons/manifest.json`.
 - Installation is transactional: failures never corrupt an existing project.
-- Downloads verify SHA-256 and never shell out to `unzip`/`tar`.
+- Downloads verify SHA-256 and size, never shell out to `unzip`/`tar`, enforce
+  host allowlists and bounded redirects/timeouts, and never forward API
+  credentials to signed asset hosts.
+- Code and metadata archives must pass a manifest compatibility check
+  (tier/version/digests); mismatches fail loudly instead of mixing tiers.
+
+## Environment
+
+| variable | purpose |
+| --- | --- |
+| `MOEICONS_CACHE_DIR` | global artifact/metadata cache (default `~/.moeicons/cache`) |
+| `MOEICONS_FREE_RELEASE_DIR` | test-only free release fixture directory |
+| `MOEICONS_BOOTSTRAP_FILE` | override bootstrap completion marker path |
+| `MOEICONS_PRO_DESCRIPTOR_URL` | test-only Pro descriptor endpoint override (https or loopback http) |
+| `MOEICONS_LIBRARY_VERSIONS_URL` | test-only library versions endpoint override (https or loopback http) |
+| `MOEICONS_TOKEN_STORE_DIR` | 0600 file token store directory |
+| `MOEICONS_DISABLE_SYSTEM_KEYCHAIN` | `1` disables OS keychain storage |
+| `MOEICONS_AUTH0_ISSUER` / `MOEICONS_AUTH0_CLIENT_ID` | Auth0 refresh/revoke |
 
 ## Status
 
-Scaffold in progress (Phase 5 of the Moeicons development plan).
+Metadata distribution (`MANUAL-DIST`) implemented: builder-generated manual,
+catalog and manifest, per-tier archives and descriptors, Free bootstrap,
+metadata-only sync, and authenticated Pro pre-download/update.
+
+### Download modes and resource selection
+
+Set `downloadMode` in `moeicons.config.jsonc` (schemaVersion 3):
+
+```json
+{
+  "schemaVersion": 3,
+  "tier": "free",
+  "target": "react",
+  "outputDir": "src/icons",
+  "downloadMode": "auto",
+  "icons": ["ui-search", "arrow-bold-right"],
+  "defaultTheme": "outline",
+  "themes": {
+    "outline": { "styleGroup": "moe-outline", "icons": ["ui-search"] },
+    "solid": { "styleGroup": "moe-solid", "icons": ["arrow-bold-right"] }
+  },
+  "missingIconPolicy": "fallback"
+}
+```
+
+- `auto` (default): selected resources when the fixed release advertises them. A legacy release without this capability uses the full archive and explains why.
+- `icons`: require selected resources. Unsupported releases, authorization failures, bad ranges and invalid digests stop the operation; they never trigger a full archive download.
+- `full`: download and verify the complete archive, then install the configured target/resources.
+
+`icons` registers the allowed icon IDs. Install/update requires at least one global icon ID; an empty global list stops before version queries or downloads and preserves the existing installation. An individual theme may still use `icons: []`. A theme's `icons` restricts that theme to a subset; omitting it selects every registered ID available in the style group, and `[]` selects none. Fallback chooses the requested theme, then the default theme, then theme names in ASCII order. An icon with no selected variant fails validation. Bitmap themes also select `format` and `imageSize`; changing these fields may require new resources.
+
+The CLI reads the release metadata before planning resources, so validation uses that release's catalog. It shows the target, registered icon/theme counts, required file count and compressed payload budget before reading the data object. Verified cache entries reduce traffic. `--json` reports `downloadMode`, `downloadNotes`, `selectedFiles` and `networkBytes` (resource payload only; descriptor/metadata/index traffic is separate).
+
+Run `moeicons install free` or `moeicons install pro` after changing the selected icons, themes, bitmap format or size, then `moeicons generate`. `moeicons update` also reconciles the configuration when the release version is unchanged. Missing resources name the affected path and ask for reinstall; stale resources are removed only if still owned and unmodified. A configuration change during download stops before project writes; retry with the final configuration.
+
+Generation works offline from the project's verified installed resources; `moeicons recover` also needs no network. Install/update still consult the fixed descriptor and metadata, and Pro checks current entitlement. A resource cache hit does not bypass authorization, and there is no offline install flag. Corrupt cache entries are rejected and fetched again online. Interrupted downloads retain only verified cache members; project files change in one recoverable transaction after all required resources have verified.
+
+Version queries have a deadline covering both response headers and body, with bounded JSON sizes. Invalid or unavailable version responses make update fail explicitly. Cache cleanup preserves staging files owned by a live process; disk-full and permission failures report actionable errors.
+
+## MCP project integration
+
+Run `moeicons mcp` in the project root containing `package.json`. Use a fixed,
+installed CLI executable in your MCP client's command configuration:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/node_modules/@moewolf/moe-icons-cli/bin/moeicons.js", "mcp"],
+  "cwd": "/absolute/path/to/your/project"
+}
+```
+
+The client must support a working directory for subprocesses. The server uses
+stdio and needs no port. Log in with `moeicons login` outside the MCP server;
+never place credentials in client configuration or browser source code.
+
+Use `init_config` (explicit `target: "vue"` for mixed-framework projects), then
+`get_project_config` to obtain the current config hash. `list_icon_groups` and
+`find_icons` expose installed, verified catalog data when available; bundled
+results are identified separately. Call `update_config` with `expectedHash` and
+an explicit patch, `install` with the configured tier, then `generate`.
+`update` updates icon resources, not the CLI executable. Changes to selection
+require resource reconciliation before generation. Read `get_usage_guide` and
+the installed manual before editing application code.
+
+For example, add or remove selections without replacing the whole config:
+
+```json
+{
+  "expectedHash": "<hash from get_project_config>",
+  "patch": {
+    "icons": { "add": ["dashboard"], "remove": ["weather-sun"] }
+  },
+  "dryRun": true
+}
+```
+
+Review the dry-run diff, then call with `dryRun: false`. If the config changed,
+read it again and revise the patch. Generated files are owned by the generator:
+import their named exports rather than editing them. Install the runtime
+`clsx` and a `tailwind-merge` version compatible with your Tailwind version.
+For Vue, put `MoeiconsProvider` around all consuming components and bind its
+`theme` to an exact configured theme key. Give decorative icons `aria-hidden`
+and bitmap icons empty `alt`; icon-only controls require accessible labels.
+Custom application bootstrap can require manual Provider placement; doctor
+reports unsupported shapes rather than certifying them automatically.
+
+Available tools: `list_icon_groups`, `get_account`, `get_project_config`,
+`find_icons`, `get_usage_guide`, `init_config`, `update_config`, `install`,
+`update`, and `generate`. The legacy `install_icon_group` tool remains an
+explicit unsupported operation with migration guidance. Tool failures use
+`isError`; malformed protocol arguments use JSON-RPC errors. The server binds
+all operations to one project root and does not expose arbitrary shell commands.

package/bin/check-node.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+var MIN_MAJOR = 22;
+var LTS_URL = "https://nodejs.org/en/download";
+var EOL_URL = "https://nodejs.org/en/about/eol";
+
+function parseMajor(version) {
+  var raw = String(version || "").replace(/^v/, "");
+  var major = parseInt(raw.split(".")[0], 10);
+  if (!isFinite(major)) return null;
+  return major;
+}
+
+function assertSupportedNode(version) {
+  var major = parseMajor(version);
+  var display = String(version || "").charAt(0) === "v" ? String(version) : "v" + String(version);
+  if (major === null || major < MIN_MAJOR) {
+    return {
+      ok: false,
+      major: major,
+      message:
+        "moeicons requires Node.js " + MIN_MAJOR + " or later (you have " + display + ").\n" +
+        "Node " + (major === null ? display : major) + " is outside the supported line. Node 20 reached end-of-life on 2026-03-24 and no longer receives security patches.\n" +
+        "Install the current Node.js LTS: " + LTS_URL + "\n" +
+        "Policy: " + EOL_URL + "\n",
+    };
+  }
+  return { ok: true, major: major, message: "" };
+}
+
+module.exports = {
+  MIN_MAJOR: MIN_MAJOR,
+  LTS_URL: LTS_URL,
+  parseMajor: parseMajor,
+  assertSupportedNode: assertSupportedNode,
+};

package/bin/moeicons.js

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
-import { main } from "../dist/cli.js";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const { assertSupportedNode } = require("./check-node.cjs");
+const checked = assertSupportedNode(process.version);
+if (!checked.ok) {
+  process.stderr.write(checked.message);
+  process.exit(1);
+}
+
+const { main } = await import("../dist/cli.js");
 
 const runtime = {
   cwd: () => process.cwd(),
@@ -7,6 +17,7 @@ const runtime = {
   stderr: (text) => process.stderr.write(text),
   env: process.env,
   isTTY: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  columns: () => process.stdout.columns,
 };
 
 main(process.argv.slice(2), runtime).then(

package/dist/api/client.d.ts

@@ -16,15 +16,26 @@ export interface RequestJsonOptions {
     readonly signal?: AbortSignal;
     readonly retries?: number;
     readonly requestId?: string;
+    /** Optional stage label included in transport diagnostics (e.g. login create). */
+    readonly stage?: string;
+    /**
+     * Opt-in debug only. Default user-facing errors never include response body
+     * text (kind + byte length only). When true, JSON bodies may include a
+     * recursively redacted preview; HTML/opaque bodies are still omitted.
+     */
+    readonly debugBodyPreview?: boolean;
 }
 export interface ApiResult<T> {
     readonly status: number;
     readonly data: T;
     readonly requestId: string;
 }
+/** Recursively redact secret keys and secret-shaped leaf values for debug previews only. */
+export declare function redactJsonForPreview(value: unknown): unknown;
 /**
- * Perform a JSON request against the fixed base URL. Retries GET/idempotent
- * calls with capped exponential backoff on 5xx and network errors.
+ * Perform a JSON request against the fixed base URL. Retries GET/DELETE
+ * (idempotent) calls with capped exponential backoff on 5xx and network errors.
+ * POST/PUT never retry. External AbortSignal stops immediately without retry.
  */
 export declare function requestJson<T>(config: ApiConfig, path: string, options?: RequestJsonOptions): Promise<ApiResult<T>>;
 export interface ApiKeyEntitlement {

package/dist/api/client.js

@@ -1,14 +1,91 @@
 import { CliError } from "../errors/index.js";
+const SECRET_KEY = /^(access[_-]?token|refresh[_-]?token|polling[_-]?token|exchange[_-]?code|code[_-]?verifier|authorization|password|secret|cookie|set-cookie|email)$/i;
+const JWT_LIKE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const BEARER_LIKE = /^Bearer\s+\S+/i;
+const EMAIL_LIKE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isIdempotentMethod(method) {
+    return method === "GET" || method === "DELETE";
+}
+function bodyKind(text, contentType) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return "empty";
+    const lower = (contentType ?? "").toLowerCase();
+    if (lower.includes("text/html") || /^<!doctype html/i.test(trimmed) || /^<html/i.test(trimmed)) {
+        return "html";
+    }
+    if (lower.includes("application/json") || lower.includes("+json"))
+        return "json-declared";
+    if (trimmed.startsWith("{") || trimmed.startsWith("["))
+        return "json-looking";
+    if (lower.includes("text/plain"))
+        return "text/plain";
+    return "opaque";
+}
+/** Recursively redact secret keys and secret-shaped leaf values for debug previews only. */
+export function redactJsonForPreview(value) {
+    if (Array.isArray(value))
+        return value.map(redactJsonForPreview);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = SECRET_KEY.test(key) ? "[redacted]" : redactJsonForPreview(nested);
+        }
+        return out;
+    }
+    if (typeof value === "string") {
+        if (JWT_LIKE.test(value) || BEARER_LIKE.test(value) || EMAIL_LIKE.test(value))
+            return "[redacted]";
+        if (/[?&](access_token|refresh_token|code|token)=/i.test(value))
+            return "[redacted-url]";
+        return value;
+    }
+    return value;
+}
+function summarizeBody(text, contentType, debugBodyPreview) {
+    const kind = bodyKind(text, contentType);
+    const base = `body=${kind}, ${text.length} bytes`;
+    if (!debugBodyPreview)
+        return base;
+    if (kind === "html" || kind === "opaque" || kind === "empty" || kind === "text/plain") {
+        return base;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        const redacted = redactJsonForPreview(parsed);
+        const preview = JSON.stringify(redacted).replace(/\s+/g, " ").slice(0, 120);
+        return `${base}, preview=${JSON.stringify(preview)}`;
+    }
+    catch {
+        return base;
+    }
+}
+function transportError(stage, status, contentType, text, reason, debugBodyPreview) {
+    const stagePrefix = stage ? `${stage}: ` : "";
+    const ct = contentType ?? "unknown";
+    const message = `${stagePrefix}${reason} (HTTP ${status}, content-type=${ct}, ${summarizeBody(text, contentType, debugBodyPreview)})`;
+    if (status === 401)
+        return new CliError("AUTH_ERROR", message);
+    if (status === 403)
+        return new CliError("FORBIDDEN", message);
+    if (status === 404)
+        return new CliError("NOT_FOUND", message);
+    if (status === 0)
+        return new CliError("NETWORK_ERROR", message);
+    return new CliError("VALIDATION_ERROR", message);
+}
 /**
- * Perform a JSON request against the fixed base URL. Retries GET/idempotent
- * calls with capped exponential backoff on 5xx and network errors.
+ * Perform a JSON request against the fixed base URL. Retries GET/DELETE
+ * (idempotent) calls with capped exponential backoff on 5xx and network errors.
+ * POST/PUT never retry. External AbortSignal stops immediately without retry.
  */
 export async function requestJson(config, path, options = {}) {
     const method = options.method ?? "GET";
     const retries = options.retries ?? 0;
     const timeoutMs = config.timeoutMs ?? 10_000;
-    const requestId = options.requestId ??
-        `req-${Math.random().toString(36).slice(2, 10)}`;
+    const requestId = options.requestId ?? `req-${Math.random().toString(36).slice(2, 10)}`;
+    const debugBodyPreview = options.debugBodyPreview === true;
+    const canRetry = isIdempotentMethod(method) && retries > 0;
     const attempt = async () => {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -23,13 +100,26 @@ export async function requestJson(config, path, options = {}) {
             headers[options.authHeader ?? "authorization"] = options.auth;
         }
         try {
-            const response = await fetch(`${config.baseUrl.replace(/\/$/, "")}${path}`, {
-                method,
-                headers,
-                ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
-                signal: controller.signal,
-            });
+            let response;
+            try {
+                response = await fetch(`${config.baseUrl.replace(/\/$/, "")}${path}`, {
+                    method,
+                    headers,
+                    ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+                    signal: controller.signal,
+                });
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === "AbortError") {
+                    if (externalSignal?.aborted) {
+                        throw new CliError("NETWORK_ERROR", `${options.stage ? `${options.stage}: ` : ""}request was aborted`);
+                    }
+                    throw new RetryableTransportError(`${options.stage ? `${options.stage}: ` : ""}request timed out`);
+                }
+                throw new RetryableTransportError(`${options.stage ? `${options.stage}: ` : ""}network error (${error instanceof Error ? error.message : String(error)})`);
+            }
             const text = await response.text();
+            const contentType = response.headers.get("content-type");
             if (text.length > (config.maxBodyBytes ?? 5 * 1024 * 1024)) {
                 throw new CliError("VALIDATION_ERROR", "response body exceeds size limit");
             }
@@ -39,21 +129,35 @@ export async function requestJson(config, path, options = {}) {
                     data = JSON.parse(text);
                 }
                 catch {
-                    throw new CliError("VALIDATION_ERROR", "response is not valid JSON");
+                    throw transportError(options.stage, response.status, contentType, text, "response is not valid JSON", debugBodyPreview);
                 }
             }
-            if (response.status === 401)
-                throw new CliError("AUTH_ERROR", "unauthorized");
-            if (response.status === 403)
-                throw new CliError("FORBIDDEN", "forbidden");
+            else if (response.ok) {
+                data = null;
+            }
+            else {
+                throw transportError(options.stage, response.status, contentType, text, "empty error response", debugBodyPreview);
+            }
+            if (response.status === 401) {
+                throw transportError(options.stage, response.status, contentType, text, "unauthorized", debugBodyPreview);
+            }
+            if (response.status === 403) {
+                throw transportError(options.stage, response.status, contentType, text, "forbidden", debugBodyPreview);
+            }
             if (response.status === 429) {
-                throw new CliError("NETWORK_ERROR", "rate limited");
+                if (canRetry) {
+                    throw new RetryableTransportError(`${options.stage ? `${options.stage}: ` : ""}rate limited`);
+                }
+                throw new CliError("NETWORK_ERROR", `${options.stage ? `${options.stage}: ` : ""}rate limited`);
             }
-            if (response.status >= 500 && retries > 0) {
-                throw new RetryableStatus(response.status);
+            if (response.status >= 500) {
+                if (canRetry) {
+                    throw new RetryableStatus(response.status);
+                }
+                throw transportError(options.stage, response.status, contentType, text, `request failed with ${response.status}`, debugBodyPreview);
             }
             if (response.status >= 400) {
-                throw new CliError("NETWORK_ERROR", `request failed with ${response.status}`);
+                throw transportError(options.stage, response.status, contentType, text, `request failed with ${response.status}`, debugBodyPreview);
             }
             return { status: response.status, data: data, requestId };
         }
@@ -68,13 +172,27 @@ export async function requestJson(config, path, options = {}) {
             return await attempt();
         }
         catch (error) {
-            if (error instanceof CliError)
+            if (error instanceof CliError) {
+                // Auth / schema / validation / not-found never retry.
                 throw error;
-            if (error instanceof RetryableStatus && i < retries) {
+            }
+            if (options.signal?.aborted) {
+                throw new CliError("NETWORK_ERROR", `${options.stage ? `${options.stage}: ` : ""}request was aborted`);
+            }
+            const retryable = canRetry &&
+                i < retries &&
+                (error instanceof RetryableStatus || error instanceof RetryableTransportError);
+            if (retryable) {
                 const backoff = Math.min(500 * 2 ** i, 4000);
                 await new Promise((resolve) => setTimeout(resolve, backoff));
                 continue;
             }
+            if (error instanceof RetryableTransportError) {
+                throw new CliError("NETWORK_ERROR", error.message);
+            }
+            if (error instanceof RetryableStatus) {
+                throw new CliError("NETWORK_ERROR", `${options.stage ? `${options.stage}: ` : ""}request failed with ${error.status}`);
+            }
             lastError = error;
         }
     }
@@ -87,6 +205,12 @@ class RetryableStatus extends Error {
         this.status = status;
     }
 }
+class RetryableTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RetryableTransportError";
+    }
+}
 /**
  * Verify an API key. Trim once, never log, send via the configured header,
  * map 401/403/429/5xx distinctly. No persistent storage by default.

package/dist/auth/device-login.d.ts

@@ -1,17 +1,20 @@
-import type { StoredSession, TokenStore } from './token-store.js';
+import type { StoredSession, TokenStore } from "./token-store.js";
 export interface DeviceLoginConfig {
     readonly apiBaseUrl: string;
     readonly websiteOrigin: string;
     readonly auth0Issuer: string;
     readonly auth0ClientId: string;
 }
+export type LoginRequestStage = "create" | "poll" | "exchange" | "cleanup";
+export interface DeviceLoginRequestOptions {
+    readonly method: "GET" | "POST" | "DELETE";
+    readonly auth?: string;
+    readonly body?: unknown;
+    readonly signal?: AbortSignal;
+    readonly stage?: LoginRequestStage;
+}
 export interface DeviceLoginDependencies {
-    readonly request: <T>(path: string, options: {
-        method: 'GET' | 'POST' | 'DELETE';
-        auth?: string;
-        body?: unknown;
-        signal?: AbortSignal;
-    }) => Promise<{
+    readonly request: <T>(path: string, options: DeviceLoginRequestOptions) => Promise<{
         status: number;
         data: T;
     }>;