@eidos.space/just-bash 3.0.2

package/dist/commands/xan/csv.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CSV parsing and formatting utilities for xan command
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+export interface CsvRow {
+    [key: string]: string | number | boolean | null;
+}
+export type CsvData = CsvRow[];
+/**
+ * Create a null-prototype CsvRow to prevent prototype pollution.
+ * User-controlled CSV column names could match dangerous keys like
+ * __proto__, constructor, or prototype. Using a null-prototype object
+ * ensures these don't access the prototype chain.
+ */
+export declare function createSafeRow(): CsvRow;
+/**
+ * Set a property on a CsvRow.
+ * Since CsvRow uses null-prototype, this is safe from prototype pollution.
+ */
+export declare function safeSetRow(row: CsvRow, key: string, value: string | number | boolean | null): void;
+/**
+ * Convert a plain object row to a safe null-prototype row.
+ */
+export declare function toSafeRow(plainRow: Record<string, unknown>): CsvRow;
+/** Parse CSV input string to array of row objects */
+export declare function parseCsv(input: string): {
+    headers: string[];
+    data: CsvData;
+};
+/** Format array of row objects back to CSV string */
+export declare function formatCsv(headers: string[], data: CsvData): string;
+/** Read CSV input from file or stdin */
+export declare function readCsvInput(args: string[], ctx: CommandContext): Promise<{
+    headers: string[];
+    data: CsvData;
+    error?: ExecResult;
+}>;

