@ahood/cli 0.8.7 → 0.9.0

package/README.md

@@ -252,7 +252,7 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood snap remove <id> [--yes]` | Permanently delete a snap (prompts for confirmation unless --yes is passed). |
 | `ahood snap share <id> [--json]` | Mint (or return the existing) shareable link for a snap. |
 | `ahood snap unshare <id> [--yes]` | Revoke a snap's share link (the snap itself is untouched; prompts for confirmation unless --yes is passed). |
-| `ahood snap tags <id> [tag1,tag2,...] [--json]` | Replace a snap's tags (omit the tag list, or pass an empty one, to clear all tags). |
+| `ahood snap tags <id> [tag ...] [--clear] [--json]` | Print a snap's tags, or replace them with the tags given. |
 <!-- COMMANDS_TABLE_END -->
 
 Run `ahood --help`, `ahood skill --help`, `ahood group --help`, `ahood snap --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help skill <verb>` / `ahood help group <verb>` / `ahood help snap <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.

package/dist/commands/add.js

@@ -7,6 +7,7 @@ import { apiFetch, apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
 import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir, agentPath, AGENTS_ROOT, MCP_CONFIG_PATH } from "../spec.js";
 import { readLockfile, withLock, writeJsonFileAtomic, writeLockfileEntryVerifyingChecksum, LockfileChecksumConflictError, } from "../lockfile.js";
 import { promptSecret } from "../secret-prompt.js";
+import { sanitizeForTerminal } from "../terminal-safe.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill add <owner>/<skill>[@version]";
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB compressed
@@ -237,25 +238,6 @@ export async function extractSingleFileContent(buffer, entryName) {
         throw new Error(`${entryName} not found in the downloaded archive`);
     return found;
 }
-// Every manifest field used below -- and every tar entry name extractTarGz
-// quotes back in an error above -- reaches the terminal (an error message, or
-// -- worse -- the text printed immediately before a masked secret prompt)
-// but comes verbatim from a third-party-published archive: server-side
-// validation only checks these are strings, not that they're free of
-// control/escape characters. A malicious description could otherwise smuggle
-// a terminal control sequence (cursor movement, line-clear) that repaints
-// what the user sees at the exact moment they're about to type a credential.
-// Strips C0/C1 control characters (including ESC, \x1b) and caps length so a
-// single field can't also flood the terminal.
-//
-// Takes `unknown` rather than `string` because every caller's "string" is a
-// declared type over an unchecked `as ServerManifest` cast of downloaded JSON,
-// not a guarantee: calling .replace() directly on a `registry_type: 123` would
-// turn a diagnosable message into the raw TypeError ahood-cli#121 removed from
-// this same path (ahood-cli#122).
-function sanitizeForTerminal(text) {
-    return String(text).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 200);
-}
 // Only npm+npx is supported in v1 (docs/superpowers/specs/2026-09-03-mcp-server-artifacts-design.md) --
 // server-side publish validation (lib/publish/parse-server-manifest.ts) already
 // rejects anything else, so this check is defense-in-depth against a
@@ -480,10 +462,10 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
             throw new Error(`${sanitizeForTerminal(variable.name)} is required by ${sanitizeForTerminal(manifest.name)} but is not set -- export ${sanitizeForTerminal(variable.name)} and re-run.`);
         }
     }
-    // Required-ness needs no separate check on the secret path: every branch
-    // below either resolves a value or throws, so a required secret with
-    // nothing to fall back on already fails loudly (the non-TTY guard) or is
-    // supplied at the prompt (ahood-cli#120).
+    // Required-ness is consulted on the secret path only in the one branch
+    // where a secret can still end up unresolved: the unattended update guard
+    // below. Every other branch either resolves a value or prompts for one, so
+    // an `is_required` check there would change nothing (ahood-cli#120).
     const secretNames = [];
     for (const variable of envVars) {
         if (!variable.is_secret)
@@ -511,6 +493,21 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
             continue;
         }
         if (!allowNonTtyPrompt && !process.stdin.isTTY) {
+            // Optional means optional here too, exactly as it does on the
+            // non-secret pass above (ahood-cli#126). This guard used to fire for
+            // ANY unresolved secret, so a single artifact declaring an optional
+            // token that nothing had exported aborted the whole `ahood skill
+            // update` walk -- and said the variable "is required" while the
+            // manifest that declared it said otherwise. Announced rather than
+            // silent because skipping and carrying forward leave different entries
+            // in .mcp.json and nothing else distinguishes them; the notice is
+            // confined to this branch, so an interactive `add` (which still prompts
+            // for optional secrets) and a routine update whose credential carries
+            // forward both stay quiet.
+            if (!variable.is_required) {
+                console.warn(`${sanitizeForTerminal(variable.name)} is optional and is not set -- updating ${sanitizeForTerminal(manifest.name)} without it.`);
+                continue;
+            }
             throw new Error(`${sanitizeForTerminal(variable.name)} is required by ${sanitizeForTerminal(manifest.name)} but is not set, and there is no terminal to prompt on -- export ${sanitizeForTerminal(variable.name)} and re-run.`);
         }
         env[variable.name] = await promptSecret(`${sanitizeForTerminal(variable.name)} (${sanitizeForTerminal(variable.description)}): `);
