@xandreed/plugin-workspace 0.0.0-stage → 0.14.0

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,51 @@
+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 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, 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 (${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.functions.test.d.ts

@@ -0,0 +1 @@
+export {};

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.functions.test.d.ts

@@ -0,0 +1 @@
+export {};

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,22 @@
+import { Schema } from "effect";
+/**
+ * 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;
+}>;
+export type WorkspaceRoot = typeof WorkspaceRoot.Type;

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

@@ -0,0 +1,60 @@
+import { Effect, Option, Result } from "effect";
+import type { Context, Path } from "effect";
+import { FileSystem, FsError, SessionEnvironment } from "@xandreed/core";
+import type { Failure } from "@xandreed/core";
+import type { 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. */
+export declare const fsFailure: (display: string) => (error: FsError) => 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`.
+ */
+export declare const openWorkspace: (path: Path.Path) => Effect.Effect<WorkspaceAccess, Failure, FileSystem | SessionEnvironment>;
+/** 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 the root is refused
+ * before anything is read, and so is one whose real location (links
+ * resolved, through the nearest existing ancestor) is outside it
+ * (`OutsideWorkspace`). 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;
+}) => Effect.Effect<WorkspaceTarget, Failure>;
+/** 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. */
+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 {};

package/dist/workspace-path.entity.functions.js

@@ -0,0 +1,63 @@
+import { Effect, Option, Result } from "effect";
+import { compileGlob, FileSystem, FsError, SessionEnvironment } from "@xandreed/core";
+const failure = (error, message) => ({ error, message }), reasons = {
+  NotFound: (display) => failure("NotFound", `${display} does not exist`),
+  IsDirectory: (display) => failure("IsDirectory", `${display} is a directory`),
+  NotDirectory: (display) => failure("NotDirectory", `${display} is not a directory, or a part of the path before it is a file`),
+  Permission: (display) => failure("Permission", `permission denied: ${display}`)
+};
+export const fsFailure = (display) => (error) => reasons[error.reason]?.(display) ?? failure(error.reason, `${display}: ${error.message}`), isWithin = (root, path) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`), openWorkspace = (path) => Effect.gen(function* () {
+  const fs = yield* FileSystem, { workspace } = yield* SessionEnvironment, lexicalRoot = path.resolve(workspace), root = yield* fs.realPath(lexicalRoot).pipe(Effect.mapError((error) => failure("WorkspaceMissing", `the workspace directory cannot be opened (${error.reason}): ${error.message}`)));
+  return { fs, path, root, lexicalRoot };
+}), displayOf = (access, absolute) => {
+  const base = isWithin(access.root, absolute) ? access.root : isWithin(access.lexicalRoot, absolute) ? access.lexicalRoot : void 0;
+  if (base === void 0)
+    return absolute;
+  const relative = access.path.relative(base, absolute);
+  return relative === "" ? "." : relative;
+};
+const canonicalOf = (access, target) => access.fs.realPath(target).pipe(Effect.catchIf((error) => error.reason === "NotFound", (missing) => {
+  const parent = access.path.dirname(target);
+  if (parent === target)
+    return Effect.fail(missing);
+  return access.fs.stat(target, { followSymlinks: !1 }).pipe(Effect.matchEffect({
+    onSuccess: () => Effect.fail(new FsError({ path: target, reason: "Invalid", message: "it is a symbolic link to something that does not exist" })),
+    onFailure: (error) => error.reason === "NotFound" ? canonicalOf(access, parent).pipe(Effect.map((dir) => access.path.join(dir, access.path.basename(target)))) : Effect.fail(error)
+  }));
+}));
+export const resolveTarget = (access, input, options) => Effect.gen(function* () {
+  const lexical = access.path.resolve(access.root, input.length === 0 ? "." : input), display = displayOf(access, lexical), inside = (path) => isWithin(access.root, path) || isWithin(access.lexicalRoot, path);
+  if (options.confine && !inside(lexical))
+    return yield* Effect.fail(failure("OutsideWorkspace", `${input} is outside the workspace; use a path under its root`));
+  const path = yield* canonicalOf(access, lexical).pipe(Effect.mapError(fsFailure(display)));
+  if (options.confine && !isWithin(access.root, path))
+    return yield* Effect.fail(failure("OutsideWorkspace", `${display} leads outside the workspace through a symbolic link`));
+  return { path, display };
+}), compileProtect = (globs) => Result.all(globs.map((glob) => Result.mapError(Result.map(compileGlob(glob, { dot: !0 }), (matcher) => ({ glob, matches: matcher.matches })), (reason) => `protect glob ${glob} is not usable: ${reason}`)));
+const segmentsOf = (glob) => glob.split("/").filter((segment) => segment.length > 0 && segment !== "."), ownBraces = (segment) => (segment.match(/\{/g) ?? []).length === (segment.match(/\}/g) ?? []).length, remainderBelow = (pattern, names) => {
+  const [head, ...rest] = pattern, [name, ...below] = names;
+  if (name === void 0)
+    return pattern.length === 0 ? [] : [`./${pattern.join("/")}`];
+  if (head === void 0)
+    return [];
+  if (head === "**")
+    return [`./${pattern.join("/")}`, ...names.flatMap((_, at) => remainderBelow(rest, names.slice(at)))];
+  return Result.match(compileGlob(head, { dot: !0 }), {
+    onFailure: () => [],
+    onSuccess: (segment) => segment.matches(name) ? remainderBelow(rest, below) : []
+  });
+};
+export const excludesBelow = (excludes, directory) => [...new Set(excludes.flatMap((glob) => {
+  if (!glob.includes("/"))
+    return [glob];
+  return Option.match(directory, {
+    onNone: () => [],
+    onSome: (relative) => {
+      const names = segmentsOf(relative), pattern = segmentsOf(glob);
+      return names.length === 0 || !pattern.every(ownBraces) ? [glob] : remainderBelow(pattern, names);
+    }
+  });
+}))], checkWritable = (access, target, rules) => {
+  const relatives = [target.display, isWithin(access.root, target.path) ? access.path.relative(access.root, target.path) : ""].filter((relative) => relative.length > 0 && relative !== "." && !relative.startsWith("/") && !relative.startsWith("..")), rule = rules.find((candidate) => relatives.some((relative) => candidate.matches(relative)));
+  return rule === void 0 ? Effect.void : Effect.fail(failure("Protected", `${target.display} is protected (${rule.glob}); the workspace tools do not change it`));
+};

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

@@ -0,0 +1 @@
+export {};

package/dist/workspace-path.entity.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+export const WorkspaceTarget = Schema.Struct({
+  path: Schema.String,
+  display: Schema.String
+}), WorkspaceRoot = Schema.Struct({
+  root: Schema.String,
+  lexicalRoot: Schema.String
+});

package/dist/workspace-tools.adapter.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import type { Scope } from "effect";
+import { HarnessError } from "@xandreed/core";
+import type { Capability } from "@xandreed/core";
+import type { WorkspaceToolsConfig } from "./workspace-tools.entity.js";
+/**
+ * The workspace tools as one capability, for the workspace in each call's
+ * `SessionEnvironment`, over each call's `FileSystem` and `Bash`: `read`,
+ * `ls`, `find` and `grep` (skill `workspace.read`, read-only), `write` and
+ * `edit` (`workspace.edit`, needing `fs.write`) and `bash`
+ * (`workspace.shell`, needing `shell.exec`), plus the
+ * `workspace.environment` prompt section. Built once (in a scope, which
+ * holds the per-file write locks): `bash` and its skill are left out, with
+ * a warning, when there is no `Bash` service here; `protect` and `exclude`
+ * globs that do not compile fail with `config.options` (through the plugin,
+ * `WorkspaceToolsConfig` refuses them already when its options are
+ * decoded, so a graph refuses them before activating anything). Tools are never
+ * given guidance as skill instructions: it is in their descriptions and the
+ * section, since an always-on skill's instructions never reach the model.
+ */
+export declare const workspaceTools: (config: WorkspaceToolsConfig) => Effect.Effect<Capability, HarnessError, Scope.Scope>;

package/dist/workspace-tools.adapter.js

@@ -0,0 +1,46 @@
+import { Effect, Option, Path, RcMap, Result, Semaphore } from "effect";
+import { Bash, compileGlob, defineCapability, defineSkill, HarnessError, SessionEnvironment } from "@xandreed/core";
+import { bashTool } from "./bash-tool.adapter.js";
+import { findTool, grepTool, lsTool, readTool } from "./read-tools.adapter.js";
+import { compileProtect, openWorkspace } from "./workspace-path.entity.functions.js";
+import { WORKSPACE_PERMISSIONS } from "./workspace-tools.entity.js";
+import { environmentText, skillOfTool } from "./workspace-tools.entity.functions.js";
+import { editTool, writeTool } from "./write-tools.adapter.js";
+const ORDER = ["read", "ls", "find", "grep", "write", "edit", "bash"], builders = {
+  read: readTool,
+  ls: lsTool,
+  find: findTool,
+  grep: grepTool,
+  write: writeTool,
+  edit: editTool,
+  bash: bashTool
+}, skills = {
+  read: { id: "workspace.read", summary: "Read, list and search the workspace's files (read, ls, find, grep).", permissions: [] },
+  edit: { id: "workspace.edit", summary: "Create and change files in the workspace (write, edit).", permissions: [WORKSPACE_PERMISSIONS.write] },
+  shell: { id: "workspace.shell", summary: "Run shell commands in the workspace (bash).", permissions: [WORKSPACE_PERMISSIONS.exec] }
+}, invalid = (message) => new HarnessError({ code: "config.options", plugin: "@xandreed/plugin-workspace/tools", message });
+export const workspaceTools = (config) => Effect.gen(function* () {
+  const path = yield* Effect.service(Path.Path).pipe(Effect.provide(Path.layer)), protect = yield* Effect.fromResult(compileProtect(config.protect)).pipe(Effect.mapError(invalid)), badExclude = config.exclude.find((glob) => Result.isFailure(compileGlob(glob, { dot: !0 })));
+  if (badExclude !== void 0)
+    return yield* Effect.fail(invalid(`exclude glob ${badExclude} is not usable`));
+  const locks = yield* RcMap.make({ lookup: (_path) => Semaphore.make(1), idleTimeToLive: "1 minute" }), hasBash = Option.isSome(yield* Effect.serviceOption(Bash)), wanted = ORDER.filter((tool) => config.tools.includes(tool));
+  if (wanted.includes("bash") && !hasBash)
+    yield* Effect.logWarning("@xandreed/plugin-workspace/tools: there is no Bash service, so the bash tool and the workspace.shell skill are left out (add localSystemPlugin, or a Bash, to have them)");
+  const enabled = wanted.filter((tool) => tool !== "bash" || hasBash), context = { config, path, protect, locks }, section = {
+    id: "workspace.environment",
+    version: "1",
+    tier: "session",
+    order: config.sectionOrder,
+    render: () => openWorkspace(path).pipe(Effect.map((access) => access.root), Effect.catch(() => SessionEnvironment.pipe(Effect.map((environment) => path.resolve(environment.workspace)))), Effect.map((root) => Option.some(environmentText(root, config, enabled))))
+  };
+  return defineCapability({
+    id: "@xandreed/plugin-workspace/tools",
+    version: "1",
+    tools: enabled.map((tool) => builders[tool](context)),
+    skills: ["read", "edit", "shell"].flatMap((name) => {
+      const tools = enabled.filter((tool) => skillOfTool[tool] === name);
+      return tools.length === 0 ? [] : [defineSkill({ ...skills[name], tools, always: config.always.includes(name) })];
+    }),
+    promptSections: config.environmentSection && enabled.length > 0 ? [section] : []
+  });
+});

package/dist/workspace-tools.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};