@trawlme/cli 1.20.0 → 1.21.0

package/dist/commands/skills.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { listBundledSkills, installSkill, uninstallSkill, getBundledSkillsVersion, getInstalledVersion, isSkillInstalled, removeOrphanedSkills, } from '../lib/skills.js';
 import { UsageError } from '../lib/errors.js';
+import { json } from '../lib/format.js';
 function pickScope(opts) {
     return opts.local ? 'local' : 'user';
 }
@@ -20,14 +21,21 @@ export const skills = new Command('skills').description('Manage Claude Code skil
 skills
     .command('list')
     .description('List bundled skills and their installed status')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     const bundled = listBundledSkills();
+    const version = getBundledSkillsVersion();
     if (!bundled.length) {
+        if (opts.json) {
+            json({ version, skills: [] });
+            return;
+        }
         console.log(chalk.dim('No bundled skills.'));
         return;
     }
-    const version = getBundledSkillsVersion();
-    console.log(chalk.dim(`@trawlme/skills@${version}\n`));
+    if (!opts.json)
+        console.log(chalk.dim(`@trawlme/skills@${version}\n`));
+    const rows = [];
     for (const name of bundled) {
         const userInstalled = isSkillInstalled(name, 'user');
         const localInstalled = isSkillInstalled(name, 'local');
@@ -59,7 +67,16 @@ skills
                 installedVersion = null;
             }
         }
-        const stale = installedVersion && installedVersion !== version;
+        const stale = Boolean(installedVersion && installedVersion !== version);
+        if (opts.json) {
+            rows.push({
+                name,
+                installed: { user: userInstalled, local: localInstalled },
+                installedVersion,
+                outdated: stale,
+            });
+            continue;
+        }
         const tag = userInstalled
             ? localInstalled
                 ? '(user + local)'
@@ -70,46 +87,72 @@ skills
         const staleNote = stale ? chalk.yellow(` outdated: ${installedVersion} → ${version}`) : '';
         console.log(`  ${name} ${chalk.dim(tag)}${staleNote}`);
     }
+    if (opts.json)
+        json({ version, skills: rows });
 });
 skills
     .command('install [skill]')
     .description('Install one or all bundled skills')
     .option('--local', 'Install at project level (./.claude/skills) instead of user level (~/.claude/skills)')
     .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
+    .option('--json', 'Output as JSON')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
+    const results = [];
     for (const name of targets) {
         const dest = installSkill(name, scope, { force: opts.force });
+        if (opts.json) {
+            results.push({ name, scope, dest });
+            continue;
+        }
         console.log(chalk.green(`✓ Installed "${name}"`) + chalk.dim(` at ${dest}`));
     }
+    if (opts.json) {
+        json({ installed: results });
+        return;
+    }
     console.log(chalk.dim('  Restart Claude Code if it was already running.'));
 });
 skills
     .command('uninstall [skill]')
     .description('Remove one or all bundled skills')
     .option('--local', 'Remove from project level (./.claude/skills)')
+    .option('--json', 'Output as JSON')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
+    const results = [];
     for (const name of targets) {
         const dest = uninstallSkill(name, scope);
+        if (opts.json) {
+            results.push({ name, scope, dest, removed: dest !== null });
+            continue;
+        }
         if (dest)
             console.log(chalk.green(`✓ Removed "${name}"`) + chalk.dim(` from ${dest}`));
         else
             console.log(chalk.dim(`  No "${name}" found`));
     }
+    if (opts.json)
+        json({ uninstalled: results });
 });
 skills
     .command('update [skill]')
     .description('Reinstall over the existing skill (force sync with CLI version)')
     .option('--local', 'Update at project level')
     .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
+    .option('--json', 'Output as JSON')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
+    const results = [];
     for (const name of targets) {
         const dest = installSkill(name, scope, { force: opts.force });
+        if (opts.json) {
+            results.push({ name, scope, dest });
+            continue;
+        }
         console.log(chalk.green(`✓ Updated "${name}"`) + chalk.dim(` at ${dest}`));
     }
     // #86 review — same orphan sweep as the startup auto-sync: an explicit
@@ -117,6 +160,9 @@ skills
     // or removed upstream (e.g. 1.0.0's `trawl` → 1.3.1's `trawl-cli`),
     // instead of leaving a stale ghost teaching outdated usage. Only the
     // scope being updated is swept; marker-less dirs are never touched.
-    // removeOrphanedSkills prints its own honest stderr line per removal.
-    removeOrphanedSkills(scope);
+    // removeOrphanedSkills prints its own honest stderr line per removal
+    // (stderr, so it's safe under --json too).
+    const orphansRemoved = removeOrphanedSkills(scope);
+    if (opts.json)
+        json({ updated: results, orphansRemoved });
 });

