@fnndsc/brasa 0.1.0

package/dist/core/engine.d.ts

@@ -0,0 +1,91 @@
+import type { CommandEnvelope } from '@fnndsc/cumin';
+/**
+ * Result of a completion request: the candidates and the prefix they
+ * complete, matching what a readline completer consumes.
+ *
+ * @property candidates - The matching completion candidates.
+ * @property prefix - The input prefix the candidates complete.
+ */
+export interface CompletionResult {
+    candidates: string[];
+    prefix: string;
+}
+/**
+ * The hostable shell engine.
+ *
+ * One engine serves one session: it executes command lines against the
+ * shared session state and answers completion requests. Hosts own the
+ * output destination (via the sink) and the input source (a readline loop,
+ * a socket); the engine owns everything between.
+ */
+export interface BrasaEngine {
+    /**
+     * Executes one input line and returns one envelope per executed command.
+     *
+     * @param line - The raw input line (may contain `;`, `|`, `>`, `!`).
+     * @returns The envelopes of the executed commands, in execution order.
+     */
+    line_execute(line: string): Promise<CommandEnvelope[]>;
+    /**
+     * Computes completion candidates for a partial input line.
+     *
+     * @param linePrefix - The input line up to the cursor.
+     * @returns The matching candidates and the prefix they complete.
+     */
+    line_complete(linePrefix: string): Promise<CompletionResult>;
+}
+/**
+ * Sets the shared stop-on-error flag. Exposed so the boot layer (which owns
+ * the `-e` flag and script execution) can drive the flag that the batch
+ * loop reads.
+ *
+ * @param value - `true` to abort a batch on the first error.
+ */
+export declare function stopOnError_set(value: boolean): void;
+/**
+ * Executes one input line and returns one envelope per executed command.
+ *
+ * Line-level constructs are recognized in the shell's historical order:
+ * shell escape first (the whole line goes to the host shell), then
+ * semicolon batching (each segment recurses through this function), then
+ * output redirection, then pipes, then plain dispatch. Output reaches the
+ * active sink as each command completes.
+ *
+ * @param line - The raw input line.
+ * @returns The envelopes of the executed commands, in execution order.
+ */
+export declare function line_execute(line: string): Promise<CommandEnvelope[]>;
+/**
+ * Computes completion candidates for a partial input line.
+ *
+ * Promise-shaped facade over the callback-style completer, for hosts that
+ * answer completion requests asynchronously (a remote surface's tab press).
+ * Completion failures resolve to no candidates; they never reject, matching
+ * the completer's own never-crash contract.
+ *
+ * @param linePrefix - The input line up to the cursor.
+ * @returns The matching candidates and the prefix they complete.
+ */
+export declare function line_complete(linePrefix: string): Promise<CompletionResult>;
+/**
+ * Handles a command entered by the user.
+ *
+ * Compatibility shape over {@link line_execute} for callers that do not
+ * consume envelopes.
+ *
+ * @param line - The input line.
+ * @returns A Promise that resolves once the command has been processed.
+ */
+export declare function command_handle(line: string): Promise<void>;
+/**
+ * Creates the engine: initializes session state, registers the VFS
+ * providers, and returns the facade a host drives.
+ *
+ * Establishing a CUBE connection is deliberately not the engine's concern —
+ * connection setup involves host-owned interaction (credential prompting,
+ * boot reporting) and the engine executes correctly both offline and
+ * connected.
+ *
+ * @returns The engine facade.
+ */
+export declare function engine_create(): Promise<BrasaEngine>;

package/dist/core/engine.js