package/dist/commands/xan/moonblade-parser.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Moonblade expression parser for xan
+ *
+ * Parses moonblade expressions (xan's expression language) and transforms
+ * them to jq AST for evaluation by the shared query engine.
+ *
+ * Grammar based on xan's grammar.pest
+ */
+export type MoonbladeExpr = {
+    type: "int";
+    value: number;
+} | {
+    type: "float";
+    value: number;
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "bool";
+    value: boolean;
+} | {
+    type: "null";
+} | {
+    type: "identifier";
+    name: string;
+    unsure: boolean;
+} | {
+    type: "underscore";
+} | {
+    type: "func";
+    name: string;
+    args: Array<{
+        name?: string;
+        expr: MoonbladeExpr;
+    }>;
+} | {
+    type: "list";
+    elements: MoonbladeExpr[];
+} | {
+    type: "map";
+    entries: Array<{
+        key: string;
+        value: MoonbladeExpr;
+    }>;
+} | {
+    type: "regex";
+    pattern: string;
+    caseInsensitive: boolean;
+} | {
+    type: "slice";
+    start?: MoonbladeExpr;
+    end?: MoonbladeExpr;
+} | {
+    type: "lambda";
+    params: string[];
+    body: MoonbladeExpr;
+} | {
+    type: "lambdaBinding";
+    name: string;
+} | {
+    type: "pipeline";
+    exprs: MoonbladeExpr[];
+};
+export interface NamedExpr {
+    expr: MoonbladeExpr;
+    name: string | string[];
+}
+export interface Aggregation {
+    aggName: string;
+    funcName: string;
+    args: MoonbladeExpr[];
+}
+/**
+ * Parse named expressions like: "expr1, expr2 as name, expr3 as (a, b)"
+ */
+export declare function parseNamedExpressions(input: string): NamedExpr[];
+/**
+ * Parse a moonblade expression string into AST
+ */
+export declare function parseMoonblade(input: string): MoonbladeExpr;

package/dist/commands/xan/moonblade-to-jq.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Transform moonblade AST to jq AST
+ *
+ * This module converts moonblade expressions (xan's expression language)
+ * to jq AST for evaluation by the shared query engine.
+ */
+import type { AstNode } from "../query-engine/parser.js";
+import type { MoonbladeExpr } from "./moonblade-parser.js";
+/**
+ * Transform moonblade AST to jq AST
+ */
+export declare function moonbladeToJq(expr: MoonbladeExpr, rowContext?: boolean): AstNode;

package/dist/commands/xan/moonblade-tokenizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Moonblade expression tokenizer
+ */
+export type TokenType = "int" | "float" | "string" | "regex" | "ident" | "true" | "false" | "null" | "(" | ")" | "[" | "]" | "{" | "}" | "," | ":" | ";" | "=>" | "+" | "-" | "*" | "/" | "//" | "%" | "**" | "++" | "==" | "!=" | "<" | "<=" | ">" | ">=" | "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "&&" | "||" | "and" | "or" | "!" | "." | "|" | "in" | "not in" | "as" | "=" | "_" | "eof";
+export interface Token {
+    type: TokenType;
+    value: string;
+    pos: number;
+}
+export declare class Tokenizer {
+    private input;
+    private pos;
+    private tokens;
+    constructor(input: string);
+    tokenize(): Token[];
+    private skipWhitespace;
+    private nextToken;
+    private match;
+    private isIdentStart;
+    private isIdentChar;
+    private readNumber;
+    private readString;
+    private readRegex;
+    private readIdentifier;
+}

package/dist/commands/xan/subcommands.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Barrel file for xan subcommand handlers
+ *
+ * This file re-exports all subcommands from their individual modules
+ * for cleaner organization and easier maintenance.
+ */
+export { cmdAgg, cmdFrequency, cmdGroupby, cmdStats } from "./xan-agg.js";
+export { cmdDrop, cmdEnum, cmdRename, cmdSelect } from "./xan-columns.js";
+export { cmdCount, cmdHead, cmdHeaders, cmdReverse, cmdSlice, cmdTail, } from "./xan-core.js";
+export { cmdFixlengths, cmdFrom, cmdPartition, cmdShuffle, cmdSplit, cmdTo, cmdTranspose, } from "./xan-data.js";
+export { cmdDedup, cmdFilter, cmdSort, cmdTop } from "./xan-filter.js";
+export { cmdMap, cmdTransform } from "./xan-map.js";
+export { cmdExplode, cmdImplode, cmdJoin, cmdMerge, cmdPivot, } from "./xan-reshape.js";
+export { cmdBehead, cmdCat, cmdFlatmap, cmdFmt, cmdSample, cmdSearch, } from "./xan-simple.js";
+export { cmdFlatten, cmdView } from "./xan-view.js";

package/dist/commands/xan/xan-agg.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Aggregation commands: agg, groupby, frequency, stats
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+export declare function cmdAgg(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdGroupby(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdFrequency(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdStats(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-columns.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Column operation commands: select, drop, rename, enum
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+export declare function cmdSelect(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdDrop(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdRename(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdEnum(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-core.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Core xan commands: headers, count, head, tail, slice, reverse
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+export declare function cmdHeaders(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdCount(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdHead(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdTail(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdSlice(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdReverse(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-data.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Data utility commands: transpose, shuffle, fixlengths, split, partition
+ * Commands that exist in real xan
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+/**
+ * Transpose: swap rows and columns
+ * Usage: xan transpose [FILE]
+ *   First column becomes header row, first row becomes header column
+ */
+export declare function cmdTranspose(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Shuffle: randomly reorder rows
+ * Usage: xan shuffle [OPTIONS] [FILE]
+ *   --seed N    Random seed for reproducibility
+ */
+export declare function cmdShuffle(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Fixlengths: fix ragged CSV by padding/truncating rows
+ * Usage: xan fixlengths [OPTIONS] [FILE]
+ *   -l, --length N    Target number of columns (default: max row length)
+ *   -d, --default V   Default value for missing fields (default: empty)
+ */
+export declare function cmdFixlengths(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Split: split CSV into multiple files by row count
+ * Usage: xan split [OPTIONS] FILE
+ *   -c, --chunks N    Split into N equal chunks
+ *   -S, --size N      Split into chunks of N rows each
+ *   -o, --output DIR  Output directory (default: current)
+ *
+ * In sandbox mode, outputs as JSON with parts as array
+ */
+export declare function cmdSplit(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Partition: split CSV by column value into separate outputs
+ * Usage: xan partition COLUMN [OPTIONS] [FILE]
+ *   -o, --output DIR  Output directory (default: current)
+ */
+export declare function cmdPartition(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * To: convert CSV to other formats
+ * Usage: xan to FORMAT [OPTIONS] [FILE]
+ *   FORMAT: json
+ */
+export declare function cmdTo(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * From: convert other formats to CSV
+ * Usage: xan from [OPTIONS] [FILE]
+ *   -f, --format FORMAT   Input format (json)
+ */
+export declare function cmdFrom(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-filter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Filter and sort commands: filter, sort, dedup, top
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+export declare function cmdFilter(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdSort(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdDedup(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdTop(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-map.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Map command: add computed columns
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+export declare function cmdMap(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Transform command: modify existing columns in-place
+ * Usage: xan transform COLUMN EXPR [FILE]
+ *   -r, --rename NAME  Rename the column after transformation
+ */
+export declare function cmdTransform(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-reshape.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reshape commands: explode, implode, flatmap, pivot, join, merge
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+/**
+ * Explode: split delimited column values into multiple rows
+ * Usage: xan explode COLUMN [OPTIONS] [FILE]
+ *   -s, --separator SEP  Value separator (default: |)
+ *   --drop-empty         Drop rows where column is empty
+ *   -r, --rename NAME    Rename the column
+ */
+export declare function cmdExplode(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Implode: combine consecutive rows with same key, joining column values
+ * Usage: xan implode COLUMN [OPTIONS] [FILE]
+ *   -s, --separator SEP  Value separator (default: |)
+ *   -r, --rename NAME    Rename the column
+ */
+export declare function cmdImplode(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Join: join two CSV files on key columns
+ * Usage: xan join KEY1 FILE1 KEY2 FILE2 [OPTIONS]
+ *   --left       Left outer join (keep all rows from first file)
+ *   --right      Right outer join (keep all rows from second file)
+ *   --full       Full outer join (keep all rows from both files)
+ *   -D, --default VALUE  Default value for missing fields
+ */
+export declare function cmdJoin(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Pivot: reshape data by turning row values into columns
+ * Usage: xan pivot COLUMN AGG_EXPR [OPTIONS] [FILE]
+ *   -g, --groupby COLS   Group by these columns (default: all other columns)
+ */
+export declare function cmdPivot(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Merge: merge multiple sorted CSV files
+ * Usage: xan merge [OPTIONS] FILE1 FILE2 ...
+ *   -s, --sort COLUMN   Sort column (files must be pre-sorted by this)
+ */
+export declare function cmdMerge(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-simple.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Simple commands: behead, sample, cat, search, flatmap, fmt
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+/**
+ * Behead: remove header row from CSV (output data rows only)
+ * Usage: xan behead [FILE]
+ */
+export declare function cmdBehead(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Sample: randomly sample N rows from CSV
+ * Usage: xan sample [OPTIONS] <sample-size> [FILE]
+ *   --seed SEED    Random seed for reproducibility
+ */
+export declare function cmdSample(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Cat: concatenate CSV files
+ * Usage: xan cat [OPTIONS] FILE1 FILE2 ...
+ *   -p, --pad    Pad missing columns with empty values
+ */
+export declare function cmdCat(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Search: filter rows by regex match on any/specific columns
+ * Usage: xan search [OPTIONS] PATTERN [FILE]
+ *   -s, --select COLS    Only search in these columns
+ *   -v, --invert         Invert match (exclude matching rows)
+ *   -i, --ignore-case    Case insensitive match
+ */
+export declare function cmdSearch(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Flatmap: like map but expression can return multiple rows
+ * Usage: xan flatmap EXPR [FILE]
+ *   The expression should return an array; each element becomes a row
+ */
+export declare function cmdFlatmap(args: string[], ctx: CommandContext): Promise<ExecResult>;
+/**
+ * Fmt: format CSV as a table (alias for view with options)
+ * Usage: xan fmt [OPTIONS] [FILE]
+ */
+export declare function cmdFmt(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-view.d.ts

@@ -0,0 +1,12 @@
+/**
+ * View commands: pretty print CSV as table or flattened records
+ */
+import type { CommandContext, ExecResult } from "../../types.js";
+/**
+ * Flatten: display records vertically, one field per line
+ * Usage: xan flatten [OPTIONS] [FILE]
+ *   -l, --limit N    Maximum number of rows to display
+ *   -s, --select COLS  Select columns to display
+ */
+export declare function cmdFlatten(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdView(args: string[], ctx: CommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan.d.ts

@@ -0,0 +1,10 @@
+/**
+ * xan - CSV toolkit command
+ *
+ * Provides ergonomic CLI for CSV operations, translating commands to jq expressions
+ * and using the shared query engine. Inspired by xsv and xan tools.
+ */
+import type { Command } from "../../types.js";
+export declare const xanCommand: Command;
+import type { CommandFuzzInfo } from "../fuzz-flags-types.js";
+export declare const flagsForFuzzing: CommandFuzzInfo;

package/dist/commands/xargs/xargs.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "../../types.js";
+export declare const xargsCommand: Command;
+import type { CommandFuzzInfo } from "../fuzz-flags-types.js";
+export declare const flagsForFuzzing: CommandFuzzInfo;

package/dist/commands/yq/formats.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Format parsing and output for yq command
+ *
+ * Supports YAML, JSON, XML, INI, CSV, and TOML formats with conversion between them.
+ */
+import type { QueryValue } from "../query-engine/index.js";
+export type InputFormat = "yaml" | "xml" | "json" | "ini" | "csv" | "toml";
+export type OutputFormat = "yaml" | "json" | "xml" | "ini" | "csv" | "toml";
+/**
+ * Type guard to validate input format strings at runtime
+ */
+export declare function isValidInputFormat(value: unknown): value is InputFormat;
+/**
+ * Type guard to validate output format strings at runtime
+ */
+export declare function isValidOutputFormat(value: unknown): value is OutputFormat;
+export interface FormatOptions {
+    /** Input format (default: yaml) */
+    inputFormat: InputFormat;
+    /** Output format (default: yaml) */
+    outputFormat: OutputFormat;
+    /** Output raw strings without quotes (json only) */
+    raw: boolean;
+    /** Compact output (json only) */
+    compact: boolean;
+    /** Pretty print output */
+    prettyPrint: boolean;
+    /** Indentation level */
+    indent: number;
+    /** XML attribute prefix (default: +@) */
+    xmlAttributePrefix: string;
+    /** XML text content name (default: +content) */
+    xmlContentName: string;
+    /** CSV delimiter (empty = auto-detect) */
+    csvDelimiter: string;
+    /** CSV has header row */
+    csvHeader: boolean;
+}
+export declare const defaultFormatOptions: FormatOptions;
+/**
+ * Detect input format from file extension
+ */
+export declare function detectFormatFromExtension(filename: string): InputFormat | null;
+/**
+ * Parse input data from the given format into a QueryValue
+ */
+export declare function parseInput(input: string, options: FormatOptions): QueryValue;
+/**
+ * Parse all YAML documents from input (for slurp mode)
+ */
+export declare function parseAllYamlDocuments(input: string): QueryValue[];
+/**
+ * Extract front-matter from content
+ * Front-matter is YAML/TOML/JSON at the start of a file between --- or +++ delimiters
+ * Returns { frontMatter: parsed data, content: remaining content } or null if no front-matter
+ */
+export declare function extractFrontMatter(input: string): {
+    frontMatter: QueryValue;
+    content: string;
+} | null;
+/**
+ * Format a QueryValue for output in the given format
+ */
+export declare function formatOutput(value: QueryValue, options: FormatOptions): string;

package/dist/commands/yq/yq.d.ts

@@ -0,0 +1,13 @@
+/**
+ * yq - Command-line YAML/XML/INI/CSV/TOML processor
+ *
+ * Uses jq-style query expressions to process YAML, XML, INI, CSV, and TOML files.
+ * Shares the query engine with jq for consistent filtering behavior.
+ *
+ * Inspired by mikefarah/yq (https://github.com/mikefarah/yq)
+ * This is a reimplementation for the just-bash sandboxed environment.
+ */
+import type { Command } from "../../types.js";
+export declare const yqCommand: Command;
+import type { CommandFuzzInfo } from "../fuzz-flags-types.js";
+export declare const flagsForFuzzing: CommandFuzzInfo;

package/dist/custom-commands.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Custom Commands API
+ *
+ * Provides types and utilities for registering user-provided TypeScript commands.
+ */
+import type { Command, CommandContext, ExecResult } from "./types.js";
+/**
+ * A custom command - either a Command object or a lazy loader.
+ */
+export type CustomCommand = Command | LazyCommand;
+/**
+ * Lazy-loaded custom command (for code-splitting).
+ */
+export interface LazyCommand {
+    name: string;
+    load: () => Promise<Command>;
+}
+/**
+ * Type guard to check if a custom command is lazy-loaded.
+ */
+export declare function isLazyCommand(cmd: CustomCommand): cmd is LazyCommand;
+/**
+ * Define a TypeScript command with type inference.
+ * Convenience wrapper - you can also just use the Command interface directly.
+ *
+ * @example
+ * ```ts
+ * const hello = defineCommand("hello", async (args, ctx) => {
+ *   const name = args[0] || "world";
+ *   return { stdout: `Hello, ${name}!\n`, stderr: "", exitCode: 0 };
+ * });
+ *
+ * const bash = new Bash({ customCommands: [hello] });
+ * await bash.exec("hello Alice"); // "Hello, Alice!\n"
+ * ```
+ */
+export declare function defineCommand(name: string, execute: (args: string[], ctx: CommandContext) => Promise<ExecResult>): Command;
+/**
+ * Create a lazy-loaded wrapper for a custom command.
+ * The command is only loaded when first executed.
+ */
+export declare function createLazyCustomCommand(lazy: LazyCommand): Command;

package/dist/encoding.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Byte/text boundary types for the shell pipeline.
+ *
+ * Shell pipes carry bytes, not text. Internally we represent a byte buffer as
+ * a JS string where `s.charCodeAt(i)` is the i-th byte (0–255), the same
+ * convention as `Buffer.from(s, "latin1")`. That's a space-cheap byte buffer,
+ * but the type system can't tell it apart from a real `string`, and command
+ * authors keep writing `ctx.stdin.split(...)` / `RegExp.test(ctx.stdin)` /
+ * `JSON.parse(ctx.stdin)` over data that is actually UTF-8 packed in latin1.
+ * The result is silent mojibake — every multibyte codepoint gets misread as
+ * several latin1 chars, then re-encoded as UTF-8 on the way out.
+ *
+ * `ByteString` is opaque (deliberately not assignable to/from `string`) so
+ * you cannot accidentally call string methods on it. The only ways out are
+ * `latin1FromBytes` (passthrough — stay byte-clean) and `decodeBytesToUtf8`
+ * (decode — process as text). Pick one explicitly per call site.
+ */
+declare const __byteString: unique symbol;
+export interface ByteString {
+    readonly [__byteString]: true;
+}
+/**
+ * Tag a latin1 byte buffer (each char = one byte) as a `ByteString`. Use at
+ * the pipeline edge: `cmdCtx.stdin = unsafeBytesFromLatin1(prevStdout)`.
+ * Avoid inside command implementations.
+ */
+export declare function unsafeBytesFromLatin1(s: string): ByteString;
+/**
+ * Reveal the underlying latin1 byte buffer. Use when a command intentionally
+ * forwards bytes unchanged (cat, head, tee, base64 -d, gzip, ...). Calling
+ * regex / parse / `.length-as-chars` on the result re-introduces the
+ * mojibake bug — if you need text, use `decodeBytesToUtf8` instead.
+ */
+export declare function latin1FromBytes(b: ByteString): string;
+/**
+ * Decode a `ByteString` as UTF-8. Use when a command interprets stdin as
+ * text (jq, sed, grep, awk, ...). Returns proper Unicode where multibyte
+ * codepoints occupy a single JS char, so regex and parsers work correctly.
+ *
+ * Falls back to the raw latin1 view if the bytes are not valid UTF-8 (e.g.
+ * a binary stream piped into grep). Callers that want hard failure on
+ * invalid UTF-8 should encode + decode manually with `{ fatal: true }`.
+ */
+export declare function decodeBytesToUtf8(b: ByteString): string;
+/**
+ * UTF-8 encode `s` (treating every char as a Unicode codepoint) into a
+ * `ByteString`. Use at sites that *know* their input is decoded Unicode
+ * text and need to emit it back as bytes — typically the inverse of an
+ * earlier `decodeBytesToUtf8` call inside the same command.
+ */
+export declare function encodeUtf8ToBytes(s: string): ByteString;
+/** The empty `ByteString`. */
+export declare const EMPTY_BYTES: ByteString;
+/**
+ * Convert a `Uint8Array` to a `ByteString`. Each byte becomes one char.
+ * The reverse is `Uint8Array.from(latin1FromBytes(b), (c) => c.charCodeAt(0))`.
+ */
+export declare function bytesFromUint8Array(buf: Uint8Array): ByteString;
+/**
+ * Read a file's raw bytes from any `IFileSystem`. Prefers the optional
+ * {@link IFileSystem.readFileBytes} method (built-in filesystems implement
+ * it natively), falling back to {@link IFileSystem.readFileBuffer} +
+ * conversion for external/custom filesystems written before
+ * `readFileBytes` existed. Use this from internal commands instead of
+ * calling `fs.readFileBytes` directly so user-supplied filesystems keep
+ * working.
+ */
+export declare function readBytesFrom(fs: {
+    readFileBytes?(path: string): Promise<ByteString>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+}, path: string): Promise<ByteString>;
+/** Either-or shape of a command's `stdout`. */
+export type OutputKind = "text" | "bytes";
+/**
+ * Read the explicit shape of a command's stdout. Falls back to the legacy
+ * `stdoutEncoding === "binary"` flag for results produced before the
+ * `stdoutKind` field existed; defaults to `"text"` otherwise.
+ */
+export declare function stdoutKind(result: {
+    stdoutKind?: OutputKind;
+    stdoutEncoding?: "binary";
+}): OutputKind;
+/**
+ * Coerce a command's stdout to a `ByteString` for the byte-shaped pipe.
+ * Text gets UTF-8 encoded once (codepoints → bytes); bytes pass through.
+ */
+export declare function stdoutAsBytes(result: {
+    stdout: string;
+    stdoutKind?: OutputKind;
+    stdoutEncoding?: "binary";
+}): ByteString;
+/**
+ * Build an `ExecResult`-shaped object whose stdout is decoded text. Sets
+ * `stdoutKind: "text"` so the pipe knows to UTF-8 encode it on handoff
+ * and redirects know to write it as UTF-8. Use for command authors that
+ * decode their input and emit Unicode text — they no longer have to
+ * manually re-encode for downstream byte consumers.
+ */
+export declare function textOutput(data: string): {
+    stdout: string;
+    stdoutKind: "text";
+};
+/**
+ * Build an `ExecResult`-shaped object whose stdout is a latin1 byte view.
+ * Sets both `stdoutKind: "bytes"` (new contract) and `stdoutEncoding:
+ * "binary"` (legacy alias) so older code paths keep working through the
+ * migration. Use for command authors that emit raw bytes (cat, gzip,
+ * tar, base64 -d, ...).
+ */
+export declare function bytesOutput(data: ByteString): {
+    stdout: string;
+    stdoutKind: "bytes";
+    stdoutEncoding: "binary";
+};
+export {};

package/dist/fs/encoding.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared utilities for filesystem implementations
+ */
+import type { BufferEncoding, ReadFileOptions, WriteFileOptions } from "./interface.js";
+export type FileContent = string | Uint8Array;
+/**
+ * Helper to convert content to Uint8Array
+ */
+export declare function toBuffer(content: FileContent, encoding?: BufferEncoding): Uint8Array;
+/**
+ * Helper to convert Uint8Array to string with encoding
+ */
+export declare function fromBuffer(buffer: Uint8Array, encoding?: BufferEncoding | null): string;
+/**
+ * Helper to get encoding from options
+ */
+export declare function getEncoding(options?: ReadFileOptions | WriteFileOptions | BufferEncoding | string | null): BufferEncoding | undefined;