@ahood/cli 0.8.8 → 0.10.0

package/dist/http.js

@@ -1,11 +1,20 @@
 import { getApiUrl } from "./config.js";
 import { resolveToken } from "./credentials.js";
+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
@@ -14,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`.
@@ -31,8 +70,12 @@ export async function apiFetch(path, init = {}) {
         });
     }
     catch (error) {
-        const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
-        const message = error instanceof Error ? error.message : String(error);
+        // The `instanceof Error` guard on the cause is load-bearing, not defensive
+        // noise: `cause` is `unknown`, and optional-chaining into `.message`
+        // instead would print a bare "undefined" as the reason a request failed
+        // (ahood-cli#129). Dropping the reason entirely is the better failure mode.
+        const cause = error instanceof Error && error.cause instanceof Error ? `: ${sanitizeForTerminal(error.cause.message)}` : "";
+        const message = sanitizeForTerminal(error instanceof Error ? error.message : error);
         throw new NetworkError(`Request to ${getApiUrl()}${path} failed (${message}${cause})`);
     }
 }
@@ -44,23 +87,8 @@ const MAX_ERROR_MESSAGE_LENGTH = 500;
 // sits on every apiJson call in the CLI -- including `add`, which prints
 // server-sourced text immediately before a masked secret prompt, the exact
 // moment a cursor-movement/line-clear sequence can repaint what the user sees.
+// See src/terminal-safe.ts for what that substitution does and why.
 //
-// Control characters are replaced with a space rather than deleted so that
-// stripping can't silently glue two tokens into one misleading word.
-//
-// Newlines (\x0a) and carriage returns (\x0d) are inside this range and are
-// deliberately flattened too: a forged prompt line ("...\n\nEnter your token:")
-// needs no escape sequence at all, just a newline, so preserving them would
-// leave the spoofing half of the threat model open while closing the escape
-// half. The readability cost is small because anything reaching this branch is
-// already capped at MAX_ERROR_MESSAGE_LENGTH -- a few lines' worth of text, not
-// a stack trace.
-//
-// Known duplication: this is the same substitution as `sanitizeForTerminal` in
-// src/commands/add.ts (ahood-cli#122). It is copied rather than shared on
-// purpose -- promoting a shared helper means editing add.ts's call sites, which
-// is follow-up refactor work kept out of this security fix; see ahood-cli#127.
-const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/g;
 // Defense in depth (ahood-cli#31): the API is expected to never forward a raw
 // upstream error body (an HTML block page from a proxy/WAF, a giant stack
 // trace, etc.) into `error`, but this CLI shouldn't trust that unconditionally
@@ -69,39 +97,103 @@ const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/g;
 // a normal error string is replaced with a short, safe summary instead.
 export function sanitizeErrorMessage(message) {
     const looksLikeHtml = /<!DOCTYPE|<html[\s>]/i.test(message);
+    // The length argument is belt-and-braces, not behavior: this branch already
+    // guarantees `message.length <= MAX_ERROR_MESSAGE_LENGTH`, and an oversized
+    // body takes the generic-summary path below instead.
     if (!looksLikeHtml && message.length <= MAX_ERROR_MESSAGE_LENGTH)
-        return message.replace(CONTROL_CHARACTERS, " ");
+        return sanitizeForTerminal(message, MAX_ERROR_MESSAGE_LENGTH);
     // No preview of the raw content: an HTML-shaped body's first bytes are
     // exactly where infra details (e.g. a Cloudflare block page's title, Ray
     // ID) live, so a "helpful" excerpt would leak the same details this
     // 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.`);
+        }
     }
 }

package/dist/index.js

@@ -20,15 +20,16 @@ import { versions } from "./commands/versions.js";
 import { diff } from "./commands/diff.js";
 import { completion } from "./commands/completion.js";
 import { mcp } from "./commands/mcp.js";
+import { extractKindFlag, resolveScope } from "./kinds.js";
+import { readUseme } from "./useme.js";
+import { UsageError } from "./usage-error.js";
 import { init } from "./commands/init.js";
 import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
 import { createSnap, listSnaps, searchSnaps, showSnap, removeSnap, shareSnap, unshareSnap, tagsSnap, } from "./commands/snap.js";
