@sema-agent/core 7.55.0 → 7.56.0

package/dist/tools/fs/shell-read-argv.js

@@ -21,9 +21,46 @@ function mayOwnNextWord(row, tok) {
             return k === tok.length;
     return false;
 }
+class OperandBase {
+    base;
+    taken = [];
+    move(spec, value, settled, at) {
+        if (spec?.rebases !== true)
+            return;
+        if (!settled)
+            this.base = "unsettled";
+        else if (namesOwnPlace(value))
+            this.base = value;
+        else if (this.base !== "unsettled")
+            this.base = this.base === undefined ? value : joinSpelling(this.base, value);
+        if (typeof this.base === "string" && this.base !== "unsettled")
+            this.taken.push({ at, base: this.base });
+    }
+    of(r) {
+        if (this.base === undefined || namesOwnPlace(r.folded))
+            return r;
+        if (this.base === "unsettled" || r.expands !== false)
+            return { ...r, expands: "unresolvable" };
+        return { word: r.word, raw: r.raw, folded: joinSpelling(this.base, r.folded), expands: false };
+    }
+    covers(unsettled) {
+        const out = new Set();
+        for (const u of unsettled) {
+            if (namesOwnPlace(u.folded) || u.folded.split("/").includes(".."))
+                continue;
+            for (const t of this.taken)
+                if (t.at < u.at)
+                    out.add(t.base);
+        }
+        return [...out].map((b) => readOfText(b));
+    }
+}
+const namesOwnPlace = (spelled) => spelled.startsWith("/") || spelled.startsWith("~");
+const joinSpelling = (base, rel) => (base.endsWith("/") ? `${base}${rel}` : `${base}/${rel}`);
 const rootValue = (spec) => spec?.walks === true || spec?.delivers === "operands";
 class RootsGathered {
     positional = [];
+    opened = new Map();
     places = [];
     maybeValues = new Set();
     stdinOperands = 0;
@@ -50,16 +87,23 @@ class RootsGathered {
         if (this.maybeValues.has(r))
             this.slotOwned = true;
     }
-    operand(r, namesPath, stdin) {
+    operand(r, namesPath, stdin, opened = r) {
         if (stdin) {
             if (!this.maybeValues.has(r))
                 this.stdinOperands++;
         }
-        else if (namesPath)
+        else if (namesPath) {
             this.positional.push(r);
+            if (opened !== r)
+                this.opened.set(r, opened);
+        }
+    }
+    cover(place) {
+        this.places.push(bare(place, "traversal_root"));
     }
     restart() {
         this.positional.length = 0;
+        this.opened.clear();
         this.places.length = 0;
         this.stdinOperands = 0;
         this.slotOwned = false;
@@ -71,7 +115,7 @@ class RootsGathered {
         const reads = this.unsettled
             ? [...this.positional, ...(this.slotWord !== undefined ? [this.slotWord] : []), ...(walksCwdWithoutOperand(row) ? [readOfText(".")] : [])]
             : walksCwdWithoutOperand(row) && leftOver <= (this.slotOwned ? 1 : 0) ? [...this.positional, readOfText(".")] : [...this.positional];
-        return [...reads.map((r) => bare(r, "traversal_root")), ...this.places];
+        return [...reads.map((r) => bare(this.opened.get(r) ?? r, "traversal_root")), ...this.places];
     }
 }
 export const programTextSentence = (language) => `runs inline ${language} program text, which may open files this station does not read`;
@@ -178,6 +222,9 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
             pushAssignment(reads, toks[j].word, provenance);
     }
     const gathered = new RootsGathered();
+    let base = new OperandBase();
+    const valueAt = new Set();
+    const unsettledAt = [];
     let slotWord;
     const pastOperand = new Set();
     let globs = "expanded";
@@ -251,6 +298,8 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
             walkFrom = argvStart + 2 + sub.at;
             relocated = sub.relocated;
             gathered.restart();
+            base = new OperandBase();
+            unsettledAt.length = 0;
             walk(sub.row, walkFrom, toks.length, true);
         }
         else
@@ -268,10 +317,12 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
                 return;
             case "dash-word-operand":
                 pastOperand.add(j);
