functionalscript 0.29.1 → 0.31.0

package/fs/mcp/stdio/module.f.d.ts

@@ -0,0 +1,39 @@
+/**
+ * stdio transport for JSON-RPC / MCP servers.
+ *
+ * `stdioTransport` wraps a step function — the `mcpStep`-shaped
+ * `(value) => Effect<O, Response | null>` from `fs/mcp/module.f.ts` — in the
+ * canonical read → parse → dispatch → write loop, expressed as a recursive
+ * effect so it stays in the pure effect model and is fully testable against a
+ * mock stdin / stdout (see `fs/effects/node/virtual`) with no real process.
+ *
+ * The loop only consumes `Read` (stdin, one byte at a time, via the pure
+ * `readLine` combinator) and emits `Write` (stdout) on top of whatever `O` the
+ * step needs (e.g. `MemOp`); it is transport-agnostic and carries no filesystem
+ * dependency.
+ *
+ * Edge cases, matching the issue's spec:
+ * - `readLine` yields `null` (EOF) → the loop returns, a clean shutdown.
+ * - a malformed JSON line → a JSON-RPC parse-error response (`-32700`, `id`
+ *   `null`) is written rather than silently discarded, per JSON-RPC 2.0 §5.
+ * - the step yields `null` (a notification needing no reply) → nothing is
+ *   written and the loop continues.
+ *
+ * @module
+ */
+import { type Effect, type Operation } from '../../effects/module.f.ts';
+import { type Read, type Write } from '../../effects/node/module.f.ts';
+import { type Unknown } from '../../json/module.f.ts';
+import { type Response } from '../../json/rpc/module.f.ts';
+/**
+ * A transport step: maps one parsed JSON-RPC message to a response, or `null`
+ * for a notification that needs no reply. The shape of `mcpStep(config)(handlers)(key)`.
+ */
+export type Step<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
+/**
+ * Drives the read-parse-dispatch-write loop for `step` over stdin/stdout.
+ *
+ * Recurses after each handled line; terminates (resolving to `void`) when
+ * `readLine` reports EOF.
+ */
+export declare const stdioTransport: <O extends Operation>(step: Step<O>) => Effect<Read | Write | O, void>;

package/fs/mcp/stdio/module.f.js

@@ -0,0 +1,54 @@
+/**
+ * stdio transport for JSON-RPC / MCP servers.
+ *
+ * `stdioTransport` wraps a step function — the `mcpStep`-shaped
+ * `(value) => Effect<O, Response | null>` from `fs/mcp/module.f.ts` — in the
+ * canonical read → parse → dispatch → write loop, expressed as a recursive
+ * effect so it stays in the pure effect model and is fully testable against a
+ * mock stdin / stdout (see `fs/effects/node/virtual`) with no real process.
+ *
+ * The loop only consumes `Read` (stdin, one byte at a time, via the pure
+ * `readLine` combinator) and emits `Write` (stdout) on top of whatever `O` the
+ * step needs (e.g. `MemOp`); it is transport-agnostic and carries no filesystem
+ * dependency.
+ *
+ * Edge cases, matching the issue's spec:
+ * - `readLine` yields `null` (EOF) → the loop returns, a clean shutdown.
+ * - a malformed JSON line → a JSON-RPC parse-error response (`-32700`, `id`
+ *   `null`) is written rather than silently discarded, per JSON-RPC 2.0 §5.
+ * - the step yields `null` (a notification needing no reply) → nothing is
+ *   written and the loop continues.
+ *
+ * @module
+ */
+import { pure } from "../../effects/module.f.js";
+import { readLine, write } from "../../effects/node/module.f.js";
+import { utf8 } from "../../text/module.f.js";
+import { stringToList } from "../../text/utf16/module.f.js";
+import { stringify } from "../../json/module.f.js";
+import { tokenize } from "../../json/tokenizer/module.f.js";
+import { parse } from "../../json/parser/module.f.js";
+import { sort } from "../../types/object/module.f.js";
+import { jsonrpc, parseError } from "../../json/rpc/module.f.js";
+const stringifyJson = stringify(sort);
+/** The parse-error response (`-32700`, `id: null`) for a malformed input line. */
+const parseErrorResponse = { jsonrpc, error: parseError, id: null };
+/** Encodes a response as a newline-terminated UTF-8 line and writes it to `stdout`. */
+const writeResponse = (resp) => write('stdout', utf8(stringifyJson(resp) + '\n'));
+/** Writes `resp` when present, otherwise does nothing (notification). */
+const writeMaybe = (resp) => resp === null ? pure(undefined) : writeResponse(resp);
+/**
+ * Drives the read-parse-dispatch-write loop for `step` over stdin/stdout.
+ *
+ * Recurses after each handled line; terminates (resolving to `void`) when
+ * `readLine` reports EOF.
+ */
+export const stdioTransport = (step) => readLine('stdin').step(line => line === null
+    ? pure(undefined)
+    : handleLine(step)(line));
+const handleLine = (step) => (line) => {
+    const [t, value] = parse(tokenize(stringToList(line)));
+    return (t === 'error'
+        ? writeResponse(parseErrorResponse)
+        : step(value).step(writeMaybe)).step(() => stdioTransport(step));
+};