-import { formatHelp, formatSkillHelp, formatGroupHelp, formatSnapHelp, formatCommandHelp, findCommandHelp } from "./help.js";
+import { formatHelp, formatKindHelp, formatGroupHelp, formatSnapHelp, formatCommandHelp, findCommandHelp } from "./help.js";
 import { ApiError } from "./http.js";
 import { exitCodeFor } from "./exit-code.js";
 import { CLI_NAME, CLI_VERSION } from "./version.js";
-// Every skill-entity verb, reached only as `ahood skill <verb>` -- see
-// dispatchSkill() below. "show" is an alias for "view" (issue #30).
 const SKILL_COMMANDS = {
     search,
     view,
@@ -44,7 +45,7 @@ const SKILL_COMMANDS = {
     // can never accidentally move a pin forward. Reuses update()'s existing
     // "no targets = every installed skill, explicit targets = just those"
     // behavior as-is; no new logic.
-    outdated: (args) => update([...args, "--dry-run"]),
+    outdated: (args, scope) => (scope ? update([...args, "--dry-run"], scope) : update([...args, "--dry-run"])),
     remove,
     edit,
     unpublish,
@@ -92,8 +93,9 @@ const COMMANDS = {
     whoami,
     token,
     completion,
-    mcp,
+    mcp: dispatchMcp,
     skill: dispatchSkill,
+    agent: dispatchAgent,
     group: dispatchGroup,
     snap: dispatchSnap,
 };
@@ -105,7 +107,8 @@ const COMMANDS = {
 // here just means "a command that owns its own sub-verb dispatch", the same
 // sense "skill" already used before "group" (the entity) existed. "snap"
 // joins this set for the exact same reason (ahood-cli#107).
-const GROUP_COMMANDS = new Set(["skill", "group", "snap"]);
+// "agent" and "mcp" join it as registry nouns (ahood-cli#172).
+const GROUP_COMMANDS = new Set(["skill", "agent", "mcp", "group", "snap"]);
 function levenshtein(a, b) {
     const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
     for (let i = 0; i <= a.length; i++)
@@ -143,31 +146,96 @@ function closestGroupVerb(input) {
 function closestSnapVerb(input) {
     return closestOf(input, Object.keys(SNAP_VERBS));
 }
-// `ahood skill <verb> [...]` -- owns its own help handling at both the
-// group level (`ahood skill` / `ahood skill --help`) and the per-verb level
-// (`ahood skill <verb> --help`), since neither should fall through to
-// main()'s generic top-level --help interception (see GROUP_COMMANDS).
-async function dispatchSkill(args) {
+// `ahood <noun> <verb> [...]` for every registry noun (skill, agent, mcp) --
+// owns its own help handling at both the noun level (`ahood agent` /
+// `ahood agent --help`) and the per-verb level (`ahood agent <verb> --help`),
+// since neither should fall through to main()'s generic top-level --help
+// interception (see GROUP_COMMANDS).
+//
+// Scope (ahood-cli#172): `--kind <k|all>` is consumed here, never by a
+// handler, and resolved by resolveScope(): agent/mcp are strict for their own
+// kind (a contradictory --kind is a usage error), while skill stays legacy
+// cross-kind unless --kind narrows it. `ahood skill publish` is the one
+// exception: its --kind has always been publish's own "what kind of artifact
+// is this folder" flag, so it is passed through untouched.
+async function dispatchRegistry(noun, args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h") {
-        console.log(formatSkillHelp());
+        console.log(formatKindHelp(noun));
         return;
     }
     const handler = SKILL_COMMANDS[sub];
     if (!handler) {
-        console.error(`Unknown skill command: ${sub}`);
-        const suggestion = closestSkillCommand(sub);
+        console.error(`Unknown ${noun} command: ${sub}`);
+        const suggestion = closestOf(sub, noun === "mcp" ? ["serve", ...Object.keys(SKILL_COMMANDS)] : Object.keys(SKILL_COMMANDS));
         if (suggestion)
             console.error(`Did you mean '${suggestion}'?`);
-        console.error("Run `ahood skill --help` for a list of commands.");
+        console.error(`Run \`ahood ${noun} --help\` for a list of commands.`);
+        if (noun === "mcp") {
+            console.error("To start the local MCP server, run `ahood mcp serve` (or `ahood mcp` with no arguments).");
+        }
         process.exit(2);
     }
     if (rest.includes("--help") || rest.includes("-h")) {
-        const entry = findCommandHelp("skill", sub);
-        console.log(entry ? formatCommandHelp(entry) : formatSkillHelp());
+        const entry = findCommandHelp(noun, sub);
+        console.log(entry ? formatCommandHelp(entry) : formatKindHelp(noun));
         return;
     }
-    await handler(rest);
+    if (noun === "skill" && sub === "publish") {
+        await handler(rest);
+        return;
+    }
+    const { kind, rest: handlerArgs } = extractKindFlag(rest);
+    const scope = resolveScope(noun, kind);
+    if (scope.kind === "all") {
+        // Legacy: the exact pre-#172 call, minus an explicit `--kind all`.
+        await handler(kind === undefined ? rest : handlerArgs);
+        return;
+    }
+    try {
+        await handler(handlerArgs, scope);
+    }
+    catch (error) {
+        // Handlers phrase their usage lines as `ahood skill <verb>`; under another
+        // noun, say the command the user actually typed.
+        if (error instanceof UsageError && noun !== "skill") {
+            error.message = error.message.replace(/(Usage: |or: )ahood skill /g, `$1ahood ${noun} `);
+        }
+        throw error;
+    }
+}
+async function dispatchSkill(args) {
+    await dispatchRegistry("skill", args);
+}
+async function dispatchAgent(args) {
+    await dispatchRegistry("agent", args);
+}
+// `ahood mcp` keeps its original contract byte-for-byte: with NO arguments it
+// is the local stdio MCP server that existing host configs launch -- nothing
+// is printed and nothing else runs first. `ahood mcp serve` is the same
+// server under an explicit, documented name. Every other first word is a
+// registry verb for mcp-kind entries, help, or an error: an unrecognized one
+// fails with usage (dispatchRegistry) rather than silently starting a
+// long-lived server that a typo would otherwise leave hanging.
+async function dispatchMcp(args) {
+    if (args.length === 0) {
+        await mcp(args);
+        return;
+    }
+    const [sub, ...rest] = args;
+    if (sub === "serve") {
+        if (rest.includes("--help") || rest.includes("-h")) {
+            const entry = findCommandHelp("mcp", "serve");
+            console.log(entry ? formatCommandHelp(entry) : formatKindHelp("mcp"));
+            return;
+        }
+        if (rest.length > 0) {
+            throw new UsageError(`\`ahood mcp serve\` takes no arguments (got: ${rest.join(" ")}).\nUsage: ahood mcp serve`);
+        }
+        await mcp([]);
+        return;
+    }
+    await dispatchRegistry("mcp", args);
 }
 // `ahood group <verb> [...]` -- owns its own help handling at both the
 // group level (`ahood group` / `ahood group --help`) and the per-verb level
@@ -228,10 +296,26 @@ async function main() {
     }
     if (command === "help") {
         const sub = args[0];
-        if (sub === "skill") {
+        // `ahood help useme` (ahood-cli#172): the bundled self-skill, as raw
+        // bytes on stdout and nothing else -- no banner, no trailing newline of
+        // our own -- so the output IS the SKILL.md. No network, no credentials,
+        // no project writes.
+        if (sub === "useme") {
+            let content;
+            try {
+                content = readUseme();
+            }
+            catch (error) {
+                console.error(`Could not read the bundled ahood SKILL.md: ${error instanceof Error ? error.message : String(error)}`);
+                process.exit(1);
+            }
+            process.stdout.write(content);
+            return;
+        }
+        if (sub === "skill" || sub === "agent" || sub === "mcp") {
             const verb = args[1];
-            const entry = verb ? findCommandHelp("skill", verb) : undefined;
-            console.log(entry ? formatCommandHelp(entry) : formatSkillHelp());
+            const entry = verb ? findCommandHelp(sub, verb) : undefined;
+            console.log(entry ? formatCommandHelp(entry) : formatKindHelp(sub));
             return;
         }
         if (sub === "group") {
@@ -310,4 +394,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };
+export { main, dispatchSkill, dispatchAgent, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };

package/dist/kind-info.js

@@ -0,0 +1,40 @@
+// Pure kind metadata (no imports, no I/O) so help.ts -- which
+// scripts/sync-readme.mjs imports straight from dist/ -- can use it without
+// pulling in the HTTP/filesystem layer. Behavior lives in kinds.ts.
+//
+// Kind-aware registry commands (ahood-cli#172).
+//
+// The registry stores four artifact kinds (the backend's
+// lib/skills/validation.ts ALLOWED_KINDS: skill, agent, mcp, doc), and a
+// kind is fixed when an entry is created -- PATCH's allow-list has no `kind`
+// -- so the kind an entry reports now is the kind it has always had. This
+// CLI has a noun group for three of them. `doc` is a real registry kind left
+// out of this CLI's scope on purpose; adding it means one entry in KINDS
+// below plus its help/init template, not a new dispatcher.
+export const KINDS = {
+    skill: {
+        label: "skill",
+        article: "a",
+        plural: "skills",
+        rootDoc: "SKILL.md",
+        installsTo: ".claude/skills/<owner>@<skill>/",
+    },
+    agent: {
+        label: "agent",
+        article: "an",
+        plural: "agents",
+        rootDoc: "AGENT.md",
+        installsTo: ".claude/agents/<owner>@<agent>.md",
+    },
+    mcp: {
+        label: "MCP server manifest",
+        article: "an",
+        plural: "MCP server manifests",
+        rootDoc: "server.json",
+        installsTo: "an entry in .mcp.json",
+    },
+};
+export const CLI_KINDS = Object.keys(KINDS);
+export function isCliKind(value) {
+    return typeof value === "string" && CLI_KINDS.includes(value);
+}

package/dist/kinds.js

@@ -0,0 +1,122 @@
+// Kind-aware registry commands (ahood-cli#172): scope resolution and the
+// wrong-kind guards every kind-scoped verb runs before its first side effect.
+// The kind table itself lives in kind-info.ts.
+import { existsSync } from "node:fs";
+import { apiJson } from "./http.js";
+import { agentPath, skillDir } from "./spec.js";
+import { UsageError } from "./usage-error.js";
+import { KINDS, CLI_KINDS, isCliKind } from "./kind-info.js";
+export { KINDS, CLI_KINDS, isCliKind };
+export const LEGACY_SCOPE = { noun: "skill", kind: "all" };
+export function strictKind(scope) {
+    return scope && scope.kind !== "all" ? scope.kind : undefined;
+}
+// A wrong-kind target: the user pointed a noun at the wrong kind of entry, so
+// it maps to exit 2 ("fix your input") through UsageError, the same code a
+// server-side validation refusal gets.
+export class KindMismatchError extends UsageError {
+}
+export function describeKind(kind) {
+    return `${KINDS[kind].article} ${KINDS[kind].label}`;
+}
+// Throws unless `actual` is the scope's kind. A no-op for the legacy scope.
+//
+// Missing or unrecognized kind metadata is refused, never guessed: the legacy
+// code treated a missing `kind` as a skill, and a strict verb that did the
+// same would silently misclassify exactly the entry it exists to protect.
+// That refusal is a plain Error (exit 1) rather than a KindMismatchError,
+// since nothing about the user's input is wrong -- the registry's answer is.
+export function assertKind(scope, key, actual, verb, action) {
+    const expected = strictKind(scope);
+    if (expected === undefined || actual === expected)
+        return;
+    const legacyHint = `\`ahood skill ${verb} ${key}\` (legacy, any kind)`;
+    if (isCliKind(actual)) {
+        throw new KindMismatchError(`${key} is ${describeKind(actual)}, not ${describeKind(expected)} -- refusing to ${action} it. ` +
+            `Use \`ahood ${actual} ${verb} ${key}\` instead.`);
+    }
+    if (actual === undefined || actual === null || actual === "") {
+        throw new Error(`The registry did not report a kind for ${key}, so ahood cannot confirm it is ${describeKind(expected)} -- ` +
+            `refusing to ${action} it. If you are sure, use ${legacyHint}.`);
+    }
+    throw new Error(`${key} has kind "${String(actual).slice(0, 40)}", which \`ahood ${scope.noun}\` does not handle -- ` +
+        `refusing to ${action} it. Use ${legacyHint} if you really mean it.`);
+}
+// Resolves an existing registry entry's kind and asserts it, for verbs whose
+// own request carries no kind (star, share, edit, versions, ...). A no-op --
+// and, importantly, no extra request -- for the legacy scope, so
+// `ahood skill <verb>` sends exactly what it always has.
+export async function ensureRemoteKind(scope, owner, skill, verb, action) {
+    if (strictKind(scope) === undefined)
+        return;
+    const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+    assertKind(scope, `${owner}/${skill}`, detail.kind, verb, action);
+}
+// What this project's own files say an installed pin is, without asking the
+// registry. The lockfile records no `kind` (and this change does not migrate
+// it), so the footprint each kind leaves is the evidence:
+//   skill -> a .claude/skills/<owner>@<skill>/ directory
+//   agent -> a .claude/agents/<owner>@<skill>.md file
+//   mcp   -> neither, plus the mcp_config_hash only an mcp install records
+// Anything else (both, or a bare pin with no hash -- a legacy mcp pin or a
+// skill whose directory was deleted by hand) is undefined: unknown, and the
+// caller must ask the registry rather than guess.
+export function localInstalledKind(owner, skill, entry) {
+    const hasDir = existsSync(skillDir(owner, skill));
+    const hasAgentFile = existsSync(agentPath(owner, skill));
+    if (hasDir && !hasAgentFile)
+        return "skill";
+    if (hasAgentFile && !hasDir)
+        return "agent";
+    if (!hasDir && !hasAgentFile && entry?.mcp_config_hash !== undefined)
+        return "mcp";
+    return undefined;
+}
+// Pulls `--kind <value>` / `--kind=<value>` out of a registry verb's args.
+// Returns the remaining args untouched otherwise, so a handler never sees a
+// flag it does not declare.
+export function extractKindFlag(args) {
+    let kind;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--kind" || arg.startsWith("--kind=")) {
+            if (kind !== undefined)
+                throw new UsageError("--kind given more than once. Pass it once.");
+            if (arg === "--kind") {
+                const value = args[i + 1];
+                if (value === undefined || value.startsWith("--"))
+                    throw new UsageError("--kind requires a value.");
+                kind = value;
+                i++;
+            }
+            else {
+                kind = arg.slice("--kind=".length);
+            }
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { kind, rest };
+}
+// Resolves the scope for `ahood <noun> <verb> [--kind <k>]`.
+//   skill noun, no --kind or --kind all  -> legacy (cross-kind)
+//   skill noun, --kind <k>               -> strict <k>
+//   agent/mcp noun, no --kind or --kind <same> -> strict <noun>
+//   agent/mcp noun, any other --kind     -> usage error (contradiction)
+export function resolveScope(noun, kindFlag) {
+    const valid = [...CLI_KINDS, "all"].join(", ");
+    if (kindFlag !== undefined && kindFlag !== "all" && !isCliKind(kindFlag)) {
+        throw new UsageError(`--kind must be one of: ${valid} (got "${kindFlag}").`);
+    }
+    if (noun === "skill") {
+        return kindFlag === undefined || kindFlag === "all" ? LEGACY_SCOPE : { noun, kind: kindFlag };
+    }
+    if (kindFlag !== undefined && kindFlag !== noun) {
+        throw new UsageError(`\`ahood ${noun}\` only operates on ${KINDS[noun].plural} -- --kind ${kindFlag} contradicts it. ` +
+            (kindFlag === "all"
+                ? "Use `ahood skill <verb>` (legacy, any kind) for a cross-kind operation."
+                : `Use \`ahood ${kindFlag} <verb>\` instead.`));
+    }
+    return { noun, kind: noun };
+}