package/dist/commands/telemetry.js

@@ -2,33 +2,53 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import config from '../lib/config.js';
 import { initPostHog } from '../lib/posthog.js';
+import { json } from '../lib/format.js';
 export const telemetry = new Command('telemetry').description('Manage CLI telemetry (usage data collection)');
 telemetry
     .command('on')
     .description('Enable telemetry (default)')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     config.set('telemetry', true);
     // Ensure a telemetryUserId is created on opt-in
     initPostHog();
+    if (opts.json) {
+        json({ telemetry: true });
+        return;
+    }
     console.log(chalk.green('✓ Telemetry enabled'));
     console.log(chalk.dim('  Anonymous usage data will be collected. Run `trawl telemetry status` to view.'));
 });
 telemetry
     .command('off')
     .description('Disable telemetry')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     config.set('telemetry', false);
+    if (opts.json) {
+        json({ telemetry: false });
+        return;
+    }
     console.log(chalk.green('✓ Telemetry disabled'));
     console.log(chalk.dim('  No data will be sent. Your telemetry ID is kept for if you re-enable later.'));
 });
 telemetry
     .command('status')
     .description('Show current telemetry state')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     const enabled = config.get('telemetry') !== false;
     const userId = config.get('telemetryUserId') || '(not yet generated)';
     const envOverride = process.env['TRAWL_TELEMETRY'] === '0';
     const doNotTrack = process.env['DO_NOT_TRACK'] === '1';
