@fnndsc/chell 4.4.0 → 5.0.1

package/dist/core/sink.d.ts

@@ -1,201 +0,0 @@
-/**
- * @file Output sink: the seam through which command output leaves the engine.
- *
- * Builtins historically printed straight to process stdout, which fuses the
- * engine to a terminal. The sink inverts that: output is written to whatever
- * sink the host installed, and only the host knows where bytes finally go
- * (a terminal for the CLI REPL, a capture buffer for pipes, a connection for
- * a remote surface).
- *
- * Three channels are distinguished. Data is the command's actual output: it
- * is accumulated into the command's result envelope and is what capture,
- * piping and redirection consume. Err is the error stream: presented to the
- * user, never piped, never captured. Status is ephemeral (spinners,
- * progress, transient messages): displayed live, never accumulated, never
- * piped.
- *
- * This module also provides delivery helpers that bridge envelope-returning
- * builtins into the existing dispatch table, so conversion can proceed one
- * builtin at a time while unconverted builtins keep printing.
- *
- * @see docs/calypso.adoc for the governing design.
- * @module
- */
-import type { CommandEnvelope } from '@fnndsc/cumin';
-import type { ProgressEvent } from './progress.js';
-import { TerminalProgressRenderer } from './progressRenderer.js';
-/**
- * Destination for command output, installed by the host.
- */
-export interface OutputSink {
-    /**
-     * Writes command output (the data channel).
-     *
-     * @param chunk - Printable text (ANSI permitted) or raw bytes.
-     */
-    data_write(chunk: string | Buffer): void;
-    /**
-     * Writes error-stream output (the err channel).
-     *
-     * @param chunk - Printable text (ANSI permitted) or raw bytes.
-     */
-    err_write(chunk: string | Buffer): void;
-    /**
-     * Writes an ephemeral status line (the status channel).
-     *
-     * @param text - Transient text; consumers may overwrite or drop it.
-     */
-    status_write(text: string): void;
-    progress_write(event: ProgressEvent): void;
-}
-/**
- * Sink that writes both channels to the process's standard output.
- *
- * This is the CLI host's sink and the default, preserving the shell's
- * historical behavior exactly.
- */
-export declare class StdoutSink implements OutputSink {
-    private readonly progressRenderer;
-    constructor(progressRenderer?: TerminalProgressRenderer);
-    /** @inheritdoc */
-    data_write(chunk: string | Buffer): void;
-    /** @inheritdoc */
-    err_write(chunk: string | Buffer): void;
-    /** @inheritdoc */
-    status_write(text: string): void;
-    progress_write(event: ProgressEvent): void;
-}
-/**
- * Sink that accumulates the data channel in memory and drops status.
- *
- * Used by capture paths and tests; will carry the pipe and redirect
- * machinery once those consume envelopes.
- */
-export declare class BufferSink implements OutputSink {
-    private chunks;
-    /** @inheritdoc */
-    data_write(chunk: string | Buffer): void;
-    /** @inheritdoc */
-    err_write(chunk: string | Buffer): void;
-    /** @inheritdoc */
-    status_write(_text: string): void;
-    progress_write(_event: ProgressEvent): void;
-    /**
-     * Returns everything written to the data channel so far.
-     *
-     * @returns The accumulated bytes.
-     */
-    buffer_get(): Buffer;
-    /**
-     * Returns the accumulated data channel as UTF-8 text.
-     *
-     * @returns The accumulated text.
-     */
-    text_get(): string;
-}
-/**
- * Sink that captures the data and err channels while passing status through
- * to a live sink, so transients (spinners, progress) remain visible while a
- * legacy printing command's output is being gathered into an envelope.
- */
-export declare class CaptureSink implements OutputSink {
-    private dataChunks;
-    private errChunks;
-    private live;
-    private readonly forwardEnvelopeOutput;
-    /**
-     * Initializes the capture around a live sink for status passthrough.
-     *
-     * @param live - The sink that continues to receive status writes.
-     */
-    constructor(live: OutputSink, options?: {
-        forwardEnvelopeOutput?: boolean;
-    });
-    /** @inheritdoc */
-    data_write(chunk: string | Buffer): void;
-    /** @inheritdoc */
-    err_write(chunk: string | Buffer): void;
-    /** @inheritdoc */
-    status_write(text: string): void;
-    progress_write(event: ProgressEvent): void;
-    /**
-     * Returns the captured data channel as UTF-8 text.
-     *
-     * @returns The captured data text.
-     */
-    dataText_get(): string;
-    /**
-     * Returns the captured err channel as UTF-8 text.
-     *
-     * @returns The captured error-stream text.
-     */
-    errText_get(): string;
-}
-/**
- * Returns the currently installed sink.
- *
- * @returns The active output sink.
- */
-export declare function sink_get(): OutputSink;
-/**
- * Installs a sink. Called by the host that owns the output destination.
- *
- * @param sink - The sink to install.
- * @returns The previously installed sink, so callers can restore it.
- */
-export declare function sink_set(sink: OutputSink): OutputSink;
-/**
- * Delivers a completed envelope to the active sink.
- *
- * Rendered text goes to the data channel and error-stream text to the err
- * channel. The structured errors field is machine-facing and is not
- * presented here: its terminal presentation, when any, travels in
- * renderedErr.
- *
- * @param envelope - The completed command envelope.
- */
-export declare function envelope_deliver(envelope: CommandEnvelope): void;
-/**
- * Adapts an envelope-returning builtin to the legacy printing handler shape.
- *
- * This is the compatibility bridge for incremental conversion: converted
- * builtins return envelopes, and this wrapper delivers them through the
- * active sink so the dispatch table, pipes and redirects need no changes.
- * A handler that resolves without an envelope (as stubbed handlers in tests
- * do) is treated as having produced no output.
- *
- * @param handler - An envelope-returning command handler.
- * @returns A handler with the legacy void-returning shape.
- */
-export declare function envelopeHandler_wrap(handler: (args: string[]) => Promise<CommandEnvelope>): (args: string[]) => Promise<void>;
-/**
- * Adapts a legacy printing builtin to the envelope-returning shape.
- *
- * This is the capture bridge for commands whose rendering lives below the
- * seam (chili's table display prints internally): the handler runs with the
- * data and err channels captured, console printing redirected into the
- * capture, and status passed through live so spinners stay visible. The
- * result is an envelope carrying the exact bytes each stream would have
- * shown, with the status derived from the process exit code the handler set.
- *
- * Bridged commands gain envelope semantics without typed models; native
- * conversion (models, streamed data) remains the end state for commands
- * where a structural consumer exists.
- *
- * @param handler - A legacy printing command handler.
- * @returns An envelope-returning handler with identical observable output.
- */
-export declare function printingHandler_wrap(handler: (args: string[]) => Promise<void>): (args: string[]) => Promise<CommandEnvelope>;
-/**
- * Strips ANSI escape sequences from text.
- *
- * Applied at the pipe and redirect boundary so downstream consumers receive
- * plain text, the way programs behind a real shell pipe see no color. This
- * is a deliberate, documented deviation from the historical behavior, in
- * which escape bytes leaked into pipes because color detection saw the
- * terminal regardless of capture.
- *
- * @param text - Text possibly containing ANSI sequences.
- * @returns The text with all ANSI sequences removed.
- */
-export declare function ansi_strip(text: string): string;

