humanish 0.114.0 → 0.116.0

package/dist/run/escape-sequences.js

@@ -0,0 +1,93 @@
+// What a terminal draws with and what a URL encodes with, found in one pass. RunSecrets looks for a
+// value in a view of the text with the first dropped and the second decoded, so that a color code
+// or a percent escape inside a value does not hide it.
+const BEL = "\x07";
+const STRING_TERMINATOR = "\x1b\\";
+const between = (code, low, high) => code >= low && code <= high;
+const isHexDigit = (code) => between(code, 0x30, 0x39) || between(code, 0x41, 0x46) || between(code, 0x61, 0x66);
+/**
+ * The end of a control sequence whose parameter bytes start at `from`: parameter bytes, then
+ * intermediate bytes, then one final byte. -1 when no final byte follows.
+ */
+function controlSequenceEnd(text, from) {
+    let at = from;
+    while (at < text.length && between(text.charCodeAt(at), 0x30, 0x3f))
+        at += 1;
+    while (at < text.length && between(text.charCodeAt(at), 0x20, 0x2f))
+        at += 1;
+    return at < text.length && between(text.charCodeAt(at), 0x40, 0x7e) ? at + 1 : -1;
+}
+/** The end of the run of percent escapes that starts at `from`, or `from` when none does. */
+function percentRunEnd(text, from) {
+    let end = from;
+    while (end + 2 < text.length &&
+        text[end] === "%" &&
+        isHexDigit(text.charCodeAt(end + 1)) &&
+        isHexDigit(text.charCodeAt(end + 2)))
+        end += 3;
+    return end;
+}
+/**
+ * The stretches of the text a value's view drops or decodes, in order and without overlap, each
+ * as [start, end): operating-system commands (`ESC ]`), control sequences (`ESC [`) and the
+ * two-byte escapes `ESC 7`, `ESC 8`, `ESC =` and `ESC >`, raw or JSON-escaped (`\u001b`), and runs
+ * of percent escapes. An operating-system command ends at the first bell character after it or,
+ * with none after it, at the last `ESC \` in the text. A JSON-escaped one ends at the first
+ * backslash after it, which must start `\u0007` or `\u001b\\`. A start with no end is left as
+ * written. One regex of the six shapes finds the same stretches, in time quadratic in a run of
+ * unterminated commands; this takes time linear in the text.
+ */
+export function escapeSequences(text) {
+    const lastTerminator = text.lastIndexOf(STRING_TERMINATOR);
+    // The first bell character at or after the last place searched from. Starts only move forward,
+    // so each stretch of text is searched once.
+    let bel = text.indexOf(BEL);
+    const commandEnd = (start) => {
+        if (bel !== -1 && bel < start + 2)
+            bel = text.indexOf(BEL, start + 2);
+        if (bel !== -1)
+            return bel + 1;
+        return lastTerminator >= start + 2 ? lastTerminator + STRING_TERMINATOR.length : -1;
+    };
+    const jsonCommandEnd = (start) => {
+        const backslash = text.indexOf("\\", start + 7);
+        if (backslash === -1)
+            return -1;
+        if (text.startsWith("\\u0007", backslash))
+            return backslash + 6;
+        return text.startsWith("\\u001b\\\\", backslash) ? backslash + 8 : -1;
+    };
+    const endAt = (at) => {
+        switch (text[at]) {
+            case "\x1b": {
+                const next = text[at + 1];
+                if (next === "]")
+                    return commandEnd(at);
+                if (next === "[")
+                    return controlSequenceEnd(text, at + 2);
+                return next !== undefined && "78=>".includes(next) ? at + 2 : -1;
+            }
+            case "\\":
+                if (text.startsWith("\\u001b]", at))
+                    return jsonCommandEnd(at);
+                return text.startsWith("\\u001b[", at) ? controlSequenceEnd(text, at + 7) : -1;
+            case "%": {
+                const end = percentRunEnd(text, at);
+                return end === at ? -1 : end;
+            }
+            default:
+                return -1;
+        }
+    };
+    const sequences = [];
+    for (let at = 0; at < text.length;) {
+        const end = endAt(at);
+        if (end === -1)
+            at += 1;
+        else {
+            sequences.push([at, end]);
+            at = end;
+        }
+    }
+    return sequences;
+}

