@ahood/cli 0.5.1 → 0.6.0

package/dist/commands/whoami.js

@@ -14,26 +14,20 @@ async function fetchProfile() {
         return undefined;
     }
 }
-export async function whoami(args = []) {
-    const wantsJson = args.includes("--json");
+// Pure auth-status check: no console output, no process.exitCode -- callers
+// (the CLI's whoami() below, and the MCP whoami tool) decide how to present
+// each outcome. Never throws; every failure mode is a normal return value.
+export async function checkAuth() {
     const token = resolveToken();
     if (!token) {
-        // Previously exited 0 here, defeating whoami's purpose as a scriptable
-        // auth check -- "no token configured at all" must fail just like "token
-        // rejected by the server" does below.
-        if (wantsJson)
-            console.log(JSON.stringify({ authenticated: false }));
-        else
-            console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
-        process.exitCode = 1;
-        return;
+        return { authenticated: false, reason: "not_logged_in" };
     }
     // There is no endpoint that returns an identity for a bearer caller yet, so
-    // whoami can only answer "does this token still authenticate?". It probes
+    // this can only answer "does this token still authenticate?". It probes
     // /api/v1/auth/tokens, which is deliberately session-only (Task 3), and
     // reads the STATUS to tell the two failure modes apart -- swallowing every
-    // error and printing "Authenticated." unconditionally (as this did) meant a
-    // revoked token and a garbage token both reported success with exit code 0.
+    // error and reporting success unconditionally (as this used to) meant a
+    // revoked token and a garbage token both reported success.
     //   403 -> resolveCaller accepted the token, the route then rejected it for
     //          being a token rather than a session. The token is valid.
     //   401 -> resolveCaller could not resolve the token at all: unknown,
@@ -45,35 +39,66 @@ export async function whoami(args = []) {
         // A session-backed caller (only reachable if this ever runs against a
         // cookie-bearing client) -- the token list came back.
         const profile = await fetchProfile();
-        if (wantsJson)
-            console.log(JSON.stringify({ authenticated: true, mode: "session", ...profile }));
-        else
-            console.log(profile ? `Authenticated as ${profile.username}.` : "Authenticated.");
+        return { authenticated: true, mode: "session", profile };
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 403) {
             const profile = await fetchProfile();
-            if (wantsJson)
-                console.log(JSON.stringify({ authenticated: true, mode: "token", ...profile }));
-            else
-                console.log(profile
-                    ? `Authenticated as ${profile.username} (personal API token).`
-                    : "Authenticated with a personal API token.");
-            return;
+            return { authenticated: true, mode: "token", profile };
         }
         if (error instanceof ApiError && error.status === 401) {
-            if (wantsJson)
-                console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
-            else
-                console.error("Not authenticated -- your token is invalid or has been revoked.");
-            process.exitCode = 1;
-            return;
+            return { authenticated: false, reason: "invalid_token" };
         }
         const message = error instanceof Error ? error.message : String(error);
+        return { authenticated: null, error: message };
+    }
+}
+export async function whoami(args = []) {
+    const wantsJson = args.includes("--json");
+    const result = await checkAuth();
+    if (result.authenticated === false && result.reason === "not_logged_in") {
+        // Previously exited 0 here, defeating whoami's purpose as a scriptable
+        // auth check -- "no token configured at all" must fail just like "token
+        // rejected by the server" does below. Exit 4 ("authentication required
+        // or rejected"), not the generic 1 -- this is exactly the case the
+        // README's own exit-code table names as the canonical example of 4
+        // (ahood-cli#80).
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: false }));
+        else
+            console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
+        process.exitCode = 4;
+        return;
+    }
+    if (result.authenticated === false && result.reason === "invalid_token") {
+        // Same exit-4 reasoning as the "no token at all" branch above: the
+        // token was rejected by the server, which is the other half of the
+        // README's exit-code-4 definition ("or the token was refused").
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
+        else
+            console.error("Not authenticated -- your token is invalid or has been revoked.");
+        process.exitCode = 4;
+        return;
+    }
+    if (result.authenticated === null) {
         if (wantsJson)
-            console.log(JSON.stringify({ authenticated: null, error: message }));
+            console.log(JSON.stringify({ authenticated: null, error: result.error }));
         else
-            console.error(`Could not verify your token: ${message}`);
+            console.error(`Could not verify your token: ${result.error}`);
         process.exitCode = 1;
+        return;
+    }
+    if (wantsJson) {
+        console.log(JSON.stringify({ authenticated: true, mode: result.mode, ...result.profile }));
+        return;
+    }
+    if (result.mode === "session") {
+        console.log(result.profile ? `Authenticated as ${result.profile.username}.` : "Authenticated.");
+    }
+    else {
+        console.log(result.profile
+            ? `Authenticated as ${result.profile.username} (personal API token).`
+            : "Authenticated with a personal API token.");
     }
 }

