@hwip/cli 0.0.1 → 0.1.0

package/dist/file-view.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Reading a session's repository for the phone's file view (F5): the one place
+ * the working tree is opened for it. Design: hwip `docs/file-view.md` (V1~V14,
+ * D1~D13); this module is V6, V7, V9, V10, V11, D4 and D5.
+ *
+ * What a path may be and what the phone may see of the tree is decided here and
+ * nowhere else. Nothing here knows about sealing, the wire or who asked — the
+ * listener decides that; this decides what is read and what is never opened.
+ *
+ * git is run only through `gitIn`, with constant arguments. What this module adds
+ * is `ls-files` (twice) for the visible set and `check-attr` (through `filteredPaths`)
+ * for `filter=`; `resolveBase` and `filteredPaths` bring their own `rev-parse` and
+ * `hash-object`. None of them runs a filter. One caller path goes to git, after `--`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBlob = exports.listTree = exports.visibleSet = exports.isViewablePath = exports.FILE_VIEW_MAX_BYTES = exports.TREE_PAGE_MAX_ENTRIES = void 0;
+const buffer_1 = require("buffer");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const secret_mask_js_1 = require("./secret-mask.js");
+const session_diff_js_1 = require("./session-diff.js");
+/** The longest path, in UTF-8 bytes, the phone may name. */
+const PATH_MAX_BYTES = 1024;
+/** Most entries in one page of a directory listing. */
+exports.TREE_PAGE_MAX_ENTRIES = 500;
+/** A file past this is not read. Same value as an untracked file's line count limit in the diff. */
+exports.FILE_VIEW_MAX_BYTES = session_diff_js_1.UNTRACKED_COUNT_MAX_BYTES;
+/** A NUL in this many leading bytes makes a file binary — the length git itself looks at. */
+const BINARY_PROBE_BYTES = 8000;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+/**
+ * V7 ①, the string rules. A path is repo-relative and names one thing: not empty
+ * (a directory request's `""` for the root is the tree handler's to allow), no NUL
+ * or other control character, not absolute, at most 1,024 UTF-8 bytes, and no
+ * segment that is empty, `.`, `..` or — at any depth, in any case — `.git` (a
+ * case-insensitive file system opens `.GIT` as `.git`, D11). A leading `-` is fine:
+ * the path only ever follows `--`.
+ */
+const isViewablePath = (path) => {
+    if (path === '' || path.startsWith('/') || CONTROL_CHARACTER.test(path))
+        return false;
+    if (buffer_1.Buffer.byteLength(path, 'utf-8') > PATH_MAX_BYTES)
+        return false;
+    return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..' && segment.toLowerCase() !== '.git');
+};
+exports.isViewablePath = isViewablePath;
+/** U+FFFD is what `gitIn` makes of a byte that is not UTF-8 (O1): such a name cannot be matched byte for byte. */
+const REPLACEMENT_CHARACTER = '\uFFFD';
+/**
+ * V6, the visible set: what git lists as tracked (`ls-files --stage`) plus what it lists as
+ * untracked and not ignored (`ls-files --others --exclude-standard`), under `scope` (the
+ * whole repository when absent). An ignored path is simply not there, so asking for it by
+ * name answers like a path that does not exist. The caller matches a path against the keys
+ * exactly; the pathspec only narrows what git has to print. A path the phone could never
+ * ask for (`isViewablePath`) or whose bytes are not UTF-8 is left out, so a listing never
+ * shows a name that cannot be opened.
+ */
+const visibleSet = (root, scope, deadline = (0, session_diff_js_1.newDeadline)()) => {
+    const pathspec = scope === undefined ? [] : ['--', scope];
+    const tracked = (0, session_diff_js_1.gitIn)(root, ['ls-files', '-z', '--stage', ...pathspec], deadline);
+    if (tracked.status !== 0)
+        return { ok: false, error: tracked.tooLarge ? 'too_large' : 'git_failed' };
+    const untracked = (0, session_diff_js_1.gitIn)(root, ['ls-files', '-z', '--others', '--exclude-standard', ...pathspec], deadline);
+    if (untracked.status !== 0)
+        return { ok: false, error: untracked.tooLarge ? 'too_large' : 'git_failed' };
+    const entries = new Map();
+    const admit = (path, entry) => {
+        if (path.includes(REPLACEMENT_CHARACTER) || !(0, exports.isViewablePath)(path))
+            return;
+        // A path in conflict is listed once per stage; the first row stands.
+        if (!entries.has(path))
+            entries.set(path, entry);
+    };
+    for (const record of tracked.stdout.split('\0')) {
+        // `<mode> <oid> <stage>\t<path>`
+        if (!record)
+            continue;
+        const tab = record.indexOf('\t');
+        // A row of another shape means git's output is not what this reads: say so, not "nothing is visible".
+        if (tab < 0)
+            return { ok: false, error: 'git_failed' };
+        const [mode, oid] = record.slice(0, tab).split(' ');
+        admit(record.slice(tab + 1), { mode, oid });
+    }
+    for (const record of untracked.stdout.split('\0')) {
+        if (!record)
+            continue;
+        if (record.endsWith('/'))
+            admit(record.slice(0, -1), { nested: true });
+        else
+            admit(record, {});
+    }
+    return { ok: true, entries };
+};
+exports.visibleSet = visibleSet;
+/** The errno of a file-system call that failed because nothing is there, or what is there cannot be followed. */
+const isGone = (e) => e instanceof Error && 'code' in e && (e.code === 'ENOENT' || e.code === 'ENOTDIR' || e.code === 'ELOOP');
+/**
+ * V7 ③: no directory of `dir` (a repo-relative path, `""` for none) is a symlink, and each is a directory. git does
+ * not track through a symlink, but a tracked directory can be replaced by one after the
+ * index was written. Walked a segment at a time with `lstat`, so a root that itself sits
+ * under a symlink (`/tmp` → `/private/tmp`) and a case-insensitive file system make no
+ * difference. A segment that does not exist ends the walk with a yes: there is nothing
+ * to follow there (a deleted file stays in the index until it is committed). null when the
+ * file system failed in some other way (permissions, I/O): that is not an answer about symlinks.
+ */
+const reachesWithoutSymlink = (root, dir) => {
+    let at = root;
+    for (const segment of dir === '' ? [] : dir.split('/')) {
+        at = (0, path_1.join)(at, segment);
+        try {
+            if (!(0, fs_1.lstatSync)(at).isDirectory())
+                return false;
+        }
+        catch (e) {
+            return isGone(e) ? true : null;
+        }
+    }
+    return true;
+};
+/** `a/b/c` → `a/b`; `c` → `""`. */
+const parentOf = (path) => path.slice(0, Math.max(0, path.lastIndexOf('/')));
+const entryTypeOf = (entry) => {
+    if (entry.nested || entry.mode === '160000')
+        return 'submodule';
+    return entry.mode === '120000' ? 'symlink' : 'file';
+};
+const utf8 = (text) => buffer_1.Buffer.from(text, 'utf-8');
+/**
+ * One page of the entries directly under `dir` (`""` is the repository root), by
+ * name in UTF-8 byte order. `cursor` is the last name of the page before; the page is
+ * at most `TREE_PAGE_MAX_ENTRIES` and `truncated` says there is more. A directory is
+ * only a name some visible path continues under, so an empty one, an ignored one and
+ * one that is not there are all `absent`.
+ */
+const listTree = (root, dir, cursor, deadline = (0, session_diff_js_1.newDeadline)()) => {
+    if (dir !== '' && !(0, exports.isViewablePath)(dir))
+        return { ok: false, error: 'bad_path' };
+    const set = (0, exports.visibleSet)(root, dir === '' ? undefined : dir, deadline);
+    if (!set.ok)
+        return set;
+    const prefix = dir === '' ? '' : `${dir}/`;
+    const found = new Map();
+    for (const [path, entry] of set.entries) {
+        if (!path.startsWith(prefix))
+            continue;
+        const rest = path.slice(prefix.length);
+        const slash = rest.indexOf('/');
+        if (slash < 0)
+            found.set(rest, entryTypeOf(entry));
+        else
+            found.set(rest.slice(0, slash), 'dir');
+    }
+    if (dir !== '' && found.size === 0)
+        return { ok: true, body: 'absent' };
+    const clear = reachesWithoutSymlink(root, dir);
+    if (clear === null)
+        return { ok: false, error: 'git_failed' };
+    if (!clear)
+        return { ok: true, body: 'absent' };
+    // Each name's bytes are made once: the sort would otherwise make two buffers per comparison.
+    const cursorBytes = cursor === undefined ? undefined : utf8(cursor);
+    const after = [...found]
+        .map(([name, type]) => ({ name, type, bytes: utf8(name) }))
+        .sort((a, b) => buffer_1.Buffer.compare(a.bytes, b.bytes))
+        .filter((entry) => cursorBytes === undefined || buffer_1.Buffer.compare(entry.bytes, cursorBytes) > 0);
+    const page = after.slice(0, exports.TREE_PAGE_MAX_ENTRIES).map(({ name, type }) => ({ name, type }));
+    const truncated = after.length > page.length;
+    return {
+        ok: true,
+        body: 'entries',
+        entries: page,
+        truncated,
+        ...(truncated ? { cursor: page[page.length - 1].name } : {}),
+    };
+};
+exports.listTree = listTree;
+/**
+ * D4: names that stay unread even when a repository tracks them. The list is code, not
+ * configuration. Compared on the last segment, ignoring case (the file systems that
+ * open `.GIT` as `.git` open `.ENV` as `.env`).
+ */
+const BLOCKED_NAME = /^(?:\.env(?:\..*)?|.*\.(?:pem|key|p12|pfx|keystore)|id_rsa.*|id_ed25519.*|credentials.*)$/;
+const ALLOWED_ENV_NAMES = new Set(['.env.example', '.env.sample']);
+const isBlockedName = (path) => {
+    const name = (path.split('/').pop() ?? '').toLowerCase();
+    return !ALLOWED_ENV_NAMES.has(name) && BLOCKED_NAME.test(name);
+};
+const ABSENT = { ok: true, body: 'absent' };
+const FILTERED = { ok: true, body: 'filtered' };
+/** Is `path` still, right now, a regular file with the identity of `opened`? */
+const sameFile = (path, opened) => {
+    try {
+        const now = (0, fs_1.lstatSync)(path, { bigint: true });
+        return now.isFile() && now.dev === opened.dev && now.ino === opened.ino;
+    }
+    catch (e) {
+        // Gone is a swap (false); anything else is the file system failing, which the caller's catch reports.
+        if (isGone(e))
+            return false;
+        throw e;
+    }
+};
+/** Read up to `limit` bytes from the start of `fd`; fewer when the file ends first. */
+const readUpTo = (fd, limit) => {
+    const buffer = buffer_1.Buffer.alloc(limit);
+    let filled = 0;
+    while (filled < limit) {
+        const n = (0, fs_1.readSync)(fd, buffer, filled, limit - filled, filled);
+        if (n === 0)
+            break;
+        filled += n;
+    }
+    return buffer.subarray(0, filled);
+};
+/**
+ * What a file looks like to the phone. The order is the design's V7: ① the string rules
+ * (`bad_path`) · ② the visible set, exact match · ③ no symlink on the way · ④ `lstat`: a
+ * symlink is shown as its target string and never followed, a gitlink or nested repository
+ * is shown as a submodule and never entered, anything but a regular file is `absent` ·
+ * D4 and V9 (`filter=`) say `filtered` · ⑤ open with `O_NOFOLLOW | O_NONBLOCK`, `fstat`
+ * the descriptor and compare it with ④ — a different file is `absent`, a hard link is
+ * `filtered` (D5) · V11: past 1 MiB is `too_large`, a NUL in the first 8,000 bytes is
+ * `binary` · V10: the whole text is masked before the caller pages it. A path outside the
+ * set, ignored, deleted or swapped is `absent`, never an error: the phone cannot tell them apart.
+ */
+const readBlob = (root, path, options = {}) => {
+    if (!(0, exports.isViewablePath)(path))
+        return { ok: false, error: 'bad_path' };
+    const deadline = options.deadline ?? (0, session_diff_js_1.newDeadline)();
+    const set = (0, exports.visibleSet)(root, path, deadline);
+    if (!set.ok)
+        return set;
+    const entry = set.entries.get(path);
+    if (!entry)
+        return ABSENT;
+    const parent = parentOf(path);
+    const clear = reachesWithoutSymlink(root, parent);
+    if (clear === null)
+        return { ok: false, error: 'git_failed' };
+    if (!clear)
+        return ABSENT;
+    if (entry.nested)
+        return { ok: true, body: 'submodule' };
+    if (entry.mode === '160000')
+        return { ok: true, body: 'submodule', commit: entry.oid };
+    const full = (0, path_1.join)(root, path);
+    options.beforeLstat?.();
+    let seen;
+    try {
+        // bigint: an inode past 2^53 (FUSE, NFS) would otherwise compare equal to its neighbour.
+        seen = (0, fs_1.lstatSync)(full, { bigint: true });
+    }
+    catch (e) {
+        return isGone(e) ? ABSENT : { ok: false, error: 'git_failed' };
+    }
+    if (seen.isSymbolicLink()) {
+        try {
+            return { ok: true, body: 'symlink', target: (0, fs_1.readlinkSync)(full) };
+        }
+        catch (e) {
+            // EINVAL: it stopped being a symlink since the lstat — a swap, like a vanished file.
+            const swapped = isGone(e) || (e instanceof Error && 'code' in e && e.code === 'EINVAL');
+            return swapped ? ABSENT : { ok: false, error: 'git_failed' };
+        }
+    }
+    if (!seen.isFile())
+        return ABSENT;
+    if (isBlockedName(path))
+        return FILTERED;
+    const base = (0, session_diff_js_1.resolveBase)(root, 'head', deadline);
+    if (!base.ok)
+        return base;
+    const filtered = (0, session_diff_js_1.filteredPaths)(root, [path], base.rev, deadline);
+    if (!filtered)
+        return { ok: false, error: 'git_failed' };
+    if (filtered.size > 0)
+        return FILTERED;
+    options.beforeOpen?.();
+    let fd;
+    try {
+        fd = (0, fs_1.openSync)(full, fs_1.constants.O_RDONLY | fs_1.constants.O_NOFOLLOW | fs_1.constants.O_NONBLOCK);
+    }
+    catch (e) {
+        // ELOOP is `O_NOFOLLOW` catching a symlink put there since the lstat; running out of descriptors is not "absent".
+        return isGone(e) ? ABSENT : { ok: false, error: 'git_failed' };
+    }
+    let bytes;
+    try {
+        const opened = (0, fs_1.fstatSync)(fd, { bigint: true });
+        if (!opened.isFile() || opened.dev !== seen.dev || opened.ino !== seen.ino)
+            return ABSENT;
+        // The walk and the `lstat` ran before the open; a directory swapped for a symlink in between would
+        // have made `seen` the outside file's. The descriptor is the one fixed thing: ask again, and the
+        // swap has to be undone and redone inside this window to pass.
+        const stillClear = reachesWithoutSymlink(root, parent);
+        if (stillClear === null)
+            return { ok: false, error: 'git_failed' };
+        if (!stillClear || !sameFile(full, opened))
+            return ABSENT;
+        if (opened.nlink !== 1n)
+            return FILTERED;
+        if (opened.size > BigInt(exports.FILE_VIEW_MAX_BYTES))
+            return { ok: false, error: 'too_large' };
+        // One byte past the limit: a file that grew after `fstat` is still caught.
+        bytes = readUpTo(fd, exports.FILE_VIEW_MAX_BYTES + 1);
+    }
+    catch {
+        // The file system failed under an open descriptor (EIO and the like): nothing was read.
+        return { ok: false, error: 'git_failed' };
+    }
+    finally {
+        try {
+            (0, fs_1.closeSync)(fd);
+        }
+        catch {
+            // intentionally ignored: the bytes (or the answer) are already in hand; a failed close of a read-only descriptor loses nothing.
+        }
+    }
+    if (bytes.length > exports.FILE_VIEW_MAX_BYTES)
+        return { ok: false, error: 'too_large' };
+    if (bytes.subarray(0, BINARY_PROBE_BYTES).includes(0))
+        return { ok: true, body: 'binary', size: bytes.length };
+    return { ok: true, body: 'text', ...(0, secret_mask_js_1.maskText)(bytes.toString('utf-8')) };
+};
+exports.readBlob = readBlob;