-                reads.push(bare(r, provenance));
+                reads.push(bare(base.of(r), provenance));
                 speculate(start, "whole");
                 return;
             case "value": {
+                base.move(e.spec, r.folded, e.consumed && r.expands === false, j);
+                valueAt.add(j);
                 if (!e.consumed) {
                     gathered.value(r, e, false);
                     if (r.expands !== "unresolvable")
@@ -299,19 +350,23 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
                     return;
                 }
                 {
+                    base.move(e.reading.spec, literalTildeSpelling(e.reading.attached), r.expands === false, j);
                     const named = roleReads(r, "option_value", literalTildeSpelling(e.reading.attached), e.reading.role, globs, ctx, pastOperand.has(j));
                     reads.push(...named);
                     gathered.attached(named, e.reading.spec);
                 }
                 return;
             case "operand": {
-                const role = e.dash === undefined ? (e.slot ?? e.role) : undefined;
-                const named = role !== undefined ? roleReads(r, provenance, r.folded, role, globs, ctx) : [bare(r, provenance)];
                 const inSlot = j === slotWord;
+                const o = inSlot || e.dash !== undefined ? r : base.of(r);
+                const role = e.dash === undefined ? (e.slot ?? e.role) : undefined;
+                const named = role !== undefined ? roleReads(o, provenance, o.folded, role, globs, ctx) : [bare(o, provenance)];
                 if (inSlot)
                     gathered.slot(r);
                 else
-                    gathered.operand(r, named.some((c) => c.denyOnly !== true), e.dash === "stdin");
+                    gathered.operand(r, named.some((c) => c.denyOnly !== true), e.dash === "stdin", o);
+                if (!inSlot && e.dash === undefined && r.expands !== false)
+                    unsettledAt.push({ at: j, folded: r.folded });
                 reads.push(...named);
                 speculate(start, r.word.assignment !== undefined ? "whole" : "containment");
                 const values = reads.length;
@@ -323,6 +378,11 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
         }
     }
     if (walkRow !== undefined && argv !== undefined && selectsContentsTraversal(walkRow, toks.slice(walkFrom).map((x) => x.folded))) {
+        for (const j of expanding)
+            if (j >= walkFrom && !valueAt.has(j))
+                unsettledAt.push({ at: j, folded: toks[j].folded });
+        for (const place of base.covers(unsettledAt))
+            gathered.cover(place);
         for (const root of gathered.roots(walkRow))
             reads.push(relocated ? { ...root, expands: "unresolvable" } : root);
     }
@@ -372,6 +432,9 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
     const slice = argReads.slice(first, last);
     const args = slice.map((r) => r.folded);
     const gathered = new RootsGathered();
+    const base = new OperandBase();
+    const valueAt = new Set();
+    const unsettledAt = [];
     let unexplained = false;
     const globs = valuesAreLiteral(row, args) ? "literal" : "expanded";
     noteDeliveredOperands(row, args, ctx);
@@ -391,9 +454,11 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                 break;
             case "dash-word-operand":
                 pastOperand.add(e.at);
-                reads.push(bare(slice[e.at], "operand"));
+                reads.push(bare(base.of(slice[e.at]), "operand"));
                 break;
             case "value": {
+                base.move(e.spec, t, e.consumed && slice[e.at].expands === false, e.at);
+                valueAt.add(e.at);
                 if (expanding.has(first + e.at))
                     break;
                 gathered.value(slice[e.at], e, opensPath(offer(e.at, t, e.role, "option_value", !e.consumed)));
@@ -409,6 +474,7 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                         reads.push(bare(slice[e.at], "option_value", payload));
                     break;
                 }
+                base.move(e.reading.spec, literalTildeSpelling(e.reading.attached), slice[e.at].expands === false, e.at);
                 gathered.attached(offer(e.at, literalTildeSpelling(e.reading.attached), e.reading.role, "option_value", pastOperand.has(e.at)), e.reading.spec);
                 break;
             case "operand": {
@@ -428,11 +494,17 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                     break;
                 }
                 let opens = true;
-                if (e.role !== undefined)
-                    opens = opensPath(offer(e.at, t, e.role, "operand"));
+                const o = base.of(slice[e.at]);
+                if (e.role !== undefined) {
+                    const named = roleReads(o, "operand", o.folded, e.role, globs, ctx);
+                    reads.push(...named);
+                    opens = opensPath(named);
+                }
                 else
