@fnndsc/brasa 0.1.0

package/dist/config/storeConfig.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Engine store configuration: which ChRIS peer store the engine targets.
+ *
+ * This is engine state, not a surface preference: the `store` builtin reads and
+ * mutates it. The value lives here, but where it is persisted is the host's
+ * concern — a CLI writes it to a settings file, a daemon may hold it per
+ * session, a headless host keeps it in memory. The host installs a persistence
+ * callback via {@link storeConfigPersist_install}; with none installed the
+ * value simply lives for the process, so the engine carries no file or path
+ * knowledge of its own.
+ *
+ * @module
+ */
+/** Built-in peer store used when the operator has set no override. */
+export declare const DEFAULT_STORE_URL: string;
+/**
+ * Returns the peer store URL in effect, falling back to the built-in default.
+ *
+ * @returns The store URL to use.
+ */
+export declare function storeUrl_get(): string;
+/**
+ * Reports whether the effective store URL is the built-in default.
+ *
+ * @returns True when no override is set.
+ */
+export declare function storeUrl_isDefault(): boolean;
+/**
+ * Returns the operator's override without applying the default.
+ *
+ * The persistence layer uses this so it writes only an explicit override.
+ *
+ * @returns The override URL, or undefined when none is set.
+ */
+export declare function storeUrlOverride_get(): string | undefined;
+/**
+ * Sets the peer store override.
+ *
+ * @param url - The store URL to use.
+ */
+export declare function storeUrl_set(url: string): void;
+/**
+ * Clears the peer store override, restoring the built-in default.
+ */
+export declare function storeUrl_clear(): void;
+/**
+ * Installs the host's persistence hook.
+ *
+ * @param fn - Callback invoked to persist the current store configuration.
+ */
+export declare function storeConfigPersist_install(fn: () => Promise<void>): void;
+/**
+ * Persists the current store configuration through the installed hook.
+ *
+ * @returns A promise resolving once persistence completes.
+ */
+export declare function storeConfig_persist(): Promise<void>;

package/dist/config/storeConfig.js

@@ -0,0 +1,78 @@
+/**
+ * @file Engine store configuration: which ChRIS peer store the engine targets.
+ *
+ * This is engine state, not a surface preference: the `store` builtin reads and
+ * mutates it. The value lives here, but where it is persisted is the host's
+ * concern — a CLI writes it to a settings file, a daemon may hold it per
+ * session, a headless host keeps it in memory. The host installs a persistence
+ * callback via {@link storeConfigPersist_install}; with none installed the
+ * value simply lives for the process, so the engine carries no file or path
+ * knowledge of its own.
+ *
+ * @module
+ */
+/** Built-in peer store used when the operator has set no override. */
+export const DEFAULT_STORE_URL = 'https://cube.chrisproject.org/api/v1/';
+/** The operator's override, or undefined to use {@link DEFAULT_STORE_URL}. */
+let storeUrl;
+/** Host-installed persistence hook; the default keeps the value in memory. */
+let persist = async () => {
+    // Headless default: the override lives for the process and is not persisted.
+};
+/**
+ * Returns the peer store URL in effect, falling back to the built-in default.
+ *
+ * @returns The store URL to use.
+ */
+export function storeUrl_get() {
+    return storeUrl ?? DEFAULT_STORE_URL;
+}
+/**
+ * Reports whether the effective store URL is the built-in default.
+ *
+ * @returns True when no override is set.
+ */
+export function storeUrl_isDefault() {
+    return storeUrl === undefined;
+}
+/**
+ * Returns the operator's override without applying the default.
+ *
+ * The persistence layer uses this so it writes only an explicit override.
+ *
+ * @returns The override URL, or undefined when none is set.
+ */
+export function storeUrlOverride_get() {
+    return storeUrl;
+}
+/**
+ * Sets the peer store override.
+ *
+ * @param url - The store URL to use.
+ */
+export function storeUrl_set(url) {
+    storeUrl = url;
+}
+/**
+ * Clears the peer store override, restoring the built-in default.
+ */
+export function storeUrl_clear() {
+    storeUrl = undefined;
+}
+/**
+ * Installs the host's persistence hook.
+ *
+ * @param fn - Callback invoked to persist the current store configuration.
+ */
+export function storeConfigPersist_install(fn) {
+    persist = fn;
+}
+/**
+ * Persists the current store configuration through the installed hook.
+ *
+ * @returns A promise resolving once persistence completes.
+ */
+export async function storeConfig_persist() {
+    await persist();
+}
+//# sourceMappingURL=storeConfig.js.map

package/dist/config/storeConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeConfig.js","sourceRoot":"","sources":["../../src/config/storeConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,iBAAiB,GAAW,uCAAuC,CAAC;AAEjF,8EAA8E;AAC9E,IAAI,QAA4B,CAAC;AAEjC,8EAA8E;AAC9E,IAAI,OAAO,GAAwB,KAAK,IAAmB,EAAE;IAC3D,6EAA6E;AAC/E,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,QAAQ,IAAI,iBAAiB,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,QAAQ,KAAK,SAAS,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,QAAQ,GAAG,GAAG,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,EAAuB;IAChE,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,OAAO,EAAE,CAAC;AAClB,CAAC"}

