@trawlme/cli 3.11.0 → 3.12.1

package/dist/lib/session-capture-guard.d.ts

@@ -0,0 +1,6 @@
+export interface NonInteractiveEnv {
+    stdinIsTTY: boolean;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+}
+export declare function detectNonInteractive({ stdinIsTTY, platform, env }: NonInteractiveEnv): string | null;

package/dist/lib/session-capture-guard.js

@@ -0,0 +1,9 @@
+export function detectNonInteractive({ stdinIsTTY, platform, env }) {
+    if (!stdinIsTTY) {
+        return 'No interactive terminal attached (stdin is not a TTY) — this command opens a visible Chrome window for a human to log into and needs a terminal to confirm completion. It does not work headless, in CI, or piped.';
+    }
+    if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+        return 'No display detected (DISPLAY/WAYLAND_DISPLAY are both unset) — this command opens a visible Chrome window and cannot run over a plain SSH session, in a container, or headless.';
+    }
+    return null;
+}

package/dist/lib/session-capture.d.ts

@@ -0,0 +1,55 @@
+import type { ChildProcess } from 'node:child_process';
+import type { CdpPipe } from './cdp-pipe.js';
+import { type RawCdpCookie, type RawOriginLocalStorage, type StorageState } from './storage-state.js';
+export interface CaptureCounts {
+    cookiesCaptured: number;
+    cookiesDroppedOutOfScope: number;
+    cookiesDroppedInvalid: number;
+    originsCaptured: number;
+    originsDroppedOutOfScope: number;
+    originsUnreadable: number;
+    closedEarly: boolean;
+}
+export type CaptureFailureReason = 'non_interactive' | 'no_chrome' | 'launch_failed' | 'capture_failed' | 'process_exited_before_capture' | 'cdp_protocol_error' | 'no_cookies_in_scope';
+export type CaptureResult = {
+    ok: true;
+    storageState: StorageState;
+    counts: CaptureCounts;
+    targetDomain: string;
+} | {
+    ok: false;
+    reason: CaptureFailureReason;
+    message: string;
+};
+interface RawCapture {
+    cookies: RawCdpCookie[];
+    origins: RawOriginLocalStorage[];
+    originsUnreadable: number;
+}
+export interface CaptureDeps {
+    detectNonInteractive(): string | null;
+    findChrome(): string | null;
+    mkdtemp(): string;
+    rmSync(dir: string): void;
+    launch(chromePath: string, targetUrl: string, userDataDir: string): Promise<{
+        proc: ChildProcess;
+        cdp: CdpPipe;
+    }>;
+    findPageTarget(cdp: CdpPipe): Promise<string>;
+    waitForDone(cdp: CdpPipe, targetId: string, cleanup: () => void): Promise<{
+        closedEarly: boolean;
+    }>;
+    readCapture(cdp: CdpPipe, targetUrl: string, closedEarly: boolean): Promise<RawCapture>;
+    onSigint(cleanup: () => void): () => void;
+}
+export declare function findPageTargetDefault(cdp: CdpPipe): Promise<string>;
+export declare function waitForDoneDefault(cdp: CdpPipe, targetId: string, cleanup: () => void): Promise<{
+    closedEarly: boolean;
+}>;
+export declare const LOCALSTORAGE_READ_TIMEOUT_MS = 30000;
+export declare function readCaptureDefault(cdp: CdpPipe, targetUrl: string, closedEarly: boolean): Promise<RawCapture>;
+export declare function rmSyncWithRetry(dir: string): void;
+export declare function registerTerminationHandlers(cleanup: () => void): () => void;
+export declare function checkInteractiveEnvironment(): string | null;
+export declare function captureSession(targetUrl: string, depsOverride?: Partial<CaptureDeps>): Promise<CaptureResult>;
+export {};

package/dist/lib/session-capture.js