package/fs/mcp/stdio/proof.f.d.ts

@@ -0,0 +1,10 @@
+export declare const proof: {
+    eofImmediately: () => void;
+    requestWritesResponse: () => void;
+    requestWithoutTrailingNewline: () => void;
+    notificationWritesNothing: () => void;
+    malformedJsonWritesParseError: () => void;
+    trailingCommaWritesParseError: () => void;
+    undefinedFieldOmitted: () => void;
+    multipleLines: () => void;
+};

package/fs/mcp/stdio/proof.f.js

@@ -0,0 +1,92 @@
+import { assertEq } from "../../asserts/module.f.js";
+import { pure } from "../../effects/module.f.js";
+import { emptyState, virtual } from "../../effects/node/virtual/module.f.js";
+import { stringify } from "../../json/module.f.js";
+import { utf8 } from "../../text/module.f.js";
+import { fromVec } from "../../types/uint8array/module.f.js";
+import { sort } from "../../types/object/module.f.js";
+import { jsonrpc, parseError } from "../../json/rpc/module.f.js";
+import { stdioTransport } from "./module.f.js";
+const stringifyJson = stringify(sort);
+// Extracts the request `id` (a request has one; a notification does not).
+const idOf = (value) => value !== null && typeof value === 'object' && !(value instanceof Array)
+    ? value.id
+    : undefined;
+// A step that mirrors the mcpStep contract closely enough to drive the loop:
+// a message carrying an `id` (a request) gets an echo success response; a
+// message without an `id` (a notification) yields `null` — no reply.
+const echoStep = (value) => {
+    const id = idOf(value);
+    return pure(id === undefined
+        ? null
+        : { jsonrpc, result: { ok: true }, id });
+};
+// UTF-8 bytes of `s` as a plain array — the virtual stdin byte stream.
+const toBytes = (s) => [...fromVec(utf8(s))];
+// Run the transport with `step` over `input` fed to stdin one byte at a time;
+// return the final state. `input` is raw text so tests control newline framing.
+const runStep = (step) => (input) => virtual({ ...emptyState, stdin: toBytes(input) })(stdioTransport(step))[0];
+const run = runStep(echoStep);
+const okResponse = (id) => stringifyJson({ jsonrpc, result: { ok: true }, id }) + '\n';
+const parseErrorLine = stringifyJson({ jsonrpc, error: parseError, id: null }) + '\n';
+const ping = (id) => `{"jsonrpc":"2.0","method":"ping","id":${id}}`;
+const notification = '{"jsonrpc":"2.0","method":"notifications/initialized"}';
+export const proof = {
+    // EOF on the very first read: clean shutdown, nothing written, no further reads.
+    eofImmediately: () => {
+        const state = run('');
+        assertEq(state.stdout, '');
+        assertEq(state.stdin.length, 0);
+    },
+    // A newline-terminated request is parsed, dispatched, and its response
+    // written; stdin is fully drained before the terminating EOF.
+    requestWritesResponse: () => {
+        const state = run(ping(1) + '\n');
+        assertEq(state.stdout, okResponse(1));
+        assertEq(state.stdin.length, 0);
+    },
+    // A final line lacking a trailing newline is still flushed and dispatched
+    // (covers `readLine`'s EOF-with-buffered-bytes branch).
+    requestWithoutTrailingNewline: () => {
+        const state = run(ping(2));
+        assertEq(state.stdout, okResponse(2));
+    },
+    // A notification (no `id`) yields a `null` step result → nothing is written.
+    notificationWritesNothing: () => {
+        const state = run(notification + '\n');
+        assertEq(state.stdout, '');
+    },
+    // A malformed JSON line produces a JSON-RPC parse-error response (-32700),
+    // not a silent discard.
+    malformedJsonWritesParseError: () => {
+        const state = run('not json\n');
+        assertEq(state.stdout, parseErrorLine);
+    },
+    // A request that is not strict JSON (trailing comma) must be rejected with
+    // a parse error, never dispatched to the step.
+    trailingCommaWritesParseError: () => {
+        const state = run('{"jsonrpc":"2.0","method":"ping","id":1,}\n');
+        assertEq(state.stdout, parseErrorLine);
+    },
+    // A response with an optional field explicitly `undefined` serializes like
+    // JSON.stringify — the field is omitted, not a thrown TypeError that would
+    // abort the loop.
+    undefinedFieldOmitted: () => {
+        const step = (value) => {
+            const id = idOf(value);
+            return pure(id === undefined
+                ? null
+                : { jsonrpc, result: { ok: true, nextCursor: undefined }, id });
+        };
+        const state = runStep(step)(ping(1) + '\n');
+        assertEq(state.stdout, okResponse(1));
+    },
+    // A multi-line session interleaving all cases: request, notification, and
+    // malformed line, ending with an unterminated request. Order is preserved
+    // and the notification contributes nothing.
+    multipleLines: () => {
+        const state = run([ping(1), notification, 'not json', ping(2)].join('\n'));
+        assertEq(state.stdout, okResponse(1) + parseErrorLine + okResponse(2));
+        assertEq(state.stdin.length, 0);
+    },
+};

