@cad0p/pi-steering 0.1.0

package/dist/__test-helpers__.d.ts

@@ -0,0 +1,95 @@
+import type { ExtensionContext, ExecResult as PiExecResult } from "@earendil-works/pi-coding-agent";
+import type { EvaluatorHost } from "./evaluator-internals/context.ts";
+/**
+ * Per-test scratch `$HOME` fixture. Registers `beforeEach` /
+ * `afterEach` that:
+ *
+ *   - `mkdtempSync` a fresh temp dir using `prefix`,
+ *   - save `process.env["HOME"]`, point it at the temp dir,
+ *   - restore `process.env["HOME"]` and recursively remove the temp
+ *     dir on teardown.
+ *
+ * Used by every test surface that exercises the loader walk-up
+ * (`index.test.ts`, `loader.test.ts`, `internal/session-runtime.test.ts`)
+ * so the per-file scratch-HOME boilerplate stays in one place.
+ *
+ * The temp dir path is exposed via the optional `onReady` callback,
+ * fired inside `beforeEach`; tests typically stash it in a
+ * describe-scoped `let` for terser reads.
+ */
+export declare function useIsolatedHome(prefix: string, onReady?: (tmp: string) => void): void;
+/**
+ * Like {@link useIsolatedHome} but also chdirs into the scratch dir, so factory-time tests find the per-test config via the loader walk-up. macOS tmpdir is a symlink; canonicalized via `realpathSync` so cwd-mismatch tests don't see false-divergence.
+ */
+export declare function useScratchHome(prefix: string, onReady?: (tmp: string) => void): void;
+/**
+ * Write a single-file steering config to `<dir>/.pi/steering.ts`.
+ * `body` is the full module source (must include `export default`).
+ * Used by suites whose fixtures embed regex literals or other
+ * non-JSON-friendly module shapes inline.
+ */
+export declare function writeSteeringSingleFileConfig(dir: string, body: string): void;
+/**
+ * Write a directory-form steering config to
+ * `<dir>/.pi/steering/index.ts`. `body` is the full module source
+ * (must include `export default`). Mirrors the layout the bin tests
+ * use for their isolated `@cad0p/pi-steering` invocations.
+ */
+export declare function writeSteeringDirConfig(dir: string, body: string): void;
+/**
+ * Exact shape pi's `sessionManager.getEntries()` returns for entries
+ * produced by `appendEntry`. The evaluator filters to `type: "custom"`,
+ * matches by `customType`, and reads `{ data, timestamp }` — other
+ * fields (`id`, `parentId`) exist on real entries so we mirror them
+ * here to avoid silent type drift.
+ */
+export interface CustomEntry {
+    readonly type: "custom";
+    readonly customType: string;
+    readonly data: unknown;
+    readonly timestamp: string;
+    readonly id: string;
+    readonly parentId: string | null;
+}
+/**
+ * Minimal stub for pi's `ExtensionContext`. Only the fields the
+ * evaluator + observer-dispatcher read are populated; everything else
+ * throws if touched so accidental reliance on unsupported surface
+ * breaks loudly.
+ *
+ * The `entries` array mimics `sessionManager.getEntries()` output —
+ * tests that want cross-handler `findEntries` visibility pass
+ * `host.entries` (from {@link makeTrackedHost}) here so the host's
+ * `appendEntry` writes show up on subsequent reads.
+ */
+export declare function makeCtx(cwd: string, entries?: ReadonlyArray<CustomEntry>): ExtensionContext;
+/**
+ * Tracked {@link EvaluatorHost} recording every exec / appendEntry
+ * call so tests can assert memoization + audit logging.
+ *
+ * `entries` is the backing array `makeCtx` wraps when tests want the
+ * host's `appendEntry` writes visible to a later `findEntries` read.
+ * Timestamps are monotonically-incrementing second-level ISO strings
+ * so ordering asserts stay stable inside the same millisecond.
+ */
+export interface TrackedHost extends EvaluatorHost {
+    readonly execCalls: Array<{
+        cmd: string;
+        args: string[];
+        cwd: string;
+    }>;
+    readonly appended: Array<{
+        type: string;
+        data: unknown;
+    }>;
+    readonly entries: CustomEntry[];
+}
+/**
+ * Build a {@link TrackedHost}. Optional `exec` override lets evaluator
+ * tests count real invocations against the cache (the default exec
+ * returns `{ stdout: "", stderr: "", code: 0, killed: false }`).
+ */
+export declare function makeTrackedHost(options?: {
+    exec?: (cmd: string, args: string[], cwd: string) => Promise<PiExecResult>;
+}): TrackedHost;
+//# sourceMappingURL=__test-helpers__.d.ts.map

