@hwip/cli 0.0.1 → 0.1.0

package/dist/private-files.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensurePrivateFile = exports.ensurePrivateDir = exports.mkdirExclusiveHandedBack = exports.createdHandedBack = exports.mkdirHandedBack = exports.handBackToSudoUser = exports.sudoOwner = void 0;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Where the API key lives (`~/.hwip`) is for its owner alone. `mkdir` and
+ * `open` apply their mode only on creation, so an older install — or a login
+ * under a loose umask — left the folder and the listener log readable by every
+ * local user. These make the mode what it should be whether the path is new or
+ * not. Best effort: a path owned by someone else cannot be changed here, and
+ * Windows has no such modes.
+ */
+const SUDO_ID = /^[1-9]\d{0,9}$/;
+/**
+ * Who a file hwip creates under the home folder belongs to when root runs it by `sudo` with HOME
+ * kept (macOS does): the person who typed `sudo`, so the next plain `hwip` can read what this
+ * one wrote. Null unless every sign agrees: root, `SUDO_UID`/`SUDO_GID` set to real ids, the path
+ * under the home folder, and the home folder owned by that same `SUDO_UID`. The last one is what
+ * stops a root whose HOME is `/root` (sudo resets it there on Linux) from handing root's folder
+ * to whoever ran `sudo`.
+ */
+const sudoOwner = (path) => {
+    if (process.getuid?.() !== 0)
+        return null;
+    const { SUDO_UID, SUDO_GID } = process.env;
+    if (!SUDO_UID || !SUDO_GID || !SUDO_ID.test(SUDO_UID) || !SUDO_ID.test(SUDO_GID))
+        return null;
+    try {
+        const home = (0, node_os_1.homedir)();
+        let realHome = home;
+        try {
+            realHome = (0, node_fs_1.realpathSync)(home);
+        }
+        catch {
+            /* lexical home is all there is */
+        }
+        let realDir = (0, node_path_1.dirname)(path);
+        try {
+            realDir = (0, node_fs_1.realpathSync)(realDir);
+        }
+        catch {
+            /* not there yet: lexical parent is all there is */
+        }
+        if (!(realDir === realHome || realDir.startsWith(realHome + node_path_1.sep)))
+            return null;
+        if ((0, node_fs_1.statSync)(home).uid !== Number(SUDO_UID))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { uid: Number(SUDO_UID), gid: Number(SUDO_GID) };
+};
+exports.sudoOwner = sudoOwner;
+/**
+ * Give a path root just created to the person who ran `sudo` (see `sudoOwner`). Best effort. The path
+ * itself, never what a link points at: whoever owns the folder can put a link where the new file was,
+ * and root following it would hand them a file of anyone's.
+ */
+const handBackToSudoUser = (path) => {
+    const owner = (0, exports.sudoOwner)(path);
+    if (!owner)
+        return;
+    try {
+        (0, node_fs_1.lchownSync)(path, owner.uid, owner.gid);
+    }
+    catch { /* not ours to change */ }
+};
+exports.handBackToSudoUser = handBackToSudoUser;
+/**
+ * `mkdir -p`: every folder it makes, not only the last, goes to the person who ran `sudo` when root
+ * makes it — a root-owned `~/.hwip` is one the next plain `hwip` cannot write in.
+ */
+const mkdirHandedBack = (dir, mode) => {
+    const made = [];
+    for (let at = dir; !(0, node_fs_1.existsSync)(at) && (0, node_path_1.dirname)(at) !== at; at = (0, node_path_1.dirname)(at))
+        made.push(at);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true, ...(mode === undefined ? {} : { mode }) });
+    for (const path of made)
+        (0, exports.handBackToSudoUser)(path);
+};
+exports.mkdirHandedBack = mkdirHandedBack;
+/**
+ * Create `path` without following a link at its end, handing the new file back
+ * when root made it (fd, never by name: a hardlink put there before shares the
+ * inode, and `lchown` by name would hand that inode over too). EEXIST (taken
+ * before, by anyone) and ELOOP (a link at the end) create nothing and hand
+ * nothing back — fail closed.
+ */
+const createExclusiveHandedBack = (path, mode) => {
+    const { O_CREAT, O_EXCL, O_WRONLY, O_NOFOLLOW } = node_fs_1.constants;
+    if (O_EXCL === undefined || O_NOFOLLOW === undefined)
+        return 'not-created';
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(path, O_CREAT | O_EXCL | O_WRONLY | O_NOFOLLOW, mode);
+    }
+    catch {
+        return 'not-created';
+    }
+    try {
+        const owner = (0, exports.sudoOwner)(path);
+        if (owner) {
+            try {
+                (0, node_fs_1.fchownSync)(fd, owner.uid, owner.gid);
+            }
+            catch { /* not ours to change */ }
+        }
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    return 'created';
+};
+/**
+ * Make sure `path` exists before a plain write fills it, handing it back when root made it. For a
+ * caller whose write line is better left alone (it sits next to code others are changing); the
+ * write that follows keeps the owner, since it opens the same file.
+ */
+const createdHandedBack = (path) => {
+    if ((0, node_fs_1.existsSync)(path))
+        return;
+    createExclusiveHandedBack(path, 0o600);
+};
+exports.createdHandedBack = createdHandedBack;
+/** `mkdir` without `-p`: fails with EEXIST when it is there, so the caller can tell who made it first. */
+const mkdirExclusiveHandedBack = (dir) => {
+    (0, node_fs_1.mkdirSync)(dir, { recursive: false });
+    (0, exports.handBackToSudoUser)(dir);
+};
+exports.mkdirExclusiveHandedBack = mkdirExclusiveHandedBack;
+/**
+ * The directory exists and only its owner can enter it (0700). A symlink is left
+ * as it is: it points at a folder that may be shared on purpose (dotfiles), and
+ * what it points at is not ours to lock.
+ *
+ * Opened without following a link and changed through what was opened, so the folder looked at is the
+ * one changed: by name, a link put there after the look got its target locked instead. Where the
+ * platform has no such open (Windows, which has no such modes either), by name as before.
+ *
+ * A folder its owner cannot read (0377) cannot be opened, yet others may still write into it, so that one
+ * too is changed by name — when it is a folder of the caller's own, and unless root runs this (by either of
+ * its ids): root is who could lock a file of someone else's through a link put there after the look. A person
+ * can only lock their own.
+ */
+const ensurePrivateDir = (dir) => {
+    (0, exports.mkdirHandedBack)(dir, 0o700);
+    try {
+        const { O_RDONLY, O_DIRECTORY, O_NOFOLLOW } = node_fs_1.constants;
+        if (O_DIRECTORY === undefined || O_NOFOLLOW === undefined) {
+            if (!(0, node_fs_1.lstatSync)(dir).isSymbolicLink())
+                (0, node_fs_1.chmodSync)(dir, 0o700);
+            return;
+        }
+        // A link here fails the open (ENOTDIR on macOS, seen 2026-10-14), which is the "left as it is" above.
+        let fd;
+        try {
+            fd = (0, node_fs_1.openSync)(dir, O_RDONLY | O_DIRECTORY | O_NOFOLLOW);
+        }
+        catch (err) {
+            const unreadable = err instanceof Error && 'code' in err && err.code === 'EACCES';
+            const asRoot = process.geteuid?.() === 0 || process.getuid?.() === 0;
+            if (!unreadable || asRoot)
+                throw err;
+            const seen = (0, node_fs_1.lstatSync)(dir);
+            const ownFolder = seen.isDirectory() && seen.uid === process.geteuid?.();
+            if (ownFolder)
+                (0, node_fs_1.chmodSync)(dir, 0o700);
+            return;
+        }
+        try {
+            (0, node_fs_1.fchmodSync)(fd, 0o700);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+    }
+    catch { /* not ours to change */ }
+};
+exports.ensurePrivateDir = ensurePrivateDir;
+/** The file exists and only its owner can read it (0600); its content is untouched. A link at the
+ *  end is left as it is: creating its target and then fixing only the link would leave a file of
+ *  someone's behind (C149 ②). An existing file is changed through an fd for the same reason. */
+const ensurePrivateFile = (path) => {
+    const existed = (0, node_fs_1.existsSync)(path);
+    if (!existed) {
+        if (createExclusiveHandedBack(path, 0o600) === 'created')
+            return;
+        if ((0, node_fs_1.lstatSync)(path, { throwIfNoEntry: false })?.isSymbolicLink())
+            return;
+    }
+    else if ((0, node_fs_1.lstatSync)(path, { throwIfNoEntry: false })?.isSymbolicLink()) {
+        return;
+    }
+    const { O_WRONLY, O_NOFOLLOW } = node_fs_1.constants;
+    if (O_NOFOLLOW === undefined) {
+        // No link-safe primitives on this platform: the legacy by-name path stays.
+        try {
+            (0, node_fs_1.closeSync)((0, node_fs_1.openSync)(path, 'a', 0o600));
+            (0, node_fs_1.chmodSync)(path, 0o600);
+        }
+        catch { /* not ours to change */ }
+        return;
+    }
+    try {
+        const fd = (0, node_fs_1.openSync)(path, O_WRONLY | O_NOFOLLOW);
+        try {
+            (0, node_fs_1.fchmodSync)(fd, 0o600);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+    }
+    catch { /* link swapped in after the look, or not ours to change */ }
+};
+exports.ensurePrivateFile = ensurePrivateFile;

package/dist/project-switch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A per-project on/off switch kept as local state files — one per project and one for every project — in the state
+ * directory (`gate.ts`'s, beside `muted-<hash>`). `ask-context` and `file-view` share it, so the rule that matters
+ * ("a switch file that cannot be read counts as off") is written once. A switch never reaches the server or the wire.
+ * No file means on.
+ */
+export type SwitchOffBy = 'env' | 'project' | 'global' | 'unreadable';
+export type SwitchScope = 'project' | 'global';
+/** The project a command or request belongs to: the repository root, else the directory itself, so a subfolder reads the same switch. */
+export declare const projectDirOf: (cwd: string, repoRoot?: (cwd: string) => string | null) => string;
+export interface ProjectSwitch {
+    /** Why the feature is off for this project, or `null` when it is on. The env variable turns it off for one run. */
+    offBy: (dir: string, env?: NodeJS.ProcessEnv) => SwitchOffBy | null;
+    /** Turn it on or off for this project, or for every project. Throws when the state file cannot be written or removed. */
+    set: (dir: string, on: boolean, scope: SwitchScope) => void;
+}
+/** The switch named `<name>` (state files `<name>-off-<project hash>` and `<name>-off-default`), also turned off by `envVar` for one run. */
+export declare const projectSwitch: (name: string, envVar: string) => ProjectSwitch;
+//# sourceMappingURL=project-switch.d.ts.map

package/dist/project-switch.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectSwitch = exports.projectDirOf = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const gate_js_1 = require("./gate.js");
+const private_files_js_1 = require("./private-files.js");
+const session_diff_js_1 = require("./session-diff.js");
+const OFF_WORDS = new Set(['0', 'false', 'off', 'no']);
+/** The project a command or request belongs to: the repository root, else the directory itself, so a subfolder reads the same switch. */
+const projectDirOf = (cwd, repoRoot = session_diff_js_1.repoRootOf) => repoRoot(cwd) ?? cwd;
+exports.projectDirOf = projectDirOf;
+/**
+ * Whether a state file is there. A file that cannot be told apart from absent (permissions, a broken state
+ * directory) counts as there: a switch someone turned off must not turn itself back on.
+ */
+const stateOf = (path) => {
+    try {
+        (0, node_fs_1.lstatSync)(path);
+        return 'present';
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? 'absent' : 'unreadable';
+    }
+};
+/** The switch named `<name>` (state files `<name>-off-<project hash>` and `<name>-off-default`), also turned off by `envVar` for one run. */
+const projectSwitch = (name, envVar) => {
+    const offFile = (scope, dir) => (0, node_path_1.join)((0, gate_js_1.stateDir)(), `${name}-off-${scope === 'global' ? 'default' : (0, gate_js_1.projectHash)(dir)}`);
+    return {
+        offBy: (dir, env = process.env) => {
+            if (OFF_WORDS.has((env[envVar] ?? '').trim().toLowerCase()))
+                return 'env';
+            for (const scope of ['project', 'global']) {
+                const state = stateOf(offFile(scope, dir));
+                if (state === 'present')
+                    return scope;
+                if (state === 'unreadable')
+                    return 'unreadable';
+            }
+            return null;
+        },
+        set: (dir, on, scope) => {
+            const file = offFile(scope, dir);
+            if (on) {
+                try {
+                    (0, node_fs_1.unlinkSync)(file);
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+                return;
+            }
+            (0, private_files_js_1.mkdirHandedBack)((0, gate_js_1.stateDir)());
+            (0, private_files_js_1.createdHandedBack)(file);
+            (0, node_fs_1.writeFileSync)(file, 'off\n');
+        },
+    };
+};
+exports.projectSwitch = projectSwitch;

package/dist/redact.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Text that may go to stderr, a log file or a crash line is cleaned of the API
+ * key first. The listener's socket URL carries it (`?apiKey=…`), and an error
+ * that quotes the URL — `Invalid URL: ws.hwip.app?apiKey=ak_…` — used to land,
+ * key and all, in `~/.hwip/listener.log`.
+ */
+export declare const redactSecrets: (text: string) => string;
+/** A key for a line that shows which one is in use: the prefix and no more (`ak_…`), never enough to guess from. */
+export declare const maskKey: (key: string) => string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskKey = exports.redactSecrets = void 0;
+/**
+ * Text that may go to stderr, a log file or a crash line is cleaned of the API
+ * key first. The listener's socket URL carries it (`?apiKey=…`), and an error
+ * that quotes the URL — `Invalid URL: ws.hwip.app?apiKey=ak_…` — used to land,
+ * key and all, in `~/.hwip/listener.log`.
+ */
+const redactSecrets = (text) => text
+    // `https://user:password@host` — a base URL with credentials in it, quoted by a fetch error. Up to the last
+    // `@` before the host, since a password can have one of its own; a quote, a comma or a space ends the
+    // address, so one after another in unrelated text is not run together.
+    .replace(/(\b[a-z][a-z0-9+.-]{0,31}:\/\/)[^\s/?#"'<>,]*@/gi, '$1***@')
+    .replace(/([?&]apiKey=)[^&\s"'<>]*/gi, '$1***')
+    .replace(/("apiKey"\s*:\s*")[^"]*"/gi, '$1***"')
+    .replace(/\bak_[A-Za-z0-9_.~-]{4,}/g, 'ak_***');
+exports.redactSecrets = redactSecrets;
+/** A key for a line that shows which one is in use: the prefix and no more (`ak_…`), never enough to guess from. */
+const maskKey = (key) => `${key.length > 4 ? key.slice(0, 3) : ''}…`;
+exports.maskKey = maskKey;