package/dist/config.js

@@ -1,3 +1,4 @@
+import { UsageError } from "./usage-error.js";
 const DEFAULT_API_URL = "https://ahood.vercel.app";
 let warnedAboutOverride = false;
 // AHOOD_API_URL is trusted with the bearer token on every request (see
@@ -15,7 +16,7 @@ export function getApiUrl() {
         url = new URL(trimmed);
     }
     catch {
-        throw new Error(`AHOOD_API_URL is not a valid URL: "${configured}"`);
+        throw new UsageError(`AHOOD_API_URL is not a valid URL: "${configured}"`);
     }
     // Plain http:// is only allowed for localhost and the RFC 2606 reserved
     // test TLDs (.test/.invalid/.example/.localhost), which can never resolve
@@ -26,7 +27,7 @@ export function getApiUrl() {
         url.hostname === "::1" ||
         /\.(test|invalid|example|localhost)$/i.test(url.hostname);
     if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocalHost)) {
-        throw new Error(`AHOOD_API_URL must use https:// (http:// is only allowed for localhost/test hosts); got "${configured}".`);
+        throw new UsageError(`AHOOD_API_URL must use https:// (http:// is only allowed for localhost/test hosts); got "${configured}".`);
     }
     if (trimmed !== DEFAULT_API_URL && !warnedAboutOverride) {
         console.error(`warning: using non-default API endpoint from AHOOD_API_URL: ${trimmed}`);

package/dist/exit-code.js

@@ -1,10 +1,19 @@
 import { ApiError, NetworkError } from "./http.js";
+import { UsageError } from "./usage-error.js";
 // A hung/black-holed connection throws undici's generic TypeError("fetch
 // failed") -- http.ts wraps that into NetworkError so it gets its own exit
 // code here, distinct from a server-returned ApiError. Kept in its own
 // module (rather than inline in index.ts) so it's importable in tests
 // without triggering index.ts's unconditional top-level main() call.
 export function exitCodeFor(error) {
+    // A local validation failure (missing/malformed argument, bad flag value)
+    // is exactly the "bad arguments" half of exit code 2's documented meaning
+    // -- same code the server-rejected branch below already uses, so a caller
+    // branching on exit code sees one consistent "fix your input" signal
+    // regardless of whether the check ran locally or round-tripped to the
+    // server (ahood-cli#80).
+    if (error instanceof UsageError)
+        return 2;
     if (error instanceof ApiError) {
         if (error.status === 401 || error.status === 403)
             return 4;

package/dist/flags.js

@@ -1,3 +1,4 @@
+import { UsageError } from "./usage-error.js";
 // Shared flag-value parsing. Throws instead of silently treating the next flag
 // as this flag's value (e.g. `--tagline --visibility public` used to send
 // "--visibility" as the tagline and drop --visibility entirely).
@@ -20,7 +21,7 @@ export function flagValue(args, flag) {
         if (arg === flag) {
             const value = args[i + 1];
             if (value === undefined || value.startsWith("--")) {
-                throw new Error(`${flag} requires a value.`);
+                throw new UsageError(`${flag} requires a value.`);
             }
             return value;
         }

package/dist/help.js

@@ -26,6 +26,14 @@ export const TOP_LEVEL_COMMANDS_HELP = [
         desc: "Print a shell completion script for the command names.",
         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, 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.",
+    },
 ];
 export const SKILL_COMMANDS_HELP = [
     {
@@ -71,7 +79,11 @@ export const SKILL_COMMANDS_HELP = [
     {
         usage: "ahood skill add <owner>/<skill>[@version]",
         summary: "Install a skill into .claude/skills/, pinned in the lockfile.",
-        desc: "Install a skill into .claude/skills/, pinned in the lockfile.",
+        desc: "Install a skill into .claude/skills/, pinned in the lockfile. An artifact published with --kind agent " +
+            "installs instead as a single file at .claude/agents/<owner>@<skill>.md (Claude Code's own subagent " +
+            "loader scans .claude/agents/*.md as flat files), not a .claude/skills/ directory. An artifact published " +
+            "with --kind mcp installs by merging an entry into .mcp.json instead, prompting for any secret " +
+            "environment variables its server.json declares that aren't already set in your shell.",
         examples: ["ahood skill add alice/pdf-tools", "ahood skill add alice/pdf-tools@1.2.0"],
     },
     {
@@ -143,20 +155,23 @@ export const SKILL_COMMANDS_HELP = [
         examples: ["ahood skill init pdf-tools", "ahood skill init"],
     },
     {
-        usage: "ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]",
-        summary: "Publish a new version of a skill from a folder containing SKILL.md, creating the skill first if it doesn't already exist.",
-        desc: "Publish a new version of a skill from a folder containing SKILL.md. If the skill doesn't exist yet, this " +
-            "creates it first -- pass --name (required in that case) and optionally --tagline/--tags/--license/--homepage/--repository. " +
+        usage: "ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]",
+        summary: "Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json, creating the skill first if it doesn't already exist.",
+        desc: "Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json. If the artifact " +
+            "doesn't exist yet, this creates it first -- pass --name to set its display name, and --kind agent or --kind mcp if " +
+            "publishing an AGENT.md or server.json (auto-detected from the folder contents when only one of SKILL.md/AGENT.md/server.json is present). " +
+            "--name is required when creating; optionally also pass --tagline/--tags/--license/--homepage/--repository. " +
             "Processing happens server-side after upload; this command polls and reports the final published/failed status. " +
             "The legacy form `ahood skill publish <path> --owner <owner> --slug <skill> --version <x.y.z>` is still accepted. " +
             "Every flag also accepts the --flag=value form, needed when a value itself starts with --.",
         flags: [
-            "--name <text>                 Required only when creating the skill on this publish.",
+            "--kind skill|agent|mcp        What kind of artifact this is. Auto-detected from SKILL.md/AGENT.md/server.json when omitted.",
+            "--name <text>                 Required only when creating the artifact on this publish.",
             "--tagline <text>              Short one-line description, used only when creating.",
             "--tags <comma,separated>      Initial tags, used only when creating.",
             "--license <id>                An SPDX license identifier, e.g. MIT, used only when creating.",
-            "--homepage <url>              The skill's homepage URL, used only when creating.",
-            "--repository <url>            The skill's source repository URL, used only when creating.",
+            "--homepage <url>              The artifact's homepage URL, used only when creating.",
+            "--repository <url>            The artifact's source repository URL, used only when creating.",
             "--json                        Suppress human progress lines; print one {version,status,...} JSON object on completion (or {error} on failure).",
         ],
         examples: [
@@ -278,10 +293,74 @@ export function formatCommandHelp(entry) {
         lines.push("", "Examples:", ...entry.examples.map((e) => `  ${e}`));
     return lines.join("\n");
 }
+const FALLBACK_TERMINAL_WIDTH = 80;
+// Piped/redirected output (a script capturing `ahood skill --help`, a test)
+// has no TTY and so no column count -- falls back to a fixed width rather
+// than wrapping to whatever width happened to be inherited, so scripted use
+// gets stable, repeatable output.
+function terminalWidth() {
+    const columns = process.stdout.columns;
+    return columns && columns > 20 ? columns : FALLBACK_TERMINAL_WIDTH;
+}
+// Greedy word wrap -- doesn't split words, so a single word longer than
+// `width` is left on its own overlength line rather than being cut mid-word.
+function wrapText(text, width) {
+    if (width < 10)
+        return [text];
+    const words = text.split(" ");
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        const candidate = current ? `${current} ${word}` : word;
+        if (candidate.length > width && current) {
+            lines.push(current);
+            current = word;
+        }
+        else {
+            current = candidate;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines;
+}
+// Longest usage string an aligned label column will stretch to accommodate
+// -- past this, one outlier (e.g. `skill publish`'s usage line, with every
+// flag spelled out) would otherwise push every other row's description
+// column out with it, which is what made `ahood skill --help` wrap to
+// 300+ characters per line with no relation to the terminal's actual width
+// (ahood-cli#81). A row whose usage is longer than this gets its summary on
+// its own indented line instead of sharing the row.
+const MAX_LABEL_COLUMN = 50;
+// Renders a two-column command table (usage on the left, one-line summary on
+// the right, aligned and wrapped to the terminal width) -- shared by
+// formatSkillHelp/formatGroupHelp/formatHelp so all three `--help` listings
+// wrap the same way.
+function formatCommandTable(rows) {
+    const longest = Math.max(...rows.map((r) => r.usage.length));
+    const labelWidth = Math.min(longest, MAX_LABEL_COLUMN);
+    const columnWidth = labelWidth + 4; // 2-space left margin + 2-space gutter after the label
+    const summaryWidth = Math.max(20, terminalWidth() - columnWidth);
+    const indent = " ".repeat(columnWidth);
+    const lines = [];
+    for (const row of rows) {
+        const summaryLines = wrapText(row.summary, summaryWidth);
+        if (row.usage.length <= labelWidth) {
+            lines.push(`  ${row.usage.padEnd(labelWidth + 2)}${summaryLines[0]}`);
+        }
+        else {
+            lines.push(`  ${row.usage}`);
+            lines.push(`${indent}${summaryLines[0]}`);
+        }
+        for (const continuation of summaryLines.slice(1)) {
+            lines.push(`${indent}${continuation}`);
+        }
+    }
+    return lines;
+}
 // `ahood skill --help` -- the group-level listing for every skill verb.
 export function formatSkillHelp() {
-    const width = Math.max(...SKILL_COMMANDS_HELP.map((c) => usageWithAliases(c).length));
-    const lines = SKILL_COMMANDS_HELP.map((c) => `  ${usageWithAliases(c).padEnd(width + 2)}${c.summary}`);
+    const lines = formatCommandTable(SKILL_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
     return [
         "ahood skill -- manage skills in the ahood registry",
         "",
@@ -293,8 +372,7 @@ export function formatSkillHelp() {
 }
 // `ahood group --help` -- the group-level listing for every group verb.
 export function formatGroupHelp() {
-    const width = Math.max(...GROUP_COMMANDS_HELP.map((c) => usageWithAliases(c).length));
-    const lines = GROUP_COMMANDS_HELP.map((c) => `  ${usageWithAliases(c).padEnd(width + 2)}${c.summary}`);
+    const lines = formatCommandTable(GROUP_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
     return [
         "ahood group -- create private groups, invite members, and share skills with them",
         "",
@@ -312,12 +390,11 @@ export function formatHelp() {
     const skillGroupSummary = "Search, install, and publish skills -- run `ahood skill --help` for the full list.";
     const groupGroupUsage = "ahood group <command>";
     const groupGroupSummary = "Create private groups and share skills with them -- run `ahood group --help` for the full list.";
-    const width = Math.max(...TOP_LEVEL_COMMANDS_HELP.map((c) => usageWithAliases(c).length), skillGroupUsage.length, groupGroupUsage.length);
-    const lines = [
-        ...TOP_LEVEL_COMMANDS_HELP.map((c) => `  ${usageWithAliases(c).padEnd(width + 2)}${c.summary}`),
-        `  ${skillGroupUsage.padEnd(width + 2)}${skillGroupSummary}`,
-        `  ${groupGroupUsage.padEnd(width + 2)}${groupGroupSummary}`,
-    ];
+    const lines = formatCommandTable([
+        ...TOP_LEVEL_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })),
+        { usage: skillGroupUsage, summary: skillGroupSummary },
+        { usage: groupGroupUsage, summary: groupGroupSummary },
+    ]);
     return [
         "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
         "",

package/dist/index.js

@@ -18,6 +18,7 @@ import { view } from "./commands/view.js";
 import { read } from "./commands/read.js";
 import { versions } from "./commands/versions.js";
 import { completion } from "./commands/completion.js";
+import { mcp } from "./commands/mcp.js";
 import { init } from "./commands/init.js";
 import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
 import { formatHelp, formatSkillHelp, formatGroupHelp, formatCommandHelp, findCommandHelp } from "./help.js";
@@ -69,6 +70,7 @@ const COMMANDS = {
     whoami,
     token,
     completion,
+    mcp,
     skill: dispatchSkill,
     group: dispatchGroup,
 };

package/dist/lockfile.js

@@ -15,20 +15,29 @@ export function readLockfile(path) {
         throw new Error(`Lockfile at ${path} is corrupted and could not be parsed as JSON. Fix or delete it before continuing.`);
     }
 }
-function writeLockfile(path, lockfile) {
+// Generalized so callers other than the lockfile itself (e.g. add.ts's
+// .mcp.json merge, which sits right next to the lockfile and can hold other
+// servers' secrets) get the same crash-safety guarantee instead of a bare
+// writeFileSync that risks truncating the file on interruption.
+export function writeJsonFileAtomic(path, data) {
     mkdirSync(dirname(path), { recursive: true });
     // Write-then-rename so a process interrupted mid-write never leaves a
-    // truncated lockfile on disk -- a reader always sees either the old or the
-    // new complete content, never a partial one.
+    // truncated file on disk -- a reader always sees either the old or the new
+    // complete content, never a partial one.
     const tmpPath = `${path}.tmp-${process.pid}-${process.hrtime.bigint()}`;
-    writeFileSync(tmpPath, JSON.stringify(lockfile, null, 2) + "\n");
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
     renameSync(tmpPath, path);
 }
+function writeLockfile(path, lockfile) {
+    writeJsonFileAtomic(path, lockfile);
+}
 // Simple advisory lock via mkdir's atomicity (EEXIST on a second caller),
-// so two concurrent `ahood add`/`remove` invocations against the same
+// so two concurrent `ahood skill add`/`remove` invocations against the same
 // project don't race a read-modify-write and silently drop one another's
-// entry.
-function withLock(path, fn) {
+// entry. Exported so other same-directory JSON files with the same
+// read-modify-write shape (e.g. add.ts's .mcp.json merge) can reuse it
+// instead of duplicating the pattern.
+export function withLock(path, fn) {
     mkdirSync(dirname(path), { recursive: true });
     const lockDir = `${path}.lock`;
     const deadline = Date.now() + 5000;

package/dist/mcp/safe-tool.js

@@ -0,0 +1,46 @@
+import { ApiError, NetworkError } from "../http.js";
+import { UsageError } from "../usage-error.js";
+// Mirrors exit-code.ts's exitCodeFor categorization (ahood-cli#83) -- one
+// error taxonomy for both the CLI's exit codes and MCP's error_code field,
+// rather than maintaining two.
+export function errorCodeFor(error) {
+    if (error instanceof UsageError)
+        return "usage_error";
+    if (error instanceof ApiError) {
+        if (error.status === 401 || error.status === 403)
+            return "auth_error";
+        if (error.status === 404)
+            return "not_found";
+        if (error.status >= 500)
+            return "network_error";
+        return "usage_error";
+    }
+    if (error instanceof NetworkError)
+        return "network_error";
+    return "general_error";
+}
+// Wraps an MCP tool's data-fetching logic so a thrown error never crosses
+// the stdio boundary as a raw exception -- caught here and turned into a
+// structured isError result instead. `fn` is the tool's own core function
+// (e.g. searchSkills), already adapted to take the single zod-validated
+// input object each MCP tool callback receives.
+export function safeTool(fn) {
+    return async (input) => {
+        try {
+            const result = await fn(input);
+            // Defensive backstop: JSON.stringify(undefined) evaluates to the JS
+            // value `undefined`, not a string -- if any tool's core function ever
+            // returns undefined (e.g. a malformed API response missing an
+            // expected key), the MCP SDK rejects that as an invalid tool result
+            // and throws a raw protocol-level error instead of the structured
+            // isError result this wrapper exists to guarantee. Coalescing to null
+            // keeps `text` a string no matter what `fn` returns.
+            return { content: [{ type: "text", text: JSON.stringify(result ?? null) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const body = { error: message, error_code: errorCodeFor(error) };
+            return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+        }
+    };
+}

package/dist/mcp/server.js

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { CLI_VERSION } from "../version.js";
+// Split from startMcpServer so tests can build a server and connect it to an
+// InMemoryTransport instead of real stdio.
+export function buildServer() {
+    const server = new McpServer({ name: "ahood", version: CLI_VERSION });
+    registerTools(server);
+    return server;
+}
+// Connects over stdio and blocks: StdioServerTransport reads process.stdin
+// for the life of the process. This is expected -- an MCP host spawns
+// `ahood mcp` as a long-lived subprocess and talks to it over stdio for as
+// long as the session lasts.
+export async function startMcpServer() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/mcp/tools.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { safeTool } from "./safe-tool.js";
+import { searchSkills } from "../commands/search.js";
+import { viewSkill } from "../commands/view.js";
+import { readSkillMd } from "../commands/read.js";
+import { listSkillVersions } from "../commands/versions.js";
+import { listOwnSkills } from "../commands/list.js";
+import { checkAuth } from "../commands/whoami.js";
+import { validateSegment } from "../spec.js";
+// MCP tool inputs arrive as separate owner/skill zod fields (not a single
+// "<owner>/<skill>" spec string like the CLI's argv), so they bypass
+// parseOwnerSkill entirely and go straight to the core function -- which
+// URL-encodes them and hits the API. Running the same validateSegment checks
+// the CLI gets via parseOwnerSkill here closes that gap: an invalid segment
+// (e.g. "..") or an absurdly long one now fails locally as a UsageError
+// (safeTool maps it to error_code "usage_error") instead of reaching the
+// wire with the caller's bearer token.
+function validateOwnerAndSkill(owner, skill) {
+    const spec = `${owner}/${skill}`;
+    validateSegment(owner, "owner", spec);
+    validateSegment(skill, "skill", spec);
+}
+// Registers every v1 MCP tool. Read-only by design (ahood-cli#83's spec) --
+// each tool wraps the same core function the equivalent `ahood skill <verb>
+// --json` CLI path already calls, so there is exactly one source of truth
+// for what each of these returns.
+export function registerTools(server) {
+    server.registerTool("skill_search", {
+        description: "Search published skills in the ahood registry.",
+        inputSchema: { query: z.string().min(1), limit: z.number().int().positive().optional() },
+    }, safeTool(async ({ query, limit }) => searchSkills(query, limit)));
+    server.registerTool("skill_view", {
+        description: "Show a skill's details (tags, license, homepage, repository, dates, etc.) without installing it.",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return viewSkill(owner, skill);
+    }));
+    server.registerTool("skill_read", {
+        description: "Read a skill's full SKILL.md content without installing it.",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return readSkillMd(owner, skill);
+    }));
+    server.registerTool("skill_versions", {
+        description: "List a skill's published-version history (version, changelog, size, publish date).",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return listSkillVersions(owner, skill);
+    }));
+    server.registerTool("skill_list", {
+        description: "List the authenticated caller's own skills, public and private.",
+        inputSchema: {},
+    }, safeTool(async () => listOwnSkills()));
+    server.registerTool("whoami", {
+        description: "Report whether the configured token (AHOOD_TOKEN or a stored login) still authenticates.",
+        inputSchema: {},
+    }, safeTool(async () => checkAuth()));
+}

package/dist/secret-prompt.js

@@ -0,0 +1,74 @@
+import { createInterface } from "node:readline";
+// Masked secret-value prompt, extending confirm.ts's TTY-safe "close" race
+// (see confirm.ts's own comment): the same closed-stdin-never-resolves
+// problem, and the same fix -- a "close" listener rejects if it fires
+// before an answer is captured. Kept as its own module rather than folded
+// into confirm.ts because that module's contract is yes/no, not a typed
+// value, and because masking requires raw-mode keystroke handling that a
+// plain rl.question() call cannot do (readline always echoes verbatim when
+// its input is a TTY).
+export function promptSecret(promptText) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+        // Non-interactive stdin (piped input, CI, or these tests' fake
+        // Readable): fall back to an ordinary line-buffered question. There is
+        // no keystroke stream to mask in this mode -- the whole line arrives as
+        // one chunk -- and masking would only hide a value that's already
+        // sitting unmasked in whatever produced the pipe.
+        const rl = createInterface({ input: stdin, output: process.stdout });
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            rl.once("close", () => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new Error("Prompt was not answered (stdin closed)."));
+            });
+            rl.question(promptText, (answer) => {
+                settled = true;
+                rl.close();
+                resolve(answer);
+            });
+        });
+    }
+    process.stdout.write(promptText);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    return new Promise((resolve, reject) => {
+        let value = "";
+        function cleanup() {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(false);
+            stdin.pause();
+        }
+        function onData(chunk) {
+            for (const char of chunk) {
+                if (char === "\n" || char === "\r") {
+                    cleanup();
+                    process.stdout.write("\n");
+                    resolve(value);
+                    return;
+                }
+                if (char === "\u0003") {
+                    // Ctrl-C
+                    cleanup();
+                    process.stdout.write("\n");
+                    reject(new Error("Prompt cancelled (Ctrl-C)."));
+                    return;
+                }
+                if (char === "\u007f" || char === "\b") {
+                    // Backspace/delete
+                    if (value.length > 0) {
+                        value = value.slice(0, -1);
+                        process.stdout.write("\b \b");
+                    }
+                    continue;
+                }
+                value += char;
+                process.stdout.write("*");
+            }
+        }
+        stdin.on("data", onData);
+    });
+}