@ahood/cli 0.9.0 → 0.10.1

package/dist/help.js

@@ -1,3 +1,27 @@
+// Canonical command list for terminal --help output. Kept in sync by hand
+// with cli/README.md's table and app/docs/page.tsx's COMMANDS array (three
+// copies of the same list, none of which can literally import from this
+// file -- README.md is plain markdown and the docs page is a separate
+// Next.js app) -- a comment in each of those two places points back here so
+// a future command addition doesn't update only one.
+//
+// The command surface is split into two tiers, gh-style:
+//   - TOP_LEVEL_COMMANDS_HELP: account/auth-scoped commands that stay flat
+//     (login, logout, whoami, token, completion) -- same reasoning
+//     `gh auth login` isn't `gh account login`.
+//   - SKILL_COMMANDS_HELP: every registry verb, reached as `ahood skill
+//     <verb>` -- legacy and cross-kind in this release (ahood-cli#172).
+//   - AGENT_COMMANDS_HELP / MCP_COMMANDS_HELP: the same verbs, kind-scoped,
+//     generated from one template (registryCommandsHelp); MCP's list also
+//     carries `ahood mcp` / `ahood mcp serve`, the local stdio server.
+//   - GROUP_COMMANDS_HELP / SNAP_COMMANDS_HELP: the other entity nouns.
+//
+// `summary` is a genuinely one-sentence blurb used only by the top-level
+// `ahood --help` / `ahood skill --help` listings. `desc` is the full
+// (possibly multi-sentence) description rendered in full by `ahood help
+// <command>` / `ahood skill <verb> --help`. Keep `summary` self-contained --
+// it must not depend on the reader having also seen `desc`.
+import { KINDS } from "./kind-info.js";
 export const TOP_LEVEL_COMMANDS_HELP = [
     {
         usage: "ahood login",
@@ -27,12 +51,15 @@ export const TOP_LEVEL_COMMANDS_HELP = [
         examples: ["ahood completion bash >> ~/.bashrc"],
     },
     {
-        usage: "ahood mcp",
-        summary: "Start an MCP server exposing read-only skill commands as tools over stdio.",
-        desc: "Start a Model Context Protocol server over stdio, exposing skill_search, skill_view, skill_read, " +
-            "skill_versions, skill_list, skill_outdated, and whoami as MCP tools -- the same data ahood's --json " +
-            "commands already return, reachable as typed tool calls instead of parsed CLI output. Meant to be " +
-            "launched by an MCP-aware agent host (e.g. Claude Code's MCP server configuration), not run interactively.",
+        usage: "ahood help useme",
+        summary: "Print the bundled ahood SKILL.md for an AI agent -- raw, offline, no login needed.",
+        desc: "Print the ahood self-skill bundled with this exact CLI version: a complete SKILL.md teaching an AI agent " +
+            "(or a human) when and how to use ahood. Stdout is the raw file and nothing else -- no banner, no colors -- " +
+            "so it can be pasted into an agent's context, redirected into a file, or read directly by an agent with " +
+            "shell access. Works offline and without credentials, and never writes to your project. It is not the " +
+            "same as `ahood skill add alexkay/ahood`, which installs the registry-published copy as a separate, " +
+            "pinned project skill.",
+        examples: ["ahood help useme", "ahood help useme > ahood-SKILL.md"],
     },
 ];
 export const SKILL_COMMANDS_HELP = [
@@ -206,6 +233,182 @@ export const SKILL_COMMANDS_HELP = [
         ],
     },
 ];
