@hwip/cli 0.0.1 → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+export interface HwipOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+export interface NotifyPayload {
+    title?: string;
+    body?: string;
+    url?: string;
+    type?: 'note' | 'link' | 'file' | 'hook';
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+    targetDeviceId?: string;
+    /** Send to this channel's subscribers instead of to the account's own devices. Plain text — see `HwipHook.notify`. */
+    channelId?: string;
+    sessionId?: string;
+    /** Stable agent-session grouping so a hook/notify joins the agent chat:
+     *  the listener device (per-host) + tmux session name. Auto-filled by
+     *  HwipHook.notify when running inside a tmux agent session. */
+    agentDeviceId?: string;
+    agentSessionName?: string;
+}
+export interface NotifyResult {
+    pushId: string;
+    fileKey?: string;
+    autoFile?: boolean;
+}
+export interface UploadRequestResult {
+    fileId: string;
+    fileKey: string;
+    uploadUrl: string;
+}
+export interface ListParams {
+    limit?: number;
+    type?: 'note' | 'link' | 'file' | 'clipboard' | 'hook';
+}
+export interface PushItem {
+    pushId: string;
+    type: string;
+    title?: string;
+    body?: string;
+    createdAt: string;
+    /** E2E: when true, `title`/`body` are absent and the ciphertext is in `body`. */
+    isEncrypted?: boolean;
+}
+export interface ListResult {
+    pushes: PushItem[];
+    count: number;
+    hasMore: boolean;
+}
+export interface DismissOneResult {
+    dismissed: true;
+}
+export interface DismissAllResult {
+    dismissed: number;
+}
+export interface ApiErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        status: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/uninstall.d.ts

@@ -0,0 +1,55 @@
+import { checkListenerPid, type ListenerStop } from './listener-process.js';
+/** A step line that is not a change made: a `note` is for information, an
+ *  `attention` line is something only the user can finish. */
+export type Notice = {
+    readonly notice: 'note' | 'attention';
+    readonly text: string;
+};
+type StepLine = string | Notice;
+/** Remove just the `hwip` entry from an MCP registry JSON file. `key` is the
+ *  container: `mcpServers` for Cursor/Windsurf, top-level `mcp` for
+ *  opencode.json (opencode's own schema). Exported for tests. */
+export declare const rmMcpEntry: (filePath: string, dry: boolean, key?: string) => StepLine | null;
+/** Remove `[mcp_servers.hwip]` from codex's TOML config, leaving the rest of
+ *  the user's file byte-for-byte. Exported for tests. */
+export declare const rmCodexMcpEntry: (filePath: string, dry: boolean) => StepLine | null;
+/** Strip the <!-- HWIP:START/END --> block from a shared rule file. Exported for tests. */
+export declare const stripManagedRule: (filePath: string, dry: boolean) => string | null;
+/** Drop the Hwip `read:` directive from ~/.aider.conf.yml. */
+/** Exported for tests. */
+export declare const rmAiderReadDirective: (confPath: string, dry: boolean) => string | null;
+/** Remove just the hwip-written entries from Gemini's settings.json.
+ *  Exported for tests (gemini is PATH-detected, so the full-uninstall
+ *  suite can't reach this deterministically). */
+export declare const rmGeminiHook: (filePath: string, dry: boolean) => StepLine | null;
+/** Remove the hwip-written entries from a hooks.json (Codex, Cursor,
+ *  Windsurf). The file is usually hwip-born, so it is deleted outright when
+ *  nothing but hwip's entries and Cursor's `version` was in it — hooks and keys
+ *  the user added survive. Exported for tests (codex is PATH-detected, same as
+ *  gemini). */
+export declare const rmHwipHooks: (filePath: string, dry: boolean) => StepLine | null;
+/**
+ * Remove the login-time service (LaunchAgent or systemd user unit), if one is installed.
+ *
+ * Async, so it does not fit the sync `Step` shape the per-agent uninstallers
+ * use — the service manager has to be waited on. Returns the same "one line or null"
+ * contract those steps do.
+ */
+export declare const removeServiceStep: (dry: boolean) => Promise<StepLine | null>;
+export interface ListenerStopDeps {
+    readonly runningListenerPid: () => number | null;
+    readonly checkListenerPid: typeof checkListenerPid;
+    readonly stopListener: (pid: number) => Promise<ListenerStop>;
+}
+export declare const defaultListenerStopDeps: ListenerStopDeps;
+/**
+ * Stop the listener daemon. `hwip cc` starts it without the login-time
+ * service, so removing the service alone leaves it running — and it is what
+ * carries phone input into tmux. `stopListener` only stops a process whose
+ * command line is hwip's listener; this turns what it found into one line.
+ * Same "one line or null" contract as the removal primitives.
+ */
+export declare const stopListenerStep: (dry: boolean, deps?: ListenerStopDeps) => Promise<StepLine | null>;
+export declare const handleUninstall: (args: Record<string, string | boolean>, listenerDeps?: ListenerStopDeps, confirm?: (message: string) => Promise<boolean>) => Promise<number>;
+export {};
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/uninstall.js

