@xandreed/plugin-workspace 0.0.0-stage → 0.15.0

package/dist/text-edit.entity.d.ts

@@ -0,0 +1,32 @@
+import { Schema } from "effect";
+/**
+ * How a text ends its lines: every break is `\r\n` (`crlf`), none has a
+ * `\r` (`lf`), or both kinds appear (`mixed`, matched as it is).
+ */
+export declare const LineEnding: Schema.Literals<readonly ["lf", "crlf", "mixed"]>;
+export type LineEnding = typeof LineEnding.Type;
+/**
+ * Edits applied to a text: `text` is the new text, in the original's line
+ * endings; `before` and `after` are the old and new text with `\n` line
+ * breaks (what a diff compares); `replaced` counts the edits, `normalized`
+ * says whether any was found only after normalising, and
+ * `firstChangedLine` is the 1-based line of the first change.
+ */
+export declare const EditPlan: Schema.Struct<{
+    readonly text: Schema.String;
+    readonly before: Schema.String;
+    readonly after: Schema.String;
+    readonly replaced: Schema.Int;
+    readonly normalized: Schema.Boolean;
+    readonly firstChangedLine: Schema.Int;
+}>;
+export type EditPlan = typeof EditPlan.Type;
+/** Where one edit applies in the original: the span `[start, end)` and what replaces it. */
+export declare const EditSpan: Schema.Struct<{
+    readonly index: Schema.Int;
+    readonly start: Schema.Int;
+    readonly end: Schema.Int;
+    readonly newText: Schema.String;
+    readonly normalized: Schema.Boolean;
+}>;
+export type EditSpan = typeof EditSpan.Type;

package/dist/text-edit.entity.functions.d.ts

@@ -0,0 +1,32 @@
+import { Result } from "effect";
+import type { Failure } from "@xandreed/core";
+import type { EditPlan, LineEnding } from "./text-edit.entity.js";
+import type { TextEdit } from "./workspace-tools.entity.js";
+/** How `text` ends its lines (see `LineEnding`). */
+export declare const lineEndingOf: (text: string) => LineEnding;
+/**
+ * A line as the fallback compares it: Unicode compatibility forms folded
+ * (NFKC, which also makes a no-break space a space), curly quotes and
+ * primes made straight, dashes and the minus sign made `-`, runs of
+ * whitespace made one space, and the ends trimmed.
+ */
+export declare const normalizeLine: (line: string) => string;
+/**
+ * Apply edits to a file's text. Every edit is matched against the original,
+ * never against another edit's result: its `oldText` must appear exactly
+ * once (an empty one is refused), or, with `fuzzy`, once over whole lines
+ * after `normalizeLine`. The spans must not overlap. A text whose every
+ * line break is `\r\n` is matched with `\n` breaks (in it and in the edits)
+ * and written back with `\r\n`; a text without `\r` gets the edits' `\r\n`
+ * as `\n`. Edits that leave the text as it was fail with `NoChange`.
+ */
+export declare const applyTextEdits: (original: string, edits: ReadonlyArray<TextEdit>, options: {
+    readonly fuzzy: boolean;
+}) => Result.Result<EditPlan, Failure>;
+/**
+ * The change as a unified diff (`--- path` / `+++ path`), from effect's
+ * `TextDiff` with at most 10 000 edits searched per changed region (beyond
+ * that the diff stays valid, just not minimal), cut to `maxBytes` characters
+ * with a note when longer.
+ */
+export declare const unifiedDiff: (path: string, before: string, after: string, maxChars: number) => string;

package/dist/text-edit.entity.functions.js