-                    reads.push(bare(slice[e.at], "operand"));
-                gathered.operand(slice[e.at], opens, false);
+                    reads.push(bare(o, "operand"));
+                gathered.operand(slice[e.at], opens, false, o);
+                if (slice[e.at].expands !== false)
+                    unsettledAt.push({ at: e.at, folded: t });
                 if (row?.operands?.assignmentArguments !== "not-paths")
                     pushAssignment(reads, slice[e.at].word, "operand");
                 break;
@@ -444,6 +516,11 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                     reads[i] = { ...reads[i], speculative: "containment" };
     }
     if (row !== undefined && selectsContentsTraversal(row, args)) {
+        for (let k = 0; k < slice.length; k++)
+            if (expanding.has(first + k) && !valueAt.has(k))
+                unsettledAt.push({ at: k, folded: args[k] });
+        for (const place of base.covers(unsettledAt))
+            gathered.cover(place);
         for (const root of gathered.roots(row))
             reads.push(relocated ? { ...root, expands: "unresolvable" } : root);
     }

package/dist/tools/fs/shell-read-bindings.d.ts

@@ -106,6 +106,37 @@ export declare const functionKey: (name: string) => string;
 /** What a function name is at a reader: `defined` — it certainly is one; `absent` — it certainly is not; `maybe` — a branch,
  *  a loop, a body that may not have run, a removal that may not have found it. */
 export type FunctionState = "defined" | "maybe" | "absent";
+/** The function names a segment exports to child shells — the `-f` function flag with export (`export` always exports;
+ *  `declare` / `typeset` need `-x`), its bare-name operands. A child `bash -c` inherits them as functions
+ *  ({@link inheritedExportedFunctions}); their definitions are text this reader does not hold, so a call to one shadows
+ *  the builtin of the name (#1628). */
+export declare function exportedFunctionNames(argv: readonly LexedWord[]): string[];
+/** A function the CHILD inherits through its ENVIRONMENT: bash exports a function as a `BASH_FUNC_<name>%%` variable
+ *  (older bashes `BASH_FUNC_<name>()`), and a child reading that variable from its environment defines `<name>` as a
+ *  function whose body the engine cannot read. Delivered on a child's env by `env BASH_FUNC_x%%=… cmd` (env's own
+ *  assignment grammar accepts the `%%` name the shell's does not). Each such assignment word of a segment names an
+ *  inherited function — the same law as {@link exportedFunctionNames}, a different delivery; a value the shell rewrites
+ *  (`env "BASH_FUNC_$n%%=…"`) names a function the text cannot settle and is not tracked (KL-1628-a). */
+export declare function envFunctionNames(argv: readonly LexedWord[]): string[];
+/** Whether the BODY of a function a child shell inherits is text the engine read: `read` — the text (or a shell above it)
+ *  defines the function it exports (`f(){ …; }; export -f f`, `declare -fx f`), so the body's segments are read where it
+ *  is defined; `unread` — delivered on an environment (`BASH_FUNC_f%%=…`, {@link envFunctionNames}), or exported with no
+ *  definition the text holds (one a `source` or an `eval` made): a body nobody read. */
+export type InheritedBody = "read" | "unread";
+/** The functions a text's child shells inherit, each with its {@link InheritedBody}: what the shell running the text
+ *  inherited; then each name the text exports — `read` where the text defines it, else what it was inherited as, else
+ *  `unread`; then each name it delivers on an environment, `unread` whatever else holds it. */
+export declare function inheritedFunctionsOf(segments: readonly {
+    readonly argv: readonly LexedWord[];
+    readonly defines: readonly string[];
+}[], inherited: ReadonlyMap<string, InheritedBody> | undefined): ReadonlyMap<string, InheritedBody>;
+/** What a child shell (`bash -c`) inherits from a parent that EXPORTED functions ({@link exportedFunctionNames}): each
+ *  such name is a `defined` function in the child — bash looks a function up before the builtin of its name, so
+ *  `declare X=…` run under an exported `declare` function is the FUNCTION (it binds nothing), not the declaration
+ *  builtin. Every other function key is `absent` (a child inherits only exported functions), every builtin enabled;
+ *  the child holds none of their bodies, so a call to one may change any name (`bound: "all"`). The existing binding
+ *  carrier ({@link PlanStart.names}), not a second table (#1628). */
+export declare function inheritedExportedFunctions(names: ReadonlyMap<string, InheritedBody>): InheritedFunctions;
 /** One binding a segment makes: a name and what it now holds (`unknown` = made unknown). `prefix`: a binding that may or
  *  may not take effect (a prefix assignment to a special builtin, which may or may not outlive its command; an `unset` of a
  *  function, which a read-only function refuses). `loopVar`: a `for` loop's variable, held through its body. */