package/dist/core/chiliDelegate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Delegation to the chili command layer.
+ *
+ * Unknown commands and several resource builtins hand off to chili. This lives
+ * in its own leaf module so both the dispatcher and those builtins can call it
+ * without importing each other — dispatch imports the builtins, so routing the
+ * delegation through dispatch would close a cycle.
+ *
+ * @module
+ */
+/**
+ * Runs a chili command in-process.
+ *
+ * chili shares this process's cumin connection and context, so there is no node
+ * subprocess to spawn and no per-command startup cost.
+ *
+ * @param command - The command to run (e.g., "feeds").
+ * @param args - The arguments to pass to the command.
+ * @returns A promise resolving when the command completes.
+ */
+export declare function chiliCommand_run(command: string, args: string[]): Promise<void>;

package/dist/core/chiliDelegate.js

@@ -0,0 +1,32 @@
+/**
+ * @file Delegation to the chili command layer.
+ *
+ * Unknown commands and several resource builtins hand off to chili. This lives
+ * in its own leaf module so both the dispatcher and those builtins can call it
+ * without importing each other — dispatch imports the builtins, so routing the
+ * delegation through dispatch would close a cycle.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+import { run as chiliRun } from '@fnndsc/chili/run.js';
+/**
+ * Runs a chili command in-process.
+ *
+ * chili shares this process's cumin connection and context, so there is no node
+ * subprocess to spawn and no per-command startup cost.
+ *
+ * @param command - The command to run (e.g., "feeds").
+ * @param args - The arguments to pass to the command.
+ * @returns A promise resolving when the command completes.
+ */
+export async function chiliCommand_run(command, args) {
+    try {
+        await chiliRun([command, ...args]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`chili command '${command}' failed: ${message}`));
+    }
+}
+//# sourceMappingURL=chiliDelegate.js.map

package/dist/core/chiliDelegate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chiliDelegate.js","sourceRoot":"","sources":["../../src/core/chiliDelegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,GAAG,IAAI,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAe,EAAE,IAAc;IACpE,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAW,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,OAAO,aAAa,OAAO,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC"}

package/dist/core/connect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Headless session connect: restore a ChRIS connection from saved creds.
+ *
+ * This is the non-interactive half of establishing a session — load the saved
+ * context and validate its token against the server. It carries no terminal
+ * output of its own: it returns a status a frontend narrates (the CLI prints
+ * progress; a daemon logs or exits). Interactive login (prompting for a URL and
+ * password) is a frontend concern and lives with the CLI, not here.
+ *
+ * @module
+ */
+import { SingleContext } from '@fnndsc/cumin';
+/**
+ * The outcome of a saved-session restore.
+ *
+ * - `restored` — a saved token validated against the server.
+ * - `no-context` — no saved user/URL to restore.
+ * - `no-token` — a saved context but no token; connect again to obtain one.
+ * - `no-client` — a token, but a client could not be created.
+ * - `invalid-token` — a token that the server rejected (expired/invalid).
+ */
+export type SavedSessionStatus = 'restored' | 'no-context' | 'no-token' | 'no-client' | 'invalid-token';
+/** The result of {@link sessionConnect_fromSaved}. */
+export interface SavedSessionResult {
+    status: SavedSessionStatus;
+    context: SingleContext;
+    /** The server error message when the status is `invalid-token`. */
+    error?: string;
+}
+/**
+ * Restores a session from saved credentials, without any prompting.
+ *
+ * On any failure the session is put into offline mode. The caller narrates the
+ * outcome; a daemon treats anything but `restored` as "not connected".
+ *
+ * @returns The restore outcome and the resolved context.
+ */
+export declare function sessionConnect_fromSaved(): Promise<SavedSessionResult>;

package/dist/core/connect.js

