@fnndsc/calypso 0.2.0

package/dist/protocol/messages.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverMessageSchema = exports.editMessageSchema = exports.pipeMessageSchema = exports.promptLineMessageSchema = exports.promptMessageSchema = exports.errorMessageSchema = exports.sessionMessageSchema = exports.progressMessageSchema = exports.progressStatusSchema = exports.progressUnitSchema = exports.progressPhaseSchema = exports.progressKindSchema = exports.progressOperationSchema = exports.outputMessageSchema = exports.completeReplySchema = exports.resultMessageSchema = exports.attachedMessageSchema = exports.clientMessageSchema = exports.editResultMessageSchema = exports.pipeResultMessageSchema = exports.promptAnswerMessageSchema = exports.completeRequestSchema = exports.executeMessageSchema = exports.attachMessageSchema = exports.channelSchema = void 0;
+/**
+ * @file The wire-contract message schemas.
+ *
+ * Two discriminated unions, one per direction, keyed on a `type` tag:
+ * {@link clientMessageSchema} (surface → daemon) and
+ * {@link serverMessageSchema} (daemon → surface). Every request carries a
+ * correlation `id` so its reply and any streamed output can be matched to
+ * it, and output events carry the sink channel they belong to. These schemas
+ * are the single source of truth for the protocol; the human-readable
+ * description in `docs/calypso.adoc` is checked against them.
+ *
+ * @module
+ */
+const zod_1 = require("zod");
+const envelope_js_1 = require("./envelope.js");
+/** The sink channel an output event belongs to. */
+exports.channelSchema = zod_1.z.enum(['data', 'err', 'status']);
+// --- Surface → daemon ------------------------------------------------------
+/** Attach to a session: declares the contract version and the attach token. */
+exports.attachMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('attach'),
+    protocolVersion: zod_1.z.number().int(),
+    token: zod_1.z.string(),
+    session: zod_1.z.string().optional(),
+});
+/** Execute one input line, correlated by `id`. */
+exports.executeMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('execute'),
+    id: zod_1.z.string(),
+    line: zod_1.z.string(),
+});
+/** Request completion candidates for a partial line, correlated by `id`. */
+exports.completeRequestSchema = zod_1.z.object({
+    type: zod_1.z.literal('complete'),
+    id: zod_1.z.string(),
+    prefix: zod_1.z.string(),
+});
+/** Answers a prompt the daemon requested during a command, correlated by `promptId`. */
+exports.promptAnswerMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('promptAnswer'),
+    promptId: zod_1.z.string(),
+    answer: zod_1.z.string(),
+});
+/** Returns the output of a pipeline segment the daemon asked the surface to run, correlated by `pipeId`. */
+exports.pipeResultMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('pipeResult'),
+    pipeId: zod_1.z.string(),
+    output: zod_1.z.string(),
+});
+/** Returns the edited content from a local-edit the daemon requested, correlated by `editId`. */
+exports.editResultMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('editResult'),
+    editId: zod_1.z.string(),
+    content: zod_1.z.string(),
+    changed: zod_1.z.boolean(),
+});
+/** Any message a surface may send to the daemon. */
+exports.clientMessageSchema = zod_1.z.discriminatedUnion('type', [
+    exports.attachMessageSchema,
+    exports.executeMessageSchema,
+    exports.completeRequestSchema,
+    exports.promptAnswerMessageSchema,
+    exports.pipeResultMessageSchema,
+    exports.editResultMessageSchema,
+]);
+// --- Daemon → surface ------------------------------------------------------
+/** Acknowledges a successful attach. */
+exports.attachedMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('attached'),
+    session: zod_1.z.string(),
+    protocolVersion: zod_1.z.number().int(),
+});
+/** The final result of one executed line: one envelope per command. */
+exports.resultMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('result'),
+    id: zod_1.z.string(),
+    envelopes: zod_1.z.array(envelope_js_1.commandEnvelopeSchema),
+});
+/** The reply to a completion request. */
+exports.completeReplySchema = zod_1.z.object({
+    type: zod_1.z.literal('complete'),
+    id: zod_1.z.string(),
+    prefix: zod_1.z.string(),
+    candidates: zod_1.z.array(zod_1.z.string()),
+});
+/** A streamed output event on one channel, correlated to its command. */
+exports.outputMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('output'),
+    id: zod_1.z.string(),
+    channel: exports.channelSchema,
+    chunk: zod_1.z.string(),
+});
+/** The operation producing structured progress. */
+exports.progressOperationSchema = zod_1.z.enum(['upload', 'download', 'pull', 'workflow']);
+/** Broad class of progress producer. */
+exports.progressKindSchema = zod_1.z.enum(['transfer', 'retrieve', 'workflow']);
+/** Lifecycle phase of a progress operation. */
+exports.progressPhaseSchema = zod_1.z.enum(['scanning', 'transferring', 'watching', 'retrying', 'complete', 'failed']);
+/** Unit used by the primary progress counter. */
+exports.progressUnitSchema = zod_1.z.enum(['files', 'bytes', 'series', 'jobs', 'nodes']);
+/** State of the operation or item being reported. */
+exports.progressStatusSchema = zod_1.z.enum(['running', 'done', 'unconfirmed', 'stalled', 'timeout', 'error', 'unknown']);
+/** A structured progress event correlated to a command. */
+exports.progressMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('progress'),
+    id: zod_1.z.string(),
+    operation: exports.progressOperationSchema,
+    kind: exports.progressKindSchema.optional(),
+    phase: exports.progressPhaseSchema,
+    label: zod_1.z.string().optional(),
+    itemId: zod_1.z.string().optional(),
+    current: zod_1.z.number().nonnegative().optional(),
+    total: zod_1.z.number().nonnegative().optional(),
+    percent: zod_1.z.number().min(0).max(100).optional(),
+    unit: exports.progressUnitSchema.optional(),
+    status: exports.progressStatusSchema.optional(),
+});
+/** A session-bus broadcast: an envelope tagged with its originating surface. */
+exports.sessionMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('session'),
+    surface: zod_1.z.string(),
+    envelope: envelope_js_1.commandEnvelopeSchema,
+});
+/** A boundary error: a refused attach, a malformed message, correlated when possible. */
+exports.errorMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('error'),
+    id: zod_1.z.string().optional(),
+    reason: zod_1.z.string(),
+});
+/**
+ * A prompt request the daemon raises during a command: the surface that
+ * submitted the command must answer it (with `promptAnswer`) before the
+ * command can proceed. `hidden` requests no-echo entry (password).
+ */
+exports.promptMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('prompt'),
+    promptId: zod_1.z.string(),
+    message: zod_1.z.string(),
+    hidden: zod_1.z.boolean(),
+});
+/**
+ * The themed prompt string, pushed by the daemon with each result and on any
+ * context change. Only the daemon knows the session context the prompt
+ * renders; a surface prints what it receives, so prompt themes work
+ * identically everywhere.
+ */
+exports.promptLineMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('promptline'),
+    text: zod_1.z.string(),
+});
+/**
+ * Asks the surface to run a pipeline segment on its own machine (never on the
+ * daemon host) and return the output. `input` and the reply's `output` are
+ * base64, since segment data is arbitrary bytes.
+ */
+exports.pipeMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('pipe'),
+    pipeId: zod_1.z.string(),
+    command: zod_1.z.string(),
+    input: zod_1.z.string(),
+});
+/**
+ * Asks the surface to open content in its local editor (never on the daemon
+ * host) and return the edited result.
+ */
+exports.editMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal('edit'),
+    editId: zod_1.z.string(),
+    content: zod_1.z.string(),
+    extension: zod_1.z.string().optional(),
+});
+/** Any message the daemon may send to a surface. */
+exports.serverMessageSchema = zod_1.z.discriminatedUnion('type', [
+    exports.attachedMessageSchema,
+    exports.resultMessageSchema,
+    exports.completeReplySchema,
+    exports.outputMessageSchema,
+    exports.progressMessageSchema,
+    exports.sessionMessageSchema,
+    exports.errorMessageSchema,
+    exports.promptMessageSchema,
+    exports.promptLineMessageSchema,
+    exports.pipeMessageSchema,
+    exports.editMessageSchema,
+]);
+//# sourceMappingURL=messages.js.map

