team 0.0.1 → 0.1.0

package/dist/commands/up.js

@@ -0,0 +1,361 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { approvalDifferences, budgetsInForce } from "../approve/approval.js";
+import { readArgs } from "../args.js";
+import { callerOf, describeCaller, isOwner } from "../caller.js";
+import { loadTeamFile } from "../file/load.js";
+import { renderSignature } from "../file/signature.js";
+import { agentList, agentStatus, agentRename, paneRead, paneRun, typeText, pressEnter, sessionRunning, sessionState, startServer, workspaceClose, workspaceCreate, workspaceList, } from "../herdr.js";
+import { executePlan } from "../launch/execute.js";
+import { formatPlan, upPlan } from "../launch/plan.js";
+import { rulesText } from "../launch/rules.js";
+import { deliverRules } from "../launch/deliver.js";
+import { logLine } from "../log.js";
+import { shellQuote } from "../profiles/profile.js";
+import { profileFor } from "../profiles/index.js";
+import { readApproval, storePath } from "../store/store.js";
+import { emptySession, readState, updateState } from "../state.js";
+import { seatBudget } from "../budgets/gate.js";
+import { loadReadings } from "../budgets/readings.js";
+import { blocksLaunch, doctorFindings, realSources as doctorSources } from "./doctor.js";
+import { launchLimit, readMachine } from "../watch/machine.js";
+import { readScreen } from "../watch/screen.js";
+import { seatStart } from "../worktree/place.js";
+function aim(session) {
+    return session === 'default' ? undefined : session;
+}
+/** The watchdog command, from this process and this install: `team` may not be on the PATH. */
+export function watchCommand(session) {
+    const here = fileURLToPath(import.meta.url);
+    const cli = join(dirname(here), '..', here.endsWith('.ts') ? 'cli.ts' : 'cli.js');
+    const suffix = session === 'default' ? '' : ` --session ${shellQuote(session)}`;
+    return `${shellQuote(process.execPath)} ${shellQuote(cli)} watch${suffix}`;
+}
+const realLaunch = {
+    sessionState,
+    startServer,
+    sessionUp: sessionRunning,
+    createWorkspace: (session, cwd, label) => workspaceCreate(cwd, label, aim(session)),
+    paneRun: (session, pane, command) => paneRun(pane, command, aim(session)),
+    renameAgent: (session, pane, name) => agentRename(pane, name, aim(session)),
+    closeWorkspace: (session, workspace) => workspaceClose(workspace, aim(session)),
+    agentPanes(session) {
+        const agents = agentList(aim(session));
+        return agents === null ? null : agents.map((agent) => agent.pane);
+    },
+    paneText: (session, pane) => paneRead(pane, 200, aim(session)),
+    typeText: (session, pane, text) => typeText(pane, text, aim(session)),
+    pressEnter: (session, pane) => pressEnter(pane, aim(session)),
+    agentStatus: (session, pane) => agentStatus(pane, aim(session)),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => new Date(),
+};
+export const realSources = {
+    sessionRunning,
+    sessionState,
+    agents: (session) => agentList(aim(session)),
+    workspaces: (session) => workspaceList(aim(session)),
+    home: homedir(),
+    doctor: doctorSources,
+    machine: readMachine,
+    now: () => new Date(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    alive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    watchCommand,
+    launch: realLaunch,
+};
+export const USAGE = 'Usage: team up [--dry-run] [--session <name>] [--file <path>]\n';
+export const up = (argv, io) => runUp(argv, io, realSources);
+export default up;
+/** The rules one seat gets at launch, with its own signature lines. */
+export function rulesOf(team, seat) {
+    const { commits, pullRequests } = team.identity.signature;
+    return rulesText({
+        coordinator: team.coordinator,
+        rules: team.rules,
+        signature: {
+            commit: renderSignature(commits.template, seat),
+            pullRequest: renderSignature(pullRequests.template, seat),
+            commitPosition: commits.position,
+        },
+        workspace: { mode: seat.mode, protected: team.workspace.protected, branch: team.workspace.branch },
+    });
+}
+function resolveState(sources, session) {
+    if (sources.sessionState)
+        return sources.sessionState(session);
+    const running = sources.sessionRunning(session);
+    if (running === null)
+        return null;
+    return running ? 'running' : 'absent';
+}
+function overCeiling(ceilings, running, seat) {
+    if (running.some((item) => item.name === seat.name))
+        return null;
+    const count = running.length + 1;
+    if (count > ceilings.seats)
+        return `the approval allows ${ceilings.seats} seats; ${count} would be running`;
+    const cap = ceilings.vendors[seat.vendor];
+    if (cap !== undefined) {
+        const vendors = running.filter((item) => item.vendor === seat.vendor).length + 1;
+        if (vendors > cap)
+            return `the approval allows ${cap} ${seat.vendor} seats; ${vendors} would be running`;
+    }
+    return null;
+}
+function seatPlan(team, seat, recorded, agents, workspaces, resume) {
+    const planned = {
+        name: seat.name,
+        cli: seat.cli,
+        launch: seat.launch,
+        cwd: seat.cwd,
+        label: seat.label,
+        stopped: seat.stopped,
+        rules: rulesOf(team, seat),
+    };
+    if (!resume || !recorded || seat.stopped)
+        return planned;
+    const named = agents.find((agent) => agent.name === seat.name);
+    const onPane = recorded.pane ? agents.some((agent) => agent.pane === recorded.pane) : false;
+    if (recorded.stage === 'ready')
+        return named || onPane ? { ...planned, stage: 'ready' } : planned;
+    const workspaceLive = recorded.workspace && workspaces ? workspaces.some((workspace) => workspace.id === recorded.workspace) : null;
+    const live = Boolean(named || onPane || workspaceLive);
+    if (!live)
+        return planned;
+    return {
+        ...planned,
+        stage: recorded.stage,
+        pane: recorded.pane,
+        workspace: recorded.workspace,
+        agentLive: Boolean(named || onPane),
+    };
+}
+export async function runUp(argv, io, sources) {
+    const args = readArgs(argv, ['session', 'file'], ['dry-run']);
+    if (args.error || args.rest.length) {
+        io.stderr(`team up: ${args.error ?? `unexpected "${args.rest[0]}"`}\n${USAGE}`);
+        return 2;
+    }
+    const dry = args.flags.has('dry-run');
+    const loaded = loadTeamFile(io.cwd, args.values.file ? { file: args.values.file } : {});
+    if (!loaded.ok) {
+        for (const problem of loaded.errors) {
+            io.stderr(`team up: ${problem.line ? `line ${problem.line}: ` : ''}${problem.message}\n`);
+        }
+        return 2;
+    }
+    const { team, root } = loaded;
+    const session = args.values.session ?? team.session;
+    const dir = dirname(loaded.path);
+    const state = resolveState(sources, session);
+    // What would make `up` refuse. A dry run prints the plan anyway; a real run stops first.
+    const refusals = [];
+    const caller = callerOf(io);
+    if (!isOwner(caller)) {
+        refusals.push(`only the owner runs \`up\`, from a terminal outside herdr; this call is ${describeCaller(caller)}`);
+    }
+    const differences = approvalDifferences(team, root, sources.home);
+    if (differences === null)
+        refusals.push('the file was never approved on this machine: run `team approve`');
+    else if (differences.length) {
+        refusals.push(`the file is not the approved one (${differences.join('; ')}): run \`team approve\``);
+    }
+    // The budget readings the gate refuses on are the approved ones: an unapproved lower reserve
+    // unblocks nothing, not even the seat a dry run would plan.
+    const budgets = budgetsInForce(team, root, sources.home);
+    if (sources.doctor) {
+        const findings = doctorFindings(team, root, dir, session, sources.doctor, loaded.warnings);
+        for (const finding of findings)
+            if (blocksLaunch(finding))
+                refusals.push(finding.text);
+    }
+    const samples = [];
+    const readAt = () => (sources.now?.() ?? new Date()).getTime();
+    const crossed = (machine) => launchLimit(machine, team.machine, samples, readAt());
+    const machine = sources.machine?.(root);
+    if (machine) {
+        const problem = crossed(machine);
+        if (problem)
+            refusals.push(problem);
+    }
+    if (state === null)
+        refusals.push("herdr doesn't answer");
+    if (state === 'stopped') {
+        refusals.push(`session ${session} is stopped; clear it with \`herdr session delete ${session}\``);
+    }
+    const agents = state === 'running' ? sources.agents(session) : [];
+    if (state === 'running') {
+        const recorded = readState(dir).sessions[session]?.seats ?? {};
+        if (agents === null)
+            refusals.push(`session ${session} runs, and its agents can't be read`);
+        else {
+            const unknown = agents.filter((agent) => !agent.name || !Object.hasOwn(recorded, agent.name));
+            if (unknown.length) {
+                refusals.push(`session ${session} has ${unknown.length} agent${unknown.length === 1 ? '' : 's'} this file's state doesn't record: \`up\` never touches a running team`);
+            }
+        }
+    }
+    const recorded = readState(dir).sessions[session];
+    const workspaces = sources.workspaces?.(session) ?? null;
+    const readings = loadReadings(dir, session);
+    const seats = [];
+    const refused = new Set();
+    for (const seat of team.seats) {
+        const planned = seatPlan(team, seat, recorded?.seats[seat.name], agents ?? [], workspaces, state === 'running');
+        // A stopped seat, one without a profile, and one already ready are left out of the budget.
+        // A seat resumed into a live workspace starts nowhere new, but its reading is still said.
+        if (planned.stopped || !profileFor(seat.cli) || planned.stage === 'ready') {
+            seats.push(planned);
+            continue;
+        }
+        const placed = planned.stage === undefined || !planned.pane;
+        if (!placed) {
+            const budget = seatBudget(budgets, readings, seat, readAt());
+            seats.push({ ...planned, ...(budget.kind === 'clear' ? {} : { budget }) });
+            continue;
+        }
+        const start = seatStart(team, seat, root);
+        if ('problem' in start) {
+            if (!start.once || !refused.has(start.problem)) {
+                refused.add(start.problem);
+                refusals.push(start.problem);
+            }
+            continue;
+        }
+        const budget = seatBudget(budgets, readings, seat, readAt());
+        seats.push({
+            ...planned,
+            cwd: start.cwd,
+            ...(start.lobby ? { lobby: true } : {}),
+            ...(budget.kind === 'clear' ? {} : { budget }),
+        });
+    }
+    const watch = recorded?.watch;
+    const plan = upPlan({
+        root,
+        session,
+        // A stopped session is not started. The refusal above names the delete command.
+        sessionRunning: state === 'running' || state === 'stopped',
+        seats,
+        watchAlive: Boolean(watch && sources.alive?.(watch.pid)),
+        watchLine: (sources.watchCommand ?? watchCommand)(session),
+    });
+    if (dry) {
+        for (const refusal of refusals)
+            io.stdout(`! up would refuse: ${refusal}\n`);
+        io.stdout(formatPlan(plan));
+        return 0;
+    }
+    if (refusals.length) {
+        for (const refusal of refusals)
+            io.stderr(`team up: ${refusal}\n`);
+        return 1;
+    }
+    const launch = sources.launch;
+    if (!launch) {
+        io.stderr('team up: this call has no way to reach herdr\n');
+        return 1;
+    }
+    const ceilings = readApproval(storePath(team.project, root, sources.home))?.approval.ceilings ?? null;
+    const running = [];
+    if (agents) {
+        const byName = new Map(team.seats.map((seat) => [seat.name, seat]));
+        for (const agent of agents) {
+            if (!agent.name)
+                continue;
+            const seat = byName.get(agent.name);
+            const known = recorded?.seats[agent.name];
+            if (!seat && !known)
+                continue;
+            const like = known?.temporary?.like;
+            const vendor = seat?.vendor ?? (like ? byName.get(like)?.vendor : undefined) ?? 'unknown';
+            running.push({ name: agent.name, vendor, temporary: Boolean(known?.temporary) });
+        }
+    }
+    const now = () => sources.now?.() ?? launch.now();
+    const host = {
+        startServer: launch.startServer,
+        sessionUp: launch.sessionUp,
+        makeDir(path) {
+            try {
+                mkdirSync(path, { recursive: true });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        createWorkspace: launch.createWorkspace,
+        paneRun: launch.paneRun,
+        typeLine: () => false,
+        deliverRules: (session, pane, cli, text, seconds) => deliverRules(cli, text, seconds, {
+            screen: () => launch.paneText(session, pane) ?? undefined,
+            status: () => launch.agentStatus?.(session, pane) ?? null,
+            type: (value) => launch.typeText?.(session, pane, value) ?? false,
+            enter: () => launch.pressEnter?.(session, pane) ?? false,
+            now: () => now().getTime(),
+            sleep: sources.sleep ?? launch.sleep,
+        }),
+        renameAgent: launch.renameAgent,
+        closeWorkspace: launch.closeWorkspace,
+        stopSession: () => false,
+        kill: () => false,
+        agentPanes: launch.agentPanes,
+        classify: (name, pane, cli) => readScreen(cli, launch.paneText(name, pane) ?? undefined).kind,
+        sleep: sources.sleep ?? launch.sleep,
+        now: () => now().getTime(),
+        allow(name) {
+            if (sources.machine) {
+                const problem = crossed(sources.machine(root));
+                if (problem)
+                    return problem;
+            }
+            const seat = team.seats.find((item) => item.name === name);
+            if (!seat || !ceilings)
+                return null;
+            return overCeiling(ceilings, running, seat);
+        },
+        record(name, patch) {
+            updateState(dir, (file) => {
+                const current = (file.sessions[session] ??= emptySession());
+                const prior = current.seats[name] ?? { stage: patch.stage };
+                current.seats[name] = { ...prior, ...patch };
+            });
+        },
+        running(name) {
+            if (running.some((item) => item.name === name))
+                return;
+            const seat = team.seats.find((item) => item.name === name);
+            if (seat)
+                running.push({ name, vendor: seat.vendor, temporary: false });
+        },
+        drop(name) {
+            updateState(dir, (file) => {
+                const seats = file.sessions[session]?.seats;
+                if (seats)
+                    delete seats[name];
+            });
+        },
+        say: (line) => io.stdout(line),
+        log: (who, what) => logLine(dir, 'up', describeCaller(caller), `${who}: ${what}`, now()),
+    };
+    const report = await executePlan(plan, session, host);
+    const afterwards = readState(dir).sessions[session]?.seats ?? {};
+    const pending = team.seats.filter((seat) => {
+        if (seat.stopped || !profileFor(seat.cli))
+            return false;
+        return afterwards[seat.name]?.stage !== 'ready';
+    });
+    return pending.length || report.serverFailed || report.watchFailed ? 1 : 0;
+}

package/dist/commands/watch.d.ts

@@ -0,0 +1,35 @@
+import { type CheckOutcome } from '../budgets/run.ts';
+import type { TeamFile } from '../file/types.ts';
+import type { Command, Io } from '../io.ts';
+import type { Live } from '../status/compare.ts';
+import type { Machine } from '../watch/machine.ts';
+import { type EndView } from '../watch/end.ts';
+import type { DownSeat } from '../launch/plan.ts';
+export type WatchSources = {
+    live(session: string, team: TeamFile): Live | null;
+    machine(root: string): Machine;
+    approval(team: TeamFile, root: string): string[] | null;
+    watchInForce(team: TeamFile, root: string): TeamFile['watch'];
+    budgetsInForce(team: TeamFile, root: string): TeamFile['budgets'];
+    readChecks(team: TeamFile, root: string, now: number): CheckOutcome[];
+    screen(pane: string, session: string): string | null;
+    status(pane: string, session: string): string | null;
+    typeText(pane: string, text: string, session: string): boolean;
+    pressEnter(pane: string, session: string): boolean;
+    notify(text: string): void;
+    now(): Date;
+    wait(seconds: number): Promise<boolean>;
+    alive(pid: number): boolean;
+    pid: number;
+    /** How an end is read. The real watch uses git and the filesystem. */
+    readEnd?(root: string, until: string, base: string | null, ownBefore: boolean): EndView;
+    /** Stops one free seat. The real watch uses the same steps as `remove`. */
+    stopSeat?(session: string, seat: DownSeat): Promise<boolean>;
+    /** Removes one merged worktree. The real watch calls `worktree remove`. */
+    removeWorktree?(task: string): number;
+};
+export declare const realWatchSources: WatchSources;
+export declare const watch: Command;
+export default watch;
+export declare const USAGE = "Usage: team watch [--session <name>] [--file <path>] [--no-nudge] [--no-notify]\n";
+export declare function runWatch(argv: string[], io: Io, sources: WatchSources): Promise<number>;