@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/dist/esm/internal/CodexText.js

@@ -0,0 +1,156 @@
+/**
+ * Faithful port of Codex CLI output truncation.
+ *
+ * Mirrors `codex-rs/utils/string/src/truncate.rs` and
+ * `codex-rs/utils/output-truncation/src/lib.rs`: middle truncation on UTF-8
+ * boundaries with a `…{n} tokens truncated…` marker and a 4-bytes-per-token
+ * estimate, so ChatGPT-family models see the exact shapes they were
+ * posttrained on.
+ *
+ * @since 1.0.0
+ */
+const APPROX_BYTES_PER_TOKEN = 4;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * UTF-8 byte length of a string.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const byteLength = (text) => encoder.encode(text).byteLength;
+/**
+ * Approximate token count: ceil(utf8Bytes / 4).
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const approxTokenCount = (text) => Math.floor((byteLength(text) + APPROX_BYTES_PER_TOKEN - 1) / APPROX_BYTES_PER_TOKEN);
+/**
+ * Approximate byte budget for a token budget.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const approxBytesForTokens = (tokens) => tokens * APPROX_BYTES_PER_TOKEN;
+/**
+ * Approximate tokens represented by a byte count: ceil(bytes / 4).
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const approxTokensFromByteCount = (bytes) => Math.floor((bytes + APPROX_BYTES_PER_TOKEN - 1) / APPROX_BYTES_PER_TOKEN);
+const formatTruncationMarker = (useTokens, removedCount) => useTokens ? `…${removedCount} tokens truncated…` : `…${removedCount} chars truncated…`;
+/** A UTF-8 continuation byte is `10xxxxxx`; every other byte starts a character. */
+const isContinuation = (byte) => (byte & 0b1100_0000) === 0b1000_0000;
+/** The last character boundary at or before `offset`. */
+const boundaryAtOrBefore = (bytes, offset) => {
+    let at = Math.min(offset, bytes.byteLength);
+    while (at > 0 && at < bytes.byteLength && isContinuation(bytes[at]))
+        at--;
+    return at;
+};
+/** The first character boundary at or after `offset`. */
+const boundaryAtOrAfter = (bytes, offset) => {
+    let at = Math.max(offset, 0);
+    while (at < bytes.byteLength && isContinuation(bytes[at]))
+        at++;
+    return at;
+};
+/**
+ * Splits `s` into the head that fits `beginningBytes` and the tail that fits
+ * `endBytes`, both cut on UTF-8 character boundaries, and counts the characters
+ * dropped between them.
+ *
+ * The boundaries are read off the encoded bytes rather than by re-encoding one
+ * character at a time: a per-character `TextEncoder.encode` costs about two
+ * microseconds, which is nineteen seconds for the eight megabytes a bounded
+ * capture can hand this function.
+ */
+const splitString = (s, beginningBytes, endBytes) => {
+    const bytes = encoder.encode(s);
+    const tailStartTarget = Math.max(bytes.byteLength - endBytes, 0);
+    const prefixEnd = boundaryAtOrBefore(bytes, beginningBytes);
+    const suffixStart = boundaryAtOrAfter(bytes, Math.max(tailStartTarget, prefixEnd));
+    let removedChars = 0;
+    for (let at = prefixEnd; at < suffixStart; at++)
+        if (!isContinuation(bytes[at]))
+            removedChars++;
+    return {
+        removedChars,
+        before: decoder.decode(bytes.subarray(0, prefixEnd)),
+        after: decoder.decode(bytes.subarray(suffixStart))
+    };
+};
+const truncateWithByteEstimate = (s, maxBytes, useTokens) => {
+    if (s === "")
+        return "";
+    const totalBytes = byteLength(s);
+    if (maxBytes === 0) {
+        return formatTruncationMarker(useTokens, useTokens ? approxTokensFromByteCount(totalBytes) : [...s].length);
+    }
+    if (totalBytes <= maxBytes)
+        return s;
+    const leftBudget = Math.floor(maxBytes / 2);
+    const rightBudget = maxBytes - leftBudget;
+    const { after, before, removedChars } = splitString(s, leftBudget, rightBudget);
+    const marker = formatTruncationMarker(useTokens, useTokens ? approxTokensFromByteCount(Math.max(totalBytes - maxBytes, 0)) : removedChars);
+    return `${before}${marker}${after}`;
+};
+/**
+ * Middle-truncate to a byte budget with a char-count marker.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const truncateMiddleChars = (s, maxBytes) => truncateWithByteEstimate(s, maxBytes, false);
+/**
+ * Middle-truncate to an approximate token budget, preserving the beginning
+ * and end. Returns the possibly truncated string and the original token
+ * count when truncation occurred.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const truncateMiddleWithTokenBudget = (s, maxTokens) => {
+    if (s === "")
+        return { text: "", originalTokenCount: undefined };
+    if (maxTokens > 0 && byteLength(s) <= approxBytesForTokens(maxTokens)) {
+        return { text: s, originalTokenCount: undefined };
+    }
+    const truncated = truncateWithByteEstimate(s, approxBytesForTokens(maxTokens), true);
+    if (truncated === s)
+        return { text: s, originalTokenCount: undefined };
+    return { text: truncated, originalTokenCount: approxTokenCount(s) };
+};
+const countLines = (content) => {
+    if (content === "")
+        return 0;
+    const parts = content.split("\n");
+    return parts[parts.length - 1] === "" ? parts.length - 1 : parts.length;
+};
+/**
+ * Codex `format_exec_output_for_model`: exit code, wall time, optional line
+ * count disclosure, then the (possibly middle-truncated) output.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const formatExecOutputForModel = (options) => {
+    const content = options.timedOutAfterMs === undefined
+        ? options.output
+        : `command timed out after ${options.timedOutAfterMs} milliseconds\n${options.output}`;
+    const durationSeconds = Math.round(options.durationSeconds * 10) / 10;
+    const totalLines = countLines(content);
+    const formatted = truncateMiddleWithTokenBudget(content, options.maxOutputTokens).text;
+    const sections = [
+        `Exit code: ${options.exitCode}`,
+        `Wall time: ${durationSeconds} seconds`
+    ];
+    if (totalLines !== countLines(formatted))
+        sections.push(`Total output lines: ${totalLines}`);
+    sections.push("Output:");
+    sections.push(formatted);
+    return sections.join("\n");
+};
+//# sourceMappingURL=CodexText.js.map

package/dist/esm/internal/CodexText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodexText.js","sourceRoot":"","sources":["../../../src/internal/CodexText.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Faithful port of Codex CLI output truncation.\n *\n * Mirrors `codex-rs/utils/string/src/truncate.rs` and\n * `codex-rs/utils/output-truncation/src/lib.rs`: middle truncation on UTF-8\n * boundaries with a `…{n} tokens truncated…` marker and a 4-bytes-per-token\n * estimate, so ChatGPT-family models see the exact shapes they were\n * posttrained on.\n *\n * @since 1.0.0\n */\n\nconst APPROX_BYTES_PER_TOKEN = 4\n\nconst encoder = new TextEncoder()\nconst decoder = new TextDecoder()\n\n/**\n * UTF-8 byte length of a string.\n *\n * @since 1.0.0\n * @private\n */\nexport const byteLength = (text: string): number => encoder.encode(text).byteLength\n\n/**\n * Approximate token count: ceil(utf8Bytes / 4).\n *\n * @since 1.0.0\n * @private\n */\nexport const approxTokenCount = (text: string): number =>\n  Math.floor((byteLength(text) + APPROX_BYTES_PER_TOKEN - 1) / APPROX_BYTES_PER_TOKEN)\n\n/**\n * Approximate byte budget for a token budget.\n *\n * @since 1.0.0\n * @private\n */\nexport const approxBytesForTokens = (tokens: number): number => tokens * APPROX_BYTES_PER_TOKEN\n\n/**\n * Approximate tokens represented by a byte count: ceil(bytes / 4).\n *\n * @since 1.0.0\n * @private\n */\nexport const approxTokensFromByteCount = (bytes: number): number =>\n  Math.floor((bytes + APPROX_BYTES_PER_TOKEN - 1) / APPROX_BYTES_PER_TOKEN)\n\nconst formatTruncationMarker = (useTokens: boolean, removedCount: number): string =>\n  useTokens ? `…${removedCount} tokens truncated…` : `…${removedCount} chars truncated…`\n\ninterface Split {\n  readonly removedChars: number\n  readonly before: string\n  readonly after: string\n}\n\n/** A UTF-8 continuation byte is `10xxxxxx`; every other byte starts a character. */\nconst isContinuation = (byte: number): boolean => (byte & 0b1100_0000) === 0b1000_0000\n\n/** The last character boundary at or before `offset`. */\nconst boundaryAtOrBefore = (bytes: Uint8Array, offset: number): number => {\n  let at = Math.min(offset, bytes.byteLength)\n  while (at > 0 && at < bytes.byteLength && isContinuation(bytes[at]!)) at--\n  return at\n}\n\n/** The first character boundary at or after `offset`. */\nconst boundaryAtOrAfter = (bytes: Uint8Array, offset: number): number => {\n  let at = Math.max(offset, 0)\n  while (at < bytes.byteLength && isContinuation(bytes[at]!)) at++\n  return at\n}\n\n/**\n * Splits `s` into the head that fits `beginningBytes` and the tail that fits\n * `endBytes`, both cut on UTF-8 character boundaries, and counts the characters\n * dropped between them.\n *\n * The boundaries are read off the encoded bytes rather than by re-encoding one\n * character at a time: a per-character `TextEncoder.encode` costs about two\n * microseconds, which is nineteen seconds for the eight megabytes a bounded\n * capture can hand this function.\n */\nconst splitString = (s: string, beginningBytes: number, endBytes: number): Split => {\n  const bytes = encoder.encode(s)\n  const tailStartTarget = Math.max(bytes.byteLength - endBytes, 0)\n  const prefixEnd = boundaryAtOrBefore(bytes, beginningBytes)\n  const suffixStart = boundaryAtOrAfter(bytes, Math.max(tailStartTarget, prefixEnd))\n  let removedChars = 0\n  for (let at = prefixEnd; at < suffixStart; at++) if (!isContinuation(bytes[at]!)) removedChars++\n  return {\n    removedChars,\n    before: decoder.decode(bytes.subarray(0, prefixEnd)),\n    after: decoder.decode(bytes.subarray(suffixStart))\n  }\n}\n\nconst truncateWithByteEstimate = (s: string, maxBytes: number, useTokens: boolean): string => {\n  if (s === \"\") return \"\"\n  const totalBytes = byteLength(s)\n  if (maxBytes === 0) {\n    return formatTruncationMarker(useTokens, useTokens ? approxTokensFromByteCount(totalBytes) : [...s].length)\n  }\n  if (totalBytes <= maxBytes) return s\n  const leftBudget = Math.floor(maxBytes / 2)\n  const rightBudget = maxBytes - leftBudget\n  const { after, before, removedChars } = splitString(s, leftBudget, rightBudget)\n  const marker = formatTruncationMarker(\n    useTokens,\n    useTokens ? approxTokensFromByteCount(Math.max(totalBytes - maxBytes, 0)) : removedChars\n  )\n  return `${before}${marker}${after}`\n}\n\n/**\n * Middle-truncate to a byte budget with a char-count marker.\n *\n * @since 1.0.0\n * @private\n */\nexport const truncateMiddleChars = (s: string, maxBytes: number): string => truncateWithByteEstimate(s, maxBytes, false)\n\n/**\n * Middle-truncate to an approximate token budget, preserving the beginning\n * and end. Returns the possibly truncated string and the original token\n * count when truncation occurred.\n *\n * @since 1.0.0\n * @private\n */\nexport const truncateMiddleWithTokenBudget = (\n  s: string,\n  maxTokens: number\n): { readonly text: string; readonly originalTokenCount: number | undefined } => {\n  if (s === \"\") return { text: \"\", originalTokenCount: undefined }\n  if (maxTokens > 0 && byteLength(s) <= approxBytesForTokens(maxTokens)) {\n    return { text: s, originalTokenCount: undefined }\n  }\n  const truncated = truncateWithByteEstimate(s, approxBytesForTokens(maxTokens), true)\n  if (truncated === s) return { text: s, originalTokenCount: undefined }\n  return { text: truncated, originalTokenCount: approxTokenCount(s) }\n}\n\nconst countLines = (content: string): number => {\n  if (content === \"\") return 0\n  const parts = content.split(\"\\n\")\n  return parts[parts.length - 1] === \"\" ? parts.length - 1 : parts.length\n}\n\n/**\n * Codex `format_exec_output_for_model`: exit code, wall time, optional line\n * count disclosure, then the (possibly middle-truncated) output.\n *\n * @since 1.0.0\n * @private\n */\nexport const formatExecOutputForModel = (options: {\n  readonly output: string\n  readonly exitCode: number\n  readonly durationSeconds: number\n  readonly maxOutputTokens: number\n  readonly timedOutAfterMs?: number | undefined\n}): string => {\n  const content = options.timedOutAfterMs === undefined\n    ? options.output\n    : `command timed out after ${options.timedOutAfterMs} milliseconds\\n${options.output}`\n  const durationSeconds = Math.round(options.durationSeconds * 10) / 10\n  const totalLines = countLines(content)\n  const formatted = truncateMiddleWithTokenBudget(content, options.maxOutputTokens).text\n  const sections = [\n    `Exit code: ${options.exitCode}`,\n    `Wall time: ${durationSeconds} seconds`\n  ]\n  if (totalLines !== countLines(formatted)) sections.push(`Total output lines: ${totalLines}`)\n  sections.push(\"Output:\")\n  sections.push(formatted)\n  return sections.join(\"\\n\")\n}\n"]}

