humanish 0.104.3 → 0.106.0

package/dist/observer/library.js

@@ -0,0 +1,190 @@
+const STATUS_TONES = {
+    passed: "#3fb970",
+    running: "#4f8ff7",
+    failed: "#e5534b",
+    blocked: "#d29922",
+    timed_out: "#d29922",
+};
+export function renderLibraryHtml(history, opts) {
+    const emptyState = opts.safe
+        ? "No share_ready runs yet — run `humanish verify` to see why."
+        : "No runs yet — run `humanish watch` to create one.";
+    return `<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>humanish Library</title>
+<style>${libraryCss()}</style>
+</head>
+<body>
+<header class="bar">
+  <span class="mark">humanish</span>
+  <span class="title">Run Library</span>
+  <span class="mode">${escapeHtml(modeLabel(opts))}</span>
+</header>
+<main>
+  <p class="note" id="note" hidden></p>
+  <ul class="runs" id="runs"></ul>
+  <p class="empty" id="empty" hidden>${escapeHtml(emptyState)}</p>
+</main>
+<script type="application/json" id="serve-capabilities">${escapeJsonScript(opts.capabilities)}</script>
+<script type="application/json" id="library-data">${escapeJsonScript(history)}</script>
+<script>${libraryClientJs()}</script>
+</body>
+</html>
+`;
+}
+function modeLabel(opts) {
+    const auth = opts.mode === "exposed" ? "edge-authed" : opts.mode === "share-safe-open" ? "open" : "loopback";
+    return opts.safe ? `${auth} · share_ready only` : auth;
+}
+function libraryCss() {
+    return `
+:root { color-scheme: dark; }
+* { box-sizing: border-box; margin: 0; }
+body {
+  background: #0c0e12; color: #e6e8ec; min-height: 100vh;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+.bar {
+  display: flex; align-items: baseline; gap: 0.6rem;
+  padding: 1rem 1.1rem; border-bottom: 1px solid #1e222b;
+  position: sticky; top: 0; background: rgba(12,14,18,0.95); backdrop-filter: blur(6px);
+}
+.mark { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-weight: 600; color: #9aa3b2; }
+.title { font-weight: 600; }
+.mode { margin-left: auto; font-size: 0.75rem; color: #9aa3b2; font-family: ui-monospace, "SF Mono", Menlo, monospace; }
+main { padding: 1rem 1.1rem 3rem; max-width: 44rem; margin: 0 auto; }
+.note { font-size: 0.8rem; color: #d29922; padding: 0.5rem 0; }
+.runs { list-style: none; padding: 0; display: grid; gap: 0.6rem; }
+.runs a {
+  display: block; text-decoration: none; color: inherit;
+  border: 1px solid #1e222b; border-radius: 10px; padding: 0.8rem 0.9rem; background: #11141a;
+}
+.runs a:active { background: #171b23; }
+.run-top { display: flex; align-items: center; gap: 0.5rem; }
+.pip { width: 9px; height: 9px; border-radius: 50%; flex: none; }
+.pip.running { animation: pulse 1.6s ease-in-out infinite; }
+@keyframes pulse { 50% { opacity: 0.35; } }
+.run-id {
+  font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 0.8rem;
+  overflow-wrap: anywhere;
+}
+.badge {
+  margin-left: auto; flex: none; font-size: 0.65rem; text-transform: uppercase; letter-spacing: 0.06em;
+  border: 1px solid #2c5f8a; color: #7cb8ec; border-radius: 999px; padding: 0.1rem 0.5rem;
+}
+.badge.latest { border-color: #3fb970; color: #7ee2a8; }
+.run-meta { margin-top: 0.35rem; font-size: 0.75rem; color: #9aa3b2; }
+.empty { color: #9aa3b2; font-size: 0.85rem; padding: 2rem 0; text-align: center; }
+`;
+}
+function libraryClientJs() {
+    const tones = JSON.stringify(STATUS_TONES);
+    return `
+(function () {
+  var TONES = ${tones};
+  var POLL_MS = 15000;
+  var stopped = false;
+
+  function render(history) {
+    var list = document.getElementById("runs");
+    var empty = document.getElementById("empty");
+    list.textContent = "";
+    var runs = history.runs || [];
+    empty.hidden = runs.length !== 0;
+    for (var i = 0; i < runs.length; i += 1) {
+      var run = runs[i];
+      var item = document.createElement("li");
+      var link = document.createElement("a");
+      link.href = run.href;
+      var top = document.createElement("div");
+      top.className = "run-top";
+      var pip = document.createElement("span");
+      pip.className = run.status === "running" ? "pip running" : "pip";
+      pip.style.background = TONES[run.status] || "#57606f";
+      var id = document.createElement("span");
+      id.className = "run-id";
+      id.textContent = run.runId;
+      top.appendChild(pip);
+      top.appendChild(id);
+      if (run.runId === history.latestRunId) {
+        var latest = document.createElement("span");
+        latest.className = "badge latest";
+        latest.textContent = "latest";
+        top.appendChild(latest);
+      } else if (run.status === "running") {
+        var live = document.createElement("span");
+        live.className = "badge";
+        live.textContent = "live";
+        top.appendChild(live);
+      }
+      var meta = document.createElement("div");
+      meta.className = "run-meta";
+      var metaBits = [run.mode || "unknown", run.streamCount + " participants", run.createdAt || ""];
+      // Labeled cost token: ALWAYS "~$X est." (never a bare "$X"), so the library never implies an
+      // authoritative charge. Null = omitted (advisory, fail-open on display).
+      if (run.estimatedCostUsd != null) {
+        metaBits.push("~$" + Number(run.estimatedCostUsd).toFixed(2) + " est." + (run.costPlaceholder ? " (placeholder)" : ""));
+        if (run.costRatesAsOf) meta.title = "estimated, rates as of " + run.costRatesAsOf;
+      }
+      meta.textContent = metaBits.filter(Boolean).join(" \\u00b7 ");
+      link.appendChild(top);
+      link.appendChild(meta);
+      item.appendChild(link);
+      list.appendChild(item);
+    }
+  }
+
+  function note(text) {
+    var element = document.getElementById("note");
+    element.hidden = !text;
+    element.textContent = text || "";
+  }
+
+  function poll() {
+    if (stopped) return;
+    fetch("/_humanish/history.json", { cache: "no-store" }).then(function (response) {
+      return response.json();
+    }).then(function (history) {
+      if (history) {
+        note("");
+        render(history);
+      }
+    }).catch(function () {
+      note("connection lost \\u2014 retrying");
+    }).then(function () {
+      if (!stopped) setTimeout(poll, POLL_MS);
+    });
+  }
+
+  render(JSON.parse(document.getElementById("library-data").textContent));
+  setTimeout(poll, POLL_MS);
+})();
+`;
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            default:
+                return "&#39;";
+        }
+    });
+}
+function escapeJsonScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}

