@softov/ahpc 0.1.0

package/dist/src/diff.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A line diff, small enough to read.
+ *
+ * The host sends two whole files and a count of what changed between them; it
+ * does not send the diff itself, so somebody has to work out which lines those
+ * were. This is that, and it is deliberately the textbook algorithm rather
+ * than anything clever: the longest common subsequence of the two line arrays,
+ * with everything not in it marked as removed on the left or added on the
+ * right.
+ *
+ * The cost is quadratic in the number of lines, which is why `diffLines` takes
+ * a ceiling. Two files of ten thousand lines each is a hundred million cells
+ * and a terminal that stops answering, and the honest answer at that size is
+ * to say the files are too big rather than to spend a minute proving it.
+ */
+export type DiffKind = 'same' | 'added' | 'removed';
+export interface DiffRow {
+    kind: DiffKind;
+    /** 1-based, on the side this row exists on. Absent on the side it does not. */
+    before?: number;
+    after?: number;
+    text: string;
+}
+export interface DiffResult {
+    rows: DiffRow[];
+    added: number;
+    removed: number;
+    /** Set instead of a diff when the pair was over `limit`. */
+    tooLarge?: {
+        lines: number;
+        limit: number;
+    };
+}
+/** Lines of a file, with the trailing newline not counted as an empty last line. */
+export declare function toLines(text: string): string[];
+/**
+ * The two sides, lined up.
+ *
+ * A creation has no `before` and a deletion no `after`; both are passed as an
+ * empty string rather than as a special case, because "every line is an
+ * addition" is exactly the right diff for a new file and needs no branch of
+ * its own.
+ */
+export declare function diffLines(before: string, after: string, limit?: number): DiffResult;

package/dist/src/diff.js

@@ -0,0 +1,111 @@
+/**
+ * A line diff, small enough to read.
+ *
+ * The host sends two whole files and a count of what changed between them; it
+ * does not send the diff itself, so somebody has to work out which lines those
+ * were. This is that, and it is deliberately the textbook algorithm rather
+ * than anything clever: the longest common subsequence of the two line arrays,
+ * with everything not in it marked as removed on the left or added on the
+ * right.
+ *
+ * The cost is quadratic in the number of lines, which is why `diffLines` takes
+ * a ceiling. Two files of ten thousand lines each is a hundred million cells
+ * and a terminal that stops answering, and the honest answer at that size is
+ * to say the files are too big rather than to spend a minute proving it.
+ */
+/** Lines of a file, with the trailing newline not counted as an empty last line. */
+export function toLines(text) {
+    if (text === '')
+        return [];
+    const lines = text.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * The two sides, lined up.
+ *
+ * A creation has no `before` and a deletion no `after`; both are passed as an
+ * empty string rather than as a special case, because "every line is an
+ * addition" is exactly the right diff for a new file and needs no branch of
+ * its own.
+ */
+export function diffLines(before, after, limit = 4000) {
+    const a = toLines(before);
+    const b = toLines(after);
+    if (a.length + b.length > limit) {
+        return { rows: [], added: 0, removed: 0, tooLarge: { lines: a.length + b.length, limit } };
+    }
+    // The common head and tail first. Two files that differ in one line share
+    // everything either side of it, and taking those off shrinks the table the
+    // quadratic part has to fill to the part that actually differs.
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head])
+        head++;
+    let tail = 0;
+    while (tail < a.length - head
+        && tail < b.length - head
+        && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+        tail++;
+    const midA = a.slice(head, a.length - tail);
+    const midB = b.slice(head, b.length - tail);
+    const table = lcs(midA, midB);
+    const rows = [];
+    let added = 0;
+    let removed = 0;
+    const push = (kind, text, ai, bi) => {
+        rows.push({
+            kind,
+            ...(kind !== 'added' ? { before: ai + 1 } : {}),
+            ...(kind !== 'removed' ? { after: bi + 1 } : {}),
+            text,
+        });
+        if (kind === 'added')
+            added++;
+        if (kind === 'removed')
+            removed++;
+    };
+    for (let i = 0; i < head; i++)
+        push('same', a[i], i, i);
+    // Walking the table forwards, so the rows come out in file order.
+    let i = 0;
+    let j = 0;
+    while (i < midA.length || j < midB.length) {
+        if (i < midA.length && j < midB.length && midA[i] === midB[j]) {
+            push('same', midA[i], head + i, head + j);
+            i++;
+            j++;
+            // A tie goes to the removal, so a replaced line reads `-old` then `+new`
+            // the way every other diff on the machine prints it. With `>=` here the
+            // pair comes out the other way round, which is not wrong so much as
+            // unreadable next to `git diff`.
+        }
+        else if (j < midB.length && (i === midA.length || (table[i]?.[j + 1] ?? 0) > (table[i + 1]?.[j] ?? 0))) {
+            push('added', midB[j], head + i, head + j);
+            j++;
+        }
+        else {
+            push('removed', midA[i], head + i, head + j);
+            i++;
+        }
+    }
+    for (let k = 0; k < tail; k++) {
+        push('same', a[a.length - tail + k], a.length - tail + k, b.length - tail + k);
+    }
+    return { rows, added, removed };
+}
+/**
+ * `table[i][j]` is the length of the longest common subsequence of `a[i..]`
+ * and `b[j..]`, filled from the end so the walk above can go forwards.
+ */
+function lcs(a, b) {
+    const table = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            table[i][j] = a[i] === b[j]
+                ? (table[i + 1]?.[j + 1] ?? 0) + 1
+                : Math.max(table[i + 1]?.[j] ?? 0, table[i]?.[j + 1] ?? 0);
+        }
+    }
+    return table;
+}