package/dist/gate.d.ts

@@ -0,0 +1,141 @@
+export type GateMarker = 'skip' | 'push' | 'high' | 'none';
+export type GatePushMode = 'quiet' | 'loud' | 'normal';
+export interface GateInput {
+    /** Total tool_use blocks this turn. */
+    toolCount: number;
+    /** Tools that are NOT read-only (Read/Grep/Glob). */
+    nonReadonlyCount: number;
+    /** A hwip_ask already notified this turn. */
+    alreadyAsked: boolean;
+    marker: GateMarker;
+    pushMode: GatePushMode;
+    /** The user is away from the terminal (presence.ts awayForGate) — lets quiet
+     *  push. Optional so existing callers keep compiling; absent = present,
+     *  matching the bash twin's missing 6th argument. */
+    away?: boolean;
+}
+export interface GateVerdict {
+    push: boolean;
+    priority: 'high' | 'normal';
+}
+/**
+ * "Assume real work" defaults for hooks that can't supply turn facts
+ * (most non-Claude agents pass no counts): in normal mode the push still
+ * fires — preserving the historical always-push behavior of the dumb
+ * hooks — while quiet/loud now work everywhere.
+ *
+ * These defaults cannot rescue a quiet dial: quiet only lets a `high` marker
+ * or an away user (presence.ts) through, and a hook with no turn facts has no
+ * marker either. That is why the installed templates pass `--pushmode-default
+ * normal` (see templates.ts) — for them quiet is not a lower volume, it is
+ * silence while the user is at the terminal.
+ */
+export declare const GATE_DEFAULTS: {
+    readonly toolCount: 2;
+    readonly nonReadonlyCount: 1;
+    readonly alreadyAsked: false;
+};
+export declare const normalizeMarker: (raw: string | undefined) => GateMarker;
+export declare const normalizePushMode: (raw: string | undefined) => GatePushMode;
+export declare const decidePush: (input: GateInput) => GateVerdict;
+export declare const stateDir: () => string;
+/**
+ * The first field of POSIX `cksum` over `data`: the CRC of the bytes, then of
+ * the length (low byte first, no trailing zero bytes), complemented.
+ */
+export declare const posixCksum: (data: Uint8Array) => number;
+/** `cksum` of the project dir as the plugin computes it. */
+export declare const projectHash: (dir: string) => string;
+/** Marker path for a project hash: `<stateDir>/remote-<cksum(projectDir)>`. */
+export declare const remoteMarkerPath: (hash: string) => string;
+/**
+ * sha256 over the ASCII-only-trimmed text — recorded at inject time,
+ * recomputed at prompt submit. Trim strips ONLY ' \t\r\n\f\v', NOT
+ * String.trim(): trim() also eats Unicode whitespace (U+00A0 etc.) that
+ * the bash reader keeps, and both sides must hash identical bytes.
+ */
+export declare const remoteDigest: (text: string) => string;
+/**
+ * How long REMOTE stays live without a refresh. Generous on purpose: the state
+ * is refreshed on every phone prompt and every answered `hwip_ask`, so it only
+ * has to outlive a working session, never an idle user. It is the backstop and
+ * not the usual exit — a terminal-typed prompt, a Done-like answer and the
+ * model's `<!-- hwip: exit -->` all delete the file outright. What none of them
+ * covers is a session that simply died: there is no SessionEnd hook, so without
+ * a TTL a crash or Ctrl-C would latch REMOTE forever.
+ */
+export declare const REMOTE_TTL_SEC = 14400;
+/** State path for a project hash: `<stateDir>/remote-active-<cksum(dir)>`. */
+export declare const remoteStatePath: (hash: string) => string;
+/**
+ * True while REMOTE is live for this project. A time ahead of the clock counts
+ * as now (and is rewritten as now). State that is expired or
+ * unparseable is deleted on sight — the same housekeeping a stale entry
+ * marker gets, since state that can never flag again is dead weight.
+ */
+export declare const isRemoteActive: (dir: string, now?: () => number) => boolean;
+/**
+ * Enter REMOTE, or push its expiry back. Best-effort by contract: the prompt
+ * hooks that call this must never fail a prompt over state IO.
+ */
+export declare const touchRemoteActive: (dir: string, now?: () => number) => void;
+/**
+ * Leave REMOTE. Best-effort like its twin: an absent file is success, and the
+ * caller is a hook with its own job to finish. Bash twin: gate.sh
+ * hwip_remote_clear.
+ */
+export declare const clearRemoteActive: (dir: string) => void;
+/** True when the user ran /hwip-mode mute for this project. */
+export declare const isMuted: (dir: string) => boolean;
+/**
+ * Push mode for an install that has never set a dial. The twin is
+ * plugin/hooks/gate.sh's missing-5th-argument default; the shared vectors
+ * never reach either one (every vector passes pushMode explicitly), so both
+ * sides pin it in their own tests.
+ */
+export declare const PUSHMODE_DEFAULT: GatePushMode;
+/**
+ * `notify` flag naming the push mode to assume when the project has no dial.
+ * Written by templates.ts into every hook-driven agent's completion hook and
+ * read back in cli.ts — shared so the two can never drift apart.
+ */
+export declare const PUSHMODE_DEFAULT_FLAG = "pushmode-default";
+/**
+ * `notify` flags carrying the turn's tool counts. Only the drop-in artifacts
+ * (pi extension, opencode plugin) can supply them — they are the only installed
+ * hooks that see per-tool events. Shared for the same reason as the flag above:
+ * templates.ts writes them, cli.ts reads them, and a rename on one side alone
+ * would send `gateCount` back to GATE_DEFAULTS with nothing to show for it.
+ */
+export declare const TOOL_COUNT_FLAG = "tools";
+export declare const NONREADONLY_COUNT_FLAG = "nonreadonly";
+/**
+ * The user's session push-mode dial (/hwip-mode quiet | /hwip-mode loud | /hwip-mode normal).
+ *
+ * Three failure shapes, three answers — "no dial" is the only one that gets
+ * the quiet default:
+ *   - no dial file          → `fallback` (PUSHMODE_DEFAULT unless the caller
+ *                             overrides it with --pushmode-default)
+ *   - unusable dial file    → normal. An unreadable
+ *                             file, or a garbled/empty value is a broken
+ *                             setting, and resolving breakage to silence
+ *                             leaves the user with no symptom to debug. The
+ *                             point of the new default is quiet, not hidden
+ *                             errors.
+ *   - readable dial file    → whatever it says.
+ */
+export declare const readPushMode: (dir: string, fallback?: GatePushMode) => GatePushMode;
+/**
+ * Push mode for a `--auto` notify: the user's dial if they set one, otherwise
+ * the mode named by `--pushmode-default`, otherwise the built-in quiet.
+ *
+ * The dial outranks the flag deliberately. The flag exists so an agent whose
+ * hook cannot participate in the heuristic still pushes out of the box; if it
+ * outranked the dial, `/hwip-mode quiet` would silently do nothing for that agent.
+ *
+ * A flag value that isn't one of the three modes resolves to `normal`, not to
+ * the quiet default — same rule as a garbled dial file. A caller that passes
+ * nonsense has a bug, and answering a bug with silence hides it.
+ */
+export declare const autoPushMode: (dir: string, flag: string | boolean | undefined) => GatePushMode;
+//# sourceMappingURL=gate.d.ts.map