package/dist/observer/listen.js

@@ -0,0 +1,85 @@
+// One loopback bind for every humanish server, with the one failure people actually hit named.
+//
+// `listen EADDRINUSE` used to surface as HUMANISH_UNEXPECTED, the command-boundary catch-all for
+// "a handler threw" (#484). Something already serving on the port is the most expected condition
+// a serve command has: a second session, a forgotten background one, someone's dev server. It only
+// bites with an explicit --port, which is exactly when a person is asking for a stable address.
+export class PortInUseError extends Error {
+    port;
+    holder;
+    constructor(port, holder) {
+        super(holder === "humanish"
+            ? `port ${port} is already served by another humanish process on this machine; stop it, or pass --port 0 for a free port`
+            : `something else is already listening on 127.0.0.1:${port}; pass --port 0 for a free port, or stop it`);
+        this.port = port;
+        this.holder = holder;
+        this.name = "PortInUseError";
+    }
+}
+/**
+ * Is the process on this port one of ours? humanish's serve and observer servers answer
+ * `/_humanish/history.json` (serve) or `/observer-data.json` (observer) as JSON with a humanish
+ * schema; anything else is somebody's app. Bounded to half a second and never throws: a probe
+ * that cannot decide says "other", which is the answer that suggests the safer action.
+ */
+export async function probePortHolder(port, fetchFn = fetch) {
+    // The whole probe is raced against a hard clock as well: a fetch that ignores its abort signal
+    // (a test double, a proxy) must not turn "tell me whose port this is" into a hang.
+    let hardTimer;
+    const hardStop = new Promise((resolve) => {
+        hardTimer = setTimeout(() => resolve("other"), 1_500);
+        hardTimer.unref?.();
+    });
+    try {
+        return await Promise.race([probeRoutes(port, fetchFn), hardStop]);
+    }
+    finally {
+        clearTimeout(hardTimer);
+    }
+}
+async function probeRoutes(port, fetchFn) {
+    for (const route of ["/_humanish/history.json", "/observer-data.json"]) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 500);
+        try {
+            const response = await fetchFn(`http://127.0.0.1:${port}${route}`, {
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                continue;
+            const body = (await response.json());
+            if (typeof body?.schema === "string" && body.schema.startsWith("humanish."))
+                return "humanish";
+        }
+        catch {
+            // not ours, or not answering: keep probing, then say "other"
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return "other";
+}
+/** Bind on loopback only; resolve the port that was actually bound; name a taken port. */
+export function listenOnLoopback(server, port, probe = probePortHolder) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            if (error.code === "EADDRINUSE") {
+                void probe(port).then((holder) => reject(new PortInUseError(port, holder)));
+                return;
+            }
+            reject(error);
+        };
+        server.once("error", onError);
+        // Never beyond loopback; exposure only ever happens through a tunnel or proxy forwarding here.
+        server.listen(port, "127.0.0.1", () => {
+            server.off("error", onError);
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                reject(new Error("server did not bind to a TCP port"));
+                return;
+            }
+            resolve(address.port);
+        });
+    });
+}