package/dist/src/flags.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The words that mean "no screen".
+ *
+ * A closed set rather than "anything that is not a flag": every other argument
+ * shape has always started the screen, and a typo becoming a silent CLI run
+ * would be a worse answer than a refusal.
+ */
+export declare const COMMANDS: ReadonlySet<string>;
+/**
+ * Every flag that takes no value, in either front end.
+ *
+ * One set rather than one per component, because a flag takes a value or it
+ * does not - that is a fact about the flag, not about who is reading it. What
+ * each component does with the answer differs: the entry point stops itself
+ * swallowing the next word, the CLI keeps a positional a positional, and the
+ * screen matches its own arms.
+ */
+export declare const SWITCHES: ReadonlySet<string>;
+/**
+ * The command, wherever it is.
+ *
+ * `ahpc --claude status` and `ahpc status --claude` mean the same thing, so
+ * this is a scan rather than a look at the first word - reading only the first
+ * one made every flag before a command silently open the screen instead.
+ * A flag that takes a value swallows the next word, or `--path status` would
+ * be a command.
+ */
+export declare const commandIn: (argv: string[]) => string | undefined;

package/dist/src/flags.js

@@ -0,0 +1,76 @@
+/*
+ * The words the command line is made of, in one place.
+ *
+ * Three components need to know which flags take a value: the entry point,
+ * which scans for a command word and must not read a flag's value as one; the
+ * CLI, whose positionals are whatever is left after the flags; and the screen,
+ * whose parser consumes the next word for some flags and not others. Held as
+ * three tables it was three vocabularies - the entry point knew 18 flags, the
+ * CLI knew 18, and only 10 were shared, so `ahpc --force resource write ...`
+ * swallowed the command word and opened the screen, which then refused a flag
+ * that was never meant for it. Seven flags behaved that way.
+ *
+ * This file imports nothing on purpose. The entry point decides which front
+ * end to load and must not load either one to decide, which is why the tables
+ * were copied there rather than imported in the first place; a leaf with no
+ * dependencies costs it nothing.
+ */
+/**
+ * The words that mean "no screen".
+ *
+ * A closed set rather than "anything that is not a flag": every other argument
+ * shape has always started the screen, and a typo becoming a silent CLI run
+ * would be a worse answer than a refusal.
+ */
+export const COMMANDS = new Set([
+    'help', 'status', 'config', 'session', 'chat', 'terminal', 'resource',
+    'agents', 'models', 'commands', 'customizations', 'completions', 'changes', 'content',
+    'prompt', 'exec', 'cancel', 'queue', 'unqueue',
+    'watch', 'confirm', 'answer', 'dispatch',
+]);
+/**
+ * Every flag that takes no value, in either front end.
+ *
+ * One set rather than one per component, because a flag takes a value or it
+ * does not - that is a fact about the flag, not about who is reading it. What
+ * each component does with the answer differs: the entry point stops itself
+ * swallowing the next word, the CLI keeps a positional a positional, and the
+ * screen matches its own arms.
+ */
+export const SWITCHES = new Set([
+    // The screen's own.
+    '--static', '-s', '--settled', '--approve', '--answer', '--bood', '--help', '-h',
+    // Shape and scope, on both sides.
+    '--json', '--full', '--all', '--archived', '--unread', '--undo',
+    '--off', '--deny', '--reject', '--claude', '--chat',
+    // The write half's, which take no value: without them a positional after one
+    // is read as that flag's argument and disappears.
+    '--create-only', '--recursive', '--fail-if-exists', '--follow', '--force',
+    // What this client serves back to the host.
+    '--publish-writable',
+    // Output shape, on the two commands that offer a second one.
+    '--operations', '--markdown',
+    // Asking rather than doing, and agreeing in advance.
+    '--list', '--yes',
+]);
+/**
+ * The command, wherever it is.
+ *
+ * `ahpc --claude status` and `ahpc status --claude` mean the same thing, so
+ * this is a scan rather than a look at the first word - reading only the first
+ * one made every flag before a command silently open the screen instead.
+ * A flag that takes a value swallows the next word, or `--path status` would
+ * be a command.
+ */
+export const commandIn = (argv) => {
+    for (let i = 0; i < argv.length; i++) {
+        const word = argv[i];
+        if (word.startsWith('-')) {
+            if (!SWITCHES.has(word))
+                i++;
+            continue;
+        }
+        return COMMANDS.has(word) ? word : undefined;
+    }
+    return undefined;
+};

