@hwip/cli 0.0.1 → 0.1.1

package/dist/tmux-socket.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tmuxArgs = exports.socketKey = exports.invalidateTmuxSocketCache = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const listener_log_js_1 = require("./listener-log.js");
+// ─── tmux socket discovery ──────────────────────────────────────────
+/**
+ * macOS sets a per-user `TMPDIR` like `/var/folders/xz/.../T/`, and tmux
+ * (started from a regular shell there) lays its socket at
+ * `<TMPDIR>/tmux-<uid>/default`. When the listener is spawned from a
+ * shell with a different TMPDIR — or no TMPDIR at all (cron, launchd,
+ * IDE-managed terminals) — tmux defaults to `/tmp/tmux-<uid>/default`
+ * and the user's real server is invisible. We probe a small list of
+ * common locations and use `-S <path>` for every subsequent tmux call
+ * once a live server is found.
+ *
+ * Caching is one-way: a successful discovery sticks for the process
+ * lifetime, but failure does NOT — we re-probe every cycle so the
+ * listener picks up a tmux server that gets started AFTER the listener
+ * itself (very common: the user opens `hwip cc` after starting the
+ * daemon). If tmux dies and respawns under a different path the user
+ * has to restart the listener (rare).
+ */
+let cachedSocketPath = null;
+/** True once we've confirmed a working socket. `cachedSocketPath` of
+ *  `null` is ambiguous on its own — it can mean either "use default
+ *  (we verified it works)" or "we haven't checked yet". This flag
+ *  removes the ambiguity so we don't re-probe every collectSessions
+ *  cycle (which was spamming the log with "tmux: default socket OK"). */
+let cacheValid = false;
+/**
+ * Mark the cached socket as no longer trustworthy — call this when a
+ * tmux command fails against the cached path. The next findTmuxSocket()
+ * will redo full discovery (default probe → /var/folders walk → lsof
+ * fallback) instead of returning a stale answer. Without this the
+ * listener wedged at "reported 0 session(s)" forever after a tmux
+ * server restart, even when a new server was live and discoverable.
+ */
+const invalidateTmuxSocketCache = () => {
+    cacheValid = false;
+    cachedSocketPath = null;
+};
+exports.invalidateTmuxSocketCache = invalidateTmuxSocketCache;
+const probeTmuxSocketDetail = (socketPath) => {
+    const args = socketPath ? ['-S', socketPath, 'list-sessions'] : ['list-sessions'];
+    const r = (0, child_process_1.spawnSync)('tmux', args, {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (r.status === 0)
+        return { ok: true };
+    const err = (r.stderr ?? '').trim();
+    return { ok: false, stderr: err || undefined };
+};
+const probeTmuxSocket = (socketPath) => probeTmuxSocketDetail(socketPath).ok;
+/**
+ * List every socket file inside a `tmux-<uid>/` directory. tmux's
+ * default socket name is `default`, but users can change it with
+ * `tmux -L <name>` or via .tmux.conf — so we probe every file we find,
+ * not just `default`. Returns absolute socket paths.
+ */
+const listSocketsIn = (dir) => {
+    if (!(0, fs_1.existsSync)(dir))
+        return [];
+    try {
+        return (0, fs_1.readdirSync)(dir).map((name) => `${dir}/${name}`);
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * One name per socket file: the path with its symlinks resolved, or the path
+ * as given when nothing is there to resolve. macOS reaches the same directory
+ * as `/tmp/…` and `/private/tmp/…`, and as `/var/folders/…` and
+ * `/private/var/folders/…`; without this each dead socket there is probed
+ * once per spelling.
+ */
+const socketKey = (path) => {
+    try {
+        return (0, fs_1.realpathSync)(path);
+    }
+    catch {
+        return path;
+    }
+};
+exports.socketKey = socketKey;
+/**
+ * Final-fallback socket discovery: find tmux server processes via `ps`
+ * and ask `lsof` what unix socket each is bound to. Handles the cases
+ * filesystem walking can't:
+ *   - macOS auto-cleanup deleted the socket file while the server kept
+ *     running (the most likely cause of "no server running" errors when
+ *     a tmux session is clearly alive in another iTerm/Warp pane)
+ *   - The user runs tmux with `-L <name>` or `-S <unusual-path>` that we
+ *     never thought to enumerate
+ *
+ * `lsof` on macOS may report sockets as `(deleted)`. Even then, if the
+ * server still has the inode open we can still tmux-attach by recreating
+ * the path — but for now we only return paths that still exist on disk
+ * so tmux's connect logic isn't confused. If the path is gone, the user
+ * has to `tmux kill-server` + restart anyway.
+ *
+ * Returns the first path `isLive` accepts, and stops there: every tmux
+ * process — each `tmux new -A` client, not only the server — costs one
+ * `lsof`, seconds apiece on a loaded daemon.
+ */
+const findTmuxViaProcess = (isLive) => {
+    const username = (0, os_1.userInfo)().username;
+    const ps = (0, child_process_1.spawnSync)('ps', ['-A', '-o', 'pid=,user=,command='], {
+        encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (ps.status !== 0)
+        return undefined;
+    const tmuxPids = [];
+    for (const line of (ps.stdout ?? '').split('\n')) {
+        const m = line.match(/^\s*(\d+)\s+(\S+)\s+(.+)$/);
+        if (!m)
+            continue;
+        const [, pid, user, cmd] = m;
+        if (user !== username)
+            continue;
+        // Server processes show up as `tmux: server` (with the colon) on
+        // some versions; client/wrapper invocations show up as `tmux new`
+        // / `tmux attach` etc. lsof works on either.
+        if (!/(^|[^\w-])tmux($|[:\s])/.test(cmd))
+            continue;
+        tmuxPids.push(pid);
+    }
+    for (const pid of tmuxPids) {
+        const lsof = (0, child_process_1.spawnSync)('lsof', ['-p', pid, '-Fn'], {
+            encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (lsof.status !== 0)
+            continue;
+        // `-Fn` prints names prefixed with `n`; one per line. Filter for
+        // tmux-shaped socket paths.
+        for (const lline of (lsof.stdout ?? '').split('\n')) {
+            if (!lline.startsWith('n'))
+                continue;
+            const path = lline.slice(1);
+            if (!/\/tmux-\d+\//.test(path))
+                continue;
+            if (path.includes('(deleted)'))
+                continue;
+            if (isLive(path))
+                return path;
+        }
+    }
+    return undefined;
+};
+/** Walk `/var/folders` for user-owned `tmux-<uid>/*` socket files. Each
+ * subdir is wrapped in its own try/catch — entries that belong to other
+ * users (or that we otherwise can't read) must skip cleanly, not abort
+ * the whole walk. */
+const walkVarFolders = (uid) => {
+    const found = [];
+    const root = '/var/folders';
+    if (!(0, fs_1.existsSync)(root))
+        return found;
+    let topEntries;
+    try {
+        topEntries = (0, fs_1.readdirSync)(root);
+    }
+    catch {
+        return found;
+    }
+    for (const a of topEntries) {
+        const aPath = `${root}/${a}`;
+        let subEntries;
+        try {
+            subEntries = (0, fs_1.readdirSync)(aPath);
+        }
+        catch {
+            continue;
+        }
+        for (const b of subEntries) {
+            found.push(...listSocketsIn(`${aPath}/${b}/T/tmux-${uid}`));
+        }
+    }
+    return found;
+};
+/**
+ * Track whether the "no server anywhere" diagnostic was already logged
+ * this run. We want the user to see the path list *once* on first
+ * failure, then go quiet until we either find a server or notice a new
+ * candidate file appearing — otherwise every 30-s cycle would spam the
+ * full probe report.
+ */
+let warnedNoServer = false;
+const findTmuxSocket = () => {
+    // Successful discovery sticks. Failure does NOT — we want to pick
+    // up a tmux server that the user launches *after* `hwip listener`.
+    if (cacheValid)
+        return cachedSocketPath;
+    // Explicit override — for users with `tmux -L <name>` setups or
+    // unusual socket locations. Skip discovery entirely if set and
+    // probeable.
+    const override = process.env.HWIP_TMUX_SOCKET;
+    if (override) {
+        if (probeTmuxSocket(override)) {
+            cachedSocketPath = override;
+            cacheValid = true;
+            (0, listener_log_js_1.log)(`tmux socket → ${override} (from HWIP_TMUX_SOCKET)`);
+            warnedNoServer = false;
+            return override;
+        }
+        // Fall through to standard discovery if override fails — better
+        // than failing silently. We re-log this every cycle (no
+        // `warnedNoServer`) because it's a user-supplied setting we want
+        // to keep nagging about.
+        (0, listener_log_js_1.log)(`tmux: HWIP_TMUX_SOCKET=${override} probe failed, falling back to auto-discovery`);
+    }
+    // Default first — succeeds when the shell that launched us shares
+    // tmux's view, and costs one tmux call. It must run before the scans
+    // below: `findTmuxViaProcess` runs up to one `lsof` per tmux process (every
+    // `tmux new -A` client, not just the server), which took 11–19s+ with 14
+    // sessions on a loaded daemon — longer than a fresh inventory worker's
+    // whole 20s budget.
+    if (probeTmuxSocket(null)) {
+        cachedSocketPath = null; // null means "use default"
+        cacheValid = true;
+        if (!warnedNoServer)
+            (0, listener_log_js_1.log)('tmux: default socket OK');
+        warnedNoServer = false;
+        return null;
+    }
+    const uid = (0, os_1.userInfo)().uid;
+    const probed = new Set();
+    const isLive = (path) => {
+        const key = (0, exports.socketKey)(path);
+        if (probed.has(key))
+            return false;
+        probed.add(key);
+        return (0, fs_1.existsSync)(path) && probeTmuxSocket(path);
+    };
+    // Every socket file in any `tmux-<uid>/` dir next — `tmux -L <name>`
+    // puts its socket beside `default`, so one probe per file finds it.
+    const envDir = process.env.TMUX_TMPDIR || process.env.TMPDIR;
+    const files = [
+        ...(envDir ? listSocketsIn(`${envDir.replace(/\/+$/, '')}/tmux-${uid}`) : []),
+        ...walkVarFolders(uid),
+        ...listSocketsIn(`/tmp/tmux-${uid}`),
+        ...listSocketsIn(`/private/tmp/tmux-${uid}`),
+    ];
+    // Process-based discovery last — it is the only path that finds a `-S`
+    // path the walks never look in, but it is also the one that costs seconds.
+    const live = files.find(isLive) ?? findTmuxViaProcess(isLive);
+    if (live) {
+        cachedSocketPath = live;
+        cacheValid = true;
+        (0, listener_log_js_1.log)(`tmux socket → ${live}`);
+        warnedNoServer = false;
+        return live;
+    }
+    const unique = [...probed];
+    // No live tmux yet. Log the full probe report once, then stay quiet
+    // until something works — otherwise the user gets a 4-line dump
+    // every 30 seconds while they're still bringing tmux up. Include the
+    // tmux binary identification + stderr for failed probes so the user
+    // can spot version mismatches (homebrew on /usr/local vs /opt/homebrew)
+    // or stale socket files.
+    if (!warnedNoServer) {
+        const which = (0, child_process_1.spawnSync)('which', ['tmux'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const tmuxPath = (which.stdout ?? '').trim() || '(not on PATH)';
+        const ver = (0, child_process_1.spawnSync)('tmux', ['-V'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const tmuxVer = (ver.stdout ?? '').trim() || '?';
+        (0, listener_log_js_1.log)(`tmux: no live server yet — using ${tmuxPath} (${tmuxVer})`);
+        (0, listener_log_js_1.log)(`tmux: probed ${unique.length} candidate(s):`);
+        for (const path of unique) {
+            if (!(0, fs_1.existsSync)(path)) {
+                (0, listener_log_js_1.log)(`  - ${path}  (no socket file)`);
+                continue;
+            }
+            const detail = probeTmuxSocketDetail(path);
+            (0, listener_log_js_1.log)(`  ✗ ${path}  (${detail.stderr ?? 'probe failed without stderr'})`);
+        }
+        (0, listener_log_js_1.log)(`tmux: will retry each cycle. If your tmux uses a custom socket,`);
+        (0, listener_log_js_1.log)(`     run \`tmux info | head -1\` in the same shell as 'hwip cc'`);
+        (0, listener_log_js_1.log)(`     and pass it via:  HWIP_TMUX_SOCKET=<path> hwip listener`);
+        warnedNoServer = true;
+    }
+    return null;
+};
+/** Prepend `-S <socket>` when we've discovered a non-default tmux server. */
+const tmuxArgs = (args) => {
+    const sock = findTmuxSocket();
+    return sock ? ['-S', sock, ...args] : args;
+};
+exports.tmuxArgs = tmuxArgs;

package/dist/todo-fold.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The agent's own to-do list, folded out of Claude Code's task tools.
+ *
+ * Claude Code does not write the list down whole: TaskCreate adds one task,
+ * TaskUpdate moves one, TaskList reads them back. What the timeline wants is the
+ * list as it stands, so this folds those steps into it.
+ *
+ * Only the *results* are read — the user entry's top-level `toolUseResult` —
+ * because they carry everything at once: a created task's id comes back there and
+ * nowhere in the call (measured 2026-10-09, one transcript: TaskCreate input is
+ * `{subject, description, activeForm}`, its result `{task: {id, subject}}`;
+ * TaskUpdate's result `{taskId, statusChange: {from, to}}`; TaskList's
+ * `{tasks: [{id, subject, status}]}`). Folding results alone means a call and its
+ * result landing in different reads never have to be matched up.
+ */
+export type TodoStatus = 'pending' | 'in_progress' | 'completed';
+export interface TodoItem {
+    readonly id: string;
+    readonly text: string;
+    readonly status: TodoStatus;
+}
+export interface TodoList {
+    readonly items: readonly TodoItem[];
+}
+/**
+ * The list after one transcript entry. Returns `list` itself — the same
+ * reference — when the entry is not a task result, so a caller tells "changed"
+ * from "not" by identity.
+ */
+export declare const applyTodoEntry: (list: TodoList | undefined, entry: Record<string, unknown>) => TodoList | undefined;
+//# sourceMappingURL=todo-fold.d.ts.map

package/dist/todo-fold.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * The agent's own to-do list, folded out of Claude Code's task tools.
+ *
+ * Claude Code does not write the list down whole: TaskCreate adds one task,
+ * TaskUpdate moves one, TaskList reads them back. What the timeline wants is the
+ * list as it stands, so this folds those steps into it.
+ *
+ * Only the *results* are read — the user entry's top-level `toolUseResult` —
+ * because they carry everything at once: a created task's id comes back there and
+ * nowhere in the call (measured 2026-10-09, one transcript: TaskCreate input is
+ * `{subject, description, activeForm}`, its result `{task: {id, subject}}`;
+ * TaskUpdate's result `{taskId, statusChange: {from, to}}`; TaskList's
+ * `{tasks: [{id, subject, status}]}`). Folding results alone means a call and its
+ * result landing in different reads never have to be matched up.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyTodoEntry = void 0;
+const isTodoStatus = (value) => value === 'pending' || value === 'in_progress' || value === 'completed';
+// `record`, `nonBlank` and `listed` take `unknown` on purpose: they are the parse
+// boundary, reading the vendor's JSON field by field.
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : undefined; // narrowed by the object/array check
+const nonBlank = (value) => typeof value === 'string' && value.trim() ? value.trim() : undefined;
+const allDone = (list) => list.items.length > 0 && list.items.every((item) => item.status === 'completed');
+/** TaskCreate: one more task, pending. A finished list is replaced, not added to. */
+const created = (list, task) => {
+    const id = nonBlank(task.id);
+    const text = nonBlank(task.subject);
+    if (!id || !text)
+        return list;
+    const item = { id, text, status: 'pending' };
+    // Every task done and a new one arrives: that is the next list starting.
+    if (!list || allDone(list))
+        return { items: [item] };
+    if (list.items.some((existing) => existing.id === id))
+        return list;
+    return { items: [...list.items, item] };
+};
+/** TaskUpdate: one task moved. `to` undefined = a status outside the three, which takes it off the list. */
+const updated = (list, taskId, to) => {
+    // A task this list never saw was made before the read began: nothing to move.
+    const task = list?.items.find((item) => item.id === taskId);
+    // Already there (or never seen): the same list, so no `todo` goes out again.
+    if (!list || !task || task.status === to)
+        return list;
+    if (!to)
+        return { items: list.items.filter((item) => item.id !== taskId) };
+    return { items: list.items.map((item) => (item.id === taskId && item.status !== to ? { ...item, status: to } : item)) };
+};
+/**
+ * TaskList: the tasks it named are refreshed and any it adds are taken, but a
+ * task it leaves out stays. The one TaskList measured returned only pending and
+ * in-progress tasks, so treating its answer as the whole list would drop every
+ * finished one and turn 7/7 into 0/4.
+ */
+const listed = (list, tasks) => {
+    const named = [];
+    for (const raw of tasks) {
+        const task = record(raw);
+        const id = nonBlank(task?.id);
+        const text = nonBlank(task?.subject);
+        if (!id || !text || !isTodoStatus(task?.status))
+            return list;
+        named.push({ id, text, status: task.status });
+    }
+    if (!named.length)
+        return list;
+    const byId = new Map(named.map((item) => [item.id, item]));
+    const kept = (list?.items ?? []).map((item) => byId.get(item.id) ?? item);
+    const known = new Set(kept.map((item) => item.id));
+    const items = [...kept, ...named.filter((item) => !known.has(item.id))];
+    const same = list && items.length === list.items.length && items.every((item, i) => sameItem(item, list.items[i]));
+    return same ? list : { items };
+};
+const sameItem = (a, b) => a.id === b.id && a.text === b.text && a.status === b.status;
+/**
+ * The list after one transcript entry. Returns `list` itself — the same
+ * reference — when the entry is not a task result, so a caller tells "changed"
+ * from "not" by identity.
+ */
+const applyTodoEntry = (list, entry) => {
+    if (entry.type !== 'user')
+        return list;
+    const result = record(entry.toolUseResult);
+    if (!result)
+        return list;
+    const task = record(result.task);
+    // A task that says its status (TaskGet's answer, unmeasured) is a read, not a create:
+    // folded like a one-task TaskList, so it cannot restart a finished list.
+    if (task && 'status' in task)
+        return listed(list, [task]);
+    if (task)
+        return created(list, task);
+    const taskId = nonBlank(result.taskId);
+    const change = record(result.statusChange);
+    if (taskId && change)
+        return updated(list, taskId, isTodoStatus(change.to) ? change.to : undefined);
+    if (Array.isArray(result.tasks))
+        return listed(list, result.tasks);
+    return list;
+};
+exports.applyTodoEntry = applyTodoEntry;