@softov/ahpc 0.1.0

package/dist/src/cli/render.d.ts

@@ -0,0 +1,43 @@
+/** How the CLI puts things on stdout. */
+import type { SessionSummary } from '../ahp/types.js';
+/**
+ * Structured output, when it is asked for.
+ *
+ * Two spaces, because the reader of `--json` is as often a person scrolling as
+ * a program piping - and a program does not mind the whitespace.
+ */
+export declare const json: (data: unknown) => void;
+export declare const line: (text?: string) => void;
+/**
+ * How long ago, in the units a person would say it in.
+ *
+ * A timestamp answers "when"; a list is read for "how long since", and the
+ * two are not the same question.
+ */
+export declare const ago: (iso: string) => string;
+/**
+ * The status bitset, as the word and the shape that carry it.
+ *
+ * Both, deliberately: the glyph is what a list is scanned by and the word is
+ * what survives being read aloud, grepped, or piped somewhere colourless.
+ */
+export declare const mark: (status: number) => string;
+/**
+ * What a host says about a project, or what its path implies.
+ *
+ * The same fallback the catalogue draws, so a row here and a row there name
+ * the same session the same way.
+ */
+export declare const project: (session: SessionSummary) => string;
+/** The branch a host reports under `_meta.git`, if it reports one. */
+export declare const branch: (session: SessionSummary) => string;
+/**
+ * Rows as columns, sized to what is actually in them.
+ *
+ * Padding to a fixed width is what turns a list of long paths into a list of
+ * ragged ones; the widest cell in a column is the only honest width for it.
+ * The last column is never padded, since nothing follows it to line up with.
+ */
+export declare const table: (rows: string[][]) => void;
+/** Whether a session was put away, which a listing hides unless asked. */
+export declare const archived: (status: number) => boolean;

package/dist/src/cli/render.js

