@fnndsc/calypso 0.6.1 → 0.7.0

package/dist/calypso.js

@@ -12,8 +12,11 @@
  */
 import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
-import { engine_create, sessionConnect_fromSaved } from '@fnndsc/brasa';
+import { engine_create, procIndex_snapshot, sessionConnect_fromSaved } from '@fnndsc/brasa';
+import chalk from 'chalk';
 import { daemon_launch } from './daemon/launch.js';
+import { face_start } from './daemon/face.js';
+import { LocalBerthResolver, berthUrl_isAlive } from './daemon/berth.js';
 /**
  * Creates the engine, restores the saved session, and hosts the daemon.
  *
@@ -29,7 +32,52 @@ async function calypso_start() {
     else {
         console.error(`[!] No active session (${result.status}). Log in with 'chell' first; hosting offline.`);
     }
-    await daemon_launch(engine);
+    const info = await daemon_launch(engine);
+    // On a TTY, the terminal's resting state is the console face; off one
+    // (systemd, nohup) face_start declines and logging stays sequential.
+    face_start({
+        info: [
+            { label: 'identity', value: info.identity },
+            { label: 'wire', value: info.url },
+            ...(info.argusUrl !== null ? [{ label: 'ARGUS', value: info.argusUrl }] : []),
+            { label: 'token', value: info.token },
+            { label: 'berth', value: info.berthPath },
+            { label: 'attach', value: `chell --remote --attach ${info.url} --token ${info.token}` },
+        ],
+        telemetry_get: () => {
+            const index = procIndex_snapshot();
+            return {
+                sessions: info.daemon.surfaces_count(),
+                busy: info.daemon.busy_get(),
+                jobs: index.jobs,
+                feeds: index.feeds,
+            };
+        },
+    });
+}
+/**
+ * Prints how to attach to each live daemon.
+ *
+ * A daemon prints its addresses once, at launch, into a terminal it then
+ * occupies. The facts survive in the berth — url and token, mode 0600 in the
+ * user's runtime directory — so they are reprinted from there rather than
+ * copied somewhere more convenient and less private. `/tmp` would be more
+ * convenient; it is also world-readable, and the token is a credential.
+ */
+async function berths_print() {
+    const resolver = new LocalBerthResolver((berth) => berthUrl_isAlive(berth.url));
+    const berths = await resolver.list();
+    if (berths.length === 0) {
+        console.error(chalk.yellow('No CALYPSO daemon is running.'));
+        console.error(chalk.gray("Start one with:  chell --daemon <user>@<url>"));
+        return;
+    }
+    for (const berth of berths) {
+        const web = berth.url.replace(/^ws/, 'http');
+        console.log(chalk.bold.cyan(berth.identity));
+        console.log(chalk.green(`  ARGUS:   ${web}/?token=${berth.token}`));
+        console.log(chalk.gray(`  attach:  chell --remote --attach ${berth.url} --token ${berth.token}`));
+    }
 }
 const currentFile = fileURLToPath(import.meta.url);
 let isMain = false;
@@ -40,6 +88,8 @@ catch {
     // Not invoked as a script.
 }
 if (isMain) {
-    void calypso_start();
+    // One flag, not a subcommand grammar: this binary hosts a daemon, and the
+    // only other thing anyone needs from it is where the running ones are.
+    void (process.argv.includes('--berths') ? berths_print() : calypso_start());
 }
 //# sourceMappingURL=calypso.js.map

package/dist/calypso.js.map