@@ -0,0 +1,68 @@
+import { Option, Result, TextDiff } from "effect";
+const failure = (error, message) => ({ error, message });
+export const lineEndingOf = (text) => !text.includes("\r") ? "lf" : text.includes(`\r
+`) && !/(^|[^\r])\n/.test(text) ? "crlf" : "mixed", normalizeLine = (line) => line.normalize("NFKC").replace(/[\u2018\u2019\u201A\u201B\u2032\u2035]/g, "'").replace(/[\u201C\u201D\u201E\u201F\u2033\u2036]/g, '"').replace(/[\u2010-\u2015\u2212]/g, "-").replace(/\s+/g, " ").trim();
+const label = (index, count) => count === 1 ? "oldText" : `edit ${index + 1}'s oldText`, exactSpan = (base, edit, index, count) => {
+  const first = base.indexOf(edit.oldText);
+  if (first < 0)
+    return Result.succeed(Option.none());
+  if (base.indexOf(edit.oldText, first + 1) >= 0)
+    return Result.fail(failure("AmbiguousMatch", `${label(index, count)} appears ${Math.max(2, base.split(edit.oldText).length - 1)} times; add surrounding lines so it appears exactly once`));
+  return Result.succeed(Option.some({ index, start: first, end: first + edit.oldText.length, newText: edit.newText, normalized: !1 }));
+}, normalizedSpan = (base, edit, index, count) => {
+  const withBreak = edit.oldText.endsWith(`
+`), wantedLines = edit.oldText.split(`
+`), wanted = (withBreak ? wantedLines.slice(0, -1) : wantedLines).map(normalizeLine);
+  if (wanted.every((line) => line.length === 0))
+    return Result.succeed(Option.none());
+  const lines = base.split(`
+`), normal = lines.map(normalizeLine), starts = Array.from({ length: Math.max(0, lines.length - wanted.length + 1) }, (_, at) => at).filter((at) => wanted.every((line, offset) => normal[at + offset] === line)), [start, ...others] = starts;
+  if (start === void 0)
+    return Result.succeed(Option.none());
+  if (others.length > 0)
+    return Result.fail(failure("AmbiguousMatch", `${label(index, count)} matches ${starts.length} places once whitespace and quotes are normalised; add surrounding lines so it matches exactly once`));
+  const lineStart = (line) => lines.slice(0, line).reduce((total, text) => total + text.length + 1, 0), after = start + wanted.length, lastLine = lines[after - 1] ?? "", end = withBreak ? Math.min(base.length, lineStart(after)) : lineStart(after) - 1 - (lastLine.endsWith("\r") ? 1 : 0);
+  return Result.succeed(Option.some({ index, start: lineStart(start), end, newText: edit.newText, normalized: !0 }));
+}, spanOf = (base, edit, index, count, fuzzy) => {
+  if (edit.oldText.length === 0)
+    return Result.fail(failure("EmptyOldText", `${label(index, count)} is empty; to create a file or replace all of it, use write`));
+  return Result.flatMap(exactSpan(base, edit, index, count), Option.match({
+    onSome: Result.succeed,
+    onNone: () => Result.flatMap(fuzzy ? normalizedSpan(base, edit, index, count) : Result.succeed(Option.none()), Option.match({
+      onSome: Result.succeed,
+      onNone: () => Result.fail(failure("NoMatch", `${label(index, count)} was not found in the file; read it again and copy the text exactly, whitespace included`))
+    }))
+  }));
+};
+export const applyTextEdits = (original, edits, options) => {
+  const ending = lineEndingOf(original), plain = (text) => ending === "mixed" ? text : text.replaceAll(`\r
+`, `
+`), base = plain(original), found = Result.all(edits.map((edit, index) => spanOf(base, { oldText: plain(edit.oldText), newText: plain(edit.newText) }, index, edits.length, options.fuzzy)));
+  return Result.flatMap(found, (spans) => {
+    const ordered = [...spans].sort((left, right) => left.start - right.start), clash = ordered.findIndex((span, at) => at > 0 && span.start < (ordered[at - 1]?.end ?? 0));
+    if (clash > 0) {
+      const [first, second] = [ordered[clash - 1]?.index ?? 0, ordered[clash]?.index ?? 0].sort((left, right) => left - right);
+      return Result.fail(failure("OverlappingEdits", `edits ${(first ?? 0) + 1} and ${(second ?? 0) + 1} change overlapping text; merge them into one edit`));
+    }
+    const built = ordered.reduce((state, span) => ({ text: state.text + base.slice(state.at, span.start) + span.newText, at: span.end }), { text: "", at: 0 }), after = built.text + base.slice(built.at);
+    if (after === base)
+      return Result.fail(failure("NoChange", "the edits leave the file as it is"));
+    const firstStart = ordered[0]?.start ?? 0;
+    return Result.succeed({
+      text: ending === "crlf" ? after.replaceAll(`
+`, `\r
+`) : after,
+      before: base,
+      after,
+      replaced: ordered.length,
+      normalized: ordered.some((span) => span.normalized),
+      firstChangedLine: base.slice(0, firstStart).split(`
+`).length
+    });
+  });
+}, unifiedDiff = (path, before, after, maxChars) => {
+  const diff = TextDiff.unified(TextDiff.lines(before, after, { maxEdits: 1e4 }), { fromFile: path, toFile: path });
+  return diff.length <= maxChars ? diff : `${diff.slice(0, maxChars)}
+[diff cut at ${maxChars} characters]
+`;
+};

package/dist/text-edit.entity.js