package/dist/observer/live.d.ts

@@ -0,0 +1,9 @@
+import type { ObserverResult } from "./render.js";
+/**
+ * The Observer result for a run's in-progress files, handed to `onObserverReady` before the
+ * participants start. Nothing is rendered: the live server builds the page from run.json on each
+ * request, so only the paths are needed.
+ */
+export declare function liveObserverResult(cwd: string, runId: string, artifactRoot: string, warnings?: string[]): ObserverResult & {
+    ok: true;
+};

package/dist/observer/live.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * The Observer result for a run's in-progress files, handed to `onObserverReady` before the
+ * participants start. Nothing is rendered: the live server builds the page from run.json on each
+ * request, so only the paths are needed.
+ */
+export function liveObserverResult(cwd, runId, artifactRoot, warnings = []) {
+    const observerPath = path.join(artifactRoot, "observer", "index.html");
+    const observerDataPath = path.join(artifactRoot, "observer", "observer-data.json");
+    const eventsPath = path.join(artifactRoot, "events.ndjson");
+    return {
+        schema: "humanish.observer-result.v1",
+        ok: true,
+        cwd,
+        run: runId,
+        observerPath: path.relative(cwd, observerPath),
+        observerDataPath: path.relative(cwd, observerDataPath),
+        eventsPath: path.relative(cwd, eventsPath),
+        observerUrl: pathToFileURL(observerPath).href,
+        bundlePath: path.join(artifactRoot, "run.json"),
+        opened: false,
+        warnings,
+    };
+}

package/dist/observer/pinned-files.d.ts