package/dist/tools/fs/shell-read-bindings.js

@@ -46,6 +46,47 @@ const isFunctionKey = (name) => name.startsWith(FUNCTION_KEY_PREFIX);
 const FUNCTION_DEFINED = [{ spelled: "defined" }];
 const FUNCTION_ABSENT = [{ spelled: "absent" }];
 const isDefinedValue = (v) => v.spelled === "defined";
+const EXPORT_FUNCTION_BUILTINS = new Set(["export", "declare", "typeset"]);
+export function exportedFunctionNames(argv) {
+    const program = readProgramPosition(argv).program;
+    const prog = program?.basename;
+    if (program === undefined || prog === undefined || !EXPORT_FUNCTION_BUILTINS.has(prog))
+        return [];
+    const literal = (w) => w.expansions.length === 0;
+    const rest = argv.slice(program.index + 1);
+    const flags = new Set(rest.filter((w) => literal(w) && /^-[A-Za-z]+$/.test(w.folded)).flatMap((w) => [...w.folded.slice(1)]));
+    if (!flags.has("f") || !(prog === "export" || flags.has("x")))
+        return [];
+    return rest.filter((w) => literal(w) && w.assignment === undefined && /^[A-Za-z_][A-Za-z0-9_]*$/.test(w.folded)).map((w) => w.folded);
+}
+export function envFunctionNames(argv) {
+    const out = [];
+    for (const w of argv) {
+        if (w.expansions.length !== 0)
+            continue;
+        const m = /^BASH_FUNC_([A-Za-z_][A-Za-z0-9_]*)(?:%%|\(\))=/.exec(w.folded);
+        if (m !== null)
+            out.push(m[1]);
+    }
+    return out;
+}
+export function inheritedFunctionsOf(segments, inherited) {
+    const defined = new Set(segments.flatMap((s) => s.defines));
+    const out = new Map(inherited ?? []);
+    for (const s of segments)
+        for (const name of exportedFunctionNames(s.argv))
+            out.set(name, defined.has(name) ? "read" : out.get(name) ?? "unread");
+    for (const s of segments)
+        for (const name of envFunctionNames(s.argv))
+            out.set(name, "unread");
+    return out;
+}
+export function inheritedExportedFunctions(names) {
+    return {
+        start: (key) => (isFunctionKey(key) ? (names.has(key.slice(FUNCTION_KEY_PREFIX.length)) ? FUNCTION_DEFINED : FUNCTION_ABSENT) : BUILTIN_ENABLED),
+        bound: "all",
+    };
+}
 const ATTRIBUTE_KINDS = { integer: "integer", transformed: "transformed", frozen: "frozen" };
 const EVERY_ATTRIBUTE = Object.values(ATTRIBUTE_KINDS).map((kind) => ({ kind }));
 export function projectSegment(segment) {

package/dist/tools/fs/shell-read-check.js

@@ -3,7 +3,7 @@ import { errorResult } from "../../core/tools.js";
 import { BASH_READONLY_CONFINEMENT_NOTE } from "./fs-shared.js";
 import { isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf, violationDetails, withinAnyRoot } from "./safety.js";
 import { checkedReadDenyHomes, fitMiddle, READ_DENY_SENTENCE_PART_MAX, readDenySentence } from "./read-deny.js";
-import { NOT_AUTO_ALLOWED, programPositionRefusalSentence, readProgramPosition } from "./bash-program-position.js";
+import { NOT_AUTO_ALLOWED, declinedProgramSentence } from "./bash-program-position.js";
 import { bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { planShellReads } from "./shell-read-plan.js";
 import { createShellReadEstablisher, establishShellReadsLexically } from "./shell-read-establish.js";
@@ -12,10 +12,10 @@ import { anyOptionWord, programArgs } from "./shell-read-write-targets.js";
 import { shellReadFaceWords } from "./shell-read-face.js";
 import { passesUnasked } from "./shell-read-device.js";
 import { programRow, selectedOptions } from "./program-read-model.js";
+import { refusedByRemoval, SHELL_REMOVAL_COMMANDS } from "./removal-targets.js";
 import { allFindings, anyFaceGuards, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, stationGuards, writeFaceGuards, } from "./shell-read-judge.js";
 import { seatOf } from "../../core/tool-name-readings.js";
 import { normalizeReadRootCandidate } from "../../core/read-root-candidate.js";
-import { argvOf, lexShellText } from "../../shell/lex.js";
 import { assertNoRetiredShellReadBoundaryKeys } from "../../core/retired-keys.js";
 function containmentDetails(paths) {
     return { type: "readonly_out_of_root", code: "readonly_out_of_root", paths };
@@ -26,7 +26,6 @@ function unestablishedDetails() {
 function findingDetails(finding, paths) {
     return finding === "unestablishable" || finding === "declined" || finding === "unanswered" ? unestablishedDetails() : containmentDetails(paths);
 }
-const REMOVAL_COMMANDS = new Set(["rm", "rmdir"]);
 const WRITES_BENEATH = {
     cp: () => true,
     mv: () => true,
@@ -74,15 +73,16 @@ function writesPlacedOf(judged, boundary) {
         if (UNPLACED_OPTIONS[verb]?.(programArgs(s.segment).map((w) => w.spelled)) === true)
             return false;
         const beneath = WRITES_BENEATH[verb]?.(s.segment) === true;
+        const removal = SHELL_REMOVAL_COMMANDS.includes(verb);
         for (const f of s.findings) {
             if (f.read.candidate.face !== "write")
                 continue;
             const target = f.read.target;
             if (f.read.established === "unestablishable" || target === undefined || isPattern(f) || f.kind !== "none" || (f.containment !== "inside" && f.containment !== "open"))
                 return false;
-            if (beneath && denyRowAtOrBelow(f.read, boundary, !REMOVAL_COMMANDS.has(verb)))
+            if (beneath && denyRowAtOrBelow(f.read, boundary, !removal))
                 return false;
-            if (REMOVAL_COMMANDS.has(verb) && writeRoots.some((root) => withinAnyRoot([target], root)))
+            if (removal && !refusedByRemoval(f.read) && writeRoots.some((root) => withinAnyRoot([target], root)))
                 return false;
         }
         return true;
@@ -182,19 +182,6 @@ function shellCommandOf(args) {
     const command = args?.command;
     return typeof command === "string" ? command : undefined;
 }
-function declineSentence(segment) {
-    const lexed = lexShellText(segment.text);
-    if (!("reject" in lexed) && lexed.segments[0] !== undefined) {
-        const pos = readProgramPosition(argvOf(lexed.segments[0]));
-        if (pos.refusal !== undefined)
-            return programPositionRefusalSentence(pos.refusal);
-        if (pos.argvFromStdin) {
-            const runs = pos.program?.basename ?? "the program it runs";
-            return `"${segment.text.trim()}" hands ${runs} its operands on its standard input, which this station does not read ${NOT_AUTO_ALLOWED}`;
-        }
-    }
-    return `"${segment.text.trim()}" runs a program this station cannot name ${NOT_AUTO_ALLOWED}`;
-}
 const ACCOUNT_PART_MAX = READ_DENY_SENTENCE_PART_MAX;
 const CAUSE_SPELLING_MAX = 64;
 function fitCause(cause) {
@@ -236,7 +223,7 @@ function findingAccount(fold, boundary) {
                 return `the text given to ${reenteredPrograms(fold)} — as an argument, on standard input, or in the file it names — runs as shell text this station does not parse ${NOT_AUTO_ALLOWED}`;
             return `the command's text could not be read as shell, so where it ${verb} cannot be established ${NOT_AUTO_ALLOWED}`;
         case "declined":
-            return fold.declined !== undefined ? declineSentence(fold.declined) : `the station could not read which program runs ${NOT_AUTO_ALLOWED}`;
+            return fold.declined !== undefined ? declinedProgramSentence(fold.declined.text) : `the station could not read which program runs ${NOT_AUTO_ALLOWED}`;
         case "identity_changed":
             return `"${fitMiddle(w?.read.candidate.raw ?? "?", ACCOUNT_PART_MAX)}" resolves to "${fitMiddle(w?.read.target ?? "?", ACCOUNT_PART_MAX)}" now, not where it resolved when this call was judged`;
         case "deny_hit":

package/dist/tools/fs/shell-read-environment.d.ts

@@ -9,7 +9,8 @@
  * establisher and the write guards are handed an {@link ObservedFilesystem}, never the environment, so a lookup they make
  * cannot escape the record.
  *
- * What is NOT a failure: a conclusive absence (`not_found`, `not_directory` — the answer is "nothing there") and an adapter
+ * What is NOT a failure: a conclusive absence (`not_found`, `not_directory`, `name_too_long` — the answer is "nothing there", or
+ * "nothing can be there": the program that opens such a name fails the same way) and an adapter
  * that has no filesystem surface (`not_supported` — its answer that there is no file face: a chain it answers so keeps the
  * lexical reading). Everything else is, and is recorded wherever it falls — a resolver that answered nothing at all in the
  * command included: a lookup that failed (`permission_denied`, `timeout`, `unknown`, a throw) is a resolver failing, whose
@@ -47,6 +48,9 @@ export interface ObservedEnvironment {
     /** Records that came from outside the door: the declared roots' own lookup and the home views a read could not be placed against. */
     adopt(records: readonly Incomplete[]): void;
 }
+/** The answers that say NOTHING IS THERE — no entry (`not_found`), nothing reachable under a non-directory (`not_directory`), a
+ *  name the filesystem cannot hold (`name_too_long`): the station's one reading of an absence, wherever a lookup is read. */
+export declare const isAbsence: (code: string) => boolean;
 /** The declared roots, canonicalized ONCE per establisher (through the same door), with what that lookup could not finish —
  *  merged into every establishment. `known`: the caller already holds them as canonical identities and they are used verbatim
  *  (re-resolving one that was since swapped for a link would substitute the link's target for the root that was approved). */

package/dist/tools/fs/shell-read-environment.js

@@ -1,6 +1,7 @@
 import { canonicalPathIsAuthoritative } from "../../core/remote-env.js";
 const OBSERVED = Symbol("observedFilesystem");
-const CONCLUSIVE = new Set(["not_found", "not_directory", "not_supported"]);
+export const isAbsence = (code) => code === "not_found" || code === "not_directory" || code === "name_too_long";
+const conclusive = (code) => isAbsence(code) || code === "not_supported";
 export function canonicalRootsOnce(env, readRoots, known) {
     let once = known ? Promise.resolve({ roots: readRoots, incomplete: [] }) : undefined;
     return (signal) => (once ??= (async () => {
@@ -21,7 +22,7 @@ export function observeEnvironment(env) {
     const records = [];
     const note = (op, path, what, code) => void records.push({ op, detail: `"${path}" ${what} (${code})` });
     const watch = (op, path, what, ask) => new Promise((resolve) => resolve(ask())).then((r) => {
-        if (!r.ok && !CONCLUSIVE.has(r.error.code))
+        if (!r.ok && !conclusive(r.error.code))
             note(op, path, what, r.error.code);
         return r;
     }, (e) => {

package/dist/tools/fs/shell-read-establish.d.ts

@@ -43,6 +43,7 @@ import { type ObservedEnvironment } from "./shell-read-environment.js";
 import type { ShellReadPlan, ShellReadSegment } from "./shell-read-plan.js";
 import type { EstablishedRead, ShellReadBoundary } from "./shell-read-judge.js";
 import type { HomeViewSource } from "./read-deny-home.js";
+import { type FsGlob } from "./fs-glob.js";
 /**
  * How many directories one glob operand may enumerate, and how many names it may
  * match, before the leg gives up and answers `unestablishable`.
@@ -54,6 +55,20 @@ import type { HomeViewSource } from "./read-deny-home.js";
  */
 export declare const MAX_GLOB_DIRS = 256;
 export declare const MAX_GLOB_MATCHES = 8192;
+/**
+ * Compile ONE path segment of a shell glob into a whole-name matcher (the engine in `fs-glob.ts`), or `undefined` when the
+ * pattern uses a construct this matcher does not model (the caller then fails closed).
+ *
+ * Modelled: `*` (any run of non-separator characters), `?` (one), and bracket expressions with `!`/`^`
+ * negation, `a-z` ranges, and a literal `]` in first position. A POSIX class (`[[:alpha:]]`) is deliberately widened to
+ * "any one character" rather than refused — the lexer spells such a class, and one holding a quoted character, `?` —
+ * over-matching only adds candidates to verify, the safe direction here, while refusing would cost a usable idiom.
+ *
+ * NOT modelled: a backslash. Its escaping semantics interact with the lexer's quote folding (which has
+ * already rewritten the token), so a segment carrying one is failed closed rather than guessed at. The
+ * leading-dot rule is not a property of the pattern's own text and lives in {@link globSegmentMatches}.
+ */
+export declare function compileGlobSegment(pattern: string): FsGlob | undefined;
 /** The reads of one plan, established: per segment, in the plan's own order, with nested plans beside. */
 export interface EstablishedPlan {
     readonly plan: ShellReadPlan;

package/dist/tools/fs/shell-read-establish.js

@@ -1,45 +1,44 @@
-import { canonicalRootsOnce, observeEnvironment } from "./shell-read-environment.js";
+import { canonicalRootsOnce, isAbsence, observeEnvironment } from "./shell-read-environment.js";
 import { anchorSpelling, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
 import { boundaryIsTheSandbox } from "../../core/remote-env.js";
 import { resolveOperandSpellings } from "./bash-readonly-classifier.js";
 import { judgedCandidatesOf, sedBackupNames } from "./shell-read-write-targets.js";
 import { movedReads, withHomeViews } from "./shell-read-identity.js";
 import { passesUnasked } from "./shell-read-device.js";
+import { compileFsGlob, fsGlobClass } from "./fs-glob.js";
 const GLOB_METACHAR_RE = /[*?[]/;
 export const MAX_GLOB_DIRS = 256;
 export const MAX_GLOB_MATCHES = 8192;
 const WRITE_LINK_HOPS = 32;
-function compileGlobSegment(pattern) {
+export function compileGlobSegment(pattern) {
     if (pattern.includes("\\"))
         return undefined;
-    let src = "";
+    const tokens = [];
     for (let i = 0; i < pattern.length; i++) {
         const ch = pattern[i];
         if (ch === "*") {
-            src += "[^/]*";
+            tokens.push({ kind: "star" });
         }
         else if (ch === "?") {
-            src += "[^/]";
+            tokens.push({ kind: "one" });
         }
         else if (ch === "[") {
-            const cls = parseBracketExpression(pattern, i);
-            if (cls === undefined)
-                src += "\\[";
+            const bracket = parseBracketExpression(pattern, i);
+            if (bracket === undefined)
+                tokens.push({ kind: "text", text: "[" });
             else {
-                src += cls.source;
-                i = cls.end;
+                const cls = fsGlobClass(bracket.source);
+                if (cls === undefined)
+                    return undefined;
+                tokens.push({ kind: "class", class: cls });
+                i = bracket.end;
             }
         }
         else {
-            src += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            tokens.push({ kind: "text", text: ch });
         }
     }
-    try {
-        return new RegExp(`^${src}$`, "s");
-    }
-    catch {
-        return undefined;
-    }
+    return compileFsGlob(tokens, "start");
 }
 function parseBracketExpression(pattern, start) {
     let i = start + 1;
@@ -248,7 +247,7 @@ function establishLegOver(seen, readRoots) {
                     return { value: canon.value, exact: true };
                 return { value: [canon.value.replace(TRAILING_SEP, ""), ...[...tail].reverse()].join("/"), exact: false, missing: allAbsent };
             }
-            if (canon.error.code !== "not_found" && canon.error.code !== "not_directory")
+            if (!isAbsence(canon.error.code))
                 allAbsent = false;
             tail.push(parts.pop());
         }
@@ -339,7 +338,7 @@ function establishLegOver(seen, readRoots) {
                     return { unverifiable: `"${dir}" cannot be resolved to verify what "${seg}" would expand to` };
                 const listed = await env.listDir(canonDir?.value ?? dir, signal);
                 if (!listed.ok) {
-                    if (listed.error.code === "not_found" || listed.error.code === "not_directory")
+                    if (isAbsence(listed.error.code))
                         continue;
                     return { unverifiable: `"${dir}" cannot be enumerated to verify what "${seg}" would expand to (${listed.error.code})` };
                 }
@@ -414,7 +413,7 @@ function establishLegOver(seen, readRoots) {
                 return parent.missing === true ? name : undefined;
             const entry = await env.fileInfo(joinUnder(parent.value, leaf), signal);
             if (!entry.ok)
-                return entry.error.code === "not_found" || entry.error.code === "not_directory" ? name : undefined;
+                return isAbsence(entry.error.code) ? name : undefined;
             if (entry.value.kind !== "symlink")
                 return name;
             const link = await env.readLink?.(joinUnder(parent.value, leaf), signal);