package/dist/protocol/messages.js.map

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

package/dist/protocol/validate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Boundary validation.
+ *
+ * Every message is validated on the way in and out. Structural violations
+ * (missing required fields, wrong types, an unknown `type`) are rejected;
+ * unknown *additional* fields are tolerated (stripped), so a daemon accepts
+ * additive extensions from a newer minor without understanding them. Parsing
+ * never throws — it returns a {@link ParseResult} so the caller can answer a
+ * malformed message with an `error` message rather than dropping the socket.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { attachMessageSchema, type ClientMessage, type ServerMessage } from './messages.js';
+/**
+ * The outcome of validating a message at the boundary.
+ *
+ * @property ok - Whether the input was a valid message.
+ * @property value - The parsed message, when `ok`.
+ * @property error - A human-readable reason, when not `ok`.
+ */
+export interface ParseResult<T> {
+    ok: boolean;
+    value?: T;
+    error?: string;
+}
+/**
+ * Validates a message a surface sent to the daemon.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+export declare function clientMessage_parse(raw: unknown): ParseResult<ClientMessage>;
+/**
+ * Validates a message the daemon sent to a surface.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+export declare function serverMessage_parse(raw: unknown): ParseResult<ServerMessage>;
+/**
+ * Parses a JSON string into a client message, rejecting both malformed JSON
+ * and structurally invalid messages with a clear reason.
+ *
+ * @param json - The raw JSON text received on the socket.
+ * @returns The parse result.
+ */
+export declare function clientMessage_fromJson(json: string): ParseResult<ClientMessage>;
+/**
+ * Validates an attach message and checks its declared contract version
+ * against this build. A structurally valid attach on an incompatible major
+ * is rejected with a clear reason.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result; an incompatible version is a validation failure.
+ */
+export declare function attach_parse(raw: unknown): ParseResult<z.infer<typeof attachMessageSchema>>;

