@ahood/cli 0.8.8 → 0.10.0

package/dist/commands/edit.js

@@ -2,13 +2,14 @@ import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill, validateExternalUrl } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill edit <owner>/<skill> [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--visibility public|private] [--homepage <url>] [--repository <url>]";
 // Mirrors PATCH /api/v1/skills/{owner}/{skill}'s allow-list exactly
 // (lib/skills/mutations.ts's UpdateSkillInput) -- only a field the caller
 // explicitly passed a flag for is included in the body, so an omitted flag
 // never clobbers an existing value (the route only validates/writes keys
 // that are present on the body at all).
-export async function edit(args) {
+export async function edit(args, scope) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
         throw new UsageError(USAGE);
@@ -43,6 +44,7 @@ export async function edit(args) {
     if (Object.keys(body).length === 0) {
         throw new UsageError("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility, --homepage, --repository.");
     }
+    await ensureRemoteKind(scope, owner, skill, "edit", "edit");
     const updated = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`, {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },

package/dist/commands/init.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, join, resolve, sep } from "node:path";
 import { UsageError } from "../usage-error.js";
+import { CLI_KINDS, KINDS, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill init [name]";
 // Mirrors the server's slug convention referenced by ahood-cli#60 (and the
 // same shape as spec.ts's SEGMENT_RE, minus "." and "_" -- skill slugs are
@@ -56,15 +57,76 @@ description: TODO -- describe what this skill does and when Claude should use it
 TODO: describe, step by step, what Claude should do when this skill is invoked.
 `;
 }
+// AGENT.md, for `ahood agent init` (ahood-cli#172). The backend's publish
+// validator (lib/publish/parse-agent-frontmatter.ts in the ahood repo) is a
+// hand-rolled flat `key: value` reader, not YAML: it requires the file to
+// START with a `---` line, a closing `---` line followed by a newline, and
+// non-empty `name` and `description`; an optional `skills: [owner/slug, ...]`
+// flow list must hold owner/slug entries. Claude Code's own subagent loader
+// reads the same frontmatter (name, description, and optionally tools and
+// model). So: no leading comment above the opening `---` (that alone fails
+// publish), and the optional keys are left as commented-out examples, with
+// no colon in any prose comment, so neither reader can mistake a comment for
+// a key.
+function buildAgentMd(name) {
+    return `---
+name: ${name}
+description: TODO -- describe what this agent does and when Claude should delegate to it.
+# Optional. Uncomment to restrict the tools this agent may use (omit to inherit all).
+# tools: Read, Grep, Glob
+# Optional. Uncomment to pin a model for this agent.
+# model: sonnet
+---
+
+TODO -- write the system prompt for this agent. Say what it is responsible for,
+the steps it should take, and what it should hand back when it is done.
+`;
+}
+// server.json, for `ahood mcp init` (ahood-cli#172). Mirrors exactly what the
+// backend's publish validator (lib/publish/parse-server-manifest.ts in the
+// ahood repo) accepts: a JSON object with non-empty `name` and `description`
+// and exactly one of `packages` (one npm/npx entry) or `remotes` (one http(s)
+// url). The starter uses `remotes`, pointed at a reserved example.com host
+// (RFC 2606), deliberately: a `packages` placeholder would name an npm
+// package that `ahood mcp add` turns into `npx -y <identifier>@<version>` --
+// an install of whatever someone later publishes under that name if the
+// starter were ever published unedited. A reserved host can never resolve to
+// anyone's server. JSON has no comments, so the editing guidance is printed
+// by init instead.
+function buildServerJson(name) {
+    const manifest = {
+        name,
+        description: "TODO -- describe what this MCP server does and when an agent should use it.",
+        remotes: [{ url: "https://mcp.example.com/mcp" }],
+    };
+    return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+const TEMPLATES = {
+    skill: buildSkillMd,
+    agent: buildAgentMd,
+    mcp: buildServerJson,
+};
+const NEXT_STEPS = {
+    skill: ["Fill in the description, then flesh out the ## Instructions section."],
+    agent: ["Fill in the description, then write the agent's system prompt below the frontmatter."],
+    mcp: [
+        "Fill in the description and point remotes[0].url at your server's https endpoint, or replace",
+        '"remotes" with one npm package: "packages": [{"registry_type": "npm", "runtime_hint": "npx",',
+        '"identifier": "<npm-package>", "version": "<x.y.z>"}] (plus optional "environment_variables").',
+    ],
+};
 // Falls back to "my-skill" when the directory name itself isn't usable as a
 // bare YAML scalar (empty, or starting with a character like "-" or "@" that
 // would need quoting) -- e.g. running `ahood skill init` with no name directly in
 // "/" (basename "") or in a directory whose name starts with punctuation.
-function skillNameFor(dirPath) {
+function skillNameFor(dirPath, fallback = "my-skill") {
     const base = basename(dirPath);
-    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base) ? base : "my-skill";
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base) ? base : fallback;
 }
-export async function init(args) {
+export async function init(args, scope) {
+    const strict = strictKind(scope);
+    const kind = strict ?? "skill";
     let name = args[0];
     if (name !== undefined && name.startsWith("-"))
         throw new UsageError(USAGE);
@@ -93,13 +155,31 @@ export async function init(args) {
         }
     }
     const targetDir = name ? resolve(name) : process.cwd();
-    const skillMdPath = join(targetDir, "SKILL.md");
-    if (existsSync(skillMdPath)) {
-        throw new Error(`SKILL.md already exists at ${skillMdPath} -- refusing to overwrite it.`);
+    const rootDoc = KINDS[kind].rootDoc;
+    const docPath = join(targetDir, rootDoc);
+    if (existsSync(docPath)) {
+        throw new Error(`${rootDoc} already exists at ${docPath} -- refusing to overwrite it.`);
+    }
+    // A kind-scoped init also refuses a folder that already holds ANOTHER
+    // kind's root document: one folder is one artifact, and a second root doc
+    // makes a plain `ahood skill publish` of that folder ambiguous. The legacy
+    // `ahood skill init` keeps its exact pre-#172 behavior.
+    if (strict !== undefined) {
+        for (const other of CLI_KINDS) {
+            if (other === kind)
+                continue;
+            const otherPath = join(targetDir, KINDS[other].rootDoc);
+            if (existsSync(otherPath)) {
+                throw new Error(`${otherPath} already exists -- that folder is already ${KINDS[other].article} ${KINDS[other].label}. ` +
+                    `Refusing to add ${rootDoc} next to it; pick another name.`);
+            }
+        }
     }
     mkdirSync(targetDir, { recursive: true });
-    writeFileSync(skillMdPath, buildSkillMd(name ?? skillNameFor(targetDir)));
-    console.log(`Created ${skillMdPath}`);
-    console.log("Fill in the description, then flesh out the ## Instructions section.");
-    console.log(`Run \`ahood skill publish <owner>/<skill>@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
+    writeFileSync(docPath, TEMPLATES[kind](name ?? skillNameFor(targetDir, `my-${kind}`)));
+    console.log(`Created ${docPath}`);
+    for (const line of NEXT_STEPS[kind])
+        console.log(line);
+    const placeholder = kind === "skill" ? "<skill>" : kind === "agent" ? "<agent>" : "<server>";
+    console.log(`Run \`ahood ${strict ?? "skill"} publish <owner>/${placeholder}@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
 }

package/dist/commands/list.js

@@ -1,17 +1,23 @@
 import { apiJson } from "../http.js";
-export async function listOwnSkills() {
-    const { skills } = await apiJson("/api/v1/skills?mine=true");
+import { KINDS, strictKind } from "../kinds.js";
+// A strict kind is filtered by the registry: its `mine=true` branch honours
+// ?kind= (ahood#657) and, with no page/per_page, still returns every owned
+// row unpaginated -- the same shape as before.
+export async function listOwnSkills(kind) {
+    const query = kind ? `mine=true&kind=${encodeURIComponent(kind)}` : "mine=true";
+    const { skills } = await apiJson(`/api/v1/skills?${query}`);
     return skills ?? [];
 }
-export async function listSkills(args = []) {
+export async function listSkills(args = [], scope) {
     const jsonOutput = args.includes("--json");
-    const skills = await listOwnSkills();
+    const kind = strictKind(scope);
+    const skills = await listOwnSkills(kind);
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;
     }
     if (skills.length === 0) {
-        console.log("You haven't published any skills yet.");
+        console.log(kind ? `You haven't published any ${KINDS[kind].plural} yet.` : "You haven't published any skills yet.");
         return;
     }
     for (const skill of skills) {

package/dist/commands/login.js

@@ -1,8 +1,13 @@
-import { apiJson } from "../http.js";
+import { apiJson, parseRetryAfterMs } from "../http.js";
 import { getApiUrl } from "../config.js";
 import { writeCredentials } from "../credentials.js";
 const DEFAULT_EXPIRES_IN_SECONDS = 600; // 10 minutes, matching the previous timeout loop's real-world duration
 const POLL_TIMEOUT_MS = 10_000;
+const POLL_INTERVAL_MS = 2_000;
+// ahood-cli#159: cap on a single 429 backoff hop, same policy as apiJson's
+// rate-limit retry -- however large the server's Retry-After, one wait stays
+// bounded, and the deadline check below keeps the loop inside expires_in.
+const RATE_LIMIT_MAX_BACKOFF_MS = 30_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -10,6 +15,11 @@ export async function login() {
     const { code, verification_url, expires_in } = await apiJson("/api/v1/auth/cli/device", {
         method: "POST",
     });
+    // Printed VERBATIM, deliberately not through sanitizeForTerminal the way
+    // `add` treats server-supplied text: this line exists so the user can
+    // compare it against the code on the /cli-auth page, and a tidied-up
+    // rendering would make that comparison meaningless. Pinned by
+    // tests/login-device-code-verbatim.test.ts (ahood#357).
     console.log(`First, confirm this code matches what you see in your browser: ${code}`);
     console.log(`Open ${verification_url} to approve.`);
     // expires_in is server-supplied; a missing/non-finite value previously
@@ -18,8 +28,29 @@ export async function login() {
     // failed instantly with "timed out" instead of ever actually polling.
     const seconds = Number.isFinite(expires_in) && expires_in > 0 ? expires_in : DEFAULT_EXPIRES_IN_SECONDS;
     const deadline = Date.now() + seconds * 1000;
+    // ahood-cli#159: when the registry rate-limits the poll, `backoffMs` carries
+    // the wait for the NEXT poll -- 429 must not `continue` on the normal
+    // cadence, which is the retry-storm shape: the client answers "you are
+    // asking too often" by asking again on the same schedule, against an
+    // endpoint that can least afford it.
+    let backoffMs;
+    let consecutive429s = 0;
+    // Whether the loop ever saw a 429 -- the timeout message below can then say
+    // why the window ran out instead of blaming the user's pace.
+    let wasRateLimited = false;
     while (Date.now() < deadline) {
-        await sleep(2000);
+        let waitMs = POLL_INTERVAL_MS;
+        if (backoffMs !== undefined) {
+            waitMs = backoffMs;
+            backoffMs = undefined;
+            // The 429 backoff counts against the login deadline like every other
+            // wait: a server that keeps answering "wait 60s" must not stretch the
+            // loop past expires_in -- and past expiry the device code is dead, so
+            // polling after the wait would be pointless anyway.
+            if (Date.now() + waitMs >= deadline)
+                break;
+        }
+        await sleep(waitMs);
         let res;
         try {
             // Poll against the CONFIGURED API host (getApiUrl()), not a URL derived
@@ -27,6 +58,17 @@ export async function login() {
             // shown to the human, never used to build a request, so a compromised
             // or redirected registry response can't point this at a host that
             // then harvests the device code and hands back an attacker's token.
+            //
+            // `code` is sent VERBATIM and must stay that way: do not trim it,
+            // change its case, strip its separator or otherwise tidy it. The format
+            // is defined once, in ahood's lib/auth/device-code.ts, and the server
+            // canonicalizes whatever arrives -- so this CLI stays format-agnostic
+            // and a server-side format fix needs no release of this package. In
+            // ahood#349 that property was all that stood between a bad ten-minute
+            // "Login timed out" and a bad error: the hyphen happens to be
+            // unreserved, so encodeURIComponent left it alone. Pinned by
+            // tests/login-device-code-verbatim.test.ts; contract in ahood's
+            // docs/adr/backend/0005-device-code-cross-repo-contract.md (ahood#357).
             res = await apiFetchWithTimeout(`/api/v1/auth/cli/device/${encodeURIComponent(code)}`);
         }
         catch (error) {
@@ -46,6 +88,22 @@ export async function login() {
         if (res.status === 410 || res.status === 404) {
             throw new Error("This login was cancelled or expired. Run `ahood login` again.");
         }
+        if (res.status === 429) {
+            // ahood-cli#159: the registry has said stop. Back off by Retry-After
+            // (exponentially, 1s doubling, when the header is absent/unparseable)
+            // instead of polling on -- and let the deadline check at the top of the
+            // loop bound the total time, so rate limiting cannot extend the window.
+            wasRateLimited = true;
+            consecutive429s++;
+            // Drain the rejected body so the socket is released while we wait.
+            await res.text().catch(() => "");
+            const retryAfterMs = parseRetryAfterMs(res.headers.get("Retry-After"));
+            const wait = Math.min(retryAfterMs ?? 1_000 * 2 ** (consecutive429s - 1), RATE_LIMIT_MAX_BACKOFF_MS);
+            backoffMs = wait;
+            console.error(`Rate limited while polling; waiting ${Math.ceil(wait / 1000)}s before trying again...`);
+            continue;
+        }
+        consecutive429s = 0;
         let body;
         try {
             body = (await res.json());
@@ -65,7 +123,9 @@ export async function login() {
         }
         // status === "pending" -- keep polling.
     }
-    throw new Error("Login timed out. Run `ahood login` again.");
+    throw new Error(wasRateLimited
+        ? "Login timed out -- the registry kept rate limiting the poll. Wait a bit and run `ahood login` again."
+        : "Login timed out. Run `ahood login` again.");
 }
 // Not apiJson: a non-2xx poll response ("pending", still-provisioning, etc.)
 // is expected and must not throw -- the status code is inspected by the

package/dist/commands/mcp.js

@@ -1,7 +1,10 @@
 import { startMcpServer } from "../mcp/server.js";
-// `ahood mcp` takes no subcommands/flags in v1. Unlike every other
-// account-scoped command it never returns until the client disconnects --
-// see startMcpServer's comment.
+// Starts the local stdio MCP server -- reached as bare `ahood mcp` (the
+// original v1 contract, kept byte-for-byte for existing host configs) or
+// `ahood mcp serve`; index.ts's dispatchMcp() decides which first words mean
+// "serve" and which are registry verbs (ahood-cli#172). Unlike every other
+// command it never returns until the client disconnects -- see
+// startMcpServer's comment.
 export async function mcp(_args) {
     await startMcpServer();
 }

package/dist/commands/publish.js

@@ -6,6 +6,26 @@ import { apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill, SEMVER_RE, validateExternalUrl } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind, strictKind } from "../kinds.js";
+// `ahood agent publish` / `ahood mcp publish` (ahood-cli#172): an existing
+// entry of another kind must be refused before anything is packed, created,
+// or uploaded. The upload would fail server-side anyway -- the processing
+// workflow validates the archive against the entry's stored kind -- but only
+// after a version row was created and a full upload spent. A 404 is the
+// "doesn't exist yet" case publish already handles by creating the entry,
+// now with the scope's kind.
+async function assertPublishTargetKind(scope, owner, skill) {
+    let detail;
+    try {
+        detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 404)
+            return;
+        throw error;
+    }
+    assertKind(scope, `${owner}/${skill}`, detail.kind, "publish", "publish a new version of");
+}
 // Processing (decompress/validate/checksum/scan/upload) now happens in a
 // background workflow, not inline in versions/complete's response (server
 // issue #120) -- complete returns 202 immediately, so this polls
@@ -342,10 +362,18 @@ async function initVersion(owner, skill, version, packageSizeBytes, changelog, c
 // validation, network, or a rejected publish -- still yields exactly one
 // JSON object (`{error}`) rather than a human message, while still
 // rethrowing so index.ts's exit-code mapping (exitCodeFor) is unaffected.
-export async function publish(args) {
+export async function publish(args, scope) {
     const jsonOutput = args.includes("--json");
     try {
-        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository, kind, changelog } = parsePublishArgs(args);
+        const parsed = parsePublishArgs(args);
+        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository, changelog } = parsed;
+        // A kind-scoped publish implies its kind. The dispatcher has already
+        // refused a contradictory --kind before this runs, so the flag (when the
+        // legacy `ahood skill publish` passes one through) and the scope can't
+        // disagree here.
+        const scopedKind = strictKind(scope);
+        const kind = scopedKind ?? parsed.kind;
+        const via = scopedKind ? `ahood ${scope.noun} publish` : `publish --kind ${kind}`;
         const skillMdPath = join(path, "SKILL.md");
         const agentMdPath = join(path, "AGENT.md");
         const serverJsonPath = join(path, "server.json");
@@ -355,15 +383,15 @@ export async function publish(args) {
         let resolvedKind = kind;
         if (kind === "agent") {
             if (!hasAgentMd)
-                throw new Error(`No AGENT.md found at ${agentMdPath} -- publish --kind agent must point at a folder containing AGENT.md.`);
+                throw new Error(`No AGENT.md found at ${agentMdPath} -- ${via} must point at a folder containing AGENT.md.`);
         }
         else if (kind === "skill") {
             if (!hasSkillMd)
-                throw new Error(`No SKILL.md found at ${skillMdPath} -- publish --kind skill must point at a folder containing SKILL.md.`);
+                throw new Error(`No SKILL.md found at ${skillMdPath} -- ${via} must point at a folder containing SKILL.md.`);
         }
         else if (kind === "mcp") {
             if (!hasServerJson)
-                throw new Error(`No server.json found at ${serverJsonPath} -- publish --kind mcp must point at a folder containing server.json.`);
+                throw new Error(`No server.json found at ${serverJsonPath} -- ${via} must point at a folder containing server.json.`);
         }
         else {
             // kind === undefined -- infer from whichever root file(s) are actually present
@@ -390,6 +418,8 @@ export async function publish(args) {
         if (resolvedKind === "skill" || (resolvedKind === undefined && hasSkillMd)) {
             warnAboutSkillDescription(skillMdPath);
         }
+        if (scopedKind !== undefined)
+            await assertPublishTargetKind(scope, owner, skill);
         const archive = await tarGzDirectory(path);
         const { init, created } = await initVersion(owner, skill, version, archive.length, changelog, { name, tagline, tags, license, homepage, repository, kind: resolvedKind }, jsonOutput);
         // TS's lib.dom BodyInit (in scope here since tsconfig has no explicit

package/dist/commands/read.js

@@ -1,6 +1,8 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
+import { sanitizeDocumentForTerminal, sanitizeForTerminal } from "../terminal-safe.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill read <owner>/<skill> [--json]";
 export async function readSkillMd(owner, skill) {
     const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
@@ -12,8 +14,16 @@ export async function readSkillMd(owner, skill) {
     // be silent about handing back a yanked version's content. Written to
     // stderr, not stdout -- safe for MCP callers too (only stdout is reserved
     // for the JSON-RPC stream).
+    //
+    // yanked_reason is publisher-controlled free text interpolated into a
+    // CLI-authored line, which is exactly sanitizeForTerminal's case (and
+    // exactly what add.ts does with manifest fields) -- not the document case
+    // below, so it keeps the flatten-newlines/200-char defaults rather than
+    // sanitizeDocumentForTerminal. Unconditional, not TTY-gated: nothing
+    // round-trips a warning, so there is no byte-exactness to preserve here
+    // (ahood-cli#133).
     if (detail.skill_versions.yanked_at) {
-        console.warn(`WARNING: ${detail.owner}/${detail.slug}@${detail.skill_versions.version} has been yanked${detail.skill_versions.yanked_reason ? `: ${detail.skill_versions.yanked_reason}` : "."}`);
+        console.warn(`WARNING: ${detail.owner}/${detail.slug}@${detail.skill_versions.version} has been yanked${detail.skill_versions.yanked_reason ? `: ${sanitizeForTerminal(detail.skill_versions.yanked_reason)}` : "."}`);
     }
     const content = detail.skill_versions.skill_md_content;
     if (!content) {
@@ -32,12 +42,13 @@ export async function readSkillMd(owner, skill) {
         yanked_reason: detail.skill_versions.yanked_reason ?? null,
     };
 }
-export async function read(args) {
+export async function read(args, scope) {
     const jsonOutput = args.includes("--json");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
         throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    await ensureRemoteKind(scope, owner, skill, "read", "read");
     const { version, content } = await readSkillMd(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify({ version, content }));
@@ -52,5 +63,22 @@ export async function read(args) {
     // a real, reported round-trip mismatch between "ahood skill read" and the
     // source file, even though the registry itself stores/serves the content
     // byte-exact (ahood-cli#90).
+    //
+    // That byte-exactness is a promise made to a *pipe*, though, and #90 is the
+    // only reason the raw write exists. A human looking at a terminal gets no
+    // value from it and pays for it with every control sequence the publisher
+    // chose to embed, because skill_md_content is publisher-controlled free text
+    // and `skill read` is the command the CLI advertises for inspecting a skill
+    // *before* installing it -- the cautious path. An embedded OSC 52
+    // ("\x1b]52;c;<base64>\x07") silently overwrites the reader's system
+    // clipboard on xterm/kitty/wezterm/foot; cheaper variants retitle the window
+    // (OSC 0), clear the screen and forge "verified safe" output (ESC[2J ESC[H),
+    // or switch charsets (ESC(0) and corrupt every later line in the session. So
+    // strip on the TTY path only, leaving the redirected path the exact bytes
+    // #90 guaranteed (ahood-cli#133).
+    if (process.stdout.isTTY) {
+        process.stdout.write(sanitizeDocumentForTerminal(content));
+        return;
+    }
     process.stdout.write(content);
 }

package/dist/commands/remove.js

@@ -1,11 +1,37 @@
-import { existsSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, rmSync } from "node:fs";
 import { confirm } from "../confirm.js";
 import { readLockfile, removeLockfileEntry, withLock, writeJsonFileAtomic } from "../lockfile.js";
 import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, MCP_CONFIG_PATH } from "../spec.js";
 import { readMcpConfig, matchesMcpConfigHash } from "./add.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind, ensureRemoteKind, KindMismatchError, describeKind, localInstalledKind, strictKind, } from "../kinds.js";
+// `ahood agent remove` / `ahood mcp remove` (ahood-cli#172): decide whether
+// this install really is the scope's kind BEFORE the prompt and every delete
+// below. Local evidence first -- remove has always worked offline, and the
+// footprint answers it for every install made by a current CLI. Only a pin
+// whose footprint is ambiguous (a pre-fingerprint mcp pin, or a skill whose
+// directory was deleted by hand) asks the registry, and if that can't answer
+// either, nothing is removed.
+async function assertInstalledKind(scope, owner, skill, lockEntry) {
+    const key = `${owner}/${skill}`;
+    const local = localInstalledKind(owner, skill, lockEntry);
+    if (local !== undefined) {
+        assertKind(scope, key, local, "remove", "remove");
+        return;
+    }
+    try {
+        await ensureRemoteKind(scope, owner, skill, "remove", "remove");
+    }
+    catch (error) {
+        if (error instanceof KindMismatchError)
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not confirm that ${key} is installed as ${describeKind(strictKind(scope))}: its local files don't say, and the registry lookup failed (${reason}). ` +
+            `Nothing was removed. Use \`ahood skill remove ${key}\` (legacy, any kind) to remove it anyway.`);
+    }
+}
 const USAGE = "Usage: ahood skill remove <owner>/<skill> [--yes]";
-export async function remove(args) {
+export async function remove(args, scope) {
     const spec = args[0];
     if (!spec)
         throw new UsageError(USAGE);
@@ -22,11 +48,21 @@ export async function remove(args) {
     const agentExisted = existsSync(agentFile);
     const lockEntry = readLockfile(LOCKFILE_PATH)[key];
     const hadLockfileEntry = lockEntry !== undefined;
+    // A pin whose install left nothing on disk is the defining shape of an
+    // mcp-kind install: its only footprint is this pin plus a live .mcp.json
+    // entry. Kept as evidence for the unreadable-.mcp.json warning at the
+    // bottom because, unlike mcp_config_hash, it exists for entries installed
+    // before that field did (lockfile.ts: "absent for any mcp entry installed
+    // before this field existed") and it is computed HERE, above the .mcp.json
+    // read -- so it survives the case where that read throws (ahood-cli#143).
+    const hadNoOnDiskFootprint = !dirExisted && !agentExisted && hadLockfileEntry;
     if (!dirExisted && !agentExisted && !hadLockfileEntry) {
         console.error(`${key} was not installed -- nothing to remove.`);
         process.exitCode = 1;
         return;
     }
+    if (scope && strictKind(scope) !== undefined)
+        await assertInstalledKind(scope, owner, skill, lockEntry);
     // Matches unpublish.ts/group.ts's confirm-before-destroy pattern (CLAUDE.md:
     // "Destructive commands ... prompt for confirmation unless --yes is passed").
     // Checked only once something is actually installed, so a no-op remove of an
@@ -36,16 +72,32 @@ export async function remove(args) {
         console.log("Aborted.");
         return;
     }
+    // Every artifact the pin points at is deleted BEFORE the pin itself, which
+    // is cleared exactly once at the end of this function. The two interruption
+    // states are not symmetric, which is the whole reason for the ordering: a
+    // pin left behind after its artifact is gone is a dangling reference that a
+    // re-run of this same command finds (hadLockfileEntry) and clears, while an
+    // artifact left behind after its pin is gone is invisible to list/update
+    // forever -- and for an mcp-kind install that artifact is a live .mcp.json
+    // entry holding a resolved secret (ahood-cli#142). The rule is applied
+    // uniformly rather than per-kind: the directory and agent file are lower
+    // stakes (no secret, and a re-run's own existsSync rediscovers them), but
+    // ordering them by stakes would just make the invariant harder to keep.
+    //
+    // `force: true` on both, rather than trusting the existsSync taken at the
+    // top: an unbounded confirm() prompt sits between that check and here, so
+    // the path may legitimately be gone by now. Without it, unlinkSync threw a
+    // raw ENOENT that propagated out and skipped the pin clear below, leaving
+    // the pin behind for a file that no longer existed (ahood-cli#142).
     if (dirExisted)
         rmSync(dir, { recursive: true, force: true });
     if (agentExisted)
-        unlinkSync(agentFile);
-    removeLockfileEntry(LOCKFILE_PATH, key);
+        rmSync(agentFile, { force: true });
     // An mcp-kind install has no directory or agent file on disk -- its only
-    // footprint here is the lockfile entry just cleared above and a live
-    // entry in .mcp.json (which add.ts's installMcpEntry merged in, possibly
-    // holding a resolved secret in its `env`). Real removal (delete that one
-    // key) only happens when the on-disk entry's fingerprint still matches
+    // footprint is the lockfile entry (cleared below, once this block has run)
+    // and a live entry in .mcp.json (which add.ts's installMcpEntry merged in,
+    // possibly holding a resolved secret in its `env`). Real removal (delete
+    // that one key) only happens when the on-disk entry's fingerprint matches
     // what was recorded at install/update time -- same posture as add.ts's
     // own assertNoCollision: never blind-write/delete something this process
     // didn't verify it still owns. Without SOME check here, "Removed" would
@@ -77,9 +129,9 @@ export async function remove(args) {
         // path. But leaving every flag false here meant the unreadable case
         // printed a bare "Removed" with the entry (and its secret) still live,
         // the very false-assurance bug the block above exists to prevent
-        // (ahood-cli#115). The lockfile's mcp_config_hash, read at the top of
-        // this function before the pin was cleared, is direct evidence that
-        // ahood DID install an entry into this file, so record why the read
+        // (ahood-cli#115). Both the lockfile's mcp_config_hash and
+        // hadNoOnDiskFootprint, read at the top of this function, are evidence
+        // that ahood DID install an entry into this file, so record why the read
         // failed and warn off that instead of off a shape we can't inspect.
         mcpConfigUnreadable = error instanceof Error ? error.message : String(error);
     }
@@ -114,7 +166,26 @@ export async function remove(args) {
             // removedMcpEntry stays false -- falls through to the warning below.
         }
     }
-    if (mcpConfigUnreadable !== undefined && lockEntry?.mcp_config_hash !== undefined) {
+    // Last, per the ordering note above: everything this pin could point at has
+    // now either been deleted or been diagnosed and warned about below, so the
+    // pin has no surviving work left to surface (ahood-cli#142).
+    removeLockfileEntry(LOCKFILE_PATH, key);
+    if (mcpConfigUnreadable !== undefined && (lockEntry?.mcp_config_hash !== undefined || hadNoOnDiskFootprint)) {
+        // Two independent pieces of evidence, because mcp_config_hash alone is
+        // not sufficient: it is absent for any mcp entry installed before that
+        // field existed, and for such a legacy pin the unreadable read also
+        // leaves mcpEntryPresent false -- so the `else if` below could not fire
+        // either and #115's fix silently did not apply, printing the bare
+        // "Removed" with the entry and its credential still live (ahood-cli#143).
+        // hadNoOnDiskFootprint closes that hole without needing the missing
+        // field. It cannot be narrowed further from the lockfile alone (LockEntry
+        // records no `kind`), so a skill whose directory was deleted by hand
+        // before this ran looks identical to a legacy mcp pin and warns too --
+        // deliberately, since the only thing that could tell them apart is the
+        // .mcp.json read that just failed, and a hedged sentence is the cheaper
+        // error of the two. A plain skill install still has its directory, so
+        // that far more common shape stays silent as ahood-cli#115 requires.
+        //
         // Its own wording rather than the branch below's: "remove it manually"
         // isn't actionable while the file doesn't parse, and we can't say the
         // entry is definitely still there -- only that one was installed and

package/dist/commands/search.js

@@ -1,15 +1,23 @@
 import { apiJson } from "../http.js";
 import { flagValue, parseSearchQuery } from "../flags.js";
 import { UsageError } from "../usage-error.js";
+import { KINDS, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill search <query> [--json] [--limit <n>]";
-export async function searchSkills(query, limit) {
+// `kind` narrows the search server-side (GET /api/v1/skills?kind=, which the
+// backend validates against its ALLOWED_KINDS). Omitted -- the legacy
+// `ahood skill search` and the MCP skill_search tool -- the request is
+// byte-for-byte what it always was: every kind.
+export async function searchSkills(query, limit, kind) {
     const qs = new URLSearchParams({ q: query });
     if (limit !== undefined)
         qs.set("per_page", String(limit));
+    if (kind !== undefined)
+        qs.set("kind", kind);
     const { skills } = await apiJson(`/api/v1/skills?${qs}`);
     return skills ?? [];
 }
-export async function search(args) {
+export async function search(args, scope) {
+    const kind = strictKind(scope);
     const jsonOutput = args.includes("--json");
     const limitStr = flagValue(args, "--limit");
     const query = parseSearchQuery(args, USAGE);
@@ -17,13 +25,13 @@ export async function search(args) {
         throw new UsageError(`--limit must be a positive integer (got "${limitStr}").\n${USAGE}`);
     }
     const limit = limitStr !== undefined ? Number(limitStr) : undefined;
-    const skills = await searchSkills(query, limit);
+    const skills = await searchSkills(query, limit, kind);
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;
     }
     if (skills.length === 0) {
-        console.log("No skills found.");
+        console.log(kind ? `No ${KINDS[kind].plural} found.` : "No skills found.");
         return;
     }
     for (const skill of skills) {