@cairn-tool/cairn 2.0.0

package/dist/scripts/resolve.js

@@ -0,0 +1,288 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { configIn, findConfig } from "../config.js";
+import { isInside, object } from "../config-schema.js";
+import { repositoryFor } from "../git.js";
+import { emptyRegistry, parseScriptsBlock } from "./registry.js";
+/**
+ * Resolves a script name to the definition that wins for a given working
+ * directory.
+ *
+ * The walk here is deliberately not `findConfig`, which returns the nearest
+ * `.cairn.yml` and stops. A nested configuration that exists but does not
+ * define the requested name must not shadow an ancestor that does, so every file
+ * from the invocation directory up to the boundary is consulted and the nearest
+ * *definition of the name* wins.
+ */
+/** A registry file larger than this is not one anybody wrote by hand. */
+const MAX_REGISTRY_BYTES = 1024 * 1024;
+/** Enough of the head to catch a binary file mistakenly named `.cairn.yml`. */
+const NUL_PROBE_BYTES = 8 * 1024;
+/** Byte comparison; never `localeCompare`, which is ICU-build dependent. */
+function byteOrder(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function realpath(target) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function hasNodeModules(directory) {
+    return directory.split(path.sep).includes("node_modules");
+}
+export function resolveBoundary(options = {}) {
+    const invokedFrom = realpath(path.resolve(options.cwd ?? process.cwd()));
+    const selection = options.selection;
+    if (selection?.disabled)
+        return { directory: invokedFrom, kind: "disabled" };
+    if (selection?.explicitPath) {
+        return { directory: path.dirname(realpath(selection.explicitPath)), kind: "single-config" };
+    }
+    const candidates = [];
+    if (options.root) {
+        const root = realpath(path.resolve(options.root));
+        if (!isInside(root, invokedFrom)) {
+            throw new Error(`--root is not an ancestor of the working directory: ${options.root}`);
+        }
+        candidates.push({ directory: root, kind: "explicit-root" });
+    }
+    try {
+        candidates.push({ directory: repositoryFor(invokedFrom).root, kind: "git-root" });
+    }
+    catch {
+        // Not a repository, or git is not on PATH. Both are ordinary here.
+    }
+    if (candidates.length > 0) {
+        // The deeper of the two stops the walk sooner, so it is the safer reading of
+        // "whichever is found first" while ascending.
+        return candidates.reduce((deepest, candidate) => candidate.directory.length > deepest.directory.length ? candidate : deepest);
+    }
+    const nearest = findConfig(invokedFrom);
+    return {
+        directory: nearest ? path.dirname(realpath(nearest)) : invokedFrom,
+        kind: "nearest-config",
+    };
+}
+/**
+ * Reads one candidate registry file.
+ *
+ * The guards mirror `readSnippetSource` in `src/snippets.ts`: realpath first,
+ * then containment, then a regular-file check — a FIFO would block the read
+ * forever and wedge a hook with no output — then a size cap and a NUL probe.
+ */
+function readRegistry(file, boundary, distance) {
+    const directory = path.dirname(file);
+    const base = { file, directory, distance, status: "skipped", names: [] };
+    let real;
+    try {
+        real = fs.realpathSync(file);
+    }
+    catch {
+        return { consulted: { ...base, reason: "Unreadable" } };
+    }
+    if (!isInside(boundary, real)) {
+        return { consulted: { ...base, reason: "Resolves outside the boundary" } };
+    }
+    let stat;
+    try {
+        stat = fs.lstatSync(real);
+    }
+    catch {
+        return { consulted: { ...base, reason: "Unreadable" } };
+    }
+    if (!stat.isFile()) {
+        return { consulted: { ...base, reason: "Not a regular file" } };
+    }
+    if (stat.size > MAX_REGISTRY_BYTES) {
+        return { consulted: { ...base, reason: `Larger than ${MAX_REGISTRY_BYTES} bytes` } };
+    }
+    let contents;
+    try {
+        const buffer = fs.readFileSync(real);
+        if (buffer.subarray(0, NUL_PROBE_BYTES).includes(0)) {
+            return { consulted: { ...base, reason: "Not a text file" } };
+        }
+        contents = buffer.toString("utf-8");
+    }
+    catch {
+        return { consulted: { ...base, reason: "Unreadable" } };
+    }
+    let registry;
+    try {
+        const parsed = object(parseYaml(contents), "configuration");
+        if (parsed.scripts === undefined) {
+            return {
+                consulted: { ...base, status: "no-scripts" },
+                registry: emptyRegistry(file, directory),
+            };
+        }
+        registry = parseScriptsBlock(parsed.scripts, { file, directory });
+    }
+    catch (error) {
+        const reason = error.message.split("\n")[0];
+        return { consulted: { ...base, status: "invalid", reason } };
+    }
+    const names = [...registry.scripts.keys()].sort(byteOrder);
+    return { consulted: { ...base, status: "declares", names }, registry };
+}
+/**
+ * Walks from the invocation directory to the boundary, inclusive, nearest first.
+ *
+ * Only the `scripts:` block of each file is validated. An ancestor belongs to a
+ * different project, and a malformed `urls:` block there is none of this
+ * command's business — failing on it would make one broken package configuration
+ * break `scripts run` for every sibling.
+ */
+function walk(boundary, options) {
+    if (boundary.kind === "disabled")
+        return [];
+    if (boundary.kind === "single-config") {
+        const file = realpath(options.selection?.explicitPath ?? "");
+        if (!fs.existsSync(file)) {
+            throw new Error(`Configuration file not found: ${options.selection?.explicitPath}`);
+        }
+        return [readRegistry(file, boundary.directory, 0)];
+    }
+    const invokedFrom = realpath(path.resolve(options.cwd ?? process.cwd()));
+    const steps = [];
+    let current = invokedFrom;
+    let distance = 0;
+    while (true) {
+        // A vendored package that ships a `.cairn.yml` would otherwise win over
+        // the project's own registry for any invocation inside it.
+        if (!hasNodeModules(current)) {
+            // `configIn` stops at the first name it finds, so a directory holding both
+            // the current and the legacy filename contributes one step rather than two
+            // — the legacy file must not read as a registry the new one shadows.
+            const candidate = configIn(current);
+            if (candidate)
+                steps.push(readRegistry(candidate, boundary.directory, distance));
+        }
+        if (current === boundary.directory)
+            break;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+        distance++;
+    }
+    return steps;
+}
+/**
+ * The directory a script runs in.
+ *
+ * Containment is checked on the *resolved* directory, not on the spelling: `cwd`
+ * decides where the script's own relative paths land, which makes it the more
+ * attractive escape of the two paths this module resolves.
+ */
+function workingDirectoryFor(definition, registry, invokedFrom, boundary) {
+    const target = definition.cwd.kind === "registry"
+        ? registry.directory
+        : definition.cwd.kind === "invocation"
+            ? invokedFrom
+            : path.resolve(registry.directory, definition.cwd.value);
+    const resolved = realpath(target);
+    if (boundary.kind !== "disabled" && !isInside(boundary.directory, resolved)) {
+        throw new Error(`Script '${definition.name}' resolves a working directory outside the boundary: ${resolved}`);
+    }
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+        throw new Error(`Script '${definition.name}' has a working directory that does not exist: ${resolved}`);
+    }
+    return resolved;
+}
+export function resolveScript(name, options = {}) {
+    const invokedFrom = realpath(path.resolve(options.cwd ?? process.cwd()));
+    const boundary = resolveBoundary(options);
+    const steps = walk(boundary, options);
+    const consulted = [];
+    const definitions = [];
+    for (const step of steps) {
+        const declares = step.registry?.scripts.has(name) ?? false;
+        consulted.push(declares ? { ...step.consulted, status: "defines" } : step.consulted);
+        if (declares && step.registry) {
+            definitions.push({ definition: step.registry.scripts.get(name), registry: step.registry });
+        }
+    }
+    const resolution = {
+        name,
+        boundary,
+        invokedFrom,
+        consulted,
+        shadowed: definitions.slice(1).map(({ registry, definition }) => ({
+            file: registry.file,
+            directory: registry.directory,
+            ...(definition.description ? { description: definition.description } : {}),
+        })),
+    };
+    const nearest = definitions[0];
+    if (nearest) {
+        resolution.winner = {
+            definition: nearest.definition,
+            registry: nearest.registry,
+            workingDirectory: workingDirectoryFor(nearest.definition, nearest.registry, invokedFrom, boundary),
+        };
+    }
+    return resolution;
+}
+/**
+ * The first invalid file that could have changed the answer, if any.
+ *
+ * A file farther from the invocation directory than the winner cannot have won,
+ * so it must not break the run. A nearer one might have defined the name, and
+ * running the wrong script is precisely the failure this design exists to
+ * prevent.
+ */
+export function shadowingFailure(resolution) {
+    const winnerDistance = resolution.consulted.find((file) => file.status === "defines")?.distance;
+    return resolution.consulted.find((file) => file.status === "invalid" && (winnerDistance === undefined || file.distance < winnerDistance));
+}
+export function listScripts(options = {}) {
+    const invokedFrom = realpath(path.resolve(options.cwd ?? process.cwd()));
+    const boundary = resolveBoundary(options);
+    const steps = walk(boundary, options);
+    const entries = new Map();
+    for (const step of steps) {
+        if (!step.registry)
+            continue;
+        for (const [name, definition] of step.registry.scripts) {
+            const existing = entries.get(name);
+            if (existing) {
+                // Nearest wins; a farther definition only records that it was shadowed.
+                existing.shadows.push(step.registry.file);
+                continue;
+            }
+            let workingDirectory;
+            try {
+                workingDirectory = workingDirectoryFor(definition, step.registry, invokedFrom, boundary);
+            }
+            catch {
+                // `list` reports what is declared; a bad `cwd` is `run`'s problem to
+                // refuse, and hiding the entry here would make it harder to diagnose.
+                workingDirectory = step.registry.directory;
+            }
+            entries.set(name, {
+                name,
+                ...(definition.description ? { description: definition.description } : {}),
+                form: definition.run !== undefined ? "run" : "exec",
+                ...(definition.run !== undefined ? { run: definition.run } : {}),
+                ...(definition.exec !== undefined ? { exec: definition.exec } : {}),
+                ...(definition.shell !== undefined ? { shell: definition.shell } : {}),
+                file: step.registry.file,
+                directory: step.registry.directory,
+                workingDirectory,
+                shadows: [],
+            });
+        }
+    }
+    return {
+        boundary,
+        invokedFrom,
+        consulted: steps.map((step) => step.consulted),
+        scripts: [...entries.values()].sort((left, right) => byteOrder(left.name, right.name)),
+    };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/scripts/resolve.js.map

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

package/dist/sections.d.ts

@@ -0,0 +1,53 @@
+import { type MdHeading } from "./markdown-ast.js";
+import type { MarkdownDocument } from "./workspace.js";
+export interface DocumentSection {
+    file: string;
+    /** Null for the content preceding the first heading. */
+    heading: MdHeading | null;
+    /** Heading depth; 0 for the preamble. */
+    depth: number;
+    /** 1-indexed, inclusive. */
+    startLine: number;
+    /** 1-indexed, inclusive. Less than `startLine` for an empty section. */
+    endLine: number;
+    content: string;
+}
+/**
+ * Line number of a document's closing frontmatter fence, or 0 when there is none.
+ *
+ * `Workspace.document` parses with `parseMarkdown`, which has no frontmatter
+ * extension, so a short frontmatter block whose body is one paragraph-shaped run
+ * becomes a setext heading: `---\ntitle: X\n---` yields a phantom depth-2
+ * heading. Callers that reason about document structure filter on this rather
+ * than inheriting the phantom.
+ */
+export declare function frontmatterEndLine(content: string): number;
+/**
+ * The flat partition of a document: every heading owns the lines up to the next
+ * heading of any depth, and the preamble owns whatever precedes the first one.
+ *
+ * Non-overlapping and exhaustive, which is what makes byte accounting over the
+ * result exact. Nested sections are deliberately absent — a `--children` view
+ * would double-count every ancestor's bytes.
+ */
+export declare function documentSections(document: MarkdownDocument): DocumentSection[];
+/** A section located by name, which therefore always has a heading. */
+export interface MatchedSection extends DocumentSection {
+    heading: MdHeading;
+}
+/** Position in `sections` of the section named by `heading`, or -1. */
+export declare function matchSectionIndex(sections: readonly DocumentSection[], heading: string): number;
+export interface FindSectionOptions {
+    /** Extend the section through headings deeper than the match. Defaults to true. */
+    children?: boolean;
+    /** Include the heading line itself. Defaults to true. */
+    includeHeading?: boolean;
+}
+/**
+ * Locates one section by heading text or slug.
+ *
+ * Reproduces `md section`'s rule exactly, including its use of the unfiltered
+ * heading list — that command predates `frontmatterEndLine` and its output is
+ * published.
+ */
+export declare function findSection(document: MarkdownDocument, heading: string, options?: FindSectionOptions): MatchedSection | undefined;

package/dist/sections.js

@@ -0,0 +1,100 @@
+import { slugify } from "./markdown-ast.js";
+/**
+ * Line number of a document's closing frontmatter fence, or 0 when there is none.
+ *
+ * `Workspace.document` parses with `parseMarkdown`, which has no frontmatter
+ * extension, so a short frontmatter block whose body is one paragraph-shaped run
+ * becomes a setext heading: `---\ntitle: X\n---` yields a phantom depth-2
+ * heading. Callers that reason about document structure filter on this rather
+ * than inheriting the phantom.
+ */
+export function frontmatterEndLine(content) {
+    if (!content.startsWith("---\n") && !content.startsWith("---\r\n"))
+        return 0;
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/);
+    if (!match)
+        return 0;
+    return match[0].replace(/\r?\n$/, "").split(/\r?\n/).length;
+}
+/**
+ * The flat partition of a document: every heading owns the lines up to the next
+ * heading of any depth, and the preamble owns whatever precedes the first one.
+ *
+ * Non-overlapping and exhaustive, which is what makes byte accounting over the
+ * result exact. Nested sections are deliberately absent — a `--children` view
+ * would double-count every ancestor's bytes.
+ */
+export function documentSections(document) {
+    const lines = document.content.split("\n");
+    const frontmatterEnd = frontmatterEndLine(document.content);
+    const headings = document.headings.filter((heading) => heading.line > frontmatterEnd);
+    const slice = (start, end) => end >= start ? lines.slice(start - 1, end).join("\n") : "";
+    const sections = [];
+    const preambleStart = frontmatterEnd + 1;
+    const preambleEnd = (headings.length ? headings[0].line : lines.length + 1) - 1;
+    if (preambleEnd >= preambleStart) {
+        sections.push({
+            file: document.path,
+            heading: null,
+            depth: 0,
+            startLine: preambleStart,
+            endLine: preambleEnd,
+            content: slice(preambleStart, preambleEnd),
+        });
+    }
+    for (let index = 0; index < headings.length; index++) {
+        const startLine = headings[index].line;
+        const endLine = index + 1 < headings.length ? headings[index + 1].line - 1 : lines.length;
+        sections.push({
+            file: document.path,
+            heading: headings[index],
+            depth: headings[index].depth,
+            startLine,
+            endLine,
+            content: slice(startLine, endLine),
+        });
+    }
+    return sections;
+}
+/** The shared heading lookup rule: case-insensitive text, or slug. */
+function matches(heading, query) {
+    return heading.text.toLowerCase() === query.toLowerCase() || heading.slug === slugify(query);
+}
+/** Position in `sections` of the section named by `heading`, or -1. */
+export function matchSectionIndex(sections, heading) {
+    return sections.findIndex((section) => section.heading !== null && matches(section.heading, heading));
+}
+/**
+ * Locates one section by heading text or slug.
+ *
+ * Reproduces `md section`'s rule exactly, including its use of the unfiltered
+ * heading list — that command predates `frontmatterEndLine` and its output is
+ * published.
+ */
+export function findSection(document, heading, options = {}) {
+    const children = options.children ?? true;
+    const includeHeading = options.includeHeading ?? true;
+    const headings = document.headings;
+    const matchIndex = headings.findIndex((candidate) => matches(candidate, heading));
+    if (matchIndex === -1)
+        return undefined;
+    const matched = headings[matchIndex];
+    const lines = document.content.split("\n");
+    let endLine = lines.length;
+    for (let index = matchIndex + 1; index < headings.length; index++) {
+        if (!children || headings[index].depth <= matched.depth) {
+            endLine = headings[index].line - 1;
+            break;
+        }
+    }
+    const startLine = includeHeading ? matched.line : matched.line + 1;
+    return {
+        file: document.path,
+        heading: matched,
+        depth: matched.depth,
+        startLine,
+        endLine,
+        content: endLine >= startLine ? lines.slice(startLine - 1, endLine).join("\n") : "",
+    };
+}
+//# sourceMappingURL=sections.js.map

