@hwip/cli 0.0.1 → 0.1.1

package/dist/command-seq.js

@@ -0,0 +1,150 @@
+"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 private_files_js_1 = require("./private-files.js");
+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);
+    }
+    (0, private_files_js_1.handBackToSudoUser)(path);
+    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, private_files_js_1.handBackToSudoUser)(temp);
+        (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, private_files_js_1.mkdirHandedBack)(dir, 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,156 @@
+export declare const CONFIG_DIR: string;
+export declare const CONFIG_FILE: string;
+/** The listener's subscriber trust store (subscriber-trust.ts), shared with `hwip trust`. */
+export declare const TRUST_FILE: string;
+export interface HwipConfig {
+    apiKey?: string;
+    hookId?: string;
+    baseUrl?: string;
+    wsUrl?: string;
+    /** `false` stops the listener holding the Mac awake on AC (`caffeinate -s`). README § Listener Options. */
+    keepAwake?: boolean;
+    /** `false` stops the listener uploading sealed session conversations for the app's history (`turn-recorder.ts`). README § Session history. */
+    turnHistory?: boolean;
+    /** Proxy settings for a process that does not get the shell's `HTTPS_PROXY` (a launchd service); the environment wins. README § Environment Variables. */
+    httpProxy?: string;
+    httpsProxy?: string;
+    noProxy?: string;
+}
+/**
+ * What a boolean option is when `config.json` is there and cannot be used (it does
+ * not parse, or is ignored for its mode). The options are opt-outs: read as "not set"
+ * they come back ON, and a user who wrote `"turnHistory": false` found sealed
+ * conversations uploading. Unreadable means off, for every boolean option HwipConfig has
+ * (the compiler holds the keys to the interface, and config-unreadable.test.ts reads it too).
+ */
+export type BooleanConfigKey = {
+    [K in keyof HwipConfig]-?: NonNullable<HwipConfig[K]> extends boolean ? K : never;
+}[keyof HwipConfig];
+export declare const unreadableConfigDefaults: Record<BooleanConfigKey, false>;
+export declare const resolvedEnv: (key: string, env?: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * The two-way hook id: `HWIP_HOOK_ID` when it carries a real value, else
+ * `hookId` from ~/.hwip/config.json — what `hwip setup` writes. The plugin's
+ * gate.sh `hwip_hook_id` and the MCP server resolve it in the same order.
+ */
+export declare const resolveHookId: (env?: NodeJS.ProcessEnv) => string | undefined;
+/** tmux session options the listener reads before falling back to parsing the name (listener `parseSessionName`). */
+export declare const SESSION_PROJECT_OPTION = "@hwip_project";
+export declare const SESSION_LABEL_OPTION = "@hwip_session_label";
+/**
+ * The herdr pane a session is attached from, as `<herdr env var> → <session
+ * option>`. herdr finds agents by a pane's foreground process, which for a
+ * wrapped pane is the tmux client, so the plugin's `hwip-herdr.sh` hook and
+ * the pi extension (templates `PI_EXTENSION`) report the agent's state
+ * themselves, to the pane these options name. They are session options rather
+ * than the agent's own env because a `hwip` reattach from another herdr pane
+ * (or from outside herdr) must retarget a running agent.
+ */
+export declare const HERDR_SESSION_OPTIONS: {
+    readonly HERDR_PANE_ID: "@hwip_herdr_pane";
+    readonly HERDR_SOCKET_PATH: "@hwip_herdr_socket";
+    readonly HERDR_BIN_PATH: "@hwip_herdr_bin";
+};
+/**
+ * Set by `hwip sh` on the session it opens, to that session's own name. The
+ * one exception to the listener's shell-pane refusal. Only a process on this
+ * machine can set a tmux option, so it says the user opened the shell — but it
+ * is not a boundary: the phone can set it through `!` in a Claude Code session,
+ * or from a shell that is already marked (README § Defense).
+ */
+export declare const SESSION_SHELL_OPTION = "@hwip_shell";
+/** `name` as tmux holds it: tmux turns `.`/`:` into `_`, and `;` would end a tmux command (wrapper `tmuxSessionName`). */
+export declare const tmuxName: (name: string) => string;
+/**
+ * The repo a directory belongs to: `key` names the main checkout, `linked` says the directory is in a linked worktree,
+ * `root` is the main checkout's path — null where there is no main checkout to point at (the layouts `key` falls back on).
+ */
+export interface Checkout {
+    key: string;
+    linked: boolean;
+    root: string | null;
+}
+/**
+ * Which checkout `dir` is in, from one `git rev-parse`; null outside git.
+ *
+ * Inside a linked worktree `--show-toplevel` is the worktree itself, so its
+ * name is not the repo's. The common dir is `<main checkout>/.git` from every
+ * worktree, and differs from the git dir only in a linked one. A common dir not
+ * named `.git` (bare-repo layout, submodule, `--separate-git-dir`) has no
+ * checkout to be named for, so the toplevel's own name stands and nothing is
+ * called linked — those worktrees keep reading as their own projects.
+ *
+ * Anything but three absolute paths is "outside git": a git too old for
+ * `--path-format` echoes it back as an unknown flag and exits 0, which would
+ * otherwise shift every answer by one and name the repo `--path-format=absolute`.
+ *
+ * The timeout is for the listener's sweep worker, which calls this for every
+ * new pane cwd: a repo on a hung network mount must cost one sweep a moment,
+ * not stop inventory. A timeout reads as "outside git" — nothing is regrouped.
+ */
+export declare const checkoutOf: (dir: string, run?: (dir: string) => string) => Checkout | null;
+/**
+ * The project and label a `hwip-<tail>` session groups under, when its name
+ * does not say so — null when it does (the whole tail is the project).
+ *
+ * The one rule behind both the wrapper's session options and the listener's
+ * correction of sessions started without them, so the two never disagree.
+ * A tail starting `<repo>-` splits there, unless the rest is the wrapper's
+ * `-2`/`-3` family counter. Any session in a linked worktree belongs to its
+ * repo, whatever the worktree is called.
+ */
+export declare const groupOf: (tail: string, checkout: Checkout | null) => {
+    project: string;
+    label: string;
+} | null;
+export declare const PROJECT_DIR_ENV_VARS: readonly ["CLAUDE_PROJECT_DIR", "CURSOR_PROJECT_DIR", "WINDSURF_PROJECT_DIR"];
+/** First set project-dir env (unresolved `${VAR}` placeholders ignored), else cwd. */
+export declare const detectProjectDir: () => string;
+/**
+ * Why this machine should not trust `~/.hwip/config.json` as it stands, or null.
+ * 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 (and never write over it); otherwise only
+ * warn and restrict it. 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 command. Root may read what a user owns (sudo).
+ */
+export declare const configModeProblem: (st: {
+    uid: number;
+    mode: number;
+}, myUid: number, file?: string) => {
+    refuse: boolean;
+    why: string;
+} | null;
+export declare const loadConfig: () => HwipConfig;
+/** Why `config.json` is being ignored right now (it does not parse, or its mode refuses it), or null. For a log line or `hwip verify`. */
+export declare const configIgnoredBecause: () => string | null;
+/** The key about to be used is the config file's: none came by flag (`flagKey`) or `HWIP_API_KEY`. */
+export declare const keyIsFromFile: (flagKey: string | boolean | undefined, config: HwipConfig) => boolean;
+/**
+ * Why the config file's key must not go to `envBase`, an address from `HWIP_BASE_URL`, or null. The key belongs to
+ * the file's `baseUrl`, else the default API; only the same origin may carry it (C129).
+ */
+export declare const fileKeyBaseRefusal: (envBase: string, config: HwipConfig) => string | null;
+/**
+ * `url` as a base URL from `from`, before it is saved or sent anywhere: the same checks
+ * `resolveBaseUrl` applies (no user name or password in it, and an address at all).
+ */
+export declare const checkBaseUrl: (url: string, from: string) => string;
+/**
+ * Where the key goes: the flag, `HWIP_BASE_URL`, the file, else the default API. A file that
+ * cannot be read may hold a base URL the key belongs to (staging, self-hosted); falling to the
+ * default would send the key to another server, so that stops here instead. A file ignored for
+ * its mode is not trusted for a base URL on purpose, and the default stands.
+ *
+ * `keyFromFile` (see `keyIsFromFile`): the config file's key belongs to the addresses the file says (its
+ * `baseUrl`, else the default API), so an address from `HWIP_BASE_URL` on another origin stops here instead of
+ * receiving it (C129). A flag is the user's own word on this command and is followed; so is the environment's
+ * address when the key came by flag or `HWIP_API_KEY` too.
+ */
+export declare const resolveBaseUrl: (flagValue: string | boolean | undefined, config: HwipConfig, keyFromFile?: boolean) => string;
+/** `writeBlock` for the file as it is now. `install` and `login` ask first, so nothing is signed in to or verified for a save that cannot happen. */
+export declare const configWriteProblem: () => string | null;
+export declare const saveConfig: (config: HwipConfig) => void;
+export declare const VERSION: string;
+//# sourceMappingURL=config.d.ts.map