@ahood/cli 0.8.8 → 0.10.0

package/dist/commands/share.js

@@ -2,6 +2,7 @@ import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 // These are skill-entity verbs (reached as `ahood skill share`/`ahood skill
 // unshare`, registered in SKILL_COMMANDS in index.ts), not group verbs --
 // they mutate a skill's sharing, not a group. Grouped together in one file
@@ -14,7 +15,7 @@ const UNSHARE_USAGE = "Usage: ahood skill unshare <owner>/<skill> --group <group
 // first (before any flags), since --group takes a value and a "first
 // non---flag token" scan would misidentify the --group value as the spec
 // if --group happened to come first.
-export async function share(args) {
+export async function share(args, scope) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
         throw new UsageError(SHARE_USAGE);
@@ -22,6 +23,7 @@ export async function share(args) {
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
         throw new UsageError(SHARE_USAGE);
+    await ensureRemoteKind(scope, owner, skill, "share", "share");
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -29,7 +31,7 @@ export async function share(args) {
     });
     console.log(`Shared ${owner}/${skill} with ${groupSlug}.`);
 }
-export async function unshare(args) {
+export async function unshare(args, scope) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
         throw new UsageError(UNSHARE_USAGE);
@@ -37,6 +39,7 @@ export async function unshare(args) {
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
         throw new UsageError(UNSHARE_USAGE);
+    await ensureRemoteKind(scope, owner, skill, "unshare", "unshare");
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share/${encodeURIComponent(groupSlug)}`, { method: "DELETE" });
     console.log(`Unshared ${owner}/${skill} from ${groupSlug}.`);
 }

package/dist/commands/snap.js

@@ -1,15 +1,15 @@
 import { apiJson } from "../http.js";
-import { flagValue, parseSearchQuery } from "../flags.js";
+import { flagValue, parseSearchQuery, unrecognizedArgs, unrecognizedIndices } from "../flags.js";
 import { confirm } from "../confirm.js";
 import { UsageError } from "../usage-error.js";
-const CREATE_USAGE = "Usage: ahood snap create <content> [--tags tag1,tag2] (or pipe content on stdin)";
+const CREATE_USAGE = "Usage: ahood snap create <content> [--tags tag1,tag2] (or pipe content on stdin; put -- before content that starts with --)";
 const LIST_USAGE = "Usage: ahood snap list [--json] [--limit <n>] [--tags tag1,tag2]";
 const SEARCH_USAGE = "Usage: ahood snap search <query> [--json] [--limit <n>] [--tags tag1,tag2]";
 const SHOW_USAGE = "Usage: ahood snap show <id> [--json]";
 const REMOVE_USAGE = "Usage: ahood snap remove <id> [--yes]";
 const SHARE_USAGE = "Usage: ahood snap share <id> [--json]";
 const UNSHARE_USAGE = "Usage: ahood snap unshare <id> [--yes]";
-const TAGS_USAGE = "Usage: ahood snap tags <id> [tag1,tag2,...] [--json] (omit or pass an empty value to clear all tags)";
+const TAGS_USAGE = 'Usage: ahood snap tags <id> [tag ...] [--clear] [--json] (with no tag list, prints the snap\'s current tags; pass --clear or "" to remove them all)';
 // There's no existing "read stdin to completion" helper in this codebase to
 // reuse -- confirm.ts and secret-prompt.ts both only ever read a single
 // line via readline, never an arbitrary-length paste/pipe. Standard Node
@@ -60,15 +60,61 @@ function printSnaps(jsonOutput, snaps, emptyMessage) {
     }
 }
 export async function createSnap(args) {
-    const jsonOutput = args.includes("--json");
-    const tagsArg = flagValue(args, "--tags");
+    // POSIX end-of-options: everything after a bare "--" is content, verbatim,
+    // never a flag. Snap content is freeform, so a note that legitimately begins
+    // with "--" would otherwise be unexpressible once the unknown-flag check
+    // below lands -- `--tags=value` is exactly that escape hatch for the flag
+    // (flags.ts), and content had none (ahood-cli#134).
+    //
+    // Scoped to `create` rather than made group-wide on purpose: it's the only
+    // snap verb whose argument is freeform text. `show`/`remove`/`share`/
+    // `unshare` take an id, `tags` a tag list and `search` a query -- all
+    // constrained enough that a leading "--" is always a mistake there, so "--"
+    // would buy them nothing -- and `search`'s parsing lives in the shared
+    // parseSearchQuery, which `skill search` also uses.
+    const endOfOptions = args.indexOf("--");
+    const flagArgs = endOfOptions === -1 ? args : args.slice(0, endOfOptions);
+    const literalArgs = endOfOptions === -1 ? [] : args.slice(endOfOptions + 1);
+    const jsonOutput = flagArgs.includes("--json");
+    const tagsArg = flagValue(flagArgs, "--tags");
+    // Whatever this command doesn't consume. --tags and its value (both
+    // "--tags x" and "--tags=x" forms) are stripped the same way --json is, so
+    // they never leak into the joined content.
+    const leftover = unrecognizedIndices(flagArgs, ["--json"], ["--tags"]);
+    // Every leftover used to be kept and folded into the note body, because
+    // content is freeform and a blanket "--" rejection would break a note that
+    // starts with a dash. That made a typo silently rewrite what got stored, at
+    // exit 0: `snap create "my note" --tag deploy` (singular) posted content
+    // "my note --tag deploy" with no tags at all, and `--limit 5` likewise
+    // (ahood-cli#134). With "--" above providing the escape hatch, refuse them
+    // instead -- the same rejection `snap tags` already does below.
+    const unknownFlag = leftover.map((i) => flagArgs[i]).find((a) => a.startsWith("--"));
+    if (unknownFlag)
+        throw new UsageError(`Unknown flag: ${unknownFlag}\n${CREATE_USAGE}`);
+    // The other half of ahood-cli#134, and the part no "--" check catches:
+    // `snap create "note" --tags deploy bugfix` posted content "note bugfix",
+    // because only the token immediately after --tags is consumed and the second
+    // word fell through into the body. A bare token is indistinguishable from a
+    // note word on its own -- `--tags deploy Debugged the CI` is a legitimate
+    // flags-first invocation -- so the signal isn't the token, it's that content
+    // ends up on BOTH sides of a flag. Nobody writes a note with a flag wedged
+    // mid-sentence; erroring there refuses the typo without outlawing either
+    // ordering. Not silently retagging "bugfix" either: guessing wrong steals a
+    // word out of the note, which is the same corruption in the other direction.
+    const gap = leftover.findIndex((at, n) => n > 0 && at !== leftover[n - 1] + 1);
+    if (gap !== -1) {
+        const stray = flagArgs[leftover[gap]];
+        const consumed = flagArgs[leftover[gap - 1] + 1];
+        throw new UsageError(`Note content is split across ${consumed}: "${stray}" comes after it and would be folded into the note. ` +
+            `Quote the whole note, or move every flag after it` +
+            (consumed === "--tags" ? `; pass multiple tags as one comma-separated value (--tags a,b)` : "") +
+            `.\n${CREATE_USAGE}`);
+    }
     // Joined, not just args[0] -- an unquoted multi-word note (e.g. `ahood
     // snap create Debugged the flaky CI step`) arrives as multiple positional
     // tokens, and taking only the first one silently dropped the rest with no
-    // error. Mirrors searchSnaps' own query-joining below. --tags and its
-    // value (both "--tags x" and "--tags=x" forms) are stripped the same way
-    // --json is, so they never leak into the joined content.
-    const positionals = args.filter((a, i) => a !== "--json" && a !== "--tags" && !a.startsWith("--tags=") && args[i - 1] !== "--tags");
+    // error. Mirrors searchSnaps' own query-joining below.
+    const positionals = [...leftover.map((i) => flagArgs[i]), ...literalArgs];
     const positional = positionals.length > 0 ? positionals.join(" ") : undefined;
     let content;
     if (positional !== undefined) {
@@ -114,6 +160,22 @@ export async function listSnaps(args) {
     const jsonOutput = args.includes("--json");
     const limitStr = flagValue(args, "--limit");
     const tagsStr = flagValue(args, "--tags");
+    // Reject whatever this command doesn't accept instead of issuing an
+    // unfiltered request and presenting the result as the filtered set:
+    // `snap list --tag ci` (singular typo) used to send no tags param at all and
+    // print every snap, while the sibling `snap search --tag ci` refused the
+    // identical typo -- so a user filtering for "deploy" and seeing three snaps
+    // couldn't tell them from the three most recent (ahood-cli#135). That's the
+    // same silent-broadening this command's verbatim --tags pass-through below
+    // was chosen to avoid; it was defended at the small end and left open at the
+    // large one. `snap list` takes no positional argument either, and nothing
+    // upstream gives a stray token a meaning (index.ts's dispatchSnap consumes
+    // only the verb, and intercepts --help/-h before the handler runs), so an
+    // extra positional is a mistake too rather than something to ignore.
+    const extra = unrecognizedArgs(args, ["--json"], ["--limit", "--tags"])[0];
+    if (extra !== undefined) {
+        throw new UsageError(`${extra.startsWith("--") ? "Unknown flag" : "Unexpected argument"}: ${extra}\n${LIST_USAGE}`);
+    }
     validateLimit(limitStr, LIST_USAGE);
     const qs = new URLSearchParams();
     if (limitStr !== undefined)
@@ -226,9 +288,38 @@ export async function unshareSnap(args) {
     await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}/share`, { method: "DELETE" });
     console.log(`Unshared snap ${id}.`);
 }
+// Shared by both of tagsSnap's paths so reading a snap's tags and the echo
+// after replacing them print the identical line -- the read is meant to be the
+// way a user checks what a write did, which only works if the two agree.
+//
+// Each tag is printed quoted. Unquoted, `Tags for X: deploy bugfix` is
+// character-for-character what ONE tag "deploy bugfix" and TWO tags "deploy"
+// and "bugfix" both printed, so a tag list that had silently collapsed into a
+// single multi-word tag looked exactly like the correct result and the mistake
+// left no trace on screen (ahood-cli#137). JSON.stringify rather than manual
+// quoting so a tag that itself contains a quote or a newline stays unambiguous.
+function printTags(jsonOutput, id, tags, emptyMessage) {
+    // ?? [] -- see printSnaps' identical degrade-on-null guard above
+    // (ahood-cli#106): a degraded response shouldn't crash on undefined.length.
+    // Normalized before the --json branch too, so the emitted shape is the same
+    // {id, tags: []} whether the server said [] or null.
+    const list = tags ?? [];
+    if (jsonOutput) {
+        console.log(JSON.stringify({ id, tags: list }));
+        return;
+    }
+    console.log(list.length > 0 ? `Tags for ${id}: ${list.map((t) => JSON.stringify(t)).join(", ")}` : emptyMessage);
+}
 export async function tagsSnap(args) {
     const jsonOutput = args.includes("--json");
-    const positionals = args.filter((a) => a !== "--json");
+    const clear = args.includes("--clear");
+    // Folded onto flags.ts's shared stripping helper, which this command was the
+    // last caller still hand-rolling its own copy of (see unrecognizedArgs'
+    // comment, ahood-cli#135/#136). The `args.filter(a => a !== "--json")` it
+    // replaces knew about exactly one flag, so --clear below would have meant
+    // growing a third variant of the same rules -- the duplication that let
+    // `snap list` ship with no unknown-flag check at all.
+    const positionals = unrecognizedArgs(args, ["--json", "--clear"], []);
     // Reject stray "--" flags rather than folding them into the tag list
     // (parseSearchQuery in flags.ts does the same). Without this, the natural
     // mistake `snap tags <id> --tags a,b` -- natural because `snap create`
@@ -240,34 +331,48 @@ export async function tagsSnap(args) {
     const id = positionals[0];
     if (!id)
         throw new UsageError(TAGS_USAGE);
-    // PATCH replaces the full tag set (not a merge) -- omitting the tags
-    // argument, or passing an empty string, both clear every tag, matching
-    // the "pass [] to clear" contract of the endpoint itself. Joined, not
-    // just positionals[1] -- an unquoted "tag1, tag2" arrives as multiple
-    // positional tokens, and taking only the first one silently dropped the
-    // rest with no error, the same bug createSnap's own content-joining
-    // above already fixed.
-    const tagsArg = positionals.slice(1).join(" ");
-    const tags = tagsArg
-        ? tagsArg
-            .split(",")
-            .map((t) => t.trim())
-            .filter(Boolean)
-        : [];
-    // No confirm() gate, unlike remove/unshare -- this only replaces metadata
-    // (tags), never the snap's content or its shareability, and re-running
-    // `tags` with the old set restores it exactly. Per ahood-cli#114's spec.
+    const tagArgs = positionals.slice(1);
+    if (clear && tagArgs.length > 0) {
+        throw new UsageError(`--clear takes no tag list, but got "${tagArgs[0]}". Pass --clear to remove every tag, or the tags to set -- not both.\n${TAGS_USAGE}`);
+    }
+    // The bare `snap tags <id>` form READS instead of clearing (ahood-cli#138).
+    // It used to PATCH {"tags":[]} unconfirmed, and it is the form a user reaches
+    // for to ASK what a snap's tags are -- `git tag`, `docker tag` and `hg tags`
+    // all read on their bare form, and nothing else in this CLI showed one snap's
+    // tags (`snap show` prints content only, `snap list` truncates across all
+    // snaps), so the answer was destroyed by the act of asking. Destroying a tag
+    // set now takes saying so: --clear, or the documented explicit "" form below.
+    // That's why there's still no confirm() gate here, unlike remove/unshare --
+    // the accident it would have guarded against can no longer be typed by
+    // accident, and #114's original reasoning (metadata only, and re-running
+    // `tags` with the old set restores it exactly) holds once the user can
+    // actually find out what the old set was.
+    if (!clear && tagArgs.length === 0) {
+        const snap = await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}`);
+        printTags(jsonOutput, snap.id, snap.tags, `${snap.id} has no tags.`);
+        return;
+    }
+    // Each positional is parsed on its own, then concatenated -- NOT joined into
+    // one string first. The join existed to rescue an unquoted `tags <id>
+    // "deploy, bugfix"`, which the shell hands over as two argv entries and which
+    // taking only positionals[1] silently truncated (ahood-cli#114). But joining
+    // cannot tell that apart from a user typing space separators, so `tags <id>
+    // deploy bugfix` became the single tag "deploy bugfix" (ahood-cli#137).
+    // Splitting per token serves both: ["deploy,", "bugfix"] and ["deploy",
+    // "bugfix"] each yield ["deploy", "bugfix"], while a tag that genuinely
+    // contains a space stays expressible by quoting it as one argument -- which
+    // treating whitespace as a separator would have taken away.
+    const tags = tagArgs.flatMap((arg) => arg
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean));
+    // PATCH replaces the full tag set (not a merge) -- passing --clear, or an
+    // empty string, sends [] and clears every tag, matching the "pass [] to
+    // clear" contract of the endpoint itself.
     const updated = await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}`, {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ tags }),
     });
-    if (jsonOutput) {
-        console.log(JSON.stringify(updated));
-        return;
-    }
-    // ?? [] -- see printSnaps' identical degrade-on-null guard above
-    // (ahood-cli#106): a degraded response shouldn't crash on undefined.length.
-    const updatedTags = updated.tags ?? [];
-    console.log(updatedTags.length > 0 ? `Tags for ${updated.id}: ${updatedTags.join(", ")}` : `Cleared tags for ${updated.id}.`);
+    printTags(jsonOutput, updated.id, updated.tags, `Cleared tags for ${updated.id}.`);
 }

package/dist/commands/star.js

@@ -1,21 +1,24 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
+import { ensureRemoteKind } from "../kinds.js";
 // Mirrors POST/DELETE /api/v1/skills/{owner}/{skill}/star -- both are
 // idempotent server-side (POST upserts on the stars table's
 // unique(skill_id, user_id) constraint with ignoreDuplicates, DELETE just
 // deletes any matching row), so starring an already-starred skill or
 // unstarring one you never starred is a no-op 200, not an error.
-export async function star(args) {
+export async function star(args, scope) {
     const USAGE = "Usage: ahood skill star <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
+    await ensureRemoteKind(scope, owner, skill, "star", "star");
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "POST",
     });
     console.log(`Starred ${owner}/${skill}.`);
 }
-export async function unstar(args) {
+export async function unstar(args, scope) {
     const USAGE = "Usage: ahood skill unstar <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
+    await ensureRemoteKind(scope, owner, skill, "unstar", "unstar");
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "DELETE",
     });

package/dist/commands/unpublish.js

@@ -3,6 +3,7 @@ import { confirm } from "../confirm.js";
 import { parseOwnerSkill, parseOwnerSkillVersion } from "../spec.js";
 import { fetchVersionMeta } from "./add.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill unpublish <owner>/<skill>[@version] [--yes]";
 // A bare "owner/skill" has no "@" at all, so lastIndexOf("@") is -1 and this
 // is a whole-skill unpublish (preserves the exact pre-existing behavior).
@@ -13,13 +14,15 @@ const USAGE = "Usage: ahood skill unpublish <owner>/<skill>[@version] [--yes]";
 function isVersioned(spec) {
     return spec.lastIndexOf("@") > 0;
 }
-export async function unpublish(args) {
+export async function unpublish(args, scope) {
     const yes = args.includes("--yes");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
         throw new UsageError(USAGE);
     if (isVersioned(spec)) {
         const { owner, skill, version: parsedVersion } = parseOwnerSkillVersion(spec, USAGE);
+        // Before resolving "latest", before the prompt, before the DELETE.
+        await ensureRemoteKind(scope, owner, skill, "unpublish", "yank a version of");
         // parseOwnerSkillVersion only validates *syntax* -- an omitted "@version"
         // or an explicit "@latest" both parse to the literal string "latest".
         // But the yank request below hits DELETE .../versions/{version}, which
@@ -72,6 +75,7 @@ export async function unpublish(args) {
     }
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const key = `${owner}/${skill}`;
+    await ensureRemoteKind(scope, owner, skill, "unpublish", "unpublish");
     // --yes bypasses the prompt for scripts/CI; otherwise a closed stdin (no
     // TTY, no piped answer either) now throws via confirm()'s "close" handling
     // instead of silently exiting 0 with nothing prompted, confirmed, or done.

package/dist/commands/update.js

@@ -1,11 +1,10 @@
 import { LOCKFILE_PATH, parseOwnerSkill } from "../spec.js";
 import { readLockfile } from "../lockfile.js";
-import { add, fetchVersionMeta, updateMcpEntry } from "./add.js";
+import { add, fetchVersionMeta, readMcpConfig, updateMcpEntry } from "./add.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind, isCliKind, KINDS, localInstalledKind, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]";
-async function previewSkill(ownerSlashSkill, currentVersion) {
-    const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
-    const meta = await fetchVersionMeta(owner, skill, "latest");
+function toPreview(ownerSlashSkill, currentVersion, meta) {
     const upToDate = currentVersion === meta.version;
     return {
         skill: ownerSlashSkill,
@@ -15,13 +14,47 @@ async function previewSkill(ownerSlashSkill, currentVersion) {
         changelog_md: upToDate ? null : meta.changelog_md ?? null,
     };
 }
+// Whether .mcp.json currently holds something that could actually start this
+// skill's server (ahood-cli#139). Anything ahood itself writes is a non-empty
+// JSON object -- buildMcpServerConfig always emits at least a `command` or a
+// `url` -- so a missing key, `null`, `{}`, or a bare scalar all mean the same
+// thing operationally: the server is gone, whatever the lockfile still pins.
+// An emptied entry is reported broken but is NOT self-healed by overwriting:
+// falling through hands it to updateMcpEntry, whose fingerprint check refuses
+// it (before any download or prompt) with the "delete it by hand, then
+// `ahood skill add`" message. ahood never writes `{}` or `null`, so something
+// else did, and quietly stamping over an entry ahood cannot prove is its own
+// is exactly what that check exists to prevent -- an actionable refusal beats
+// both a silent overwrite and today's false "already up to date".
+//
+// Deliberately narrow: an entry that is present and non-empty but doesn't
+// match its recorded fingerprint is NOT reported as broken here. That's a
+// hand-edit, `update` has always left those alone when the pin was already at
+// latest, and turning every locally-tweaked entry into a per-entry failure
+// would be a regression of its own.
+//
+// readMcpConfig() throws on an unreadable or malformed .mcp.json rather than
+// being caught and treated as "no entry": update.ts's per-entry catch turns
+// that into one `Failed to update <skill>: ...` line and a non-zero exit
+// without stopping the rest of the batch, which is what the version-differs
+// path has always done (updateMcpEntry reads the same file through the same
+// function). Swallowing it here would instead print "already up to date"
+// about an entry sitting in a file nothing can parse -- the same false
+// all-clear #139 is about.
+function mcpEntryIsIntact(skill) {
+    const mcpServers = readMcpConfig().mcpServers;
+    if (!Object.prototype.hasOwnProperty.call(mcpServers, skill))
+        return false;
+    const entry = mcpServers[skill];
+    return typeof entry === "object" && entry !== null && Object.keys(entry).length > 0;
+}
 function padRow(cells, widths) {
     return cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
 }
 // Prints a side-by-side current/latest table for every previewed skill, then
 // -- for only the skills that actually have an update available -- the
 // changelog for the version they'd move to. Nothing here touches disk or the
-// network beyond the read-only resolution already done in previewSkill().
+// network beyond the read-only resolution already done by the caller before toPreview().
 function printDryRunTable(previews) {
     const header = ["SKILL", "CURRENT", "LATEST", "STATUS"];
     const rows = previews.map((p) => [
@@ -44,7 +77,30 @@ function printDryRunTable(previews) {
         console.log(p.changelog_md ? p.changelog_md : "(no changelog available)");
     }
 }
-export async function update(args) {
+// Kind scoping for update/outdated (ahood-cli#172). Returns true when `key`
+// should be skipped as out of scope, throws when it must be refused, and
+// returns false when it is in scope.
+//
+//   explicit target, wrong kind -> refused (counts as that entry's failure)
+//   no-arg run, wrong kind      -> silently out of scope: `ahood agent update`
+//                                  only ever considers installed agents
+//   no-arg run, kind unknown    -> skipped with a warning rather than guessed
+//                                  into (or out of) the run
+function outOfScope(scope, key, actual, implicit) {
+    const kind = strictKind(scope);
+    if (kind === undefined || actual === kind)
+        return false;
+    if (!implicit) {
+        assertKind(scope, key, actual, "update", "update");
+        return false; // unreachable: assertKind throws for every actual !== kind
+    }
+    if (!isCliKind(actual)) {
+        console.warn(`WARNING: skipping ${key} -- the registry did not report a kind ahood can match against ${KINDS[kind].plural}.`);
+    }
+    return true;
+}
+export async function update(args, scope) {
+    const kind = strictKind(scope);
     const dryRun = args.includes("--dry-run");
     const jsonOutput = args.includes("--json");
     if (jsonOutput && !dryRun) {
@@ -52,9 +108,23 @@ export async function update(args) {
     }
     const targets = args.filter((a) => a !== "--dry-run" && a !== "--json");
     const lockfile = readLockfile(LOCKFILE_PATH);
-    const skillKeys = targets.length > 0 ? targets : Object.keys(lockfile);
+    const implicit = targets.length === 0;
+    let skillKeys = implicit ? Object.keys(lockfile) : targets;
+    if (implicit && kind) {
+        // A cheap local pre-filter so a pin this project's own files already
+        // show to be another kind costs no request (and can't fail the run).
+        // Unknown footprints stay in and are settled by the registry's answer.
+        skillKeys = skillKeys.filter((key) => {
+            const parts = key.split("/");
+            if (parts.length !== 2)
+                return true; // let the loop report the bad key as before
+            const local = localInstalledKind(parts[0], parts[1], lockfile[key]);
+            return local === undefined || local === kind;
+        });
+    }
+    const noneMessage = kind ? `No installed ${KINDS[kind].plural} to update.` : "No installed skills to update.";
     if (skillKeys.length === 0) {
-        console.log("No installed skills to update.");
+        console.log(noneMessage);
         return;
     }
     if (dryRun) {
@@ -65,7 +135,11 @@ export async function update(args) {
         const failures = [];
         for (const key of skillKeys) {
             try {
-                previews.push(await previewSkill(key, lockfile[key]?.version ?? null));
+                const { owner, skill } = parseOwnerSkill(key, USAGE);
+                const meta = await fetchVersionMeta(owner, skill, "latest");
+                if (outOfScope(scope, key, meta.kind, implicit))
+                    continue;
+                previews.push(toPreview(key, lockfile[key]?.version ?? null, meta));
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -86,6 +160,7 @@ export async function update(args) {
         return;
     }
     const failures = [];
+    let inScope = 0;
     for (const ownerSlashSkill of skillKeys) {
         if (!lockfile[ownerSlashSkill]) {
             // Reachable two ways: an explicitly-named skill that was never
@@ -107,22 +182,42 @@ export async function update(args) {
             // mcp-update support) instead.
             const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
             const meta = await fetchVersionMeta(owner, skill, "latest");
+            if (outOfScope(scope, ownerSlashSkill, meta.kind, implicit))
+                continue;
+            inScope++;
             if (meta.kind === "mcp") {
                 const currentEntry = lockfile[ownerSlashSkill];
-                if (currentEntry && currentEntry.version === meta.version) {
+                if (currentEntry && currentEntry.version === meta.version && mcpEntryIsIntact(skill)) {
                     // Matches skill/agent update's own "nothing to do" case for a
                     // pin that's already at latest -- not a warning (nothing's
                     // wrong), and, unlike skill/agent (which always blindly
                     // re-extracts even when nothing changed), skipped here
                     // specifically so an up-to-date mcp entry with a secret in its
                     // env never re-triggers a masked prompt for no reason.
+                    //
+                    // Conditioned on the entry actually being there (ahood-cli#139):
+                    // .mcp.json is merged into rather than owned (see CLAUDE.md), so
+                    // losing an entry to a merge or a hand cleanup is ordinary, and
+                    // matching versions alone said "already up to date" about a server
+                    // that no longer existed -- the one kind `update` could not repair,
+                    // where skill/agent are restored by add() below regardless of
+                    // version. Falling through runs updateMcpEntry's self-heal (see the
+                    // "If the entry is missing entirely" case in add.ts), which does
+                    // have to prompt for secrets there is no on-disk entry to carry
+                    // forward; on the unattended path its allowNonTtyPrompt: false
+                    // turns that into a named-variable error instead of a hang.
                     console.log(`${ownerSlashSkill} is already up to date (v${meta.version}).`);
                     continue;
                 }
                 await updateMcpEntry(owner, skill, meta, currentEntry);
                 continue;
             }
-            await add([ownerSlashSkill]); // no @version -- resolves to latest again
+            // no @version -- resolves to latest again. A strict scope is passed on so
+            // add() re-checks the kind it resolves itself before writing anything.
+            if (kind)
+                await add([ownerSlashSkill], scope);
+            else
+                await add([ownerSlashSkill]);
         }
         catch (error) {
             // One skill being removed/yanked/unreachable must not stop every other
@@ -132,6 +227,9 @@ export async function update(args) {
             failures.push(ownerSlashSkill);
         }
     }
+    if (implicit && kind && inScope === 0 && failures.length === 0) {
+        console.log(noneMessage);
+    }
     if (failures.length > 0) {
         console.error(`${failures.length} of ${skillKeys.length} skill(s) failed to update: ${failures.join(", ")}`);
         process.exitCode = 1;

package/dist/commands/versions.js

@@ -1,6 +1,7 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill versions <owner>/<skill> [--json]";
 function formatSize(bytes) {
     if (bytes < 1024)
@@ -18,12 +19,13 @@ export async function listSkillVersions(owner, skill) {
     const { versions } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
     return versions ?? [];
 }
-export async function versions(args) {
+export async function versions(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, "versions", "list the versions of");
     const list = await listSkillVersions(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify(list));

package/dist/commands/view.js

@@ -3,6 +3,7 @@ import { apiJson } from "../http.js";
 import { getApiUrl } from "../config.js";
 import { parseOwnerSkill } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind, ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill view <owner>/<skill> [--json] [--web]";
 // Spawned with argv as an array (not a shell string), so a crafted owner/skill
 // can never inject shell syntax -- and both segments are already restricted
@@ -26,7 +27,7 @@ function openBrowser(url) {
 export async function viewSkill(owner, skill) {
     return apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
 }
-export async function view(args) {
+export async function view(args, scope) {
     const jsonOutput = args.includes("--json");
     const web = args.includes("--web");
     const spec = args.find((a) => !a.startsWith("--"));
@@ -35,10 +36,12 @@ export async function view(args) {
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const url = `${getApiUrl()}/${owner}/${skill}`;
     if (web) {
+        await ensureRemoteKind(scope, owner, skill, "view", "open");
         openBrowser(url);
         return;
     }
     const detail = await viewSkill(owner, skill);
+    assertKind(scope, `${owner}/${skill}`, detail.kind, "view", "show");
     if (jsonOutput) {
         console.log(JSON.stringify(detail));
         return;