@@ -0,0 +1,30 @@
+import type { BigIntStats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+/** internal: consumed by src/observer/serve.ts */
+export interface PinnedDirectory {
+    readonly birthtimeNs: bigint;
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly physicalPath: string;
+    /**
+     * When set, a file opens only if this accepts its root-relative path and the opened file's own
+     * stats, so a file added or changed after a check of the directory cannot be read.
+     */
+    readonly admitsFile?: (relativePath: string, stats: BigIntStats) => boolean;
+    /** When set, a file's bytes are served only if this accepts their sha256. */
+    readonly admitsContent?: (relativePath: string, sha256: string) => boolean;
+}
+export declare function readContainedFile(root: PinnedDirectory, filePathInput: string): Promise<Buffer | null>;
+export declare function openContainedFile(root: PinnedDirectory, filePathInput: string): Promise<{
+    handle: FileHandle;
+    size: number;
+} | null>;
+/** The sha256 of an opened file, read by position so the handle's own offset is untouched. */
+export declare function sha256OfOpenedFile(handle: FileHandle): Promise<string>;
+/** internal: consumed by src/observer/run-routes.ts */
+export declare function relativeToRoot(root: PinnedDirectory, filePathInput: string): string;
+/** internal: consumed by src/observer/serve.ts */
+export declare function pinDirectory(directoryInput: string): Promise<PinnedDirectory>;
+/** internal: consumed by src/observer/serve.ts */
+export declare function pinDirectChildDirectory(root: PinnedDirectory, name: string): Promise<PinnedDirectory | null>;
+export declare function assertPinnedDirectory(root: PinnedDirectory): Promise<void>;

package/dist/observer/pinned-files.js

@@ -0,0 +1,160 @@
+// Reads files under a pinned directory. pinDirectory records the directory's device, inode and
+// birth time; each read rechecks them, refuses a symlink anywhere on the path and accepts only a
+// single-link regular file, so a swapped or linked path cannot redirect the read.
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import path from "node:path";
+import { isPathInside, isSafeRunIdSegment } from "../run/paths.js";
+export async function readContainedFile(root, filePathInput) {
+    const opened = await openContainedFile(root, filePathInput);
+    if (!opened)
+        return null;
+    try {
+        const body = await opened.handle.readFile();
+        // A write that landed during the read changed the file's mtime and ctime.
+        if (root.admitsFile !== undefined &&
+            !root.admitsFile(relativeToRoot(root, filePathInput), await opened.handle.stat({ bigint: true }))) {
+            return null;
+        }
+        if (root.admitsContent !== undefined &&
+            !root.admitsContent(relativeToRoot(root, filePathInput), createHash("sha256").update(body).digest("hex"))) {
+            return null;
+        }
+        await assertPinnedDirectory(root);
+        return body;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await opened.handle.close();
+    }
+}
+export async function openContainedFile(root, filePathInput) {
+    const filePath = path.resolve(filePathInput);
+    if (!isPathInside(root.physicalPath, filePath))
+        return null;
+    let handle = null;
+    try {
+        await assertPinnedDirectory(root);
+        const expectedStats = await inspectContainedRegularFile(root, filePath);
+        if (!expectedStats)
+            return null;
+        handle = await open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        const openedStats = await handle.stat({ bigint: true });
+        if (!openedStats.isFile() ||
+            openedStats.nlink !== 1n ||
+            openedStats.dev !== expectedStats.dev ||
+            openedStats.ino !== expectedStats.ino ||
+            (root.admitsFile !== undefined &&
+                !root.admitsFile(relativeToRoot(root, filePath), openedStats))) {
+            await handle.close();
+            return null;
+        }
+        const recheckedStats = await inspectContainedRegularFile(root, filePath);
+        if (!recheckedStats ||
+            recheckedStats.dev !== expectedStats.dev ||
+            recheckedStats.ino !== expectedStats.ino) {
+            await handle.close();
+            return null;
+        }
+        await assertPinnedDirectory(root);
+        return { handle, size: Number(openedStats.size) };
+    }
+    catch {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        return null;
+    }
+}
+/** The sha256 of an opened file, read by position so the handle's own offset is untouched. */
+export async function sha256OfOpenedFile(handle) {
+    const hash = createHash("sha256");
+    const buffer = Buffer.alloc(1 << 20);
+    for (let position = 0;;) {
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+        if (bytesRead === 0)
+            return hash.digest("hex");
+        hash.update(buffer.subarray(0, bytesRead));
+        position += bytesRead;
+    }
+}
+/** internal: consumed by src/observer/run-routes.ts */
+export function relativeToRoot(root, filePathInput) {
+    return path.relative(root.physicalPath, path.resolve(filePathInput)).split(path.sep).join("/");
+}
+async function inspectContainedRegularFile(root, filePath) {
+    const relative = path.relative(root.physicalPath, filePath);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return null;
+    }
+    const segments = relative.split(path.sep).filter(Boolean);
+    let current = root.physicalPath;
+    let fileIdentity = null;
+    for (const [index, segment] of segments.entries()) {
+        current = path.join(current, segment);
+        const stats = await lstat(current, { bigint: true });
+        if (stats.isSymbolicLink())
+            return null;
+        if (index < segments.length - 1) {
+            if (!stats.isDirectory())
+                return null;
+        }
+        else {
+            if (!stats.isFile() || stats.nlink !== 1n)
+                return null;
+            fileIdentity = { dev: stats.dev, ino: stats.ino };
+        }
+    }
+    if ((await realpath(filePath)) !== filePath)
+        return null;
+    return fileIdentity;
+}
+/** internal: consumed by src/observer/serve.ts */
+export async function pinDirectory(directoryInput) {
+    const physicalPath = await realpath(path.resolve(directoryInput));
+    const stats = await lstat(physicalPath, { bigint: true });
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new Error("Observer roots must be physical directories.");
+    }
+    return Object.freeze({
+        birthtimeNs: stats.birthtimeNs,
+        dev: stats.dev,
+        ino: stats.ino,
+        physicalPath,
+    });
+}
+/** internal: consumed by src/observer/serve.ts */
+export async function pinDirectChildDirectory(root, name) {
+    if (!isSafeRunIdSegment(name))
+        return null;
+    try {
+        await assertPinnedDirectory(root);
+        const candidate = path.join(root.physicalPath, name);
+        const pinned = await pinDirectory(candidate);
+        if (pinned.physicalPath !== candidate ||
+            path.dirname(pinned.physicalPath) !== root.physicalPath) {
+            return null;
+        }
+        await assertPinnedDirectory(root);
+        return pinned;
+    }
+    catch {
+        return null;
+    }
+}
+export async function assertPinnedDirectory(root) {
+    const stats = await lstat(root.physicalPath, { bigint: true });
+    if (stats.isSymbolicLink() ||
+        !stats.isDirectory() ||
+        stats.birthtimeNs !== root.birthtimeNs ||
+        stats.dev !== root.dev ||
+        stats.ino !== root.ino ||
+        (await realpath(root.physicalPath)) !== root.physicalPath) {
+        throw new Error("Observer root identity changed.");
+    }
+}