@@ -0,0 +1,15 @@
+import { Schema } from "effect";
+export const LineEnding = Schema.Literals(["lf", "crlf", "mixed"]), EditPlan = Schema.Struct({
+  text: Schema.String,
+  before: Schema.String,
+  after: Schema.String,
+  replaced: Schema.Int,
+  normalized: Schema.Boolean,
+  firstChangedLine: Schema.Int
+}), EditSpan = Schema.Struct({
+  index: Schema.Int,
+  start: Schema.Int,
+  end: Schema.Int,
+  newText: Schema.String,
+  normalized: Schema.Boolean
+});

package/dist/text-search.entity.d.ts

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+/** One line of a file's search result: its 1-based number, its text (cut to the line width), and whether it matched or is context. */
+export declare const SearchLine: Schema.Struct<{
+    readonly line: Schema.Int;
+    readonly text: Schema.String;
+    readonly match: Schema.Boolean;
+}>;
+export type SearchLine = typeof SearchLine.Type;
+/**
+ * One file searched: the lines to show (matches and their context, in
+ * order), how many lines matched in what was searched, and whether the
+ * search stopped at its cap with more of the file left.
+ */
+export declare const FileSearch: Schema.Struct<{
+    readonly lines: Schema.$Array<Schema.Struct<{
+        readonly line: Schema.Int;
+        readonly text: Schema.String;
+        readonly match: Schema.Boolean;
+    }>>;
+    readonly matches: Schema.Int;
+    readonly capped: Schema.Boolean;
+}>;
+export type FileSearch = typeof FileSearch.Type;

package/dist/text-search.entity.functions.d.ts

@@ -0,0 +1,58 @@
+import { Result } from "effect";
+import type { Failure } from "@xandreed/core";
+import type { FileSearch } from "./text-search.entity.js";
+/**
+ * Whether a regular expression (one that compiles, without the `u` or `v`
+ * flag) repeats without bound a group that itself holds an unbounded
+ * repetition: `(a+)+`, `(x*)*`, `(?:\w+\s?)*`, `((ab)+)+`. Such patterns
+ * backtrack exponentially on some lines. Repeating a group a bounded
+ * number of times (`(\d+\.){3}`) is not counted.
+ */
+export declare const repeatsRepetition: (source: string) => boolean;
+/**
+ * The pattern, refused (`InvalidPattern`) when it holds a line break: `grep`
+ * matches one line at a time, so the builtin engine would find nothing and
+ * ripgrep, which reads its patterns one per line from stdin, would search
+ * for each line of it on its own. Both engines refuse it alike.
+ */
+export declare const singleLinePattern: (pattern: string) => Result.Result<string, Failure>;
+/**
+ * The expression `grep` matches with: the pattern as a JavaScript regular
+ * expression, or, with `literal`, as plain text; `ignoreCase` ignores
+ * case. Fails with `InvalidPattern` when the pattern does not compile, or
+ * when it repeats a repeating group (`repeatsRepetition`): matching runs
+ * in the host's process and cannot be interrupted, and such a pattern can
+ * take exponential time on one line.
+ */
+export declare const compilePattern: (pattern: string, options: {
+    readonly literal: boolean;
+    readonly ignoreCase: boolean;
+}) => Result.Result<RegExp, Failure>;
+/**
+ * Search a file's text line by line. Each line is cut to `lineChars`
+ * characters first and only the cut line is matched (a match past the cut
+ * is not found), so how long a line may take is bounded by the cut, not by
+ * the line. That bound holds for patterns that match in linear time: the
+ * expression runs synchronously in the host's process, and a backtracking
+ * one can still take long on a cut line. `compilePattern` refuses nested
+ * repetition, the usual exponential form, but not every slow pattern
+ * (overlapping alternatives such as `(a|a)*`). At most `cap` matching lines
+ * are taken, each with up to `context` lines before and after it;
+ * overlapping context is shown once, in line order.
+ */
+export declare const searchText: (text: string, pattern: RegExp, options: {
+    readonly lineChars: number;
+    readonly context: number;
+    readonly cap: number;
+}) => FileSearch;
+/**
+ * The model's view of matches: `path:line:text` for a matching line,
+ * `path-line-text` for context, and, when there is context, `--` between
+ * runs of lines that are not adjacent (or not in one file).
+ */
+export declare const renderSearchLines: (lines: ReadonlyArray<{
+    readonly path: string;
+    readonly line: number;
+    readonly text: string;
+    readonly match: boolean;
+}>, withContext: boolean) => ReadonlyArray<string>;

package/dist/text-search.entity.functions.js