package/dist/protocol/validate.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientMessage_parse = clientMessage_parse;
+exports.serverMessage_parse = serverMessage_parse;
+exports.clientMessage_fromJson = clientMessage_fromJson;
+exports.attach_parse = attach_parse;
+const messages_js_1 = require("./messages.js");
+const version_js_1 = require("./version.js");
+/**
+ * Formats a Zod error into a compact, single-line boundary reason.
+ *
+ * @param error - The Zod validation error.
+ * @returns A human-readable reason string.
+ */
+function zodError_format(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.join('.');
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join('; ');
+}
+/**
+ * Validates a raw value against a schema, never throwing.
+ *
+ * @param schema - The schema to validate against.
+ * @param raw - The untrusted input.
+ * @returns The parse result.
+ */
+function schema_parse(schema, raw) {
+    const result = schema.safeParse(raw);
+    if (result.success) {
+        return { ok: true, value: result.data };
+    }
+    return { ok: false, error: zodError_format(result.error) };
+}
+/**
+ * Validates a message a surface sent to the daemon.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+function clientMessage_parse(raw) {
+    return schema_parse(messages_js_1.clientMessageSchema, raw);
+}
+/**
+ * Validates a message the daemon sent to a surface.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+function serverMessage_parse(raw) {
+    return schema_parse(messages_js_1.serverMessageSchema, raw);
+}
+/**
+ * Parses a JSON string into a client message, rejecting both malformed JSON
+ * and structurally invalid messages with a clear reason.
+ *
+ * @param json - The raw JSON text received on the socket.
+ * @returns The parse result.
+ */
+function clientMessage_fromJson(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `malformed JSON: ${message}` };
+    }
+    return clientMessage_parse(parsed);
+}
+/**
+ * Validates an attach message and checks its declared contract version
+ * against this build. A structurally valid attach on an incompatible major
+ * is rejected with a clear reason.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result; an incompatible version is a validation failure.
+ */
+function attach_parse(raw) {
+    const parsed = schema_parse(messages_js_1.attachMessageSchema, raw);
+    if (!parsed.ok || parsed.value === undefined) {
+        return parsed;
+    }
+    if (!(0, version_js_1.version_isCompatible)(parsed.value.protocolVersion)) {
+        return {
+            ok: false,
+            error: `incompatible contract version ${parsed.value.protocolVersion}`,
+        };
+    }
+    return parsed;
+}
+//# sourceMappingURL=validate.js.map