+// Kind-scoped registry verbs (ahood-cli#172): `ahood agent <verb>` and
+// `ahood mcp <verb>` take the same verbs as `ahood skill <verb>`, run by the
+// same handlers, but strictly for their own kind -- a target of another kind
+// is refused before any side effect. Generated from one template per verb
+// rather than hand-copied twice, so the two lists can't drift from each other.
+// SKILL_COMMANDS_HELP above stays hand-written: it documents the legacy,
+// cross-kind behavior `ahood skill` keeps in this release.
+function registryCommandsHelp(kind) {
+    const info = KINDS[kind];
+    const n = kind === "agent" ? "<agent>" : "<server>";
+    const p = `ahood ${kind}`;
+    const label = info.label;
+    const a = info.article;
+    const plural = info.plural;
+    const doc = info.rootDoc;
+    const ex = kind === "agent" ? "alice/code-reviewer" : "alice/github-server";
+    const kindRefusal = `Refused, before anything else happens, when the target is not ${a} ${label}.`;
+    return [
+        {
+            usage: `${p} search <query> [--json] [--limit <n>]`,
+            summary: `Search published ${plural}.`,
+            desc: `Search published ${plural} only (the registry's ?kind=${kind} filter). Same output and --json shape as \`ahood skill search\`.`,
+            flags: ["--json        Emit the raw result objects instead of formatted lines.", "--limit <n>   Cap the number of results."],
+            examples: [`${p} search github`],
+        },
+        {
+            usage: `${p} view <owner>/${n} [--json] [--web]`,
+            summary: `Show a single ${label}'s details without installing it (alias: ${p} show).`,
+            desc: `Show a single ${label}'s details without installing it. Alias: ${p} show. ${kindRefusal}`,
+            flags: ["--json   Emit the raw object instead of formatted lines.", "--web    Open its page in your browser instead of printing."],
+        },
+        {
+            usage: `${p} read <owner>/${n} [--json]`,
+            summary: `Print a published ${label}'s ${doc}, without installing it.`,
+            desc: `Print the ${doc} of a published ${label} verbatim, without installing it -- read it before you add it. ${kindRefusal}`,
+            flags: ["--json    Emit {version, content} as a single line instead of the raw content."],
+            examples: [`${p} read ${ex}`],
+        },
+        {
+            usage: `${p} versions <owner>/${n} [--json]`,
+            summary: `List a ${label}'s published-version history.`,
+            desc: `List a ${label}'s published-version history: version, changelog, size, and publish date. ${kindRefusal}`,
+            flags: ["--json    Emit the raw version objects instead of formatted text."],
+        },
+        {
+            usage: `${p} diff <owner>/${n} <versionA> <versionB> [--json]`,
+            summary: `Show what changed between two published versions of ${a} ${label}.`,
+            desc: `Show what changed between two published versions, exactly like \`ahood skill diff\`. Both versions must be explicit semver. ${kindRefusal}`,
+            flags: ["--json    Emit {skillmd_diff, manifest: {added, removed, changed}} instead of formatted text."],
+        },
+        {
+            usage: `${p} list [--json]`,
+            summary: `List your own ${plural}, public and private.`,
+            desc: `List your own ${plural}, public and private. The registry returns every entry you own; this keeps only the ${kind} ones ` +
+                "(an entry with no kind in the response is left out, with a warning on stderr). --json keeps `ahood skill list --json`'s shape.",
+            flags: ["--json    Emit the raw objects instead of formatted lines."],
+        },
+        {
+            usage: `${p} add <owner>/${n}[@version]`,
+            summary: `Install ${a} ${label} into ${info.installsTo}, pinned in the lockfile.`,
+            desc: `Install ${a} ${label} into ${info.installsTo}, pinned in .claude/skills.lock.json. ` +
+                (kind === "mcp" ? "Prompts for any secret environment variables its server.json declares that aren't already set. " : "") +
+                `Refused before anything is downloaded or written when the target is not ${a} ${label}.`,
+            examples: [`${p} add ${ex}`, `${p} add ${ex}@1.2.0`],
+        },
+        {
+            usage: `${p} update [<owner>/${n} ...] [--dry-run] [--json]`,
+            summary: `Move ${label} pins forward to the latest version.`,
+            desc: `Move lockfile pins forward to the latest version. With no argument, considers only the installed ${plural} ` +
+                `in this project -- other kinds' pins are left alone. A named target that is not ${a} ${label} is refused and counted as a failure.`,
+            flags: [
+                "--dry-run   Preview current vs. latest version (and the changelog) without installing anything.",
+                "--json      With --dry-run, emit structured preview objects instead of a formatted table.",
+            ],
+        },
+        {
+            usage: `${p} outdated [<owner>/${n} ...] [--json]`,
+            summary: `Read-only staleness check for installed ${plural}.`,
+            desc: `Read-only staleness check -- equivalent to \`${p} update --dry-run\`. With no argument, checks only the installed ${plural}.`,
+            flags: ["--json    Emit structured preview objects instead of a formatted table."],
+        },
+        {
+            usage: `${p} remove <owner>/${n} [--yes]`,
+            summary: `Uninstall and unpin ${a} ${label} (local only, prompts unless --yes is passed).`,
+            desc: `Uninstall and unpin ${a} ${label} from this project (local only). Refused, before the prompt and before anything is deleted, ` +
+                `when the install is another kind; the kind is read from the project's own files, and from the registry only when they can't tell.`,
+            flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+        },
+        {
+            usage: `${p} edit <owner>/${n} [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]`,
+            summary: `Update ${a} ${label} you own, changing only the flags you pass.`,
+            desc: `Update ${a} ${label} you own; same flags as \`ahood skill edit\`. ${kindRefusal}`,
+            flags: [
+                "--tagline <text>              Short one-line description.",
+                "--tags <comma,separated>      Replaces the tag list.",
+                "--license <id>                An SPDX license identifier, e.g. MIT.",
+                "--visibility public|private   Who can see and install it.",
+                "--homepage <url>              Homepage URL.",
+                "--repository <url>            Source repository URL.",
+            ],
+        },
+        {
+            usage: `${p} unpublish <owner>/${n}[@version] [--yes]`,
+            summary: `Delete ${a} ${label} from the registry for every consumer, or yank one version (prompts unless --yes is passed).`,
+            desc: `Without @version: delete ${a} ${label} from the registry for every consumer. With @version: yank that version. ` +
+                `Refused before the prompt when the target is not ${a} ${label}.`,
+            flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+        },
+        { usage: `${p} star <owner>/${n}`, summary: `Star ${a} ${label}.`, desc: `Star ${a} ${label}. ${kindRefusal}` },
+        { usage: `${p} unstar <owner>/${n}`, summary: `Remove your star from ${a} ${label}.`, desc: `Remove your star from ${a} ${label}. ${kindRefusal}` },
+        {
+            usage: `${p} share <owner>/${n} --group <group>`,
+            summary: `Share ${a} ${label} you own with a group, without changing its visibility.`,
+            desc: `Share ${a} ${label} you own with a group you belong to. ${kindRefusal}`,
+            flags: ["--group <group>   The group's slug (from `ahood group list`)."],
+        },
+        {
+            usage: `${p} unshare <owner>/${n} --group <group>`,
+            summary: `Stop sharing ${a} ${label} you own with a group.`,
+            desc: `Stop sharing ${a} ${label} you own with a group. ${kindRefusal}`,
+            flags: ["--group <group>   The group's slug."],
+        },
+        {
+            usage: `${p} init [name]`,
+            summary: `Scaffold a new ${label} folder with a minimal, valid ${doc}.`,
+            desc: `Scaffold a minimal ${doc} that passes the registry's publish validation: ./<name>/${doc} with a name, or ./${doc} without. ` +
+                (kind === "mcp"
+                    ? "The starter points at a reserved example.com URL, so it can never install anyone's real server until you edit it. "
+                    : "") +
+                `Refuses to overwrite an existing ${doc}, or to add one to a folder that already holds another kind's root document. ` +
+                "Names are slug-normalized and must stay inside the current directory.",
+            examples: [`${p} init ${ex.split("/")[1]}`, `${p} init`],
+        },
+        {
+            usage: `${p} publish <owner>/${n}@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]`,
+            summary: `Publish a new version of ${a} ${label} from a folder containing ${doc}, creating it first if it doesn't exist yet.`,
+            desc: `Publish a new version from a folder containing ${doc}; the kind is implied, and a contradictory --kind is refused. ` +
+                `If the entry already exists as another kind, this stops before anything is packed or uploaded. ` +
+                "If it doesn't exist yet, it is created first -- pass --name for that. Otherwise the same flags and --json output as `ahood skill publish`.",
+            flags: [
+                "--path <dir>                  Folder to publish (default: the current directory).",
+                "--name <text>                 Required only when creating the entry on this publish.",
+                "--changelog <text>            What changed in this version.",
+                "--json                        Print one {version,status,...} JSON object on completion (or {error} on failure).",
+            ],
+            examples: [`${p} publish ${ex}@1.0.0 --name "${kind === "agent" ? "Code Reviewer" : "GitHub Server"}"`],
+        },
+    ];
+}
+export const AGENT_COMMANDS_HELP = registryCommandsHelp("agent");
+// `ahood mcp` is two things (ADR 0007 in the ahood repo separates the hosted
+// registry MCP endpoint from this CLI's local one): with no verb, or with
+// `serve`, it is the local, read-only stdio MCP server that MCP hosts spawn;
+// with a registry verb it manages mcp-kind registry entries (server.json
+// manifests). Both are listed here so `ahood mcp --help` explains both.
+export const MCP_SERVE_HELP = [
+    {
+        usage: "ahood mcp serve",
+        summary: "Start the local, read-only ahood MCP server over stdio (preferred spelling).",
+        desc: "Start a Model Context Protocol server over stdio, exposing skill_search, skill_view, skill_read, " +
+            "skill_versions, skill_list, skill_outdated, and whoami as MCP tools -- the same data ahood's --json " +
+            "commands already return, reachable as typed tool calls instead of parsed CLI output. Meant to be " +
+            "launched by an MCP-aware agent host (e.g. Claude Code's MCP server configuration), not run interactively. " +
+            "Read-only by design. This is not the hosted registry MCP endpoint (https://www.ahood.dev/api/mcp), which " +
+            "is a separate server with write tools.",
+        examples: ['claude mcp add ahood -- ahood mcp serve', "npx @ahood/cli@latest mcp serve"],
+    },
+    {
+        usage: "ahood mcp",
+        summary: "Same as `ahood mcp serve`, kept byte-for-byte so existing MCP host configs keep working.",
+        desc: "With no arguments at all, `ahood mcp` starts the same stdio server as `ahood mcp serve` -- nothing is printed " +
+            "to stdout before the protocol starts, and no login or network is needed to start it. Any other first word must " +
+            "be `serve`, `--help`, or a registry verb below; anything unrecognized fails with usage instead of starting a server.",
+    },
+];
+export const MCP_COMMANDS_HELP = [...MCP_SERVE_HELP, ...registryCommandsHelp("mcp")];
 // Every group-entity verb, all reached as `ahood group <verb>` -- mirrors
 // SKILL_COMMANDS_HELP above, just for the "Groups" feature: private groups,
 // shareable invite links, and sharing your own skills with a group without
