@herbertgao/pi-extensions 2026.8.9 → 2026.8.11

package/node_modules/@herbertgao/resume-from/dist/platform/config/validate.d.ts

@@ -0,0 +1,9 @@
+import type { ImportConfig } from "./contract.js";
+/**
+ * Completes and checks one parsed configuration file. Absent settings keep their default;
+ * a present but unusable one rejects with the field named (FR-56).
+ *
+ * @param baseDir directory a relative home is resolved against — the file's own directory.
+ * @param source the file's path, used as the field of a whole-file complaint.
+ */
+export declare function buildConfig(raw: unknown, baseDir: string, source: string): Promise<ImportConfig>;

package/node_modules/@herbertgao/resume-from/dist/platform/config/validate.js

@@ -0,0 +1,117 @@
+import { defaultConfig } from "./defaults.js";
+import { ConfigLoadError } from "./errors.js";
+import { resolveHomePath } from "./paths.js";
+// Exhaustive by construction: adding an agent (FR-57) fails to compile here until it is listed,
+// instead of silently rejecting the new value at run time.
+const AGENTS = { pi: true, codex: true, "claude-code": true };
+const SETTINGS = {
+    extraHomes: true,
+    budgetShare: true,
+    pinnedRecentTurns: true,
+    windowOverrides: true,
+};
+/**
+ * Completes and checks one parsed configuration file. Absent settings keep their default;
+ * a present but unusable one rejects with the field named (FR-56).
+ *
+ * @param baseDir directory a relative home is resolved against — the file's own directory.
+ * @param source the file's path, used as the field of a whole-file complaint.
+ */
+export async function buildConfig(raw, baseDir, source) {
+    const settings = asRecord(raw, source, `${source} must hold a JSON object of settings, such as { "budgetShare": 0.5 }.`);
+    for (const key of Object.keys(settings)) {
+        if (!Object.hasOwn(SETTINGS, key)) {
+            throw new ConfigLoadError(key, `${key} is not a setting. The settings are ${Object.keys(SETTINGS).join(", ")}. ` +
+                "Correct the spelling or remove the line.");
+        }
+    }
+    const config = defaultConfig();
+    if (settings.budgetShare !== undefined) {
+        config.budgetShare = asShare("budgetShare", settings.budgetShare);
+    }
+    if (settings.pinnedRecentTurns !== undefined) {
+        config.pinnedRecentTurns = asTurnCount("pinnedRecentTurns", settings.pinnedRecentTurns);
+    }
+    if (settings.extraHomes !== undefined) {
+        config.extraHomes = await asHomeEntries(settings.extraHomes, baseDir);
+    }
+    if (settings.windowOverrides !== undefined) {
+        config.windowOverrides = asWindowOverrides(settings.windowOverrides);
+    }
+    return config;
+}
+function asShare(field, value) {
+    // 0 is refused: it would make FR-33 block every import, which is a mistake, not a choice.
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1) {
+        throw new ConfigLoadError(field, `${field} must be a number greater than 0 and at most 1, for example 0.5. Found ${show(value)}.`);
+    }
+    return value;
+}
+function asTurnCount(field, value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new ConfigLoadError(field, `${field} must be a whole number of turns, zero or more, for example 8. Found ${show(value)}.`);
+    }
+    return value;
+}
+async function asHomeEntries(value, baseDir) {
+    const items = asArray(value, "extraHomes");
+    const entries = [];
+    for (const [index, item] of items.entries()) {
+        const field = `extraHomes[${index}]`;
+        const entry = asRecord(item, field, `${field} must be an object with an agent and a home, such as ` +
+            '{ "agent": "pi", "home": "~/.pi-work" }.');
+        entries.push({
+            agent: asAgentId(`${field}.agent`, entry.agent),
+            home: await resolveHomePath(asPath(`${field}.home`, entry.home), baseDir),
+        });
+    }
+    // Duplicates are kept: deduplication belongs to the search, which alone sees the
+    // adapter defaults an extra home may repeat.
+    return entries;
+}
+function asWindowOverrides(value) {
+    const items = asArray(value, "windowOverrides");
+    return items.map((item, index) => {
+        const field = `windowOverrides[${index}]`;
+        const entry = asRecord(item, field, `${field} must be an object with an agent and a windowTokens count, such as ` +
+            '{ "agent": "claude-code", "windowTokens": 200000 }.');
+        return {
+            agent: asAgentId(`${field}.agent`, entry.agent),
+            windowTokens: asWindowTokens(`${field}.windowTokens`, entry.windowTokens),
+        };
+    });
+}
+function asWindowTokens(field, value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new ConfigLoadError(field, `${field} must be a whole number of tokens greater than zero, for example 200000. ` +
+            `Found ${show(value)}.`);
+    }
+    return value;
+}
+function asAgentId(field, value) {
+    if (typeof value !== "string" || !Object.hasOwn(AGENTS, value)) {
+        throw new ConfigLoadError(field, `${field} must name a known agent: ${Object.keys(AGENTS).join(", ")}. Found ${show(value)}.`);
+    }
+    return value;
+}
+function asPath(field, value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ConfigLoadError(field, `${field} must be a path to an agent profile directory. Found ${show(value)}.`);
+    }
+    return value;
+}
+function asArray(value, field) {
+    if (!Array.isArray(value)) {
+        throw new ConfigLoadError(field, `${field} must be a list. Found ${show(value)}.`);
+    }
+    return value;
+}
+function asRecord(value, field, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ConfigLoadError(field, message);
+    }
+    return value;
+}
+function show(value) {
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}