package/fs/mime/module.f.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Magic-byte MIME type detection.
+ *
+ * A pure table lookup over the leading bytes of a `Vec`: no I/O, no
+ * dependencies beyond `fs/types/bit_vec`. `detect` returns a MIME type string
+ * for the container formats whose signatures it knows, or `null` for anything
+ * else — text, unknown binary, or a `Vec` too short to match.
+ *
+ * The CAS store is type-agnostic and keeps raw bytes only, so type is never
+ * stored; it is recovered on read by sniffing the content. Callers decide what
+ * `null` means: the CAS MCP adapter falls back to a plain text result.
+ *
+ * ## Recognised signatures
+ *
+ * | MIME type         | Leading bytes                          |
+ * |-------------------|----------------------------------------|
+ * | `image/png`       | `89 50 4E 47 0D 0A 1A 0A`              |
+ * | `image/jpeg`      | `FF D8 FF`                             |
+ * | `image/gif`       | `47 49 46 38 37 61` / `…39 61` (`"GIF87a"` / `"GIF89a"`) |
+ * | `image/webp`      | `52 49 46 46 .. .. .. .. 57 45 42 50` (`"RIFF"…"WEBP"`) |
+ * | `application/pdf` | `25 50 44 46 2D` (`"%PDF-"`)           |
+ * | `application/zip` | `50 4B 03 04` / `05 06` / `07 08` (`"PK"` entry, empty, or spanned) |
+ *
+ * WebP is the one signature with a gap: the four-byte little-endian file size
+ * sits between the `RIFF` and `WEBP` markers, so it is matched as a prefix plus
+ * a second marker at byte offset 8 rather than a single contiguous run.
+ *
+ * @module
+ */
+import { type Vec } from '../types/bit_vec/module.f.ts';
+import type { Nullable } from '../types/nullable/module.f.ts';
+/**
+ * Detects the MIME type of `bytes` from its leading magic-byte signature.
+ *
+ * @returns the MIME type string for a recognised format, or `null` when the
+ *   leading bytes match no known signature (including any `Vec` shorter than
+ *   the signature it might otherwise match).
+ */
+export declare const detect: (bytes: Vec) => Nullable<string>;

package/fs/mime/module.f.js

