codecartographer-pi 0.19.5 → 0.20.0

package/dist/core/secrets.js

@@ -0,0 +1,98 @@
+// Secret redaction for text that leaves the machine (#252).
+//
+// Broad-Side uploads repository content to a batch API as-is; the only thing
+// keeping a `.env` out of a batch was that no language glob matched it. This
+// module is the content-level counterpart: files that exist to hold secrets
+// are skipped by name, and high-confidence secret shapes inside any other
+// file are replaced with `[REDACTED:<kind>]` before the text is sent. The
+// marker keeps the *presence* of a credential visible to the security lens —
+// `password = "[REDACTED:credential-assignment]"` is still a hardcoded
+// credential to flag — while the value stays home.
+//
+// The patterns are deliberately the well-known, low-false-positive ones. A
+// generic entropy scan would redact hashes, ids, and base64 blobs that the
+// lenses need to read, and the point of the pass is to make an accidental
+// upload harmless, not to replace a secret scanner in CI.
+/** A file whose purpose is to hold credentials; never uploaded, whatever a lens's globs say. */
+const SECRET_FILE_PATTERNS = [
+    /^\.env(?:\..*)?$/i, // .env, .env.local, .env.production — templates included; they hold values more often than not
+    /\.(?:pem|key|p12|pfx|jks|keystore|asc|gpg|ppk)$/i,
+    /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\..*)?$/, // private keys and their .pub siblings; the public half is noise anyway
+    /^(?:\.npmrc|\.pypirc|\.netrc|_netrc|\.htpasswd|\.git-credentials|\.pgpass|\.my\.cnf|\.boto)$/i,
+    // credentials.json, secrets.yaml, secret.env — data files by that name.
+    // Not `secrets.go` or `credentials.py`: source that *handles* secrets is
+    // exactly what the security lens should read, so only data extensions
+    // (or none) count here.
+    /^(?:credentials?|secrets?)(?:\.(?:json|ya?ml|toml|ini|txt|cfg|conf|properties|env|local))?$/i,
+    /\.secret$/i,
+    /\.tfvars(?:\.json)?$/i,
+    /^service[-_]?account.*\.json$/i,
+];
+/** Whether a repo-relative path names a file that exists to hold secrets. */
+export function isSecretFile(relPath) {
+    const base = relPath.slice(relPath.lastIndexOf("/") + 1);
+    return SECRET_FILE_PATTERNS.some((pattern) => pattern.test(base));
+}
+const SECRET_PATTERNS = [
+    { kind: "private-key", pattern: /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END (?:[A-Z ]+ )?PRIVATE KEY(?: BLOCK)?-----/g },
+    { kind: "aws-access-key-id", pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { kind: "github-token", pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})\b/g },
+    // OpenAI, OpenRouter (sk-or-v1-…), and Anthropic (sk-ant-…) keys share the prefix.
+    { kind: "sk-api-key", pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+    { kind: "stripe-key", pattern: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}\b/g },
+    { kind: "slack-token", pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g },
+    { kind: "google-api-key", pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    { kind: "jwt", pattern: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+    // `password: "hunter2hunter2"`, `API_KEY = 'abcdefgh…'`: the key and the
+    // quotes stay, the value goes. Eight characters or more, so `password: "x"`
+    // in a test fixture is left alone.
+    // The key may carry a prefix (`DB_PASSWORD`, `stripe-secret-key`), and a
+    // value that is already a marker is left alone, which is what makes the
+    // pass idempotent.
+    {
+        kind: "credential-assignment",
+        pattern: /\b((?:[A-Za-z0-9]+[_-])*(?:api[_-]?key|secret[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token|access[_-]?token|refresh[_-]?token|bearer[_-]?token|password|passwd|pwd|secret|token)\s*[:=]\s*)(["'`])(?!\[REDACTED:)([^"'`\r\n]{8,})\2/gi,
+        rebuild: (marker, prefix, quote) => `${prefix}${quote}${marker}${quote}`,
+    },
+    // The password in `scheme://user:password@host`.
+    {
+        kind: "url-credential",
+        pattern: /\b([a-z][a-z0-9+.-]*:\/\/[^\s/:@"']+:)(?!\[REDACTED:)([^\s/@"']{3,})(@)/gi,
+        rebuild: (marker, head, _password, at) => `${head}${marker}${at}`,
+    },
+];
+/**
+ * Replace every high-confidence secret in `text` with `[REDACTED:<kind>]`.
+ * Idempotent: a marker contains nothing any pattern matches.
+ */
+export function redactSecrets(text) {
+    let out = text;
+    let count = 0;
+    const kinds = {};
+    for (const { kind, pattern, rebuild } of SECRET_PATTERNS) {
+        out = out.replace(pattern, (...match) => {
+            count++;
+            kinds[kind] = (kinds[kind] ?? 0) + 1;
+            const marker = `[REDACTED:${kind}]`;
+            if (!rebuild)
+                return marker;
+            // replace() passes [whole, ...groups, offset, input]; hand over the groups.
+            const groups = match.slice(1, match.length - 2).map((value) => (typeof value === "string" ? value : ""));
+            return rebuild(marker, ...groups);
+        });
+    }
+    return { text: out, count, kinds };
+}
+/** One line for a submit report: what the pass did, or nothing when it did nothing. */
+export function describeRedactions(values, files, skipped) {
+    const parts = [];
+    if (values > 0)
+        parts.push(`redacted ${values} secret-like value(s) in ${files} file(s)`);
+    if (skipped.length > 0) {
+        const shown = skipped.slice(0, 3).join(", ");
+        parts.push(`skipped ${skipped.length} secret-bearing file(s) by name (${shown}${skipped.length > 3 ? ", …" : ""})`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `Before upload: ${parts.join("; ")}.`;
+}

package/dist/core/status.d.ts

@@ -16,6 +16,14 @@ export declare function autoAssignIds(entries: OpenQuestionEntry[], prefix: stri
 export declare function ensurePostPipelineArray(value: unknown): PostPipelineEntry[];
 export declare function ensurePhaseRecord(value: unknown): Record<string, StatusPhase>;
 export declare function createEmptyStatus(projectName: string, pipelinePath: string, pipeline: PipelineFile): NormalizedStatus;
+/**
+ * The one next_actions line for a phase the engine says is eligible. Init,
+ * completion, and a pipeline switch all spell it this way.
+ */
+export declare function beginPhaseAction(phase: {
+    id: string;
+    primary_output?: string;
+}): string;
 /**
  * Route the terminal boundary to the post-pipeline surfaces (issue #114). The
  * moment every phase completes is exactly when skills, amendments, publishing,
@@ -36,6 +44,26 @@ export declare function parseHandoff(value: unknown): PhaseHandoff;
 export declare function ensureProposedConventionArray(value: unknown): ProposedConventionEntry[];
 export declare function loadHandoffFile(phaseId: string, workspaceDir: string): Promise<PhaseHandoff | null>;
 export declare function applyHandoff(status: NormalizedStatus, handoff: PhaseHandoff): NormalizedStatus;
-export declare function acquireLock(lockPath: string): Promise<{
+/** What {@link acquireLock} hands back: a release that only ever removes its own lock. */
+export interface LockHandle {
     release: () => Promise<void>;
-}>;
+    /**
+     * Set when acquiring meant breaking a lock older than {@link STALE_LOCK_MS}:
+     * the previous holder as its lock file recorded it, for callers that log.
+     */
+    brokeStale?: {
+        pid: number | null;
+        since: string | null;
+    };
+}
+/**
+ * Take the O_EXCL lock at `lockPath`, waiting up to {@link LOCK_TIMEOUT_MS}
+ * and breaking a lock older than {@link STALE_LOCK_MS}.
+ *
+ * The lock file records `pid`, timestamp, and a per-acquisition token, and
+ * release removes the file only while it still carries that token. Without
+ * the token, release removed whoever's lock was there: after a stale break
+ * the previous holder's release deleted the new holder's lock, and a third
+ * writer walked straight in (#227).
+ */
+export declare function acquireLock(lockPath: string): Promise<LockHandle>;

package/dist/core/status.js

@@ -1,6 +1,7 @@
 // Status normalization, atomic writes, and file-lock primitives. Pure
 // framework logic shared by every wrapper.
-import { open, rm, stat } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { open, readFile, rm, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { pathExists, sleep } from "./utils.js";
 import { loadYamlFile } from "./yaml.js";
@@ -154,12 +155,17 @@ export function createEmptyStatus(projectName, pipelinePath, pipeline) {
         last_updated: "",
         schema_version: 1,
         phases,
-        next_actions: firstPhaseConfig?.primary_output
-            ? [`Begin ${firstPhase} phase by producing ${firstPhaseConfig.primary_output}`]
-            : ["Begin the first pending phase."],
+        next_actions: [beginPhaseAction(firstPhaseConfig ?? { id: firstPhase })],
         post_pipeline: [],
     };
 }
+/**
+ * The one next_actions line for a phase the engine says is eligible. Init,
+ * completion, and a pipeline switch all spell it this way.
+ */
+export function beginPhaseAction(phase) {
+    return `Begin ${phase.id} phase by producing ${phase.primary_output ?? `findings/${phase.id}/`}`;
+}
 /**
  * Spell a tool for both executable surfaces — the shape the scaffold
  * staleness notice adopted (#177). next_actions is canonical state rendered
@@ -397,13 +403,25 @@ export function applyHandoff(status, handoff) {
     status.post_pipeline = [...legacyPostPipeline, ...postPipeline.values()];
     return status;
 }
+/**
+ * Take the O_EXCL lock at `lockPath`, waiting up to {@link LOCK_TIMEOUT_MS}
+ * and breaking a lock older than {@link STALE_LOCK_MS}.
+ *
+ * The lock file records `pid`, timestamp, and a per-acquisition token, and
+ * release removes the file only while it still carries that token. Without
+ * the token, release removed whoever's lock was there: after a stale break
+ * the previous holder's release deleted the new holder's lock, and a third
+ * writer walked straight in (#227).
+ */
 export async function acquireLock(lockPath) {
     const startedAt = Date.now();
+    const token = `${process.pid}.${randomBytes(8).toString("hex")}`;
+    let brokeStale;
     while (true) {
         try {
             const handle = await open(lockPath, "wx");
             try {
-                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n${token}\n`, "utf8");
             }
             catch (error) {
                 // A non-EEXIST write failure must not leak the descriptor the
@@ -413,9 +431,8 @@ export async function acquireLock(lockPath) {
             }
             await handle.close();
             return {
-                release: async () => {
-                    await rm(lockPath, { force: true }).catch(() => undefined);
-                },
+                release: () => releaseOwnedLock(lockPath, token),
+                ...(brokeStale && { brokeStale }),
             };
         }
         catch (error) {
@@ -425,6 +442,7 @@ export async function acquireLock(lockPath) {
             try {
                 const lockStat = await stat(lockPath);
                 if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+                    brokeStale = await describeLockHolder(lockPath);
                     await rm(lockPath, { force: true }).catch(() => undefined);
                     continue;
                 }
@@ -439,3 +457,31 @@ export async function acquireLock(lockPath) {
         }
     }
 }
+/**
+ * Remove the lock at `lockPath` only if it is still ours. A lock that vanished
+ * (someone broke it as stale) or that now carries another holder's token is
+ * left alone; one whose content cannot be read is left to go stale rather
+ * than removed unverified.
+ */
+async function releaseOwnedLock(lockPath, token) {
+    let content;
+    try {
+        content = await readFile(lockPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (content.split(/\r?\n/)[2] !== token)
+        return;
+    await rm(lockPath, { force: true }).catch(() => undefined);
+}
+async function describeLockHolder(lockPath) {
+    try {
+        const [pidLine, sinceLine] = (await readFile(lockPath, "utf8")).split(/\r?\n/);
+        const pid = Number.parseInt(pidLine ?? "", 10);
+        return { pid: Number.isFinite(pid) ? pid : null, since: sinceLine?.trim() || null };
+    }
+    catch {
+        return { pid: null, since: null };
+    }
+}

package/dist/core/synthesis.js

@@ -4,7 +4,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { discoverLibrary, listEntries } from "./library.js";
-import { loadCodecartoConfig } from "./orchestrator-config.js";
+import { describeConfigProblems, loadCodecartoConfig } from "./orchestrator-config.js";
 import { pathExists } from "./utils.js";
 export const SYNTHESIS_PROPOSAL_PATH = "findings/goal-synthesis/proposal.md";
 export const SYNTHESIS_VISION_INPUT_PATH = "inputs/vision.md";
@@ -88,7 +88,10 @@ export async function runPhasePreflight(state, phase) {
     if (checks.has("requires-library")) {
         const config = await loadCodecartoConfig(state.workspaceDir);
         if (!config.library.path) {
-            throw new PhasePreflightError(phase.id, "no library.path is configured. Create a library directory with a .codecarto-library marker file, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml. Example config:\n  library:\n    path: ~/codecarto-library\n    publish_confirm: true");
+            // When a config file was dropped, that — not a missing key — is the
+            // likeliest reason there is no path; say so ahead of the example.
+            const problems = config.problems.length > 0 ? `${describeConfigProblems(config).join("\n")}\n` : "";
+            throw new PhasePreflightError(phase.id, `${problems}no library.path is configured. Create a library directory with a .codecarto-library marker file, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml. Example config:\n  library:\n    path: ~/codecarto-library\n    publish_confirm: true`);
         }
         const marker = await discoverLibrary(config.library.path);
         if (!marker) {

package/dist/core/usage.d.ts

@@ -44,6 +44,14 @@ export interface UsageTotals {
     compactions: CompactionTelemetry;
 }
 export declare function loadUsage(workspaceDir: string): Promise<UsageFile>;
+/**
+ * Append one run. The read-modify-write runs under the file's lock and lands
+ * through an atomic write, so concurrent appends (a Pi runner and an MCP host
+ * on one workspace, two phases finishing together) each keep their record
+ * (#226, #238). A log that exists but does not parse is never rewritten: the
+ * lenient {@link loadUsage} is for display, and appending over its empty
+ * fallback destroyed every record the file still held.
+ */
 export declare function appendUsageRun(workspaceDir: string, run: UsageRun): Promise<void>;
 export declare function computeTotals(file: UsageFile): UsageTotals;
 export declare function computePerPhaseTotals(file: UsageFile): Map<string, UsageTotals>;

package/dist/core/usage.js

@@ -7,9 +7,10 @@
 // running, and phases run sequentially against this file, so a plain
 // read-modify-write is safe enough. If parallel-phase dispatch ever ships,
 // switch this to atomic-rename (see core/workspace.ts for the pattern).
-import { readFile, rename, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { pathExists } from "./utils.js";
+import { acquireLock } from "./status.js";
+import { atomicWriteFile, pathExists } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 export const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
 const SCHEMA_VERSION = 1;
@@ -29,13 +30,40 @@ export async function loadUsage(workspaceDir) {
         return emptyUsage();
     }
 }
+/**
+ * Append one run. The read-modify-write runs under the file's lock and lands
+ * through an atomic write, so concurrent appends (a Pi runner and an MCP host
+ * on one workspace, two phases finishing together) each keep their record
+ * (#226, #238). A log that exists but does not parse is never rewritten: the
+ * lenient {@link loadUsage} is for display, and appending over its empty
+ * fallback destroyed every record the file still held.
+ */
 export async function appendUsageRun(workspaceDir, run) {
-    const current = await loadUsage(workspaceDir);
-    current.runs.push(run);
     const path = join(workspaceDir, USAGE_RELATIVE_PATH);
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${stringifySimpleYaml(current)}\n`, "utf8");
-    await rename(tempPath, path);
+    const lock = await acquireLock(`${path}.lock`);
+    try {
+        const current = await loadUsageForAppend(path);
+        current.runs.push(run);
+        await atomicWriteFile(path, `${stringifySimpleYaml(current)}\n`);
+    }
+    finally {
+        await lock.release();
+    }
+}
+async function loadUsageForAppend(path) {
+    if (!(await pathExists(path)))
+        return emptyUsage();
+    const raw = await readFile(path, "utf8");
+    let parsed;
+    try {
+        parsed = parseSimpleYaml(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Refusing to append to ${USAGE_RELATIVE_PATH}: the existing file does not parse (${reason}). ` +
+            "Its records are still in it — move the file aside to start a new log.");
+    }
+    return normalize(parsed);
 }
 export function computeTotals(file) {
     const totals = emptyTotals();

package/dist/core/utils.d.ts

@@ -1,15 +1,42 @@
 export declare function sleep(ms: number): Promise<void>;
 export declare function pathExists(path: string): Promise<boolean>;
+/**
+ * A temp-file suffix that is unique within and across processes: pid, a
+ * per-process sequence number, and random bytes. `<pid>.<Date.now()>` alone
+ * collides whenever two writers hit one target inside a millisecond, and the
+ * loser's rename then either fails with ENOENT or clobbers the winner (#226).
+ */
+export declare function uniqueTempSuffix(): string;
+/**
+ * Write `content` to `path` atomically: a uniquely named sibling temp file,
+ * then a rename over the target. Readers see the old bytes or the new bytes,
+ * never a truncated file. On failure the temp file is removed best-effort and
+ * the error propagates. Every framework file that is rewritten in place goes
+ * through this so no caller hand-rolls the temp name.
+ */
+export declare function atomicWriteFile(path: string, content: string): Promise<void>;
 export declare function canonicalPath(path: string): Promise<string>;
 export declare function normalizeForComparison(path: string): string;
 export declare function isWithinPath(path: string, root: string): boolean;
 /**
- * Symlink-aware version of isWithinPath. Resolves symlinks on both the path
- * and root before comparing, preventing bypass via symlinks inside the
- * allowed root that point outside it.
+ * Resolve a path the way the kernel will when something is written to it:
+ * every component that already exists is followed through symlinks
+ * (`realpath`), and the not-yet-existing tail is appended lexically. A `..`
+ * is applied to the *resolved* prefix, not the spelled one, because
+ * `link/..` means the link target's parent on disk. A relative `path` is
+ * taken against `base` without normalisation for the same reason.
  *
- * Falls back to lexical isWithinPath if realpath fails (e.g., path does not
- * exist yet), which is safe for write targets that haven't been created.
+ * `realpath` alone throws for a file that does not exist yet, and a lexical
+ * fallback let `.codecarto/link/new.md` through when `link` was a symlink to
+ * somewhere outside the workspace — the file landed outside (#223).
+ */
+export declare function resolveExistingPrefix(path: string, base?: string): Promise<string>;
+/**
+ * Symlink-aware version of isWithinPath for paths that may not exist yet:
+ * the existing prefix of `path` is resolved through symlinks
+ * ({@link resolveExistingPrefix}), the root through `realpath`, and the two
+ * are compared lexically. A symlinked ancestor that points outside the root
+ * fails whether or not the target file exists.
  */
 export declare function isWithinPathResolved(path: string, root: string): Promise<boolean>;
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/core/utils.js

@@ -1,10 +1,10 @@
 // General-purpose helpers used by yaml/status/prompts and by wrapper-specific
 // path-boundary enforcement (Pi tool interception, MCP cwd validation).
-import { access } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { access, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { homedir } from "node:os";
-import { join, normalize, resolve } from "node:path";
-import { realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, parse, resolve, sep } from "node:path";
 export function sleep(ms) {
     return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
@@ -17,6 +17,35 @@ export async function pathExists(path) {
         return false;
     }
 }
+let tempSequence = 0;
+/**
+ * A temp-file suffix that is unique within and across processes: pid, a
+ * per-process sequence number, and random bytes. `<pid>.<Date.now()>` alone
+ * collides whenever two writers hit one target inside a millisecond, and the
+ * loser's rename then either fails with ENOENT or clobbers the winner (#226).
+ */
+export function uniqueTempSuffix() {
+    tempSequence = (tempSequence + 1) % 0x7fffffff;
+    return `${process.pid}.${tempSequence}.${randomBytes(4).toString("hex")}`;
+}
+/**
+ * Write `content` to `path` atomically: a uniquely named sibling temp file,
+ * then a rename over the target. Readers see the old bytes or the new bytes,
+ * never a truncated file. On failure the temp file is removed best-effort and
+ * the error propagates. Every framework file that is rewritten in place goes
+ * through this so no caller hand-rolls the temp name.
+ */
+export async function atomicWriteFile(path, content) {
+    const tempPath = `${path}.${uniqueTempSuffix()}.tmp`;
+    try {
+        await writeFile(tempPath, content, "utf8");
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 export async function canonicalPath(path) {
     try {
         return await realpath(path);
@@ -43,25 +72,58 @@ export function isWithinPath(path, root) {
     return normalizedPath.startsWith(prefix);
 }
 /**
- * Symlink-aware version of isWithinPath. Resolves symlinks on both the path
- * and root before comparing, preventing bypass via symlinks inside the
- * allowed root that point outside it.
+ * Resolve a path the way the kernel will when something is written to it:
+ * every component that already exists is followed through symlinks
+ * (`realpath`), and the not-yet-existing tail is appended lexically. A `..`
+ * is applied to the *resolved* prefix, not the spelled one, because
+ * `link/..` means the link target's parent on disk. A relative `path` is
+ * taken against `base` without normalisation for the same reason.
  *
- * Falls back to lexical isWithinPath if realpath fails (e.g., path does not
- * exist yet), which is safe for write targets that haven't been created.
+ * `realpath` alone throws for a file that does not exist yet, and a lexical
+ * fallback let `.codecarto/link/new.md` through when `link` was a symlink to
+ * somewhere outside the workspace — the file landed outside (#223).
  */
-export async function isWithinPathResolved(path, root) {
-    try {
-        const resolvedPath = await realpath(path);
-        const resolvedRoot = await realpath(root);
-        return isWithinPath(resolvedPath, resolvedRoot);
-    }
-    catch {
-        // If realpath fails (path doesn't exist yet, broken symlink, etc.),
-        // fall back to lexical check. For write targets this is safe because
-        // the parent directory should already be within the root.
-        return isWithinPath(path, root);
+export async function resolveExistingPrefix(path, base = process.cwd()) {
+    const raw = isAbsolute(path) ? path : `${base}${sep}${path}`;
+    const { root } = parse(raw);
+    const segments = raw
+        .slice(root.length)
+        .split(/[\\/]+/)
+        .filter((segment) => segment !== "" && segment !== ".");
+    let current = await canonicalPath(root || sep);
+    const tail = [];
+    for (const segment of segments) {
+        if (segment === "..") {
+            if (tail.length > 0)
+                tail.pop();
+            else
+                current = dirname(current);
+            continue;
+        }
+        if (tail.length > 0) {
+            // Once one component is missing, nothing below it can exist either.
+            tail.push(segment);
+            continue;
+        }
+        try {
+            current = await realpath(join(current, segment));
+        }
+        catch {
+            tail.push(segment);
+        }
     }
+    return tail.length === 0 ? current : join(current, ...tail);
+}
+/**
+ * Symlink-aware version of isWithinPath for paths that may not exist yet:
+ * the existing prefix of `path` is resolved through symlinks
+ * ({@link resolveExistingPrefix}), the root through `realpath`, and the two
+ * are compared lexically. A symlinked ancestor that points outside the root
+ * fails whether or not the target file exists.
+ */
+export async function isWithinPathResolved(path, root) {
+    const [resolvedPath, resolvedRoot] = await Promise.all([resolveExistingPrefix(path), canonicalPath(root)]);
+    return isWithinPath(resolvedPath, resolvedRoot);
 }
 export function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);