@@ -602,6 +599,22 @@ function readMcpEntryEnv(entry) {
     }
     return result;
 }
+// Every install path below undoes its own on-disk write when the lockfile
+// write that would have pinned it fails. This runs that undo so that a
+// failure IN the undo can never replace the original error: a rollback fails
+// for the same reasons the write did (the lock still contended, the disk
+// still full), and letting that escape would hand the user an EACCES or a
+// lock timeout in place of the checksum-conflict message that actually
+// explains what happened (ahood-cli#132). The warning is the consolation
+// prize -- it has to name what was left behind, since nothing else will.
+function rollbackOrWarn(rollback, warning) {
+    try {
+        rollback();
+    }
+    catch {
+        console.warn(warning);
+    }
+}
 async function installMcpEntry(owner, skill, meta, buffer) {
     // Check for an existing .mcp.json collision BEFORE resolving secrets --
     // matches resolveMcpServerConfig's own "don't cost the user a prompt for
@@ -633,16 +646,43 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         });
     }
     catch (error) {
-        if (!(error instanceof LockfileChecksumConflictError))
-            throw error;
         // Roll back the .mcp.json merge above under the same lock pattern --
         // re-read+delete rather than assuming nothing else changed it since.
-        withLock(MCP_CONFIG_PATH, () => {
-            const fileContents = readMcpConfig();
-            delete fileContents.mcpServers[skill];
-            writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
-        });
-        throw new Error(checksumConflictMessage(mcpKey, meta, error.existing));
+        //
+        // Runs for EVERY lockfile failure, not just a checksum conflict
+        // (ahood-cli#132) -- the same widening updateMcpEntry below already got,
+        // for the same reason. A rethrow-before-rollback here left the entry
+        // this function just merged in -- including, on the npm+npx path, the
+        // plaintext secret the user had just typed at the prompt -- sitting in
+        // .mcp.json with no lockfile pin at all. `remove` then bails at its
+        // `!dirExisted && !agentExisted && !hadLockfileEntry` check ("was not
+        // installed -- nothing to remove") before it ever reaches its .mcp.json
+        // cleanup, and a retried `add` refuses forever at assertNoCollision:
+        // the credential is removable only by hand-editing .mcp.json, and
+        // nothing tells the user it is there. Reachable from nothing worse than
+        // withLock's 5s timeout against a concurrent ahood, or an EACCES/ENOSPC
+        // on the write.
+        //
+        // Deletes, where updateMcpEntry's rollback restores: assertNoCollision
+        // has already established there was no entry under this key before this
+        // install wrote one, so there is nothing to put back. Deletes it
+        // unconditionally rather than re-fingerprinting it first the way
+        // remove.ts does -- remove is deciding about an entry of unknown age
+        // that may hold an intentional local edit, while this one was written
+        // by this same process moments ago and cannot be anyone else's work.
+        // Re-verifying here would only reintroduce the stranded-secret dead end
+        // above for whatever raced us.
+        rollbackOrWarn(() => {
+            withLock(MCP_CONFIG_PATH, () => {
+                const fileContents = readMcpConfig();
+                delete fileContents.mcpServers[skill];
+                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+            });
+        }, `WARNING: could not roll back ${MCP_CONFIG_PATH} after ${mcpKey}'s install failed -- its mcpServers."${skill}" entry (which may contain a secret you entered) may still be present while ${LOCKFILE_PATH} has no pin for it. Delete that entry by hand before re-running \`ahood skill add ${mcpKey}\`.`);
+        if (error instanceof LockfileChecksumConflictError) {
+            throw new Error(checksumConflictMessage(mcpKey, meta, error.existing));
+        }
+        throw error;
     }
     console.log(`Installed ${owner}/${skill}@${meta.version} into ${MCP_CONFIG_PATH} as "${skill}"`);
     // Only the npm+npx package path ever carries secrets into `env` (headers
