@fnndsc/calypso 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FNNDSC / BCH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @fnndsc/calypso
+
+**CALYPSO** **A**ccepts **L**anguage, **Y**ielding **P**ermitted **S**hell **O**perations — the intent layer and session daemon of the [mise](../../README.md) stack.
+
+The name is a harbor reference. In the *Odyssey*, Calypso keeps the island where the voyager finds haven; the name is the Greek word for "to conceal," which the project keeps but turns around. **HARBOR** is that haven for the ChRIS operator, and CALYPSO is the keeper at its edge — the layer between you and the open water: the Collection+JSON sprawl, the complexity of a federated backend. What CALYPSO conceals is the friction, never the outcome. A harbor shelters without holding: the work is left as materialized, verifiable state, yours to leave and return to — CALYPSO the harbor you pass through, never the ground you stand on.
+
+## What this package is
+
+CALYPSO hosts the [chell](../chell/README.md) engine behind a **session daemon** and serves it to surfaces over a WebSocket: the CLI today, a web console next, each rendering the same session. Because the engine is separable from its display (see [stage one](../../docs/calypso.adoc)), it can run where the data must stay — inside a spoke's trust boundary — while an operator drives it over a thin client.
+
+This first slice is the **wire contract**: the typed protocol schemas and boundary validation every message crosses. The daemon, the session bus, and the remote client build on it.
+
+## The wire contract
+
+The contract is defined as [zod](https://zod.dev) schemas — the single source of truth, from which the message types are inferred and against which every message is validated at the boundary.
+
+- **Messages** (two direction-keyed unions):
+  - surface → daemon: `attach {protocolVersion, token, session?}`, `execute {id, line}`, `complete {id, prefix}`
+  - daemon → surface: `attached`, `result {id, envelopes}`, `complete {id, prefix, candidates}`, `output {id, channel, chunk}`, `session {surface, envelope}`, `error`
+- **Envelope** — the `commandEnvelopeSchema` validates cumin's `CommandEnvelope` on the wire; a compile-time guard keeps the schema in step with cumin's type so the published contract can never silently drift from what the code produces.
+- **Boundary validation** — structural violations are rejected; unknown *additive* fields are tolerated, so a daemon accepts extensions from a newer minor without understanding them. Parsing never throws.
+- **Versioning** — the contract version (`CONTRACT_VERSION`) is carried in the attach handshake and refused on mismatch; within a major, changes are additive only.
+
+```ts
+import { clientMessage_fromJson, attach_parse, type ClientMessage } from '@fnndsc/calypso';
+
+const parsed = clientMessage_fromJson(rawSocketText);
+if (!parsed.ok) socket.send({ type: 'error', reason: parsed.error });
+```
+
+## Status
+
+Design-in-progress, not shipped. The full design — daemon, session bus, remote client, and the eventual natural-language intent layer that only ever *proposes* commands the deterministic shell validates and runs — is in [docs/calypso.adoc](../../docs/calypso.adoc) (the staged plan) and [docs/surfaces.adoc](../../docs/surfaces.adoc).

package/dist/daemon/engine.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file The engine seam the daemon hosts.
+ *
+ * The daemon is deliberately engine-agnostic: it accepts anything shaped like
+ * a hosted engine rather than importing chell directly. This keeps calypso's
+ * dependencies to cumin and the wire libraries, and — because chell will
+ * import calypso's wire contract for its remote client — avoids a package
+ * cycle. chell's `ChellEngine` structurally satisfies this interface, so the
+ * launcher (in chell) creates a real engine and hands it to the daemon.
+ *
+ * @module
+ */
+import type { CommandEnvelope } from '@fnndsc/cumin';
+/**
+ * A completion answer: the candidates and the prefix they complete.
+ *
+ * @property candidates - The matching completion candidates.
+ * @property prefix - The input prefix the candidates complete.
+ */
+export interface CompletionResult {
+    candidates: string[];
+    prefix: string;
+}
+/**
+ * The engine the daemon drives. Matches chell's `ChellEngine` structurally,
+ * so a real chell engine is assignable to it without calypso depending on
+ * chell.
+ */
+export interface HostedEngine {
+    /**
+     * Executes one input line, yielding one envelope per executed command.
+     *
+     * @param line - The raw input line.
+     * @returns The envelopes of the executed commands, in 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>;
+}

package/dist/daemon/engine.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=engine.js.map

package/dist/daemon/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/daemon/engine.ts"],"names":[],"mappings":""}

package/dist/daemon/server.d.ts

@@ -0,0 +1,217 @@
+import type { HostedEngine } from './engine.js';
+import type { ProgressEvent } from '../protocol/messages.js';
+/** The result of a surface's local edit, returned by {@link CalypsoDaemon.edit_current}. */
+export interface EditOutcome {
+    content: string;
+    changed: boolean;
+}
+/**
+ * Options for creating a daemon.
+ *
+ * @property engine - The engine to host.
+ * @property token - The attach token a surface must present.
+ * @property port - The port to bind; 0 (default) picks an ephemeral port.
+ * @property host - The interface to bind; loopback (`127.0.0.1`) by default.
+ * @property scrollbackSize - How many recent envelopes to retain for replay
+ *   to an attaching surface; defaults to 200.
+ * @property promptProvider - Renders the current session's themed prompt
+ *   string, which the daemon pushes to surfaces after each command and on
+ *   attach. Omitted when a host does not push a prompt (e.g. tests).
+ */
+export interface DaemonOptions {
+    engine: HostedEngine;
+    token: string;
+    port?: number;
+    host?: string;
+    scrollbackSize?: number;
+    promptProvider?: () => string | Promise<string>;
+}
+/**
+ * A WebSocket daemon hosting one engine for attached surfaces, with a session
+ * bus broadcasting activity across them.
+ */
+export declare class CalypsoDaemon {
+    private readonly engine;
+    private readonly token;
+    private readonly port;
+    private readonly host;
+    private readonly scrollbackSize;
+    private readonly promptProvider;
+    /** The one session all surfaces share; returned in each attach ack. */
+    private readonly sessionId;
+    private readonly surfaces;
+    private readonly scrollback;
+    private wss;
+    /**
+     * Execution is serialized across the whole session (one foreground command
+     * at a time), so a prompt raised mid-command has one unambiguous surface to
+     * ask — the one running the current command.
+     */
+    private queue;
+    private currentOrigin;
+    private currentId;
+    private readonly pendingPrompts;
+    private promptSeq;
+    private readonly pendingPipes;
+    private pipeSeq;
+    private readonly pendingEdits;
+    private editSeq;
+    /**
+     * @param options - The engine to host, the attach token, the bind address,
+     *   and the scrollback size.
+     */
+    constructor(options: DaemonOptions);
+    /**
+     * Starts listening.
+     *
+     * @returns The bound port (useful when an ephemeral port was requested).
+     */
+    start(): Promise<number>;
+    /**
+     * Stops listening and closes all connections.
+     *
+     * @returns A promise resolving when the server has closed.
+     */
+    stop(): Promise<void>;
+    /**
+     * Handles one surface connection: an attach handshake, then serialized
+     * command dispatch, with the surface removed from the bus on close.
+     *
+     * @param socket - The connected surface.
+     */
+    private connection_handle;
+    /**
+     * Validates an attach handshake: contract version, then constant-time
+     * token check. On success the surface is acknowledged, registered on the
+     * bus, and replayed the scrollback so it does not join blind; on failure it
+     * is told why and disconnected.
+     *
+     * @param socket - The connecting surface.
+     * @param raw - The first message received.
+     * @returns The registered surface, or null when the attach was refused.
+     */
+    private attach_handle;
+    /**
+     * Renders the current prompt (when the host supplies a provider) and pushes
+     * it to a surface, or to all surfaces when none is given. Called after each
+     * command — the context may have changed — and on attach.
+     *
+     * @param target - The surface to push to; omitted to push to all.
+     */
+    private promptline_push;
+    /**
+     * Replays the retained scrollback to a freshly attached surface as session
+     * events, so it arrives seeing recent activity rather than blank.
+     *
+     * @param socket - The surface to replay to.
+     */
+    private scrollback_replay;
+    /**
+     * Records an envelope in scrollback (trimming to the retention bound) and
+     * broadcasts it to every attached surface except the one that produced it,
+     * which already received it as the correlated `result`.
+     *
+     * @param origin - The surface that produced the envelope.
+     * @param envelope - The envelope to publish.
+     */
+    private bus_publish;
+    /**
+     * Runs one execute request: replies to the requester with the result, and
+     * publishes each envelope to the session bus.
+     *
+     * @param origin - The surface that submitted the request.
+     * @param message - The execute request.
+     */
+    private execute_run;
+    /**
+     * Raises a prompt on the surface running the current command, returning its
+     * answer. The host installs an engine-side input broker that calls this; the
+     * engine therefore prompts through the wire without knowing the transport.
+     *
+     * @param message - The prompt text to show.
+     * @param hidden - Whether to request no-echo entry (a password).
+     * @returns The surface's answer.
+     * @throws {Error} When no command is executing (nothing to prompt for) or the
+     *   surface disconnects before answering.
+     */
+    prompt_current(message: string, hidden: boolean): Promise<string>;
+    /**
+     * Streams structured progress from the executing command to its origin
+     * surface. Progress is live-only; when no command is active or the surface is
+     * gone, the event is dropped.
+     *
+     * @param event - The structured progress facts.
+     * @returns True when the event was sent to a surface.
+     */
+    progress_current(event: ProgressEvent): boolean;
+    /**
+     * Streams an opaque live output chunk from the executing command to its
+     * origin surface. Output is live telemetry, distinct from final envelopes;
+     * when no command is active or the origin surface is gone, it is dropped.
+     *
+     * @param channel - The output channel that produced the chunk.
+     * @param chunk - The text chunk to forward.
+     * @returns True when the chunk was sent to a surface.
+     */
+    output_current(channel: 'data' | 'err' | 'status', chunk: string): boolean;
+    /**
+     * Resolves a pending prompt with the surface's answer.
+     *
+     * @param promptId - The prompt correlation id.
+     * @param answer - The answer the surface supplied.
+     */
+    private promptAnswer_settle;
+    /**
+     * Runs a pipeline segment on the surface running the current command,
+     * returning its output. The host installs a `pipeSegment` on its engine-side
+     * surface that calls this, so a pipeline's segments run on the client and
+     * never on the daemon host. Data crosses the wire base64-encoded.
+     *
+     * @param command - The segment command line.
+     * @param input - The bytes to feed the segment.
+     * @returns The segment's output bytes.
+     * @throws {Error} When no command is executing or the surface disconnects.
+     */
+    pipe_current(command: string, input: Buffer): Promise<Buffer>;
+    /**
+     * Resolves a pending pipe segment with the surface's output.
+     *
+     * @param pipeId - The pipe correlation id.
+     * @param output - The base64-encoded segment output.
+     */
+    private pipeResult_settle;
+    /**
+     * Opens content in the editor of the surface running the current command
+     * and returns the edited result. The host installs a `localEdit` on its
+     * engine-side surface that calls this, so `edit` opens the operator's own
+     * editor and never one on the daemon host.
+     *
+     * @param content - The content to edit.
+     * @param extension - An optional filename extension for syntax mode.
+     * @returns The edited content and whether it changed.
+     * @throws {Error} When no command is executing or the surface disconnects.
+     */
+    edit_current(content: string, extension: string | undefined): Promise<EditOutcome>;
+    /**
+     * Resolves a pending edit with the surface's result.
+     *
+     * @param editId - The edit correlation id.
+     * @param outcome - The edited content and changed flag.
+     */
+    private editResult_settle;
+    /**
+     * Runs one completion request and sends its reply, or an error. Completion
+     * is a read and is not broadcast.
+     *
+     * @param socket - The surface to reply to.
+     * @param message - The completion request.
+     */
+    private complete_run;
+    /**
+     * Sends a message to a surface if the socket is still open.
+     *
+     * @param socket - The destination surface.
+     * @param message - The message to send.
+     */
+    private send;
+}