@@ -1 +1 @@
-{"version":3,"file":"calypso.js","sourceRoot":"","sources":["../src/calypso.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAA6C,MAAM,eAAe,CAAC;AACnH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,KAAK,UAAU,aAAa;IAC1B,MAAM,MAAM,GAAgB,MAAM,aAAa,EAAE,CAAC;IAElD,MAAM,MAAM,GAAuB,MAAM,wBAAwB,EAAE,CAAC;IACpE,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,CAAC,KAAK,CAAC,yBAAyB,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACtF,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,0BAA0B,MAAM,CAAC,MAAM,gDAAgD,CAAC,CAAC;IACzG,CAAC;IAED,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,WAAW,GAAW,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3D,IAAI,MAAM,GAAY,KAAK,CAAC;AAC5B,IAAI,CAAC;IACH,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,YAAY,CAAC,WAAW,CAAC,CAAC;AACvE,CAAC;AAAC,MAAM,CAAC;IACP,2BAA2B;AAC7B,CAAC;AAED,IAAI,MAAM,EAAE,CAAC;IACX,KAAK,aAAa,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"calypso.js","sourceRoot":"","sources":["../src/calypso.ts"],"names":[],"mappings":"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"}

package/dist/daemon/attachFile.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file The attach note: a daemon's addresses, written where they can be read.
+ *
+ * A daemon prints its ARGUS link and attach command once, into a terminal it
+ * then occupies with a live boot animation. Selecting text out from under a
+ * repainting screen is awkward, and scrollback is lost the moment anyone
+ * clears it — so the same lines are also written to a file.
+ *
+ * The file carries the attach token, which is a credential, and `/tmp` is
+ * world-readable. Three things follow, and none is optional:
+ *
+ * * it is created `0600`, so the mode rather than the directory protects it;
+ * * it is created exclusively (`wx`), so a symlink planted at the path by
+ *   another user makes the write fail rather than land somewhere chosen by
+ *   them; and
+ * * it is removed when the daemon exits, so a dead session's token does not
+ *   linger.
+ *
+ * `calypso --berths` reads the same facts from the berth, which is `0600` in
+ * the user's own runtime directory. That remains the safer route; this one is
+ * the convenient one.
+ *
+ * @module
+ */
+/**
+ * The path this daemon's attach note occupies.
+ *
+ * Per OS user rather than per session, so it can be named in a message and
+ * found again without reading one. A second daemon for a second CUBE identity
+ * overwrites it; `calypso --berths` lists them all.
+ *
+ * @returns An absolute path in the system temporary directory.
+ */
+export declare function attachFile_path(): string;
+/**
+ * Writes the attach note, replacing any note this user left before.
+ *
+ * @param lines - The addresses to record, one per line.
+ * @returns The path written, or null when it could not be written safely.
+ */
+export declare function attachFile_write(lines: string[]): string | null;
+/** Removes the attach note, so a dead session's token does not linger. */
+export declare function attachFile_remove(): void;

package/dist/daemon/attachFile.js

@@ -0,0 +1,80 @@
+/**
+ * @file The attach note: a daemon's addresses, written where they can be read.
+ *
+ * A daemon prints its ARGUS link and attach command once, into a terminal it
+ * then occupies with a live boot animation. Selecting text out from under a
+ * repainting screen is awkward, and scrollback is lost the moment anyone
+ * clears it — so the same lines are also written to a file.
+ *
+ * The file carries the attach token, which is a credential, and `/tmp` is
+ * world-readable. Three things follow, and none is optional:
+ *
+ * * it is created `0600`, so the mode rather than the directory protects it;
+ * * it is created exclusively (`wx`), so a symlink planted at the path by
+ *   another user makes the write fail rather than land somewhere chosen by
+ *   them; and
+ * * it is removed when the daemon exits, so a dead session's token does not
+ *   linger.
+ *
+ * `calypso --berths` reads the same facts from the berth, which is `0600` in
+ * the user's own runtime directory. That remains the safer route; this one is
+ * the convenient one.
+ *
+ * @module
+ */
+import { chmodSync, openSync, writeSync, closeSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { userInfo } from 'node:os';
+/**
+ * The path this daemon's attach note occupies.
+ *
+ * Per OS user rather than per session, so it can be named in a message and
+ * found again without reading one. A second daemon for a second CUBE identity
+ * overwrites it; `calypso --berths` lists them all.
+ *
+ * @returns An absolute path in the system temporary directory.
+ */
+export function attachFile_path() {
+    return join(tmpdir(), `calypso-${userInfo().username}.attach`);
+}
+/**
+ * Writes the attach note, replacing any note this user left before.
+ *
+ * @param lines - The addresses to record, one per line.
+ * @returns The path written, or null when it could not be written safely.
+ */
+export function attachFile_write(lines) {
+    const path = attachFile_path();
+    try {
+        // Remove our own stale note first, then create exclusively: if anything
+        // reappears at the path in between, the create fails rather than writing
+        // through whatever is there.
+        rmSync(path, { force: true });
+        const handle = openSync(path, 'wx', 0o600);
+        try {
+            writeSync(handle, `${lines.join('\n')}\n`);
+        }
+        finally {
+            closeSync(handle);
+        }
+        // openSync's mode is subject to umask; set it outright.
+        chmodSync(path, 0o600);
+        return path;
+    }
+    catch {
+        // A note is a convenience. Failing to write one must never stop a daemon
+        // from starting, and the addresses were printed regardless.
+        return null;
+    }
+}
+/** Removes the attach note, so a dead session's token does not linger. */
+export function attachFile_remove() {
+    try {
+        rmSync(attachFile_path(), { force: true });
+    }
+    catch {
+        // Nothing useful to say at exit about a file that may already be gone.
+    }
+}
+//# sourceMappingURL=attachFile.js.map

package/dist/daemon/attachFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachFile.js","sourceRoot":"","sources":["../../src/daemon/attachFile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,QAAQ,EAAE,CAAC,QAAQ,SAAS,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAe;IAC9C,MAAM,IAAI,GAAW,eAAe,EAAE,CAAC;IACvC,IAAI,CAAC;QACH,wEAAwE;QACxE,yEAAyE;QACzE,6BAA6B;QAC7B,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAW,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACnD,IAAI,CAAC;YACH,SAAS,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,MAAM,CAAC,CAAC;QACpB,CAAC;QACD,wDAAwD;QACxD,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,4DAA4D;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,MAAM,CAAC,eAAe,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;AACH,CAAC"}

package/dist/daemon/engine.d.ts

@@ -11,6 +11,7 @@
  * @module
  */
 import type { CommandEnvelope } from '@fnndsc/cumin';
+import type { Regard } from '@fnndsc/menu';
 /**
  * A completion answer: the candidates and the prefix they complete.
  *
@@ -58,4 +59,19 @@ export interface HostedEngine {
      * @returns The file's bytes.
      */
     file_read?(filePath: string): Promise<Buffer>;
+    /**
+     * Notes a regard write relayed from a surface, retaining it as session
+     * truth engine-side. Optional: a daemon still retains and rebroadcasts
+     * regard on the wire without it.
+     *
+     * @param regard - The indicated address with its provenance.
+     */
+    regard_note?(regard: Regard): void;
+    /**
+     * Returns the engine's retained regard, or null before the first
+     * indication.
+     *
+     * @returns The retained regard, or null.
+     */
+    regard_get?(): Regard | null;
 }

package/dist/daemon/face.d.ts

@@ -0,0 +1,127 @@
+/** One labeled fact shown on the face's identity panel. */
+export interface FaceInfo {
+    label: string;
+    value: string;
+}
+/** Live daemon readings the face polls once per frame. */
+export interface FaceTelemetry {
+    /** Attached surfaces right now. */
+    sessions: number;
+    /** Whether a foreground command is executing. */
+    busy: boolean;
+    /** Jobs the proc index holds. */
+    jobs: number;
+    /** Feeds the proc index holds. */
+    feeds: number;
+}
+/** What the face needs from its host. */
+export interface FaceOptions {
+    /** Identity panel rows: identity, wire, web surface, token, berth. */
+    info: FaceInfo[];
+    /** Live readings; omitted readings render as an idle daemon. */
+    telemetry_get?: () => FaceTelemetry;
+}
+/**
+ * A bounded line buffer for output arriving while the face owns the screen.
+ *
+ * Everything a stray `console.log` (a retry warning, a background sweep
+ * report) writes is caged here: the newest lines feed the face's strip, and
+ * the whole run since the last flush is replayed into the normal buffer when
+ * the operator drops to text — so nothing is ever lost, only re-homed.
+ */
+export declare class FaceLogRing {
+    private lines;
+    private pending;
+    private unflushed;
+    /**
+     * Absorbs one raw write, splitting it into stripped, stored lines.
+     *
+     * A carriage return without a newline is a redraw (a spinner frame): it
+     * discards what preceded it on the line rather than appending, so a
+     * thousand frames stay one line, not one enormous one.
+     *
+     * @param chunk - The text a hijacked stdout/stderr write carried.
+     */
+    push(chunk: string): void;
+    /**
+     * The newest lines, for the face's log strip.
+     *
+     * @param count - How many lines the strip shows.
+     * @returns Up to `count` lines, oldest first.
+     */
+    tail(count: number): string[];
+    /**
+     * Returns and forgets the lines not yet replayed into the normal buffer.
+     *
+     * @returns The unflushed lines, oldest first.
+     */
+    drain(): string[];
+}
+/** Everything the pure composer needs to draw one frame. */
+export interface FaceFrame {
+    rows: number;
+    columns: number;
+    frameIndex: number;
+    /** 'boot': frenetic pulse over the streaming boot log; 'ready': the steady instrument. */
+    phase: 'boot' | 'ready';
+    info: FaceInfo[];
+    telemetry: FaceTelemetry | null;
+    logTail: string[];
+    uptimeSeconds: number;
+}
+/**
+ * Formats an uptime as `2d 03:14:07` / `03:14:07`.
+ *
+ * @param seconds - Whole seconds since the daemon came up.
+ * @returns The formatted uptime.
+ */
+export declare function uptime_format(seconds: number): string;
+/**
+ * Composes one face frame as screen lines, top to bottom. Pure: no terminal
+ * control, no timers — the runtime places these under the alternate buffer
+ * and the tests read them directly.
+ *
+ * @param frame - The readings and geometry for this frame.
+ * @returns The lines to paint, at most `frame.rows - 1` of them.
+ */
+export declare function face_frameCompose(frame: FaceFrame): string[];
+/** Whether the console face currently owns the terminal. */
+export declare function face_isActive(): boolean;
+/**
+ * Takes the daemon terminal over as the console face.
+ *
+ * A no-op off a TTY (systemd, nohup, a pipe): the daemon then logs
+ * sequentially exactly as before.
+ *
+ * @param options - Identity rows and live-telemetry hook.
+ * @returns True when the face took the screen.
+ */
+export declare function face_start(options: FaceOptions, phase?: 'boot' | 'ready'): boolean;
+/**
+ * Takes the terminal over for the boot phase: the brain in its frenetic
+ * boot pulse over a tall strip of the streaming boot log — no identity
+ * panel yet, because there is nothing to identify. A no-op off a TTY.
+ *
+ * @returns True when the boot face took the screen.
+ */
+export declare function face_boot(): boolean;
+/**
+ * Settles the face into its steady state: the calm ambient pulse, the
+ * identity panel, live telemetry, and the toggle hint. Called on a face
+ * already up (the boot phase) it repaints in place; called with no face
+ * (a host that skipped the boot phase) it starts one. Off a TTY, nothing.
+ *
+ * @param options - Identity rows and live-telemetry hook.
+ * @returns True when a face is showing the steady state.
+ */
+export declare function face_ready(options: FaceOptions): boolean;
+/**
+ * Steps aside for an interactive prompt: the terminal returns to the
+ * normal buffer with cooked stdin, and the face's key handler stops
+ * listening so the prompt's readline owns every keystroke.
+ */
+export declare function face_suspend(): void;
+/** Returns from a prompt: raw keys again, and back onto the face. */
+export declare function face_resume(): void;
+/** Releases the terminal entirely: buffers, writes, raw mode, listeners. */
+export declare function face_stop(): void;