package/dist/core/sink.js

@@ -1,300 +0,0 @@
-/**
- * @file Output sink: the seam through which command output leaves the engine.
- *
- * Builtins historically printed straight to process stdout, which fuses the
- * engine to a terminal. The sink inverts that: output is written to whatever
- * sink the host installed, and only the host knows where bytes finally go
- * (a terminal for the CLI REPL, a capture buffer for pipes, a connection for
- * a remote surface).
- *
- * Three channels are distinguished. Data is the command's actual output: it
- * is accumulated into the command's result envelope and is what capture,
- * piping and redirection consume. Err is the error stream: presented to the
- * user, never piped, never captured. Status is ephemeral (spinners,
- * progress, transient messages): displayed live, never accumulated, never
- * piped.
- *
- * This module also provides delivery helpers that bridge envelope-returning
- * builtins into the existing dispatch table, so conversion can proceed one
- * builtin at a time while unconverted builtins keep printing.
- *
- * @see docs/calypso.adoc for the governing design.
- * @module
- */
-import { TerminalProgressRenderer } from './progressRenderer.js';
-function sink_streamsEnvelopeOutput(sink) {
-    return sink.liveEnvelopeOutput === true;
-}
-/**
- * Sink that writes both channels to the process's standard output.
- *
- * This is the CLI host's sink and the default, preserving the shell's
- * historical behavior exactly.
- */
-export class StdoutSink {
-    progressRenderer;
-    constructor(progressRenderer = new TerminalProgressRenderer()) {
-        this.progressRenderer = progressRenderer;
-    }
-    /** @inheritdoc */
-    data_write(chunk) {
-        process.stdout.write(chunk);
-    }
-    /** @inheritdoc */
-    err_write(chunk) {
-        process.stderr.write(chunk);
-    }
-    /** @inheritdoc */
-    status_write(text) {
-        process.stdout.write(text);
-    }
-    progress_write(event) {
-        this.progressRenderer.write(event);
-    }
-}
-/**
- * Sink that accumulates the data channel in memory and drops status.
- *
- * Used by capture paths and tests; will carry the pipe and redirect
- * machinery once those consume envelopes.
- */
-export class BufferSink {
-    chunks = [];
-    /** @inheritdoc */
-    data_write(chunk) {
-        this.chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf-8') : chunk);
-    }
-    /** @inheritdoc */
-    err_write(chunk) {
-        // The err channel is never captured: today's pipe and redirect paths
-        // inherit stderr, so error output must keep reaching the terminal even
-        // while data is being buffered.
-        process.stderr.write(chunk);
-    }
-    /** @inheritdoc */
-    status_write(_text) {
-        // Status is ephemeral by contract: never accumulated.
-    }
-    progress_write(_event) {
-        // Progress is ephemeral by contract: never accumulated.
-    }
-    /**
-     * Returns everything written to the data channel so far.
-     *
-     * @returns The accumulated bytes.
-     */
-    buffer_get() {
-        return Buffer.concat(this.chunks);
-    }
-    /**
-     * Returns the accumulated data channel as UTF-8 text.
-     *
-     * @returns The accumulated text.
-     */
-    text_get() {
-        return this.buffer_get().toString('utf-8');
-    }
-}
-/**
- * Sink that captures the data and err channels while passing status through
- * to a live sink, so transients (spinners, progress) remain visible while a
- * legacy printing command's output is being gathered into an envelope.
- */
-export class CaptureSink {
-    dataChunks = [];
-    errChunks = [];
-    live;
-    forwardEnvelopeOutput;
-    /**
-     * Initializes the capture around a live sink for status passthrough.
-     *
-     * @param live - The sink that continues to receive status writes.
-     */
-    constructor(live, options = {}) {
-        this.live = live;
-        this.forwardEnvelopeOutput = options.forwardEnvelopeOutput ?? false;
-    }
-    /** @inheritdoc */
-    data_write(chunk) {
-        this.dataChunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf-8') : chunk);
-        if (this.forwardEnvelopeOutput) {
-            this.live.data_write(chunk);
-        }
-    }
-    /** @inheritdoc */
-    err_write(chunk) {
-        this.errChunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf-8') : chunk);
-        if (this.forwardEnvelopeOutput) {
-            this.live.err_write(chunk);
-        }
-    }
-    /** @inheritdoc */
-    status_write(text) {
-        this.live.status_write(text);
-    }
-    progress_write(event) {
-        this.live.progress_write(event);
-    }
-    /**
-     * Returns the captured data channel as UTF-8 text.
-     *
-     * @returns The captured data text.
-     */
-    dataText_get() {
-        return Buffer.concat(this.dataChunks).toString('utf-8');
-    }
-    /**
-     * Returns the captured err channel as UTF-8 text.
-     *
-     * @returns The captured error-stream text.
-     */
-    errText_get() {
-        return Buffer.concat(this.errChunks).toString('utf-8');
-    }
-}
-/** The active sink. Defaults to stdout so every entry point behaves as the CLI always has. */
-let activeSink = new StdoutSink();
-/**
- * Returns the currently installed sink.
- *
- * @returns The active output sink.
- */
-export function sink_get() {
-    return activeSink;
-}
-/**
- * Installs a sink. Called by the host that owns the output destination.
- *
- * @param sink - The sink to install.
- * @returns The previously installed sink, so callers can restore it.
- */
-export function sink_set(sink) {
-    const previous = activeSink;
-    activeSink = sink;
-    return previous;
-}
-/**
- * Delivers a completed envelope to the active sink.
- *
- * Rendered text goes to the data channel and error-stream text to the err
- * channel. The structured errors field is machine-facing and is not
- * presented here: its terminal presentation, when any, travels in
- * renderedErr.
- *
- * @param envelope - The completed command envelope.
- */
-export function envelope_deliver(envelope) {
-    if (envelope.rendered.length > 0) {
-        activeSink.data_write(envelope.rendered);
-    }
-    if (envelope.renderedErr !== undefined && envelope.renderedErr.length > 0) {
-        activeSink.err_write(envelope.renderedErr);
-    }
-}
-/**
- * Adapts an envelope-returning builtin to the legacy printing handler shape.
- *
- * This is the compatibility bridge for incremental conversion: converted
- * builtins return envelopes, and this wrapper delivers them through the
- * active sink so the dispatch table, pipes and redirects need no changes.
- * A handler that resolves without an envelope (as stubbed handlers in tests
- * do) is treated as having produced no output.
- *
- * @param handler - An envelope-returning command handler.
- * @returns A handler with the legacy void-returning shape.
- */
-export function envelopeHandler_wrap(handler) {
-    return async (args) => {
-        const envelope = await handler(args);
-        if (!envelope) {
-            return;
-        }
-        envelope_deliver(envelope);
-    };
-}
-/**
- * Adapts a legacy printing builtin to the envelope-returning shape.
- *
- * This is the capture bridge for commands whose rendering lives below the
- * seam (chili's table display prints internally): the handler runs with the
- * data and err channels captured, console printing redirected into the
- * capture, and status passed through live so spinners stay visible. The
- * result is an envelope carrying the exact bytes each stream would have
- * shown, with the status derived from the process exit code the handler set.
- *
- * Bridged commands gain envelope semantics without typed models; native
- * conversion (models, streamed data) remains the end state for commands
- * where a structural consumer exists.
- *
- * @param handler - A legacy printing command handler.
- * @returns An envelope-returning handler with identical observable output.
- */
-export function printingHandler_wrap(handler) {
-    return async (args) => {
-        const capture = new CaptureSink(activeSink, {
-            forwardEnvelopeOutput: sink_streamsEnvelopeOutput(activeSink),
-        });
-        const previousSink = sink_set(capture);
-        const originalLog = console.log;
-        const originalError = console.error;
-        const originalStdoutWrite = process.stdout.write.bind(process.stdout);
-        const exitCodeBefore = typeof process.exitCode === 'number' ? process.exitCode : 0;
-        console.log = (...logArgs) => {
-            const text = logArgs
-                .map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg)))
-                .join(' ');
-            capture.data_write(`${text}\n`);
-        };
-        console.error = (...logArgs) => {
-            const text = logArgs
-                .map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg)))
-                .join(' ');
-            capture.err_write(`${text}\n`);
-        };
-        process.stdout.write = ((chunk) => {
-            if (typeof chunk === 'string' || Buffer.isBuffer(chunk)) {
-                capture.data_write(chunk);
-            }
-            else if (chunk instanceof Uint8Array) {
-                capture.data_write(Buffer.from(chunk));
-            }
-            return true;
-        });
-        try {
-            await handler(args);
-        }
-        finally {
-            console.log = originalLog;
-            console.error = originalError;
-            process.stdout.write = originalStdoutWrite;
-            sink_set(previousSink);
-        }
-        const exitCodeAfter = typeof process.exitCode === 'number' ? process.exitCode : 0;
-        const failed = exitCodeAfter !== 0 && exitCodeAfter !== exitCodeBefore;
-        const rendered = capture.dataText_get();
-        const renderedErr = capture.errText_get();
-        const envelope = { status: failed ? 'error' : 'ok', rendered };
-        if (renderedErr.length > 0) {
-            envelope.renderedErr = renderedErr;
-        }
-        return envelope;
-    };
-}
-/** Matches ANSI escape sequences (SGR colors, cursor movement, erase). */
-const ANSI_PATTERN = /\x1b\[[0-9;?]*[a-zA-Z]/g;
-/**
- * Strips ANSI escape sequences from text.
- *
- * Applied at the pipe and redirect boundary so downstream consumers receive
- * plain text, the way programs behind a real shell pipe see no color. This
- * is a deliberate, documented deviation from the historical behavior, in
- * which escape bytes leaked into pipes because color detection saw the
- * terminal regardless of capture.
- *
- * @param text - Text possibly containing ANSI sequences.
- * @returns The text with all ANSI sequences removed.
- */
-export function ansi_strip(text) {
-    return text.replace(ANSI_PATTERN, '');
-}
-//# sourceMappingURL=sink.js.map

package/dist/core/sink.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sink.js","sourceRoot":"","sources":["../../src/core/sink.ts"],"names":[],"mappings":"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"}

package/dist/core/surface.d.ts

@@ -1,172 +0,0 @@
-/**
- * @file Surface capabilities: the input/interaction seam a host provides.
- *
- * The output sink (`./sink.js`) lets a host decide where a command's output
- * goes. This module is its input-side counterpart: it lets a host declare
- * what *interaction* it can offer — prompting for a line, reading a secret
- * without echo, opening a local editor — and lets a builtin ask for a
- * capability and fail with a clear message when the attached surface cannot
- * provide it, rather than hanging on a standard input that is not there.
- *
- * The CLI host backs this with readline and the local `$EDITOR`; a future
- * daemon backs it with request messages to a remote surface, and a surface
- * that cannot (say) open a local editor simply declares `localEdit: false`.
- *
- * Capabilities the surface can act on directly (prompting) are methods here;
- * capabilities a builtin still performs itself (local editing, whose editor
- * mechanics remain in the `edit` builtin until a remote surface needs its
- * own implementation) are declared as flags a builtin gates on via
- * {@link capability_require}. This module is deliberately free of Node
- * built-ins so it stays trivially testable and host-agnostic; the readline
- * implementation lives in `./cliSurface.js`.
- *
- * @see docs/calypso.adoc — "Interactivity is a declared surface capability".
- * @module
- */
-/**
- * What interaction an attached surface can provide.
- *
- * @property hiddenInput - The surface can read a line without echoing it
- *   (password entry).
- * @property localEdit - The surface can open content in a local editor and
- *   return the edited result.
- * @property tty - The surface is an interactive terminal (as opposed to a
- *   pipe, a script, or a headless host).
- * @property pipeSegments - The surface can run a pipeline's non-first
- *   segments (`... | grep foo`) through its own tools. Nothing ever spawns on
- *   a daemon host: the local CLI runs segments in-process, a remote CLI runs
- *   them on the client machine, and a browser surface lacks the capability
- *   and fails such pipelines with a clear message.
- */
-export interface SurfaceCapabilities {
-    hiddenInput: boolean;
-    localEdit: boolean;
-    tty: boolean;
-    pipeSegments: boolean;
-}
-/**
- * A request to prompt the user for a line of input.
- *
- * @property message - The prompt text to display.
- * @property hidden - When true, the entered text is not echoed; requires the
- *   `hiddenInput` capability.
- */
-export interface PromptRequest {
-    message: string;
-    hidden?: boolean;
-}
-/**
- * Content handed to a surface's local editor.
- *
- * @property content - The text to open in the editor.
- * @property extension - Optional filename extension (e.g. `.txt`, `.json`) so
- *   the editor can apply the right syntax mode.
- */
-export interface LocalEditRequest {
-    content: string;
-    extension?: string;
-}
-/**
- * The outcome of a local edit.
- *
- * @property content - The content after editing.
- * @property changed - Whether the content differs from what was opened.
- */
-export interface LocalEditResult {
-    content: string;
-    changed: boolean;
-}
-/**
- * The interaction seam a host installs. Builtins reach it through
- * {@link surface_get}; hosts declare their capabilities and back the
- * prompt and local-edit operations with whatever their surface supports.
- */
-export interface Surface {
-    /** What this surface can do; read by builtins before they interact. */
-    readonly capabilities: SurfaceCapabilities;
-    /**
-     * Prompts for a line of input.
-     *
-     * @param request - The prompt message and whether to hide the input.
-     * @returns The entered line, trimmed.
-     * @throws {CapabilityError} When hidden input is requested but the surface
-     *   lacks the `hiddenInput` capability, or the surface cannot prompt.
-     */
-    prompt(request: PromptRequest): Promise<string>;
-    /**
-     * Runs one pipeline segment against an input, returning its output. Where
-     * this runs is the surface's business — in-process for the local CLI, on
-     * the client machine for a remote CLI — but never on a daemon host.
-     *
-     * @param command - The segment command line (e.g. `grep foo`).
-     * @param input - The bytes to feed the segment on stdin.
-     * @returns The segment's stdout.
-     * @throws {CapabilityError} When the surface lacks the `pipeSegments`
-     *   capability.
-     */
-    pipeSegment(command: string, input: Buffer): Promise<Buffer>;
-    /**
-     * Opens content in the surface's local editor and returns the result. The
-     * editor mechanics are the surface's business — a temp file and `$EDITOR`
-     * for the local CLI, the client's editor for a remote CLI, an editor
-     * component in a browser.
-     *
-     * @param request - The content to edit and an optional extension.
-     * @returns The edited content and whether it changed.
-     * @throws {CapabilityError} When the surface lacks the `localEdit`
-     *   capability.
-     */
-    localEdit(request: LocalEditRequest): Promise<LocalEditResult>;
-}
-/**
- * Raised when a builtin requests an interaction the attached surface cannot
- * provide. Carries the capability name so a host can present it uniformly.
- */
-export declare class CapabilityError extends Error {
-    /** The capability that was required but absent. */
-    readonly capability: keyof SurfaceCapabilities;
-    /**
-     * @param capability - The missing capability.
-     * @param message - Human-readable explanation.
-     */
-    constructor(capability: keyof SurfaceCapabilities, message: string);
-}
-/**
- * The default surface for a host that has not installed one: it can do
- * nothing interactive and says so clearly. This is the correct default for
- * an unknown host — a CLI host replaces it (see `./cliSurface.js`), and any
- * attempt to prompt or edit before a real surface is installed fails loudly
- * instead of hanging.
- */
-export declare class HeadlessSurface implements Surface {
-    /** @inheritdoc */
-    readonly capabilities: SurfaceCapabilities;
-    /** @inheritdoc */
-    prompt(_request: PromptRequest): Promise<string>;
-    /** @inheritdoc */
-    pipeSegment(_command: string, _input: Buffer): Promise<Buffer>;
-    /** @inheritdoc */
-    localEdit(_request: LocalEditRequest): Promise<LocalEditResult>;
-}
-/**
- * Returns the currently installed surface.
- *
- * @returns The active surface.
- */
-export declare function surface_get(): Surface;
-/**
- * Installs a surface. Called by the host that owns the interaction channel.
- *
- * @param surface - The surface to install.
- * @returns The previously installed surface, so callers can restore it.
- */
-export declare function surface_set(surface: Surface): Surface;
-/**
- * Asserts that the active surface has a capability, throwing a
- * {@link CapabilityError} with a clear message when it does not.
- *
- * @param capability - The capability the caller needs.
- * @param message - The message to present when it is absent.
- * @throws {CapabilityError} When the active surface lacks the capability.
- */
-export declare function capability_require(capability: keyof SurfaceCapabilities, message: string): void;