@@ -0,0 +1,78 @@
+/**
+ * Magic-byte MIME type detection.
+ *
+ * A pure table lookup over the leading bytes of a `Vec`: no I/O, no
+ * dependencies beyond `fs/types/bit_vec`. `detect` returns a MIME type string
+ * for the container formats whose signatures it knows, or `null` for anything
+ * else — text, unknown binary, or a `Vec` too short to match.
+ *
+ * The CAS store is type-agnostic and keeps raw bytes only, so type is never
+ * stored; it is recovered on read by sniffing the content. Callers decide what
+ * `null` means: the CAS MCP adapter falls back to a plain text result.
+ *
+ * ## Recognised signatures
+ *
+ * | MIME type         | Leading bytes                          |
+ * |-------------------|----------------------------------------|
+ * | `image/png`       | `89 50 4E 47 0D 0A 1A 0A`              |
+ * | `image/jpeg`      | `FF D8 FF`                             |
+ * | `image/gif`       | `47 49 46 38 37 61` / `…39 61` (`"GIF87a"` / `"GIF89a"`) |
+ * | `image/webp`      | `52 49 46 46 .. .. .. .. 57 45 42 50` (`"RIFF"…"WEBP"`) |
+ * | `application/pdf` | `25 50 44 46 2D` (`"%PDF-"`)           |
+ * | `application/zip` | `50 4B 03 04` / `05 06` / `07 08` (`"PK"` entry, empty, or spanned) |
+ *
+ * WebP is the one signature with a gap: the four-byte little-endian file size
+ * sits between the `RIFF` and `WEBP` markers, so it is matched as a prefix plus
+ * a second marker at byte offset 8 rather than a single contiguous run.
+ *
+ * @module
+ */
+import { msb, fromSentinel, length } from "../types/bit_vec/module.f.js";
+const { startsWith, removeFront } = msb;
+// Each signature is written as a hex literal whose leading `1` nibble is a
+// sentinel marking the start of the byte run (so leading zero bytes survive)
+// and fixing the length — see `bit_vec` `fromSentinel`.
+const sig = fromSentinel;
+/**
+ * Contiguous magic-byte signatures, checked in order; the first prefix match
+ * wins. Ordering is irrelevant here — no signature is a prefix of another.
+ */
+const table = [
+    [sig(0x189504e470d0a1a0an), 'image/png'],
+    [sig(0x1ffd8ffn), 'image/jpeg'],
+    // Match the full GIF version headers ("GIF87a" / "GIF89a"), not just "GIF8",
+    // so opaque bytes that merely start with "GIF8" are not mistyped.
+    [sig(0x1474946383761n), 'image/gif'],
+    [sig(0x1474946383961n), 'image/gif'],
+    [sig(0x1255044462dn), 'application/pdf'],
+    // ZIP has three "PK" local-header variants: a normal entry, an empty
+    // archive (end-of-central-directory only), and a spanned archive.
+    [sig(0x1504b0304n), 'application/zip'],
+    [sig(0x1504b0506n), 'application/zip'],
+    [sig(0x1504b0708n), 'application/zip'],
+];
+// WebP: "RIFF" at offset 0, "WEBP" at offset 8 (the 4 bytes between are the
+// file size). 12 bytes = 96 bits is the minimum to carry both markers.
+const riff = sig(0x152494646n);
+const webp = sig(0x157454250n);
+const isWebp = (bytes) => length(bytes) >= 96n
+    && startsWith(riff)(bytes)
+    && startsWith(webp)(removeFront(64n)(bytes));
+/**
+ * Detects the MIME type of `bytes` from its leading magic-byte signature.
+ *
+ * @returns the MIME type string for a recognised format, or `null` when the
+ *   leading bytes match no known signature (including any `Vec` shorter than
+ *   the signature it might otherwise match).
+ */
+export const detect = (bytes) => {
+    if (isWebp(bytes)) {
+        return 'image/webp';
+    }
+    for (const [s, m] of table) {
+        if (startsWith(s)(bytes)) {
+            return m;
+        }
+    }
+    return null;
+};

package/fs/mime/proof.f.d.ts

@@ -0,0 +1,15 @@
+export declare const proof: {
+    png: () => void;
+    jpeg: () => void;
+    gif89a: () => void;
+    gif87a: () => void;
+    gif8NotGif: () => void;
+    pdf: () => void;
+    zip: () => void;
+    emptyZip: () => void;
+    webp: () => void;
+    riffNotWebp: () => void;
+    textIsNull: () => void;
+    shortIsNull: () => void;
+    emptyIsNull: () => void;
+};

package/fs/mime/proof.f.js