@@ -0,0 +1,222 @@
+/**
+ * @file The chell engine facade: line execution and completion behind one
+ * hostable interface.
+ *
+ * The engine is the seam between the shell's deterministic core (dispatch,
+ * session, VFS) and whatever hosts it. The CLI REPL is one host; a session
+ * daemon serving remote surfaces is the next. A host creates the engine,
+ * installs an output sink, and drives it one line at a time:
+ *
+ * ```
+ * const engine: BrasaEngine = await engine_create();
+ * const envelopes: CommandEnvelope[] = await engine.line_execute('ls; pwd');
+ * ```
+ *
+ * `line_execute` owns line-level orchestration — shell escape, semicolon
+ * batching, redirects, pipes — and yields exactly one envelope per executed
+ * command. Output is delivered through the active sink as each command
+ * completes, so a terminal host sees output live; the returned envelopes are
+ * the records an envelope-aware host (daemon, test) consumes.
+ *
+ * Single-command execution and the command table live in `./dispatch.js`;
+ * this module deliberately keeps its cumin imports type-only.
+ *
+ * @see docs/calypso.adoc for the governing design.
+ * @module
+ */
+import chalk from 'chalk';
+import { session } from '../session/index.js';
+import { semicolons_parse } from '../lib/semicolonParser.js';
+import { pipes_parse, redirect_parse, command_shellEscape_detect, } from './preprocess.js';
+import { shellCommand_execute, command_executeToEnvelope, command_timingMaybePrint, redirect_execute, pipe_execute, } from './dispatch.js';
+/**
+ * Whether a batch (semicolon list, script) should abort on the first error.
+ * Read by the batch loop; set by the boot layer for `-e` / script modes.
+ */
+let stopOnError = false;
+/**
+ * Sets the shared stop-on-error flag. Exposed so the boot layer (which owns
+ * the `-e` flag and script execution) can drive the flag that the batch
+ * loop reads.
+ *
+ * @param value - `true` to abort a batch on the first error.
+ */
+export function stopOnError_set(value) {
+    stopOnError = value;
+}
+/**
+ * Executes a shell-escaped line (`!command`) on the host system.
+ *
+ * @param trimmedLine - The trimmed input line including the leading `!`.
+ * @param startTime - Timing reference from `performance.now()`.
+ * @param timingEnabled - Whether to print elapsed time after execution.
+ * @returns One envelope carrying the host command's outcome, or none for a
+ *   bare `!`.
+ */
+async function shellEscape_execute(trimmedLine, startTime, timingEnabled) {
+    const shellCommand = trimmedLine.substring(1).trim();
+    if (!shellCommand)
+        return [];
+    const exitCode = await shellCommand_execute(shellCommand);
+    command_timingMaybePrint(startTime, timingEnabled);
+    return [{ status: exitCode === 0 ? 'ok' : 'error', rendered: '' }];
+}
+/**
+ * Executes a semicolon batch, one segment at a time, collecting each
+ * segment's envelopes.
+ *
+ * A segment that throws yields an error envelope; the batch continues unless
+ * stop-on-error is set, in which case the envelopes collected so far are
+ * returned immediately (and no total time is printed, matching the shell's
+ * historical behavior).
+ *
+ * @param commands - The batch segments in execution order.
+ * @param startTime - Timing reference from `performance.now()`.
+ * @param timingEnabled - Whether to print the batch's total elapsed time.
+ * @returns The envelopes of all executed segments, in execution order.
+ */
+async function batch_execute(commands, startTime, timingEnabled) {
+    const envelopes = [];
+    for (const command of commands) {
+        try {
+            envelopes.push(...await line_execute(command));
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(chalk.red(`Command error: ${msg}`));
+            envelopes.push({ status: 'error', rendered: '' });
+            if (stopOnError) {
+                return envelopes;
+            }
+        }
+    }
+    if (timingEnabled) {
+        const elapsed = performance.now() - startTime;
+        console.log(chalk.gray(`[Total: ${elapsed.toFixed(2)}ms]`));
+    }
+    return envelopes;
+}
+/**
+ * Executes one input line and returns one envelope per executed command.
+ *
+ * Line-level constructs are recognized in the shell's historical order:
+ * shell escape first (the whole line goes to the host shell), then
+ * semicolon batching (each segment recurses through this function), then
+ * output redirection, then pipes, then plain dispatch. Output reaches the
+ * active sink as each command completes.
+ *
+ * @param line - The raw input line.
+ * @returns The envelopes of the executed commands, in execution order.
+ */
+export async function line_execute(line) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine)
+        return [];
+    // Start timing if enabled
+    const timingEnabled = session.timingEnabled_get();
+    const startTime = timingEnabled ? performance.now() : 0;
+    if (command_shellEscape_detect(trimmedLine)) {
+        return shellEscape_execute(trimmedLine, startTime, timingEnabled);
+    }
+    const batch = semicolons_parse(trimmedLine);
+    if (batch.length > 1) {
+        return batch_execute(batch, startTime, timingEnabled);
+    }
+    const redirectInfo = redirect_parse(trimmedLine);
+    if (redirectInfo) {
+        const envelope = await redirect_execute(redirectInfo);
+        if (envelope.status === 'ok') {
+            command_timingMaybePrint(startTime, timingEnabled);
+        }
+        return [envelope];
+    }
+    const pipeSegments = pipes_parse(trimmedLine);
+    if (pipeSegments.length > 1) {
+        try {
+            const envelope = await pipe_execute(pipeSegments);
+            command_timingMaybePrint(startTime, timingEnabled);
+            return [envelope];
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(chalk.red(`Pipe error: ${msg}`));
+            return [{ status: 'error', rendered: '' }];
+        }
+    }
+    const envelope = await command_executeToEnvelope(trimmedLine, startTime, timingEnabled);
+    return envelope ? [envelope] : [];
+}
+/**
+ * Computes completion candidates for a partial input line.
+ *
+ * Promise-shaped facade over the callback-style completer, for hosts that
+ * answer completion requests asynchronously (a remote surface's tab press).
+ * Completion failures resolve to no candidates; they never reject, matching
+ * the completer's own never-crash contract.
+ *
+ * @param linePrefix - The input line up to the cursor.
+ * @returns The matching candidates and the prefix they complete.
+ */
+export async function line_complete(linePrefix) {
+    const { input_complete } = await import('../lib/completer/index.js');
+    return new Promise((resolve) => {
+        input_complete(linePrefix, (err, result) => {
+            if (err || !result) {
+                resolve({ candidates: [], prefix: linePrefix });
+                return;
+            }
+            resolve({ candidates: result[0], prefix: result[1] });
+        });
+    });
+}
+/**
+ * Handles a command entered by the user.
+ *
+ * Compatibility shape over {@link line_execute} for callers that do not
+ * consume envelopes.
+ *
+ * @param line - The input line.
+ * @returns A Promise that resolves once the command has been processed.
+ */
+export async function command_handle(line) {
+    await line_execute(line);
+}
+/**
+ * Registers the static VFS providers and the logical→physical path resolver
+ * hook on the shared salsa vfsDispatcher.
+ */
+async function vfsProviders_register() {
+    const { vfsDispatcher } = await import('@fnndsc/salsa');
+    const { StaticVfsProvider } = await import('../lib/vfs/providers/static.js');
+    vfsDispatcher.provider_register(new StaticVfsProvider('/bin'));
+    vfsDispatcher.provider_register(new StaticVfsProvider('/usr'));
+    vfsDispatcher.provider_register(new StaticVfsProvider('/usr/bin'));
+    vfsDispatcher.pathResolver_register(async (logicalPath) => {
+        if (session.physicalMode_get()) {
+            return logicalPath;
+        }
+        const { logical_toPhysical } = await import('@fnndsc/chili/utils');
+        const res = await logical_toPhysical(logicalPath);
+        if (res.ok) {
+            return res.value;
+        }
+        throw new Error(`Logical-to-physical resolution failed for path: ${logicalPath}`);
+    });
+}
+/**
+ * Creates the engine: initializes session state, registers the VFS
+ * providers, and returns the facade a host drives.
+ *
+ * Establishing a CUBE connection is deliberately not the engine's concern —
+ * connection setup involves host-owned interaction (credential prompting,
+ * boot reporting) and the engine executes correctly both offline and
+ * connected.
+ *
+ * @returns The engine facade.
+ */
+export async function engine_create() {
+    await session.init();
+    await vfsProviders_register();
+    return { line_execute, line_complete };
+}
+//# sourceMappingURL=engine.js.map