package/node_modules/@herbertgao/resume-from/dist/platform/repo/contract.d.ts

@@ -0,0 +1,30 @@
+/** The repository the command runs in (FR-13). */
+export interface RepoIdentity {
+    /** Absolute path of the repository root, or null when the directory is not in a repository. */
+    root: string | null;
+    /** Current HEAD commit, or null when the repository has no commit yet. */
+    head: string | null;
+    branch: string | null;
+}
+/** How far the tree moved since the source session ran (FR-38). */
+export interface CommitDistance {
+    /** False when the source commit is unknown, or absent from this repository. */
+    known: boolean;
+    /** Commits on HEAD that the source commit does not have. */
+    ahead: number;
+    /** Commits the source commit has that HEAD does not. */
+    behind: number;
+}
+/** Process controls applied to every git command issued by one reader. */
+export interface RepoReaderOptions {
+    /** Maximum duration of one git command. Defaults to a finite module-owned limit. */
+    timeoutMs?: number | undefined;
+    /** Cancels the current command and every later command issued by this reader. */
+    signal?: AbortSignal | undefined;
+}
+/** Reads git state. It never writes to the repository. */
+export interface RepoReader {
+    identify(cwd: string): Promise<RepoIdentity>;
+    /** Compares HEAD with a commit of a source session (FR-37). */
+    distanceFrom(sourceCommit: string): Promise<CommitDistance>;
+}

package/node_modules/@herbertgao/resume-from/dist/platform/repo/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/platform/repo/module.md — the Public Contract section is the normative home.
+// Declarations only: no behaviour, no defaults. If this file and module.md disagree,
+// the document wins and this file is corrected.
+export {};

package/node_modules/@herbertgao/resume-from/dist/platform/repo/git.d.ts