@@ -0,0 +1,319 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { findChrome } from './chrome-discovery.js';
+import { launchChrome } from './chrome-launch.js';
+import { detectNonInteractive } from './session-capture-guard.js';
+import { mapCookies, mapOrigins, getTargetHost, isOriginHostInScope, } from './storage-state.js';
+const PROCESS_EXITED_MESSAGE = 'Chrome exited before the session was read — nothing uploaded. The capture completes on Enter in the terminal; Chrome exiting first ends the run without a session.';
+function cdpProtocolErrorMessage(protocolError) {
+    return `${protocolError.message} Nothing was uploaded.`;
+}
+export async function findPageTargetDefault(cdp) {
+    const deadline = Date.now() + 10_000;
+    for (;;) {
+        const { targetInfos } = await cdp.send('Target.getTargets');
+        const page = targetInfos.find((t) => t.type === 'page');
+        if (page)
+            return page.targetId;
+        if (Date.now() > deadline)
+            throw new Error('Chrome did not open a page target in time');
+        await new Promise((r) => setTimeout(r, 100));
+    }
+}
+export async function waitForDoneDefault(cdp, targetId, cleanup) {
+    await cdp.send('Target.setDiscoverTargets', { discover: true });
+    return new Promise((resolve) => {
+        let settled = false;
+        const offDestroyed = cdp.on('Target.targetDestroyed', (params) => {
+            const p = params;
+            if (!settled && p.targetId === targetId) {
+                settled = true;
+                offDestroyed();
+                offClose();
+                rl.close();
+                resolve({ closedEarly: true });
+            }
+        });
+        const offClose = cdp.onClose(() => {
+            if (!settled) {
+                settled = true;
+                offDestroyed();
+                rl.close();
+                resolve({ closedEarly: true });
+            }
+        });
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        rl.on('SIGINT', () => {
+            settled = true;
+            offDestroyed();
+            offClose();
+            rl.close();
+            cleanup();
+            process.exit(130);
+        });
+        rl.question('Capture completes on Enter once you are signed in, or when the Chrome window is closed: ', () => {
+            if (!settled) {
+                settled = true;
+                offDestroyed();
+                offClose();
+                rl.close();
+                resolve({ closedEarly: false });
+            }
+        });
+    });
+}
+export const LOCALSTORAGE_READ_TIMEOUT_MS = 30_000;
+const LOCALSTORAGE_READ_PROGRESS_MS = 5_000;
+function isLocalStorageEntriesShape(value) {
+    return (Array.isArray(value) &&
+        value.every((e) => typeof e === 'object' && e !== null && typeof e.name === 'string' && typeof e.value === 'string'));
+}
+async function readPageOverCdp(cdp, targetId) {
+    let sessionId;
+    try {
+        const attached = await cdp.send('Target.attachToTarget', {
+            targetId,
+            flatten: true,
+        });
+        sessionId = attached.sessionId;
+        const progressTimer = setTimeout(() => {
+            process.stderr.write(`  still waiting for a page to finish its scripts (up to ${LOCALSTORAGE_READ_TIMEOUT_MS / 1000}s)…\n`);
+        }, LOCALSTORAGE_READ_PROGRESS_MS);
+        try {
+            return await cdp.send('Runtime.evaluate', {
+                expression: 'Object.entries(window.localStorage).map(([name, value]) => ({ name, value }))',
+                returnByValue: true,
+            }, sessionId, LOCALSTORAGE_READ_TIMEOUT_MS);
+        }
+        finally {
+            clearTimeout(progressTimer);
+        }
+    }
+    finally {
+        if (sessionId) {
+            try {
+                await cdp.send('Target.detachFromTarget', { sessionId });
+            }
+            catch {
+            }
+        }
+    }
+}
+export async function readCaptureDefault(cdp, targetUrl, closedEarly) {
+    const { cookies } = await cdp.send('Storage.getCookies', {});
+    if (closedEarly)
+        return { cookies, origins: [], originsUnreadable: 0 };
+    const targetHost = getTargetHost(targetUrl);
+    const { targetInfos } = await cdp.send('Target.getTargets');
+    const pages = targetInfos.filter((t) => t.type === 'page');
+    const origins = [];
+    let originsUnreadable = 0;
+    for (const page of pages) {
+        let origin;
+        try {
+            const u = new URL(page.url);
+            if (!isOriginHostInScope(u.hostname, targetHost))
+                continue;
+            origin = u.origin;
+        }
+        catch {
+            continue;
+        }
+        let evalResult;
+        try {
+            evalResult = await readPageOverCdp(cdp, page.targetId);
+        }
+        catch (e) {
+            if (cdp.isClosed)
+                throw e;
+            originsUnreadable++;
+            process.stderr.write('  one in-scope page could not be read over CDP — counted, continuing…\n');
+            continue;
+        }
+        if (evalResult.exceptionDetails) {
+            originsUnreadable++;
+            continue;
+        }
+        const value = evalResult.result?.value;
+        if (!isLocalStorageEntriesShape(value)) {
+            originsUnreadable++;
+            continue;
+        }
+        if (value.length > 0) {
+            origins.push({ origin, entries: value });
+        }
+    }
+    return { cookies, origins, originsUnreadable };
+}
+export function rmSyncWithRetry(dir) {
+    const MAX_ATTEMPTS = 5;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            return;
+        }
+        catch (e) {
+            if (attempt === MAX_ATTEMPTS)
+                throw e;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 40);
+        }
+    }
+}
+const TERMINATION_EXIT_CODES = {
+    SIGHUP: 129,
+    SIGINT: 130,
+    SIGTERM: 143,
+};
+export function registerTerminationHandlers(cleanup) {
+    const signals = Object.keys(TERMINATION_EXIT_CODES);
+    const handlers = signals.map((signal) => {
+        const handler = () => {
+            cleanup();
+            process.exit(TERMINATION_EXIT_CODES[signal]);
+        };
+        process.on(signal, handler);
+        return { signal, handler };
+    });
+    return () => {
+        for (const { signal, handler } of handlers)
+            process.off(signal, handler);
+    };
+}
+export function checkInteractiveEnvironment() {
+    return detectNonInteractive({ stdinIsTTY: Boolean(process.stdin.isTTY), platform: process.platform, env: process.env });
+}
+function defaultDeps() {
+    return {
+        detectNonInteractive: checkInteractiveEnvironment,
+        findChrome: () => findChrome(),
+        mkdtemp: () => mkdtempSync(join(tmpdir(), 'trawl-session-')),
+        rmSync: rmSyncWithRetry,
+        launch: (chromePath, targetUrl, userDataDir) => launchChrome(chromePath, targetUrl, userDataDir),
+        findPageTarget: findPageTargetDefault,
+        waitForDone: waitForDoneDefault,
+        readCapture: readCaptureDefault,
+        onSigint: registerTerminationHandlers,
+    };
+}
+export async function captureSession(targetUrl, depsOverride = {}) {
+    const deps = { ...defaultDeps(), ...depsOverride };
+    const guardMessage = deps.detectNonInteractive();
+    if (guardMessage)
+        return { ok: false, reason: 'non_interactive', message: guardMessage };
+    const chromePath = deps.findChrome();
+    if (!chromePath) {
+        return {
+            ok: false,
+            reason: 'no_chrome',
+            message: 'No Chrome or Chromium executable was found. Google Chrome, once installed, is auto-detected; TRAWL_CHROME_PATH names one explicitly.',
+        };
+    }
+    const userDataDir = deps.mkdtemp();
+    let proc;
+    let cleaned = false;
+    const cleanup = () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        try {
+            if (proc?.pid) {
+                if (process.platform === 'win32')
+                    proc.kill('SIGKILL');
+                else
+                    process.kill(-proc.pid, 'SIGKILL');
+            }
+        }
+        catch {
+        }
+        try {
+            deps.rmSync(userDataDir);
+        }
+        catch {
+        }
+    };
+    const unregisterSigint = deps.onSigint(cleanup);
+    let launched;
+    let stage = 'launch';
+    try {
+        launched = await deps.launch(chromePath, targetUrl, userDataDir);
+        proc = launched.proc;
+        let pipeClosed = false;
+        const offClose = launched.cdp.onClose(() => {
+            pipeClosed = true;
+        });
+        stage = 'handshake';
+        const targetId = await deps.findPageTarget(launched.cdp);
+        const { closedEarly } = await deps.waitForDone(launched.cdp, targetId, cleanup);
+        if (pipeClosed) {
+            if (launched.cdp.protocolError) {
+                return {
+                    ok: false,
+                    reason: 'cdp_protocol_error',
+                    message: cdpProtocolErrorMessage(launched.cdp.protocolError),
+                };
+            }
+            return {
+                ok: false,
+                reason: 'process_exited_before_capture',
+                message: PROCESS_EXITED_MESSAGE,
+            };
+        }
+        stage = 'capture';
+        const raw = await deps.readCapture(launched.cdp, targetUrl, closedEarly);
+        offClose();
+        const cookieResult = mapCookies(raw.cookies, targetUrl);
+        const originResult = mapOrigins(raw.origins, targetUrl);
+        const targetDomain = getTargetHost(targetUrl);
+        if (cookieResult.cookies.length === 0) {
+            return {
+                ok: false,
+                reason: 'no_cookies_in_scope',
+                message: `0 cookies in scope for ${targetDomain} — nothing uploaded. Login had not completed on that domain when the capture ran.`,
+            };
+        }
+        return {
+            ok: true,
+            storageState: { cookies: cookieResult.cookies, origins: originResult.origins },
+            targetDomain,
+            counts: {
+                cookiesCaptured: cookieResult.cookies.length,
+                cookiesDroppedOutOfScope: cookieResult.droppedOutOfScope,
+                cookiesDroppedInvalid: cookieResult.droppedInvalid,
+                originsCaptured: originResult.origins.length,
+                originsDroppedOutOfScope: originResult.droppedOutOfScope,
+                originsUnreadable: raw.originsUnreadable,
+                closedEarly,
+            },
+        };
+    }
+    catch (e) {
+        if (launched?.cdp.protocolError) {
+            return {
+                ok: false,
+                reason: 'cdp_protocol_error',
+                message: cdpProtocolErrorMessage(launched.cdp.protocolError),
+            };
+        }
+        if (launched?.cdp.isClosed) {
+            return {
+                ok: false,
+                reason: 'process_exited_before_capture',
+                message: PROCESS_EXITED_MESSAGE,
+            };
+        }
+        if (stage === 'capture') {
+            return {
+                ok: false,
+                reason: 'capture_failed',
+                message: 'The capture failed during the capture stage, after Chrome was already reachable over CDP and a page was already open — this is a CLI-side failure, not a page or environment problem. Nothing was uploaded.',
+            };
+        }
+        return { ok: false, reason: 'launch_failed', message: `Chrome could not be driven over CDP: ${e.message}` };
+    }
+    finally {
+        unregisterSigint();
+        cleanup();
+    }
+}

