poe-code 4.0.12 → 4.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poe-code",
-  "version": "4.0.12",
+  "version": "4.0.14",
   "description": "CLI tool to configure Poe API for developer workflows.",
   "license": "MIT",
   "type": "module",
@@ -90,6 +90,7 @@
     "smoke:toolcraft-standalone": "node scripts/verify-toolcraft-standalone.mjs",
     "smoke:toolcraft-sdk-types": "node scripts/verify-toolcraft-published-sdk-types.mjs",
     "sync-skills": "tsx scripts/sync-skills.ts",
+    "record:fs-conformance": "tsx scripts/record-fs-conformance.ts",
     "sync:json-schema-test-suite": "node scripts/sync-json-schema-test-suite.mjs",
     "sync:uri-template-test": "node scripts/sync-uri-template-test.mjs",
     "postinstall": "node scripts/postinstall-sync-skills.mjs"

package/packages/pipeline/dist/plan/discovery.js

@@ -34,8 +34,8 @@ function countCompletedTasks(planPath, content) {
         total
     };
 }
-async function ensurePlanExists(fs, cwd, planPath) {
-    const absolutePath = path.isAbsolute(planPath) ? planPath : path.resolve(cwd, planPath);
+async function ensurePlanExists(fs, cwd, homeDir, planPath) {
+    const absolutePath = resolveAbsolutePlanPath(planPath, cwd, homeDir);
     const stat = await fs.stat(absolutePath).catch((error) => {
         if (isNotFound(error)) {
             return undefined;
@@ -97,7 +97,7 @@ export async function resolvePlanPaths(options) {
         .filter((planPath) => planPath.length > 0);
     if (explicitPlans.length > 0) {
         for (const planPath of explicitPlans) {
-            await ensurePlanExists(fs, options.cwd, planPath);
+            await ensurePlanExists(fs, options.cwd, options.homeDir, planPath);
         }
         return explicitPlans;
     }

package/packages/safejs/dist/cli.js

@@ -12,6 +12,7 @@ import { lint } from "./lint.js";
 import { createLintModulesFromRuntimeRegistry } from "./lint/runtime-modules.js";
 import { makeAgentModule } from "./modules/agent.js";
 import { makeFailModule } from "./modules/fail.js";
+import { makeFsModule } from "./modules/fs.js";
 import { makeHarnessModule } from "./modules/harness.js";
 import { makeLogModule } from "./modules/log.js";
 import { makeMetricModule } from "./modules/metric.js";
@@ -80,7 +81,8 @@ function readCurrentWorkingDirectory() {
 }
 function parseArgs(argv) {
     const parsed = {
-        fix: false
+        fix: false,
+        fs: false
     };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -88,6 +90,15 @@ function parseArgs(argv) {
             parsed.fix = true;
             continue;
         }
+        if (arg === "--fs") {
+            parsed.fs = true;
+            continue;
+        }
+        if (arg === "--fs-root") {
+            parsed.fsRoot = readFlagValue(argv, index, arg);
+            index += 1;
+            continue;
+        }
         if (arg === "--snapshot") {
             parsed.snapshotPath = readFlagValue(argv, index, arg);
             index += 1;
@@ -116,6 +127,9 @@ function parseArgs(argv) {
         }
         parsed.filepath = arg;
     }
+    if (!parsed.fs && parsed.fsRoot !== undefined) {
+        throw new CliExitError("--fs-root requires --fs. Pass --fs to give the script a filesystem confined to that root, or drop --fs-root.", EXIT_RUNTIME);
+    }
     return parsed;
 }
 function readFlagValue(argv, index, flag) {
@@ -155,6 +169,9 @@ async function runScriptFile(filepath, parsed, options) {
         version: loaded.frontmatter.version
     };
     const runtime = createRuntime(loaded.frontmatter, meta, {
+        fs: parsed.fs
+            ? { root: path.resolve(options.cwd, parsed.fsRoot ?? dirname(filepath)) }
+            : undefined,
         modulesFor: options.modulesFor,
         stderr: options.stderr,
         stdout: options.stdout
@@ -348,6 +365,8 @@ function createRuntime(frontmatter, meta, options) {
         registry: {
             agent: toModuleExports(agent),
             fail: toModuleExports(new Map([["default", makeFailModule().default]])),
+            // The one module here that is not a stub, so it is registered only when asked for.
+            ...(options.fs === undefined ? {} : { fs: toModuleExports(makeFsModule(options.fs)) }),
             git: toModuleExports(new Map([
                 ["checkpoint", git.checkpoint],
                 ["commit", git.commit],
@@ -413,6 +432,10 @@ function createUsage() {
         "",
         "Options:",
         "  --fix                 apply lint fixes before running",
+        "  --fs                  register the fs module: a real filesystem, unlike the agent,",
+        "                        git, and metric stubs this runner bundles",
+        "  --fs-root <path>      directory --fs confines the script to (default: the script's",
+        "                        directory)",
         "  --snapshot <path>     write the final snapshot, and best-effort snapshot on SIGINT",
         "  --restore <path>      restore from a snapshot before running",
         "  --max-steps <n>       cap interpreter step budget",

package/packages/safejs/dist/index.d.ts

@@ -29,6 +29,8 @@ export { createSpawnUsageAccumulator, makeAgentModule, runWithSpawnUsageAccumula
 export type { AgentModuleDefinition, AgentModuleOptions, AgentModuleParallelCall, AgentModuleRetryOptions, AgentModuleSpawnOptions, AgentSpawnEvent, SpawnAgent, SpawnAgentInput, SpawnAgentResult, SpawnUsageAccumulator, SpawnUsageTotal } from "./modules/agent.js";
 export { makeEnvModule } from "./modules/env.js";
 export { makeFailModule } from "./modules/fail.js";
+export { makeFsModule } from "./modules/fs.js";
+export type { FsImplementation, FsModule, FsModuleOptions, SandboxDirent, SandboxStats } from "./modules/fs.js";
 export { makeGitModule } from "./modules/git.js";
 export { makeHarnessModule } from "./modules/harness.js";
 export { makeLogModule } from "./modules/log.js";

package/packages/safejs/dist/index.js

@@ -20,6 +20,7 @@ export { splitFrontmatter } from "./loader/frontmatter.js";
 export { createSpawnUsageAccumulator, makeAgentModule, runWithSpawnUsageAccumulator } from "./modules/agent.js";
 export { makeEnvModule } from "./modules/env.js";
 export { makeFailModule } from "./modules/fail.js";
+export { makeFsModule } from "./modules/fs.js";
 export { makeGitModule } from "./modules/git.js";
 export { makeHarnessModule } from "./modules/harness.js";
 export { makeLogModule } from "./modules/log.js";

package/packages/safejs/dist/interp/cancel.js

@@ -1,4 +1,5 @@
 import { createSandboxClosure, createSandboxPromise, isSandboxClosure, isSandboxPromise } from "./values.js";
+import { observeSandboxPromise } from "./promise-tracker.js";
 import { replaceErrorStack } from "../error/shape.js";
 export function wrapCancelableBindings(bindings, signal) {
     if (signal === undefined) {
@@ -32,6 +33,9 @@ function wrapCancelableValue(value, signal, seen) {
         return wrapped;
     }
     if (isSandboxPromise(value)) {
+        // The wrapper delivers this promise's rejection to the sandbox in its place, so
+        // the sandbox never awaits the original and it would otherwise read as unhandled.
+        observeSandboxPromise(value);
         const wrapped = createSandboxPromise(wrapCancelablePromise(value.promise, signal, seen), {
             ...(value.hostCall === undefined ? {} : { hostCall: value.hostCall }),
             ...(value.hostCallJournal === undefined ? {} : { hostCallJournal: value.hostCallJournal }),

package/packages/safejs/dist/interp/host-bridge.js

@@ -7,6 +7,13 @@ import { digestHostCallArguments, HostCallResumabilityError } from "./host-call.
 import { createSandboxClosure, createSandboxMap, createSandboxPromise, createSandboxSet, deepCopyFromSandbox, deepCopyToSandbox, isSandboxClosure, isSandboxPromise, measureSandboxData } from "./values.js";
 import { enterRunningState } from "./running-state.js";
 const AsyncFunction = (async () => undefined).constructor;
+const hostErrorMetadata = {
+    code: "string",
+    dest: "string",
+    errno: "number",
+    path: "string",
+    syscall: "string"
+};
 const hostOperationPolicies = new WeakMap();
 export function declareHostOperation(operation, policy) {
     hostOperationPolicies.set(operation, policy);
@@ -190,9 +197,31 @@ function createHostErrorValue(reason, stackFrames, budget, span) {
         : createSubsetErrorValue("Error", describeThrownReason(reason), stackFrames, budget, {
             chargeBudget: false
         });
+    if (reason instanceof Error) {
+        copyHostErrorMetadata(error, reason, budget);
+    }
     attachErrorSpan(error, span);
     return error;
 }
+function copyHostErrorMetadata(error, reason, budget) {
+    const resumeChecks = budget.suspendChecks();
+    try {
+        for (const [key, expectedType] of Object.entries(hostErrorMetadata)) {
+            const descriptor = Object.getOwnPropertyDescriptor(reason, key);
+            if (descriptor === undefined || "get" in descriptor || "set" in descriptor) {
+                continue;
+            }
+            const value = descriptor.value;
+            if (typeof value !== expectedType) {
+                continue;
+            }
+            error[key] = typeof value === "string" ? budget.allocateString(value) : value;
+        }
+    }
+    finally {
+        resumeChecks();
+    }
+}
 function wrapSandboxClosureForHost(closure, stackFrames, budget) {
     return async (...args) => {
         const leaveRunning = enterRunningState(closure);
@@ -410,7 +439,9 @@ function copyHostValueToSandbox(value, stackFrames, options, state, path) {
             if ("get" in descriptor || "set" in descriptor) {
                 throw new TypeError(`Unsupported sandbox value at ${joinPath(path, key)}: accessor property`);
             }
-            Object.defineProperty(copy, key, {
+            // Charged like any other string the copy carries in: a key is as readable to the sandbox
+            // as the value under it, so the same limit answers for both.
+            Object.defineProperty(copy, budget.allocateString(key), {
                 enumerable: true,
                 configurable: true,
                 writable: true,

package/packages/safejs/dist/interp/promise.d.ts

@@ -10,3 +10,4 @@ export declare function getPromiseMember(target: SandboxPromise, property: strin
 export declare function resolveSandboxValue(value: SandboxValue | Promise<SandboxValue> | PromiseLike<SandboxValue>, options?: {
     budget?: Budget;
 }): Promise<SandboxValue>;
+export declare function consumeSettledHostCall(value: SandboxPromise): void;

package/packages/safejs/dist/interp/promise.js

@@ -148,6 +148,14 @@ function budgetSandboxValue(value, budget) {
 export function resolveSandboxValue(value, options = {}) {
     return Promise.resolve().then(() => resolveSandboxValueNow(value, options, new WeakSet()));
 }
+// A host call result is consumed once, when it settles. Observing the same promise
+// again is ordinary JavaScript and must not be reported as a double consumption.
+export function consumeSettledHostCall(value) {
+    if (value.hostCall?.lifecycle !== "settled") {
+        return;
+    }
+    value.hostCallJournal?.consume(value.hostCall);
+}
 function resolveSandboxValueNow(value, options, seenThenables) {
     if (isPromiseLike(value)) {
         return Promise.resolve(value).then((resolved) => resolveSandboxValueNow(resolved, options, seenThenables), (reason) => Promise.reject(budgetIfNeeded(reason, options.budget)));
@@ -155,10 +163,10 @@ function resolveSandboxValueNow(value, options, seenThenables) {
     if (isSandboxPromise(value)) {
         observeSandboxPromise(value);
         return value.promise.then((resolved) => {
-            value.hostCallJournal?.consume(value.hostCall);
+            consumeSettledHostCall(value);
             return resolveSandboxValueNow(resolved, options, seenThenables);
         }, (reason) => {
-            value.hostCallJournal?.consume(value.hostCall);
+            consumeSettledHostCall(value);
             return Promise.reject(budgetIfNeeded(reason, options.budget));
         });
     }

package/packages/safejs/dist/modules/canonical-path.d.ts

@@ -0,0 +1,15 @@
+type Realpath = (path: string) => Promise<string>;
+type Readlink = (path: string) => Promise<string>;
+export type CanonicalPathFs = {
+    realpath: Realpath;
+    readlink: Readlink;
+};
+type PathIdentity = {
+    dev: number;
+    ino: number;
+};
+export type Stat = (path: string) => Promise<PathIdentity>;
+export declare function resolveCanonicalPath({ realpath, readlink }: CanonicalPathFs, path: string): Promise<string>;
+export declare function containsPath(stat: Stat, canonicalRoot: string, canonicalPath: string): Promise<boolean>;
+export declare function isSamePath(stat: Stat, canonicalLeft: string, canonicalRight: string): Promise<boolean>;
+export {};

package/packages/safejs/dist/modules/canonical-path.js

@@ -0,0 +1,161 @@
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { getOwnErrorCode } from "../error-codes.js";
+// realpath answers ENOENT for a missing segment and ENOTDIR when a parent is a
+// file. Both mean the segment is not an existing directory, so both walk up.
+const MISSING_PATH_CODES = ["ENOENT", "ENOTDIR"];
+// What the filesystem answers for a path that has no link target to follow: EINVAL
+// for a path that exists and is not a link, and the missing-path codes for one that
+// is not there at all. Any other failure is the filesystem's own and is left to
+// surface rather than read as "not a link", which would canonicalize a link the
+// filesystem merely refused to read as though it named itself.
+const NOT_A_SYMLINK_CODES = [...MISSING_PATH_CODES, "EINVAL"];
+// A conforming realpath raises ELOOP for a cycle before the walk below can follow
+// one, so this cap is only reached by a filesystem that reports a cycle as a
+// missing path. Following one of those forever would hang the sandbox, so the walk
+// gives up the way the platform does — at SYMLOOP_MAX, which is 32 on darwin and
+// Linux alike.
+const MAX_SYMLINK_FOLLOWS = 32;
+// Canonicalizes as much of the path as exists and re-appends the segments that do
+// not, so a path is checked after symlinks are followed rather than as written.
+// The missing segments go back through resolve(), which collapses any `..` among
+// them, so they cannot re-escape what realpath already pinned down.
+//
+// A dangling symlink is the case this cannot read off realpath alone: realpath
+// refuses one with the same ENOENT it gives a path that was never there, yet the two
+// are not the same place. node follows a dangling link and acts on its target — a
+// write through one creates the target — so a dangling link canonicalizes to what it
+// names, not to itself. Reading that ENOENT as "nothing here" would answer with the
+// link's own path and call a link out of a caller's root contained.
+export async function resolveCanonicalPath({ realpath, readlink }, path) {
+    const missingSegments = [];
+    let current = path;
+    let follows = 0;
+    while (true) {
+        try {
+            const canonicalCurrent = await realpath(current);
+            return resolve(canonicalCurrent, ...missingSegments.reverse());
+        }
+        catch (error) {
+            if (!MISSING_PATH_CODES.includes(getOwnErrorCode(error) ?? "")) {
+                throw error;
+            }
+            const target = await readSymlinkTarget(readlink, current);
+            if (target !== undefined) {
+                if (++follows > MAX_SYMLINK_FOLLOWS) {
+                    throw createLoopError(path);
+                }
+                // node resolves a relative target against the link's own directory. Any
+                // segments already collected still hang off whatever the target resolves to,
+                // so they stay on the list.
+                current = isAbsolute(target) ? resolve(target) : resolve(dirname(current), target);
+                continue;
+            }
+            const parent = dirname(current);
+            if (parent === current) {
+                return resolve(path);
+            }
+            missingSegments.push(basename(current));
+            current = parent;
+        }
+    }
+}
+// The target of a link realpath could not resolve, or undefined when the path is not
+// a link at all and the walk should climb past it instead.
+async function readSymlinkTarget(readlink, path) {
+    try {
+        return await readlink(path);
+    }
+    catch (error) {
+        if (NOT_A_SYMLINK_CODES.includes(getOwnErrorCode(error) ?? "")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+// Shaped like the ELOOP a filesystem raises for a cycle it walked itself, so a
+// caller that branches on the code reads the cap and the filesystem's own answer the
+// same way.
+function createLoopError(path) {
+    const error = new Error(`ELOOP: too many symbolic links encountered, realpath '${path}'`);
+    error.code = "ELOOP";
+    return error;
+}
+// Whether root contains path, root itself included. Both arguments must already be
+// canonical: a `..` or a symlink left in either one would make the comparison lie.
+//
+// The rule: the filesystem has the deciding vote on containment, and comparing
+// the canonical spellings is only a fast path that is trusted when it answers
+// "contained". Two canonical paths can differ in spelling and still be the same
+// place — on a case-insensitive filesystem (darwin's default) `/repo` and `/REPO`
+// are one directory, and darwin's realpath echoes the spelling it was handed
+// rather than the on-disk one, so canonicalization does not fold the case away.
+// Comparing spellings can therefore only ever be wrong in one direction: it may
+// answer "outside" for a path that resolves inside root, never the reverse. So
+// "outside" is re-decided by walking the path's ancestors and asking the
+// filesystem for each one's identity, which no spelling can lie about. Folding
+// case here instead would be a hole: on a case-sensitive filesystem `/REPO/x` is
+// genuinely a different file from `/repo/x`.
+export async function containsPath(stat, canonicalRoot, canonicalPath) {
+    if (containsCanonicalSpelling(canonicalRoot, canonicalPath)) {
+        return true;
+    }
+    return descendsFromRoot(stat, canonicalRoot, canonicalPath);
+}
+// Whether two canonical paths name the same place. Two spellings can name one
+// place on a case-insensitive filesystem, so identity decides here for the same
+// reason it decides containment above.
+export async function isSamePath(stat, canonicalLeft, canonicalRight) {
+    if (canonicalLeft === canonicalRight) {
+        return true;
+    }
+    const [left, right] = await Promise.all([
+        readIdentity(stat, canonicalLeft),
+        readIdentity(stat, canonicalRight)
+    ]);
+    return (left !== undefined && right !== undefined && left.dev === right.dev && left.ino === right.ino);
+}
+function containsCanonicalSpelling(canonicalRoot, canonicalPath) {
+    const relativePath = relative(canonicalRoot, canonicalPath);
+    // An empty relative path is root itself, which the root contains.
+    return !(relativePath === ".." ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath));
+}
+// Climbs the path's ancestors looking for root's own identity. A canonical path
+// carries no symlinks and no `..`, so every ancestor it names is a real ancestor:
+// finding root among them means the path descends from root whatever either one
+// is spelled like.
+async function descendsFromRoot(stat, canonicalRoot, canonicalPath) {
+    const root = await readIdentity(stat, canonicalRoot);
+    if (root === undefined) {
+        return false;
+    }
+    let current = canonicalPath;
+    while (true) {
+        const identity = await readIdentity(stat, current);
+        if (identity !== undefined && identity.dev === root.dev && identity.ino === root.ino) {
+            return true;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return false;
+        }
+        current = parent;
+    }
+}
+// A path that is not there has no identity to match, so the walk climbs past it
+// rather than treating it as an answer. Any other failure is the filesystem's own
+// and is left to surface: swallowing it would report a refusal for what node
+// blames on something else.
+async function readIdentity(stat, path) {
+    try {
+        const { dev, ino } = await stat(path);
+        return { dev, ino };
+    }
+    catch (error) {
+        if (MISSING_PATH_CODES.includes(getOwnErrorCode(error) ?? "")) {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/packages/safejs/dist/modules/fs.conformance-cases.d.ts

@@ -0,0 +1,99 @@
+import { Volume } from "memfs";
+import { makeFsModule, type FsImplementation } from "./fs.js";
+export declare const STRING_ENCODINGS: readonly ["utf8", "utf-8", "utf16le", "utf-16le", "ucs2", "ucs-2", "latin1", "binary", "ascii", "base64", "base64url", "hex"];
+type StringEncoding = (typeof STRING_ENCODINGS)[number];
+export declare function encode(text: string, encoding: StringEncoding): string;
+export type FsCaseDriver = Omit<ReturnType<typeof makeFsModule>, "constants" | "mkdir" | "rmdir"> & {
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<string | undefined>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+};
+type ObservedFailure = {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly path?: string;
+};
+type Observed = {
+    readonly result: unknown;
+} | ObservedFailure;
+export type RecordedTruth = {
+    readonly result: unknown;
+} | (ObservedFailure & {
+    readonly errno: number;
+    readonly syscall: string;
+    readonly dest?: string;
+});
+export type RecordedCase = {
+    readonly title: string;
+    readonly resolved: boolean;
+    readonly node: RecordedTruth;
+    readonly gap?: string;
+};
+export type RecordedPlatform = {
+    readonly nodeVersion: string;
+    readonly cases: readonly RecordedCase[];
+};
+export type NodeTruthFixture = {
+    readonly platforms: Readonly<Record<string, RecordedPlatform>>;
+};
+export declare const HANGS = "hangs";
+export type FsConformanceCase = {
+    readonly title: string;
+    readonly setup?: (volume: Volume) => void;
+    readonly invoke: (fs: FsCaseDriver) => Promise<unknown>;
+    readonly node: RecordedTruth;
+    readonly gap?: {
+        readonly reason: string;
+        readonly memfs: Observed | typeof HANGS;
+    };
+    readonly readsAnswer?: true;
+};
+export declare function readSystemError(code: string): {
+    errno: number;
+    description: string;
+};
+export declare function systemErrorMessage(code: string, syscall: string, path?: string, dest?: string): string;
+export declare function createNodeTruthFs(truth: RecordedTruth): FsImplementation;
+export declare function readRecordedOutcome(operation: Promise<unknown>): Promise<RecordedTruth>;
+export declare function readObserved(operation: Promise<unknown>): Promise<Observed>;
+export declare function toObserved(truth: RecordedTruth): Observed;
+export declare function toRecordedObserved(entry: RecordedCase): Observed;
+export declare function driveCase(testCase: FsConformanceCase): {
+    fs: FsCaseDriver;
+    reference: FsCaseDriver;
+    volume: Volume;
+};
+export declare const CASE_ROOT = "/repo";
+export declare const CASE_VOLUME: Readonly<Record<string, string>>;
+type SystemErrorCase = {
+    readonly title: string;
+    readonly syscall: string;
+    readonly code: string;
+    readonly path?: string;
+    readonly dest?: string;
+    readonly setup?: (volume: Volume) => void;
+    readonly invoke: (fs: FsCaseDriver) => Promise<unknown>;
+    readonly gap?: FsConformanceCase["gap"];
+};
+export declare function systemErrorTruth(entry: {
+    readonly code: string;
+    readonly syscall: string;
+    readonly path?: string;
+    readonly dest?: string;
+}): RecordedTruth;
+export declare function toConformanceCase(entry: SystemErrorCase): FsConformanceCase;
+export declare const SYSTEM_ERROR_CASES: readonly SystemErrorCase[];
+export declare const MKDIR_RM_RMDIR_CASES: readonly FsConformanceCase[];
+export declare const WRITE_CASES: readonly FsConformanceCase[];
+export declare const stageLoop: (volume: Volume) => void;
+export declare const LOOP_HANGS = "memfs recurses through the cycle instead of answering ELOOP";
+export declare const SYMLINK_CASES: readonly FsConformanceCase[];
+export declare const COPY_RENAME_CASES: readonly FsConformanceCase[];
+export declare const READ_AND_SHAPE_CASES: readonly FsConformanceCase[];
+export declare const FS_CONFORMANCE_CASES: readonly FsConformanceCase[];
+export {};