@@ -0,0 +1,30 @@
+import { Result } from "effect";
+import { clipChars, splitLines } from "./text-window.entity.functions.js";
+const failure = (error, message) => ({ error, message }), tokenPattern = /\\[\s\S]|\[(?:\\[\s\S]|[^\]\\])*\]|\((?:\?(?::|=|!|<=|<!|<[A-Za-z_$][\w$]*>))?|\)|\{\d+(?:,\d*)?\}\??|[*+?]\??|[\s\S]/g, unbounded = (token) => token.startsWith("*") || token.startsWith("+") || /^\{\d+,\}/.test(token), isQuantifier = (token) => /^(?:[*+?]|\{\d+(?:,\d*)?\})\??$/.test(token);
+export const repeatsRepetition = (source) => (source.match(tokenPattern) ?? []).reduce((scan, token) => {
+  if (token.startsWith("("))
+    return { groups: [...scan.groups, !1], closedRepeating: !1, nested: scan.nested };
+  if (token === ")") {
+    const inner = scan.groups.at(-1) ?? !1, outer = scan.groups.slice(0, -1);
+    return { groups: outer.length === 0 ? [inner] : [...outer.slice(0, -1), (outer.at(-1) ?? !1) || inner], closedRepeating: inner, nested: scan.nested };
+  }
+  if (isQuantifier(token) && unbounded(token))
+    return { groups: [...scan.groups.slice(0, -1), !0], closedRepeating: !1, nested: scan.nested || scan.closedRepeating };
+  return { ...scan, closedRepeating: !1 };
+}, { groups: [!1], closedRepeating: !1, nested: !1 }).nested, singleLinePattern = (pattern) => /[\r\n]/.test(pattern) ? Result.fail(failure("InvalidPattern", "the pattern contains a line break, but grep matches one line at a time; search for a single line of the text instead")) : Result.succeed(pattern), compilePattern = (pattern, options) => {
+  const source = options.literal ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern, compiled = Result.try({
+    try: () => new RegExp(source, options.ignoreCase ? "i" : ""),
+    catch: (error) => failure("InvalidPattern", `${pattern} is not a valid regular expression; the engine says: ${error instanceof Error ? error.message : String(error)}. Pass literal: true to search for it as text`)
+  });
+  return Result.flatMap(compiled, (regex) => !options.literal && repeatsRepetition(source) ? Result.fail(failure("InvalidPattern", `${pattern} repeats a group that itself repeats (as in (a+)+), which can take exponential time on some lines; rewrite it without the nested repetition, or search with bash (grep -E, rg)`)) : Result.succeed(regex));
+}, searchText = (text, pattern, options) => {
+  const lines = splitLines(text).map((line) => clipChars(line, options.lineChars).text), hits = lines.reduce((state, line, at) => state.capped ? state : !pattern.test(line) ? state : state.found.length >= options.cap ? { found: state.found, capped: !0 } : { found: [...state.found, at], capped: !1 }, { found: [], capped: !1 }), shown = new Set(hits.found.flatMap((at) => Array.from({ length: options.context * 2 + 1 }, (_, offset) => at - options.context + offset).filter((line) => line >= 0 && line < lines.length))), matched = new Set(hits.found);
+  return {
+    lines: [...shown].sort((left, right) => left - right).map((at) => ({ line: at + 1, text: lines[at] ?? "", match: matched.has(at) })),
+    matches: hits.found.length,
+    capped: hits.capped
+  };
+}, renderSearchLines = (lines, withContext) => lines.flatMap((entry, at) => {
+  const previous = lines[at - 1];
+  return [...withContext && previous !== void 0 && (previous.path !== entry.path || previous.line + 1 !== entry.line) ? ["--"] : [], `${entry.path}${entry.match ? ":" : "-"}${entry.line}${entry.match ? ":" : "-"}${entry.text}`];
+});

package/dist/text-search.entity.js

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+export const SearchLine = Schema.Struct({
+  line: Schema.Int,
+  text: Schema.String,
+  match: Schema.Boolean
+}), FileSearch = Schema.Struct({
+  lines: Schema.Array(SearchLine),
+  matches: Schema.Int,
+  capped: Schema.Boolean
+});

package/dist/text-window.entity.d.ts