@@ -0,0 +1,91 @@
+/** How the CLI puts things on stdout. */
+import { decodeStatus } from '../ahp/status.js';
+/**
+ * Structured output, when it is asked for.
+ *
+ * Two spaces, because the reader of `--json` is as often a person scrolling as
+ * a program piping - and a program does not mind the whitespace.
+ */
+export const json = (data) => {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};
+export const line = (text = '') => { process.stdout.write(`${text}\n`); };
+/**
+ * How long ago, in the units a person would say it in.
+ *
+ * A timestamp answers "when"; a list is read for "how long since", and the
+ * two are not the same question.
+ */
+export const ago = (iso) => {
+    const seconds = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1000));
+    if (!Number.isFinite(seconds))
+        return '';
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    if (seconds < 3600)
+        return `${Math.round(seconds / 60)}m ago`;
+    if (seconds < 86400)
+        return `${Math.round(seconds / 3600)}h ago`;
+    return `${Math.round(seconds / 86400)}d ago`;
+};
+/**
+ * The glyph each activity keeps when there is no colour.
+ *
+ * `decodeStatus` names the shape rather than the character, because the TUI
+ * draws it from a theme. A pipe has no theme, so the characters are here.
+ */
+const GLYPH = {
+    bulletFilled: '●',
+    bulletHalf: '◐',
+    bulletHollow: '○',
+    cross: '✗',
+};
+/**
+ * The status bitset, as the word and the shape that carry it.
+ *
+ * Both, deliberately: the glyph is what a list is scanned by and the word is
+ * what survives being read aloud, grepped, or piped somewhere colourless.
+ */
+export const mark = (status) => {
+    const state = decodeStatus(status);
+    return `${GLYPH[state.glyph] ?? '·'} ${state.label.toLowerCase()}`;
+};
+/**
+ * What a host says about a project, or what its path implies.
+ *
+ * The same fallback the catalogue draws, so a row here and a row there name
+ * the same session the same way.
+ */
+export const project = (session) => session.project?.displayName
+    || (session.workingDirectories[0] ?? '').replace(/^file:\/\//, '').split('/').filter(Boolean).pop()
+    || '';
+/** The branch a host reports under `_meta.git`, if it reports one. */
+export const branch = (session) => {
+    const git = session._meta?.git;
+    if (typeof git !== 'object' || git === null)
+        return '';
+    const found = git.branch;
+    return typeof found === 'string' ? found : '';
+};
+/**
+ * Rows as columns, sized to what is actually in them.
+ *
+ * Padding to a fixed width is what turns a list of long paths into a list of
+ * ragged ones; the widest cell in a column is the only honest width for it.
+ * The last column is never padded, since nothing follows it to line up with.
+ */
+export const table = (rows) => {
+    if (rows.length === 0)
+        return;
+    const widths = [];
+    for (const row of rows) {
+        row.forEach((cell, index) => {
+            widths[index] = Math.max(widths[index] ?? 0, cell.length);
+        });
+    }
+    for (const row of rows) {
+        line(row.map((cell, index) => (index === row.length - 1 ? cell : cell.padEnd(widths[index] ?? 0))).join('  ').trimEnd());
+    }
+};
+/** Whether a session was put away, which a listing hides unless asked. */
+export const archived = (status) => decodeStatus(status).archived;

package/dist/src/config.d.ts

@@ -0,0 +1,63 @@
+/** What this client was told before anybody typed a flag. */
+/** What a config file may say. Every key is what a flag would have said. */
+export interface Config {
+    /** A live agent host, `ws://host:port`. */
+    host?: string;
+    /** A bearer token for it. */
+    token?: string;
+    /** The theme to open on. */
+    theme?: string;
+    /** The shell layout. */
+    shell?: string;
+    /**
+     * Keys, over the ones this client ships with.
+     *
+     * A chord to a command id - `"ctrl+g": "editor.open"` - or to `null`, which
+     * takes the chord away and binds nothing. Naming a chord replaces every
+     * default on it, including one registered against a single screen, so a
+     * chord is either yours or ours and never half of each.
+     *
+     * `ahpc config` lists the command ids. A chord bound to a name no command
+     * answers to is reported at startup rather than dropped, because a binding
+     * that silently does nothing is indistinguishable from one that never
+     * loaded.
+     */
+    keys?: Record<string, string | null>;
+    /**
+     * Trade the header's own name for a seven-cell creature, on an open session.
+     *
+     * Off unless it is asked for. The header's leftmost cell is the one part of
+     * the row that is the same on every screen, and a client that gives it away
+     * by default has decided something about itself on somebody else's behalf.
+     */
+    boodInline?: boolean;
+    /**
+     * Let the creature loose on the whole application.
+     *
+     * Off unless it is asked for, and the reason is the one thing a terminal
+     * cannot do: there is no per-cell transparency, so a figure that goes
+     * everywhere writes over whatever it is standing on. It keeps clear of the
+     * composer, which says how tall it is, and of anything opened on a layer -
+     * but a screen whose content runs to the bottom will have a cat on it.
+     */
+    boodFloat?: boolean;
+}
+/**
+ * Where a tool's configuration lives.
+ *
+ * XDG, and the environment variable first: `$XDG_CONFIG_HOME` is what a person
+ * sets when their configuration is not in `~/.config`, and a tool that reads
+ * the fallback anyway is a tool that ignores them.
+ */
+export declare const configHome: () => string;
+/** This tool's own file. */
+export declare const configPath: (tool: string) => string;
+/**
+ * Read it, or answer that there was nothing to read.
+ *
+ * A file that is not there is not an error - most people have none. A file
+ * that is there and is broken *is* one, and says so rather than starting with
+ * defaults somebody did not choose: silently ignoring a config somebody wrote
+ * is worse than refusing to start.
+ */
+export declare function loadConfig(tool: string, named?: string): Config;

package/dist/src/config.js

@@ -0,0 +1,45 @@
+/** What this client was told before anybody typed a flag. */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Where a tool's configuration lives.
+ *
+ * XDG, and the environment variable first: `$XDG_CONFIG_HOME` is what a person
+ * sets when their configuration is not in `~/.config`, and a tool that reads
+ * the fallback anyway is a tool that ignores them.
+ */
+export const configHome = () => process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+/** This tool's own file. */
+export const configPath = (tool) => join(configHome(), tool, 'config.json');
+/**
+ * Read it, or answer that there was nothing to read.
+ *
+ * A file that is not there is not an error - most people have none. A file
+ * that is there and is broken *is* one, and says so rather than starting with
+ * defaults somebody did not choose: silently ignoring a config somebody wrote
+ * is worse than refusing to start.
+ */
+export function loadConfig(tool, named) {
+    const path = named ?? configPath(tool);
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        // Only a file that was *asked for* by name is worth complaining about.
+        if (named === undefined)
+            return {};
+        throw new Error(`No configuration at ${named}`);
+    }
+    try {
+        const found = JSON.parse(text);
+        if (typeof found !== 'object' || found === null || Array.isArray(found)) {
+            throw new Error('it is not an object');
+        }
+        return found;
+    }
+    catch (error) {
+        throw new Error(`${path} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/src/connect.d.ts

@@ -0,0 +1,53 @@
+/** Which host this run talks to, for either front end. */
+import type { HostConnection } from './ahp/connection.js';
+/**
+ * Enough of the options to choose a host, and nothing about drawing one.
+ *
+ * The CLI and the TUI ask the same question and must get the same answer, so
+ * the choice lives here rather than in either of them. Nothing in this file
+ * imports a renderer, which is what lets `ahpc session list` connect a socket
+ * without loading a screen.
+ */
+export interface Where {
+    /** A live agent host, `ws://host:port`. */
+    host?: string;
+    /** A bearer token for it. */
+    token?: string;
+    /** Where the agent works - a path on the *host*, not on this machine. */
+    path?: string;
+    /**
+     * A directory on *this* machine to serve back, under `virtual://<clientId>/`.
+     *
+     * The authority is this connection's own id, because that is what a host
+     * routes on: it reads the authority out of the URI and matches it against
+     * the connection that published it.
+     *
+     * AHP is symmetrical and a host may read from a client-published URI. Absent
+     * means nothing is served and every such request is refused, which is the
+     * default because publishing by accident is worse than not publishing.
+     */
+    publish?: string;
+    /** Whether the published directory may be written to. Read-only otherwise. */
+    publishWritable?: boolean;
+}
+/**
+ * Where a refusal goes before there is an application to put it in.
+ *
+ * The host is built first - it has to be, the application is registered
+ * against it - so its callbacks are given a box to write into and the box is
+ * filled once there is a store. Until then a refusal goes to stderr, which is
+ * where a connection that fails during the handshake belongs anyway, and where
+ * it stays for the whole of a CLI run.
+ */
+export declare const sink: {
+    report(message: string): void;
+};
+/**
+ * The host this run talks to.
+ *
+ * The one place the choice is made, and the only place either implementation
+ * is named. A live connection is asked for by URL; anything else is the script.
+ */
+export declare function connect(options: Where): Promise<HostConnection & {
+    pump?(): boolean;
+}>;

package/dist/src/connect.js

@@ -0,0 +1,69 @@
+/** Which host this run talks to, for either front end. */
+import { MissingProtocolPackage, liveHost } from './ahp/live.js';
+import { fakeHost } from './ahp/fake.js';
+import { publish } from './ahp/publish.js';
+/**
+ * Where a refusal goes before there is an application to put it in.
+ *
+ * The host is built first - it has to be, the application is registered
+ * against it - so its callbacks are given a box to write into and the box is
+ * filled once there is a store. Until then a refusal goes to stderr, which is
+ * where a connection that fails during the handshake belongs anyway, and where
+ * it stays for the whole of a CLI run.
+ */
+export const sink = {
+    report: (message) => process.stderr.write(`${message}\n`),
+};
+/**
+ * The host this run talks to.
+ *
+ * The one place the choice is made, and the only place either implementation
+ * is named. A live connection is asked for by URL; anything else is the script.
+ */
+export async function connect(options) {
+    if (!options.host)
+        return fakeHost();
+    try {
+        return await liveHost({
+            url: options.host,
+            ...(options.token ? { token: options.token } : {}),
+            onRefusal: (_uri, message) => sink.report(message),
+            onLimit: (message) => sink.report(message),
+            // Work the host is doing under a token of its own. Reported while it
+            // runs and not on the frame that closes it - the finish is the thing
+            // that happened, and it is what the screen shows next.
+            onProgress: (_token, message) => { if (message !== null)
+                sink.report(message); },
+            /*
+             * The host wants signing into something.
+             *
+             * Said in the words a person can act on, which means naming the
+             * resource and the variable that would satisfy it. `expired` is called
+             * out because the answer is different: a new credential, not the one
+             * that was just refused.
+             */
+            onAuthRequired: (resources, why) => {
+                const names = resources.map((one) => one.resource).join(', ');
+                sink.report(why === 'expired'
+                    ? `The token for ${names} has expired. Sign in again: ahpc auth ${resources[0]?.resource ?? ''}`
+                    : `${names} needs signing in to: ahpc auth ${resources[0]?.resource ?? ''}`);
+            },
+            // What this client serves back. Nothing unless a directory was named:
+            // the protocol is symmetrical, and a client that published by default
+            // would be one that hands its disk to any host it connects to.
+            ...(options.publish !== undefined
+                ? { publish: publish({ root: options.publish, ...(options.publishWritable ? { writable: true } : {}) }) }
+                : {}),
+            onState: (state) => { if (state === 'offline')
+                sink.report('The host stopped answering'); },
+        });
+    }
+    catch (error) {
+        if (error instanceof MissingProtocolPackage) {
+            process.stderr.write(`${error.message}\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`Could not reach ${options.host}: ${String(error)}\n`);
+        process.exit(1);
+    }
+}

package/dist/src/control.d.ts

@@ -0,0 +1,189 @@
+import type { Disposable, ServiceKey, TextUIApp } from '@textui/core';
+import type { HostConnection } from './ahp/connection.js';
+import type { Terminals } from './terminal.js';
+import type { Agent, Answer, Automation, Changeset, ChangesetScope, ChatSource, Completion, ConfigProperty, ContentRef, Customization, FileContent, ResourceEntry, SessionConfig, SessionDetail, SessionUri } from './ahp/types.js';
+/**
+ * The control side: what the application can do, and what it does when the
+ * host says something.
+ *
+ * Split from the views because these are the two things that change for
+ * different reasons. A new screen is a rendering change; answering a new kind
+ * of request is a change here. Keeping them in one file is what makes a small
+ * protocol change touch every component that draws a bubble.
+ *
+ * Everything a key can do is a command, so the palette gets it for free and
+ * nothing is reachable one way only.
+ */
+export interface Controller {
+    refresh(): Promise<void>;
+    open(uri: SessionUri): void;
+    close(): void;
+    /** Send, or queue when a turn is already running. */
+    send(text: string): void;
+    /** Take a queued message back, while it is still waiting. */
+    unqueue(id: string): void;
+    stop(): void;
+    approve(optionId?: string): void;
+    deny(): void;
+    answer(answers: Record<string, Answer>, accepted?: boolean): void;
+    setArchived(uri: SessionUri, archived: boolean): void;
+    /** Put the bold back, or take it away. A client flag, not activity. */
+    setRead(uri: SessionUri, read: boolean): void;
+    /** Say that the host refused something, wherever it was noticed. */
+    report(error: unknown): void;
+    /**
+     * End the session on the host.
+     *
+     * Not `dispose`. This object is also a `Disposable` - it owns the
+     * subscription, the commands and the keys - and `Object.assign` put that
+     * `dispose()` straight over the top of this one. Confirming "delete this
+     * session" therefore tore down the whole controller instead: every command
+     * and every keybinding went with it, and the application stopped answering
+     * the keyboard entirely. The protocol's own name for this is
+     * `disposeSession`, and using it means the two can never collide again.
+     */
+    disposeSession(uri: SessionUri): Promise<void>;
+    create(options: {
+        provider: string;
+        workingDirectory?: string;
+        first?: string;
+    }): Promise<SessionUri>;
+    /** The harnesses this host advertises, and the models each offers. */
+    agents(): Promise<Agent[]>;
+    /** The session channel's own state: its chat, its lifecycle, its settings. */
+    detail(uri: SessionUri): Promise<SessionDetail>;
+    config(uri: SessionUri): Promise<SessionConfig>;
+    /** Register a command per question the chosen model asks about itself. */
+    offerModel(properties: ConfigProperty[]): void;
+    /** Put what is being typed where other clients on this chat can see it. */
+    draft(text: string): void;
+    /** What the host handed this session: plugins, skills, MCP servers. */
+    customizations(uri: SessionUri): Promise<Customization[]>;
+    /**
+     * Terminals, as operations.
+     *
+     * Its own object because a terminal is not a session and shares nothing with
+     * one: it belongs to the host, outlives any turn, and what a screen needs
+     * from it is a different set of verbs.
+     */
+    readonly terminals: Terminals;
+    /** What the host offers to complete what is being typed. */
+    completions(channel: string, text: string, offset?: number): Promise<Completion[]>;
+    /** Read a different chat in the session already open. */
+    openChat(chat: string): void;
+    /** Open another chat in it, and read that. */
+    createChat(first?: string, source?: ChatSource): Promise<void>;
+    /** Close one, and read whatever is left. */
+    disposeChat(chat: string): Promise<void>;
+    /** What a slash offers before any session exists. */
+    harnessCommands(): Promise<Customization[]>;
+    /** Turn one on or off. The host decides and tells everyone watching. */
+    setCustomizationEnabled(uri: SessionUri, id: string, enabled: boolean): void;
+    /**
+     * One directory of the host's filesystem.
+     *
+     * The *host's*, which is the whole reason this goes through the connection
+     * rather than through `node:fs`: the daemon may be on another machine, and
+     * the project a session is working in is over there.
+     *
+     * Empty for a host that serves none - `createHost` takes its filesystem as a
+     * port and one given none answers `-32601`, which a client reads as nothing
+     * to browse rather than as a failure.
+     */
+    files(uri: string): Promise<ResourceEntry[]>;
+    /** Watch a directory, where the host serves watches. Releasing closes it. */
+    watchFiles(uri: string, changed: () => void): Promise<{
+        close(): void;
+    }>;
+    /**
+     * Every automation the host holds.
+     *
+     * Rejects, rather than answering empty, for a host that serves none: an
+     * empty list is a host with a clock and nothing on it, and the two want
+     * different words on the screen.
+     */
+    automations(): Promise<Automation[]>;
+    /** Told when one moves, including one that fired while nobody was looking. */
+    onAutomations(observer: () => void): {
+        close(): void;
+    };
+    /** Write a new one, and answer with the URI the host gave it. */
+    createAutomation(definition: Record<string, unknown>): Promise<string>;
+    /** Start one now, whatever its schedule says. */
+    runAutomation(uri: string): Promise<void>;
+    /** Switch one on or off. */
+    setAutomationEnabled(uri: string, enabled: boolean): Promise<void>;
+    /** Forget one. */
+    removeAutomation(uri: string): Promise<void>;
+    /** One file's bytes, by URI on the host. */
+    file(uri: string): Promise<{
+        data: string;
+        encoding: string;
+        contentType?: string;
+    }>;
+    /**
+     * Which changesets this session offers.
+     *
+     * Asked once per session rather than derived: a host that advertises none
+     * has none, and a client that assumed the four the protocol names would
+     * offer a picker full of things to be refused.
+     */
+    changesets(uri: SessionUri): Promise<ChangesetScope[]>;
+    /** One of them, by the URI its template became. Absent is whichever the host would pick. */
+    changesAt(uri: SessionUri, changeset?: string): Promise<Changeset>;
+    /**
+     * Tick a file off, or take the tick back.
+     *
+     * Fire-and-forget: the host keeps the flag and tells every client watching,
+     * so what redraws this screen is the changeset coming back, not this call.
+     */
+    review(changeset: string, files: string[], reviewed: boolean): void;
+    /** One file out of a changeset, fetched. Nothing calls it until a row opens. */
+    content(ref: ContentRef): Promise<FileContent>;
+    /**
+     * Pull the page of history before the turns on screen.
+     *
+     * Answers whether there is still more behind it, so a transcript that has
+     * reached the beginning stops asking.
+     */
+    loadOlderTurns(uri: SessionUri): Promise<boolean>;
+    /**
+     * What the host will answer questions about, here and now.
+     *
+     * One call, because "here and now" has two answers and the caller should not
+     * have to know which: an open session describes itself, and a session that
+     * does not exist yet is what `resolveSessionConfig` is for. Asking also
+     * *registers* a command per property the schema offers, so the control row
+     * and the palette are showing the host's own questions rather than the ones
+     * this client was written knowing about.
+     */
+    settings(): Promise<SessionConfig>;
+    setConfig(uri: SessionUri, key: string, value: string): void;
+    /** Drive the scripted host. A real connection has a socket instead. */
+    pump(): boolean;
+}
+export declare const CONTROLLER: ServiceKey<Controller>;
+export declare const settingCommand: (key: string) => string;
+/** One per property of the chosen model's own schema. */
+export declare const modelCommand: (key: string) => string;
+/**
+ * The two focus scopes, and why single-letter keys need them.
+ *
+ * The runtime already offers a key to the focused node before any keybinding,
+ * so `q` typed into the composer is a letter and not a quit. What a scope adds
+ * is *where a key exists at all*: `d` disposes a session on the catalogue and
+ * means nothing in a conversation, and a binding that exists on both screens
+ * is one that fires on the wrong one.
+ *
+ * A scope is active while the component that declares it is mounted, so the
+ * screens are what turn these on and off.
+ */
+export declare const SESSIONS_SCOPE = "chat.sessions";
+export declare const CHAT_SCOPE = "chat.conversation";
+export declare const SKILLS_SCOPE = "chat.skills";
+export declare const MCP_SCOPE = "chat.mcp";
+export declare const CHANGES_SCOPE = "chat.changes";
+export declare const AUTOMATIONS_SCOPE = "chat.automations";
+export declare function createController(app: TextUIApp, host: HostConnection & {
+    pump?(): boolean;
+}, bindings?: Record<string, string | null>): Controller & Disposable;