@@ -242,10 +445,10 @@ export const GROUP_COMMANDS_HELP = [
     {
         usage: "ahood group join <invite-url-or-token>",
         summary: "Join a group using an invite link or its raw token.",
-        desc: "Join a group using an invite link (e.g. https://ahood.vercel.app/groups/join?token=...) or its bare " +
+        desc: "Join a group using an invite link (e.g. https://www.ahood.dev/groups/join?token=...) or its bare " +
             "raw token -- either form works.",
         examples: [
-            "ahood group join https://ahood.vercel.app/groups/join?token=abc123",
+            "ahood group join https://www.ahood.dev/groups/join?token=abc123",
             "ahood group join abc123",
         ],
     },
@@ -380,6 +583,8 @@ export const COMMAND_ALIASES = { show: "view" };
 // only has to be added here once, not re-special-cased in both places.
 const ENTITY_COMMANDS_HELP = {
     skill: SKILL_COMMANDS_HELP,
+    agent: AGENT_COMMANDS_HELP,
+    mcp: MCP_COMMANDS_HELP,
     group: GROUP_COMMANDS_HELP,
     snap: SNAP_COMMANDS_HELP,
 };
@@ -501,12 +706,58 @@ export function formatSkillHelp() {
     return [
         "ahood skill -- manage skills in the ahood registry",
         "",
+        "Legacy, cross-kind: in this release `ahood skill <verb>` still acts on any registry kind",
+        "(skills, agents, MCP server manifests) -- `skill list`/`skill search` include every kind, and",
+        "`skill add`/`skill update` install whatever kind they resolve. Scripts relying on that keep",
+        "working. For one kind only, use `ahood agent <verb>` / `ahood mcp <verb>`, or add",
+        "`--kind skill|agent|mcp` to any verb below (`--kind all` spells out the legacy behavior).",
+        "A future major version will make `ahood skill` skills-only.",
+        "",
         "Commands:",
         ...lines,
         "",
         "Run `ahood skill <command> --help` for a single command's flags and examples.",
     ].join("\n");
 }
+// `ahood agent --help` / `ahood mcp --help` -- kind-scoped registry verbs.
+function formatRegistryKindHelp(header, intro, entries, noun) {
+    const lines = formatCommandTable(entries.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
+    return [
+        header,
+        "",
+        ...intro,
+        "",
+        "Commands:",
+        ...lines,
+        "",
+        `Run \`ahood ${noun} <command> --help\` for a single command's flags and examples.`,
+    ].join("\n");
+}
+export function formatAgentHelp() {
+    return formatRegistryKindHelp("ahood agent -- manage agent definitions (AGENT.md) in the ahood registry", [
+        "Every verb here acts on agents only: a target of another kind is refused before anything",
+        "is downloaded, prompted for, written, or sent. Installs land in .claude/agents/<owner>@<agent>.md.",
+    ], AGENT_COMMANDS_HELP, "agent");
+}
+export function formatMcpHelp() {
+    return formatRegistryKindHelp("ahood mcp -- the local MCP server, and MCP server manifests (server.json) in the ahood registry", [
+        "Two meanings, told apart by the first word:",
+        "  ahood mcp / ahood mcp serve   start this CLI's local, read-only MCP server over stdio",
+        "                                (what MCP host configs launch; `serve` is the preferred spelling)",
+        "  ahood mcp <verb>              manage mcp-kind registry entries (installs merge into .mcp.json)",
+        "Neither is the hosted registry MCP endpoint, https://www.ahood.dev/api/mcp.",
+        "Registry verbs act on MCP server manifests only; another kind is refused before any side effect.",
+    ], MCP_COMMANDS_HELP, "mcp");
+}
+// One entry point for every registry noun's group help, so dispatch and
+// `ahood help <noun>` can't disagree about which listing a noun gets.
+export function formatKindHelp(noun) {
+    if (noun === "agent")
+        return formatAgentHelp();
+    if (noun === "mcp")
+        return formatMcpHelp();
+    return formatSkillHelp();
+}
 // `ahood group --help` -- the group-level listing for every group verb.
 export function formatGroupHelp() {
     const lines = formatCommandTable(GROUP_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
@@ -537,7 +788,11 @@ export function formatSnapHelp() {
 // entity command lists.
 export function formatHelp() {
     const skillGroupUsage = "ahood skill <command>";
-    const skillGroupSummary = "Search, install, and publish skills -- run `ahood skill --help` for the full list.";
+    const skillGroupSummary = "Search, install, and publish skills (legacy: also any other kind) -- run `ahood skill --help` for the full list.";
+    const agentGroupUsage = "ahood agent <command>";
+    const agentGroupSummary = "The same verbs, for agent definitions only -- run `ahood agent --help` for the full list.";
+    const mcpGroupUsage = "ahood mcp <command>";
+    const mcpGroupSummary = "The same verbs, for MCP server manifests only; bare `ahood mcp` or `ahood mcp serve` starts the local MCP server.";
     const groupGroupUsage = "ahood group <command>";
     const groupGroupSummary = "Create private groups and share skills with them -- run `ahood group --help` for the full list.";
     const snapGroupUsage = "ahood snap <command>";
@@ -545,22 +800,30 @@ export function formatHelp() {
     const lines = formatCommandTable([
         ...TOP_LEVEL_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })),
         { usage: skillGroupUsage, summary: skillGroupSummary },
+        { usage: agentGroupUsage, summary: agentGroupSummary },
+        { usage: mcpGroupUsage, summary: mcpGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
         { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
     return [
-        "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
+        "ahood -- CLI for the ahood skills registry (https://www.ahood.dev)",
         "",
         "Quick start:",
         "  ahood login",
         "  ahood skill search <something>",
         "  ahood skill add <owner>/<skill>",
         "",
+        "Use ahood with an AI agent:",
+        "  ahood help useme    Print a complete SKILL.md teaching an agent how to use ahood.",
+        "                      Raw stdout, offline, no login -- paste it to an agent, or let an",
+        "                      agent with a shell run it.",
+        "",
         "Commands:",
         ...lines,
         "",
         "Run `ahood <command> --help` (or `ahood help <command>`) for a single command's flags and examples.",
         "Run `ahood skill --help` for the full list of skill commands.",
+        "Run `ahood agent --help` / `ahood mcp --help` for the kind-scoped agent and MCP commands.",
         "Run `ahood group --help` for the full list of group commands.",
         "Run `ahood snap --help` for the full list of snap commands.",
         "Run `ahood --version` to print the installed CLI version.",
@@ -569,6 +832,6 @@ export function formatHelp() {
         "            4 authentication required or rejected, 5 not found,",
         "            6 network/transport error or upstream server (5xx) error.",
         "",
-        "Full reference: https://ahood.vercel.app/docs",
+        "Full reference: https://www.ahood.dev/docs",
     ].join("\n");
 }

package/dist/http.js

@@ -4,9 +4,17 @@ import { sanitizeForTerminal } from "./terminal-safe.js";
 import { CLI_NAME, CLI_VERSION } from "./version.js";
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    body;
+    // The parsed JSON error body, when there was one and it parsed as an
+    // object -- not just the `.error` string already folded into `message`.
+    // whoami.ts needs this to read the `provisioning` flag GET /api/v1/profile
+    // sets on a 404 for "row not provisioned yet" and tell it apart from a 404
+    // that means something else, which `message` alone can't do once it's been
+    // through sanitizeErrorMessage.
+    constructor(status, message, body) {
         super(message);
         this.status = status;
+        this.body = body;
     }
 }
 // Distinguished from ApiError so index.ts's top-level handler can map it to
@@ -15,6 +23,36 @@ export class ApiError extends Error {
 export class NetworkError extends Error {
 }
 const DEFAULT_TIMEOUT_MS = 30_000;
+// ahood-cli#159: 429 policy. The registry rate-limits many endpoints the CLI
+// calls directly, and every limited endpoint answers with a Retry-After. Two
+// bounded retries, then a failure that says what actually happened ("rate
+// limited", with the server's own wait) instead of a generic status message
+// that reads like a registry bug.
+const RATE_LIMIT_MAX_RETRIES = 2;
+const RATE_LIMIT_FIRST_WAIT_MS = 1_000;
+// Cap on a single backoff hop, however large the server's Retry-After is: a
+// CLI must not silently hang for minutes on one header, and the final error
+// still reports the server's uncapped ask.
+const RATE_LIMIT_MAX_WAIT_MS = 30_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Retry-After is seconds per RFC 7231 ("120"), but the same RFC also allows an
+// HTTP-date and every rate limiter is one refactor away from switching shape --
+// so parse both, defensively. Anything unparseable comes back as undefined so
+// callers fall back to their own backoff rather than trusting garbage.
+export function parseRetryAfterMs(header, now = Date.now()) {
+    const value = header?.trim();
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const when = Date.parse(value);
+    if (!Number.isNaN(when))
+        return Math.max(0, when - now);
+    return undefined;
+}
 // A hung/black-holed server would otherwise stall the process indefinitely --
 // relevant since this CLI is meant to run unattended in CI and be driven by
 // agents. Callers (e.g. publish's upload) can still pass their own `signal`.
@@ -70,31 +108,92 @@ export function sanitizeErrorMessage(message) {
     // exists to suppress. Length alone is safe to report.
     return `Request failed with an unexpected, oversized, or HTML-shaped error response (${message.length} bytes) -- this usually means an upstream proxy/WAF failure, not a problem with your request.`;
 }
+// ahood-cli#159 (finding 5): during an outage the registry answered a request
+// with 402 and an HTML body -- a client expecting JSON got a parse-shaped
+// failure ("Request failed with status 402") that named none of what actually
+// happened. These are the statuses that plausibly mean "the whole registry is
+// down or blocked" rather than "your specific request was rejected": the 5xx
+// family, plus 402 (this incident's status -- a billing/quota gate in front of
+// the registry is exactly the kind of thing that fails open with an infra page
+// rather than a JSON error).
+//
+// Deliberately NOT extended to 401/403/404/410/429: those already have their
+// own well-understood meanings elsewhere in this CLI (see exit-code.ts,
+// login.ts's device-code polling, whoami.ts's provisioning check) and, unlike
+// a 5xx or a paywall, a body-less/non-JSON response on one of them is far more
+// likely to be "this particular endpoint just doesn't send a body on this
+// status" than "the registry is down". Treating those as an outage too would
+// overfit this one incident's status code into a much broader claim than the
+// evidence supports.
+const LIKELY_OUTAGE_STATUSES = new Set([402, 500, 502, 503, 504]);
 export async function apiJson(path, init = {}) {
-    const res = await apiFetch(path, init);
-    if (!res.ok) {
-        // The error body may not be valid/object JSON (proxy error pages, an
-        // empty body, a literal `null`) -- fall back to the status-only message
-        // rather than crashing on `body.error` of something that isn't an object.
-        const body = await res.json().catch(() => undefined);
-        const message = body && typeof body === "object" && typeof body.error === "string"
-            ? sanitizeErrorMessage(body.error)
-            : `Request failed with status ${res.status}`;
-        throw new ApiError(res.status, message);
-    }
-    // A 204 No Content (or any 2xx with an empty body) has nothing to parse --
-    // res.json() throws on empty input, which previously surfaced as a
-    // generic "Malformed response" error even though the request succeeded
-    // (ahood-cli#103). Callers that don't need response data (e.g. token
-    // revoke, which awaits this without using the result) get `undefined`
-    // back instead of a spurious failure.
-    const text = await res.text();
-    if (text === "")
-        return undefined;
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        throw new Error(`Malformed response from ${getApiUrl()}${path}: expected JSON.`);
+    // ahood-cli#159: 429 is its own case, before the generic !res.ok handling.
+    // It means "you are asking too fast", and the server tells us exactly when
+    // to come back -- surface neither as a generic error, and retry a bounded
+    // number of times first. Every other status keeps its exact previous
+    // handling below.
+    for (let attempt = 0;; attempt++) {
+        const res = await apiFetch(path, init);
+        if (res.status === 429) {
+            // Drain the rejected body so undici releases the socket instead of
+            // keeping it checked out while we wait.
+            await res.text().catch(() => "");
+            const retryAfterMs = parseRetryAfterMs(res.headers.get("Retry-After"));
+            if (attempt < RATE_LIMIT_MAX_RETRIES) {
+                // No usable Retry-After -> exponential (1s, 2s), the same fallback
+                // shape the login poll uses. One wait never exceeds the cap.
+                const waitMs = Math.min(retryAfterMs ?? RATE_LIMIT_FIRST_WAIT_MS * 2 ** attempt, RATE_LIMIT_MAX_WAIT_MS);
+                await sleep(waitMs);
+                continue;
+            }
+            // Retries exhausted. Report the server's own ask (not our capped wait):
+            // that is the number the user needs to act on.
+            const seconds = Math.ceil((retryAfterMs ?? RATE_LIMIT_FIRST_WAIT_MS * 2 ** RATE_LIMIT_MAX_RETRIES) / 1000);
+            // ahood-cli#159 (finding 3): an IP-keyed limit is shared by every
+            // unauthenticated caller behind that address -- a CI runner, a
+            // corporate NAT, a university network. This CLI has no say over how
+            // the registry buckets requests (that's server policy, out of this
+            // repo's reach), but it DOES know, right here, that the caller making
+            // this specific request has no token attached -- the one fact that
+            // makes the hint worth showing now rather than always. Logged-in
+            // callers get nothing extra: they already did the one thing this
+            // message would suggest, and repeating it at them would just be noise
+            // on top of a real rate limit. Worded as "may" -- this CLI cannot
+            // confirm the registry actually keys authenticated requests
+            // differently, only that it's a plausible reason this specific 429
+            // landed on an anonymous caller.
+            const loginHint = resolveToken()
+                ? ""
+                : " You're not logged in, so this request shares a rate limit with every other anonymous caller on your network -- `ahood login` may get you your own.";
+            throw new ApiError(429, `Rate limited -- try again in ${seconds} seconds.${loginHint}`);
+        }
+        if (!res.ok) {
+            // The error body may not be valid/object JSON (proxy error pages, an
+            // empty body, a literal `null`) -- fall back to the status-only message
+            // rather than crashing on `body.error` of something that isn't an object.
+            const body = await res.json().catch(() => undefined);
+            const hasStructuredError = body && typeof body === "object" && typeof body.error === "string";
+            const message = hasStructuredError
+                ? sanitizeErrorMessage(body.error)
+                : LIKELY_OUTAGE_STATUSES.has(res.status)
+                    ? `The registry appears to be unavailable (HTTP ${res.status}).`
+                    : `Request failed with status ${res.status}`;
+            throw new ApiError(res.status, message, body);
+        }
+        // A 204 No Content (or any 2xx with an empty body) has nothing to parse --
+        // res.json() throws on empty input, which previously surfaced as a
+        // generic "Malformed response" error even though the request succeeded
+        // (ahood-cli#103). Callers that don't need response data (e.g. token
+        // revoke, which awaits this without using the result) get `undefined`
+        // back instead of a spurious failure.
+        const text = await res.text();
+        if (text === "")
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Malformed response from ${getApiUrl()}${path}: expected JSON.`);
+        }
     }
 }