@trawlme/cli 1.18.1 → 1.18.3

package/dist/index.d.ts

@@ -6,6 +6,15 @@ import { Command } from 'commander';
  * --url) don't start with '-' and would otherwise survive an argv filter and
  * leak to PostHog (#67). Falls back to 'unknown' when no command resolved
  * (e.g. an error thrown before any action ran).
+ *
+ * #88 item 9 — walks the FULL parent chain, not just the immediate parent:
+ * the old one-level join (`${parent.name()} ${own.name()}`) resolved a
+ * 4-deep command like `scraps account session set` down to just "session
+ * set", silently dropping "scraps account". The root program node (the
+ * 'trawl' Command itself, which has no `.parent`) is excluded from the
+ * chain — matching the pre-existing convention that a direct child of the
+ * root (e.g. `scraps list`, `telemetry on`) is named relative to its
+ * immediate group, never prefixed with the program name.
  */
 export declare function resolveCommandName(actionCommand: Command | undefined): string;
 /**
@@ -18,10 +27,62 @@ export declare function createProgram(): Command;
 /** True when this module is the process entrypoint (not merely imported by a test). */
 export declare function isEntryPoint(argv1: string | undefined, moduleUrl: string): boolean;
 /**
- * True when the invocation is a pure `--help`/`--version` query. These must not
- * trigger the skills auto-sync (a filesystem-mutating startup side effect) — a
- * user running `trawl --version` never expects it to rewrite their skills dirs.
- * (#73)
+ * True when the invocation is a pure `--help`/`--version` query, a bare
+ * `trawl` with no subcommand (commander prints top-level help and exits), or
+ * `trawl help [command]`. None of these should trigger the skills auto-sync
+ * (a filesystem-mutating startup side effect) — a user running `trawl
+ * --version` (or just `trawl`) never expects it to rewrite their skills
+ * dirs. (#73, extended #86 finding 7 for the bare-invocation + `help`
+ * subcommand cases)
  */
 export declare function isHelpOrVersion(argv: string[]): boolean;
+/** Best-effort scan for a `--json` flag in raw argv, used only when parsing
+ * itself failed before any command's own `.opts()` could be resolved (a
+ * commander usage error — unknown option/command, missing required arg). Same
+ * "argv scan, never trust flag values" caveat as isHelpOrVersion: positional
+ * values are never mistaken for `--json` since they don't equal the literal
+ * string. (#86 finding 3)
+ *
+ * #88 item 5 — only scans tokens BEFORE the first bare `--`. Commander treats
+ * `--` as "end of options": everything after it is a positional operand, not
+ * a flag, even if the literal text is `--json`. `scraps list -- --json`
+ * passes `--json` as an (excess) positional argument, not the flag — an
+ * unscoped `argv.includes('--json')` would still match it and wrongly emit a
+ * JSON envelope for what is actually a plain usage error with no --json
+ * requested at all.
+ */
+export declare function hasJsonFlag(argv: string[]): boolean;
+/**
+ * Commander's default (no exitOverride) calls `process.exit()` directly for
+ * a usage error (unknown option/command, missing required arg) or a
+ * --help/--version/`help` query — bypassing runCli's try/catch/finally
+ * entirely, so the telemetry shutdown() flush below never runs and a usage
+ * error exits 1 (the generic bug bucket) instead of its own distinct code.
+ * `program.exitOverride()` on the root command alone does NOT fix this for
+ * subcommands added via `addCommand()` (login/scraps/skills/telemetry/token
+ * are each built as standalone Command instances in their own module and
+ * only ever copy inherited settings — including exitOverride — from a parent
+ * at `.command()` construction time, which for these root-level modules never
+ * happens). Every node in the tree needs its own exitOverride() call, so this
+ * walks the whole tree and installs it everywhere. (#86 finding 3)
+ */
+export declare function applyExitOverride(cmd: Command): void;
+/**
+ * #88 item 6 — best-effort command-name recovery for a commander parse error
+ * that happened BEFORE any action ran, so `currentCommand` (the preAction
+ * hook's resolved command) is still undefined — e.g. an unknown option on an
+ * otherwise-valid subcommand, or excess arguments. Without this, EVERY such
+ * failure previously collapsed to resolveCommandName(undefined) === 'unknown'
+ * — and since 'unknown' was never itself allowlisted at the
+ * registerAllowedCommands call site (see runCli below), that capture was
+ * silently dropped by captureCommand's allowlist check: a dead branch that
+ * looked like it reported telemetry but never actually did.
+ *
+ * Matches ONLY a name already present in `allowedNames` (the real command
+ * tree, from collectCommandNames) — never invents one from raw argv text.
+ * Checks the two-token form first (`scraps boom`) since most usage errors
+ * happen on a nested leaf command; falls back to the single top-level token,
+ * then to 'unknown' (now itself allowlisted, so that capture fires too).
+ */
+export declare function bestEffortCommandName(argv: string[], allowedNames: readonly string[]): string;
 export declare function runCli(argv?: string[]): Promise<void>;

