@hwip/mcp-server 0.0.0-stage → 0.1.0

package/dist/command-seq.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextCommandNumber = void 0;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const FILE = 'command-seq';
+const LOCK = 'command-seq.lock';
+/** 40 tries 50 ms apart: two seconds, then the send is refused. */
+const LOCK_TRIES = 40;
+const LOCK_RETRY_MS = 50;
+/** A lock older than this was left by a process that died holding it. */
+const LOCK_STALE_MS = 5000;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * One try at the lock: its release when taken, 'held' when someone else has it, 'failed' when it cannot be made at all.
+ * The lock holds a token only its taker knows, and the release removes the file only while it still holds that token:
+ * a holder that was stopped for longer than `LOCK_STALE_MS` (a laptop asleep) finds its lock cleared and perhaps taken
+ * again, and must not remove the new holder's.
+ */
+const tryLock = (path) => {
+    const token = (0, node_crypto_1.randomBytes)(8).toString('hex');
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(path, 'wx', 0o600);
+    }
+    catch (err) {
+        // err.code is how node names a failed open. Nothing was created, so nothing here is ours to remove.
+        return err.code === 'EEXIST' ? 'held' : 'failed';
+    }
+    try {
+        (0, node_fs_1.writeSync)(fd, token);
+    }
+    catch {
+        try {
+            (0, node_fs_1.unlinkSync)(path); // created but not written (disk full): no later sender should wait on an empty lock
+        }
+        catch { /* gone already */ }
+        return 'failed';
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    return () => {
+        try {
+            if ((0, node_fs_1.readFileSync)(path, 'utf-8') === token)
+                (0, node_fs_1.unlinkSync)(path);
+        }
+        catch { /* gone already: nothing is held */ }
+    };
+};
+/**
+ * The lock file's own age says whether anyone is still behind it. A stale one is moved aside under a name of its own
+ * and only then checked and removed: a plain unlink by path could remove a lock another waiter had just made. If what
+ * was moved is not the file that was seen, it was a live lock; it goes back unless yet another has been made since.
+ */
+const removeIfStale = (path) => {
+    try {
+        const seen = (0, node_fs_1.statSync)(path);
+        if (Date.now() - seen.mtimeMs <= LOCK_STALE_MS)
+            return;
+        const aside = `${path}.${process.pid}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.stale`;
+        (0, node_fs_1.renameSync)(path, aside);
+        try {
+            const moved = (0, node_fs_1.statSync)(aside);
+            if (moved.ino !== seen.ino || moved.mtimeMs !== seen.mtimeMs) {
+                try {
+                    (0, node_fs_1.linkSync)(aside, path);
+                }
+                catch { /* someone made a lock since: theirs stands */ }
+            }
+        }
+        finally {
+            (0, node_fs_1.unlinkSync)(aside);
+        }
+    }
+    catch { /* taken, or removed, by someone else in between */ }
+};
+/** The last number handed out: 0 when there is no file or it holds no number, null when it cannot be read or is out of range. */
+const readLast = (path) => {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? 0 : null; // err.code is how node names a missing file
+    }
+    const line = text.trim();
+    if (!/^\d+$/.test(line))
+        return 0;
+    const last = Number(line);
+    return Number.isSafeInteger(last) ? last : null;
+};
+/** Read, add, write: runs with the lock held, and without a pause, so callers in one process never overlap. */
+const draw = (dir, now) => {
+    const path = (0, node_path_1.join)(dir, FILE);
+    const last = readLast(path);
+    if (last === null)
+        return { refused: 'io' };
+    const n = Math.max(last + 1, Math.floor(now()));
+    if (!Number.isSafeInteger(n))
+        return { refused: 'io' };
+    // Random name, exclusive create, then rename: a reader never sees half a line.
+    const temp = `${path}.${process.pid}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    try {
+        (0, node_fs_1.writeFileSync)(temp, `${n}\n`, { mode: 0o600, flag: 'wx' });
+        (0, node_fs_1.renameSync)(temp, path);
+    }
+    catch {
+        try {
+            (0, node_fs_1.unlinkSync)(temp);
+        }
+        catch { /* never made */ }
+        return { refused: 'io' };
+    }
+    return n;
+};
+const nextCommandNumber = async (deps = {}) => {
+    const dir = deps.dir ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.hwip');
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? defaultSleep;
+    try {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        return { refused: 'io' };
+    }
+    const lock = (0, node_path_1.join)(dir, LOCK);
+    for (let attempt = 0; attempt < LOCK_TRIES; attempt += 1) {
+        const taken = tryLock(lock);
+        if (taken === 'failed')
+            return { refused: 'io' };
+        if (typeof taken === 'function') {
+            try {
+                return draw(dir, now);
+            }
+            finally {
+                taken();
+            }
+        }
+        removeIfStale(lock);
+        await sleep(LOCK_RETRY_MS);
+    }
+    return { refused: 'lock' };
+};
+exports.nextCommandNumber = nextCommandNumber;

package/dist/config.d.ts

@@ -0,0 +1,93 @@
+export interface McpServerConfig {
+    apiKey: string;
+    baseUrl: string;
+    /** WebSocket endpoint for the hook-response fast path (§S3). Optional —
+     *  without it (or without a WebSocket global) waits are poll-only. */
+    wsUrl?: string;
+    hookId?: string;
+    deviceId?: string;
+    sessionId?: string;
+    /** Stable agent-session key parts so hook pushes join the session chat:
+     *  the listener's per-host device id (mirrors cli computeListenerDeviceId)
+     *  + the tmux session name. The Claude sessionId above rotates on
+     *  compact/resume; these don't. */
+    agentDeviceId?: string;
+    agentSessionName?: string;
+    /** Last path segment of the project directory — prefixed onto push titles. */
+    projectName: string;
+}
+/** The project directory the agent runs in, across supported agents. */
+/**
+ * The key every per-project hwip file is named by. Shelling out to `cksum`
+ * (rather than a pure-JS CRC) is what guarantees it matches the files the bash
+ * hooks have already written — they key off `printf '%s' "$dir" | cksum`. Null
+ * when `cksum` is unavailable, which means no per-project file can be resolved.
+ */
+export declare const projectHash: (dir: string) => string | null;
+export declare const detectProjectDir: () => string;
+/**
+ * Prefix a push title with the project name so the device feed stays
+ * scannable — "hwip · Build finished" instead of a bare "Build finished".
+ * Idempotent: a title already carrying the project segment is returned
+ * unchanged (guards against double-prefixing on retries).
+ */
+export declare const formatPushTitle: (projectName: string, title: string) => string;
+/**
+ * Why this machine should not trust the config file as it stands, or null — the
+ * rule of the cli's `configModeProblem` (src/config.ts), keep the two in step.
+ * The file holds the API key AND says where the key is sent (`baseUrl`, `wsUrl`),
+ * so one that another user owns, or that anyone can write, is a way to redirect
+ * the key. `refuse`: ignore the file; otherwise only warn. Group access to a file
+ * the user owns is not refused: a user-private group (umask 002, a dotfiles
+ * checkout) makes every file 664, and ignoring those would stop every session.
+ * Root may read what a user owns (sudo). This server only reads the file, so
+ * unlike the cli it does not narrow the mode itself.
+ */
+export declare const configModeProblem: (st: {
+    uid: number;
+    mode: number;
+}, myUid: number, file?: string) => {
+    refuse: boolean;
+    why: string;
+} | null;
+/**
+ * The directory name Claude Code gives a cwd under `~/.claude/projects/`.
+ * Copied from the Claude Code 2.1.287 binary (`k` / `Jx`): every character
+ * outside `[a-zA-Z0-9]` becomes `-`, so `.`, `_`, spaces, `@` and Hangul all
+ * collapse, one `-` per UTF-16 unit. Names past 200 characters are cut and
+ * suffixed with `-` plus the base-36 of a Java-style string hash of the cwd.
+ * Same rule and test vectors as the cli's `claudeProjectDirName`
+ * (cli/src/remote-agents.ts) — keep the two in step.
+ */
+export declare const claudeProjectDirName: (cwd: string) => string;
+export declare const loadConfig: () => McpServerConfig;
+/** Listener device id — MUST match cli `computeListenerDeviceId` so `hwip_ask`
+ *  hooks land under the same agent-session key as the listener's
+ *  agent.command/state pushes (otherwise they reach the feed but never thread
+ *  into the agent chat). cli hashes the platform machine id first and falls
+ *  back to a hostname hash pinned in a sticky file; mirror that order, reading
+ *  (never writing) the file so both processes resolve the same id. */
+export declare const listenerDeviceId: () => string;
+/** Shells out; returns null instead of throwing so every caller reads as one
+ *  expression. */
+export type CommandRunner = (cmd: string, args: string[]) => string | null;
+/** The tmux session name the agent runs in (`hwip-<project>`) — stable half of
+ *  the session key. Undefined outside tmux; the hook then stays feed-only. */
+export declare const detectTmuxSessionName: (run?: CommandRunner) => string | undefined;
+/**
+ * A one-line notice for a machine that still exports `HWIP_WS_URL`, or null.
+ *
+ * The variable is no longer read. Dropping it in silence would repeat the
+ * failure it caused — a value that looks like it is in effect while something
+ * else decides — so it is read here only to say it is being ignored.
+ */
+export declare const legacyWsEnv: (env?: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * What to tell a machine that still exports `HWIP_WS_URL`, or null. Two
+ * messages, because the two situations differ: an export beside a config file
+ * is dead weight, while an export on its own is still carrying the value.
+ */
+export declare const legacyWsEnvNotice: (fileConfig?: {
+    wsUrl?: string;
+}, env?: NodeJS.ProcessEnv) => string | null;
+//# sourceMappingURL=config.d.ts.map