@tinyviber/a2h 0.1.0

package/dist/util/safeRead.d.ts

@@ -0,0 +1,38 @@
+/** Opens a file read-only, refusing to follow a final-component symlink. */
+export declare function openNoFollow(path: string): number;
+/**
+ * Reads up to `maxBytes` from the head of a file.
+ * Returns undefined when the file cannot be read, or is a symlink.
+ */
+export declare function readHeadNoFollow(path: string, maxBytes: number): string | undefined;
+/** Reads up to `maxBytes` as raw bytes, with the same symlink guarantee. */
+export declare function readBytesNoFollow(path: string, maxBytes: number): Buffer | undefined;
+export interface BoundedRead {
+    text: string;
+    /** True when the file was longer than the cap and got cut. */
+    truncated: boolean;
+    totalBytes: number;
+}
+/**
+ * Reads a whole file, capped at `maxBytes`.
+ *
+ * Unlike `readFileText`, an unreadable file is reported as `undefined` rather
+ * than an empty string — the difference between "no content" and "refused to
+ * read" matters at a security boundary.
+ */
+export declare function readFileNoFollow(path: string, maxBytes: number): BoundedRead | undefined;
+export interface NoFollowStat {
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    size: number;
+}
+/**
+ * Metadata for a path, without following a final-component symlink.
+ *
+ * `statSync` would follow the link, so a link named `manifest.json` would look
+ * like a perfectly ordinary file of the target's size. `lstatSync` describes
+ * the link itself, which is what a caller deciding whether to read must know.
+ */
+export declare function statNoFollow(path: string): NoFollowStat | undefined;
+//# sourceMappingURL=safeRead.d.ts.map

package/dist/util/safeRead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeRead.d.ts","sourceRoot":"","sources":["../../src/util/safeRead.ts"],"names":[],"mappings":"AAqBA,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYnF;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYpF;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAmBxF;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAYnE"}

package/dist/util/safeRead.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openNoFollow = openNoFollow;
+exports.readHeadNoFollow = readHeadNoFollow;
+exports.readBytesNoFollow = readBytesNoFollow;
+exports.readFileNoFollow = readFileNoFollow;
+exports.statNoFollow = statNoFollow;
+const node_fs_1 = require("node:fs");
+// A2H reads files it did not create, in a directory tree it does not own. The
+// only thing standing between a workspace and the rest of the machine is that
+// A2H never follows a symlink out of it.
+//
+// Every read of workspace content goes through here. `O_NOFOLLOW` fails the
+// open if the final path component is a symlink, so a link named `notes.md`
+// pointing at `/etc/passwd` yields nothing rather than leaking a line of it
+// into the UI. Intermediate directory components are still traversed; callers
+// pair this with `resolveRealPath` so an intermediate link out of the tree is
+// caught before the read, not after.
+//
+// Nothing in this file trusts its caller to have checked anything.
+//
+// `O_NOFOLLOW` is absent on Windows; there the flag degrades to 0 and the
+// scanner's own symlink detection remains the control.
+const O_NOFOLLOW = typeof node_fs_1.constants.O_NOFOLLOW === 'number' ? node_fs_1.constants.O_NOFOLLOW : 0;
+/** Opens a file read-only, refusing to follow a final-component symlink. */
+function openNoFollow(path) {
+    return (0, node_fs_1.openSync)(path, node_fs_1.constants.O_RDONLY | O_NOFOLLOW);
+}
+/**
+ * Reads up to `maxBytes` from the head of a file.
+ * Returns undefined when the file cannot be read, or is a symlink.
+ */
+function readHeadNoFollow(path, maxBytes) {
+    let fd;
+    try {
+        fd = openNoFollow(path);
+        const buf = Buffer.alloc(maxBytes);
+        const n = (0, node_fs_1.readSync)(fd, buf, 0, maxBytes, 0);
+        return buf.subarray(0, n).toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            (0, node_fs_1.closeSync)(fd);
+    }
+}
+/** Reads up to `maxBytes` as raw bytes, with the same symlink guarantee. */
+function readBytesNoFollow(path, maxBytes) {
+    let fd;
+    try {
+        fd = openNoFollow(path);
+        const buf = Buffer.alloc(maxBytes);
+        const n = (0, node_fs_1.readSync)(fd, buf, 0, maxBytes, 0);
+        return buf.subarray(0, n);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            (0, node_fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Reads a whole file, capped at `maxBytes`.
+ *
+ * Unlike `readFileText`, an unreadable file is reported as `undefined` rather
+ * than an empty string — the difference between "no content" and "refused to
+ * read" matters at a security boundary.
+ */
+function readFileNoFollow(path, maxBytes) {
+    let fd;
+    try {
+        fd = openNoFollow(path);
+        const stat = (0, node_fs_1.fstatSync)(fd);
+        const totalBytes = stat.size;
+        const toRead = Math.min(totalBytes, maxBytes);
+        const buf = Buffer.alloc(toRead);
+        const n = (0, node_fs_1.readSync)(fd, buf, 0, toRead, 0);
+        return {
+            text: buf.subarray(0, n).toString('utf8'),
+            truncated: totalBytes > maxBytes,
+            totalBytes,
+        };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            (0, node_fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Metadata for a path, without following a final-component symlink.
+ *
+ * `statSync` would follow the link, so a link named `manifest.json` would look
+ * like a perfectly ordinary file of the target's size. `lstatSync` describes
+ * the link itself, which is what a caller deciding whether to read must know.
+ */
+function statNoFollow(path) {
+    try {
+        const st = (0, node_fs_1.lstatSync)(path);
+        return {
+            isFile: st.isFile(),
+            isDirectory: st.isDirectory(),
+            isSymbolicLink: st.isSymbolicLink(),
+            size: st.size,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=safeRead.js.map

package/dist/util/safeRead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeRead.js","sourceRoot":"","sources":["../../src/util/safeRead.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tinyviber/a2h",
+  "version": "0.1.0",
+  "description": "Agent to Human — turn messy agent workspaces into structured, human-readable local web interfaces.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "a2h": "bin/a2h.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.js",
+    "dev": "node scripts/copy-assets.js && node bin/a2h.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:acceptance": "node test/acceptance.cjs",
+    "fixtures": "node test/fixtures/generate.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "diff": "^7.0.0",
+    "markdown-it": "^14.1.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.0",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.10.0",
+    "playwright-core": "^1.49.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}