@@ -0,0 +1,30 @@
+import { assertEq } from "../asserts/module.f.js";
+import { msb, u8ListToVec, empty } from "../types/bit_vec/module.f.js";
+import { detect } from "./module.f.js";
+// Builds a big-endian `Vec` from a list of byte values — mirrors how the CAS
+// store would hold the leading bytes of a stored blob.
+const bytes = (...b) => u8ListToVec(msb)(b);
+export const proof = {
+    png: () => assertEq(detect(bytes(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)), 'image/png'),
+    jpeg: () => assertEq(detect(bytes(0xff, 0xd8, 0xff, 0xe0)), 'image/jpeg'),
+    gif89a: () => assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x39, 0x61)), 'image/gif'),
+    gif87a: () => assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x37, 0x61)), 'image/gif'),
+    // "GIF8" alone, without a valid version suffix, is not a GIF.
+    gif8NotGif: () => assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x30, 0x30)), null),
+    pdf: () => 
+    // "%PDF-1.4"
+    assertEq(detect(bytes(0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34)), 'application/pdf'),
+    zip: () => assertEq(detect(bytes(0x50, 0x4b, 0x03, 0x04, 0x14, 0x00)), 'application/zip'),
+    // An empty ZIP archive starts with the end-of-central-directory record.
+    emptyZip: () => assertEq(detect(bytes(0x50, 0x4b, 0x05, 0x06, 0x00, 0x00)), 'application/zip'),
+    webp: () => 
+    // "RIFF" + 4-byte size + "WEBP"
+    assertEq(detect(bytes(0x52, 0x49, 0x46, 0x46, 0x1a, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50)), 'image/webp'),
+    // "RIFF…" without the "WEBP" marker (e.g. a WAV) is not WebP.
+    riffNotWebp: () => assertEq(detect(bytes(0x52, 0x49, 0x46, 0x46, 0x1a, 0x00, 0x00, 0x00, 0x57, 0x41, 0x56, 0x45)), null),
+    // Plain ASCII text matches no signature.
+    textIsNull: () => assertEq(detect(bytes(0x68, 0x65, 0x6c, 0x6c, 0x6f)), null),
+    // A prefix shorter than any signature falls through to null, not a partial match.
+    shortIsNull: () => assertEq(detect(bytes(0x89, 0x50)), null),
+    emptyIsNull: () => assertEq(detect(empty), null),
+};

package/fs/path/module.f.d.ts

@@ -24,6 +24,14 @@ export declare const normalize: Unary<string, string>;
  * Concatenates two path fragments and returns a normalized path.
  */
 export declare const concat: Reduce<string>;