@@ -0,0 +1,21 @@
+import type { RepoReaderOptions } from "./contract.js";
+export interface GitResult {
+    /** True when git exited 0. A non-zero exit is an answer ("no such revision"), not a failure. */
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Runs a read-only git command in `cwd`.
+ *
+ * Rejects only when git could not be run at all — a missing binary, a signal. An exit code is
+ * reported in `ok`, because the callers of this module treat "not a repository", "no commits yet"
+ * and "unknown revision" as facts to report rather than errors to raise.
+ */
+export declare function runGit(cwd: string, args: readonly string[], options?: RepoReaderOptions): Promise<GitResult>;
+interface NormalizedOptions {
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export declare function normalizeGitOptions(options: RepoReaderOptions): NormalizedOptions;
+export {};

package/node_modules/@herbertgao/resume-from/dist/platform/repo/git.js

@@ -0,0 +1,74 @@
+// The only place in this module that reaches git. The binary is spawned with an argument array and
+// never through a shell, so no revision string can ever be interpreted as a command.
+import { execFile } from "node:child_process";
+/** 1 MB. Every command here prints a line or two; more than this means something is wrong. */
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+/** Long enough for local repositories while still bounding a wedged filesystem or git process. */
+const DEFAULT_GIT_TIMEOUT_MS = 10_000;
+/**
+ * Runs a read-only git command in `cwd`.
+ *
+ * Rejects only when git could not be run at all — a missing binary, a signal. An exit code is
+ * reported in `ok`, because the callers of this module treat "not a repository", "no commits yet"
+ * and "unknown revision" as facts to report rather than errors to raise.
+ */
+export function runGit(cwd, args, options = {}) {
+    const processOptions = normalizeGitOptions(options);
+    return new Promise((resolve, reject) => {
+        const execOptions = {
+            encoding: "utf8",
+            env: gitEnv(),
+            maxBuffer: MAX_OUTPUT_BYTES,
+            timeout: processOptions.timeoutMs,
+            windowsHide: true,
+        };
+        if (processOptions.signal !== undefined)
+            execOptions.signal = processOptions.signal;
+        execFile("git", ["-C", cwd, ...args], execOptions, (error, stdout, stderr) => {
+            if (error === null) {
+                resolve({ ok: true, stdout, stderr });
+                return;
+            }
+            // execFile reports an exit code as a number and a genuine failure to run as a string code
+            // (ENOENT, EACCES) or a signal.
+            const exited = typeof error.code === "number" && !error.signal;
+            if (exited) {
+                resolve({ ok: false, stdout, stderr });
+                return;
+            }
+            reject(processError(cwd, processOptions, error));
+        });
+    });
+}
+export function normalizeGitOptions(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new RangeError("git timeoutMs must be a positive, finite integer");
+    }
+    return options.signal === undefined ? { timeoutMs } : { timeoutMs, signal: options.signal };
+}
+function processError(cwd, options, cause) {
+    if (options.signal?.aborted === true || cause.name === "AbortError") {
+        return new Error(`git command aborted while reading ${cwd}`, { cause });
+    }
+    if (cause.killed === true && cause.signal !== undefined) {
+        return new Error(`git command timed out after ${options.timeoutMs} ms while reading ${cwd}`, {
+            cause,
+        });
+    }
+    return new Error(`git could not run while reading ${cwd}: ${cause.message}`, {
+        cause,
+    });
+}
+function gitEnv() {
+    const env = { ...process.env };
+    // Never take the index lock: a read must not be able to leave a lock file behind or rewrite the
+    // index of a repository the user owns.
+    env.GIT_OPTIONAL_LOCKS = "0";
+    // These would override `-C` and point git at a repository other than the one being asked about,
+    // for example when the tool runs inside a git hook.
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    return env;
+}

package/node_modules/@herbertgao/resume-from/dist/platform/repo/index.d.ts

@@ -0,0 +1,2 @@
+export type { CommitDistance, RepoIdentity, RepoReader, RepoReaderOptions, } from "./contract.js";
+export { createRepoReader } from "./reader.js";

package/node_modules/@herbertgao/resume-from/dist/platform/repo/index.js

@@ -0,0 +1 @@
+export { createRepoReader } from "./reader.js";

package/node_modules/@herbertgao/resume-from/dist/platform/repo/reader.d.ts

@@ -0,0 +1,8 @@
+import type { RepoReader, RepoReaderOptions } from "./contract.js";
+/**
+ * A reader bound to one working directory.
+ *
+ * `identify` takes the directory to look at; `distanceFrom` compares against the HEAD of `cwd`,
+ * which is the repository the command is running in.
+ */
+export declare function createRepoReader(cwd?: string, options?: RepoReaderOptions): RepoReader;

package/node_modules/@herbertgao/resume-from/dist/platform/repo/reader.js

@@ -0,0 +1,130 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { normalizeGitOptions, runGit } from "./git.js";
+/** Nothing is known: `ahead` and `behind` are 0 so a caller cannot print a fabricated distance. */
+function unknownDistance() {
+    return { known: false, ahead: 0, behind: 0 };
+}
+function noRepository() {
+    return { root: null, head: null, branch: null };
+}
+/**
+ * Longer than any revision git can resolve: a full commit is 40 characters, a tag or a ref
+ * expression a few more. A longer string is a mistake or an attack, and is not sent to git.
+ */
+const MAX_REVISION_LENGTH = 256;
+/**
+ * A reader bound to one working directory.
+ *
+ * `identify` takes the directory to look at; `distanceFrom` compares against the HEAD of `cwd`,
+ * which is the repository the command is running in.
+ */
+export function createRepoReader(cwd = process.cwd(), options = {}) {
+    const processOptions = normalizeGitOptions(options);
+    const git = (directory, args) => runGit(directory, args, processOptions);
+    return {
+        identify: (directory) => identify(directory, git),
+        distanceFrom: (sourceCommit) => distanceFrom(cwd, sourceCommit, git),
+    };
+}
+async function identify(directory, git) {
+    const dir = resolve(directory);
+    const toplevel = await git(dir, ["rev-parse", "--show-toplevel"]);
+    if (!toplevel.ok)
+        return noRepository();
+    const root = await resolveFully(toplevel.stdout.trim());
+    if (root === null)
+        return noRepository();
+    return {
+        root,
+        head: await commitOf(dir, "HEAD", git),
+        branch: await branch(dir, git),
+    };
+}
+async function distanceFrom(cwd, sourceCommit, git) {
+    const revision = plausibleRevision(sourceCommit);
+    if (revision === null)
+        return unknownDistance();
+    const dir = resolve(cwd);
+    const source = await commitOf(dir, revision, git);
+    if (source === null)
+        return unknownDistance();
+    const from = await commitOf(dir, "HEAD", git);
+    if (from === null)
+        return unknownDistance();
+    // Both sides are commits git itself printed, so the range holds no caller input.
+    const counts = await git(dir, [
+        "rev-list",
+        "--left-right",
+        "--count",
+        `${from}...${source}`,
+        "--",
+    ]);
+    if (!counts.ok)
+        return unknownDistance();
+    const parts = counts.stdout.trim().split(/\s+/);
+    if (parts.length !== 2)
+        return unknownDistance();
+    const ahead = Number(parts[0]);
+    const behind = Number(parts[1]);
+    if (!Number.isInteger(ahead) || !Number.isInteger(behind))
+        return unknownDistance();
+    return { known: true, ahead, behind };
+}
+/** The commit a revision names, or null when this repository does not have it. */
+async function commitOf(dir, revision, git) {
+    // `--end-of-options` stops git reading the revision as an option, and `^{commit}` rejects a
+    // revision that exists but is not a commit.
+    const result = await git(dir, [
+        "rev-parse",
+        "--verify",
+        "--quiet",
+        "--end-of-options",
+        `${revision}^{commit}`,
+    ]);
+    const commit = result.stdout.trim();
+    return result.ok && commit !== "" ? commit : null;
+}
+/** The branch HEAD is on, or null when HEAD is detached. An unborn branch still has a name. */
+async function branch(dir, git) {
+    const result = await git(dir, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const name = result.stdout.trim();
+    return result.ok && name !== "" ? name : null;
+}
+/**
+ * A revision worth sending to git, trimmed, or null.
+ *
+ * A string that starts with `-` would be read as an option, an empty one names nothing, and a
+ * control character or an absurd length is never a revision. Rejecting them here means the hostile
+ * cases of T-REP-11 never reach a process at all.
+ */
+function plausibleRevision(sourceCommit) {
+    if (typeof sourceCommit !== "string")
+        return null;
+    const revision = sourceCommit.trim();
+    if (revision === "" || revision.length > MAX_REVISION_LENGTH)
+        return null;
+    if (revision.startsWith("-"))
+        return null;
+    if (hasControlCharacter(revision))
+        return null;
+    return revision;
+}
+/** A NUL cannot be passed to a process at all, and no control character belongs in a revision. */
+function hasControlCharacter(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** The real path of a directory, following symlinks, so paths compare as locations. */
+async function resolveFully(directory) {
+    try {
+        return await realpath(directory);
+    }
+    catch {
+        return null;
+    }
+}

package/node_modules/@herbertgao/resume-from/dist/platform/store/contract.d.ts

@@ -0,0 +1,31 @@
+/** Raw file content. */
+export type Bytes = Buffer;
+/** A file to create. Its path must not already exist (FR-49). */
+export interface PendingFile {
+    absolutePath: string;
+    bytes: Bytes;
+}
+/** Why a commit refused to run, or failed (FR-56). */
+export type CommitRefusal = "path-exists" | "not-writable" | "write-failed";
+/** A commit that succeeded and reports the paths it created (FR-52, FR-53). */
+export interface CommitHandle {
+    createdPaths: string[];
+}
+/** Raised when a commit refuses to run or fails. Carries an actionable message (FR-56). */
+export interface CommitError {
+    refusal: CommitRefusal;
+    /** The path that caused the refusal, when there is one. */
+    path: string | null;
+    /** What failed, and what the user can do next (FR-56). */
+    message: string;
+    /** Paths retained for safety or not removed by cleanup, when manual inspection may be required. */
+    remainingPaths?: string[];
+}
+/** Atomically adds zero or one file to a home (FR-49, FR-53). */
+export interface FileCommitter {
+    /**
+     * Creates zero or one file. Rejects with a CommitError before filesystem access when more than one
+     * file is supplied, or before writing bytes when the destination already exists.
+     */
+    commit(root: string, files: PendingFile[]): Promise<CommitHandle>;
+}

package/node_modules/@herbertgao/resume-from/dist/platform/store/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/platform/store/module.md — the Public Contract section is the normative home.
+// Declarations only: no behaviour, no defaults. If this file and module.md disagree,
+// the document wins and this file is corrected.
+export {};

package/node_modules/@herbertgao/resume-from/dist/platform/store/file-committer.d.ts

@@ -0,0 +1,3 @@
+import type { FileCommitter } from "./contract.js";
+/** Creates the guarded store. It holds no state between commits. */
+export declare function createFileCommitter(): FileCommitter;