@@ -0,0 +1,46 @@
+import { Schema } from "effect";
+/**
+ * Lines `lineWindow` picked from a text: `lines` are lines `firstLine` to
+ * `lastLine` (1-based) of `totalLines`; `next` is the line to continue from
+ * when some are left; `clipped` when the first line alone was longer than
+ * the window's bytes and only its start is in `lines`.
+ */
+export declare const LineWindow: Schema.Struct<{
+    readonly lines: Schema.$Array<Schema.String>;
+    readonly firstLine: Schema.Int;
+    readonly lastLine: Schema.Int;
+    readonly totalLines: Schema.Int;
+    readonly next: Schema.Option<Schema.Int>;
+    readonly clipped: Schema.Boolean;
+}>;
+export type LineWindow = typeof LineWindow.Type;
+/** The lines `headLines` keeps from the start of a list, and how many it left out. */
+export declare const HeadLines: Schema.Struct<{
+    readonly lines: Schema.$Array<Schema.String>;
+    readonly omitted: Schema.Int;
+}>;
+export type HeadLines = typeof HeadLines.Type;
+/**
+ * The end of a command's output `tailText` keeps: `text` is its last whole
+ * lines within the limits (or, when the last line alone is longer than the
+ * bytes allowed, the end of that line); `totalLines` counts the lines of the
+ * whole output; `truncated` when anything was left out.
+ */
+export declare const OutputTail: Schema.Struct<{
+    readonly text: Schema.String;
+    readonly shownLines: Schema.Int;
+    readonly totalLines: Schema.Int;
+    readonly truncated: Schema.Boolean;
+}>;
+export type OutputTail = typeof OutputTail.Type;
+/**
+ * A file's bytes as text: the BOM, when there was one, removed and
+ * remembered; `lossy` when the bytes were not valid UTF-8, so the sequences
+ * that were not became U+FFFD and writing the text back would change them.
+ */
+export declare const DecodedText: Schema.Struct<{
+    readonly text: Schema.String;
+    readonly bom: Schema.Boolean;
+    readonly lossy: Schema.Boolean;
+}>;
+export type DecodedText = typeof DecodedText.Type;

package/dist/text-window.entity.functions.d.ts

@@ -0,0 +1,54 @@
+import { Option, Result } from "effect";
+import type { DecodedText, HeadLines, LineWindow, OutputTail } from "./text-window.entity.js";
+/** How many bytes `text` takes as UTF-8. */
+export declare const utf8Length: (text: string) => number;
+/** The start of `text`, at most `maxBytes` of UTF-8, never cutting a character in two. */
+export declare const clipHead: (text: string, maxBytes: number) => string;
+/** The end of `text`, at most `maxBytes` of UTF-8, never cutting a character in two. */
+export declare const clipTail: (text: string, maxBytes: number) => string;
+/** The start of a line, at most `maxChars` UTF-16 code units, never splitting a surrogate pair; and whether anything was cut. */
+export declare const clipChars: (line: string, maxChars: number) => {
+    readonly text: string;
+    readonly clipped: boolean;
+};
+/**
+ * A text's lines: split at `\n`, with a `\r` before it dropped. A final
+ * newline ends the last line rather than starting an empty one, so `""` has
+ * no lines and `"a\n"` has one.
+ */
+export declare const splitLines: (text: string) => ReadonlyArray<string>;
+/**
+ * The lines `read` shows: from line `offset` (1-based), at most `limit` of
+ * them and at most `maxBytes` of UTF-8, whole lines only, except that a
+ * first line longer than `maxBytes` is shown cut (`clipped`) rather than
+ * not at all. An empty text has an empty window at offset 1; an offset past
+ * the last line fails with the number of lines there are.
+ */
+export declare const lineWindow: (text: string, options: {
+    readonly offset: number;
+    readonly limit: number;
+    readonly maxBytes: number;
+}) => Result.Result<LineWindow, number>;
+/** The first lines of a list that fit `maxLines` and `maxBytes` (a first line longer than `maxBytes` is cut), and how many were left out. */
+export declare const headLines: (lines: ReadonlyArray<string>, maxLines: number, maxBytes: number) => HeadLines;
+/**
+ * The end of a command's output: its last whole lines within `maxLines` and
+ * `maxBytes`, or, when the last line alone is longer than `maxBytes`, that
+ * line's end.
+ */
+export declare const tailText: (text: string, maxLines: number, maxBytes: number) => OutputTail;
+/** Whether bytes look binary: a NUL byte in the first 8 KB. */
+export declare const looksBinary: (bytes: Uint8Array) => boolean;
+/**
+ * A file's bytes as UTF-8 text, its BOM removed and remembered. Bytes that
+ * are not valid UTF-8 (Latin-1, Windows-1252, Shift-JIS) are decoded all
+ * the same, their invalid sequences as U+FFFD, and the result says `lossy`:
+ * fit to show or search, not to write back.
+ */
+export declare const decodeText: (bytes: Uint8Array) => DecodedText;
+/** Text to write back: with its BOM again when it had one. */
+export declare const encodeText: (decoded: Pick<DecodedText, "text" | "bom">) => string;
+/** The media type a file name's extension suggests, for binary files the tools do not open. */
+export declare const mediaTypeOf: (name: string) => Option.Option<string>;
+/** A byte count for people: `812 B`, `50 KB`, `1.5 MB`. */
+export declare const formatBytes: (bytes: number) => string;

package/dist/text-window.entity.functions.js