package/dist/run/evidence-files.d.ts

@@ -31,5 +31,12 @@ export type BoundedFileResult = {
 } | {
     state: "unavailable";
 };
-/** Size refusals are distinguished only after the same contained regular-file checks. */
+/** readUnchangedFile for an analysis input, whose path must also be an evidence path. */
 export declare function readBoundedFileResult(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;
+/**
+ * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
+ * same size and times, from the first check to the last. Size refusals are distinguished only after
+ * the same checks. `relativePath` uses `/`, and any name a contained read accepts
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ */
+export declare function readUnchangedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;

package/dist/run/evidence-files.js

@@ -2,11 +2,12 @@ import { constants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
 import { isPathInside, validatePreparedRunRootIdentity } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, } from "./contained-output.js";
+import { assertPreparedSelectedOutputDirectory, isSafeRelativeFilePath, readOpenedAtMost, } from "./contained-output.js";
 import { isNodeError } from "./type-guards.js";
 // Reading a file from a retained run directory for analysis: the path must be a plain relative path
 // inside the run, the file a single-link regular file that stays inside it, and the read bounded.
-// Evidence capture, analysis jobs, the analysis store, cost reading and export all read through here.
+// Evidence capture, analysis jobs, the analysis store, cost reading, verify and export all read
+// through here.
 /**
  * Analysis inputs are retained local artifacts, never URLs or caller-selected outputs. The path is
  * percent-decoded up to five times, and each round must still be a plain relative path, so an
@@ -88,9 +89,23 @@ export async function pathMissing(filePath) {
     }
 }
 const unavailable = { state: "unavailable" };
-/** Size refusals are distinguished only after the same contained regular-file checks. */
+/** readUnchangedFile for an analysis input, whose path must also be an evidence path. */
 export async function readBoundedFileResult(root, relativePath, maxBytes) {
-    if (!isEvidencePath(relativePath) || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    return isEvidencePath(relativePath)
+        ? readUnchangedFile(root, relativePath, maxBytes)
+        : unavailable;
+}
+/**
+ * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
+ * same size and times, from the first check to the last. Size refusals are distinguished only after
+ * the same checks. `relativePath` uses `/`, and any name a contained read accepts
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ */
+export async function readUnchangedFile(root, relativePath, maxBytes) {
+    if (!isSafeRelativeFilePath(relativePath) ||
+        relativePath.includes("\\") ||
+        !Number.isSafeInteger(maxBytes) ||
+        maxBytes < 1)
         return unavailable;
     const validateRoot = async () => {
         if ("physicalRunRoot" in root) {
@@ -133,26 +148,17 @@ export async function readBoundedFileResult(root, relativePath, maxBytes) {
         try {
             if (!sameFile(before, await handle.stat({ bigint: true })))
                 return unavailable;
-            const chunks = [];
-            let total = 0;
-            while (total <= maxBytes) {
-                const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
-                const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
-                if (bytesRead === 0)
-                    break;
-                total += bytesRead;
-                if (total > maxBytes)
-                    return unavailable;
-                chunks.push(chunk.subarray(0, bytesRead));
-            }
-            if (!sameFile(before, await handle.stat({ bigint: true })) || total !== Number(before.size))
+            const bytes = await readOpenedAtMost(handle, maxBytes);
+            if (bytes === null ||
+                !sameFile(before, await handle.stat({ bigint: true })) ||
+                bytes.length !== Number(before.size))
                 return unavailable;
             if ((await validateRoot()) !== physicalRoot)
                 return unavailable;
             await validateParents();
             if (!sameFile(before, await lstat(candidate, { bigint: true })))
                 return unavailable;
-            return { state: "read", bytes: Buffer.concat(chunks, total) };
+            return { state: "read", bytes };
         }
         finally {
             await handle.close();

package/dist/run/locate.d.ts

@@ -1,14 +1,43 @@
 import { type PreparedRunArtifactPaths } from "./paths.js";
-import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
+import { type ContainedRefusal, type PreparedSelectedOutputDirectory } from "./contained-output.js";
 import type { RunPointer } from "./results.js";
 import { type RunBundle } from "./bundle.js";
+import { type BoundedFileResult } from "./evidence-files.js";
 /** The run input that resolves through latest.json rather than naming a run directory. */
 export declare const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
 export declare function resolveRunPath(cwd: string, runInput: string): Promise<PreparedRunArtifactPaths | null>;
 export declare function readLatest(runsRoot: PreparedSelectedOutputDirectory): Promise<RunPointer | null>;
-export declare function readRunJsonIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<unknown>;
-export declare function readRunTextIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<string | null>;
+/** A run file as text: its text, nothing at the path, or why it was refused. */
+export type RunTextRead = {
+    status: "read";
+    text: string;
+} | {
+    status: "missing";
+} | ContainedRefusal;
+/** A run file as JSON. `value` is undefined when the file is there but is not valid JSON. */
+export type RunJsonRead = {
+    status: "read";
+    value: unknown;
+} | {
+    status: "missing";
+} | ContainedRefusal;
+/**
+ * The JSON, or null for a file that is missing, refused or not valid JSON: for a caller that
+ * treats the three alike, as every reader did before a refusal had its own state.
+ */
+export declare function runJsonValue(read: RunJsonRead): unknown;
+/** A run file as JSON, within RUN_ARTIFACT_MAX_BYTES. */
+export declare function readRunJsonIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<RunJsonRead>;
+/** A run file as text, within RUN_ARTIFACT_MAX_BYTES. */
+export declare function readRunTextIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<RunTextRead>;
+/**
+ * A run file, read whole through readUnchangedFile: `limit` when it holds more than
+ * RUN_ARTIFACT_MAX_BYTES, `unavailable` when it is missing, unsafe, or changes while it is read.
+ * A `\` in the path reads as `/`.
+ */
+export declare function readSafeRunArtifact(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<BoundedFileResult>;
+/** readSafeRunArtifact's bytes, or null for any file it does not read. */
 export declare function readSafeRunArtifactBytes(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<Buffer | null>;
 export declare function readSafeRunArtifactJson(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<unknown>;
 export declare function loadRunBundle(cwdInput: string, runInput: string): Promise<{

package/dist/run/locate.js

@@ -1,10 +1,9 @@
-import { lstat } from "node:fs/promises";
 import path from "node:path";
-import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDirectory, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, } from "./contained-output.js";
+import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDirectory, resolveLatestRunDirectory, RUNS_RELATIVE_ROOT, validatePreparedRunArtifactPaths, } from "./paths.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, ContainedReadRefusedError, LATEST_POINTER_MAX_BYTES, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isRunBundle, isRunPointer } from "./bundle-shape.js";
-import { isNodeError } from "./type-guards.js";
+import { readUnchangedFile } from "./evidence-files.js";
 /** The run input that resolves through latest.json rather than naming a run directory. */
 export const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
@@ -33,59 +32,61 @@ export async function resolveRunPath(cwd, runInput) {
     return bindExistingRunArtifactPaths(cwd, runInput);
 }
 export async function readLatest(runsRoot) {
-    const latestPath = path.join(runsRoot.physicalPath, "latest.json");
-    let latestStats;
-    try {
-        latestStats = await lstat(latestPath, { bigint: true });
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT") {
-            return null;
-        }
-        throw error;
-    }
-    if (latestStats.isSymbolicLink() || !latestStats.isFile() || latestStats.nlink !== 1n) {
-        throw new Error("Latest run pointer must be a single-link regular file.");
-    }
-    const bytes = await readContainedRegularFile(runsRoot, "latest.json");
-    if (!bytes) {
-        throw new Error("Latest run pointer changed while it was being read.");
+    const read = await readContainedRegularFile(runsRoot, "latest.json", LATEST_POINTER_MAX_BYTES);
+    if (read.status === "missing")
+        return null;
+    if (read.status === "refused") {
+        if (read.reason === "too-large")
+            throw new ContainedReadRefusedError(path.join(RUNS_RELATIVE_ROOT, "latest.json"), read);
+        throw new Error(read.reason === "not-regular" || read.reason === "directory"
+            ? "Latest run pointer must be a single-link regular file."
+            : "Latest run pointer changed while it was being read.");
     }
     let latest;
     try {
-        latest = JSON.parse(bytes.toString("utf8"));
+        latest = JSON.parse(read.bytes.toString("utf8"));
     }
     catch {
         return null;
     }
     return isRunPointer(latest) ? latest : null;
 }
+/**
+ * The JSON, or null for a file that is missing, refused or not valid JSON: for a caller that
+ * treats the three alike, as every reader did before a refusal had its own state.
+ */
+export function runJsonValue(read) {
+    return read.status === "read" ? (read.value ?? null) : null;
+}
+/** A run file as JSON, within RUN_ARTIFACT_MAX_BYTES. */
 export async function readRunJsonIfExists(runPaths, ...segments) {
-    const text = await readRunTextIfExists(runPaths, ...segments);
-    if (text === null) {
-        return null;
-    }
+    const read = await readRunTextIfExists(runPaths, ...segments);
+    if (read.status !== "read")
+        return read;
     try {
-        return JSON.parse(text);
+        return { status: "read", value: JSON.parse(read.text) };
     }
     catch {
-        return null;
+        return { status: "read", value: undefined };
     }
 }
+/** A run file as text, within RUN_ARTIFACT_MAX_BYTES. */
 export async function readRunTextIfExists(runPaths, ...segments) {
-    const bytes = await readContainedRegularFile(runPaths, segments.join("/"));
-    return bytes?.toString("utf8") ?? null;
+    const read = await readContainedRegularFile(runPaths, segments.join("/"), RUN_ARTIFACT_MAX_BYTES);
+    return read.status === "read" ? { status: "read", text: read.bytes.toString("utf8") } : read;
 }
+/**
+ * A run file, read whole through readUnchangedFile: `limit` when it holds more than
+ * RUN_ARTIFACT_MAX_BYTES, `unavailable` when it is missing, unsafe, or changes while it is read.
+ * A `\` in the path reads as `/`.
+ */
+export async function readSafeRunArtifact(runPaths, relativePath) {
+    return readUnchangedFile(runPaths, relativePath.replace(/\\/g, "/"), RUN_ARTIFACT_MAX_BYTES);
+}
+/** readSafeRunArtifact's bytes, or null for any file it does not read. */
 export async function readSafeRunArtifactBytes(runPaths, relativePath) {
-    const normalized = relativePath.replace(/\\/g, "/");
-    const segments = normalized.split("/");
-    if (path.isAbsolute(relativePath) ||
-        path.win32.isAbsolute(relativePath) ||
-        segments.length === 0 ||
-        segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
-        return null;
-    }
-    return readContainedRegularFile(runPaths, normalized);
+    const read = await readSafeRunArtifact(runPaths, relativePath);
+    return read.state === "read" ? read.bytes : null;
 }
 export async function readSafeRunArtifactJson(runPaths, relativePath) {
     const bytes = await readSafeRunArtifactBytes(runPaths, relativePath);
@@ -112,7 +113,11 @@ export async function loadRunBundlePrepared(cwdInput, runPaths) {
     const cwd = path.resolve(cwdInput);
     await validatePreparedRunArtifactPaths(runPaths);
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
-    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const read = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    // A run.json it refuses is no reason to call the run absent: the caller reports why.
+    if (read.status === "refused")
+        throw new ContainedReadRefusedError(RUN_BUNDLE_FILE, read);
+    const bundle = read.status === "read" ? read.value : null;
     if (!isRunBundle(bundle)) {
         return null;
     }

package/dist/run/note-files.d.ts

@@ -1,26 +1,8 @@
+import { type RunNote } from "./note-shape.js";
 import { type PreparedRunArtifactPaths } from "./paths.js";
 export declare const RUN_NOTES_DIR = "notes";
 /** The bytes one note file may hold: 2000 characters of text with JSON escapes, and its fields. */
 export declare const MAX_NOTE_FILE_BYTES: number;
-/** The notes one run keeps. A reader reads this many and names the rest. */
-export declare const MAX_RUN_NOTES = 500;
-export declare const MAX_NOTE_TEXT = 2000;
-export interface RunNote {
-    id: string;
-    /** Milliseconds from the run clock's start. */
-    atMs: number;
-    /** The participant's stream id, or null for a note on the whole run. */
-    participant: string | null;
-    /** The latest timed capture or event at or before the moment, with its participant. */
-    nearest: {
-        participant: string;
-        itemId: string;
-    } | null;
-    text: string;
-    author: string;
-    createdAt: string;
-    editedAt: string | null;
-}
 /** A run's notes as read, in the order they were added, and why any file was skipped. */
 export interface RunNotes {
     runId: string;
@@ -33,34 +15,34 @@ export declare function newRunNoteId(createdAt: Date): string;
 export declare function runNoteFile(id: string): string;
 /** The note as its file holds it. */
 export declare function encodeRunNote(note: RunNote, runId: string): string;
-/** The note in a note file's bytes, when it is a note of `runId` stored under its own `id`. */
-export declare function decodeRunNote(bytes: Buffer, runId: string, id: string): RunNote | null;
-/**
- * Up to MAX_LISTED_ENTRIES names in the notes directory at `dir`, or null when there is none.
- * Throws when `dir` is there and is not a plain directory.
- */
-export declare function listNoteEntries(dir: string): Promise<{
-    names: string[];
-    truncated: boolean;
-} | null>;
-/** The note ids to read from a listing of notes/, in creation order, and what was left out. */
-export declare function noteListing(listing: {
-    names: readonly string[];
-    truncated: boolean;
-}): {
-    ids: string[];
-    skipped: string[];
-};
 /** How many note files notes/ lists, without reading any. Throws when notes/ is unusable. */
 export declare function countRunNotes(prepared: PreparedRunArtifactPaths): Promise<number>;
 /**
- * The run's notes. Each file is read through the bounded reader, which refuses a link, a special
- * file or anything over MAX_NOTE_FILE_BYTES before reading past the limit; a file it refuses, or
- * that is not a note of this run, is skipped and named in `skipped`.
+ * Where a run's notes are read from: the run's id, its directory, and a reader of the files under
+ * it that refuses a link or a special file and stops at `maxBytes`.
  */
-export declare function readRunNotes(prepared: PreparedRunArtifactPaths): Promise<RunNotes>;
-/** What verify's text scan finds in shared notes: a secret-shaped value, or text it cannot read. */
-type NotesFinding = "sensitive" | "opaque";
+export interface RunNoteFiles {
+    readonly runId: string;
+    /** The run directory's physical path, once it is checked to be the directory bound. Throws otherwise. */
+    directory(): Promise<string>;
+    /** A file under the run directory: its bytes, "limit" when it holds more than `maxBytes`, or null. */
+    read(relativePath: string, maxBytes: number): Promise<Buffer | "limit" | null>;
+}
+/**
+ * The run's notes, read from its prepared paths through the bounded reader or through `from`, the
+ * files of a run the caller already holds (the served Observer passes its pinned root's). Each file
+ * is read within MAX_NOTE_FILE_BYTES; a file the reader refuses, or that is not a note of this run,
+ * is skipped and named in `skipped`.
+ */
+export declare function readRunNotes(from: PreparedRunArtifactPaths | RunNoteFiles): Promise<RunNotes>;
+/** What verify's text scan finds in notes about to be shared, and the share safety that gives them. */
+export interface NotesSharingProblem {
+    status: "local_only" | "blocked";
+    reason: {
+        code: "PUBLIC_SAFETY_FINDINGS" | "UNSCANNED_ARTIFACT";
+        message: string;
+    };
+}
 /**
  * The run's notes as a caller is about to share them, read once, with what verify's text scan
  * finds in that set as it would be shared. The caller shares this set only, so a note added or
@@ -68,6 +50,5 @@ type NotesFinding = "sensitive" | "opaque";
  */
 export declare function readNotesForSharing(prepared: PreparedRunArtifactPaths): Promise<{
     notes: RunNotes;
-    finding: NotesFinding | null;
+    problem: NotesSharingProblem | null;
 }>;
-export {};