@@ -0,0 +1,507 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleUninstall = exports.stopListenerStep = exports.defaultListenerStopDeps = exports.removeServiceStep = exports.rmHwipHooks = exports.rmGeminiHook = exports.rmAiderReadDirective = exports.stripManagedRule = exports.rmCodexMcpEntry = exports.rmMcpEntry = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const agents_js_1 = require("./agents.js");
+const listener_process_js_1 = require("./listener-process.js");
+const listener_service_js_1 = require("./listener-service.js");
+const templates_js_1 = require("./templates.js");
+const config_js_1 = require("./config.js");
+const codex_config_js_1 = require("./codex-config.js");
+const replace_file_js_1 = require("./replace-file.js");
+const jsonc_doc_js_1 = require("./jsonc-doc.js");
+const args_js_1 = require("./args.js");
+const HOME = (0, os_1.homedir)();
+const ok = (msg) => console.log(`    + ${msg}`);
+const skip = (msg) => console.log(`    - ${msg}`);
+let attentionLines = 0;
+const report = (line) => {
+    if (typeof line === 'string')
+        return ok(line);
+    if (line.notice === 'note')
+        return skip(line.text);
+    attentionLines += 1;
+    console.log(`    ! ${line.text}`);
+};
+// ── Removal primitives ───────────────────────────────────────────
+// Each primitive returns a short human description of what it did (or
+// would do, in dry-run), or null when there was nothing to remove. A JSON
+// file it could not read gets an `attention` line (`unreadable`), so the user
+// knows to look at it: whatever of hwip's is in there stays and keeps working.
+/** Past/conditional verb so dry-run output reads honestly. */
+const verb = (dry) => (dry ? 'would remove' : 'removed');
+/** Delete a file Hwip fully owns. */
+const rmFile = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    if (!dry)
+        (0, fs_1.rmSync)(filePath, { force: true });
+    return `${verb(dry)} ${filePath}`;
+};
+/**
+ * Is the file reached through a symlink — itself, or a folder on the way from the home folder (`~/.cursor`
+ * linked into a dotfiles repo)? Folders above the home folder are not looked at: a home folder under a
+ * linked parent (macOS's /var) says nothing about where the user keeps their files.
+ */
+const isLinked = (filePath) => {
+    const rel = (0, path_1.relative)(HOME, filePath);
+    const parts = rel.startsWith('..') || (0, path_1.isAbsolute)(rel) ? [''] : rel.split(path_1.sep);
+    let at = rel.startsWith('..') || (0, path_1.isAbsolute)(rel) ? filePath : HOME;
+    for (const part of parts) {
+        at = part ? (0, path_1.join)(at, part) : at;
+        if ((0, fs_1.lstatSync)(at, { throwIfNoEntry: false })?.isSymbolicLink() === true)
+            return true;
+    }
+    return false;
+};
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** A settings file opened as the installer opens it (comments and trailing
+ *  commas allowed, an empty or BOM-led file read the same way), or null when it
+ *  does not parse or parses to something else (`null`, an array) that has no
+ *  entries to look in. */
+const openSettings = (filePath) => {
+    let text;
+    try {
+        text = (0, replace_file_js_1.readText)(filePath);
+    }
+    catch (err) {
+        // Bytes that are not text are named as that (the step runner prints the throw), not as "not a JSON object".
+        if (err instanceof replace_file_js_1.NotUtf8Error)
+            throw err;
+        return null;
+    }
+    try {
+        return new jsonc_doc_js_1.JsoncDoc(text);
+    }
+    catch {
+        return null;
+    }
+};
+/** The `!` line for an edit that would lose a comment of the user's: the file is left as it is. */
+const uneditable = (filePath, what) => ({
+    notice: 'attention',
+    text: `could not edit ${filePath} without risking its comments — remove hwip's ${what} by hand`,
+});
+/** Run an edit of a settings file; a `JsoncEditError` becomes the `!` line that names the file. */
+const editing = (filePath, what, edit) => {
+    try {
+        return edit();
+    }
+    catch (err) {
+        if (err instanceof jsonc_doc_js_1.JsoncEditError)
+            return uneditable(filePath, what);
+        throw err;
+    }
+};
+/** The `!` line for a settings file that exists but is not a JSON object. */
+const unreadable = (filePath, what) => ({
+    notice: 'attention',
+    text: `could not read ${filePath} as a JSON object — if hwip's ${what} is in it, remove it by hand`,
+});
+/** Remove just the `hwip` entry from an MCP registry JSON file. `key` is the
+ *  container: `mcpServers` for Cursor/Windsurf, top-level `mcp` for
+ *  opencode.json (opencode's own schema). Exported for tests. */
+const rmMcpEntry = (filePath, dry, key = 'mcpServers') => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    const doc = openSettings(filePath);
+    if (!doc)
+        return unreadable(filePath, 'MCP entry');
+    const servers = doc.data[key];
+    if (!isPlainObject(servers) || !('hwip' in servers))
+        return null;
+    return editing(filePath, 'MCP entry', () => {
+        if (!dry) {
+            doc.remove([key, 'hwip']);
+            (0, replace_file_js_1.replaceFile)(filePath, doc.text(), doc.expected);
+        }
+        return `${verb(dry)} hwip from ${filePath}`;
+    });
+};
+exports.rmMcpEntry = rmMcpEntry;
+/** Remove `[mcp_servers.hwip]` from codex's TOML config, leaving the rest of
+ *  the user's file byte-for-byte. Exported for tests. */
+const rmCodexMcpEntry = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    let config;
+    try {
+        config = (0, replace_file_js_1.readText)(filePath);
+    }
+    catch (err) {
+        // A table left in a file hwip cannot read keeps launching its server: say so.
+        if (err instanceof replace_file_js_1.NotUtf8Error)
+            return { notice: 'attention', text: `${err.message} — if hwip's MCP table is in it, remove it by hand` };
+        return null;
+    }
+    const stripped = (0, codex_config_js_1.removeHwipMcpTable)(config);
+    if (stripped === null)
+        return null;
+    if (!dry)
+        (0, replace_file_js_1.replaceFile)(filePath, stripped, config);
+    return `${verb(dry)} hwip from ${filePath}`;
+};
+exports.rmCodexMcpEntry = rmCodexMcpEntry;
+/** Strip the <!-- HWIP:START/END --> block from a shared rule file. Exported for tests. */
+const stripManagedRule = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    const existing = (0, replace_file_js_1.readText)(filePath);
+    const stripped = (0, templates_js_1.removeManagedBlock)(existing);
+    if (stripped === existing)
+        return null; // no Hwip block present
+    if (!dry) {
+        // A file that was ours alone goes — but a symlink into a dotfiles repo is not ours to delete: the block comes out of what it points at.
+        if (stripped.trim() === '' && !isLinked(filePath)) {
+            (0, replace_file_js_1.removeFile)(filePath, existing);
+        }
+        else {
+            (0, replace_file_js_1.replaceFile)(filePath, stripped, existing);
+        }
+    }
+    return `${verb(dry)} Hwip block from ${filePath}`;
+};
+exports.stripManagedRule = stripManagedRule;
+/** Drop the Hwip `read:` directive from ~/.aider.conf.yml. */
+/** Exported for tests. */
+const rmAiderReadDirective = (confPath, dry) => {
+    if (!(0, fs_1.existsSync)(confPath))
+        return null;
+    const conf = (0, replace_file_js_1.readText)(confPath);
+    if (!conf.includes('# Added by Hwip'))
+        return null;
+    // Drop the "# Added by Hwip" line and the "read:" line that follows it.
+    const lines = conf.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === '# Added by Hwip') {
+            if (lines[i + 1]?.trimStart().startsWith('read:'))
+                i++; // skip read: too
+            continue;
+        }
+        out.push(lines[i]);
+    }
+    if (!dry)
+        (0, replace_file_js_1.replaceFile)(confPath, out.join('\n').replace(/\n{3,}/g, '\n\n'), conf);
+    return `${verb(dry)} Hwip read: directive from ${confPath}`;
+};
+exports.rmAiderReadDirective = rmAiderReadDirective;
+/**
+ * Take hwip-written entries — matcher groups or flat handlers — out of the
+ * document's `hooks` (all events).
+ * Edits `doc` unless dry; returns true when anything of ours was found.
+ * Empty events are deleted so a clean file stays clean (an event that holds a
+ * comment of the user's stays, emptied). The rest of the file,
+ * comments included, is left as it is (a comment right next to one of hwip's
+ * entries goes with it).
+ */
+const stripHwipHookGroups = (doc, dry) => {
+    const hooks = doc.data.hooks;
+    if (!isPlainObject(hooks))
+        return false;
+    let removed = false;
+    for (const event of Object.keys(hooks)) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        const ours = groups.flatMap((group, i) => ((0, templates_js_1.isHwipHookGroup)(group) ? [i] : []));
+        if (ours.length === 0)
+            continue; // nothing of ours
+        removed = true;
+        if (dry)
+            continue;
+        // The whole event goes only when that takes no comment with it; otherwise its groups go one by one and the key stays.
+        if (ours.length === groups.length && !doc.removalTakesComment(['hooks', event]))
+            doc.remove(['hooks', event]);
+        else
+            for (const i of ours.reverse())
+                doc.remove(['hooks', event, i]);
+    }
+    return removed;
+};
+/** Remove just the hwip-written entries from Gemini's settings.json.
+ *  Exported for tests (gemini is PATH-detected, so the full-uninstall
+ *  suite can't reach this deterministically). */
+const rmGeminiHook = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    const doc = openSettings(filePath);
+    if (!doc)
+        return unreadable(filePath, 'hook');
+    return editing(filePath, 'hook', () => {
+        if (!stripHwipHookGroups(doc, dry))
+            return null;
+        if (!dry)
+            (0, replace_file_js_1.replaceFile)(filePath, doc.text(), doc.expected);
+        return `${verb(dry)} hwip hooks from ${filePath}`;
+    });
+};
+exports.rmGeminiHook = rmGeminiHook;
+/** Remove the hwip-written entries from a hooks.json (Codex, Cursor,
+ *  Windsurf). The file is usually hwip-born, so it is deleted outright when
+ *  nothing but hwip's entries and Cursor's `version` was in it — hooks and keys
+ *  the user added survive. Exported for tests (codex is PATH-detected, same as
+ *  gemini). */
+const rmHwipHooks = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    const doc = openSettings(filePath);
+    // Not silent: a hook left in an unreadable file keeps firing after
+    // uninstall, and the user is the only one who can take it out.
+    if (!doc)
+        return unreadable(filePath, 'hook');
+    return editing(filePath, 'hook', () => {
+        if (!stripHwipHookGroups(doc, dry))
+            return null;
+        if (!dry) {
+            const data = doc.data;
+            const hooks = isPlainObject(data.hooks) ? data.hooks : {};
+            const userKeys = Object.keys(data).filter((key) => key !== 'hooks' && key !== 'version');
+            // A comment is the user's too: a file that holds one is kept.
+            const onlyHwip = Object.keys(hooks).length === 0 && userKeys.length === 0 && !doc.hasComments();
+            // A symlink into a dotfiles repo is not ours to delete: hwip's hooks come out of what it points at,
+            // or they come back, and run, when the link is made again.
+            if (onlyHwip && !isLinked(filePath) && doc.expected !== null)
+                (0, replace_file_js_1.removeFile)(filePath, doc.expected);
+            else
+                (0, replace_file_js_1.replaceFile)(filePath, doc.text(), doc.expected);
+        }
+        return `${verb(dry)} hwip hooks from ${filePath}`;
+    });
+};
+exports.rmHwipHooks = rmHwipHooks;
+// A step that throws (a write the directory refuses) is one line, not the end
+// of the uninstall: the steps after it still have hwip's parts to take out.
+const runStep = (step) => {
+    try {
+        return step();
+    }
+    catch (err) {
+        return { notice: 'attention', text: `could not finish: ${err instanceof Error ? err.message : String(err)}` };
+    }
+};
+const runSteps = (steps) => {
+    let did = false;
+    for (const step of steps) {
+        const result = runStep(step);
+        if (result) {
+            report(result);
+            did = true;
+        }
+    }
+    if (!did)
+        skip('nothing to remove');
+};
+const AGENT_UNINSTALLERS = {
+    claude: (dry) => {
+        if (dry) {
+            skip('would run: claude plugin uninstall hwip@hwip');
+            return;
+        }
+        try {
+            (0, child_process_1.execSync)('claude plugin uninstall hwip@hwip', { stdio: 'pipe' });
+            ok('plugin uninstalled');
+        }
+        catch {
+            skip('plugin not installed (or claude CLI unavailable)');
+        }
+    },
+    cursor: (dry) => runSteps([
+        () => (0, exports.rmMcpEntry)((0, path_1.join)(HOME, '.cursor', 'mcp.json'), dry),
+        () => (0, exports.rmHwipHooks)((0, path_1.join)(HOME, '.cursor', 'hooks.json'), dry),
+        () => rmFile((0, path_1.join)(HOME, '.cursor', 'rules', 'hwip.mdc'), dry),
+    ]),
+    windsurf: (dry) => runSteps([
+        () => (0, exports.rmMcpEntry)((0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), dry),
+        () => (0, exports.rmHwipHooks)((0, path_1.join)(HOME, '.codeium', 'windsurf', 'hooks.json'), dry),
+        () => (0, exports.stripManagedRule)((0, path_1.join)(HOME, '.codeium', 'windsurf', 'memories', 'global_rules.md'), dry),
+    ]),
+    gemini: (dry) => {
+        if (!dry) {
+            // user scope first (where the ≥0.26 installer adds it), then the
+            // legacy scope-less form for entries created by older installs.
+            try {
+                (0, child_process_1.execSync)('gemini mcp remove -s user hwip', { stdio: 'pipe' });
+                ok('MCP server removed');
+            }
+            catch {
+                try {
+                    (0, child_process_1.execSync)('gemini mcp remove hwip', { stdio: 'pipe' });
+                    ok('MCP server removed');
+                }
+                catch {
+                    skip('gemini MCP entry not found');
+                }
+            }
+        }
+        else {
+            skip('would run: gemini mcp remove -s user hwip');
+        }
+        runSteps([
+            () => (0, exports.rmGeminiHook)((0, path_1.join)(HOME, '.gemini', 'settings.json'), dry),
+            () => (0, exports.stripManagedRule)((0, path_1.join)(HOME, '.gemini', 'GEMINI.md'), dry),
+        ]);
+    },
+    codex: (dry) => runSteps([
+        () => (0, exports.rmHwipHooks)((0, path_1.join)(HOME, '.codex', 'hooks.json'), dry),
+        () => (0, exports.stripManagedRule)((0, path_1.join)(HOME, '.codex', 'AGENTS.md'), dry),
+        () => (0, exports.rmCodexMcpEntry)((0, path_1.join)(HOME, '.codex', 'config.toml'), dry),
+    ]),
+    copilot: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.copilot', 'hooks', 'hwip.json'), dry),
+        () => rmFile((0, path_1.join)(HOME, '.copilot', 'instructions', 'hwip.instructions.md'), dry),
+    ]),
+    cline: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.cline', 'rules', 'hwip.md'), dry),
+    ]),
+    aider: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.hwip', 'aider-conventions.md'), dry),
+        () => (0, exports.rmAiderReadDirective)((0, path_1.join)(HOME, '.aider.conf.yml'), dry),
+    ]),
+    pi: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.pi', 'agent', 'extensions', 'hwip.ts'), dry),
+        () => (0, exports.stripManagedRule)((0, path_1.join)(HOME, '.pi', 'agent', 'AGENTS.md'), dry),
+    ]),
+    opencode: (dry) => runSteps([
+        () => (0, exports.rmMcpEntry)((0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), dry, 'mcp'),
+        () => rmFile((0, path_1.join)(HOME, '.config', 'opencode', 'plugins', 'hwip.ts'), dry),
+        () => (0, exports.stripManagedRule)((0, path_1.join)(HOME, '.config', 'opencode', 'AGENTS.md'), dry),
+    ]),
+};
+/**
+ * Remove the login-time service (LaunchAgent or systemd user unit), if one is installed.
+ *
+ * Async, so it does not fit the sync `Step` shape the per-agent uninstallers
+ * use — the service manager has to be waited on. Returns the same "one line or null"
+ * contract those steps do.
+ */
+const removeServiceStep = async (dry) => {
+    if (!(0, listener_service_js_1.serviceInstalled)())
+        return null;
+    if (dry)
+        return `would remove the login-time service (${listener_service_js_1.SERVICE_LABEL})`;
+    const result = await (0, listener_service_js_1.uninstallService)();
+    if (!result.ok)
+        return { notice: 'attention', text: `could not remove the login-time service: ${result.reason}` };
+    return `removed the login-time service (${listener_service_js_1.SERVICE_LABEL})`;
+};
+exports.removeServiceStep = removeServiceStep;
+exports.defaultListenerStopDeps = {
+    runningListenerPid: listener_process_js_1.runningListenerPid,
+    checkListenerPid: (pid) => (0, listener_process_js_1.checkListenerPid)(pid),
+    stopListener: (pid) => (0, listener_process_js_1.stopListener)(pid),
+};
+/**
+ * Stop the listener daemon. `hwip cc` starts it without the login-time
+ * service, so removing the service alone leaves it running — and it is what
+ * carries phone input into tmux. `stopListener` only stops a process whose
+ * command line is hwip's listener; this turns what it found into one line.
+ * Same "one line or null" contract as the removal primitives.
+ */
+const stopListenerStep = async (dry, deps = exports.defaultListenerStopDeps) => {
+    const pid = deps.runningListenerPid();
+    if (pid === null)
+        return null;
+    const outcome = dry ? deps.checkListenerPid(pid) : await deps.stopListener(pid);
+    switch (outcome.kind) {
+        case 'gone':
+            return null;
+        case 'unchecked':
+            return {
+                notice: 'attention',
+                text: `could not check pid ${pid} (${outcome.reason}) — if it is the listener, run: hwip listener --stop`,
+            };
+        case 'foreign':
+            return { notice: 'note', text: `left pid ${pid} alone: the listener's pid file points at another process (${outcome.program})` };
+        case 'other-listener':
+            return { notice: 'attention', text: (0, listener_process_js_1.otherListenerNote)(pid, outcome.script) };
+        case 'ours':
+            return `would stop the listener (pid ${pid})`;
+        case 'stopped':
+            return `stopped the listener (pid ${pid})`;
+        case 'killed':
+            return `stopped the listener (pid ${pid}) with SIGKILL`;
+    }
+};
+exports.stopListenerStep = stopListenerStep;
+// ── Entry point ──────────────────────────────────────────────────
+const closingLine = (dry, attention) => {
+    const lines = attention === 1 ? '1 line marked "!" needs' : `${attention} lines marked "!" need`;
+    if (dry) {
+        const tail = attention === 0 ? '' : ` ${lines} you.`;
+        return `\n  Dry-run complete — nothing was changed.${tail}\n`;
+    }
+    if (attention === 0)
+        return '\n  Uninstall complete. Restart your agents.\n';
+    return `\n  Uninstall finished, but ${lines} you. Then restart your agents.\n`;
+};
+/** Yes/no at the terminal; Ctrl-C is a no. */
+const askConfirm = async (message) => {
+    try {
+        const { confirm } = await import('@inquirer/prompts');
+        return await confirm({ message, default: false });
+    }
+    catch {
+        return false;
+    }
+};
+const handleUninstall = async (args, listenerDeps = exports.defaultListenerStopDeps, confirm = askConfirm) => {
+    const dry = (0, args_js_1.flagOn)(args, 'dry-run');
+    const purge = (0, args_js_1.flagOn)(args, 'purge');
+    attentionLines = 0;
+    console.log(`\n  Hwip uninstall${dry ? ' (dry-run)' : ''} — v${config_js_1.VERSION}\n`);
+    const detected = (0, agents_js_1.detectAgents)().filter((a) => a.detected);
+    // A real removal asks first when someone is at the terminal. `--yes`
+    // skips the question; a script has no terminal to ask on and runs as it
+    // always did. `--dry-run` changes nothing, so it never asks.
+    if (!dry && !(0, args_js_1.flagOn)(args, 'yes') && process.stdin.isTTY === true) {
+        const agents = detected.map((a) => a.name).join(', ') || 'no detected agents';
+        const go = await confirm(`Remove Hwip from ${agents} and stop the listener? (--dry-run previews it)`);
+        if (!go) {
+            console.log('\n  Cancelled — nothing was changed.\n');
+            // Not 0: a caller can tell "removed" from "said no".
+            return 1;
+        }
+    }
+    if (detected.length === 0) {
+        console.log('  No supported agents detected.\n');
+    }
+    for (const agent of detected) {
+        console.log(`  ${agent.name}:`);
+        AGENT_UNINSTALLERS[agent.id]?.(dry);
+    }
+    // The LaunchAgent outlives every agent's rules, so removing it is part of
+    // uninstall and not of any one agent's teardown.
+    console.log('\n  Login-time service:');
+    const serviceLine = await (0, exports.removeServiceStep)(dry);
+    if (serviceLine)
+        report(serviceLine);
+    else
+        skip('not installed');
+    // After the service: its bootout already stops a service-run daemon.
+    console.log('\n  Listener:');
+    const listenerLine = await (0, exports.stopListenerStep)(dry, listenerDeps);
+    if (listenerLine)
+        report(listenerLine);
+    else
+        skip('not running');
+    // ~/.hwip/config.json holds the API key — kept by default so a
+    // re-install doesn't need the key re-entered. --purge removes it.
+    console.log('\n  Config:');
+    if (purge) {
+        const removed = rmFile(config_js_1.CONFIG_FILE, dry);
+        if (removed)
+            ok(removed);
+        else
+            skip('no config file');
+    }
+    else {
+        skip(`kept ${config_js_1.CONFIG_FILE} (pass --purge to remove)`);
+    }
+    console.log(closingLine(dry, attentionLines));
+    return 0;
+};
+exports.handleUninstall = handleUninstall;

package/dist/usage.d.ts

@@ -0,0 +1,17 @@
+export declare const usageText: () => string;
+/**
+ * The short usage of one command: its entry from the full text, its options
+ * section if it has one, and the global options. Null for a word that is not a
+ * command, which the caller answers with the full usage.
+ *
+ * Every agent subcommand (`cc`, `codex`, …) shares the paragraph the full text
+ * prints once under the last of them, so each gets it.
+ */
+export declare const commandUsage: (command: string) => string | null;
+/**
+ * Which command a request for usage is about: `hwip notify --help` and
+ * `hwip --help cc` name it, `hwip help notify` names it as its argument, and
+ * `hwip` or `hwip help` alone name none.
+ */
+export declare const usageTarget: (args: Readonly<Record<string, string | boolean>>) => string;
+//# sourceMappingURL=usage.d.ts.map