@@ -0,0 +1,88 @@
+import { Option, Result } from "effect";
+const encoder = new TextEncoder, decoder = new TextDecoder("utf-8", { ignoreBOM: !0 }), strictDecoder = new TextDecoder("utf-8", { ignoreBOM: !0, fatal: !0 });
+export const utf8Length = (text) => encoder.encode(text).length;
+const isContinuation = (bytes, at) => ((bytes[at] ?? 0) & 192) === 128, startAtOrBefore = (bytes, at) => at <= 0 ? 0 : at >= bytes.length ? bytes.length : isContinuation(bytes, at) ? startAtOrBefore(bytes, at - 1) : at, startAtOrAfter = (bytes, at) => at >= bytes.length ? bytes.length : at > 0 && isContinuation(bytes, at) ? startAtOrAfter(bytes, at + 1) : Math.max(0, at);
+export const clipHead = (text, maxBytes) => {
+  const bytes = encoder.encode(text);
+  return bytes.length <= maxBytes ? text : decoder.decode(bytes.subarray(0, startAtOrBefore(bytes, maxBytes)));
+}, clipTail = (text, maxBytes) => {
+  const bytes = encoder.encode(text);
+  return bytes.length <= maxBytes ? text : decoder.decode(bytes.subarray(startAtOrAfter(bytes, bytes.length - maxBytes)));
+}, clipChars = (line, maxChars) => {
+  if (line.length <= maxChars)
+    return { text: line, clipped: !1 };
+  const last = line.charCodeAt(maxChars - 1);
+  return { text: line.slice(0, last >= 55296 && last <= 56319 ? maxChars - 1 : maxChars), clipped: !0 };
+}, splitLines = (text) => {
+  if (text.length === 0)
+    return [];
+  const parts = text.split(`
+`);
+  return (parts.at(-1) === "" ? parts.slice(0, -1) : parts).map((line) => line.endsWith("\r") ? line.slice(0, -1) : line);
+};
+const fitting = (lines, maxBytes) => {
+  const over = lines.reduce((sums, line) => {
+    sums.push(sums.length === 0 ? utf8Length(line) : (sums.at(-1) ?? 0) + 1 + utf8Length(line));
+    return sums;
+  }, []).findIndex((total) => total > maxBytes);
+  return over < 0 ? lines.length : over;
+};
+export const lineWindow = (text, options) => {
+  const all = splitLines(text), start = options.offset - 1;
+  if (all.length === 0 && start === 0)
+    return Result.succeed({ lines: [], firstLine: 0, lastLine: 0, totalLines: 0, next: Option.none(), clipped: !1 });
+  if (start >= all.length)
+    return Result.fail(all.length);
+  const candidate = all.slice(start, start + options.limit), count = fitting(candidate, options.maxBytes), clipped = count === 0, lines = clipped ? [clipHead(candidate[0] ?? "", options.maxBytes)] : candidate.slice(0, count), lastLine = start + lines.length;
+  return Result.succeed({
+    lines,
+    firstLine: options.offset,
+    lastLine,
+    totalLines: all.length,
+    next: lastLine < all.length ? Option.some(lastLine + 1) : Option.none(),
+    clipped
+  });
+}, headLines = (lines, maxLines, maxBytes) => {
+  const capped = lines.slice(0, maxLines), count = fitting(capped, maxBytes), kept = count === 0 && capped.length > 0 ? [clipHead(capped[0] ?? "", maxBytes)] : capped.slice(0, count);
+  return { lines: kept, omitted: lines.length - kept.length };
+}, tailText = (text, maxLines, maxBytes) => {
+  const all = splitLines(text), capped = all.slice(Math.max(0, all.length - maxLines)), count = fitting([...capped].reverse(), maxBytes), kept = count === 0 && capped.length > 0 ? [clipTail(capped.at(-1) ?? "", maxBytes)] : capped.slice(capped.length - count);
+  return { text: kept.join(`
+`), shownLines: kept.length, totalLines: all.length, truncated: kept.length < all.length || count === 0 && capped.length > 0 };
+}, looksBinary = (bytes) => bytes.subarray(0, 8192).includes(0), decodeText = (bytes) => {
+  const bom = bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191, body = bom ? bytes.subarray(3) : bytes;
+  return Result.match(Result.try(() => strictDecoder.decode(body)), {
+    onSuccess: (text) => ({ text, bom, lossy: !1 }),
+    onFailure: () => ({ text: decoder.decode(body), bom, lossy: !0 })
+  });
+}, encodeText = (decoded) => decoded.bom ? `\uFEFF${decoded.text}` : decoded.text;
+const mediaTypes = new Map([
+  ["png", "image/png"],
+  ["jpg", "image/jpeg"],
+  ["jpeg", "image/jpeg"],
+  ["gif", "image/gif"],
+  ["webp", "image/webp"],
+  ["bmp", "image/bmp"],
+  ["ico", "image/x-icon"],
+  ["tif", "image/tiff"],
+  ["tiff", "image/tiff"],
+  ["avif", "image/avif"],
+  ["heic", "image/heic"],
+  ["pdf", "application/pdf"],
+  ["zip", "application/zip"],
+  ["gz", "application/gzip"],
+  ["tar", "application/x-tar"],
+  ["wasm", "application/wasm"],
+  ["mp3", "audio/mpeg"],
+  ["wav", "audio/wav"],
+  ["mp4", "video/mp4"],
+  ["webm", "video/webm"],
+  ["woff", "font/woff"],
+  ["woff2", "font/woff2"],
+  ["ttf", "font/ttf"],
+  ["otf", "font/otf"]
+]);
+export const mediaTypeOf = (name) => {
+  const base = name.slice(name.lastIndexOf("/") + 1), dot = base.lastIndexOf(".");
+  return dot <= 0 ? Option.none() : Option.fromNullishOr(mediaTypes.get(base.slice(dot + 1).toLowerCase()));
+}, formatBytes = (bytes) => bytes < 1024 ? `${bytes} B` : bytes < 1048576 ? `${Number.isInteger(bytes / 1024) ? bytes / 1024 : (bytes / 1024).toFixed(1)} KB` : `${Number.isInteger(bytes / 1048576) ? bytes / 1048576 : (bytes / 1048576).toFixed(1)} MB`;