package/dist/esm/internal/Declaration.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared declaration helpers for the standard flows.
+ *
+ * @since 1.0.0
+ */
+import type * as Capability from "@smthrs/capability/Capability";
+import * as Effects from "@smthrs/core/Effects";
+/**
+ * Options accepted by {@link envelope}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface EnvelopeOptions {
+    readonly tier: "sealed" | "compensable" | "irreversible";
+    readonly mode: "hermetic" | "expected";
+    readonly reads: Iterable<string>;
+    readonly writes: Iterable<string>;
+}
+/**
+ * Builds a deterministic effect declaration for a standard flow.
+ *
+ * Every standard flow serializes on conflict: the library owns no lane
+ * partitioning of its own, so the conservative choice is the safe one.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const envelope: (options: EnvelopeOptions) => Effects.Declaration;
+/**
+ * Formats a capability request as the `action:resource` string carried on a
+ * flow declaration.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const capability: (action: Capability.Action, resource: string) => string;
+/**
+ * The read glob covering everything under one search root.
+ *
+ * `glob` and `grep` narrow their conservative `/**` declaration to the root the
+ * call actually names, and a declaration that disagreed between the two would
+ * make the same search reserve different paths depending on which flow ran it.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const rootSubtree: (root: string) => string;
+//# sourceMappingURL=Declaration.d.ts.map

package/dist/esm/internal/Declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Declaration.d.ts","sourceRoot":"","sources":["../../../src/internal/Declaration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,UAAU,MAAM,+BAA+B,CAAA;AAChE,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAA;IACxD,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAClC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,eAAe,KAAG,OAAO,CAAC,WAOxD,CAAA;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,CAAC,MAAM,EAAE,UAAU,MAAM,KAAG,MAAiC,CAAA;AAE1G;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAAiE,CAAA"}

package/dist/esm/internal/Declaration.js

@@ -0,0 +1,42 @@
+/**
+ * Shared declaration helpers for the standard flows.
+ *
+ * @since 1.0.0
+ */
+import * as Effects from "@smthrs/core/Effects";
+/**
+ * Builds a deterministic effect declaration for a standard flow.
+ *
+ * Every standard flow serializes on conflict: the library owns no lane
+ * partitioning of its own, so the conservative choice is the safe one.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const envelope = (options) => Effects.make({
+    reads: options.reads,
+    writes: options.writes,
+    mode: options.mode,
+    onConflict: "serialize",
+    tier: options.tier
+});
+/**
+ * Formats a capability request as the `action:resource` string carried on a
+ * flow declaration.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const capability = (action, resource) => `${action}:${resource}`;
+/**
+ * The read glob covering everything under one search root.
+ *
+ * `glob` and `grep` narrow their conservative `/**` declaration to the root the
+ * call actually names, and a declaration that disagreed between the two would
+ * make the same search reserve different paths depending on which flow ran it.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const rootSubtree = (root) => root === "/" ? "/**" : `${root.replace(/\/+$/, "")}/**`;
+//# sourceMappingURL=Declaration.js.map

package/dist/esm/internal/Declaration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Declaration.js","sourceRoot":"","sources":["../../../src/internal/Declaration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAe/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAwB,EAAuB,EAAE,CACxE,OAAO,CAAC,IAAI,CAAC;IACX,KAAK,EAAE,OAAO,CAAC,KAAK;IACpB,MAAM,EAAE,OAAO,CAAC,MAAM;IACtB,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,UAAU,EAAE,WAAW;IACvB,IAAI,EAAE,OAAO,CAAC,IAAI;CACnB,CAAC,CAAA;AAEJ;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAyB,EAAE,QAAgB,EAAU,EAAE,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAA;AAE1G;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAA","sourcesContent":["/**\n * Shared declaration helpers for the standard flows.\n *\n * @since 1.0.0\n */\n\nimport type * as Capability from \"@smthrs/capability/Capability\"\nimport * as Effects from \"@smthrs/core/Effects\"\n\n/**\n * Options accepted by {@link envelope}.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface EnvelopeOptions {\n  readonly tier: \"sealed\" | \"compensable\" | \"irreversible\"\n  readonly mode: \"hermetic\" | \"expected\"\n  readonly reads: Iterable<string>\n  readonly writes: Iterable<string>\n}\n\n/**\n * Builds a deterministic effect declaration for a standard flow.\n *\n * Every standard flow serializes on conflict: the library owns no lane\n * partitioning of its own, so the conservative choice is the safe one.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const envelope = (options: EnvelopeOptions): Effects.Declaration =>\n  Effects.make({\n    reads: options.reads,\n    writes: options.writes,\n    mode: options.mode,\n    onConflict: \"serialize\",\n    tier: options.tier\n  })\n\n/**\n * Formats a capability request as the `action:resource` string carried on a\n * flow declaration.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const capability = (action: Capability.Action, resource: string): string => `${action}:${resource}`\n\n/**\n * The read glob covering everything under one search root.\n *\n * `glob` and `grep` narrow their conservative `/**` declaration to the root the\n * call actually names, and a declaration that disagreed between the two would\n * make the same search reserve different paths depending on which flow ran it.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const rootSubtree = (root: string): string => root === \"/\" ? \"/**\" : `${root.replace(/\\/+$/, \"\")}/**`\n"]}