@@ -732,7 +772,12 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         // `remove` permanently refuse -- the exact dead end the comments above
         // exist to prevent, reachable from nothing worse than withLock's 5s
         // timeout against a concurrent ahood, or an EACCES/ENOSPC on the write.
-        try {
+        //
+        // The rollback itself can fail for the same reason the write did (lock
+        // still contended, disk still full), so it goes through rollbackOrWarn:
+        // the original error below is the more actionable one, and masking it
+        // with this one would hide why the update failed in the first place.
+        rollbackOrWarn(() => {
             withLock(MCP_CONFIG_PATH, () => {
                 const fileContents = readMcpConfig();
                 const mcpServers = fileContents.mcpServers;
@@ -744,14 +789,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
                 }
                 writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
             });
-        }
-        catch {
-            // The rollback can fail for the same reason the write did (lock still
-            // contended, disk still full). Warn rather than throw: the original
-            // error below is the more actionable one, and masking it with this
-            // one would hide why the update failed in the first place.
-            console.warn(`WARNING: could not roll back ${MCP_CONFIG_PATH} after ${key}'s update failed -- its mcpServers."${skill}" entry may be on the new version while ${LOCKFILE_PATH} still pins the old one. Delete that entry by hand and run \`ahood skill add ${key}\` to reinstall.`);
-        }
+        }, `WARNING: could not roll back ${MCP_CONFIG_PATH} after ${key}'s update failed -- its mcpServers."${skill}" entry may be on the new version while ${LOCKFILE_PATH} still pins the old one. Delete that entry by hand and run \`ahood skill add ${key}\` to reinstall.`);
         if (error instanceof LockfileChecksumConflictError) {
             throw new Error(checksumConflictMessage(key, meta, error.existing));
         }
@@ -829,10 +867,18 @@ export async function add(args) {
             writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
         }
         catch (error) {
-            if (!(error instanceof LockfileChecksumConflictError))
-                throw error;
-            rmSync(destPath, { force: true });
-            throw new Error(checksumConflictMessage(key, meta, error.existing));
+            // Widened past the checksum-conflict case with installMcpEntry's own
+            // rollback (ahood-cli#132): an agent file left behind by a lock
+            // timeout is less dangerous than a stranded mcp secret -- `remove`
+            // finds it via agentExisted even with no pin -- but "a failed install
+            // installs nothing" is the invariant worth having at all three sites,
+            // and the previous version's content is gone either way, overwritten
+            // by the writeFileSync above before the pin was ever attempted.
+            rollbackOrWarn(() => rmSync(destPath, { force: true }), `WARNING: could not remove ${destPath} after ${key}'s install failed -- it may be left behind with no ${LOCKFILE_PATH} pin. Run \`ahood skill remove ${key}\` to clean it up.`);
+            if (error instanceof LockfileChecksumConflictError) {
+                throw new Error(checksumConflictMessage(key, meta, error.existing));
+            }
+            throw error;
         }
         console.log(`Installed ${key}@${meta.version} to ${destPath}`);
         return;
@@ -852,10 +898,14 @@ export async function add(args) {
         });
     }
     catch (error) {
-        if (!(error instanceof LockfileChecksumConflictError))
-            throw error;
-        rmSync(destDir, { recursive: true, force: true });
-        throw new Error(checksumConflictMessage(key, meta, error.existing));
+        // Same widening as the agent path above (ahood-cli#132). extractFreshVersion
+        // has already cleared any previous version out of this directory, so the
+        // only thing this deletes is what this failed install just put there.
+        rollbackOrWarn(() => rmSync(destDir, { recursive: true, force: true }), `WARNING: could not remove ${destDir} after ${key}'s install failed -- it may be left behind with no ${LOCKFILE_PATH} pin. Run \`ahood skill remove ${key}\` to clean it up.`);
+        if (error instanceof LockfileChecksumConflictError) {
+            throw new Error(checksumConflictMessage(key, meta, error.existing));
+        }
+        throw error;
     }
     console.log(`Installed ${key}@${meta.version} to ${destDir}`);
 }

package/dist/commands/read.js

@@ -1,5 +1,6 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
+import { sanitizeDocumentForTerminal, sanitizeForTerminal } from "../terminal-safe.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill read <owner>/<skill> [--json]";
 export async function readSkillMd(owner, skill) {
@@ -12,8 +13,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) {
@@ -52,5 +61,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,4 +1,4 @@
-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";
@@ -22,6 +22,14 @@ 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;
@@ -36,16 +44,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 +101,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 +138,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/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}.`);
 }