package/dist/index.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import chalk from 'chalk';
+import { Command, CommanderError } from 'commander';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -11,7 +10,7 @@ import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
-import { classifyError } from './lib/errors.js';
+import { classifyError, reportError } from './lib/errors.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -20,13 +19,29 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8
  * --url) don't start with '-' and would otherwise survive an argv filter and
  * leak to PostHog (#67). Falls back to 'unknown' when no command resolved
  * (e.g. an error thrown before any action ran).
+ *
+ * #88 item 9 — walks the FULL parent chain, not just the immediate parent:
+ * the old one-level join (`${parent.name()} ${own.name()}`) resolved a
+ * 4-deep command like `scraps account session set` down to just "session
+ * set", silently dropping "scraps account". The root program node (the
+ * 'trawl' Command itself, which has no `.parent`) is excluded from the
+ * chain — matching the pre-existing convention that a direct child of the
+ * root (e.g. `scraps list`, `telemetry on`) is named relative to its
+ * immediate group, never prefixed with the program name.
  */
 export function resolveCommandName(actionCommand) {
     if (!actionCommand)
         return 'unknown';
-    return actionCommand.parent
-        ? `${actionCommand.parent.name()} ${actionCommand.name()}`
-        : actionCommand.name();
+    const chain = [];
+    let current = actionCommand;
+    while (current && current.parent) {
+        chain.unshift(current.name());
+        current = current.parent;
+    }
+    // `current` is now the root (no parent) — its name is excluded by design.
+    // If the chain came up empty, actionCommand itself IS the root (no parent
+    // at all) — fall back to its own name so the function never returns ''.
+    return chain.length > 0 ? chain.join(' ') : actionCommand.name();
 }
 /**
  * Walk the full command tree and produce every valid resolveCommandName()
@@ -63,20 +78,112 @@ export function isEntryPoint(argv1, moduleUrl) {
     return argv1 !== undefined && moduleUrl === pathToFileURL(argv1).href;
 }
 /**
- * True when the invocation is a pure `--help`/`--version` query. These must not
- * trigger the skills auto-sync (a filesystem-mutating startup side effect) — a
- * user running `trawl --version` never expects it to rewrite their skills dirs.
- * (#73)
+ * True when the invocation is a pure `--help`/`--version` query, a bare
+ * `trawl` with no subcommand (commander prints top-level help and exits), or
+ * `trawl help [command]`. None of these should trigger the skills auto-sync
+ * (a filesystem-mutating startup side effect) — a user running `trawl
+ * --version` (or just `trawl`) never expects it to rewrite their skills
+ * dirs. (#73, extended #86 finding 7 for the bare-invocation + `help`
+ * subcommand cases)
  */
 export function isHelpOrVersion(argv) {
-    return argv.some((a) => a === '-h' || a === '--help' || a === '-V' || a === '--version');
+    if (argv.some((a) => a === '-h' || a === '--help' || a === '-V' || a === '--version'))
+        return true;
+    const args = argv.slice(2);
+    if (args.length === 0)
+        return true;
+    if (args[0] === 'help')
+        return true;
+    return false;
+}
+/** Best-effort scan for a `--json` flag in raw argv, used only when parsing
+ * itself failed before any command's own `.opts()` could be resolved (a
+ * commander usage error — unknown option/command, missing required arg). Same
+ * "argv scan, never trust flag values" caveat as isHelpOrVersion: positional
+ * values are never mistaken for `--json` since they don't equal the literal
+ * string. (#86 finding 3)
+ *
+ * #88 item 5 — only scans tokens BEFORE the first bare `--`. Commander treats
+ * `--` as "end of options": everything after it is a positional operand, not
+ * a flag, even if the literal text is `--json`. `scraps list -- --json`
+ * passes `--json` as an (excess) positional argument, not the flag — an
+ * unscoped `argv.includes('--json')` would still match it and wrongly emit a
+ * JSON envelope for what is actually a plain usage error with no --json
+ * requested at all.
+ */
+export function hasJsonFlag(argv) {
+    const dashDashIdx = argv.indexOf('--');
+    const scanned = dashDashIdx === -1 ? argv : argv.slice(0, dashDashIdx);
+    return scanned.includes('--json');
+}
+/**
+ * Commander's default (no exitOverride) calls `process.exit()` directly for
+ * a usage error (unknown option/command, missing required arg) or a
+ * --help/--version/`help` query — bypassing runCli's try/catch/finally
+ * entirely, so the telemetry shutdown() flush below never runs and a usage
+ * error exits 1 (the generic bug bucket) instead of its own distinct code.
+ * `program.exitOverride()` on the root command alone does NOT fix this for
+ * subcommands added via `addCommand()` (login/scraps/skills/telemetry/token
+ * are each built as standalone Command instances in their own module and
+ * only ever copy inherited settings — including exitOverride — from a parent
+ * at `.command()` construction time, which for these root-level modules never
+ * happens). Every node in the tree needs its own exitOverride() call, so this
+ * walks the whole tree and installs it everywhere. (#86 finding 3)
+ */
+export function applyExitOverride(cmd) {
+    cmd.exitOverride();
+    for (const sub of cmd.commands)
+        applyExitOverride(sub);
+}
+/** Commander's own codes for a successful --help/--version/`help` query —
+ * these already printed their own output (to stdout) via commander itself;
+ * runCli's catch must treat them as a clean exit, not an error. (#86 finding 3) */
+const HELP_OR_VERSION_CODES = new Set(['commander.helpDisplayed', 'commander.help', 'commander.version']);
+/**
+ * #88 item 6 — best-effort command-name recovery for a commander parse error
+ * that happened BEFORE any action ran, so `currentCommand` (the preAction
+ * hook's resolved command) is still undefined — e.g. an unknown option on an
+ * otherwise-valid subcommand, or excess arguments. Without this, EVERY such
+ * failure previously collapsed to resolveCommandName(undefined) === 'unknown'
+ * — and since 'unknown' was never itself allowlisted at the
+ * registerAllowedCommands call site (see runCli below), that capture was
+ * silently dropped by captureCommand's allowlist check: a dead branch that
+ * looked like it reported telemetry but never actually did.
+ *
+ * Matches ONLY a name already present in `allowedNames` (the real command
+ * tree, from collectCommandNames) — never invents one from raw argv text.
+ * Checks the two-token form first (`scraps boom`) since most usage errors
+ * happen on a nested leaf command; falls back to the single top-level token,
+ * then to 'unknown' (now itself allowlisted, so that capture fires too).
+ */
+export function bestEffortCommandName(argv, allowedNames) {
+    const a2 = argv[2];
+    const a3 = argv[3];
+    if (a2 && a3) {
+        const combined = `${a2} ${a3}`;
+        if (allowedNames.includes(combined))
+            return combined;
+    }
+    if (a2 && allowedNames.includes(a2))
+        return a2;
+    return 'unknown';
 }
 export async function runCli(argv = process.argv) {
     if (!isHelpOrVersion(argv))
         autoUpdateInstalledSkills();
     initPostHog();
     const program = createProgram();
-    registerAllowedCommands(collectCommandNames(program));
+    // Must run before parseAsync — installs on every node in the tree,
+    // including subcommands added via addCommand() that don't otherwise
+    // inherit it. (#86 finding 3)
+    applyExitOverride(program);
+    const commandNames = collectCommandNames(program);
+    // #88 item 6 — 'unknown' is a legitimate resolveCommandName() output (the
+    // fallback for "no command resolved at all"), not free-form user input —
+    // it must be explicitly allowlisted here or every capture that falls back
+    // to it is silently dropped by captureCommand's allowlist check (a dead
+    // branch that looks like it reports telemetry but never does).
+    registerAllowedCommands([...commandNames, 'unknown']);
     // Track start times + the currently-resolved command per instance, so the
     // catch handler below can derive the exact same safe name the success path
     // uses — it must never re-derive anything from argv.
@@ -102,31 +209,68 @@ export async function runCli(argv = process.argv) {
         await program.parseAsync(argv);
     }
     catch (err) {
-        // Map the error to a distinct exit code + machine envelope instead of a
-        // uniform 1 — agents driving this CLI unattended need to tell
-        // auth-expired (3) from not-found (4) from network-down (5) from a bad
-        // flag (2) apart from an arbitrary bug (1). (#71)
-        const { exitCode, envelope } = classifyError(err);
-        // Capture error telemetry from the resolved command only — never argv.
-        void captureCommand(resolveCommandName(currentCommand), {
-            exit_code: exitCode,
-            error: err.name,
-        });
         const { debug } = program.opts();
         const isDebug = Boolean(debug || process.env['DEBUG']);
-        // A --json subcommand must keep stdout pure JSON even on failure — read
-        // the resolved command's own --json flag (never argv) so the error
-        // envelope lands on the same channel the success path would have used.
-        const wantsJson = Boolean(currentCommand?.opts()?.json);
-        if (isDebug)
-            console.error(err);
-        if (wantsJson) {
-            console.log(JSON.stringify({ error: envelope }));
+        if (err instanceof CommanderError) {
+            // Commander's own parse-time errors (exitOverride, #86 finding 3) —
+            // a distinct family from our ApiError/NetworkError/UsageError/generic
+            // Error taxonomy, so classifyError/reportError don't apply here.
+            if (HELP_OR_VERSION_CODES.has(err.code)) {
+                // --help / --version / `trawl help` already printed their own
+                // output via commander itself — nothing else to print, just adopt
+                // commander's suggested exit code (0) and fall through to the
+                // shared shutdown() flush below.
+                process.exitCode = err.exitCode;
+            }
+            else {
+                // A usage error (unknown option/command, missing required arg, …) —
+                // commander already wrote its own human-readable line to stderr via
+                // Command#error(), so this never duplicates it. Force exit code 2
+                // (usage) regardless of whichever code commander suggests (it
+                // defaults these to 1), and add the --json machine envelope when
+                // resolvable — parsing failed before any command's own --json flag
+                // could be read off `currentCommand` (preAction never fired), so
+                // scan raw argv instead. (#86 finding 3)
+                if (isDebug)
+                    console.error(err);
+                if (hasJsonFlag(argv)) {
+                    console.log(JSON.stringify({ error: { message: err.message, kind: 'usage' } }));
+                }
+                process.exitCode = 2;
+                // #88 item 6 — currentCommand is still undefined here whenever the
+                // parse error happened before preAction fired (the common case for a
+                // usage error — commander validates flags/arity before invoking the
+                // action). Try a best-effort match against the real command tree
+                // instead of collapsing straight to 'unknown'.
+                const commandName = currentCommand
+                    ? resolveCommandName(currentCommand)
+                    : bestEffortCommandName(argv, commandNames);
+                void captureCommand(commandName, { exit_code: 2, error: 'CommanderError' });
+            }
         }
-        else if (!isDebug) {
-            console.error(chalk.red('✗ ' + envelope.message));
+        else {
+            // Map the error to a distinct exit code + machine envelope instead of a
+            // uniform 1 — agents driving this CLI unattended need to tell
+            // auth-expired (3) from not-found (4) from network-down (5) from a bad
+            // flag (2) apart from an arbitrary bug (1). (#71)
+            const { exitCode } = classifyError(err);
+            // Capture error telemetry from the resolved command only — never argv.
+            void captureCommand(resolveCommandName(currentCommand), {
+                exit_code: exitCode,
+                error: err.name,
+            });
+            // A --json subcommand must keep stdout pure JSON even on failure — read
+            // the resolved command's own --json flag (never argv) so the error
+            // envelope lands on the same channel the success path would have used.
+            const wantsJson = Boolean(currentCommand?.opts()?.json);
+            if (isDebug)
+                console.error(err);
+            // reportError is the single formatting path (#86 finding 9) — prints
+            // EITHER the --json envelope (stdout) OR the human "✗ message" line
+            // (stderr), never both; `quiet` skips the human line when the raw
+            // stack was already dumped above under --debug.
+            process.exitCode = reportError(err, { json: wantsJson, quiet: isDebug });
         }
-        process.exitCode = exitCode;
     }
     finally {
         // Flush + close telemetry before the process exits. A `process.on('exit')`

package/dist/lib/api.d.ts

@@ -11,6 +11,32 @@ export declare class ApiError extends Error {
 export declare class NetworkError extends Error {
     constructor(message: string);
 }
+/**
+ * A LOCAL auth failure — no token available, or a locally-decoded token
+ * that's provably expired, discovered entirely client-side before any HTTP
+ * call was ever made. Distinguished from ApiError(401) (a real server-issued
+ * 401 response) so the --json envelope never claims `status:401` for
+ * something the server never said — that would be a fabricated fact,
+ * indistinguishable from an actual server round-trip to a machine consumer.
+ * Both classify to the same exit code (3) / kind "auth" in classifyError
+ * (errors.ts); only the envelope's `status` field differs (present for
+ * ApiError, absent here). (#88 item 4)
+ */
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * The single "no token available" error — every call site in this file that
+ * needs a token (request/upload/getText/stream) used to throw its own copy
+ * of `new Error('Not logged in. Run: trawl login')`, which fell through
+ * classifyError's generic branch (exit 1, kind:"unknown") — indistinguishable
+ * from an arbitrary bug. Auth-classifying it puts it on the exact same
+ * exit-3 / kind:"auth" path a real 401 response already takes — but as an
+ * AuthError (no HTTP call happened here), never a fabricated ApiError(401).
+ * `trawl token` (src/commands/token.ts) reuses this too, so "no token" means
+ * the same thing everywhere it can be observed. (#86 findings 1/2, #88 item 4)
+ */
+export declare function notLoggedInError(): AuthError;
 export declare const api: {
     get: <T>(path: string) => Promise<T>;
     getText: (path: string) => Promise<string>;

package/dist/lib/api.js

@@ -25,6 +25,37 @@ export class NetworkError extends Error {
         this.name = 'NetworkError';
     }
 }
+/**
+ * A LOCAL auth failure — no token available, or a locally-decoded token
+ * that's provably expired, discovered entirely client-side before any HTTP
+ * call was ever made. Distinguished from ApiError(401) (a real server-issued
+ * 401 response) so the --json envelope never claims `status:401` for
+ * something the server never said — that would be a fabricated fact,
+ * indistinguishable from an actual server round-trip to a machine consumer.
+ * Both classify to the same exit code (3) / kind "auth" in classifyError
+ * (errors.ts); only the envelope's `status` field differs (present for
+ * ApiError, absent here). (#88 item 4)
+ */
+export class AuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthError';
+    }
+}
+/**
+ * The single "no token available" error — every call site in this file that
+ * needs a token (request/upload/getText/stream) used to throw its own copy
+ * of `new Error('Not logged in. Run: trawl login')`, which fell through
+ * classifyError's generic branch (exit 1, kind:"unknown") — indistinguishable
+ * from an arbitrary bug. Auth-classifying it puts it on the exact same
+ * exit-3 / kind:"auth" path a real 401 response already takes — but as an
+ * AuthError (no HTTP call happened here), never a fabricated ApiError(401).
+ * `trawl token` (src/commands/token.ts) reuses this too, so "no token" means
+ * the same thing everywhere it can be observed. (#86 findings 1/2, #88 item 4)
+ */
+export function notLoggedInError() {
+    return new AuthError('Not logged in. Run: trawl login');
+}
 const DEFAULT_TIMEOUT_MS = 30_000;
 /** Effective fetch timeout — TRAWL_TIMEOUT env override (ms), default 30s. (#71) */
 function getTimeoutMs() {
@@ -166,7 +197,7 @@ async function throwIfError(res, isPublic = false) {
 async function request(path, options = {}) {
     const token = getToken();
     if (!token)
-        throw new Error('Not logged in. Run: trawl login');
+        throw notLoggedInError();
     const url = `${getApiUrl()}${path}`;
     const res = await safeFetch(url, {
         ...options,
@@ -197,7 +228,7 @@ async function request(path, options = {}) {
 async function upload(path, formData) {
     const token = getToken();
     if (!token)
-        throw new Error('Not logged in. Run: trawl login');
+        throw notLoggedInError();
     const url = `${getApiUrl()}${path}`;
     // Do NOT set Content-Type — fetch sets it automatically with the correct multipart boundary
     const res = await safeFetch(url, {
@@ -246,7 +277,7 @@ async function publicPost(path, body, baseUrlOverride) {
 async function getText(path) {
     const token = getToken();
     if (!token)
-        throw new Error('Not logged in. Run: trawl login');
+        throw notLoggedInError();
     const url = `${getApiUrl()}${path}`;
     const res = await safeFetch(url, {
         headers: {
@@ -275,7 +306,7 @@ export const api = {
     stream: async function* (path) {
         const token = getToken();
         if (!token)
-            throw new Error('Not logged in. Run: trawl login');
+            throw notLoggedInError();
         const url = `${getApiUrl()}${path}`;
         // No AbortSignal.timeout here — a long-running `watch`/`--watch` stream is
         // expected to sit open indefinitely; only connection-level failures

package/dist/lib/errors.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { ApiError, NetworkError } from './api.js';
+import { ApiError, AuthError, NetworkError } from './api.js';
 /**
  * Thrown for CLI usage / input-validation failures (bad flag value, malformed
  * JSON, invalid ObjectId, missing required prompt input, …). Distinguished
@@ -22,6 +22,14 @@ export class UsageError extends Error {
  */
 export function classifyError(err) {
     const message = err instanceof Error ? err.message : String(err);
+    // #88 item 4 — a LOCAL auth failure (no token, or a locally-decoded expired
+    // token) never made an HTTP call, so its envelope must never carry
+    // `status:401` — that would claim a server response that never happened.
+    // Same exit code / kind as a real server 401 (ApiError below); only the
+    // envelope shape differs.
+    if (err instanceof AuthError) {
+        return { exitCode: 3, envelope: { message, kind: 'auth' } };
+    }
     if (err instanceof ApiError) {
         if (err.status === 401)
             return { exitCode: 3, envelope: { message, status: 401, kind: 'auth' } };

package/dist/lib/skills.d.ts

@@ -1,14 +1,44 @@
 export declare function getBundledSkillsVersion(): string;
 export declare function listBundledSkills(): string[];
-export declare function installSkill(name: string, scope: 'user' | 'local'): string;
+/**
+ * Ownership guard (#73, extended #86 finding 7): this does `rmSync(recursive)`
+ * on the target dir before reinstalling, so it must never do that to a dir
+ * the CLI didn't install. `autoUpdateInstalledSkills()` already checks this
+ * itself before ever calling here (it skips marker-less dirs outright), but
+ * the explicit `trawl skills install`/`update` commands used to call straight
+ * through with no such check — a pre-existing user-authored
+ * `.claude/skills/<name>` dir that happens to collide with a bundled skill
+ * name would get silently deleted and overwritten. A missing `.version`
+ * marker on an EXISTING dest now refuses the install/reinstall unless
+ * `force` is passed.
+ */
+export declare function installSkill(name: string, scope: 'user' | 'local', opts?: {
+    force?: boolean;
+}): string;
 export declare function uninstallSkill(name: string, scope: 'user' | 'local'): string | null;
 export declare function getInstalledVersion(name: string, scope: 'user' | 'local'): string | null;
 export declare function isSkillInstalled(name: string, scope: 'user' | 'local'): boolean;
+/**
+ * #86 review — orphan cleanup. The re-sync loop in autoUpdateInstalledSkills
+ * iterates listBundledSkills() — the NEW package's names only. When a bundled
+ * skill is RENAMED between package versions (1.0.0 shipped `trawl`, 1.3.1
+ * renamed it `trawl-cli`), the old marker-owned dir is never visited again: a
+ * stale ghost skill teaching outdated CLI usage stays installed forever,
+ * alongside the new one. This sweeps each scope's skills base dir for
+ * installed dirs that (a) carry a `.version` marker — the same ownership
+ * proof as everywhere else; a marker-less user-authored dir is NEVER touched,
+ * whatever its name — and (b) are no longer in the bundled set, and removes
+ * them with one honest stderr line (same style as the re-sync line).
+ * Returns the removed names (for the explicit `skills update` path to
+ * summarize).
+ */
+export declare function removeOrphanedSkills(scope: 'user' | 'local'): string[];
 /**
  * Re-installs any CLI-owned skill whose installed version doesn't match the
- * bundled one. Called on CLI startup to keep skills in sync with the CLI
- * version. Never throws — failures are silent so they don't break unrelated
- * commands.
+ * bundled one, and removes CLI-owned skills that are no longer bundled at all
+ * (renamed/dropped upstream — see removeOrphanedSkills). Called on CLI
+ * startup to keep skills in sync with the CLI version. Never throws —
+ * failures are silent so they don't break unrelated commands.
  *
  * Ownership guard (#73): `installSkill` does `rmSync(recursive)` on the target
  * dir, so this MUST only ever touch dirs the CLI itself installed. Proof of

package/dist/lib/skills.js

@@ -24,14 +24,32 @@ function getSkillsBase(scope) {
     const base = scope === 'local' ? join(process.cwd(), '.claude') : join(homedir(), '.claude');
     return join(base, 'skills');
 }
-export function installSkill(name, scope) {
+/**
+ * Ownership guard (#73, extended #86 finding 7): this does `rmSync(recursive)`
+ * on the target dir before reinstalling, so it must never do that to a dir
+ * the CLI didn't install. `autoUpdateInstalledSkills()` already checks this
+ * itself before ever calling here (it skips marker-less dirs outright), but
+ * the explicit `trawl skills install`/`update` commands used to call straight
+ * through with no such check — a pre-existing user-authored
+ * `.claude/skills/<name>` dir that happens to collide with a bundled skill
+ * name would get silently deleted and overwritten. A missing `.version`
+ * marker on an EXISTING dest now refuses the install/reinstall unless
+ * `force` is passed.
+ */
+export function installSkill(name, scope, opts = {}) {
     const src = join(getSkillsPackageRoot(), 'skills', name);
     if (!existsSync(src)) {
         throw new Error(`Skill "${name}" not found in @trawlme/skills`);
     }
     const dest = join(getSkillsBase(scope), name);
-    if (existsSync(dest))
+    if (existsSync(dest)) {
+        const owned = getInstalledVersion(name, scope) !== null;
+        if (!owned && !opts.force) {
+            throw new Error(`Refusing to overwrite "${dest}" — it was not installed by trawl (no .version marker). ` +
+                `Pass --force to overwrite it anyway.`);
+        }
         rmSync(dest, { recursive: true, force: true });
+    }
     mkdirSync(dest, { recursive: true });
     cpSync(src, dest, { recursive: true });
     writeFileSync(join(dest, '.version'), getBundledSkillsVersion(), 'utf8');
@@ -53,11 +71,63 @@ export function getInstalledVersion(name, scope) {
 export function isSkillInstalled(name, scope) {
     return existsSync(join(getSkillsBase(scope), name));
 }
+/**
+ * #86 review — orphan cleanup. The re-sync loop in autoUpdateInstalledSkills
+ * iterates listBundledSkills() — the NEW package's names only. When a bundled
+ * skill is RENAMED between package versions (1.0.0 shipped `trawl`, 1.3.1
+ * renamed it `trawl-cli`), the old marker-owned dir is never visited again: a
+ * stale ghost skill teaching outdated CLI usage stays installed forever,
+ * alongside the new one. This sweeps each scope's skills base dir for
+ * installed dirs that (a) carry a `.version` marker — the same ownership
+ * proof as everywhere else; a marker-less user-authored dir is NEVER touched,
+ * whatever its name — and (b) are no longer in the bundled set, and removes
+ * them with one honest stderr line (same style as the re-sync line).
+ * Returns the removed names (for the explicit `skills update` path to
+ * summarize).
+ */
+export function removeOrphanedSkills(scope) {
+    const base = getSkillsBase(scope);
+    if (!existsSync(base))
+        return [];
+    const bundled = new Set(listBundledSkills());
+    const removed = [];
+    for (const name of readdirSync(base)) {
+        const dir = join(base, name);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue; // raced away / unreadable — nothing to clean
+        }
+        if (bundled.has(name))
+            continue;
+        // No `.version` marker → not ours → never delete it. Read is wrapped:
+        // a weird `.version` (e.g. a directory instead of a file → EISDIR on
+        // readFileSync) must skip only THIS entry, not blow up the whole sweep —
+        // a single malformed install must never leave every other entry
+        // unswept. (#88 item 12)
+        let installedVersion;
+        try {
+            installedVersion = getInstalledVersion(name, scope);
+        }
+        catch {
+            continue;
+        }
+        if (installedVersion === null)
+            continue;
+        rmSync(dir, { recursive: true, force: true });
+        process.stderr.write(`trawl: removed orphaned skill "${name}" (${scope}) — no longer bundled with this CLI version\n`);
+        removed.push(name);
+    }
+    return removed;
+}
 /**
  * Re-installs any CLI-owned skill whose installed version doesn't match the
- * bundled one. Called on CLI startup to keep skills in sync with the CLI
- * version. Never throws — failures are silent so they don't break unrelated
- * commands.
+ * bundled one, and removes CLI-owned skills that are no longer bundled at all
+ * (renamed/dropped upstream — see removeOrphanedSkills). Called on CLI
+ * startup to keep skills in sync with the CLI version. Never throws —
+ * failures are silent so they don't break unrelated commands.
  *
  * Ownership guard (#73): `installSkill` does `rmSync(recursive)` on the target
  * dir, so this MUST only ever touch dirs the CLI itself installed. Proof of
@@ -89,6 +159,11 @@ export function autoUpdateInstalledSkills() {
                 process.stderr.write(`trawl: re-synced skill "${name}" (${scope}) ${installed} → ${bundledVersion}\n`);
             }
         }
+        // Migration gap (#86 review): also drop marker-owned dirs whose skill
+        // was renamed/removed upstream, or they linger as stale ghosts forever.
+        for (const scope of ['user', 'local']) {
+            removeOrphanedSkills(scope);
+        }
     }
     catch {
         // Silent: skill auto-update should never block the CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.18.1",
+  "version": "1.18.3",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "url": "https://github.com/comes-io/trawl_cli/issues"
   },
   "dependencies": {
-    "@trawlme/skills": "^1.0.0",
+    "@trawlme/skills": "1.3.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "conf": "^15.1.0",