package/dist/esm/internal/Diagnostics.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Keeps a bound language server in step with the files the mutation flows
+ * write, and reads back the errors an edit leaves.
+ *
+ * The server is optional: a host that binds no `LanguageServer` edits files
+ * exactly as before, and a server that fails or times out never fails the
+ * write that already happened.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as LanguageServer from "../LanguageServer.ts";
+/**
+ * Most errors attached to one result.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export declare const MAX_ERRORS = 20;
+/**
+ * One error-severity diagnostic, at its 1-based position.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export declare const Problem: Schema.Struct<{
+    readonly line: Schema.Number;
+    readonly character: Schema.Number;
+    readonly message: Schema.String;
+}>;
+/**
+ * A decoded {@link Problem}.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export type Problem = typeof Problem.Type;
+/**
+ * The error-severity items of a document diagnostic report, 1-based.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export declare const errors: (report: unknown) => ReadonlyArray<Problem>;
+/**
+ * Sends a written file's new text to the bound server, if any. Succeeds with
+ * the server that took it.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export declare const sync: (path: string, text: string) => Effect.Effect<LanguageServer.LanguageServer | undefined>;
+/**
+ * Tells the bound server, if any, that a file is gone.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export declare const close: (path: string) => Effect.Effect<void>;
+/**
+ * Tells the bound server, if any, to re-read every file it has open, after
+ * something other than the mutation flows may have changed them.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export declare const refresh: Effect.Effect<void>;
+/**
+ * The errors `server` reports for `path`, or `undefined` when it could not
+ * answer.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export declare const errorsOf: (server: LanguageServer.LanguageServer, path: string) => Effect.Effect<ReadonlyArray<Problem> | undefined>;
+//# sourceMappingURL=Diagnostics.d.ts.map

package/dist/esm/internal/Diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Diagnostics.d.ts","sourceRoot":"","sources":["../../../src/internal/Diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,cAAc,MAAM,sBAAsB,CAAA;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,KAAK,CAAA;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;EAIlB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAA;AAOzC;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,OAAO,KAAG,aAAa,CAAC,OAAO,CAe7D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,cAAc,GAAG,SAAS,CAUtG,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAMpD,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAKvC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GACnB,QAAQ,cAAc,CAAC,cAAc,EACrC,MAAM,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CAIhD,CAAA"}

package/dist/esm/internal/Diagnostics.js

@@ -0,0 +1,99 @@
+/**
+ * Keeps a bound language server in step with the files the mutation flows
+ * write, and reads back the errors an edit leaves.
+ *
+ * The server is optional: a host that binds no `LanguageServer` edits files
+ * exactly as before, and a server that fails or times out never fails the
+ * write that already happened.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as LanguageServer from "../LanguageServer.js";
+/**
+ * Most errors attached to one result.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export const MAX_ERRORS = 20;
+/**
+ * One error-severity diagnostic, at its 1-based position.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export const Problem = Schema.Struct({
+    line: Schema.Number.annotate({ description: "1-based line" }),
+    character: Schema.Number.annotate({ description: "1-based character" }),
+    message: Schema.String
+});
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * The error-severity items of a document diagnostic report, 1-based.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export const errors = (report) => {
+    const items = record(report)?.items;
+    if (!Array.isArray(items))
+        return [];
+    const found = [];
+    for (const item of items) {
+        const diagnostic = record(item);
+        const start = record(record(diagnostic?.range)?.start);
+        if (diagnostic?.severity !== 1 || typeof diagnostic.message !== "string" ||
+            typeof start?.line !== "number" || typeof start.character !== "number")
+            continue;
+        found.push({ line: start.line + 1, character: start.character + 1, message: diagnostic.message });
+        if (found.length === MAX_ERRORS)
+            break;
+    }
+    return found;
+};
+/**
+ * Sends a written file's new text to the bound server, if any. Succeeds with
+ * the server that took it.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export const sync = (path, text) => Effect.serviceOption(LanguageServer.LanguageServer).pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.succeed(undefined),
+    onSome: (server) => server.sync(path, text).pipe(Effect.as(server), Effect.orElseSucceed(() => undefined))
+})));
+/**
+ * Tells the bound server, if any, that a file is gone.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export const close = (path) => Effect.serviceOption(LanguageServer.LanguageServer).pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.void,
+    onSome: (server) => server.close(path).pipe(Effect.ignore)
+})));
+/**
+ * Tells the bound server, if any, to re-read every file it has open, after
+ * something other than the mutation flows may have changed them.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export const refresh = Effect.serviceOption(LanguageServer.LanguageServer).pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.void,
+    onSome: (server) => server.refresh.pipe(Effect.ignore)
+})));
+/**
+ * The errors `server` reports for `path`, or `undefined` when it could not
+ * answer.
+ *
+ * @category internal
+ * @since 1.0.0
+ */
+export const errorsOf = (server, path) => server.diagnostics(path).pipe(Effect.map(errors), Effect.orElseSucceed(() => undefined));
+//# sourceMappingURL=Diagnostics.js.map