+/**
+ * Joins path segments with single POSIX `/` separators, without
+ * normalization. Unlike {@link concat}, the result is not parsed/collapsed,
+ * so absolute roots and `.`/`..` segments are preserved verbatim. Use this
+ * for building paths from already-clean segments (directory walks, store
+ * layouts); use {@link concat} when normalization is desired.
+ */
+export declare const join: (...list: readonly string[]) => string;
 /**
  * Returns `path` relative to `base` with a `./` prefix, or `path` unchanged
  * if it does not start with `base` or `base` is empty.

package/fs/path/module.f.js

@@ -1,6 +1,5 @@
 import { fold, last, take, length, concat as listConcat, toArray } from "../types/list/module.f.js";
-import { join } from "../types/string/module.f.js";
-import { concat as stringConcat } from "../types/string/module.f.js";
+import { join as listJoin, concat as stringConcat } from "../types/string/module.f.js";
 const foldNormalizeOp = input => state => {
     switch (input) {
         case '':
@@ -41,7 +40,7 @@ export const parse = (path) => {
  */
 export const normalize = path => {
     const foldResult = parse(path);
-    return join('/')(foldResult);
+    return listJoin('/')(foldResult);
 };
 /**
  * Concatenates two path fragments and returns a normalized path.
@@ -50,6 +49,14 @@ export const concat = a => b => {
     const s = stringConcat([a, '/', b]);
     return normalize(s);
 };
+/**
+ * Joins path segments with single POSIX `/` separators, without
+ * normalization. Unlike {@link concat}, the result is not parsed/collapsed,
+ * so absolute roots and `.`/`..` segments are preserved verbatim. Use this
+ * for building paths from already-clean segments (directory walks, store
+ * layouts); use {@link concat} when normalization is desired.
+ */
+export const join = (...list) => list.join('/');
 /**
  * Returns `path` relative to `base` with a `./` prefix, or `path` unchanged
  * if it does not start with `base` or `base` is empty.

package/fs/path/proof.f.d.ts

@@ -1,6 +1,7 @@
 export declare const proof: {
     normalizeTest: (() => void)[];
     concatTest: (() => void)[];
+    joinTest: (() => void)[];
     relativizeTest: (() => void)[];
     toPosixTest: (() => void)[];
 };

package/fs/path/proof.f.js

@@ -1,4 +1,4 @@
-import { concat, normalize, relativize, toPosix } from "./module.f.js";
+import { concat, join, normalize, relativize, toPosix } from "./module.f.js";
 const normalizeTest = [
     () => {
         const norm = normalize("dir/file.json");
@@ -45,6 +45,44 @@ const concatTest = [
         }
     },
 ];
+const joinTest = [
+    () => {
+        const r = join('a', 'b');
+        if (r !== 'a/b') {
+            throw r;
+        }
+    },
+    () => {
+        const r = join('/abs/root', 'x');
+        if (r !== '/abs/root/x') {
+            throw r;
+        }
+    },
+    () => {
+        const r = join('a', 'b', 'c', 'd');
+        if (r !== 'a/b/c/d') {
+            throw r;
+        }
+    },
+    () => {
+        const r = join('', 'x');
+        if (r !== '/x') {
+            throw r;
+        }
+    },
+    () => {
+        const r = join();
+        if (r !== '') {
+            throw r;
+        }
+    },
+    () => {
+        const r = join('only');
+        if (r !== 'only') {
+            throw r;
+        }
+    },
+];
 const relativizeTest = [
     () => {
         const r = relativize('/repo', '/repo/fs/a.ts');
@@ -91,4 +129,4 @@ const toPosixTest = [
         }
     },
 ];
-export const proof = { normalizeTest, concatTest, relativizeTest, toPosixTest };
+export const proof = { normalizeTest, concatTest, joinTest, relativizeTest, toPosixTest };

package/fs/text/sgr/proof.f.js

@@ -1,4 +1,15 @@
-import { fgRed, createConsoleText, backspace } from "./module.f.js";
+import { fgRed, reset, createConsoleText, backspace, csiWrite } from "./module.f.js";
+import { virtual, emptyState } from "../../effects/node/virtual/module.f.js";
+const makeOptions = (isTTY) => ({
+    args: [],
+    env: {},
+    home: '.',
+    std: { stdout: { isTTY }, stderr: { isTTY } },
+    testContext: { test: async () => { } },
+    bunTestContext: { test: async () => { } },
+    playwrightTestContext: { test: async () => { } },
+    engine: 'node',
+});
 export const proof = [
     () => {
         if (fgRed !== '\x1b[31m') {
@@ -19,5 +30,22 @@ export const proof = [
         if (output[1] !== expected) {
             throw output[1];
         }
-    }
+    },
+    () => {
+        // csiWrite with isTTY=false strips ANSI SGR sequences
+        const writeFn = csiWrite(makeOptions(false))('stdout');
+        const [state] = virtual(emptyState)(writeFn(fgRed + 'hello' + reset));
+        if (state.stdout !== 'hello') {
+            throw ['expected ANSI stripped', state.stdout];
+        }
+    },
+    () => {
+        // csiWrite with isTTY=true preserves ANSI SGR sequences
+        const writeFn = csiWrite(makeOptions(true))('stdout');
+        const [state] = virtual(emptyState)(writeFn(fgRed + 'hello' + reset));
+        const expected = fgRed + 'hello' + reset;
+        if (state.stdout !== expected) {
+            throw ['expected ANSI preserved', state.stdout];
+        }
+    },
 ];

package/fs/text/utf8/module.f.d.ts

@@ -5,6 +5,7 @@
  */
 import { type List, type Thunk } from '../../types/list/module.f.ts';
 import type { Array1, Array2, Array3 } from '../../types/array/module.f.ts';
+import { type Vec } from '../../types/bit_vec/module.f.ts';
 /**
  * An unsigned 8-bit integer, represents a single byte.
  */
@@ -41,3 +42,9 @@ export declare const fromCodePointList: (input: List<number>) => Thunk<U8>;
  * @returns A list of Unicode code points or error codes.
  */
 export declare const toCodePointList: (input: List<U8>) => List<I32>;
+/**
+ * Returns the decoded string if `v` is valid UTF-8, or `null` otherwise.
+ * Rejects non-octet Vecs, invalid byte sequences, surrogates, and out-of-range
+ * code points.
+ */
+export declare const fromVec: (v: Vec) => string | null;