package/dist/text-window.entity.js

@@ -0,0 +1,21 @@
+import { Schema } from "effect";
+export const LineWindow = Schema.Struct({
+  lines: Schema.Array(Schema.String),
+  firstLine: Schema.Int,
+  lastLine: Schema.Int,
+  totalLines: Schema.Int,
+  next: Schema.Option(Schema.Int),
+  clipped: Schema.Boolean
+}), HeadLines = Schema.Struct({
+  lines: Schema.Array(Schema.String),
+  omitted: Schema.Int
+}), OutputTail = Schema.Struct({
+  text: Schema.String,
+  shownLines: Schema.Int,
+  totalLines: Schema.Int,
+  truncated: Schema.Boolean
+}), DecodedText = Schema.Struct({
+  text: Schema.String,
+  bom: Schema.Boolean,
+  lossy: Schema.Boolean
+});

package/dist/workspace-path.entity.d.ts

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+/** Whether the file tools may only read a root, or may also change it. */
+export declare const WorkspaceAccessMode: Schema.Literals<readonly ["read", "write"]>;
+export type WorkspaceAccessMode = typeof WorkspaceAccessMode.Type;
+/** An extra file-tool root, absolute or relative to the session's workspace. */
+export declare const WorkspaceAllowedRoot: Schema.Struct<{
+    readonly path: Schema.NonEmptyString;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+}>;
+export type WorkspaceAllowedRoot = typeof WorkspaceAllowedRoot.Type;
+/** An allowed root, resolved on the same file system as the workspace. */
+export declare const AllowedRoot: Schema.Struct<{
+    readonly root: Schema.String;
+    readonly lexicalRoot: Schema.String;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+}>;
+export type AllowedRoot = typeof AllowedRoot.Type;
+/**
+ * A path a tool was given, resolved in the workspace: `path` is where the
+ * tool acts (absolute, every link on the way resolved, through the nearest
+ * ancestor that exists), `display` is how the model wrote it, relative to
+ * the workspace root (`.` for the root; absolute when outside it).
+ */
+export declare const WorkspaceTarget: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly display: Schema.String;
+}>;
+export type WorkspaceTarget = typeof WorkspaceTarget.Type;
+/**
+ * The workspace a call works in: its root as configured, made absolute
+ * (`lexicalRoot`), and as the file system resolves it (`root`, links
+ * resolved). Paths are resolved against `root`.
+ */
+export declare const WorkspaceRoot: Schema.Struct<{
+    readonly root: Schema.String;
+    readonly lexicalRoot: Schema.String;
+    readonly roots: Schema.$Array<Schema.Struct<{
+        readonly root: Schema.String;
+        readonly lexicalRoot: Schema.String;
+        readonly access: Schema.Literals<readonly ["read", "write"]>;
+    }>>;
+}>;
+export type WorkspaceRoot = typeof WorkspaceRoot.Type;

package/dist/workspace-path.entity.functions.d.ts

