@ahood/cli 0.5.0 → 0.5.2

package/dist/help.js

@@ -71,7 +71,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 +147,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 +285,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 +364,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 +382,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/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/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);
+    });
+}

package/dist/spec.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { UsageError } from "./usage-error.js";
 // Owner and skill segments become filesystem path components (.claude/skills/<owner>/<skill>)
 // and URL path segments, so both are restricted to a safe charset that cannot contain "..",
 // "/", "\", or a leading dot -- this is what closes the path-traversal hole in add/remove
@@ -17,19 +18,19 @@ export const SEMVER_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-
 const MAX_SEGMENT_LENGTH = { owner: 32, skill: 64 };
 export function validateSegment(value, kind, spec) {
     if (!SEGMENT_RE.test(value) || value === "." || value === "..") {
-        throw new Error(`Invalid ${kind} "${value}" in "${spec}" -- must start with a letter/digit and contain only letters, digits, ".", "_", or "-".`);
+        throw new UsageError(`Invalid ${kind} "${value}" in "${spec}" -- must start with a letter/digit and contain only letters, digits, ".", "_", or "-".`);
     }
     const maxLength = MAX_SEGMENT_LENGTH[kind];
     if (value.length > maxLength) {
-        throw new Error(`Invalid ${kind} in "${spec.slice(0, 60)}${spec.length > 60 ? "..." : ""}" -- ${kind} segment is too long (${value.length} characters; must be at most ${maxLength}).`);
+        throw new UsageError(`Invalid ${kind} in "${spec.slice(0, 60)}${spec.length > 60 ? "..." : ""}" -- ${kind} segment is too long (${value.length} characters; must be at most ${maxLength}).`);
     }
 }
 export function parseOwnerSkill(spec, usage) {
     if (!spec)
-        throw new Error(usage);
+        throw new UsageError(usage);
     const parts = spec.split("/");
     if (parts.length !== 2 || !parts[0] || !parts[1])
-        throw new Error(usage);
+        throw new UsageError(usage);
     const [owner, skill] = parts;
     validateSegment(owner, "owner", spec);
     validateSegment(skill, "skill", spec);
@@ -37,15 +38,15 @@ export function parseOwnerSkill(spec, usage) {
 }
 export function parseOwnerSkillVersion(spec, usage) {
     if (!spec)
-        throw new Error(usage);
+        throw new UsageError(usage);
     const atIndex = spec.lastIndexOf("@");
     const ownerSkill = atIndex > 0 ? spec.slice(0, atIndex) : spec;
     const version = atIndex > 0 ? spec.slice(atIndex + 1) : "latest";
     if (atIndex > 0 && version === "") {
-        throw new Error(`Missing version after "@" in "${spec}".\n${usage}`);
+        throw new UsageError(`Missing version after "@" in "${spec}".\n${usage}`);
     }
     if (version !== "latest" && !SEMVER_RE.test(version)) {
-        throw new Error(`Invalid version "${version}" in "${spec}" -- expected "latest" or a semver like 1.2.3.\n${usage}`);
+        throw new UsageError(`Invalid version "${version}" in "${spec}" -- expected "latest" or a semver like 1.2.3.\n${usage}`);
     }
     const { owner, skill } = parseOwnerSkill(ownerSkill, usage);
     return { owner, skill, version };
@@ -67,10 +68,10 @@ export function validateExternalUrl(value, flag) {
         url = new URL(value);
     }
     catch {
-        throw new Error(`${flag} must be a valid http:// or https:// URL (got "${value}").`);
+        throw new UsageError(`${flag} must be a valid http:// or https:// URL (got "${value}").`);
     }
     if (url.protocol !== "https:" && url.protocol !== "http:") {
-        throw new Error(`${flag} must use http:// or https:// (got scheme "${url.protocol}" from "${value}").`);
+        throw new UsageError(`${flag} must use http:// or https:// (got scheme "${url.protocol}" from "${value}").`);
     }
 }
 export const SKILLS_ROOT = join(".claude", "skills");
@@ -78,3 +79,26 @@ export const LOCKFILE_PATH = join(".claude", "skills.lock.json");
 export function skillDir(owner, skill) {
     return join(SKILLS_ROOT, owner, skill);
 }
+// Claude Code's own subagent loader scans .claude/agents/*.md as flat files
+// (non-recursive), unlike .claude/skills/<owner>/<skill>/ which nests by
+// owner -- a bare .claude/agents/<skill>.md would let two different owners'
+// same-named agent collide and silently overwrite each other. Joining the
+// owner into the filename with "@" keeps the layout flat (so Claude Code
+// still finds it) while staying collision-resistant: SEGMENT_RE's character
+// class is exactly [a-z0-9._-] (case-insensitive), which does not include
+// "@" -- so "@" can never appear inside a valid owner or skill segment, and
+// the joined filename always contains exactly one "@", at the boundary
+// between the two segments. That makes the join unambiguous for any pair of
+// SEGMENT_RE-valid values, including ones containing hyphens (e.g.
+// owner="al-ice"/skill="bob" joins to "al-ice@bob.md", which cannot also be
+// produced by any other valid owner/skill pair). "@" is a valid filename
+// character on Linux, macOS, and Windows.
+export const AGENTS_ROOT = join(".claude", "agents");
+export function agentPath(owner, skill) {
+    return join(AGENTS_ROOT, `${owner}@${skill}.md`);
+}
+// .mcp.json lives at the project root -- Claude Code's own convention for
+// MCP server configuration (unlike .claude/skills or .claude/agents, this
+// file isn't under .claude/ at all, since it's a convention MCP clients
+// broadly share, not one specific to this CLI).
+export const MCP_CONFIG_PATH = ".mcp.json";

package/dist/usage-error.js

@@ -0,0 +1,8 @@
+// Thrown for a usage/validation error caught locally, before any network
+// call -- a missing/malformed argument, an invalid flag value, a bad
+// owner/skill spec, etc. Kept distinct from a plain Error so exit-code.ts's
+// exitCodeFor() can map it to exit code 2 ("usage or validation error", per
+// the README's exit-code table) instead of falling through to the generic 1
+// ("general error") that every other thrown Error gets (ahood-cli#80).
+export class UsageError extends Error {
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",