team 0.0.1 → 0.1.1

package/dist/launch/execute.js

@@ -0,0 +1,284 @@
+async function until(seconds, pace, host, ready) {
+    const deadline = host.now() + seconds * 1000;
+    for (;;) {
+        if (ready())
+            return true;
+        if (host.now() >= deadline)
+            return false;
+        const before = host.now();
+        await host.sleep(pace);
+        // A clock that does not move would spin. Treat that as the wait running out.
+        if (host.now() <= before)
+            return false;
+    }
+}
+/** Runs a plan. Steps carry the operation beside the command the dry run prints. */
+export async function executePlan(steps, session, host) {
+    const places = new Map();
+    const dropped = new Set();
+    const logged = new Set();
+    const failedDirs = new Set();
+    let serverFailed = false;
+    let watchFailed = false;
+    let held = false;
+    let abort = false;
+    const finish = (seat, what) => {
+        if (logged.has(seat))
+            return;
+        logged.add(seat);
+        host.say(`${seat}: ${what}\n`);
+        host.log(seat, what);
+    };
+    const place = (label, pane, workspace) => {
+        const have = places.get(label);
+        if (have)
+            return have;
+        if (!pane)
+            return null;
+        const made = { pane, workspace };
+        places.set(label, made);
+        return made;
+    };
+    for (const step of steps) {
+        const op = step.do;
+        const seat = op && 'seat' in op ? op.seat : undefined;
+        if (abort)
+            continue;
+        if (seat && dropped.has(seat))
+            continue;
+        if (step.kind === 'skip') {
+            if (op?.do === 'ready' && op.seat) {
+                if (op.notice)
+                    host.say(`${op.seat}: ${op.notice}\n`);
+                host.record(op.seat, { stage: 'ready', rules: op.rules });
+                finish(op.seat, 'ready');
+            }
+            else if (op?.do === 'refuse') {
+                finish(op.seat, `refused: ${op.why}`);
+            }
+            else
+                host.say(`  skip ${step.text}\n`);
+            continue;
+        }
+        if (!op)
+            continue;
+        switch (op.do) {
+            case 'server': {
+                if (!host.startServer(op.session)) {
+                    serverFailed = true;
+                    abort = true;
+                    host.say(`session ${op.session}: its server did not start\n`);
+                }
+                break;
+            }
+            case 'wait-session': {
+                const up = await until(op.seconds, 1000, host, () => host.sessionUp(op.session) === true);
+                if (!up) {
+                    serverFailed = true;
+                    abort = true;
+                    host.say(`session ${op.session}: it was not running within ${op.seconds} s\n`);
+                }
+                break;
+            }
+            case 'lobby': {
+                // A seat whose lobby folder could not be made is left out at its create step.
+                if (!host.makeDir?.(op.path))
+                    failedDirs.add(op.path);
+                break;
+            }
+            case 'create': {
+                if (op.seat && op.notice)
+                    host.say(`${op.seat}: ${op.notice}\n`);
+                if (op.seat) {
+                    const why = host.allow(op.seat);
+                    if (why) {
+                        dropped.add(op.seat);
+                        finish(op.seat, why);
+                        break;
+                    }
+                    if (failedDirs.has(op.cwd)) {
+                        dropped.add(op.seat);
+                        finish(op.seat, 'its lobby folder was not created; left out');
+                        break;
+                    }
+                    host.record(op.seat, { stage: 'launched' });
+                }
+                const made = host.createWorkspace(session, op.cwd, op.label);
+                if (!made) {
+                    if (op.seat) {
+                        dropped.add(op.seat);
+                        finish(op.seat, 'its workspace was not created; left at launched');
+                    }
+                    else {
+                        watchFailed = true;
+                        host.say('watch: its workspace was not created\n');
+                        host.log('watch', 'its workspace was not created');
+                    }
+                    break;
+                }
+                places.set(op.label, made);
+                if (op.seat) {
+                    host.record(op.seat, { stage: 'launched', pane: made.pane, workspace: made.workspace });
+                    host.running(op.seat);
+                }
+                break;
+            }
+            case 'launch': {
+                if (op.notice)
+                    host.say(`${op.seat}: ${op.notice}\n`);
+                const why = host.allow(op.seat);
+                if (why) {
+                    dropped.add(op.seat);
+                    finish(op.seat, why);
+                    break;
+                }
+                const here = place(op.label, op.pane);
+                if (!here || !host.paneRun(session, here.pane, op.command)) {
+                    dropped.add(op.seat);
+                    finish(op.seat, 'its launch command did not run; left at launched');
+                    break;
+                }
+                host.running(op.seat);
+                break;
+            }
+            case 'idle': {
+                if (op.notice)
+                    host.say(`${op.seat}: ${op.notice}\n`);
+                const here = place(op.label, op.pane, op.workspace);
+                if (!here) {
+                    dropped.add(op.seat);
+                    finish(op.seat, 'has no pane to read; left at launched');
+                    break;
+                }
+                const deadline = host.now() + op.seconds * 1000;
+                let outcome = 'timeout';
+                for (;;) {
+                    const kind = host.classify(session, here.pane, op.cli);
+                    if (kind === 'idle' || kind === 'permission' || kind === 'trust' || kind === 'question') {
+                        outcome = kind;
+                        break;
+                    }
+                    if (host.now() >= deadline)
+                        break;
+                    const before = host.now();
+                    await host.sleep(2000);
+                    if (host.now() <= before)
+                        break;
+                }
+                if (outcome === 'idle')
+                    break;
+                const workspace = here.workspace ?? places.get(op.label)?.workspace;
+                if (outcome === 'permission' || outcome === 'trust' || outcome === 'question') {
+                    // A trust question is closed with no key and no text. The same for a permission or a question.
+                    if (workspace)
+                        host.closeWorkspace(session, workspace);
+                    host.drop(op.seat);
+                    dropped.add(op.seat);
+                    const why = outcome === 'trust'
+                        ? 'left out: trust question'
+                        : `${outcome}; its workspace was closed without input and the seat left out`;
+                    finish(op.seat, why);
+                    break;
+                }
+                dropped.add(op.seat);
+                finish(op.seat, 'timed out waiting for its idle prompt; left at launched');
+                break;
+            }
+            case 'rename': {
+                const here = place(op.label, op.pane);
+                if (!here) {
+                    dropped.add(op.seat);
+                    finish(op.seat, 'has no pane to name; left at launched');
+                    break;
+                }
+                const seen = await until(op.seconds, 2000, host, () => host.agentPanes(session)?.includes(here.pane) === true);
+                if (!seen || !host.renameAgent(session, here.pane, op.seat)) {
+                    dropped.add(op.seat);
+                    finish(op.seat, 'was not in the agent list in time; left at launched');
+                    break;
+                }
+                host.record(op.seat, { stage: 'named', pane: here.pane, workspace: here.workspace });
+                if (op.rules === 'option') {
+                    host.record(op.seat, { stage: 'ready', rules: 'option', pane: here.pane, workspace: here.workspace });
+                    finish(op.seat, 'ready');
+                }
+                break;
+            }
+            case 'deliver': {
+                if (op.notice)
+                    host.say(`${op.seat}: ${op.notice}\n`);
+                const here = place(op.label, op.pane);
+                if (!here || !await host.deliverRules?.(session, here.pane, op.cli, op.rules, op.seconds)) {
+                    dropped.add(op.seat);
+                    finish(op.seat, 'its rules were not delivered; left at named');
+                    break;
+                }
+                host.record(op.seat, { stage: 'ready', rules: 'message', pane: here.pane });
+                finish(op.seat, 'ready');
+                break;
+            }
+            case 'watch': {
+                const here = places.get(op.label);
+                if (!here || !host.paneRun(session, here.pane, op.command)) {
+                    watchFailed = true;
+                    host.say('watch: it did not start\n');
+                    host.log('watch', 'it did not start');
+                    break;
+                }
+                host.say('watch: started\n');
+                host.log('watch', 'started');
+                break;
+            }
+            case 'type': {
+                if (!host.typeLine(session, op.pane, op.text)) {
+                    held = true;
+                    dropped.add(op.seat);
+                    finish(op.seat, 'its exit was not typed; left as it is');
+                }
+                break;
+            }
+            case 'gone': {
+                const gone = await until(op.seconds, 2000, host, () => host.agentPanes(session)?.includes(op.pane) === false);
+                if (!gone) {
+                    held = true;
+                    dropped.add(op.seat);
+                    finish(op.seat, 'timed out leaving its pane; left as it is');
+                }
+                break;
+            }
+            case 'close': {
+                if (!host.closeWorkspace(session, op.workspace)) {
+                    held = true;
+                    finish(op.seat, 'its workspace did not close');
+                    break;
+                }
+                host.drop(op.seat);
+                finish(op.seat, 'stopped');
+                break;
+            }
+            case 'kill': {
+                if (!host.kill(op.pid)) {
+                    held = true;
+                    host.say(`watch: pid ${op.pid} did not stop\n`);
+                }
+                else
+                    host.say('watch: stopped\n');
+                break;
+            }
+            case 'stop': {
+                if (held) {
+                    host.say(`session ${op.session}: not stopped, something was left in it\n`);
+                    break;
+                }
+                if (!host.stopSession(op.session))
+                    host.say(`session ${op.session}: it did not stop\n`);
+                else
+                    host.say(`session ${op.session}: stopped\n`);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return { serverFailed, watchFailed, held };
+}

package/dist/launch/plan.d.ts

@@ -0,0 +1,185 @@
+/**
+ * What running a step does. The printed command stays in `argv`; this is how the live command
+ * performs that same step, so a dry run and a real run share one plan.
+ */
+export type Op = {
+    do: 'server';
+    session: string;
+} | {
+    do: 'wait-session';
+    session: string;
+    seconds: number;
+} | {
+    do: 'lobby';
+    path: string;
+} | {
+    do: 'create';
+    seat?: string;
+    label: string;
+    cwd: string;
+    notice?: string;
+} | {
+    do: 'launch';
+    seat: string;
+    label: string;
+    command: string;
+    pane?: string;
+    notice?: string;
+} | {
+    do: 'refuse';
+    seat: string;
+    why: string;
+} | {
+    do: 'idle';
+    seat: string;
+    label: string;
+    cli: string;
+    seconds: number;
+    pane?: string;
+    workspace?: string;
+    notice?: string;
+} | {
+    do: 'rename';
+    seat: string;
+    label: string;
+    seconds: number;
+    rules: 'option' | 'message';
+    pane?: string;
+} | {
+    do: 'deliver';
+    seat: string;
+    label: string;
+    cli: string;
+    rules: string;
+    seconds: number;
+    pane?: string;
+    notice?: string;
+} | {
+    do: 'ready';
+    seat: string;
+    rules: 'option' | 'message';
+    notice?: string;
+} | {
+    do: 'watch';
+    label: string;
+    command: string;
+} | {
+    do: 'type';
+    seat: string;
+    pane: string;
+    text: string;
+} | {
+    do: 'gone';
+    seat: string;
+    pane: string;
+    seconds: number;
+} | {
+    do: 'close';
+    seat: string;
+    workspace: string;
+} | {
+    do: 'kill';
+    pid: number;
+} | {
+    do: 'stop';
+    session: string;
+};
+/** One thing `up` or `down` does, in order. */
+export type Step = 
+/** A command that is run. */
+{
+    kind: 'run';
+    argv: string[];
+    note?: string;
+    do?: Op;
+}
+/** A wait, with its time limit. */
+ | {
+    kind: 'wait';
+    text: string;
+    note?: string;
+    do?: Op;
+}
+/** A seat that is left out, and why. */
+ | {
+    kind: 'skip';
+    text: string;
+    note?: string;
+    do?: Op;
+};
+export interface UpSeat {
+    name: string;
+    cli: string;
+    launch: string;
+    /** Relative to the root. */
+    cwd: string;
+    label: string;
+    stopped: boolean;
+    /** The seat's rules, as one text. */
+    rules: string;
+    /** Set when a running session is being resumed. Omitted: launch from the start. */
+    stage?: 'launched' | 'named' | 'ready';
+    pane?: string;
+    workspace?: string;
+    /** Herdr already lists an agent in the recorded pane. */
+    agentLive?: boolean;
+    /** The seat works in worktrees: it waits in the lobby until a brief names its worktree. */
+    lobby?: boolean;
+    /**
+     * Set when a counted reading is inside the reserve, or the figure is unknown
+     * or a first sight. A refusal stops the seat only when this plan would launch it.
+     */
+    budget?: {
+        kind: 'refuse';
+        why: string;
+    } | {
+        kind: 'unknown';
+        account: string;
+        text: string;
+    };
+}
+export interface UpInput {
+    /** The project root; seats start in it. */
+    root: string;
+    session: string;
+    /** Whether the herdr session is already running, empty. */
+    sessionRunning: boolean;
+    seats: readonly UpSeat[];
+    /** The watch's pid is alive, so no second watch is started. */
+    watchAlive?: boolean;
+    /** The command the watchdog pane runs. Defaults to `team watch`. */
+    watchLine?: string;
+}
+/** The variables a herdr server starts with: nothing else reaches a seat's pane. */
+export declare const SERVER_ENVIRONMENT: readonly ["HOME", "USER", "LOGNAME", "PATH", "SHELL", "TERM", "LANG"];
+/** `herdr` aimed at a session; herdr's default session takes no option. */
+export declare function herdr(session: string, ...args: string[]): string[];
+/** What stands for a pane id that only exists once its workspace is created. */
+export declare function paneOf(label: string): string;
+/** Every step of `team up`, in order. Nothing here runs anything. */
+export declare function upPlan(input: UpInput): Step[];
+export interface DownSeat {
+    name: string;
+    cli: string;
+    pane: string;
+    workspace: string;
+    /** What the watch's reading says of the seat: only a free seat is stopped. */
+    state: 'free' | 'working' | 'blocked' | 'unknown' | 'unsent';
+}
+export interface DownInput {
+    session: string;
+    /** The running seats the file and the state name; nothing else is closed. */
+    seats: readonly DownSeat[];
+    /** Agents in the session that the file and the state don't name. */
+    extra: number;
+    /** The watch's pid, when its state records one that is alive. */
+    watchPid: number | null;
+    /** The caller's own seat, and the coordinator's and operator's, when a seat calls. */
+    keep: readonly string[];
+    /** The owner is closing workspaces that are not free, without typing into them. */
+    abandon?: boolean;
+}
+/** Every step of `team down`, in order. Nothing here runs anything. */
+export declare function downPlan(input: DownInput): Step[];
+/** The plan as `--dry-run` prints it. */
+export declare function formatPlan(steps: readonly Step[]): string;