package/dist/core/engine.js.map

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

package/dist/core/preprocess.d.ts

@@ -0,0 +1,46 @@
+import { Result } from '@fnndsc/cumin';
+/**
+ * Determines if a command should have its arguments expanded for wildcards.
+ *
+ * @param command - The command name.
+ * @returns True if wildcards should be expanded.
+ */
+export declare function wildcards_expandCheck(command: string): boolean;
+/**
+ * Returns true if the input line is a shell escape (starts with `!`).
+ *
+ * @param line - Trimmed input line.
+ */
+export declare function command_shellEscape_detect(line: string): boolean;
+/**
+ * Parses a command line for pipe operators and returns segments.
+ * Respects single and double quotes.
+ *
+ * @param line - The full command line.
+ * @returns An array of command segments.
+ */
+export declare function pipes_parse(line: string): string[];
+/** Parsed output-redirection: command plus target file and append/overwrite. */
+export interface RedirectInfo {
+    command: string;
+    operator: '>' | '>>';
+    filePath: string;
+}
+/**
+ * Parses a command line for output redirection operators (> or >>).
+ * Respects single and double quotes.
+ *
+ * @param line - The full command line.
+ * @returns An object with the command and redirect info, or null if no redirection.
+ */
+export declare function redirect_parse(line: string): RedirectInfo | null;
+/**
+ * Resolves the final redirect target path. If the target is an existing directory
+ * and the source command is `cat <file>`, resolves to `<dir>/<basename>`.
+ * Returns Err (with message on errorStack) when the filename cannot be determined.
+ *
+ * @param filePath - The redirect target path as written by the user.
+ * @param commandLine - The command whose output is being redirected.
+ * @returns Ok(resolved path) or Err on failure.
+ */
+export declare function redirectTarget_resolve(filePath: string, commandLine: string): Result<string>;