package/dist/src/main.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * The entry point, and the one decision it makes.
+ *
+ * `ahpc` is two front ends over one client: a screen, and a shell. Which one
+ * runs is decided by the first word of argv and nothing else - so this file
+ * imports neither. Both are loaded on demand, because the screen pulls in a
+ * whole renderer and `ahpc session list --json` should not pay for one.
+ */
+export {};

package/dist/src/main.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * The entry point, and the one decision it makes.
+ *
+ * `ahpc` is two front ends over one client: a screen, and a shell. Which one
+ * runs is decided by the first word of argv and nothing else - so this file
+ * imports neither. Both are loaded on demand, because the screen pulls in a
+ * whole renderer and `ahpc session list --json` should not pay for one.
+ */
+// Both tables live in a leaf of their own: three components read this
+// vocabulary and holding a copy each is what let them disagree. Importing it
+// does not load a front end, which is the reason they were copied here.
+import { commandIn } from './flags.js';
+const argv = process.argv.slice(2);
+const first = commandIn(argv);
+if (first !== undefined) {
+    /*
+     * A closed pipe is not an error.
+     *
+     * `ahpc session list | head` closes stdout part-way through the writing,
+     * and Node turns that into an unhandled EPIPE that prints a stack trace
+     * over the output the reader actually wanted. Every command here is a
+     * writer, so every one of them can be cut short this way.
+     */
+    process.stdout.on('error', (error) => {
+        if (error.code === 'EPIPE')
+            process.exit(0);
+        throw error;
+    });
+    const { cli, Fault } = await import('./cli/main.js');
+    try {
+        // The command word taken out, so what is left is only flags and the
+        // command's own arguments - wherever in the line it happened to sit.
+        const at = argv.indexOf(first);
+        process.exitCode = await cli(first, [...argv.slice(0, at), ...argv.slice(at + 1)]);
+    }
+    catch (error) {
+        // A `Fault` is a sentence written for the person who typed the command;
+        // anything else is this client going wrong, and hiding its stack would
+        // make that indistinguishable from the first kind.
+        if (error instanceof Fault) {
+            process.stderr.write(`${error.message}\n`);
+            process.exitCode = 1;
+        }
+        else {
+            process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    }
+}
+else {
+    const { tui } = await import('./tui.js');
+    await tui(argv);
+}

package/dist/src/schedule.d.ts

@@ -0,0 +1,46 @@
+/** The protocol's five-field cron, checked for grammar and nothing else. */
+/**
+ * What is wrong with an expression, in a sentence, or nothing.
+ *
+ * A sentence rather than a boolean because it is shown under the field being
+ * typed into, and "invalid" tells somebody only that they are not finished.
+ */
+export declare function scheduleProblem(expression: string): string | undefined;
+/**
+ * Whether a zone is one this machine knows.
+ *
+ * Asked of `Intl`, which is the only thing here that holds a tz database, and
+ * asked by trying it: there is no list to check against. A zone this client
+ * does not know may still be one the host knows, so this is a warning about a
+ * likely typo rather than a refusal - which is why it is separate from
+ * `scheduleProblem` and reads as a question.
+ */
+export declare function zoneIsKnownHere(timeZone: string): boolean;
+/**
+ * Schedules people actually ask for, as expressions.
+ *
+ * A label paired with a *known* expression, which is the whole reason this can
+ * say "every day at 02:00" in English while `scheduleProblem` refuses to
+ * paraphrase anything. Reading a label off a table is not the same as claiming
+ * to understand an arbitrary expression: choose one of these and the sentence
+ * is true by construction, write your own and this says nothing about it.
+ *
+ * Empty is first and is a real choice: no trigger at all is what manual-only
+ * means, and it is the thing somebody wants more often than any single cron.
+ */
+export interface Preset {
+    id: string;
+    label: string;
+    /** Empty for manual-only. */
+    expression: string;
+}
+export declare const PRESETS: Preset[];
+/**
+ * Which preset an expression is, if it is one.
+ *
+ * Matched on the expression rather than remembered as a choice, so a preset
+ * typed out by hand is recognised and an edited preset stops claiming to be
+ * one. Undefined means the expression is the person's own, and nothing here
+ * will put words in their mouth about it.
+ */
+export declare function presetFor(expression: string): Preset | undefined;

package/dist/src/schedule.js

@@ -0,0 +1,140 @@
+/** The protocol's five-field cron, checked for grammar and nothing else. */
+/**
+ * Why this is here at all, and why it stops where it does.
+ *
+ * A schedule is protocol-defined - five whitespace-separated fields, minute
+ * through day-of-week, with names for months and weekdays - so checking one is
+ * reading the protocol rather than knowing anything about a particular host.
+ * That is the line this client does not cross, and this stays on the right
+ * side of it.
+ *
+ * It checks **grammar, not meaning**. It will not tell you when an expression
+ * next comes round, because that is the host's answer: the host evaluates the
+ * expression, in the zone, against its own clock, and says so by sending back
+ * `nextRunAt`. A client that computed its own would be a second answer to a
+ * question somebody is going to be woken up by.
+ *
+ * What it is for is the moment of typing. The daemon keeps a definition whose
+ * expression it could not read - losing the whole thing over a typo helps
+ * nobody - and reports the problem to its own log, where the person who made
+ * the typo will never see it. Without this, a mistyped schedule is silence
+ * until the morning it does not run.
+ */
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const DAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+const FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day of month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12, names: MONTHS },
+    // 0 and 7 both mean Sunday, which is what the protocol says and what every
+    // crontab accepts.
+    { name: 'day of week', min: 0, max: 7, names: DAYS },
+];
+/** One value, by number or by name. Undefined when it is neither. */
+function valueOf(text, field) {
+    const named = field.names?.indexOf(text.toLowerCase()) ?? -1;
+    if (named >= 0)
+        return named + (field.names === MONTHS ? 1 : 0);
+    if (!/^\d+$/.test(text))
+        return undefined;
+    const value = Number(text);
+    return value < field.min || value > field.max ? undefined : value;
+}
+/** What is wrong with one field, or nothing. */
+function checkField(text, field) {
+    for (const term of text.split(',')) {
+        if (term === '')
+            return `${field.name} has an empty entry`;
+        const parts = term.split('/');
+        if (parts.length > 2)
+            return `${term} has more than one step`;
+        const [range, step] = parts;
+        if (step !== undefined && (!/^\d+$/.test(step) || Number(step) === 0)) {
+            return `${step} is not a step - a step must be a positive whole number`;
+        }
+        if (range === '*')
+            continue;
+        if (range.includes('-')) {
+            const ends = range.split('-');
+            if (ends.length > 2)
+                return `${range} is not a range`;
+            const [a, b] = ends;
+            const from = valueOf(a, field);
+            const to = valueOf(b, field);
+            if (from === undefined)
+                return `${a} is not a ${field.name}`;
+            if (to === undefined)
+                return `${b} is not a ${field.name}`;
+            if (to < from)
+                return `${range} runs backwards`;
+            continue;
+        }
+        if (valueOf(range, field) === undefined)
+            return `${range} is not a ${field.name}`;
+    }
+    return undefined;
+}
+/**
+ * What is wrong with an expression, in a sentence, or nothing.
+ *
+ * A sentence rather than a boolean because it is shown under the field being
+ * typed into, and "invalid" tells somebody only that they are not finished.
+ */
+export function scheduleProblem(expression) {
+    const trimmed = expression.trim();
+    if (trimmed === '')
+        return 'A schedule needs five fields, like 0 9 * * 1-5';
+    if (trimmed.startsWith('@'))
+        return 'AHP has no @daily or @hourly - write the five fields out';
+    const fields = trimmed.split(/\s+/);
+    if (fields.length !== 5) {
+        return `A schedule has five fields - minute, hour, day, month, weekday - and this has ${fields.length}`;
+    }
+    for (let at = 0; at < FIELDS.length; at++) {
+        const problem = checkField(fields[at], FIELDS[at]);
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+}
+/**
+ * Whether a zone is one this machine knows.
+ *
+ * Asked of `Intl`, which is the only thing here that holds a tz database, and
+ * asked by trying it: there is no list to check against. A zone this client
+ * does not know may still be one the host knows, so this is a warning about a
+ * likely typo rather than a refusal - which is why it is separate from
+ * `scheduleProblem` and reads as a question.
+ */
+export function zoneIsKnownHere(timeZone) {
+    if (timeZone.trim() === '')
+        return false;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const PRESETS = [
+    { id: 'manual', label: 'By hand only', expression: '' },
+    { id: 'half-hourly', label: 'Every 30 minutes', expression: '*/30 * * * *' },
+    { id: 'hourly', label: 'Every hour, on the hour', expression: '0 * * * *' },
+    { id: 'daily', label: 'Every day at 02:00', expression: '0 2 * * *' },
+    { id: 'weekdays', label: 'Weekdays at 09:00', expression: '0 9 * * 1-5' },
+    { id: 'saturday', label: 'Saturdays at 23:00', expression: '0 23 * * 6' },
+];
+/**
+ * Which preset an expression is, if it is one.
+ *
+ * Matched on the expression rather than remembered as a choice, so a preset
+ * typed out by hand is recognised and an edited preset stops claiming to be
+ * one. Undefined means the expression is the person's own, and nothing here
+ * will put words in their mouth about it.
+ */
+export function presetFor(expression) {
+    const trimmed = expression.trim();
+    return PRESETS.find((one) => one.expression === trimmed);
+}

package/dist/src/screens.d.ts

@@ -0,0 +1,79 @@
+import type { RenderOutput } from '@textui/core';
+export declare const SessionsScreen: (props: Record<string, never>) => RenderOutput;
+/**
+ * The terminal screen.
+ *
+ * Nothing is decided here: which terminals exist, which is open and what
+ * happens when a line is sent all live in `terminal.ts`, and this puts them on
+ * screen. Unmounting it therefore does not lose the shell, which is the
+ * reason for the split.
+ */
+export declare const TerminalScreen: (props: Record<string, never>) => RenderOutput;
+export declare const ChatScreen: (props: Record<string, never>) => RenderOutput;
+export declare const NewSessionScreen: (props: Record<string, never>) => RenderOutput;
+/**
+ * The changeset, and one file out of it.
+ *
+ * Two states of one screen rather than two screens, because opening a file is
+ * not somewhere you navigate to: escape goes back to the list and then out,
+ * the way it does everywhere else here. Which file is in the store so that
+ * leaving for the conversation and coming back arrives where it was.
+ *
+ * The content is fetched when a row opens and never before. A changeset is a
+ * list of names the host sends up front and a pile of bytes it does not, and
+ * a screen that read both together would download a session's whole diff to
+ * draw a list of filenames.
+ */
+export declare const ChangesScreen: (props: Record<string, never>) => RenderOutput;
+/**
+ * Writing one down.
+ *
+ * The half that was missing: this client could list, run and switch off an
+ * automation and could not make one, so the only way to have any was to write
+ * the daemon's own file by hand and restart it. That is not a workflow, it is
+ * what a person does when a client has a hole in it.
+ *
+ * The expression is checked here and *understood* on the host. `scheduleProblem`
+ * reads the protocol's grammar and stops there; when it next comes round is the
+ * host's answer, and it arrives as `nextRunAt` on the row this screen leaves
+ * behind. So the confirmation that a schedule is real is the list saying when it
+ * will fire, not this form saying it looks right.
+ *
+ * Manual-only is a real choice and not an empty box. The protocol says an
+ * automation with no triggers is one nothing fires, so leaving the schedule
+ * blank writes a definition with an empty trigger list rather than a broken one.
+ */
+export declare const NewAutomationScreen: (props: Record<string, never>) => RenderOutput;
+/**
+ * What the host does without being asked.
+ *
+ * The catalogue answers "what has been said"; this answers "what will happen".
+ * They are both the host's and only one of them was drawn, so a session that
+ * appeared at nine this morning was a session with no account of itself - which
+ * is what protocol 0.9.0's `origin` is for, and it is read on the catalogue
+ * rather than here.
+ *
+ * Read whole on every change rather than patched. The channel says an
+ * automation moved and the list is a dozen rows; a client that reduced its own
+ * copy would be a second answer to what the host holds, for no gain at this
+ * size.
+ */
+export declare const AutomationsScreen: (props: Record<string, never>) => RenderOutput;
+/**
+ * The host's filesystem, browsed.
+ *
+ * `resourceList` and `resourceRead` were on the connection and behind
+ * `ahpc resource`, and the only place a host's files were *drawn* was the `@`
+ * completion in the composer - so a host that serves a project made people
+ * type paths they could not see.
+ *
+ * One directory at a time rather than a tree: `resourceList` answers about one
+ * directory, and an expanding tree would be a request per node with nothing on
+ * screen meanwhile. Opening a file reads it and shows it; nothing here writes,
+ * though the host would now allow it - see the roadmap.
+ */
+export declare const FilesScreen: (props: Record<string, never>) => RenderOutput;
+export declare const SkillsScreen: (props: Record<string, never>) => RenderOutput;
+export declare const McpScreen: (props: Record<string, never>) => RenderOutput;
+export declare const SettingsScreen: (props: Record<string, never>) => RenderOutput;
+export declare const HostsScreen: (props: Record<string, never>) => RenderOutput;