@@ -0,0 +1,90 @@
+import { Effect, Option, Result } from "effect";
+import type { Context, Path } from "effect";
+import { FileSystem, FsError, SessionEnvironment } from "@xandreed/core";
+import type { Failure, FsReason } from "@xandreed/core";
+import type { WorkspaceAccessMode, WorkspaceAllowedRoot, WorkspaceRoot, WorkspaceTarget } from "./workspace-path.entity.js";
+type Fs = Context.Service.Shape<typeof FileSystem>;
+/** The workspace a call works in (`WorkspaceRoot`), with the file system and path functions it uses. */
+export type WorkspaceAccess = WorkspaceRoot & {
+    readonly fs: Fs;
+    readonly path: Path.Path;
+};
+/**
+ * A file-system failure as the model reads it: what went wrong with the path
+ * it gave, in words, by the failure's reason. Never the backend's message,
+ * which names host paths the model never gave.
+ */
+export declare const fsFailure: (display: string) => (error: FsError) => Failure;
+/** The workspace directory cannot be opened: why, in words, never the reason's name or the backend's message (it names the host's path). */
+export declare const workspaceMissing: (reason: FsReason) => Failure;
+/** Whether `path` is `root` or below it. */
+export declare const isWithin: (root: string, path: string) => boolean;
+/**
+ * Open the workspace of the call: `SessionEnvironment.workspace` made
+ * absolute (against the process's directory) and resolved by the file
+ * system; one that cannot be resolved fails with `WorkspaceMissing`.
+ * Extra roots are resolved against it for this call. An extra root that
+ * cannot be opened as a directory is logged and left out.
+ */
+export declare const openWorkspace: (path: Path.Path, options?: {
+    readonly roots: ReadonlyArray<WorkspaceAllowedRoot>;
+    readonly workspaceAccess: WorkspaceAccessMode;
+} | undefined) => Effect.Effect<WorkspaceAccess, {
+    readonly error: string;
+    readonly message: string;
+}, FileSystem | SessionEnvironment>;
+/** Whether a real path is inside any root the file tools may read. */
+export declare const withinAnyRoot: (access: WorkspaceAccess, path: string) => boolean;
+/** How a path appears to the model: relative to the root (`.` for the root itself), or absolute outside it. */
+export declare const displayOf: (access: WorkspaceAccess, absolute: string) => string;
+/**
+ * Resolve a path a tool was given: relative to the workspace root, or
+ * absolute. With `confine`, a path written outside every allowed root is refused
+ * before anything is read, and so is one whose real location (links
+ * resolved, through the nearest existing ancestor) is outside all roots
+ * (`OutsideWorkspace`). A write into a read root fails with `ReadOnly`;
+ * the most specific real root decides access. With confinement off these
+ * restrictions are disabled. This is a guardrail against mistakes, not a
+ * sandbox: what a path names can change between this check and its use.
+ */
+export declare const resolveTarget: (access: WorkspaceAccess, input: string, options: {
+    readonly confine: boolean;
+    readonly intent?: WorkspaceAccessMode;
+}) => Effect.Effect<{
+    readonly path: string;
+    readonly display: string;
+}, {
+    readonly error: string;
+    readonly message: string;
+}, never>;
+/** A compiled `protect` glob: the pattern, and whether a path relative to the root matches it. */
+export interface ProtectRule {
+    readonly glob: string;
+    readonly matches: (relative: string) => boolean;
+}
+/**
+ * Compile `protect` globs (dot entries included); fails with the first
+ * pattern that does not compile. A rule also matches a path that differs
+ * from it only in letter case, so a case-insensitive file system cannot
+ * reach a protected file (`.GIT/config`) through another spelling.
+ */
+export declare const compileProtect: (globs: ReadonlyArray<string>) => Result.Result<ReadonlyArray<ProtectRule>, string>;
+/**
+ * The `exclude` globs as a walk from a directory must be given them, the
+ * directory written relative to the root (`""` for the root; none when it
+ * is outside the workspace). A name (no `/`) applies at any depth, so it is
+ * kept. A path is relative to the root, and the walk matches it against
+ * paths relative to where it starts: its leading segments are matched
+ * against the directory's names and what is left is kept, anchored there
+ * with `./`. A path that cannot reach below the directory, or that names
+ * the directory or one above it (the walk was asked to go there), is
+ * dropped, and so is every path when the directory is outside the
+ * workspace. A path whose braces span segments is kept as it is.
+ */
+export declare const excludesBelow: (excludes: ReadonlyArray<string>, directory: Option.Option<string>) => ReadonlyArray<string>;
+/**
+ * Refuse a write to a protected path: the path as written and where it
+ * really is are both checked, relative to the root, against every rule.
+ */
+export declare const checkWritable: (access: WorkspaceAccess, target: WorkspaceTarget, rules: ReadonlyArray<ProtectRule>) => Effect.Effect<void, Failure>;
+export {};