package/dist/esm/internal/Diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Diagnostics.js","sourceRoot":"","sources":["../../../src/internal/Diagnostics.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Keeps a bound language server in step with the files the mutation flows\n * write, and reads back the errors an edit leaves.\n *\n * The server is optional: a host that binds no `LanguageServer` edits files\n * exactly as before, and a server that fails or times out never fails the\n * write that already happened.\n *\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as LanguageServer from \"../LanguageServer.ts\"\n\n/**\n * Most errors attached to one result.\n *\n * @category internal\n * @since 1.0.0\n */\nexport const MAX_ERRORS = 20\n\n/**\n * One error-severity diagnostic, at its 1-based position.\n *\n * @category internal\n * @since 1.0.0\n */\nexport const Problem = Schema.Struct({\n  line: Schema.Number.annotate({ description: \"1-based line\" }),\n  character: Schema.Number.annotate({ description: \"1-based character\" }),\n  message: Schema.String\n})\n\n/**\n * A decoded {@link Problem}.\n *\n * @category internal\n * @since 1.0.0\n */\nexport type Problem = typeof Problem.Type\n\nconst record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value)\n    ? value as Readonly<Record<string, unknown>>\n    : undefined\n\n/**\n * The error-severity items of a document diagnostic report, 1-based.\n *\n * @category internal\n * @since 1.0.0\n */\nexport const errors = (report: unknown): ReadonlyArray<Problem> => {\n  const items = record(report)?.items\n  if (!Array.isArray(items)) return []\n  const found: Array<Problem> = []\n  for (const item of items) {\n    const diagnostic = record(item)\n    const start = record(record(diagnostic?.range)?.start)\n    if (\n      diagnostic?.severity !== 1 || typeof diagnostic.message !== \"string\" ||\n      typeof start?.line !== \"number\" || typeof start.character !== \"number\"\n    ) continue\n    found.push({ line: start.line + 1, character: start.character + 1, message: diagnostic.message })\n    if (found.length === MAX_ERRORS) break\n  }\n  return found\n}\n\n/**\n * Sends a written file's new text to the bound server, if any. Succeeds with\n * the server that took it.\n *\n * @category internal\n * @since 1.0.0\n */\nexport const sync = (path: string, text: string): Effect.Effect<LanguageServer.LanguageServer | undefined> =>\n  Effect.serviceOption(LanguageServer.LanguageServer).pipe(\n    Effect.flatMap(Option.match({\n      onNone: () => Effect.succeed(undefined),\n      onSome: (server) =>\n        server.sync(path, text).pipe(\n          Effect.as(server),\n          Effect.orElseSucceed(() => undefined)\n        )\n    }))\n  )\n\n/**\n * Tells the bound server, if any, that a file is gone.\n *\n * @category internal\n * @since 1.0.0\n */\nexport const close = (path: string): Effect.Effect<void> =>\n  Effect.serviceOption(LanguageServer.LanguageServer).pipe(\n    Effect.flatMap(Option.match({\n      onNone: () => Effect.void,\n      onSome: (server) => server.close(path).pipe(Effect.ignore)\n    }))\n  )\n\n/**\n * Tells the bound server, if any, to re-read every file it has open, after\n * something other than the mutation flows may have changed them.\n *\n * @category internal\n * @since 1.0.0\n */\nexport const refresh: Effect.Effect<void> = Effect.serviceOption(LanguageServer.LanguageServer).pipe(\n  Effect.flatMap(Option.match({\n    onNone: () => Effect.void,\n    onSome: (server) => server.refresh.pipe(Effect.ignore)\n  }))\n)\n\n/**\n * The errors `server` reports for `path`, or `undefined` when it could not\n * answer.\n *\n * @category internal\n * @since 1.0.0\n */\nexport const errorsOf = (\n  server: LanguageServer.LanguageServer,\n  path: string\n): Effect.Effect<ReadonlyArray<Problem> | undefined> =>\n  server.diagnostics(path).pipe(\n    Effect.map(errors),\n    Effect.orElseSucceed(() => undefined)\n  )\n"]}