package/dist/observer/render.d.ts

@@ -0,0 +1,69 @@
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import { type ObserverRuntimeStreamUrl } from "./run-routes.js";
+declare const OBSERVER_SCHEMA = "humanish.observer-result.v1";
+export interface ObserverResult {
+    schema: typeof OBSERVER_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    run: string;
+    observerPath?: string;
+    observerDataPath?: string;
+    eventsPath?: string;
+    observerUrl?: string;
+    serverUrl?: string;
+    bundlePath?: string;
+    opened?: boolean;
+    openCommand?: string;
+    warnings: string[];
+    error?: {
+        code: "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_INVALID_RUN_BUNDLE";
+        message: string;
+    };
+}
+export interface ObserverOptions {
+    open?: boolean;
+    /** Internal producer pin: refreshing a finished run must not bind a replacement. */
+    expectedRun?: PreparedRunArtifactPaths;
+}
+export interface ObserverServeOptions {
+    open?: boolean;
+    port?: number;
+    /** Restrict history and evidence routes to the selected run. Exposed viewers always do this. */
+    scope?: "run" | "library";
+    exposed?: boolean;
+}
+export interface ObserverServer {
+    url: string;
+    port: number;
+    opened: boolean;
+    openCommand?: string;
+    warning?: string;
+    addPublicOrigin(origin: string): void;
+    close(): Promise<void>;
+}
+export declare function attachObserverRuntimeStreamUrls(result: ObserverResult, streams: ObserverRuntimeStreamUrl[]): void;
+export declare function renderObserver(cwdInput: string, runInput: string, options?: ObserverOptions): Promise<ObserverResult>;
+export declare function serveObserver(result: ObserverResult, options?: ObserverServeOptions): Promise<ObserverServer>;
+/** The host facts that decide whether a desktop browser can open a target. */
+export interface DesktopOpenerHost {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    /** Whether an executable with this name is on the host's PATH. */
+    onPath(name: string): boolean;
+}
+/**
+ * The command that opens a target in the desktop browser, or why this host has none. Linux needs
+ * a display and xdg-open; without them the opener would exit quietly and nothing would appear.
+ */
+export declare function desktopOpener(target: string, host: DesktopOpenerHost): {
+    command: string;
+    args: string[];
+} | {
+    reason: string;
+};
+export declare function openTarget(target: string, host?: DesktopOpenerHost): {
+    opened: boolean;
+    command?: string;
+    warning?: string;
+};
+export {};