package/dist/sections.js.map

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

package/dist/serve/errors.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Rewrites absolute paths out of a message before it reaches the client.
+ *
+ * Paths under the served root become root-relative, which is the form every
+ * tool result already uses. Anything still absolute is replaced outright rather
+ * than shortened: those are the paths a confinement failure refused to serve,
+ * and echoing one back in the error would disclose exactly what was withheld.
+ */
+export declare function scrub(message: string, root: string): string;
+/**
+ * Maps a thrown error to a tool result the model can act on.
+ *
+ * Workspace-layer failures — a missing file, an unmatched heading, a malformed
+ * query, a rejected path — are the model's to correct, so they come back as
+ * `isError` content rather than as JSON-RPC errors. Protocol-level mistakes
+ * (an unknown tool, arguments that fail their schema) are raised as `McpError`
+ * by the caller instead and never reach here.
+ *
+ * `CommandExit` is caught defensively: no tool calls a command action, but a
+ * stray call into `src/input.ts` would otherwise surface as an internal error.
+ */
+export declare function toolFailure(error: unknown, root: string): CallToolResult;
+/** Whether `error` came from confinement, which callers may want to log distinctly. */
+export declare function isRejection(error: unknown): boolean;

package/dist/serve/errors.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { CommandExit } from "../command-result.js";
+import { PathRejected } from "./paths.js";
+/** Any `/`- or drive-rooted run of non-whitespace, once root-relative paths are out of the way. */
+const ABSOLUTE = /(?:[A-Za-z]:)?[/\\][^\s"'`,;)]+/g;
+/**
+ * Rewrites absolute paths out of a message before it reaches the client.
+ *
+ * Paths under the served root become root-relative, which is the form every
+ * tool result already uses. Anything still absolute is replaced outright rather
+ * than shortened: those are the paths a confinement failure refused to serve,
+ * and echoing one back in the error would disclose exactly what was withheld.
+ */
+export function scrub(message, root) {
+    const withRoot = message.split(`${root}${path.sep}`).join("").split(root).join(".");
+    return withRoot.replace(ABSOLUTE, "<path outside root>");
+}
+/**
+ * Maps a thrown error to a tool result the model can act on.
+ *
+ * Workspace-layer failures — a missing file, an unmatched heading, a malformed
+ * query, a rejected path — are the model's to correct, so they come back as
+ * `isError` content rather than as JSON-RPC errors. Protocol-level mistakes
+ * (an unknown tool, arguments that fail their schema) are raised as `McpError`
+ * by the caller instead and never reach here.
+ *
+ * `CommandExit` is caught defensively: no tool calls a command action, but a
+ * stray call into `src/input.ts` would otherwise surface as an internal error.
+ */
+export function toolFailure(error, root) {
+    const message = error instanceof CommandExit
+        ? `Command exited with status ${error.exitCode}`
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return {
+        content: [{ type: "text", text: scrub(message, root) }],
+        isError: true,
+    };
+}
+/** Whether `error` came from confinement, which callers may want to log distinctly. */
+export function isRejection(error) {
+    return error instanceof PathRejected;
+}
+//# sourceMappingURL=errors.js.map

package/dist/serve/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/serve/errors.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,mGAAmG;AACnG,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,IAAY;IACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpF,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,IAAY;IACtD,MAAM,OAAO,GACX,KAAK,YAAY,WAAW;QAC1B,CAAC,CAAC,8BAA8B,KAAK,CAAC,QAAQ,EAAE;QAChD,CAAC,CAAC,KAAK,YAAY,KAAK;YACtB,CAAC,CAAC,KAAK,CAAC,OAAO;YACf,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtB,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,YAAY,CAAC;AACvC,CAAC"}

package/dist/serve/paths.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A path argument that failed confinement, or otherwise cannot be served.
+ *
+ * Carries no absolute path: a rejected traversal names precisely the location
+ * the server declined to disclose.
+ */
+export declare class PathRejected extends Error {
+}
+/**
+ * Resolves `root` through any symlinks, so comparisons against it are physical.
+ *
+ * Called once at startup. A root that does not exist is a startup failure, not
+ * a per-call one.
+ */
+export declare function resolveRoot(root: string): string;
+/**
+ * The real path `value` names, once confined to `root`.
+ *
+ * Confinement is physical rather than lexical. `Workspace.inside` compares with
+ * `path.relative` alone, and `Workspace.markdownFiles` admits symlinked *files*
+ * even though it skips symlinked directories — so a `.md` symlink inside the
+ * root pointing outside it would otherwise be served. Resolving both sides also
+ * makes the comparison correct on macOS, where `/tmp` is a symlink to
+ * `/private/tmp`.
+ *
+ * The nearest existing ancestor is resolved rather than the target itself, so a
+ * path that simply does not exist reports as missing by the caller's own check
+ * instead of being reported as a confinement failure.
+ */
+export declare function confine(root: string, value: string, label?: string): string;
+/** Renders an absolute path relative to `root`, which is what tool results carry. */
+export declare function relativeTo(root: string, target: string): string;

package/dist/serve/paths.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * A path argument that failed confinement, or otherwise cannot be served.
+ *
+ * Carries no absolute path: a rejected traversal names precisely the location
+ * the server declined to disclose.
+ */
+export class PathRejected extends Error {
+}
+/**
+ * Resolves `root` through any symlinks, so comparisons against it are physical.
+ *
+ * Called once at startup. A root that does not exist is a startup failure, not
+ * a per-call one.
+ */
+export function resolveRoot(root) {
+    const absolute = path.resolve(root);
+    if (!fs.existsSync(absolute) || !fs.statSync(absolute).isDirectory()) {
+        throw new Error(`Root directory not found: ${absolute}`);
+    }
+    return fs.realpathSync(absolute);
+}
+/** Whether `target` is `root` or lies beneath it, compared lexically. */
+function within(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+/**
+ * The real path `value` names, once confined to `root`.
+ *
+ * Confinement is physical rather than lexical. `Workspace.inside` compares with
+ * `path.relative` alone, and `Workspace.markdownFiles` admits symlinked *files*
+ * even though it skips symlinked directories — so a `.md` symlink inside the
+ * root pointing outside it would otherwise be served. Resolving both sides also
+ * makes the comparison correct on macOS, where `/tmp` is a symlink to
+ * `/private/tmp`.
+ *
+ * The nearest existing ancestor is resolved rather than the target itself, so a
+ * path that simply does not exist reports as missing by the caller's own check
+ * instead of being reported as a confinement failure.
+ */
+export function confine(root, value, label = "path") {
+    if (value === "-") {
+        // On a stdio server fd 0 is the JSON-RPC channel. `requireFile("-")` would
+        // read it and deadlock the transport, so "-" never reaches the workspace.
+        throw new PathRejected(`A ${label} of "-" is not available over MCP`);
+    }
+    if (value.includes("\0"))
+        throw new PathRejected(`Invalid ${label}`);
+    const absolute = path.resolve(root, value);
+    let existing = absolute;
+    while (!fs.existsSync(existing)) {
+        const parent = path.dirname(existing);
+        if (parent === existing)
+            break;
+        existing = parent;
+    }
+    const real = fs.existsSync(existing)
+        ? path.join(fs.realpathSync(existing), path.relative(existing, absolute))
+        : absolute;
+    if (!within(root, real))
+        throw new PathRejected(`The ${label} is outside the served root`);
+    return real;
+}
+/** Renders an absolute path relative to `root`, which is what tool results carry. */
+export function relativeTo(root, target) {
+    const relative = path.relative(root, target);
+    return (relative === "" ? "." : relative).split(path.sep).join("/");
+}
+//# sourceMappingURL=paths.js.map

package/dist/serve/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/serve/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;CAAG;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED,yEAAyE;AACzE,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,QAAQ,KAAK,IAAI,CAAC,CAAC;AACzF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,KAAa,EAAE,KAAK,GAAG,MAAM;IACjE,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QAClB,2EAA2E;QAC3E,0EAA0E;QAC1E,MAAM,IAAI,YAAY,CAAC,KAAK,KAAK,mCAAmC,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC;IAErE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3C,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM;QAC/B,QAAQ,GAAG,MAAM,CAAC;IACpB,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAClC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACzE,CAAC,CAAC,QAAQ,CAAC;IAEb,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,OAAO,KAAK,6BAA6B,CAAC,CAAC;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAc;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC"}