package/dist/lib/skills.d.ts

@@ -1,198 +1,23 @@
 export declare function getBundledSkillsVersion(): string;
 export declare function listBundledSkills(): string[];
-/**
- * #184 defect 1 — the ownership-refusal thrown below serves two different
- * audiences on two different channels, and one string can't correctly serve
- * both:
- *
- *  - A human who just typed `trawl skills install`/`update` reaches this via
- *    an uncaught throw (index.ts's generic error path prints `.message`
- *    verbatim) — that reader can decide whether to add `--force`, so the
- *    guidance belongs on this channel. `.message` (below) keeps it.
- *  - `bootstrapSkillsOnLogin` also catches this exact throw and relays its
- *    text into `skipped[].reason`, which `login.ts` prints to stderr — a
- *    channel this feature's own doc comments say must never carry a command
- *    phrased as an instruction, because this CLI is driven by AI agents and
- *    this platform can feed a CLI's own stderr back into an agent's own
- *    context. `Pass --force to overwrite it anyway` is exactly that kind of
- *    instruction: an agent "obeying" it calls `installSkill`'s own
- *    `rmSync(recursive)` on a directory the user owns and trawl did not
- *    create — the destroy-the-user's-files incident this class of bug
- *    produces.
- *
- * `.relayableReason` carries the identical fact — this path exists, trawl
- * did not create it, so it was left untouched — with the imperative sentence
- * removed, for every channel that is not a direct, synchronous reply to a
- * human's own typed command.
- */
 export declare class SkillOwnershipRefusalError extends Error {
     readonly relayableReason: string;
     constructor(dest: 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, 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
- * ownership is a `.version` marker. A user-created `.claude/skills/<name>` dir
- * that happens to collide with a bundled skill name carries no marker, so it is
- * left untouched instead of being silently deleted + overwritten.
- *
- * Opt-out: `TRAWL_SKILLS_SYNC=0` disables auto-sync entirely (mirrors
- * `TRAWL_TELEMETRY=0`), for users who manage their skills by hand.
- */
 export declare function autoUpdateInstalledSkills(): void;
-/**
- * #184 — one line, reused everywhere the CLI installs a skill mid-invocation
- * (login's bootstrap below, lib/skillsNudge.ts's two nudges): skills are
- * discovered at Claude Code SESSION START, so a skill written to disk right
- * now is invisible to whatever session is already running. Stated as a
- * fact, never an imperative ("restart Claude Code") — this text can be
- * relayed into an AI agent's own context (this CLI's whole incident was an
- * agent driving it), and a command phrased there must never read as an
- * instruction the agent is being told to obey.
- */
 export declare const RESTART_CLAUDE_CODE_NOTE = "Claude Code must be restarted to see them \u2014 skills are loaded at session start, not mid-session.";
-/**
- * #184 — pure gate shared by every skills-related write/print that must
- * never fire under `--json` (a machine consumer needs pure stdout and there
- * is no human reading a suggestion anyway), on a non-TTY invocation (a CI
- * runner or an agent driving this CLI as a subprocess has no Claude Code
- * session to discover a newly-installed skill in the first place), or when
- * `TRAWL_SKILLS_SYNC=0` (the existing auto-sync opt-out, extended here: a
- * user who manages skills by hand does not want the CLI touching that dir
- * for ANY reason — install or nudge alike). Every signal is a parameter,
- * exactly like lib/tips.ts's `isReferralTipDue`, so this is testable
- * without mocking env/TTY. `isTTY`'s exact definition (stdout-only vs
- * stdin+stdout) is the CALLER's call — see bootstrapSkillsOnLogin below vs
- * lib/skillsNudge.ts for the two different answers this codebase already
- * gives elsewhere (confirm.ts's `isInteractive` vs tips.ts's own check).
- */
 export declare function isSkillsActionAllowed(opts: {
     json?: boolean;
     isTTY: boolean;
     optedOut: boolean;
 }): boolean;
-/**
- * #184 — the "install on login, and only there" half of the never-installed
- * bootstrap (see the module doc comment on `autoUpdateInstalledSkills`
- * above for the "elsewhere: suggest, never install" half, which lives in
- * lib/skillsNudge.ts instead). `autoUpdateInstalledSkills` deliberately
- * never installs (`if (!isSkillInstalled) continue`) — it only keeps an
- * EXISTING install in sync. A user who has never run any `trawl skills`
- * command and never logged in before this shipped has nothing installed at
- * all, and nothing in the CLI's startup path ever puts anything there: the
- * CLI is competent, the agent reading its skills is not — the incident this
- * issue exists to prevent. `login` is the one intentional human setup
- * moment (the only place a human types credentials), so it is the ONLY
- * place this function is ever called from (see commands/login.ts) — never
- * from the generic startup path.
- *
- * Gated by `isSkillsActionAllowed` exactly like every other skills-related
- * side effect: a non-interactive `trawl login` (CI's `TRAWL_TOKEN=x trawl
- * login --json`, or any non-TTY invocation) writes nothing — that machine
- * has no Claude Code session to discover a skill in, and `--json`'s stdout
- * contract has no room for a plain-text confirmation line anyway. Also
- * skipped entirely under `TRAWL_SKILLS_SYNC=0`.
- *
- * Installs every bundled skill NOT YET OWNED by trawl at `scope` (default
- * 'user' — the global location a fresh `npx @trawlme/cli login` writes to;
- * 'local' is opt-in via the same --local convention `trawl skills install`
- * already uses everywhere else, kept for parity/tests). "Owned" means a
- * readable `.version` marker (#184 review MAJOR — NOT mere path existence:
- * see below for why that distinction matters here). One skill's install
- * throwing must never blank out the others (#91's posture, applied here):
- * each is wrapped individually, and the function reports exactly what
- * landed. Returns `null` (nothing written, nothing to report) ONLY when
- * gated out, or when every bundled skill is already owned (the re-sync
- * loop above already keeps an existing install's version current) — the
- * genuine "nothing to do" case. Never throws — a broken bootstrap must
- * never turn a successful login into a failed one.
- *
- * #184 review (BLOCK + MAJOR) — two cases used to collapse into the exact
- * same `null`/silence as genuine "nothing to do":
- *
- *  1. (BLOCK) Every install attempt failing outright (an unwritable
- *     `~/.claude/skills`, e.g.) used to return `null` — indistinguishable
- *     from "already installed" or "never attempted at all" on a first-run
- *     machine, the precise false-success shape #184 exists to prevent.
- *  2. (MAJOR) A bundled skill name colliding with a PRE-EXISTING,
- *     marker-less directory the CLI doesn't own. The action set here used
- *     to be computed from `isSkillInstalled` (mere `existsSync`), which
- *     can't tell "we already installed this" from "something else already
- *     lives at this path" — a foreign dir was silently read as "already
- *     installed, nothing to do", so `installSkill`'s ownership-refusal
- *     guard was never even reached and the collision went unreported
- *     anywhere. The action set below is computed from *ownership*
- *     (`getInstalledVersion(...) !== null`) instead, so a foreign
- *     collision is genuinely attempted — hits the same guard `installSkill`
- *     already enforces elsewhere, throws, and is captured below — rather
- *     than silently skipped as if it were a prior trawl install.
- *
- * Whenever there was anything to attempt, the result is now ALWAYS a
- * non-null object reporting both what landed (`installed`) and what didn't
- * (`skipped`, each with a RELAYABLE reason — see `SkillOwnershipRefusalError`
- * above: the ownership-refusal case reports `.relayableReason` [fact only,
- * no `--force` imperative], every other throw [skill-not-found, raw fs
- * errors like EACCES] reports `.message` as before, since those were never
- * imperative to begin with), so `login.ts` can print an honest, distinct
- * line for a skip instead of falling through to the generic "not installed"
- * nudge as if login had done nothing, or silently omitting a name from the
- * success line as if it had never been requested.
- *
- * #184 defect 2 — `error` (present whenever the function returns non-null)
- * distinguishes a THIRD case from both "nothing to do" (`null`) and "one or
- * more skills failed" (`skipped`): "could not even determine what to
- * install" — `listBundledSkills()` returning an empty list (its own
- * contract silently swallows a missing/renamed `skills/` dir into `[]`; see
- * its doc comment) or `getSkillsPackageRoot()` throwing outright (the
- * `@trawlme/skills` package itself unresolvable — a broken node_modules
- * entry). Both used to fall through to `notOwned.length === 0` or the outer
- * catch below, landing on the exact same `null` as a fully-up-to-date
- * install — a genuinely corrupted bundle produced ZERO signal, not even a
- * failed-attempt line, because nothing was ever attempted. `error` is
- * `null` on every ordinary path (including genuine "all already owned",
- * which still short-circuits to the `null` return below) and non-null only
- * for this diagnostic-failure case, where `installed`/`skipped` are both
- * empty because no skill name was ever known to attempt.
- */
 export declare function bootstrapSkillsOnLogin(opts?: {
     json?: boolean;
     isTTY?: boolean;