@jini-ai/vibecoding 0.6.10 → 0.6.11

package/dist/html/node/parse5-region-parser.js

@@ -45,10 +45,11 @@
  * source text's occurrence count against what the tree walk actually found, independent of
  * parse5's own error stream.
  *
- * Both mechanisms are handled uniformly: `findRegions` throws (never returns a silently-shortened
- * list), and `checkWellFormed` reports the same problem through the port's ordinary rejection
- * channel so `regions.ts`'s `validate` can surface it as a model-facing reason before `findRegions`
- * is ever reached a second time for the same prospective document.
+ * `scanHtmlRegions` retains every tree-discovered handle, recording unsafe boundaries on that
+ * region and dropped-source handles as a document diagnostic. Reads can still inspect the page
+ * and edit another safely delimited region. The strict `findRegions` throws on either problem
+ * (never returns a silently-shortened list), and `checkWellFormed` reports the same problem through
+ * the port's ordinary rejection channel so `regions.ts`'s `validate` can surface it before writing.
  *
  * ## `checkWellFormed` is a courtesy diagnostic, not the safety mechanism
  *
@@ -87,69 +88,155 @@ const VOID_ELEMENTS = new Set([
 /** Matches `data-agent-element` as an attribute *name* only — deliberately not the value or its
  * quoting style, so it survives single-quoted, double-quoted and unquoted attribute forms alike.
  *
- * This is a plain substring/regex scan of the raw source, the same cost/precision tradeoff
- * `withFormGuardrail` ( Decision 8) makes for its own guardrail: a comment or script-text
- * mention of the attribute name can inflate the count and cause an over-eager rejection, but that
- * false positive is a safe failure mode (the model is asked to retry), whereas the false negative
- * this check exists to catch — a genuinely dropped region — is not.
+ * This remains a conservative source cross-check for genuinely dropped regions. Comments and
+ * raw-text bodies are blanked using parse5 locations first: a script building a handle string
+ * is not a region. Treating those examples as failures would break otherwise valid page reads.
  * See docs/decisions/DR-001-conservative-region-detection.md.
  */
 const RAW_HANDLE_ATTRIBUTE_RE = new RegExp(`\\b${AGENT_ELEMENT_ATTRIBUTE}\\s*=`, "gi");
 function attributeValue(element, name) {
     return element.attrs.find((a) => a.name === name)?.value;
 }
-/** Yields every element node in the tree, in document order, recursing into `<template>` content. */
-function* walkElements(node) {
-    if ("tagName" in node)
+/** Visit all nodes, including comments/raw text and nested template contents. */
+function* walkNodes(root) {
+    const pending = [root];
+    // An explicit stack avoids overflowing the JS call stack on deeply nested author markup.
+    while (pending.length > 0) {
+        const node = pending.pop(); // Nonempty stack on this branch.
         yield node;
-    const children = "content" in node ? node.content.childNodes : "childNodes" in node ? node.childNodes : undefined;
-    if (children === undefined)
-        return;
-    for (const child of children)
-        yield* walkElements(child);
+        const children = "content" in node ? node.content.childNodes : "childNodes" in node ? node.childNodes : undefined;
+        if (children === undefined)
+            continue;
+        for (let index = children.length - 1; index >= 0; index -= 1)
+            pending.push(children[index]);
+    }
+}
+// RCDATA bodies also contain literal text rather than child markup. Keep their source examples
+// out of the dropped-region check just like raw-text bodies; opening-tag attributes still count.
+// `noscript` is raw text too: parse5 parses with scripting enabled, as a browser running the page does.
+const TEXT_BODY_ELEMENTS = new Set([
+    "script", "style", "xmp", "iframe", "noembed", "noframes", "noscript", "plaintext", "textarea", "title",
+]);
+/** Whether a located node is a comment or the literal text body of a raw-text/RCDATA element. */
+function isNonMarkup(node) {
+    if (node.nodeName === "#comment")
+        return true;
+    if (node.nodeName !== "#text" || !("parentNode" in node))
+        return false;
+    const parent = node.parentNode;
+    return parent !== null && "tagName" in parent && TEXT_BODY_ELEMENTS.has(parent.tagName);
 }
 /** A parse-error entry, phrased for the model rather than left as parse5's bare kebab-case code. */
 function describeParseError(error) {
     return `${error.code.replace(/-/g, " ")} near character ${error.startOffset}`;
 }
-function analyzeRegion({ element, handle }, _options = {}) {
+/** Why a tagged element's boundaries are unsafe; optional closing tags are unsafe too. */
+function regionProblem(element, handle) {
     const location = element.sourceCodeLocation;
     if (location === null || location === undefined || location.startTag === undefined) {
-        return {
-            locationProblem: `a "${AGENT_ELEMENT_ATTRIBUTE}" region ("${handle}") could not be located in the document — ` +
-                "the parser's error-recovery rules likely dropped or repositioned it. Rewrite the document " +
-                "so this element is reachable in ordinary document structure (for example, not a table-only " +
-                "tag used outside a <table>).",
-        };
+        return `a "${AGENT_ELEMENT_ATTRIBUTE}" region ("${handle}") could not be located in the document — ` +
+            "the parser's error-recovery rules likely dropped or repositioned it. Rewrite the document " +
+            "so this element is reachable in ordinary document structure (for example, not a table-only " +
+            "tag used outside a <table>).";
     }
     if (location.endTag === undefined) {
-        return {
-            locationProblem: VOID_ELEMENTS.has(element.tagName)
-                ? `"${handle}" tags a <${element.tagName}> element, which is void and has no inner content — ` +
-                    `void elements cannot be a ${AGENT_ELEMENT_ATTRIBUTE} region`
-                : `a "${AGENT_ELEMENT_ATTRIBUTE}" region ("${handle}") has no closing tag the parser could ` +
-                    "locate — its content boundaries cannot be determined safely. Close the tag explicitly.",
-        };
+        return VOID_ELEMENTS.has(element.tagName)
+            ? `"${handle}" tags a <${element.tagName}> element, which is void and has no inner content — ` +
+                `void elements cannot be a ${AGENT_ELEMENT_ATTRIBUTE} region`
+            : `a "${AGENT_ELEMENT_ATTRIBUTE}" region ("${handle}") has no closing tag the parser could ` +
+                "locate — its content boundaries cannot be determined safely. Close the tag explicitly.";
     }
+    return undefined;
+}
+/** Original-source offsets shared by region discovery and top-level tagging advice. */
+function sourceOffsets(element) {
+    const location = element.sourceCodeLocation;
+    if (!location?.startTag)
+        return { start: -1, end: -1, innerStart: -1, innerEnd: -1 };
+    return {
+        start: location.startTag.startOffset,
+        end: location.endTag?.endOffset ?? location.endOffset,
+        innerStart: location.startTag.endOffset,
+        innerEnd: location.endTag?.startOffset ?? location.endOffset,
+    };
+}
+/** Keep unsafe regions discoverable; sentinel offsets are never used by locateRegion for edits. */
+function analyzeRegion(element, handle) {
     const role = attributeValue(element, "data-agent-role");
     const label = attributeValue(element, "data-agent-label");
+    const problem = regionProblem(element, handle);
     return {
-        region: {
-            handle,
-            innerStart: location.startTag.endOffset,
-            innerEnd: location.endTag.startOffset,
-            ...(role === undefined ? {} : { role }),
-            ...(label === undefined ? {} : { label }),
-        },
+        handle,
+        tag: element.tagName,
+        ...sourceOffsets(element),
+        ...(role === undefined ? {} : { role }),
+        ...(label === undefined ? {} : { label }),
+        ...(problem === undefined ? {} : { problem }),
     };
 }
+/** Direct fragment children in source order; implied closes suffice for tagging advice, not edits. */
+function topLevelElements(fragment) {
+    const elements = [];
+    for (const child of fragment.childNodes) {
+        if (!("tagName" in child))
+            continue;
+        const location = child.sourceCodeLocation;
+        if (!location?.startTag)
+            continue; // Implicit wrappers have no authored open tag to annotate.
+        const handle = attributeValue(child, AGENT_ELEMENT_ATTRIBUTE);
+        elements.push({
+            tag: child.tagName,
+            ...(handle === undefined ? {} : { handle }),
+            ...sourceOffsets(child),
+        });
+    }
+    return elements.sort((a, b) => a.start - b.start);
+}
 /**
- * One parse pass, shared by `findRegions` and `checkWellFormed` so both methods judge the same
- * parse5 run rather than parsing the document twice with a chance of disagreeing.
- *
- * @complexity Linear in document size: one parse5 pass plus one tree walk plus one regex scan.
+ * Report each authored tag once. parse5 copies an unclosed or misnested formatting element's
+ * start-tag location onto every clone it reconstructs (`<p><b data-agent-element="x">a</p><p>b`
+ * yields two `b`s starting at the same offset), and a clone can even pick up a later `</b>` that
+ * does not delimit the authored element. Counting clones would make one handle "ambiguous", and an
+ * unrelated edit that adds text after it would then look like it newly duplicated that handle.
+ * Input must be sorted by `start`; the stable sort keeps the authored element (first in tree order).
  */
-function analyzeDocument(html_) {
+function collapseClones(sorted) {
+    const out = [];
+    for (const region of sorted) {
+        const previous = out[out.length - 1];
+        if (previous === undefined || region.start < 0 || previous.start !== region.start) {
+            out.push(region);
+            continue;
+        }
+        out[out.length - 1] = {
+            ...previous,
+            problem: previous.problem ?? `"${region.handle}" tags an element the parser had to split while ` +
+                "recovering misnested or unclosed tags — its content boundaries cannot be determined safely. " +
+                "Close the tag explicitly, inside the element that contains it.",
+        };
+    }
+    return out;
+}
+/** Cross-check only markup-bearing source; recovered/dropped tokens may have no tree node. */
+function droppedRegionProblem(masked, regionCount) {
+    const rawMentions = masked.match(RAW_HANDLE_ATTRIBUTE_RE)?.length ?? 0;
+    if (rawMentions <= regionCount)
+        return undefined;
+    return `the source mentions ${AGENT_ELEMENT_ATTRIBUTE} ${rawMentions} time(s) but only ` +
+        `${regionCount} could be located in the parsed document — the parser's error-recovery ` +
+        "rules likely dropped one entirely (a common cause: a table-only tag, such as <td>, used " +
+        "outside a <table>). Rewrite the document so every tagged element sits in ordinary, " +
+        "non-table-recovery document structure.";
+}
+/**
+ * Scan once without throwing for malformed markup: unsafe regions carry their own problem, while
+ * unaccounted-for source handles produce documentProblem. Every offset indexes the untouched input.
+ * Comments/raw-text bodies are blanked by parse5's own locations before the raw-mention check.
+ * @example const scan = scanHtmlRegions({ html: '<section data-agent-element="hero">Hi</section>' });
+ * @complexity One parse and node walk, plus source-order sorting: O(n + r log r) for n source code
+ * units and r discovered elements. Masked ranges are disjoint, so blanking is linear in source size.
+ */
+export function scanHtmlRegions({ html: html_ }, _options = {}) {
     const parseErrorReasons = [];
     /** Fresh `<div>` fragment-context element — see this module's doc for why `<div>`, not the default. */
     const context = defaultTreeAdapter.createElement("div", html.NS.HTML, []);
@@ -157,33 +244,31 @@ function analyzeDocument(html_) {
         sourceCodeLocationInfo: true,
         onParseError: (error) => parseErrorReasons.push(describeParseError(error)),
     });
-    const regions = [];
-    let locationProblem;
-    for (const element of walkElements(fragment)) {
-        const handle = attributeValue(element, AGENT_ELEMENT_ATTRIBUTE);
-        if (handle === undefined || locationProblem !== undefined)
-            continue; // Already failed; stop accumulating regions.
-        const analyzed = analyzeRegion({ element, handle });
-        if ("locationProblem" in analyzed) {
-            locationProblem = analyzed.locationProblem;
+    const found = [];
+    // split("") preserves UTF-16 code units, including CRLF, BOM and astral-character offsets.
+    const masked = html_.split("");
+    for (const node of walkNodes(fragment)) {
+        const location = node.sourceCodeLocation;
+        if (isNonMarkup(node) && location)
+            masked.fill(" ", location.startOffset, location.endOffset);
+        if (!("tagName" in node))
             continue;
-        }
-        regions.push(analyzed.region);
-    }
-    if (locationProblem === undefined) {
-        const rawMentions = html_.match(RAW_HANDLE_ATTRIBUTE_RE)?.length ?? 0;
-        if (rawMentions > regions.length) {
-            locationProblem =
-                `the source mentions ${AGENT_ELEMENT_ATTRIBUTE} ${rawMentions} time(s) but only ` +
-                    `${regions.length} could be located in the parsed document — the parser's error-recovery ` +
-                    "rules likely dropped one entirely (a common cause: a table-only tag, such as <td>, used " +
-                    "outside a <table>). Rewrite the document so every tagged element sits in ordinary, " +
-                    "non-table-recovery document structure.";
-        }
+        const handle = attributeValue(node, AGENT_ELEMENT_ATTRIBUTE);
+        if (handle !== undefined)
+            found.push(analyzeRegion(node, handle));
     }
-    return locationProblem === undefined
-        ? { regions, parseErrorReasons }
-        : { regions, locationProblem, parseErrorReasons };
+    const regions = collapseClones(found.sort((a, b) => a.start - b.start));
+    const documentProblem = droppedRegionProblem(masked.join(""), regions.length);
+    return {
+        regions,
+        topLevel: topLevelElements(fragment),
+        parseErrorReasons,
+        ...(documentProblem === undefined ? {} : { documentProblem }),
+    };
+}
+/** Preserve strict rejection precedence: an unsafe discovered region before a dropped-source handle. */
+function locationProblem(scan) {
+    return scan.regions.find((region) => region.problem !== undefined)?.problem ?? scan.documentProblem;
 }
 /**
  * Build the parse5-backed `HtmlRegionParser`. Stateless — a single instance is safe to share as a
@@ -191,20 +276,23 @@ function analyzeDocument(html_) {
  *
  * @returns a parser ready to hand to `createHtmlRegionTarget`, with `checkWellFormed` always
  * present even though the generic parser port allows implementations to omit it.
- * @complexity 1 (delegates entirely to `analyzeDocument`)
+ * @complexity 1 (delegates to `scanHtmlRegions`)
  */
 export function createParse5RegionParser() {
     return {
         findRegions({ html: html_ }) {
-            const { regions, locationProblem } = analyzeDocument(html_);
-            if (locationProblem !== undefined)
-                throw new Error(locationProblem);
-            return regions;
+            const scan = scanHtmlRegions({ html: html_ });
+            const problem = locationProblem(scan);
+            if (problem !== undefined)
+                throw new Error(problem);
+            return scan.regions;
         },
         checkWellFormed({ html: html_ }) {
-            const { locationProblem, parseErrorReasons } = analyzeDocument(html_);
-            if (locationProblem !== undefined)
-                return { ok: false, reason: locationProblem };
+            const scan = scanHtmlRegions({ html: html_ });
+            const problem = locationProblem(scan);
+            if (problem !== undefined)
+                return { ok: false, reason: problem };
+            const parseErrorReasons = scan.parseErrorReasons ?? [];
             if (parseErrorReasons.length > 0) {
                 return { ok: false, reason: `the document does not parse cleanly: ${parseErrorReasons.join("; ")}` };
             }

package/dist/html/regions.d.ts

@@ -1,56 +1,3 @@
-/**
- * @module html/regions
- *
- * An `EditTarget` whose parts are **tagged regions of one HTML document** — the shape a
- * single-document host needs, as opposed to the file tree a multi-file host edits.
- *
- * This is the target the port was designed against but never had an implementation for, and it is
- * where `validate` stops being a formality: a file cannot corrupt another file's syntax, but a
- * region shares one document with every other region, so one unbalanced tag corrupts everything
- * after it.
- *
- * ## Addressing reuses `data-agent-element`, deliberately
- *
- * Handles are the existing `data-agent-element` convention (`@jini-ai/agentic`'s
- * `element-handles.ts`), including its handle grammar — lowercase words joined by single hyphens,
- * bounded length, and no quote, bracket, backslash or whitespace. That grammar exists so a handle
- * cannot break out of the attribute selector it gets interpolated into, and it serves equally well
- * here: a `PartId` a model can name is a string a model authored.
- *
- * Minting a new product-specific attribute was considered and rejected twice over — the convention
- * already exists with `region` as a defined role, and a product-named attribute could not live in
- * this workspace anyway.
- *
- * ## THE SECURITY PROPERTY: a model may not extend its own allowlist
- *
- * `listParts` is an allowlist, and an allowlist a model can write to is not an allowlist. If a model
- * may edit region `hero`, and it writes `data-agent-element="anything"` inside `hero`, then the very
- * next `listParts()` publishes `anything` as addressable — the model has granted itself a new part
- * without the host ever deciding to. Every subsequent turn inherits the expanded surface.
- *
- * So `validate` refuses any candidate whose prospective document does not carry **exactly the same
- * multiset of handles** as the current one. That covers all three ways this breaks: a handle
- * invented, a handle deleted, and a handle duplicated (which would make an id ambiguous and let one
- * write land somewhere the host did not intend). Neither reference implementation has an equivalent
- * check, because neither has sub-document parts — there was nothing to copy.
- *
- * ## Writes are byte-preserving outside the edited region
- *
- * `replacePart` is a string splice across the region's inner offsets: everything outside those
- * offsets is carried through untouched, byte for byte. This is a deliberate departure from the
- * visual editor studied for this design, which re-parses, regenerates and pretty-prints the whole
- * file on every write — semantically faithful, but it reformats the document out from under the
- * author, and it does so even to files it failed to parse. A host that stores author-written HTML
- * cannot accept that.
- *
- * ## The parser is injected, not imported
- *
- * This package is `"runtime": "universal"`, and no HTML parser exists anywhere in this workspace, so
- * hard-wiring one would either make this module Node-only or push a parser into every browser
- * bundle. It arrives as a port instead — the same choice, for the same reason, that `EditTarget`
- * itself is a port. A browser host can satisfy it with `DOMParser`; a server host with whatever it
- * already depends on.
- */
 import type { EditTarget } from "../core/target.js";
 /** The attribute that publishes a region's handle. Mirrors `@jini-ai/agentic`'s convention. */
 export declare const AGENT_ELEMENT_ATTRIBUTE = "data-agent-element";

package/dist/html/regions.js

@@ -1,3 +1,57 @@
+/**
+ * @module html/regions
+ *
+ * An `EditTarget` whose parts are **tagged regions of one HTML document** — the shape a
+ * single-document host needs, as opposed to the file tree a multi-file host edits.
+ *
+ * This is the target the port was designed against but never had an implementation for, and it is
+ * where `validate` stops being a formality: a file cannot corrupt another file's syntax, but a
+ * region shares one document with every other region, so one unbalanced tag corrupts everything
+ * after it.
+ *
+ * ## Addressing reuses `data-agent-element`, deliberately
+ *
+ * Handles are the existing `data-agent-element` convention (`@jini-ai/agentic`'s
+ * `element-handles.ts`), including its handle grammar — lowercase words joined by single hyphens,
+ * bounded length, and no quote, bracket, backslash or whitespace. That grammar exists so a handle
+ * cannot break out of the attribute selector it gets interpolated into, and it serves equally well
+ * here: a `PartId` a model can name is a string a model authored.
+ *
+ * Minting a new product-specific attribute was considered and rejected twice over — the convention
+ * already exists with `region` as a defined role, and a product-named attribute could not live in
+ * this workspace anyway.
+ *
+ * ## THE SECURITY PROPERTY: a model may not extend its own allowlist
+ *
+ * `listParts` is an allowlist, and an allowlist a model can write to is not an allowlist. If a model
+ * may edit region `hero`, and it writes `data-agent-element="anything"` inside `hero`, then the very
+ * next `listParts()` publishes `anything` as addressable — the model has granted itself a new part
+ * without the host ever deciding to. Every subsequent turn inherits the expanded surface.
+ *
+ * So `validate` refuses any candidate whose prospective document does not carry **exactly the same
+ * multiset of handles** as the current one. That covers all three ways this breaks: a handle
+ * invented, a handle deleted, and a handle duplicated (which would make an id ambiguous and let one
+ * write land somewhere the host did not intend). Neither reference implementation has an equivalent
+ * check, because neither has sub-document parts — there was nothing to copy.
+ *
+ * ## Writes are byte-preserving outside the edited region
+ *
+ * `replacePart` is a string splice across the region's inner offsets: everything outside those
+ * offsets is carried through untouched, byte for byte. This is a deliberate departure from the
+ * visual editor studied for this design, which re-parses, regenerates and pretty-prints the whole
+ * file on every write — semantically faithful, but it reformats the document out from under the
+ * author, and it does so even to files it failed to parse. A host that stores author-written HTML
+ * cannot accept that.
+ *
+ * ## The parser is injected, not imported
+ *
+ * This package is `"runtime": "universal"`, and no HTML parser exists anywhere in this workspace, so
+ * hard-wiring one would either make this module Node-only or push a parser into every browser
+ * bundle. It arrives as a port instead — the same choice, for the same reason, that `EditTarget`
+ * itself is a port. A browser host can satisfy it with `DOMParser`; a server host with whatever it
+ * already depends on.
+ */
+import { replaceRegionInner } from "./edit.js";
 /** The attribute that publishes a region's handle. Mirrors `@jini-ai/agentic`'s convention. */
 export const AGENT_ELEMENT_ATTRIBUTE = "data-agent-element";
 /**
@@ -53,7 +107,7 @@ export function createHtmlRegionTarget(deps, options = {}) {
     const maxPartLength = options.maxPartLength ?? 256 * 1024;
     /** Splices `content` into `region`'s inner range, preserving every byte outside it. */
     function spliced(html, region, content) {
-        return html.slice(0, region.innerStart) + content + html.slice(region.innerEnd);
+        return replaceRegionInner({ html, region, fragment: content });
     }
     return {
         async listParts() {

package/dist/node/index.d.ts

@@ -0,0 +1,6 @@
+/** Node-only local project adapter; universal contracts live in ../core/project. */
+export { openFileTreeProject } from './project.js';
+export type { OpenFileTreeProjectInput, OpenFileTreeProjectOptions } from './project.js';
+export type { FileTreePolicy } from './paths.js';
+export * from '../core/project.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.js

@@ -0,0 +1,4 @@
+/** Node-only local project adapter; universal contracts live in ../core/project. */
+export { openFileTreeProject } from './project.js';
+export * from '../core/project.js';
+//# sourceMappingURL=index.js.map

package/dist/node/paths.d.ts

@@ -0,0 +1,50 @@
+import { type ProjectLimits } from '../core/project.js';
+export interface FileTreePolicy {
+    /** Host authority intersects mandatory exclusions, including for external captures. */
+    allows(input: {
+        readonly relativePath: string;
+    }): boolean;
+}
+export declare const DEFAULT_PROJECT_LIMITS: ProjectLimits;
+/** Portable comparison also catches APFS case folding aliases such as the Kelvin sign. */
+export declare function portablePathKey({ path }: {
+    path: string;
+}, _options?: {}): string;
+/** Resolve positive integer bounds once; no silent clamping or partial tree captures.
+ * @complexity O(number of limits) time and space.
+ */
+export declare function projectLimits(input: {
+    limits?: Partial<ProjectLimits>;
+}, _options?: {}): ProjectLimits;
+/** Names must already be canonical: never normalize a traversal into an authorized filename.
+ * @throws ProjectError INVALID_PATH for nonportable or noncanonical names.
+ * @complexity O(path length) time and space; relative names are capped at 200 code units.
+ */
+export declare function canonicalPath({ relativePath, maxDepth }: {
+    relativePath: string;
+    maxDepth: number;
+}, _options?: {}): string;
+/** Validate all candidate file AND directory spellings; a delete/create case-only rename passes.
+ * @complexity O(total prefix lengths) time and space; no pairwise path comparisons.
+ */
+export declare function assertCandidatePaths({ paths }: {
+    paths: readonly string[];
+}, _options?: {}): void;
+/** Platform owns physical containment and bounded traversal; this adapter adds project policy.
+ * @complexity Construction O(1); path checks O(depth), listing bounded by configured limits.
+ */
+export declare function createProjectPaths({ root, policy, limits }: {
+    root: string;
+    policy: FileTreePolicy;
+    limits: ProjectLimits;
+}, _options?: {}): {
+    reader: import("@jini-ai/platform/fs").GuardedFileReader;
+    check: ({ relativePath }: {
+        relativePath: string;
+    }) => string;
+    allows: ({ relativePath }: {
+        relativePath: string;
+    }) => boolean;
+};
+export type ProjectPaths = ReturnType<typeof createProjectPaths>;
+//# sourceMappingURL=paths.d.ts.map

package/dist/node/paths.js

@@ -0,0 +1,91 @@
+import { createGuardedFileReader, createNodeGuardedReaderFilesystem } from '@jini-ai/platform/fs';
+import { ProjectError } from '../core/project.js';
+export const DEFAULT_PROJECT_LIMITS = {
+    maxFiles: 2_000, maxFileBytes: 2 * 1024 * 1024, maxTreeBytes: 64 * 1024 * 1024,
+    maxDepth: 32, maxChanges: 100, validationTimeoutMs: 30_000,
+};
+const EXCLUDED = new Set(['node_modules', '.git', 'dist', 'build', 'out', 'coverage',
+    '.next', '.nuxt', '.angular', '.vite', '.cache', '.turbo']);
+const DEVICE = /^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i;
+// Platform's atomic writer stages `.<name>.<pid>.<uuid>.tmp` beside the destination. A crash
+// mid-materialize leaves one in the app root; never capture that debris as a managed file.
+const ATOMIC_TEMP = /^\..+\.\d+\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/i;
+/** Portable comparison also catches APFS case folding aliases such as the Kelvin sign. */
+export function portablePathKey({ path }, _options = {}) {
+    return path.normalize('NFC').toLowerCase().toUpperCase().toLowerCase();
+}
+/** Resolve positive integer bounds once; no silent clamping or partial tree captures.
+ * @complexity O(number of limits) time and space.
+ */
+export function projectLimits(input, _options = {}) {
+    const limits = { ...DEFAULT_PROJECT_LIMITS, ...input.limits };
+    for (const value of Object.values(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new TypeError('project limits must be positive safe integers');
+    }
+    return limits;
+}
+/** Names must already be canonical: never normalize a traversal into an authorized filename.
+ * @throws ProjectError INVALID_PATH for nonportable or noncanonical names.
+ * @complexity O(path length) time and space; relative names are capped at 200 code units.
+ */
+export function canonicalPath({ relativePath, maxDepth }, _options = {}) {
+    if (!relativePath || relativePath.length > 200 || relativePath.includes('\\')) {
+        throw new ProjectError({ code: 'INVALID_PATH', message: 'use a relative slash-separated path of at most 200 characters' });
+    }
+    const segments = relativePath.split('/');
+    if (segments.length > maxDepth)
+        throw new ProjectError({ code: 'LIMIT', message: 'path exceeds depth limit' });
+    for (const segment of segments)
+        assertSegment({ segment });
+    return relativePath;
+}
+/** Each segment must survive Windows parsing without aliases, streams or device semantics. */
+function assertSegment({ segment }) {
+    if (!segment || segment === '.' || segment === '..' || /[<>:"|?*\x00-\x1f\x7f]/.test(segment) || /[. ]$/.test(segment) || DEVICE.test(segment)) {
+        throw new ProjectError({ code: 'INVALID_PATH', message: `nonportable path segment: ${segment}` });
+    }
+}
+/** Validate all candidate file AND directory spellings; a delete/create case-only rename passes.
+ * @complexity O(total prefix lengths) time and space; no pairwise path comparisons.
+ */
+export function assertCandidatePaths({ paths }, _options = {}) {
+    const spellings = new Map();
+    const files = new Set(paths.map(path => portablePathKey({ path })));
+    for (const path of paths) {
+        const segments = path.split('/');
+        for (let end = 1; end <= segments.length; end += 1) {
+            const prefix = segments.slice(0, end).join('/');
+            const key = portablePathKey({ path: prefix });
+            const prior = spellings.get(key);
+            if ((prior !== undefined && prior !== prefix) || (end < segments.length && files.has(key))) {
+                throw new ProjectError({ code: 'INVALID_PATH', message: `candidate path collision: ${prefix}` });
+            }
+            spellings.set(key, prefix);
+        }
+    }
+}
+/** Platform owns physical containment and bounded traversal; this adapter adds project policy.
+ * @complexity Construction O(1); path checks O(depth), listing bounded by configured limits.
+ */
+export function createProjectPaths({ root, policy, limits }, _options = {}) {
+    const reader = createGuardedFileReader({ rootPath: root, filesystem: createNodeGuardedReaderFilesystem({}),
+        denyRules: { segments: EXCLUDED, filenamePatterns: [/^\.env/i, ATOMIC_TEMP] },
+        limits: { maxFileBytes: limits.maxFileBytes, binarySniffBytes: 1024,
+            maxListedFiles: limits.maxFiles + 1, maxWalkDepth: limits.maxDepth, maxWalkEntries: limits.maxFiles * (limits.maxDepth + 1) },
+    }, { excludedListingDirs: EXCLUDED });
+    function check({ relativePath }) {
+        const canonical = canonicalPath({ relativePath, maxDepth: limits.maxDepth });
+        for (const segment of canonical.split('/')) {
+            if (reader.isDeniedPathSegment({ segmentName: segment }) || reader.isDeniedFileName({ fileName: segment })) {
+                throw new ProjectError({ code: 'INVALID_PATH', message: `excluded path: ${relativePath}` });
+            }
+        }
+        if (!policy.allows({ relativePath: canonical }))
+            throw new ProjectError({ code: 'INVALID_PATH', message: `host policy refuses ${canonical}` });
+        return canonical;
+    }
+    return { reader, check, allows: ({ relativePath }) => relativePath.split('/').every(segment => !reader.isDeniedPathSegment({ segmentName: segment }) && !reader.isDeniedFileName({ fileName: segment }))
+            && policy.allows({ relativePath }) };
+}
+//# sourceMappingURL=paths.js.map

package/dist/node/project.d.ts

@@ -0,0 +1,19 @@
+import { type FileTreeProject, type ProjectLimits, type ProjectValidator } from '../core/project.js';
+import { type FileTreePolicy } from './paths.js';
+export interface OpenFileTreeProjectInput {
+    readonly root: string;
+    /** Private host-owned directory outside the watched and served application tree. */
+    readonly stateDir: string;
+    readonly policy: FileTreePolicy;
+    readonly validator?: ProjectValidator;
+}
+export interface OpenFileTreeProjectOptions {
+    readonly limits?: Partial<ProjectLimits>;
+    readonly historyLimit?: number;
+}
+/** Open real local files with process-crash roll-forward and session-local pointer history.
+ * @throws ProjectError for conflicts, unsafe paths, corruption, limits or I/O failure.
+ * @complexity O(files + bytes) opening/capture; each turn is bounded by configured tree limits.
+ */
+export declare function openFileTreeProject(input: OpenFileTreeProjectInput, options?: OpenFileTreeProjectOptions): Promise<FileTreeProject>;
+//# sourceMappingURL=project.d.ts.map