package/dist/esm/internal/EnvelopePrecheck.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The hermetic pre-check: a lexical scan of shell text for the paths it names,
+ * and the refusal when one of them falls outside the declared envelope.
+ *
+ * The scan is fail-closed over explicit path tokens and nothing more. It
+ * cannot prove confinement — a shell can name a path no lexer sees, through a
+ * variable, a substitution, or a program that opens a file of its own — so a
+ * kernel or host sandbox must eventually enforce and report the complete read
+ * and write sets.
+ *
+ * It lives beside the flow rather than inside it because it is its own
+ * concept, with its own vocabulary (Access, PathReference) and its own
+ * security history: three independent bypasses, each sufficient on its own to
+ * defeat it, are closed here.
+ *
+ * @since 1.0.0
+ */
+import type * as Path from "@smthrs/kernel/Path";
+import * as StdError from "../StdError.ts";
+/**
+ * The filesystem envelope one invocation declared.
+ *
+ * Structural rather than the hermetic `Bash.Input` itself: the scan needs the
+ * three fields and none of the rest, and depending on the flow module would
+ * make the flow and its pre-check import each other.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Envelope {
+    readonly cwd?: string | undefined;
+    readonly reads: ReadonlyArray<string>;
+    readonly writes: ReadonlyArray<string>;
+}
+/**
+ * How a command touches a path it names.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Access = "read" | "write";
+/**
+ * One path a command names, and how it touches it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface PathReference {
+    readonly access: Access;
+    readonly value: string;
+}
+/**
+ * Every path token the shell text names, one segment at a time.
+ *
+ * @throws {StdError.StdError} `invalid_input` when substitutions or quotes nest
+ * deeper than the scan reads.
+ * @category pre-check
+ * @since 1.0.0
+ */
+export declare const commandReferences: (path: Path.Path, command: string) => ReadonlyArray<PathReference>;
+/**
+ * The refusal shell text earns by naming a path outside its declared
+ * envelope, or `undefined` when every path it names is declared.
+ *
+ * @category pre-check
+ * @since 1.0.0
+ */
+export declare const outsideEnvelope: (input: Envelope, text: string, path: Path.Path) => StdError.StdError | undefined;
+//# sourceMappingURL=EnvelopePrecheck.d.ts.map

package/dist/esm/internal/EnvelopePrecheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvelopePrecheck.d.ts","sourceRoot":"","sources":["../../../src/internal/EnvelopePrecheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAG1C;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACvC;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAErC;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AA0VD;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,KAAG,aAAa,CAAC,aAAa,CAClE,CAAA;AAmB9B;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,QAAQ,EACf,MAAM,MAAM,EACZ,MAAM,IAAI,CAAC,IAAI,KACd,QAAQ,CAAC,QAAQ,GAAG,SAgDtB,CAAA"}