@hwip/cli 0.0.1 → 0.1.1

package/dist/login.js

@@ -0,0 +1,388 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleLogin = exports.runLoginFlow = exports.resolveTimeoutSec = exports.resolveAllowHosts = exports.resolveWebUrl = exports.openBrowser = exports.browserPlan = exports.MAX_CALLBACK_BODY_BYTES = exports.parseCallback = exports.MAX_STATE_MISMATCHES = exports.parseCallbackParams = exports.persistConfig = exports.buildBridgeUrl = exports.stripUndefined = void 0;
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_child_process_1 = require("node:child_process");
+const node_readline_1 = require("node:readline");
+const config_js_1 = require("./config.js");
+const login_address_js_1 = require("./login-address.js");
+const login_page_js_1 = require("./login-page.js");
+const redact_js_1 = require("./redact.js");
+const DEFAULT_WEB_URL = 'https://console.hwip.app';
+const DEFAULT_TIMEOUT_SEC = 300;
+// ── Pure helpers (unit-tested) ───────────────────────────────────
+const stripUndefined = (obj) => {
+    const out = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+};
+exports.stripUndefined = stripUndefined;
+/**
+ * `post=1` tells the console this listener takes the callback as a form POST:
+ * the key then travels in the request body and never in a URL (browser history,
+ * autofill and session restore keep URLs). `/cb` takes no key any other way.
+ */
+const buildBridgeUrl = (webUrl, port, state, host) => {
+    const base = webUrl.replace(/\/+$/, '');
+    const params = new URLSearchParams({ port: String(port), state, host, post: '1' });
+    return `${base}/auth/cli-bridge?${params.toString()}`;
+};
+exports.buildBridgeUrl = buildBridgeUrl;
+const persistConfig = (next) => {
+    const existing = (0, config_js_1.loadConfig)();
+    (0, config_js_1.saveConfig)({ ...existing, ...(0, exports.stripUndefined)(next) });
+};
+exports.persistConfig = persistConfig;
+/**
+ * The callback's fields, from a form body (the only place the key may be). The `baseUrl` and `wsUrl` it names are
+ * where `config.json` will send the key, so one that is not https/wss on a host hwip knows (`login-address.ts`) is
+ * refused whole — nothing is saved — and ends the login saying which address and why (C131).
+ * `extraHosts`: hosts besides `hwip.app` the callback may name (the console's, those already in the config).
+ */
+const parseCallbackParams = (params, expectedState, extraHosts = []) => {
+    const state = params.get('state');
+    if (state !== expectedState)
+        return { ok: false, status: 403, reason: 'state mismatch' };
+    const apiKey = params.get('key') ?? undefined;
+    if (!apiKey)
+        return { ok: false, status: 400, reason: 'missing key' };
+    const baseUrl = params.get('baseUrl') ?? undefined;
+    const wsUrl = params.get('wsUrl') ?? undefined;
+    for (const [field, value] of [['baseUrl', baseUrl], ['wsUrl', wsUrl]]) {
+        if (value === undefined)
+            continue;
+        const problem = (0, login_address_js_1.callbackAddressProblem)(field, value, extraHosts);
+        if (problem) {
+            return {
+                ok: false,
+                status: 400,
+                reason: 'the console sent an address hwip will not save',
+                endsLogin: `${problem}, so the sign-in was not saved. Check the console you signed in at (--web-url), or name a host you trust with --allow-host <host>, and run \`hwip login\` again`,
+            };
+        }
+    }
+    return { ok: true, config: { apiKey, hookId: params.get('hook') ?? undefined, baseUrl, wsUrl } };
+};
+exports.parseCallbackParams = parseCallbackParams;
+/** Requests with a wrong state one login answers 403 and waits through, before it gives up. */
+exports.MAX_STATE_MISMATCHES = 5;
+const KEY_IN_URL = 'the console sent the key in a URL, which hwip refuses, so it was not saved. That URL is in the browser\'s history: ' +
+    'revoke the key in the app (Settings > API Keys), update the console, and run `hwip login` again';
+/**
+ * A GET callback. It carries no key: the console's "cancel" is one (`?error=denied&state=…`) and answers "missing
+ * key". A key in the query is refused unread (C102) and ends the login with `KEY_IN_URL`; its value is not in the
+ * result, the page or the log.
+ */
+const parseCallback = (reqUrl, expectedState) => {
+    const url = new URL(reqUrl, 'http://127.0.0.1');
+    if (url.pathname !== '/cb')
+        return { ok: false, status: 404, reason: 'not found' };
+    if (url.searchParams.get('state') !== expectedState)
+        return { ok: false, status: 403, reason: 'state mismatch' };
+    if (url.searchParams.has('key'))
+        return { ok: false, status: 400, reason: 'a key in the URL is refused', endsLogin: KEY_IN_URL };
+    return { ok: false, status: 400, reason: 'missing key' };
+};
+exports.parseCallback = parseCallback;
+/** A form with five short fields is well under this; the cap is for whatever else can reach a loopback port. */
+exports.MAX_CALLBACK_BODY_BYTES = 8 * 1024;
+const FORM_TYPE = 'application/x-www-form-urlencoded';
+/** The body of a callback POST, or the status to refuse it with. */
+const readCallbackBody = (req) => {
+    const type = (req.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase();
+    if (type !== FORM_TYPE)
+        return Promise.resolve({ status: 415, reason: 'unsupported content type' });
+    return new Promise((resolve) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > exports.MAX_CALLBACK_BODY_BYTES) {
+                resolve({ status: 413, reason: 'request too large' });
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve({ body: Buffer.concat(chunks).toString('utf-8') }));
+        // The browser went away before the body ended: nothing to answer, but the wait must not outlive the socket.
+        req.on('close', () => resolve({ status: 400, reason: 'unreadable request' }));
+    });
+};
+// ── Browser launch ───────────────────────────────────────────────
+const browserCommand = () => {
+    if (process.platform === 'darwin')
+        return { cmd: 'open', prefixArgs: [] };
+    if (process.platform === 'win32')
+        return { cmd: 'cmd', prefixArgs: ['/c', 'start', ''] };
+    return { cmd: 'xdg-open', prefixArgs: [] };
+};
+const browserPlan = (env = process.env, platform = process.platform) => {
+    // A $BROWSER helper opens it where the user is — VS Code Remote-SSH sets one
+    // and forwards the loopback port — and WSL opens the Windows browser, which
+    // shares localhost.
+    if (env.BROWSER)
+        return { kind: 'open' };
+    if (env.SSH_CONNECTION || env.SSH_TTY)
+        return { kind: 'ssh' };
+    if (platform !== 'darwin' && platform !== 'win32' && !env.WSL_DISTRO_NAME && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+        return { kind: 'none', reason: 'no display (DISPLAY and WAYLAND_DISPLAY are unset)' };
+    }
+    return { kind: 'open' };
+};
+exports.browserPlan = browserPlan;
+/** How long an opener has to fail before it counts as started. */
+const OPENER_GRACE_MS = 1500;
+/**
+ * Opens `url`; resolves to why it could not, or undefined once the opener
+ * started. An opener that exits non-zero inside the grace window failed —
+ * `xdg-open` with no handler exits 3 — and one still running after it, or
+ * done with 0, handed the URL on.
+ */
+const openBrowser = (url, graceMs = OPENER_GRACE_MS) => {
+    const { cmd, prefixArgs } = browserCommand();
+    return new Promise((resolve) => {
+        try {
+            const child = (0, node_child_process_1.spawn)(cmd, [...prefixArgs, url], { stdio: 'ignore', detached: true });
+            // A missing `xdg-open` fails here, after spawn() returned.
+            child.once('error', (err) => resolve(`${cmd} failed: ${err.message}`));
+            child.once('spawn', () => {
+                const grace = setTimeout(() => {
+                    child.unref();
+                    resolve(undefined);
+                }, graceMs);
+                child.once('exit', (code) => {
+                    clearTimeout(grace);
+                    resolve(code ? `${cmd} exited with code ${code}` : undefined);
+                });
+            });
+        }
+        catch (err) {
+            resolve(`${cmd} failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+};
+exports.openBrowser = openBrowser;
+/**
+ * Inside `hwip install`, Enter skips the wait and goes to the paste prompt —
+ * and a key pasted right here, before Enter, is that answer. Resolves to the
+ * typed line. Null without a terminal to read it from.
+ */
+const enterToSkip = () => {
+    if (process.stdin.isTTY !== true)
+        return null;
+    const rl = (0, node_readline_1.createInterface)({ input: process.stdin });
+    const pressed = new Promise((resolve) => rl.once('line', (line) => resolve(line.trim())));
+    return { pressed, close: () => rl.close() };
+};
+// ── Loopback server ──────────────────────────────────────────────
+const respond = (res, status, body) => {
+    res.writeHead(status, {
+        'content-type': 'text/html; charset=utf-8',
+        // The page is inline styles and an inline drawing, nothing else: let the
+        // browser refuse anything more. What got here carries the new key (in the
+        // body), so it is not cached and not sent on as a referrer.
+        'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'",
+        'cache-control': 'no-store',
+        'referrer-policy': 'no-referrer',
+    });
+    res.end(body);
+};
+const startLoopbackServer = (state, extraHosts) => {
+    let mismatches = 0;
+    let settle;
+    let fail;
+    const done = new Promise((res, rej) => {
+        settle = res;
+        fail = rej;
+    });
+    const server = (0, node_http_1.createServer)((req, res) => {
+        // A handler that rejects would end the process; whatever slipped past the checks inside ends the login instead.
+        handleCallback(req, res).catch((err) => {
+            if (!res.headersSent)
+                respond(res, 500, (0, login_page_js_1.errorPage)('The sign-in could not be completed. Return to your terminal for the reason.'));
+            fail(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+    const handleCallback = async (req, res) => {
+        let result;
+        if (req.method === 'POST') {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            // The key is in the body: the query of a POST is not read.
+            if (url.pathname !== '/cb') {
+                result = { ok: false, status: 404, reason: 'not found' };
+            }
+            else {
+                const read = await readCallbackBody(req);
+                result = 'body' in read
+                    ? (0, exports.parseCallbackParams)(new URLSearchParams(read.body), state, extraHosts)
+                    : { ok: false, status: read.status, reason: read.reason };
+            }
+        }
+        else {
+            result = (0, exports.parseCallback)(req.url ?? '/', state);
+        }
+        if (!result.ok) {
+            respond(res, result.status, (0, login_page_js_1.errorPage)(result.reason));
+            // A request that does not hold the state is not the console's: it is answered and the wait goes on, so one stray
+            // request cannot end the sign-in. A run of them can (the state is a secret only the console has).
+            if (result.status === 403 && ++mismatches >= exports.MAX_STATE_MISMATCHES) {
+                fail(new Error(`state mismatch — refused after ${exports.MAX_STATE_MISMATCHES} requests that did not hold the sign-in state`));
+            }
+            else if (result.endsLogin)
+                fail(new Error(result.endsLogin));
+            return;
+        }
+        // A handler that throws takes the process down with it. The file can have gone bad since `handleLogin` looked.
+        try {
+            (0, exports.persistConfig)(result.config);
+        }
+        catch (err) {
+            respond(res, 500, (0, login_page_js_1.errorPage)('The key could not be saved. Return to your terminal for the reason.'));
+            fail(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        respond(res, 200, (0, login_page_js_1.okPage)());
+        settle(result.config);
+    };
+    return new Promise((resolveHandle, rejectHandle) => {
+        server.once('error', rejectHandle);
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            resolveHandle({ port, done, close: () => server.close() });
+        });
+    });
+};
+// ── Command ──────────────────────────────────────────────────────
+// The loopback server closes with the attempt, so the bridge URL is no use
+// after this: the way forward is the manual flow — or, inside `hwip install`,
+// the paste prompt that follows.
+const headlessHint = (reason, pasteNext) => {
+    console.error(`\n  Could not open a browser: ${reason}.`);
+    console.error(pasteNext ? '  Paste the API key below instead.\n' : `  Use the manual flow instead:\n${MANUAL_FLOW}\n`);
+};
+const MANUAL_FLOW = '    npx @hwip/cli install --key ak_… --hook hook_…';
+const resolveWebUrl = (raw) => typeof raw === 'string' ? raw : DEFAULT_WEB_URL;
+exports.resolveWebUrl = resolveWebUrl;
+/** The hosts `--allow-host` adds to the callback's trusted ones. A bad value stops the command — it is not read as "none". */
+const resolveAllowHosts = (raw) => {
+    const parsed = (0, login_address_js_1.parseAllowHosts)(raw);
+    if ('error' in parsed)
+        throw new Error(parsed.error);
+    return parsed.hosts;
+};
+exports.resolveAllowHosts = resolveAllowHosts;
+const resolveTimeoutSec = (raw) => {
+    if (typeof raw !== 'string')
+        return DEFAULT_TIMEOUT_SEC;
+    const n = Number(raw);
+    // Reject NaN / non-positive — a bad --timeout must not fire setTimeout instantly.
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_SEC;
+};
+exports.resolveTimeoutSec = resolveTimeoutSec;
+/**
+ * Core login flow shared by `handleLogin` (CLI command) and `handleInstall`
+ * (auto-trigger on missing credentials). Returns the issued credentials, or
+ * null when the browser can't open (headless) or the callback never arrives.
+ * `deps.open` is injectable for tests; defaults to the real browser launcher.
+ */
+const runLoginFlow = async (
+/** `pasteNext`: the caller (`hwip install`) prompts for the key when this returns null. */
+opts, deps = {}) => {
+    const open = deps.open ?? exports.openBrowser;
+    const plan = deps.plan ?? (0, exports.browserPlan)();
+    const pasteNext = opts.pasteNext === true;
+    if (plan.kind === 'none') {
+        headlessHint(plan.reason, pasteNext);
+        return null;
+    }
+    const state = (0, node_crypto_1.randomBytes)(16).toString('hex');
+    let handle;
+    try {
+        handle = await startLoopbackServer(state, [...(0, login_address_js_1.trustedCallbackHosts)(opts.webUrl, (0, config_js_1.loadConfig)()), ...(opts.allowHosts ?? [])]);
+    }
+    catch (err) {
+        console.error(`  Error: could not start local server (${err instanceof Error ? err.message : 'unknown'})`);
+        return null;
+    }
+    const bridgeUrl = (0, exports.buildBridgeUrl)(opts.webUrl, handle.port, state, (0, node_os_1.hostname)());
+    if (plan.kind === 'ssh') {
+        // No browser here, but one on the user's machine can still finish the
+        // login once the callback port reaches this box.
+        console.log(`\n  This is an SSH session, so no browser opens here. To sign in from your own machine,\n` +
+            `  forward the callback port and open the URL there:\n` +
+            `    ssh -L ${handle.port}:127.0.0.1:${handle.port} <this host>\n` +
+            `    ${bridgeUrl}\n` +
+            (pasteNext ? '' : `  Otherwise press Ctrl+C and use the manual flow:\n${MANUAL_FLOW}\n`));
+    }
+    else {
+        const failed = await open(bridgeUrl);
+        if (failed) {
+            headlessHint(failed, pasteNext);
+            handle.close();
+            return null;
+        }
+        console.log(`\n  Opened the browser to sign in. If it did not appear, open:\n    ${bridgeUrl}\n`);
+    }
+    // Inside install Ctrl+C would end the whole install; Enter goes to the paste prompt.
+    const skip = pasteNext ? (deps.skip ?? enterToSkip)() : null;
+    const hint = !pasteNext ? ', Ctrl+C to cancel' : skip ? ', or press Enter to paste the API key instead' : '';
+    console.log(`  Waiting for sign-in in the browser (up to ${opts.timeoutSec}s${hint})...`);
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no sign-in within ${opts.timeoutSec}s`)), opts.timeoutSec * 1000);
+        timer.unref();
+    });
+    try {
+        const skipped = skip
+            ? skip.pressed.then((line) => (line ? { pastedKey: line } : null))
+            : new Promise(() => { });
+        return await Promise.race([handle.done, timeout, skipped]);
+    }
+    catch (err) {
+        console.error(`\n  Login failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        skip?.close();
+        handle.close();
+    }
+};
+exports.runLoginFlow = runLoginFlow;
+const handleLogin = async (args, deps = {}) => {
+    const webUrl = (0, exports.resolveWebUrl)(args['web-url']);
+    const timeoutSec = (0, exports.resolveTimeoutSec)(args.timeout);
+    let allowHosts;
+    try {
+        allowHosts = (0, exports.resolveAllowHosts)(args['allow-host']);
+    }
+    catch (err) {
+        console.error(`\n  Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    // Before a browser opens: a sign-in whose key cannot be saved is a sign-in for nothing.
+    const blocked = (0, config_js_1.configWriteProblem)();
+    if (blocked) {
+        console.error(`\n  Error: ${blocked}\n`);
+        return 1;
+    }
+    const result = await (0, exports.runLoginFlow)({ webUrl, timeoutSec, allowHosts }, deps);
+    // Without `pasteNext` there is no Enter-to-paste, so no pasted key either.
+    if (!result || !('apiKey' in result)) {
+        console.error('\n  Error: login did not complete\n');
+        return 1;
+    }
+    console.log(`  + Config saved. API key: ${(0, redact_js_1.maskKey)(result.apiKey)}`);
+    if (result.hookId)
+        console.log(`  + Hook: ${result.hookId}`);
+    console.log('\n  Done! Restart your agents.\n');
+    return 0;
+};
+exports.handleLogin = handleLogin;

package/dist/mcp-command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How every agent launches the Hwip MCP server — one source, three schemas.
+ *
+ * Registrations used to say `npx -y @hwip/mcp-server`, which left an
+ * `npm exec` launcher resident beside the server for the life of the session.
+ * `hwip mcp` (see mcp.ts) runs the server in the CLI's own process instead.
+ *
+ * Cursor/Windsurf, Gemini and OpenCode each want that launch in a different
+ * shape, and the shapes drifted apart when each site spelled the command out
+ * itself. Everything below is derived from MCP_LAUNCH_ARGV.
+ */
+/** What the agents run. `hwip` resolves out of the same global bin dir as `npx`. */
+export declare const MCP_LAUNCH_ARGV: readonly ["hwip", "mcp"];
+/**
+ * `mcpServers.hwip` — what the installer writes for Cursor and Windsurf.
+ * The env block is deliberate: both spawn the MCP server from a graphical
+ * context that may not inherit shell env, so the key is passed through
+ * explicitly rather than left to inheritance.
+ *
+ * `hwipit/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
+ * it lives in another repo and cannot import this. Change one, change both.
+ */
+export declare const MCP_SERVERS_ENTRY: {
+    command: "hwip";
+    args: "mcp"[];
+    env: {
+        HWIP_API_KEY: string;
+    };
+};
+/**
+ * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
+ * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
+ * opencode is a terminal app that inherits shell env, and the MCP server
+ * falls back to ~/.hwip/config.json anyway (an unexpanded "${HWIP_API_KEY}"
+ * literal would shadow that fallback with junk).
+ */
+export declare const OPENCODE_MCP_ENTRY: {
+    type: string;
+    command: ("mcp" | "hwip")[];
+    enabled: boolean;
+};
+export declare const GEMINI_MCP_ADD: string;
+/** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
+export declare const GEMINI_MCP_ADD_LEGACY: string;
+//# sourceMappingURL=mcp-command.d.ts.map

package/dist/mcp-command.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * How every agent launches the Hwip MCP server — one source, three schemas.
+ *
+ * Registrations used to say `npx -y @hwip/mcp-server`, which left an
+ * `npm exec` launcher resident beside the server for the life of the session.
+ * `hwip mcp` (see mcp.ts) runs the server in the CLI's own process instead.
+ *
+ * Cursor/Windsurf, Gemini and OpenCode each want that launch in a different
+ * shape, and the shapes drifted apart when each site spelled the command out
+ * itself. Everything below is derived from MCP_LAUNCH_ARGV.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMINI_MCP_ADD_LEGACY = exports.GEMINI_MCP_ADD = exports.OPENCODE_MCP_ENTRY = exports.MCP_SERVERS_ENTRY = exports.MCP_LAUNCH_ARGV = void 0;
+/** What the agents run. `hwip` resolves out of the same global bin dir as `npx`. */
+exports.MCP_LAUNCH_ARGV = ['hwip', 'mcp'];
+const [MCP_BIN, ...MCP_SUBCOMMAND] = exports.MCP_LAUNCH_ARGV;
+/**
+ * `mcpServers.hwip` — what the installer writes for Cursor and Windsurf.
+ * The env block is deliberate: both spawn the MCP server from a graphical
+ * context that may not inherit shell env, so the key is passed through
+ * explicitly rather than left to inheritance.
+ *
+ * `hwipit/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
+ * it lives in another repo and cannot import this. Change one, change both.
+ */
+exports.MCP_SERVERS_ENTRY = {
+    command: MCP_BIN,
+    args: [...MCP_SUBCOMMAND],
+    env: { HWIP_API_KEY: '${HWIP_API_KEY}' },
+};
+/**
+ * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
+ * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
+ * opencode is a terminal app that inherits shell env, and the MCP server
+ * falls back to ~/.hwip/config.json anyway (an unexpanded "${HWIP_API_KEY}"
+ * literal would shadow that fallback with junk).
+ */
+exports.OPENCODE_MCP_ENTRY = {
+    type: 'local',
+    command: [...exports.MCP_LAUNCH_ARGV],
+    enabled: true,
+};
+// gemini ≥0.26 syntax: `mcp add [-s scope] <name> <command> [args…]`. The
+// server NAME and the BINARY are both "hwip" here, so the doubled word below
+// is correct, not a copy-paste slip. Default scope is "project" (cwd-local
+// .gemini/), so user scope is pinned for a machine-wide install.
+exports.GEMINI_MCP_ADD = `gemini mcp add -s user hwip ${MCP_BIN} -- ${MCP_SUBCOMMAND.join(' ')}`;
+/** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
+exports.GEMINI_MCP_ADD_LEGACY = `gemini mcp add hwip -- ${exports.MCP_LAUNCH_ARGV.join(' ')}`;

package/dist/mcp.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `hwip mcp` — run the Hwip MCP server inside THIS process.
+ *
+ * Every registration used to say `npx -y @hwip/mcp-server`, which left an
+ * `npm exec` launcher resident for the whole session on top of the server it
+ * spawned — two node processes where one does the work. `@hwip/mcp-server`
+ * is a dependency of this package now, so agents register `hwip mcp` and get
+ * exactly one process.
+ */
+/**
+ * Importing `@hwip/mcp-server` IS starting it: the package is a bin entry
+ * whose module body wires an McpServer to a StdioServerTransport and exports
+ * nothing. Verified against 2.3.0 (`dist/index.js` ends in `main().catch(…)`).
+ * Injectable so tests don't need the real package resolvable.
+ */
+type McpServerLoader = () => Promise<unknown>;
+export declare const handleMcp: (load?: McpServerLoader) => Promise<number>;
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * `hwip mcp` — run the Hwip MCP server inside THIS process.
+ *
+ * Every registration used to say `npx -y @hwip/mcp-server`, which left an
+ * `npm exec` launcher resident for the whole session on top of the server it
+ * spawned — two node processes where one does the work. `@hwip/mcp-server`
+ * is a dependency of this package now, so agents register `hwip mcp` and get
+ * exactly one process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleMcp = void 0;
+const importMcpServer = () => import('@hwip/mcp-server');
+const handleMcp = async (load = importMcpServer) => {
+    try {
+        await load();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.error(`hwip: could not start the MCP server (@hwip/mcp-server): ${reason}`);
+        console.error('hwip: reinstall the CLI with `npm i -g @hwip/cli`.');
+        return 1;
+    }
+    // The server owns this process from here: it holds stdio open and decides
+    // when to exit. Resolving would hand cli.ts a code for `process.exit()`,
+    // killing the server the line above just started.
+    return new Promise(() => { });
+};
+exports.handleMcp = handleMcp;

package/dist/node-support.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Node versions this CLI runs on: the intersection of what its runtime
+ * dependencies declare in `engines` (read from `package-lock.json`, non-dev
+ * packages, 2026-10-02): `@inquirer/*` `>=23.5.0 || ^22.13.0 || ^20.17.0`,
+ * `mute-stream` `^20.17.0 || >=22.9.0`, `undici` 6 `>=18.17`, the MCP server
+ * `>=18.17.0`, the rest lower. `package.json` `engines.node` is this string,
+ * and `node-support.test.ts` recomputes the intersection from the lockfile, so
+ * a dependency that raises its floor fails a test instead of leaving `engines`
+ * untrue again (C80: it said `>=18` for a while after its dependencies needed 20.17).
+ */
+export declare const SUPPORTED_NODE = "^20.17.0 || ^22.13.0 || >=23.5.0";
+/**
+ * Whether a version (`v24.15.0` or `24.15.0`) is in `SUPPORTED_NODE`. Anything
+ * that is not `X.Y.Z` (with an optional `-prerelease`) is not. A prerelease sorts
+ * below its release, as in npm: `20.17.0-rc.1` is under the floor, `20.17.1-rc.1`
+ * is over it.
+ */
+export declare const isSupportedNode: (version: string) => boolean;
+//# sourceMappingURL=node-support.d.ts.map

package/dist/node-support.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSupportedNode = exports.SUPPORTED_NODE = void 0;
+/**
+ * The Node versions this CLI runs on: the intersection of what its runtime
+ * dependencies declare in `engines` (read from `package-lock.json`, non-dev
+ * packages, 2026-10-02): `@inquirer/*` `>=23.5.0 || ^22.13.0 || ^20.17.0`,
+ * `mute-stream` `^20.17.0 || >=22.9.0`, `undici` 6 `>=18.17`, the MCP server
+ * `>=18.17.0`, the rest lower. `package.json` `engines.node` is this string,
+ * and `node-support.test.ts` recomputes the intersection from the lockfile, so
+ * a dependency that raises its floor fails a test instead of leaving `engines`
+ * untrue again (C80: it said `>=18` for a while after its dependencies needed 20.17).
+ */
+exports.SUPPORTED_NODE = '^20.17.0 || ^22.13.0 || >=23.5.0';
+/** The lowest supported minor of each line whose floor is not its `.0`. */
+const FLOOR_MINOR = { 20: 17, 22: 13, 23: 5 };
+/**
+ * Whether a version (`v24.15.0` or `24.15.0`) is in `SUPPORTED_NODE`. Anything
+ * that is not `X.Y.Z` (with an optional `-prerelease`) is not. A prerelease sorts
+ * below its release, as in npm: `20.17.0-rc.1` is under the floor, `20.17.1-rc.1`
+ * is over it.
+ */
+const isSupportedNode = (version) => {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?$/.exec(version.trim());
+    if (!m)
+        return false;
+    const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const prerelease = m[4] !== undefined;
+    if (major >= 24)
+        return true;
+    const floor = FLOOR_MINOR[major];
+    if (floor === undefined)
+        return false;
+    if (minor !== floor)
+        return minor > floor;
+    return !prerelease || patch > 0;
+};
+exports.isSupportedNode = isSupportedNode;

package/dist/notify-failure.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The last failed `hwip notify`, kept so a failure is visible after the fact.
+ *
+ * Every agent hook runs `hwip notify … 2>/dev/null || true`: a hook must never
+ * break the session, so the error output is thrown away. A revoked key, a used
+ * up quota or a dead network then looked exactly like "quiet mode, nothing to
+ * send". `hwip notify` itself writes this file on failure and deletes it on
+ * success — the one writer — so the record survives whatever the hook does
+ * with stderr. Concurrent hooks race last-writer-wins: a failure that finishes
+ * after a newer success stays until the next good push clears it. `hwip verify` and the Claude Code plugin (/hwip-mode, the
+ * SessionStart hook) only read it.
+ *
+ * THE CONTRACT (the plugin reads it with jq and node, so changing it is a
+ * cross-repo change — notify-failure.test.ts pins it):
+ *
+ *   path  ${XDG_STATE_HOME:-~/.local/state}/hwip/last-notify-failure.json
+ *         — the same state dir as the mute and push-mode dials (gate.ts
+ *         stateDir, plugin hooks/gate.sh HWIP_STATE_DIR)
+ *   body  {"v":1,"at":"<ISO 8601 UTC>","kind":"<kind>","status":<int|null>,"code":"<string|null>"}
+ *   kind  no-key | auth | quota | rate-limit | client | server | timeout | network | no-app | unsealed
+ *
+ * `no-app` (NO_APP_DEVICE) and `unsealed` (E2E_REQUIRED) are refusals made here, before the push went out: they
+ * carry no HTTP status, so a reader never shows one as the server's answer.
+ *
+ * A device whose key changed is not recorded here: the pin that replaced it writes
+ * key-changes.json (key-changes.ts), which another process's push cannot clear.
+ *
+ * No message text and nothing from the request: `status` is the HTTP status
+ * and `code` the server's error code (e.g. QUOTA_EXCEEDED), so the file can
+ * never carry a key, a title or a body.
+ */
+export declare const NOTIFY_FAILURE_KINDS: readonly ["no-key", "auth", "quota", "rate-limit", "client", "server", "timeout", "network", "no-app", "unsealed"];
+export type NotifyFailureKind = typeof NOTIFY_FAILURE_KINDS[number];
+export interface NotifyFailure {
+    readonly v: 1;
+    readonly at: string;
+    readonly kind: NotifyFailureKind;
+    readonly status: number | null;
+    readonly code: string | null;
+}
+export declare const notifyFailurePath: () => string;
+/** What went wrong, in the contract's terms. Anything that is not an HwipError
+ *  never got an HTTP answer — fetch rejects on DNS, refused or reset. The code is read before the
+ *  status: a refusal made here carries a status (400) the server never sent. */
+export declare const classifyNotifyFailure: (err: unknown) => Pick<NotifyFailure, "kind" | "status" | "code">;
+/** Best effort: a hook must never fail because its failure could not be noted. */
+export declare const recordNotifyFailure: (failure: Pick<NotifyFailure, "kind" | "status" | "code">, now?: Date) => void;
+export declare const clearNotifyFailure: () => void;
+/** Run one push attempt and leave the record matching its outcome. */
+export declare const withNotifyFailureRecord: <T>(send: () => Promise<T>) => Promise<T>;
+/** null when there is no record, or one this version cannot read. */
+export declare const readNotifyFailure: () => NotifyFailure | null;
+/** One line for a person: what, when, and the HTTP status when there was one. */
+export declare const describeNotifyFailure: (f: NotifyFailure) => string;
+/** Transient kinds clear themselves on the next good push; the rest need the user. */
+export declare const isTransientNotifyFailure: (f: NotifyFailure) => boolean;
+//# sourceMappingURL=notify-failure.d.ts.map