@@ -0,0 +1,46 @@
+/**
+ * @file Headless session connect: restore a ChRIS connection from saved creds.
+ *
+ * This is the non-interactive half of establishing a session — load the saved
+ * context and validate its token against the server. It carries no terminal
+ * output of its own: it returns a status a frontend narrates (the CLI prints
+ * progress; a daemon logs or exits). Interactive login (prompting for a URL and
+ * password) is a frontend concern and lives with the CLI, not here.
+ *
+ * @module
+ */
+import { session } from '../session/index.js';
+import { context_getSingle } from '@fnndsc/salsa';
+/**
+ * Restores a session from saved credentials, without any prompting.
+ *
+ * On any failure the session is put into offline mode. The caller narrates the
+ * outcome; a daemon treats anything but `restored` as "not connected".
+ *
+ * @returns The restore outcome and the resolved context.
+ */
+export async function sessionConnect_fromSaved() {
+    const context = await context_getSingle();
+    if (!context.user || !context.URL) {
+        return { status: 'no-context', context };
+    }
+    const token = await session.connection.authToken_get(true);
+    if (!token) {
+        session.offline = true;
+        return { status: 'no-token', context };
+    }
+    try {
+        const client = await session.connection.client_get();
+        if (!client) {
+            session.offline = true;
+            return { status: 'no-client', context };
+        }
+        await client.getUser();
+        return { status: 'restored', context };
+    }
+    catch (error) {
+        session.offline = true;
+        return { status: 'invalid-token', context, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=connect.js.map

package/dist/core/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/core/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAsBlD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB;IAC5C,MAAM,OAAO,GAAkB,MAAM,iBAAiB,EAAE,CAAC;IAEzD,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QACpE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QAC1C,CAAC;QACD,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7G,CAAC;AACH,CAAC"}

package/dist/core/dispatch.d.ts

@@ -0,0 +1,95 @@
+import type { CommandEnvelope } from '@fnndsc/cumin';
+import { type RedirectInfo } from './preprocess.js';
+import { chiliCommand_run } from './chiliDelegate.js';
+export { chiliCommand_run };
+/**
+ * Executes a shell command on the host system (shell escape with ! prefix).
+ *
+ * @param shellCommand - The command to execute on the host shell.
+ * @returns A Promise resolving to the command's exit code (1 on spawn failure).
+ */
+export declare function shellCommand_execute(shellCommand: string): Promise<number>;
+type CommandHandler = (args: string[]) => Promise<void>;
+/**
+ * Shape of a converted builtin: returns its outcome as an envelope instead
+ * of printing. The engine layer will consume these directly; the dispatch
+ * table below consumes them through {@link envelopeHandler_wrap}.
+ */
+type EnvelopeHandler = (args: string[]) => Promise<CommandEnvelope>;
+export declare const ENVELOPE_HANDLERS: Record<string, EnvelopeHandler>;
+export declare const COMMAND_HANDLERS: Record<string, CommandHandler>;
+export { COMMAND_HANDLERS_KEYS } from '../command-keys.js';
+/**
+ * Prints elapsed time since startTime if timing is enabled.
+ *
+ * @param startTime - Timestamp from `performance.now()` at command start.
+ * @param enabled - Whether timing display is active.
+ */
+export declare function command_timingMaybePrint(startTime: number, enabled: boolean): void;
+/**
+ * Expands `$NAME` and `${NAME}` environment references in one token.
+ *
+ * Applied per token after parsing, so an expanded value can never inject
+ * command separators, pipes or redirects (the structural characters were
+ * already consumed). References to unset variables are left verbatim —
+ * kinder than the shell's silent empty string when a script forgets an
+ * export. Shell-escape lines (`!...`) never reach this point; bash does
+ * its own expansion there.
+ *
+ * @param token - A single parsed command token.
+ * @returns The token with set environment references substituted.
+ */
+export declare function envRefs_expand(token: string): string;
+/**
+ * Dispatches a parsed command to its handler and returns its envelope, with
+ * any errors the command left on the stack drained into the envelope.
+ *
+ * @param command - The command name.
+ * @param args - Parsed arguments.
+ * @returns The envelope of the executed command.
+ */
+export declare function command_dispatchEnvelope(command: string, args: string[]): Promise<CommandEnvelope>;
+/**
+ * Dispatches a parsed command to its handler.
+ *
+ * Compatibility shape over {@link command_dispatchEnvelope} for callers that
+ * do not consume envelopes.
+ *
+ * @param command - The command name.
+ * @param args - Parsed arguments.
+ * @returns A Promise that resolves once the command has been dispatched.
+ */
+export declare function command_dispatch(command: string, args: string[]): Promise<void>;
+/**
+ * Executes a redirected command (`>` / `>>`): captures the command's output
+ * and writes it to the target file.
+ *
+ * @param redirectInfo - The parsed redirection (command, operator, target).
+ * @returns An envelope recording the outcome; rendered text stays empty
+ *   because the output went to the file, not the terminal.
+ */
+export declare function redirect_execute(redirectInfo: RedirectInfo): Promise<CommandEnvelope>;
+/**
+ * Executes a pipe chain by running the first command in chell and piping
+ * through local tools, delivering the final output on the data channel.
+ *
+ * @param segments - Array of command segments separated by pipes.
+ * @returns An envelope whose rendered text is the chain's final output.
+ */
+export declare function pipe_execute(segments: string[]): Promise<CommandEnvelope>;
+/**
+ * Executes one plain command line (no shell escape, batch, redirect or pipe)
+ * and returns its envelope.
+ *
+ * Mirrors the historical direct-execution order exactly: help flag
+ * short-circuit, wildcard expansion, simulated plugin execution, then table
+ * dispatch. Timing is printed at the same points the shell always printed
+ * it (after plugin execution or dispatch; never after help or a wildcard
+ * failure).
+ *
+ * @param trimmedLine - The trimmed command line.
+ * @param startTime - Timing reference from `performance.now()`.
+ * @param timingEnabled - Whether to print elapsed time after execution.
+ * @returns The command's envelope, or null when the line held no tokens.
+ */
+export declare function command_executeToEnvelope(trimmedLine: string, startTime: number, timingEnabled: boolean): Promise<CommandEnvelope | null>;