package/dist/__test-helpers__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__test-helpers__.d.ts","sourceRoot":"","sources":["../src/__test-helpers__.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,IAAI,YAAY,EAC3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAMtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC9B,IAAI,CAcN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC9B,IAAI,CAkBN;AAMD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAG7E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAItE;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CACrB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,aAAa,CAAC,WAAW,CAAM,GACvC,gBAAgB,CAUlB;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE;IACxC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5E,GAAG,WAAW,CA+Bd"}

package/dist/__test-helpers__.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Shared test-double helpers.
+ *
+ * `evaluator.test.ts` and `observer-dispatcher.test.ts` both need:
+ *
+ *   - a minimal {@link ExtensionContext} stub whose `sessionManager`
+ *     only exposes `getEntries()` (everything else throws on access),
+ *   - a "tracked host" {@link EvaluatorHost} that records every
+ *     `exec` / `appendEntry` call plus pushes `appendEntry` payloads
+ *     into an entries array shaped like the pi session JSONL, so the
+ *     same array can back a `makeCtx` stub and let tests assert
+ *     cross-handler `findEntries` visibility.
+ *
+ * The two former copies diverged only in whether `makeHost` accepted an
+ * `exec` override (evaluator tests need it to count child-process
+ * invocations for the memoization assertions; observer tests don't).
+ * That's now a single option on the unified helper.
+ *
+ * Kept OUT of the public surface: `__test-helpers__` is a leading-double-
+ * underscore convention indicating "test only"; nothing under `src/`
+ * imports it at runtime.
+ */
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach } from "node:test";
+// ---------------------------------------------------------------------------
+// Isolated $HOME fixture
+// ---------------------------------------------------------------------------
+/**
+ * Per-test scratch `$HOME` fixture. Registers `beforeEach` /
+ * `afterEach` that:
+ *
+ *   - `mkdtempSync` a fresh temp dir using `prefix`,
+ *   - save `process.env["HOME"]`, point it at the temp dir,
+ *   - restore `process.env["HOME"]` and recursively remove the temp
+ *     dir on teardown.
+ *
+ * Used by every test surface that exercises the loader walk-up
+ * (`index.test.ts`, `loader.test.ts`, `internal/session-runtime.test.ts`)
+ * so the per-file scratch-HOME boilerplate stays in one place.
+ *
+ * The temp dir path is exposed via the optional `onReady` callback,
+ * fired inside `beforeEach`; tests typically stash it in a
+ * describe-scoped `let` for terser reads.
+ */
+export function useIsolatedHome(prefix, onReady) {
+    let tmp;
+    let priorHome;
+    beforeEach(() => {
+        tmp = mkdtempSync(join(tmpdir(), prefix));
+        priorHome = process.env["HOME"];
+        process.env["HOME"] = tmp;
+        onReady?.(tmp);
+    });
+    afterEach(() => {
+        if (priorHome === undefined)
+            delete process.env["HOME"];
+        else
+            process.env["HOME"] = priorHome;
+        rmSync(tmp, { recursive: true, force: true });
+    });
+}
+/**
+ * Like {@link useIsolatedHome} but also chdirs into the scratch dir, so factory-time tests find the per-test config via the loader walk-up. macOS tmpdir is a symlink; canonicalized via `realpathSync` so cwd-mismatch tests don't see false-divergence.
+ */
+export function useScratchHome(prefix, onReady) {
+    let tmp;
+    let priorHome;
+    let priorCwd;
+    beforeEach(() => {
+        priorCwd = process.cwd();
+        tmp = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+        priorHome = process.env["HOME"];
+        process.env["HOME"] = tmp;
+        process.chdir(tmp);
+        onReady?.(tmp);
+    });
+    afterEach(() => {
+        process.chdir(priorCwd);
+        if (priorHome === undefined)
+            delete process.env["HOME"];
+        else
+            process.env["HOME"] = priorHome;
+        rmSync(tmp, { recursive: true, force: true });
+    });
+}
+// ---------------------------------------------------------------------------
+// Steering-config fixture writers
+// ---------------------------------------------------------------------------
+/**
+ * Write a single-file steering config to `<dir>/.pi/steering.ts`.
+ * `body` is the full module source (must include `export default`).
+ * Used by suites whose fixtures embed regex literals or other
+ * non-JSON-friendly module shapes inline.
+ */
+export function writeSteeringSingleFileConfig(dir, body) {
+    mkdirSync(join(dir, ".pi"), { recursive: true });
+    writeFileSync(join(dir, ".pi", "steering.ts"), body, "utf8");
+}
+/**
+ * Write a directory-form steering config to
+ * `<dir>/.pi/steering/index.ts`. `body` is the full module source
+ * (must include `export default`). Mirrors the layout the bin tests
+ * use for their isolated `@cad0p/pi-steering` invocations.
+ */
+export function writeSteeringDirConfig(dir, body) {
+    const pi = join(dir, ".pi", "steering");
+    mkdirSync(pi, { recursive: true });
+    writeFileSync(join(pi, "index.ts"), body, "utf8");
+}
+// ---------------------------------------------------------------------------
+// ExtensionContext stub
+// ---------------------------------------------------------------------------
+/**
+ * Minimal stub for pi's `ExtensionContext`. Only the fields the
+ * evaluator + observer-dispatcher read are populated; everything else
+ * throws if touched so accidental reliance on unsupported surface
+ * breaks loudly.
+ *
+ * The `entries` array mimics `sessionManager.getEntries()` output —
+ * tests that want cross-handler `findEntries` visibility pass
+ * `host.entries` (from {@link makeTrackedHost}) here so the host's
+ * `appendEntry` writes show up on subsequent reads.
+ */
+export function makeCtx(cwd, entries = []) {
+    return {
+        cwd,
+        sessionManager: {
+            getEntries: () => entries,
+            // Other SessionManager methods are stubbed to throw via the
+            // unknown-cast below; any accidental dependency surfaces as a
+            // clear TypeError rather than silently passing.
+        },
+    };
+}
+/**
+ * Build a {@link TrackedHost}. Optional `exec` override lets evaluator
+ * tests count real invocations against the cache (the default exec
+ * returns `{ stdout: "", stderr: "", code: 0, killed: false }`).
+ */
+export function makeTrackedHost(options) {
+    const execCalls = [];
+    const appended = [];
+    const entries = [];
+    let idCounter = 0;
+    return {
+        execCalls,
+        appended,
+        entries,
+        exec: async (cmd, args, opts) => {
+            const cwd = opts?.cwd ?? "/";
+            execCalls.push({ cmd, args: [...args], cwd });
+            if (options?.exec) {
+                return options.exec(cmd, args, cwd);
+            }
+            return { stdout: "", stderr: "", code: 0, killed: false };
+        },
+        appendEntry: (type, data) => {
+            appended.push({ type, data });
+            entries.push({
+                type: "custom",
+                customType: type,
+                data,
+                timestamp: new Date(Date.UTC(2026, 0, 1, 0, 0, idCounter++)).toISOString(),
+                id: `entry-${idCounter}`,
+                parentId: null,
+            });
+        },
+    };
+}
+//# sourceMappingURL=__test-helpers__.js.map

package/dist/__test-helpers__.js.map

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

package/dist/bin/pi-steering.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI entrypoint. Exported (not just `void main(...)` at module top)
+ * so the test suite can exercise the argument parser without spawning
+ * a subprocess. Real invocation goes through the bottom-of-file
+ * bootstrap when this module is run as `node pi-steering.js`.
+ */
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=pi-steering.d.ts.map

package/dist/bin/pi-steering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-steering.d.ts","sourceRoot":"","sources":["../../src/bin/pi-steering.ts"],"names":[],"mappings":";AAsCA;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB1D"}