+    // The effective on/off state factoring in both env overrides — matches
+    // the human-mode "State:" line's own precedence (DO_NOT_TRACK >
+    // TRAWL_TELEMETRY > config).
+    const effectiveEnabled = enabled && !envOverride && !doNotTrack;
+    if (opts.json) {
+        json({ enabled: effectiveEnabled, configEnabled: enabled, telemetryUserId: config.get('telemetryUserId') || null, envOverride, doNotTrack });
+        return;
+    }
     console.log(chalk.bold('Telemetry status'));
     console.log(chalk.dim('  State:         ') +
         (doNotTrack

package/dist/commands/token.js

@@ -4,9 +4,11 @@ import { getToken } from '../lib/config.js';
 import { AuthError, notLoggedInError } from '../lib/api.js';
 import { reportError } from '../lib/errors.js';
 import { decodeExp } from '../lib/jwt.js';
+import { json } from '../lib/format.js';
 export const token = new Command('token')
     .description('Print the stored session JWT (for MCP Bearer auth)')
-    .action(() => {
+    .option('--json', 'Output as JSON ({token, exp, expiresAt}) instead of the raw JWT')
+    .action((opts) => {
     // getToken() resolves TRAWL_TOKEN env first, then the stored config
     // token (see config.ts:47-51) — matching every other token consumer in
     // the CLI instead of reading the config store directly. (#86 finding 1)
@@ -15,7 +17,7 @@ export const token = new Command('token')
         // Auth-classified (ApiError 401 → exit 3, kind:"auth"), not a generic
         // exit 1 — an agent scripting `trawl token` needs to tell "not logged
         // in" apart from an arbitrary bug. (#86 finding 1)
-        process.exitCode = reportError(notLoggedInError());
+        process.exitCode = reportError(notLoggedInError(), { json: opts.json });
         return;
     }
     const exp = decodeExp(stored);
@@ -24,7 +26,11 @@ export const token = new Command('token')
         // Decoded entirely client-side (no HTTP call made) — AuthError, not a
         // fabricated ApiError(401): the server never actually said this. (#88
         // item 4)
-        process.exitCode = reportError(new AuthError('Session token expired. Run: trawl login to refresh.'));
+        process.exitCode = reportError(new AuthError('Session token expired. Run: trawl login to refresh.'), { json: opts.json });
+        return;
+    }
+    if (opts.json) {
+        json({ token: stored, exp, expiresAt: exp !== null ? new Date(exp * 1000).toISOString() : null });
         return;
     }
     // Print the raw token first (so it can be piped / copied)

package/dist/lib/confirm.d.ts

@@ -0,0 +1,70 @@
+/**
+ * #107 — the machine contract's non-interactive rule, in one place. True only
+ * when a blocking interactive prompt is safe to show: NOT `--json` (a machine
+ * consumer needs pure stdout, and there's no human reading a prompt anyway)
+ * AND both stdin/stdout are real TTYs. A pipe/redirect/CI runner — including
+ * an agent driving this CLI as a subprocess — has nowhere for a human to type
+ * an answer; a blocking `readline` prompt in that situation hangs forever
+ * instead of ever returning.
+ */
+export declare function isInteractive(opts?: {
+    json?: boolean;
+}): boolean;
+export interface ConfirmOutcome {
+    /** True when the caller should proceed with the guarded action. */
+    proceed: boolean;
+    /**
+     * True when refused because the invocation is non-interactive (`--json`,
+     * or stdin/stdout isn't a real TTY) — a structured usage error has ALREADY
+     * been reported (the stderr line and/or the `--json` envelope) and
+     * `process.exitCode` set to 2. The caller must return immediately without
+     * printing anything else (mirrors every other `usageError()` call site).
+     */
+    blocked: boolean;
+}
+/**
+ * Shared guard for every destructive y/N confirmation in the CLI (`scraps
+ * delete`, `scraps account delete`, …). #107 — before this, each call site
+ * hand-rolled its own `readline` question with no non-interactive escape
+ * hatch, so a scripted/agent invocation with no `-f`/`--force` would hang
+ * forever waiting for a y/N answer that could never arrive.
+ *
+ * `-f`/`--force` (`opts.force`) always pre-confirms, interactive or not — the
+ * caller already gave explicit consent up front. Otherwise:
+ *  - Non-interactive (`--json`, or stdin/stdout isn't a real TTY): NEVER
+ *    prompts. Reports a structured usage error (exit 2) instead, via the same
+ *    central `reportError` formatting path every other error in this CLI
+ *    uses (stderr human line, or the `--json` envelope on stdout).
+ *  - Interactive: prompts via `readline` exactly like the pre-#107 call
+ *    sites did.
+ *
+ * `message` MUST be plain, unstyled text — it feeds both the refusal
+ * UsageError's message (human stderr line AND the `--json` error envelope on
+ * stdout) and the fallback prompt text. Before this, call sites passed a
+ * `chalk.bold(id)`-styled string as `message`, which leaked raw ANSI escape
+ * bytes into the `--json` envelope (e.g. `scraps delete X --json` on the
+ * refusal path emitted a message with the raw bold-on/off escape sequence
+ * wrapped around the id) — unusable for a script/agent parsing that string.
+ * `promptMessage` is the OPTIONAL styled variant shown only for the
+ * interactive TTY `[y/N]` prompt (chalk is safe there — no machine ever
+ * reads it); it defaults to `message` when omitted. (#107 review F2)
+ */
+export declare function confirmDestructive(message: string, opts?: {
+    force?: boolean;
+    json?: boolean;
+    promptMessage?: string;
+}): Promise<ConfirmOutcome>;
+/**
+ * Guard for a required interactive value that has no flag-supplied value yet
+ * (login's email prompt, …) — for call sites that propagate errors by
+ * `throw`ing and let the top-level handler in index.ts classify + report
+ * (login.ts's existing convention), as opposed to `scraps.ts`'s local
+ * exitCode-setting `usageError()` style (which should check `isInteractive`
+ * directly instead of using this). Same non-interactive contract as
+ * `confirmDestructive`: never invokes a blocking prompt when `--json` is set
+ * or stdin/stdout isn't a real TTY — throws a `UsageError` naming the flag to
+ * pass instead. (#107)
+ */
+export declare function requireInteractive(message: string, opts?: {
+    json?: boolean;
+}): void;

package/dist/lib/confirm.js

@@ -0,0 +1,79 @@
+import chalk from 'chalk';
+import { UsageError } from './errors.js';
+import { reportError } from './errors.js';
+/**
+ * #107 — the machine contract's non-interactive rule, in one place. True only
+ * when a blocking interactive prompt is safe to show: NOT `--json` (a machine
+ * consumer needs pure stdout, and there's no human reading a prompt anyway)
+ * AND both stdin/stdout are real TTYs. A pipe/redirect/CI runner — including
+ * an agent driving this CLI as a subprocess — has nowhere for a human to type
+ * an answer; a blocking `readline` prompt in that situation hangs forever
+ * instead of ever returning.
+ */
+export function isInteractive(opts = {}) {
+    if (opts.json)
+        return false;
+    return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+/**
+ * Shared guard for every destructive y/N confirmation in the CLI (`scraps
+ * delete`, `scraps account delete`, …). #107 — before this, each call site
+ * hand-rolled its own `readline` question with no non-interactive escape
+ * hatch, so a scripted/agent invocation with no `-f`/`--force` would hang
+ * forever waiting for a y/N answer that could never arrive.
+ *
+ * `-f`/`--force` (`opts.force`) always pre-confirms, interactive or not — the
+ * caller already gave explicit consent up front. Otherwise:
+ *  - Non-interactive (`--json`, or stdin/stdout isn't a real TTY): NEVER
+ *    prompts. Reports a structured usage error (exit 2) instead, via the same
+ *    central `reportError` formatting path every other error in this CLI
+ *    uses (stderr human line, or the `--json` envelope on stdout).
+ *  - Interactive: prompts via `readline` exactly like the pre-#107 call
+ *    sites did.
+ *
+ * `message` MUST be plain, unstyled text — it feeds both the refusal
+ * UsageError's message (human stderr line AND the `--json` error envelope on
+ * stdout) and the fallback prompt text. Before this, call sites passed a
+ * `chalk.bold(id)`-styled string as `message`, which leaked raw ANSI escape
+ * bytes into the `--json` envelope (e.g. `scraps delete X --json` on the
+ * refusal path emitted a message with the raw bold-on/off escape sequence
+ * wrapped around the id) — unusable for a script/agent parsing that string.
+ * `promptMessage` is the OPTIONAL styled variant shown only for the
+ * interactive TTY `[y/N]` prompt (chalk is safe there — no machine ever
+ * reads it); it defaults to `message` when omitted. (#107 review F2)
+ */
+export async function confirmDestructive(message, opts = {}) {
+    if (opts.force)
+        return { proceed: true, blocked: false };
+    if (!isInteractive(opts)) {
+        process.exitCode = reportError(new UsageError(`${message} requires confirmation — refusing to block on a prompt (non-interactive). Pass -f/--force to confirm.`), { json: opts.json });
+        return { proceed: false, blocked: true };
+    }
+    const { createInterface } = await import('readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(`${opts.promptMessage ?? message} ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
+        });
+        return { proceed: answer === 'y' || answer === 'yes', blocked: false };
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Guard for a required interactive value that has no flag-supplied value yet
+ * (login's email prompt, …) — for call sites that propagate errors by
+ * `throw`ing and let the top-level handler in index.ts classify + report
+ * (login.ts's existing convention), as opposed to `scraps.ts`'s local
+ * exitCode-setting `usageError()` style (which should check `isInteractive`
+ * directly instead of using this). Same non-interactive contract as
+ * `confirmDestructive`: never invokes a blocking prompt when `--json` is set
+ * or stdin/stdout isn't a real TTY — throws a `UsageError` naming the flag to
+ * pass instead. (#107)
+ */
+export function requireInteractive(message, opts = {}) {
+    if (!isInteractive(opts)) {
+        throw new UsageError(message);
+    }
+}

package/dist/lib/errors.d.ts

@@ -8,6 +8,19 @@
 export declare class UsageError extends Error {
     constructor(message: string);
 }
+/**
+ * Thrown for a business-logic REFUSAL the server explicitly reported back
+ * (e.g. a tier-ceiling override the registry cap rejected) — distinct from
+ * an arbitrary unmapped bug. Before this, `reportTierRefusal` routed a bare
+ * `new Error(message)` through here, which fell through to the generic
+ * `kind:"unknown"` bucket — indistinguishable from a genuine crash, even
+ * though the README sells `kind` as the machine discriminant an agent
+ * branches on. Same exit code (1: a business-logic refusal, not a usage
+ * error) as before — only the `kind` differs. (#107 review F3)
+ */
+export declare class RefusalError extends Error {
+    constructor(message: string);
+}
 export interface ErrorEnvelope {
     message: string;
     status?: number;

package/dist/lib/errors.js

@@ -13,6 +13,22 @@ export class UsageError extends Error {
         this.name = 'UsageError';
     }
 }
+/**
+ * Thrown for a business-logic REFUSAL the server explicitly reported back
+ * (e.g. a tier-ceiling override the registry cap rejected) — distinct from
+ * an arbitrary unmapped bug. Before this, `reportTierRefusal` routed a bare
+ * `new Error(message)` through here, which fell through to the generic
+ * `kind:"unknown"` bucket — indistinguishable from a genuine crash, even
+ * though the README sells `kind` as the machine discriminant an agent
+ * branches on. Same exit code (1: a business-logic refusal, not a usage
+ * error) as before — only the `kind` differs. (#107 review F3)
+ */
+export class RefusalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RefusalError';
+    }
+}
 /**
  * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
  * CLI unattended need to tell "you're not logged in" (3) from "that id
@@ -43,6 +59,9 @@ export function classifyError(err) {
     if (err instanceof UsageError) {
         return { exitCode: 2, envelope: { message, kind: 'usage' } };
     }
+    if (err instanceof RefusalError) {
+        return { exitCode: 1, envelope: { message, kind: 'refused' } };
+    }
     return { exitCode: 1, envelope: { message, kind: 'unknown' } };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {