@better-fs-tools/read 0.0.0-stage → 0.1.0

package/dist/formatters/layout.js

@@ -0,0 +1,33 @@
+export function defaultNoteLine(note) {
+    return `[read:${note.code}] ${note.message}`;
+}
+export function layout(outcome, ctx, body, options) {
+    if (ctx.mode === "view")
+        return body;
+    const header = options.header?.(outcome, ctx) ?? null;
+    const footer = options.footer?.(outcome, ctx) ?? null;
+    const main = [header, body, footer].filter((part) => part !== null && part !== "").join("\n");
+    return join(main, noteLines(outcome.notes, options));
+}
+export function noteLines(notes, options) {
+    const filter = options.notes ?? ((note) => note);
+    const line = options.noteLine ?? defaultNoteLine;
+    const lines = [];
+    for (const note of notes) {
+        const shown = filter(note);
+        if (shown !== null)
+            lines.push(line(shown));
+    }
+    return lines;
+}
+export function join(main, lines) {
+    const notes = lines.join("\n");
+    if (main && notes)
+        return `${main}\n\n${notes}`;
+    return main || notes;
+}
+export function withParts(outcome, text) {
+    if (outcome.status !== "media")
+        return text;
+    return text === "" ? [...outcome.parts] : [{ type: "text", text }, ...outcome.parts];
+}

package/dist/formatters/line-number.d.ts

@@ -0,0 +1,11 @@
+import type { ReadFormatContext, ReadFormatter } from "../contract/format.ts";
+import type { ReadLine } from "../contract/result.ts";
+import type { LayoutOptions } from "./layout.ts";
+export interface LineNumberFormatterOptions extends LayoutOptions {
+    /** Default: `${line.number}|`. */
+    gutter?: (line: ReadLine, ctx: ReadFormatContext<unknown>) => string;
+    /** Default: `… [line truncated at ${n} chars]`. */
+    clampMarker?: (line: ReadLine) => string;
+}
+/** Numbered lines, then notes. A media outcome gives a text part with the notes, then the media parts. */
+export declare function lineNumberFormatter(options?: LineNumberFormatterOptions): ReadFormatter<unknown>;

package/dist/formatters/line-number.js

@@ -0,0 +1,23 @@
+import { layout, withParts } from "./layout.js";
+/** Numbered lines, then notes. A media outcome gives a text part with the notes, then the media parts. */
+export function lineNumberFormatter(options = {}) {
+    const gutter = options.gutter ?? defaultGutter;
+    const clampMarker = options.clampMarker ?? defaultClampMarker;
+    return Object.freeze({
+        id: "line-number",
+        format(outcome, ctx) {
+            const body = outcome.status === "ok"
+                ? outcome.view.lines
+                    .map((line) => `${gutter(line, ctx)}${line.text}${line.clamped ? clampMarker(line) : ""}`)
+                    .join("\n")
+                : "";
+            return withParts(outcome, layout(outcome, ctx, body, options));
+        },
+    });
+}
+function defaultGutter(line) {
+    return `${line.number}|`;
+}
+function defaultClampMarker(line) {
+    return `… [line truncated at ${line.text.length} chars]`;
+}

package/dist/formatters/plain.d.ts

@@ -0,0 +1,7 @@
+import type { ReadFormatter } from "../contract/format.ts";
+import type { LineNumberFormatterOptions } from "./line-number.ts";
+/**
+ * Source text with no gutter and no clamp marker, then notes. It trades line
+ * numbers for exact text, for hosts whose model pastes output into an edit call.
+ */
+export declare function plainFormatter(options?: Omit<LineNumberFormatterOptions, "gutter" | "clampMarker">): ReadFormatter<unknown>;

package/dist/formatters/plain.js

@@ -0,0 +1,14 @@
+import { layout, withParts } from "./layout.js";
+/**
+ * Source text with no gutter and no clamp marker, then notes. It trades line
+ * numbers for exact text, for hosts whose model pastes output into an edit call.
+ */
+export function plainFormatter(options = {}) {
+    return Object.freeze({
+        id: "plain",
+        format(outcome, ctx) {
+            const body = outcome.status === "ok" ? outcome.view.lines.map((line) => line.text).join("\n") : "";
+            return withParts(outcome, layout(outcome, ctx, body, options));
+        },
+    });
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { redact } from "./redact.ts";
+export type { RedactOptions } from "./redact.ts";
+export { repeatReadGuard } from "./repeat-read-guard.ts";
+export type { RepeatReadGuardOptions } from "./repeat-read-guard.ts";

package/dist/hooks/index.js

@@ -0,0 +1,2 @@
+export { redact } from "./redact.js";
+export { repeatReadGuard } from "./repeat-read-guard.js";

package/dist/hooks/redact.d.ts

@@ -0,0 +1,14 @@
+import type { ReadHook } from "../contract/extensions.ts";
+export interface RedactOptions {
+    /** Each pattern must have the "g" flag. */
+    patterns: readonly RegExp[];
+    /** Default "[REDACTED]". Inserted as is: "$" has no special meaning. */
+    replacement?: string;
+}
+/**
+ * Replaces matches in view line text and in text parts. A match must lie
+ * inside one line, and a clamped line holds only its first
+ * limits.maxCharsPerLine characters. When nothing matches, the outcome is
+ * unchanged and gets no view-modified note.
+ */
+export declare function redact(options: RedactOptions): ReadHook<unknown>;

package/dist/hooks/redact.js

@@ -0,0 +1,53 @@
+const ENCODER = new TextEncoder();
+/**
+ * Replaces matches in view line text and in text parts. A match must lie
+ * inside one line, and a clamped line holds only its first
+ * limits.maxCharsPerLine characters. When nothing matches, the outcome is
+ * unchanged and gets no view-modified note.
+ */
+export function redact(options) {
+    const { patterns, replacement = "[REDACTED]" } = options ?? {};
+    if (!Array.isArray(patterns))
+        throw new TypeError("redact patterns must be an array");
+    for (const pattern of patterns) {
+        if (!(pattern instanceof RegExp) || !pattern.flags.includes("g")) {
+            throw new TypeError(`redact pattern ${String(pattern)} must be a RegExp with the "g" flag`);
+        }
+    }
+    if (typeof replacement !== "string")
+        throw new TypeError("redact replacement must be a string");
+    const list = Object.freeze([...patterns]);
+    const scrub = (text) => list.reduce((current, pattern) => current.replace(pattern, () => replacement), text);
+    return Object.freeze({
+        id: "redact",
+        afterRead(outcome) {
+            if (outcome.status === "ok") {
+                const lines = outcome.view.lines.map((line) => {
+                    const text = scrub(line.text);
+                    return text === line.text ? line : { ...line, text };
+                });
+                if (lines.every((line, index) => line === outcome.view.lines[index]))
+                    return outcome;
+                return { ...outcome, view: { ...outcome.view, lines, bytes: viewBytes(lines) } };
+            }
+            if (outcome.status === "media") {
+                const parts = outcome.parts.map((part) => {
+                    if (part.type !== "text")
+                        return part;
+                    const text = scrub(part.text);
+                    return text === part.text ? part : { ...part, text };
+                });
+                if (parts.every((part, index) => part === outcome.parts[index]))
+                    return outcome;
+                return { ...outcome, parts };
+            }
+            return outcome;
+        },
+    });
+}
+function viewBytes(lines) {
+    let total = Math.max(0, lines.length - 1);
+    for (const line of lines)
+        total += ENCODER.encode(line.text).byteLength;
+    return total;
+}

package/dist/hooks/repeat-read-guard.d.ts

@@ -0,0 +1,13 @@
+import type { ReadHook } from "../contract/extensions.ts";
+import type { ReadRecord } from "../contract/state.ts";
+export interface RepeatReadGuardOptions {
+    /** The repeat-read note text. Default: names the path and when it was read. */
+    message?: (previous: ReadRecord) => string;
+}
+/**
+ * Empties the view and adds a "repeat-read" note when the same range of the
+ * same content was already read. Needs a digest and a state store. A record a
+ * write tool stored does not count. The stored record then says the whole file
+ * was not visible.
+ */
+export declare function repeatReadGuard(options?: RepeatReadGuardOptions): ReadHook<unknown>;

package/dist/hooks/repeat-read-guard.js

@@ -0,0 +1,49 @@
+/**
+ * Empties the view and adds a "repeat-read" note when the same range of the
+ * same content was already read. Needs a digest and a state store. A record a
+ * write tool stored does not count. The stored record then says the whole file
+ * was not visible.
+ */
+export function repeatReadGuard(options = {}) {
+    const { message } = options ?? {};
+    if (message !== undefined && typeof message !== "function") {
+        throw new TypeError("repeatReadGuard message must be a function");
+    }
+    return Object.freeze({
+        id: "repeat-read-guard",
+        afterRead(outcome, ctx) {
+            const { previous } = ctx;
+            if (outcome.status !== "ok" ||
+                outcome.observation === null ||
+                previous === null ||
+                previous.origin !== "read" ||
+                previous.request === null) {
+                return outcome;
+            }
+            const { contentId } = outcome.observation;
+            const { request, view } = outcome;
+            if (contentId === null ||
+                previous.contentId !== contentId ||
+                previous.request.offset !== request.offset ||
+                previous.request.limit !== request.limit ||
+                view.lines.length === 0) {
+                return outcome;
+            }
+            return {
+                ...outcome,
+                view: { ...view, lines: [], endLine: view.startLine - 1, bytes: 0, partial: true },
+                notes: [
+                    ...outcome.notes,
+                    {
+                        code: "repeat-read",
+                        severity: "info",
+                        message: message === undefined
+                            ? `${request.path} has not changed since it was read with the same range at ${previous.observedAt}. That output is still current, so it is not repeated.`
+                            : message(previous),
+                        data: { observationId: previous.observationId, observedAt: previous.observedAt },
+                    },
+                ],
+            };
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export type { Classification, ClassificationSample, Classifier } from "./contract/classify.ts";
+export type { BuiltInUnsupportedCode, DefaultClassifierOptions, NoteContext, NoteOverride, TextClassification, UnsupportedClassification, } from "./contract/classify.ts";
+export type { AccessDecision, AccessTarget, Note, SignatureDocs, ToolAuthorizer, ToolCallContext, ToolError, ToolHookContext, ToolMessages, ToolName, ToolResolveContext, ToolSignature, } from "./contract/base.ts";
+export type { ReadContext, ReadTool } from "./contract/context.ts";
+export type { ReadDependencies, ReadToolDeps, StateNeedsDigest, StateNeedsDigestOrDefault, } from "./contract/deps.ts";
+export type { Clock, Digest, DigestStream } from "./contract/digest.ts";
+export type { AfterReadContext, Converter, ConverterMatch, ConvertOutcome, DirectoryConverter, DirectoryConvertInput, FileConverter, FileConvertInput, PathResolver, ReadAuthorizeDecision, ReadAuthorizer, ReadAuthorizeTarget, ReadHook, ReadHookContext, ReadResolveContext, ResolveOutcome, Suggest, SuggestContext, ViewBudget, } from "./contract/extensions.ts";
+export type { ReadFormatContext, ReadFormatter } from "./contract/format.ts";
+export type { ReadInput, ReadRequest } from "./contract/input.ts";
+export type { JsonObject, JsonValue } from "./contract/json.ts";
+export type { ReadLimits } from "./contract/limits.ts";
+export type { ReadMessageCatalog, ReadPhase } from "./contract/messages.ts";
+export type { ClassificationInfo, Confidence, ContentPart, ConversionInfo, FileInfo, MediaPart, ReadContinuation, ReadError, ReadErrorCode, ReadFailure, ReadLine, ReadMedia, ReadNote, ReadObservation, ReadOk, ReadReport, ReadResult, ReadTotals, ReadTruncation, ReadUnsupported, ReadView, TextPart, TruncationReason, } from "./contract/result.ts";
+export type { ReadRecord, ReadStateStore } from "./contract/state.ts";
+export { createReadTool } from "./core/create-read-tool.ts";
+export { parseReadInput } from "./core/input.ts";
+export { defaultReadLimits, resolveReadLimits } from "./core/limits.ts";
+export { defaultReadMessages, resolveReadMessages } from "./core/messages.ts";
+export { textOf } from "./core/format.ts";
+export { sha256Digest } from "./digest/sha256.ts";
+export { memoryStore } from "./state/index.ts";
+export type { MemoryStoreOptions } from "./state/index.ts";
+export { binaryClassifier, defaultClassifiers, extensionClassifier, imageClassifier, notebookClassifier, officeClassifier, pdfClassifier, utf8Classifier, } from "./classifiers/index.ts";
+export type { ExtensionClassifierOptions } from "./classifiers/index.ts";
+export { askUser, compileGlob, denyPaths, readAuthorizers, sizeCeiling, } from "./authorize/index.ts";
+export { directoryListing, imageConverter, notebookConverter, textConverter, } from "./converters/index.ts";
+export type { DirectoryListingOptions, ImageConverterOptions, NotebookConverterOptions, TextConverterOptions, } from "./converters/index.ts";
+export { expandHome, pathResolvers, reanchorLeadingSlash, stripPrefixes, unicodeRepair, } from "./resolve/index.ts";
+export { redact, repeatReadGuard } from "./hooks/index.ts";
+export type { RedactOptions, RepeatReadGuardOptions } from "./hooks/index.ts";
+export { charsPerToken } from "./budget/index.ts";
+export type { CharsPerTokenOptions } from "./budget/index.ts";
+export { canonicalizeFileName, defaultSuggest, suggestFileNames } from "./suggest/index.ts";
+export { defaultNoteLine, eofFooter, fileHashHeader, hashlineGutter, jsonFormatter, lineNumberFormatter, plainFormatter, } from "./formatters/index.ts";
+export type { HashlineGutterOptions, JsonFormatterOptions, LineNumberFormatterOptions, } from "./formatters/index.ts";

package/dist/index.js

@@ -0,0 +1,15 @@
+export { createReadTool } from "./core/create-read-tool.js";
+export { parseReadInput } from "./core/input.js";
+export { defaultReadLimits, resolveReadLimits } from "./core/limits.js";
+export { defaultReadMessages, resolveReadMessages } from "./core/messages.js";
+export { textOf } from "./core/format.js";
+export { sha256Digest } from "./digest/sha256.js";
+export { memoryStore } from "./state/index.js";
+export { binaryClassifier, defaultClassifiers, extensionClassifier, imageClassifier, notebookClassifier, officeClassifier, pdfClassifier, utf8Classifier, } from "./classifiers/index.js";
+export { askUser, compileGlob, denyPaths, readAuthorizers, sizeCeiling, } from "./authorize/index.js";
+export { directoryListing, imageConverter, notebookConverter, textConverter, } from "./converters/index.js";
+export { expandHome, pathResolvers, reanchorLeadingSlash, stripPrefixes, unicodeRepair, } from "./resolve/index.js";
+export { redact, repeatReadGuard } from "./hooks/index.js";
+export { charsPerToken } from "./budget/index.js";
+export { canonicalizeFileName, defaultSuggest, suggestFileNames } from "./suggest/index.js";
+export { defaultNoteLine, eofFooter, fileHashHeader, hashlineGutter, jsonFormatter, lineNumberFormatter, plainFormatter, } from "./formatters/index.js";

package/dist/resolve/expand-home.d.ts

@@ -0,0 +1,5 @@
+import type { PathResolver } from "../contract/base.ts";
+/** Expands "~" and "~/x" to `home`. Other "~user" forms pass through unchanged. */
+export declare function expandHome(options: {
+    home: string;
+}): PathResolver<unknown>;

package/dist/resolve/expand-home.js

@@ -0,0 +1,17 @@
+/** Expands "~" and "~/x" to `home`. Other "~user" forms pass through unchanged. */
+export function expandHome(options) {
+    const home = options?.home;
+    if (typeof home !== "string" || home === "") {
+        throw new TypeError("expandHome needs a non-empty home");
+    }
+    return Object.freeze({
+        id: "expand-home",
+        resolve(path, ctx) {
+            if (path === "~" || path === "~/")
+                return { kind: "path", path: home };
+            if (!path.startsWith("~/"))
+                return { kind: "path", path };
+            return { kind: "path", path: ctx.paths.join(home, path.slice(2)) };
+        },
+    });
+}

package/dist/resolve/index.d.ts

@@ -0,0 +1,5 @@
+export { expandHome } from "./expand-home.ts";
+export { pathResolvers } from "./path-resolvers.ts";
+export { reanchorLeadingSlash } from "./reanchor-leading-slash.ts";
+export { stripPrefixes } from "./strip-prefixes.ts";
+export { unicodeRepair } from "./unicode-repair.ts";

package/dist/resolve/index.js

@@ -0,0 +1,5 @@
+export { expandHome } from "./expand-home.js";
+export { pathResolvers } from "./path-resolvers.js";
+export { reanchorLeadingSlash } from "./reanchor-leading-slash.js";
+export { stripPrefixes } from "./strip-prefixes.js";
+export { unicodeRepair } from "./unicode-repair.js";

package/dist/resolve/path-resolvers.d.ts

@@ -0,0 +1,7 @@
+import type { PathResolver } from "../contract/base.ts";
+/**
+ * Runs resolvers left to right, each on the previous path. The first not-found
+ * stops the chain. All steps share one ctx.list budget, and the last note wins.
+ * A step that throws fails the read with EXTENSION_FAILED, naming the step's id.
+ */
+export declare function pathResolvers<THost = unknown>(...steps: readonly PathResolver<NoInfer<THost>>[]): PathResolver<THost>;

package/dist/resolve/path-resolvers.js

@@ -0,0 +1,38 @@
+import { stepFailure } from "../core/extension-error.js";
+/**
+ * Runs resolvers left to right, each on the previous path. The first not-found
+ * stops the chain. All steps share one ctx.list budget, and the last note wins.
+ * A step that throws fails the read with EXTENSION_FAILED, naming the step's id.
+ */
+export function pathResolvers(...steps) {
+    for (const step of steps) {
+        if (step === null || typeof step !== "object" || typeof step.resolve !== "function") {
+            throw new TypeError("pathResolvers takes path resolvers");
+        }
+    }
+    const chain = Object.freeze([...steps]);
+    return Object.freeze({
+        id: chain.length === 0 ? "identity" : chain.map((step) => step.id).join("+"),
+        async resolve(path, ctx) {
+            let current = path;
+            let note;
+            for (const step of chain) {
+                let outcome;
+                try {
+                    outcome = await step.resolve(current, ctx);
+                    note = outcome.note ?? note;
+                }
+                catch (error) {
+                    throw stepFailure(step, error);
+                }
+                if (outcome.kind === "not-found") {
+                    return note === undefined ? { kind: "not-found" } : { kind: "not-found", note };
+                }
+                current = outcome.path;
+            }
+            return note === undefined
+                ? { kind: "path", path: current }
+                : { kind: "path", path: current, note };
+        },
+    });
+}

package/dist/resolve/reanchor-leading-slash.d.ts

@@ -0,0 +1,9 @@
+import type { PathResolver } from "../contract/base.ts";
+/**
+ * Rewrites "/src/x.ts" to "src/x.ts" when `firstSegmentExists("src")` is true.
+ * It should return true only for a segment that exists under the tool root and
+ * not at "/".
+ */
+export declare function reanchorLeadingSlash(options: {
+    firstSegmentExists: (segment: string) => boolean;
+}): PathResolver<unknown>;

package/dist/resolve/reanchor-leading-slash.js

@@ -0,0 +1,23 @@
+/**
+ * Rewrites "/src/x.ts" to "src/x.ts" when `firstSegmentExists("src")` is true.
+ * It should return true only for a segment that exists under the tool root and
+ * not at "/".
+ */
+export function reanchorLeadingSlash(options) {
+    const exists = options?.firstSegmentExists;
+    if (typeof exists !== "function") {
+        throw new TypeError("reanchorLeadingSlash needs a firstSegmentExists function");
+    }
+    return Object.freeze({
+        id: "reanchor-leading-slash",
+        resolve(path) {
+            if (!path.startsWith("/") || path.startsWith("//"))
+                return { kind: "path", path };
+            const rest = path.slice(1);
+            const segment = rest.split("/", 1)[0] ?? "";
+            if (segment === "" || !exists(segment))
+                return { kind: "path", path };
+            return { kind: "path", path: rest };
+        },
+    });
+}

package/dist/resolve/strip-prefixes.d.ts

@@ -0,0 +1,6 @@
+import type { PathResolver } from "../contract/base.ts";
+/** Strips "file://" (percent-decoded) and a leading "@". Both default true. */
+export declare function stripPrefixes(options?: {
+    fileUrl?: boolean;
+    at?: boolean;
+}): PathResolver<unknown>;

package/dist/resolve/strip-prefixes.js

@@ -0,0 +1,30 @@
+const FILE_URL = "file://";
+/** Strips "file://" (percent-decoded) and a leading "@". Both default true. */
+export function stripPrefixes(options = {}) {
+    const fileUrl = options.fileUrl ?? true;
+    const at = options.at ?? true;
+    return Object.freeze({
+        id: "strip-prefixes",
+        resolve(path) {
+            let next = path;
+            if (fileUrl && next.startsWith(FILE_URL))
+                next = fromFileUrl(next) ?? next;
+            if (at && next.length > 1 && next.startsWith("@"))
+                next = next.slice(1);
+            return { kind: "path", path: next };
+        },
+    });
+}
+function fromFileUrl(url) {
+    let rest = url.slice(FILE_URL.length);
+    if (rest.startsWith("localhost/"))
+        rest = rest.slice("localhost".length);
+    let decoded;
+    try {
+        decoded = decodeURIComponent(rest);
+    }
+    catch {
+        return null;
+    }
+    return decoded.trim() === "" || decoded.includes("\0") ? null : decoded;
+}

package/dist/resolve/unicode-repair.d.ts

@@ -0,0 +1,9 @@
+import type { PathResolver } from "../contract/base.ts";
+/**
+ * Repairs a file name that matches exactly one entry in its directory up to
+ * Unicode equivalence. An exact match, several matches, or a failed listing
+ * leave the path unchanged. `note` (default true) adds a path-repaired note.
+ */
+export declare function unicodeRepair(options?: {
+    note?: boolean;
+}): PathResolver<unknown>;

package/dist/resolve/unicode-repair.js

@@ -0,0 +1,38 @@
+import { canonicalizeFileName } from "../suggest/canonicalize.js";
+/**
+ * Repairs a file name that matches exactly one entry in its directory up to
+ * Unicode equivalence. An exact match, several matches, or a failed listing
+ * leave the path unchanged. `note` (default true) adds a path-repaired note.
+ */
+export function unicodeRepair(options = {}) {
+    const withNote = options.note ?? true;
+    return Object.freeze({
+        id: "unicode-repair",
+        async resolve(path, ctx) {
+            const dir = ctx.paths.dirname(path);
+            const name = ctx.paths.basename(path);
+            const listed = await ctx.list(dir);
+            if (!listed.ok || listed.entries.some((entry) => entry.name === name)) {
+                return { kind: "path", path };
+            }
+            const canonical = canonicalizeFileName(name);
+            const matches = listed.entries.filter((entry) => canonicalizeFileName(entry.name) === canonical);
+            const [match] = matches;
+            if (matches.length !== 1 || match === undefined)
+                return { kind: "path", path };
+            const repaired = ctx.paths.join(dir, match.name);
+            if (!withNote)
+                return { kind: "path", path: repaired };
+            return {
+                kind: "path",
+                path: repaired,
+                note: {
+                    code: "path-repaired",
+                    severity: "warning",
+                    message: ctx.messages.pathRepaired({ from: path, to: repaired }),
+                    data: { from: path, to: repaired },
+                },
+            };
+        },
+    });
+}

package/dist/signature/contract.d.ts

@@ -0,0 +1,18 @@
+import type { ToolSignature } from "../contract/base.ts";
+import type { ReadInput } from "../contract/input.ts";
+import type { JsonObject } from "../contract/json.ts";
+/** The read tool's signature. `fromInput` lets notes tell the model how to continue. */
+export interface ReadSignature<TModel extends JsonObject = JsonObject> extends ToolSignature<ReadInput, ReadParam> {
+    /** Maps a canonical retry to the object the model sends next. */
+    fromInput(retry: ReadInput): TModel;
+}
+/** The canonical read parameters, and the parameter names of `defaultReadSignature`. */
+export type ReadParam = "path" | "offset" | "limit";
+/** The parameter names of `lineRangeSignature`. */
+export type LineRangeParam = "path" | "start" | "end";
+/** The model input of `defaultReadSignature`. */
+export type DefaultReadModelInput = {
+    readonly path: string;
+    readonly offset?: number;
+    readonly limit?: number;
+};

package/dist/signature/index.d.ts

@@ -0,0 +1,4 @@
+export type { DefaultReadModelInput, LineRangeParam, ReadParam, ReadSignature, } from "./contract.ts";
+export { lineRangeSignature } from "./line-range.ts";
+export { readSignatureMessages } from "./messages.ts";
+export { defaultReadSignature } from "./offset-limit.ts";

package/dist/signature/index.js

@@ -0,0 +1,3 @@
+export { lineRangeSignature } from "./line-range.js";
+export { readSignatureMessages } from "./messages.js";
+export { defaultReadSignature } from "./offset-limit.js";

package/dist/signature/line-range.d.ts

@@ -0,0 +1,7 @@
+import type { SignatureDocs } from "../contract/base.ts";
+import type { LineRangeParam, ReadSignature } from "./contract.ts";
+/**
+ * A read({ path, start?, end? }) signature with one-based, inclusive start and
+ * end lines. param("limit") is "", because no parameter holds a line count.
+ */
+export declare function lineRangeSignature(options?: SignatureDocs<LineRangeParam>): ReadSignature;

package/dist/signature/line-range.js

@@ -0,0 +1,59 @@
+import { canonical } from "./offset-limit.js";
+import { DEFAULT_NAME, lineSchema, objectSchema, pathSchema, readLine, readObject, readPath, resolveNames, } from "./schema.js";
+const PARAMS = ["path", "start", "end"];
+/**
+ * A read({ path, start?, end? }) signature with one-based, inclusive start and
+ * end lines. param("limit") is "", because no parameter holds a line count.
+ */
+export function lineRangeSignature(options = {}) {
+    if (options === null || typeof options !== "object") {
+        throw new TypeError("lineRangeSignature options must be an object");
+    }
+    const name = resolveNames(PARAMS, options.names);
+    const keys = PARAMS.map((param) => name[param]);
+    const describe = options.describe ?? {};
+    const schema = objectSchema([
+        [
+            name.path,
+            pathSchema(describe.path ??
+                "Path to read, relative to the working directory or absolute within an allowed root."),
+        ],
+        [name.start, lineSchema(describe.start ?? "First one-based line to read. Defaults to 1.")],
+        [
+            name.end,
+            lineSchema(describe.end ??
+                `Last line to read, inclusive. Must not be less than ${name.start}. Defaults to the end of the view limits.`),
+        ],
+    ], name.path);
+    return Object.freeze({
+        name: options.name ?? DEFAULT_NAME,
+        description: options.description ??
+            `Read a UTF-8 text file. \`${name.start}\` and \`${name.end}\` are one-based, inclusive ` +
+                "source lines. Output is bounded by line, byte, and line-length limits. When the result " +
+                "reports truncation, follow the continuation it returns instead of guessing the next " +
+                "range. Paths outside the allowed roots, binary content, and special files are refused.",
+        schema,
+        toInput(input) {
+            const record = readObject(input, keys);
+            const path = readPath(record[name.path], name.path);
+            const start = readLine(record[name.start], name.start);
+            const end = readLine(record[name.end], name.end);
+            if (end === undefined)
+                return canonical(path, start);
+            const first = start ?? 1;
+            if (end < first) {
+                throw new TypeError(`${name.end} (${end}) must not be less than ${name.start} (${first})`);
+            }
+            return canonical(path, start, end - first + 1);
+        },
+        param: (canonical) => canonical === "path" ? name.path : canonical === "offset" ? name.start : "",
+        fromInput(retry) {
+            const model = { [name.path]: retry.path };
+            if (retry.offset !== undefined)
+                model[name.start] = retry.offset;
+            if (retry.limit !== undefined)
+                model[name.end] = (retry.offset ?? 1) + retry.limit - 1;
+            return model;
+        },
+    });
+}

package/dist/signature/messages.d.ts

@@ -0,0 +1,4 @@
+import type { ReadMessageCatalog } from "../contract/messages.ts";
+import type { ReadSignature } from "./contract.ts";
+/** Retry text in the signature's own names. Merge it under the host's messages. */
+export declare function readSignatureMessages(signature: ReadSignature): Pick<ReadMessageCatalog, "retry">;

package/dist/signature/messages.js

@@ -0,0 +1,9 @@
+/** Retry text in the signature's own names. Merge it under the host's messages. */
+export function readSignatureMessages(signature) {
+    if (signature === null ||
+        typeof signature !== "object" ||
+        typeof signature.fromInput !== "function") {
+        throw new TypeError("readSignatureMessages needs a ReadSignature");
+    }
+    return Object.freeze({ retry: (next) => JSON.stringify(signature.fromInput(next)) });
+}

package/dist/signature/offset-limit.d.ts

@@ -0,0 +1,13 @@
+import type { ReadInput } from "../contract/input.ts";
+import type { SignatureDocs } from "../contract/base.ts";
+import type { DefaultReadModelInput, ReadParam, ReadSignature } from "./contract.ts";
+/**
+ * A read({ path, offset?, limit? }) signature: a non-blank path without NUL,
+ * and positive integer offset and limit. `names` renames any of the three
+ * parameters.
+ */
+export declare function defaultReadSignature(options?: SignatureDocs<ReadParam> & {
+    readonly names?: undefined;
+}): ReadSignature<DefaultReadModelInput>;
+export declare function defaultReadSignature(options: SignatureDocs<ReadParam>): ReadSignature;
+export declare function canonical(path: string, offset?: number, limit?: number): ReadInput;