package/dist/protocol/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/protocol/validate.ts"],"names":[],"mappings":";;AAuEA,kDAEC;AAQD,kDAEC;AASD,wDASC;AAUD,oCAYC;AA9GD,+CAMuB;AACvB,6CAAoD;AAepD;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAiB;IACxC,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAiB,EAAU,EAAE;QACjC,MAAM,IAAI,GAAW,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5D,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAI,MAAoB,EAAE,GAAY;IACzD,MAAM,MAAM,GAAsC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACxE,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,GAAY;IAC9C,OAAO,YAAY,CAAC,iCAAmB,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,GAAY;IAC9C,OAAO,YAAY,CAAC,iCAAmB,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,IAAY;IACjD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAW,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,OAAO,EAAE,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,YAAY,CAAC,GAAY;IACvC,MAAM,MAAM,GAAqD,YAAY,CAAC,iCAAmB,EAAE,GAAG,CAAC,CAAC;IACxG,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7C,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,IAAA,iCAAoB,EAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;QACxD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,iCAAiC,MAAM,CAAC,KAAK,CAAC,eAAe,EAAE;SACvE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/protocol/version.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file The wire-contract version and its compatibility rule.
+ *
+ * The contract version is carried by a client in the attach handshake and
+ * refused by the daemon on mismatch, with no silent degradation. Per
+ * `docs/calypso.adoc`, it tracks the calypso package's major version at
+ * release; within a major, changes are additive only (new message types,
+ * new optional fields, new model kinds), so a daemon tolerates unknown
+ * additions from a newer minor but rejects a different major outright.
+ *
+ * @module
+ */
+/**
+ * The wire-contract major version this build speaks.
+ */
+export declare const CONTRACT_VERSION: number;
+/**
+ * Decides whether a client's declared contract version is compatible with
+ * this build. Compatibility is exact-major: a client on a different major is
+ * refused, because a major bump removes or re-types something.
+ *
+ * @param clientVersion - The contract major the client declared at attach.
+ * @returns True when the client may attach.
+ */
+export declare function version_isCompatible(clientVersion: number): boolean;

package/dist/protocol/version.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * @file The wire-contract version and its compatibility rule.
+ *
+ * The contract version is carried by a client in the attach handshake and
+ * refused by the daemon on mismatch, with no silent degradation. Per
+ * `docs/calypso.adoc`, it tracks the calypso package's major version at
+ * release; within a major, changes are additive only (new message types,
+ * new optional fields, new model kinds), so a daemon tolerates unknown
+ * additions from a newer minor but rejects a different major outright.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTRACT_VERSION = void 0;
+exports.version_isCompatible = version_isCompatible;
+/**
+ * The wire-contract major version this build speaks.
+ */
+exports.CONTRACT_VERSION = 1;
+/**
+ * Decides whether a client's declared contract version is compatible with
+ * this build. Compatibility is exact-major: a client on a different major is
+ * refused, because a major bump removes or re-types something.
+ *
+ * @param clientVersion - The contract major the client declared at attach.
+ * @returns True when the client may attach.
+ */
+function version_isCompatible(clientVersion) {
+    return clientVersion === exports.CONTRACT_VERSION;
+}
+//# sourceMappingURL=version.js.map

package/dist/protocol/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/protocol/version.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAeH,oDAEC;AAfD;;GAEG;AACU,QAAA,gBAAgB,GAAW,CAAC,CAAC;AAE1C;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAAC,aAAqB;IACxD,OAAO,aAAa,KAAK,wBAAgB,CAAC;AAC5C,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fnndsc/calypso",
+  "version": "0.2.0",
+  "description": "The CALYPSO wire contract: typed protocol schemas and boundary validation for the ChRIS session daemon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FNNDSC/mise.git",
+    "directory": "packages/calypso"
+  },
+  "homepage": "https://github.com/FNNDSC/mise/tree/main/packages/calypso#readme",
+  "bugs": {
+    "url": "https://github.com/FNNDSC/mise/issues"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -fr dist && tsc",
+    "test": "jest --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "chris",
+    "calypso",
+    "wire-contract",
+    "websocket",
+    "fnndsc"
+  ],
+  "author": "Rudolph Pienaar",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.10",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@fnndsc/cumin": "^3.5.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  }
+}