package/dist/core/preprocess.js

@@ -0,0 +1,146 @@
+/**
+ * @file Command-line preprocessing: pure parsing of pipes, redirects and
+ * wildcard/shell-escape detection.
+ *
+ * @module
+ */
+import * as path from 'path';
+import { statSync } from 'fs';
+import { Ok, Err, errorStack } from '@fnndsc/cumin';
+import { args_tokenize } from '../lib/parser.js';
+/** Commands whose arguments benefit from glob/wildcard expansion. */
+const WILDCARD_COMMANDS = ['ls', 'rm', 'cat', 'mv', 'cp', 'du', 'tree'];
+/**
+ * Determines if a command should have its arguments expanded for wildcards.
+ *
+ * @param command - The command name.
+ * @returns True if wildcards should be expanded.
+ */
+export function wildcards_expandCheck(command) {
+    return WILDCARD_COMMANDS.includes(command);
+}
+/**
+ * Returns true if the input line is a shell escape (starts with `!`).
+ *
+ * @param line - Trimmed input line.
+ */
+export function command_shellEscape_detect(line) {
+    return line.startsWith('!');
+}
+/**
+ * Parses a command line for pipe operators and returns segments.
+ * Respects single and double quotes.
+ *
+ * @param line - The full command line.
+ * @returns An array of command segments.
+ */
+export function pipes_parse(line) {
+    const segments = [];
+    let currentSegment = '';
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    for (let i = 0; i < line.length; i++) {
+        const char = line[i];
+        if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+            currentSegment += char;
+        }
+        else if (char === '"' && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+            currentSegment += char;
+        }
+        else if (char === '|' && !inSingleQuote && !inDoubleQuote) {
+            segments.push(currentSegment.trim());
+            currentSegment = '';
+        }
+        else {
+            currentSegment += char;
+        }
+    }
+    if (currentSegment.trim()) {
+        segments.push(currentSegment.trim());
+    }
+    return segments;
+}
+/**
+ * Parses a command line for output redirection operators (> or >>).
+ * Respects single and double quotes.
+ *
+ * @param line - The full command line.
+ * @returns An object with the command and redirect info, or null if no redirection.
+ */
+export function redirect_parse(line) {
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    for (let i = 0; i < line.length; i++) {
+        const char = line[i];
+        if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+        }
+        else if (char === '"' && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+        }
+        else if (!inSingleQuote && !inDoubleQuote) {
+            // Check for >>
+            if (i < line.length - 1 && line[i] === '>' && line[i + 1] === '>') {
+                const command = line.substring(0, i).trim();
+                const filePath = line.substring(i + 2).trim();
+                return { command, operator: '>>', filePath };
+            }
+            // Check for >
+            else if (line[i] === '>') {
+                const command = line.substring(0, i).trim();
+                const filePath = line.substring(i + 1).trim();
+                return { command, operator: '>', filePath };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolves the final redirect target path. If the target is an existing directory
+ * and the source command is `cat <file>`, resolves to `<dir>/<basename>`.
+ * Returns Err (with message on errorStack) when the filename cannot be determined.
+ *
+ * @param filePath - The redirect target path as written by the user.
+ * @param commandLine - The command whose output is being redirected.
+ * @returns Ok(resolved path) or Err on failure.
+ */
+export function redirectTarget_resolve(filePath, commandLine) {
+    try {
+        const stats = statSync(filePath);
+        if (!stats.isDirectory()) {
+            return Ok(filePath);
+        }
+    }
+    catch (err) {
+        const nodeErr = err;
+        if (nodeErr.code === 'ENOENT') {
+            return Ok(filePath);
+        }
+        errorStack.stack_push('error', `Redirect: filesystem error for '${filePath}': ${String(err)}`);
+        return Err();
+    }
+    const tokens = args_tokenize(commandLine);
+    if (tokens.length === 0) {
+        errorStack.stack_push('error', `Redirect target '${filePath}' is a directory and no source command was provided.`);
+        return Err();
+    }
+    const [command, ...args] = tokens;
+    if (command !== 'cat') {
+        errorStack.stack_push('error', `Redirect target '${filePath}' is a directory; cannot infer filename for command '${command}'.`);
+        return Err();
+    }
+    const sourceArgs = args.filter((arg) => arg !== '--binary');
+    if (sourceArgs.length === 0) {
+        errorStack.stack_push('error', `Redirect target '${filePath}' is a directory; no source file provided to 'cat'.`);
+        return Err();
+    }
+    if (sourceArgs.length > 1) {
+        errorStack.stack_push('error', `Redirect target '${filePath}' is a directory; 'cat' with multiple files cannot choose a single output name.`);
+        return Err();
+    }
+    const sourceName = path.basename(sourceArgs[0]);
+    return Ok(path.join(filePath, sourceName));
+}
+//# sourceMappingURL=preprocess.js.map

package/dist/core/preprocess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preprocess.js","sourceRoot":"","sources":["../../src/core/preprocess.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAC9B,OAAO,EAAU,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,qEAAqE;AACrE,MAAM,iBAAiB,GAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,cAAc,GAAW,EAAE,CAAC;IAChC,IAAI,aAAa,GAAY,KAAK,CAAC;IACnC,IAAI,aAAa,GAAY,KAAK,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAW,IAAI,CAAC,CAAC,CAAC,CAAC;QAE7B,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACnC,aAAa,GAAG,CAAC,aAAa,CAAC;YAC/B,cAAc,IAAI,IAAI,CAAC;QACzB,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAC1C,aAAa,GAAG,CAAC,aAAa,CAAC;YAC/B,cAAc,IAAI,IAAI,CAAC;QACzB,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,aAAa,EAAE,CAAC;YAC5D,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;YACrC,cAAc,GAAG,EAAE,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,cAAc,IAAI,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAED,IAAI,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,aAAa,GAAY,KAAK,CAAC;IACnC,IAAI,aAAa,GAAY,KAAK,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAW,IAAI,CAAC,CAAC,CAAC,CAAC;QAE7B,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACnC,aAAa,GAAG,CAAC,aAAa,CAAC;QACjC,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAC1C,aAAa,GAAG,CAAC,aAAa,CAAC;QACjC,CAAC;aAAM,IAAI,CAAC,aAAa,IAAI,CAAC,aAAa,EAAE,CAAC;YAC5C,eAAe;YACf,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAClE,MAAM,OAAO,GAAW,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACpD,MAAM,QAAQ,GAAW,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACtD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC/C,CAAC;YACD,cAAc;iBACT,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACzB,MAAM,OAAO,GAAW,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACpD,MAAM,QAAQ,GAAW,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACtD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB,EAAE,WAAmB;IAC1E,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAA0B,GAA4B,CAAC;QACpE,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtB,CAAC;QACD,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,mCAAmC,QAAQ,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/F,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAa,aAAa,CAAC,WAAW,CAAC,CAAC;IACpD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,QAAQ,sDAAsD,CAAC,CAAC;QACnH,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IAED,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;QACtB,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,QAAQ,wDAAwD,OAAO,IAAI,CAAC,CAAC;QAChI,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IAED,MAAM,UAAU,GAAa,IAAI,CAAC,MAAM,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC;IAC9E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,QAAQ,qDAAqD,CAAC,CAAC;QAClH,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,QAAQ,iFAAiF,CAAC,CAAC;QAC9I,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IAED,MAAM,UAAU,GAAW,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/core/progress.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file Structured progress events emitted by commands and rendered by hosts.
+ *
+ * Progress is semantic live telemetry. It is not command output, is never
+ * captured into envelopes, and is never consumed by pipes or redirects.
+ *
+ * @module
+ */
+export type ProgressOperation = 'upload' | 'download' | 'pull' | 'workflow';
+export type ProgressKind = 'transfer' | 'retrieve' | 'workflow';
+export type ProgressPhase = 'scanning' | 'transferring' | 'watching' | 'retrying' | 'complete' | 'failed';
+export type ProgressUnit = 'files' | 'bytes' | 'series' | 'jobs' | 'nodes';
+export type ProgressStatus = 'running' | 'done' | 'unconfirmed' | 'stalled' | 'timeout' | 'error' | 'unknown';
+export interface ProgressEvent {
+    operation: ProgressOperation;
+    kind?: ProgressKind;
+    phase: ProgressPhase;
+    label?: string;
+    itemId?: string;
+    current?: number;
+    total?: number;
+    percent?: number;
+    unit?: ProgressUnit;
+    status?: ProgressStatus;
+}
+/**
+ * Renders progress events for a frontend.
+ *
+ * The engine emits {@link ProgressEvent}s and knows nothing about how they are
+ * shown. Each frontend supplies its own implementation: a terminal draws bars,
+ * a daemon forwards the events over its wire, a headless host drops them.
+ */
+export interface ProgressRenderer {
+    /**
+     * Renders a single progress event.
+     *
+     * @param event - The progress telemetry to render.
+     */
+    write(event: ProgressEvent): void;
+}
+/**
+ * Progress renderer that drops every event.
+ *
+ * The engine's default when no frontend has supplied a live renderer, so
+ * headless hosts incur no terminal coupling.
+ */
+export declare class NullProgressRenderer implements ProgressRenderer {
+    /** @inheritdoc */
+    write(_event: ProgressEvent): void;
+}

package/dist/core/progress.js

@@ -0,0 +1,21 @@
+/**
+ * @file Structured progress events emitted by commands and rendered by hosts.
+ *
+ * Progress is semantic live telemetry. It is not command output, is never
+ * captured into envelopes, and is never consumed by pipes or redirects.
+ *
+ * @module
+ */
+/**
+ * Progress renderer that drops every event.
+ *
+ * The engine's default when no frontend has supplied a live renderer, so
+ * headless hosts incur no terminal coupling.
+ */
+export class NullProgressRenderer {
+    /** @inheritdoc */
+    write(_event) {
+        // Progress is live telemetry: with no frontend to render it, it is dropped.
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/core/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/core/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqCH;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAC/B,kBAAkB;IACX,KAAK,CAAC,MAAqB;QAChC,4EAA4E;IAC9E,CAAC;CACF"}

package/dist/core/promptContext.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file The session's prompt context: the engine-known facts a prompt reflects.
+ *
+ * A prompt shows live session state — user, CUBE, working directory, PACS,
+ * physical-mode, warm-up progress — plus the last command's outcome. Only the
+ * process holding the session can know these, but how they are *rendered*
+ * (theme, segments, terminal width) is a frontend concern. This module builds
+ * the engine half; each frontend renders it with its own theme, so the daemon
+ * ships context and never a themed string.
+ *
+ * @module
+ */
+/**
+ * The engine-known facts a prompt reflects, independent of any theme.
+ *
+ * This is the shape carried over the wire to remote frontends. Rendering
+ * inputs a frontend owns (terminal width, enabled segments, theme) are not
+ * here — each surface supplies its own.
+ */
+export interface SessionPromptContext {
+    user: string;
+    uri: string;
+    cwd: string;
+    pacsserver: string | null;
+    physicalMode: boolean;
+    lastExitCode: number;
+    lastCommandDurationMs: number;
+    /** Present while /proc topology warm-up is in progress. */
+    procWarmup?: {
+        loaded: number;
+    };
+}
+/**
+ * Inputs the caller knows that the session state does not.
+ *
+ * @property lastExitCode - The previous command's exit code (default 0).
+ * @property lastCommandDurationMs - The previous command's duration (default 0).
+ */
+export interface SessionPromptContextOptions {
+    lastExitCode?: number;
+    lastCommandDurationMs?: number;
+}
+/**
+ * Builds the current session's prompt context.
+ *
+ * @param options - The last-command inputs the session cannot know.
+ * @returns The engine-known prompt facts.
+ */
+export declare function sessionPromptContext_build(options?: SessionPromptContextOptions): Promise<SessionPromptContext>;