team 0.0.1 → 0.1.1

package/dist/file/write.d.ts

@@ -0,0 +1,11 @@
+import type { Problem } from './types.ts';
+/**
+ * The one write of a team file. The text is validated first. An invalid edit is refused and
+ * the file is left untouched. A valid one is written by a temporary file and a rename.
+ */
+export declare function writeTeamFile(path: string, text: string): {
+    ok: true;
+} | {
+    ok: false;
+    errors: Problem[];
+};

package/dist/file/write.js

@@ -0,0 +1,13 @@
+import { writeAtomic } from "../state.js";
+import { validateTeamFile } from "./validate.js";
+/**
+ * The one write of a team file. The text is validated first. An invalid edit is refused and
+ * the file is left untouched. A valid one is written by a temporary file and a rename.
+ */
+export function writeTeamFile(path, text) {
+    const parsed = validateTeamFile(text);
+    if (!parsed.ok)
+        return { ok: false, errors: parsed.errors };
+    writeAtomic(path, text);
+    return { ok: true };
+}

package/dist/herdr.d.ts

@@ -0,0 +1,38 @@
+export type HerdrAgent = {
+    name: string | null;
+    agent: string | null;
+    pane: string;
+    workspace: string;
+    status: string;
+    cwd: string | null;
+};
+export declare function agentList(session?: string): HerdrAgent[] | null;
+export declare function paneRootPid(pane: string, session?: string): number | null;
+export declare function paneForeground(pane: string, session?: string): string[] | null;
+export type HerdrWorkspace = {
+    id: string;
+    label: string;
+};
+export declare function workspaceList(session?: string): HerdrWorkspace[] | null;
+export type SessionState = 'running' | 'stopped' | 'absent';
+export declare function sessionState(name: string): SessionState | null;
+export declare function sessionRunning(name: string): boolean | null;
+export declare function startServer(session: string): boolean;
+export declare function workspaceCreate(cwd: string, label: string, session?: string): {
+    pane: string;
+    workspace: string;
+} | null;
+export declare function paneRun(pane: string, command: string, session?: string): boolean;
+export declare function agentRename(pane: string, name: string, session?: string): boolean;
+export declare function workspaceClose(workspace: string, session?: string): boolean;
+export declare function sessionStop(name: string): boolean;
+export declare function paneRead(pane: string, lines: number, session?: string): string | null;
+export declare function herdrCommand(session: string | undefined, ...args: string[]): string;
+export declare function typeText(pane: string, text: string, session?: string): boolean;
+export declare function pressEnter(pane: string, session?: string): boolean;
+export declare function agentStatus(pane: string, session?: string): string | null;
+export declare const HERDR_TESTED: {
+    from: string;
+    to: string;
+};
+export declare function herdrVersion(): string | null;

package/dist/herdr.js

@@ -0,0 +1,227 @@
+import { execFileSync, spawn } from 'node:child_process';
+function run(args, session) {
+    const full = session ? ['--session', session, ...args] : args;
+    const out = execFileSync('herdr', full, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 });
+    return JSON.parse(out).result;
+}
+// The agents herdr lists, or null when herdr can't be reached.
+export function agentList(session) {
+    try {
+        const result = run(['agent', 'list'], session);
+        return (result.agents ?? []).map((agent) => ({
+            name: typeof agent.name === 'string' && agent.name ? agent.name : null,
+            agent: typeof agent.agent === 'string' ? agent.agent : null,
+            pane: String(agent.pane_id),
+            workspace: String(agent.workspace_id),
+            status: typeof agent.agent_status === 'string' ? agent.agent_status : 'unknown',
+            cwd: typeof agent.cwd === 'string' ? agent.cwd : null,
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+// The pid of a pane's root process, or null. Always by `--pane`: herdr 0.7.1's `--current`
+// answered for another pane than the caller's.
+export function paneRootPid(pane, session) {
+    try {
+        const result = run(['pane', 'process-info', '--pane', pane], session);
+        const pid = result.process_info?.shell_pid;
+        return typeof pid === 'number' ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+// argv0 of each foreground process, or null when the pane can't be read. After a CLI exits,
+// herdr keeps the pane and the foreground process is the shell.
+export function paneForeground(pane, session) {
+    try {
+        const result = run(['pane', 'process-info', '--pane', pane], session);
+        const list = result.process_info?.foreground_processes;
+        if (!Array.isArray(list))
+            return null;
+        return list.map((proc) => (typeof proc.argv0 === 'string' ? proc.argv0 : ''));
+    }
+    catch {
+        return null;
+    }
+}
+export function workspaceList(session) {
+    try {
+        const result = run(['workspace', 'list'], session);
+        return (result.workspaces ?? []).map((workspace) => ({
+            id: String(workspace.workspace_id),
+            label: typeof workspace.label === 'string' ? workspace.label : '',
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+// Whether a session exists and runs. A stopped session stays listed with running false; a deleted
+// one is absent. Null when herdr can't be reached. "default" is herdr's own.
+export function sessionState(name) {
+    try {
+        const out = execFileSync('herdr', ['session', 'list', '--json'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10_000,
+        });
+        const sessions = JSON.parse(out).sessions ?? [];
+        const found = sessions.find((session) => session.name === name);
+        if (!found)
+            return 'absent';
+        return found.running === true ? 'running' : 'stopped';
+    }
+    catch {
+        return null;
+    }
+}
+// Whether a session exists and runs: null when herdr can't be reached.
+export function sessionRunning(name) {
+    const state = sessionState(name);
+    return state === null ? null : state === 'running';
+}
+// What a herdr command printed, or null when it did not run. Exit status is not the answer: a
+// command aimed at a session that does not exist can print an error and exit 0.
+function capture(args, session) {
+    const full = [...(session ? ['--session', session] : []), ...args];
+    try {
+        return execFileSync('herdr', full, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000 });
+    }
+    catch {
+        return null;
+    }
+}
+function parsed(out) {
+    try {
+        return JSON.parse(out);
+    }
+    catch {
+        return null;
+    }
+}
+function resultOf(args, session) {
+    const out = capture(args, session);
+    if (out === null)
+        return null;
+    const body = parsed(out);
+    if (!body || body.type === 'error')
+        return null;
+    return body.result ?? null;
+}
+const SERVER_ENV = ['HOME', 'USER', 'LOGNAME', 'PATH', 'SHELL', 'TERM', 'LANG'];
+// Starts a session's server in a clean environment. Refuses unless the session is absent: a
+// second server for a session that already runs has been seen to drop it.
+export function startServer(session) {
+    if (sessionState(session) !== 'absent')
+        return false;
+    const env = {};
+    for (const name of SERVER_ENV) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    if (process.env.SSH_AUTH_SOCK)
+        env.SSH_AUTH_SOCK = process.env.SSH_AUTH_SOCK;
+    const args = session === 'default' ? ['server'] : ['--session', session, 'server'];
+    try {
+        const child = spawn('herdr', args, { env, detached: true, stdio: 'ignore' });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function workspaceCreate(cwd, label, session) {
+    const result = resultOf(['workspace', 'create', '--cwd', cwd, '--label', label, '--no-focus'], session);
+    const pane = result?.root_pane?.pane_id;
+    const workspace = result?.workspace?.workspace_id;
+    if (typeof pane !== 'string' || typeof workspace !== 'string')
+        return null;
+    return { pane, workspace };
+}
+// Types a command into a pane and sends it. For a seat's launch, at a shell. An exit into an
+// agent is `typeText` and then `pressEnter`, and only after the screen was read as idle again.
+export function paneRun(pane, command, session) {
+    const out = capture(['pane', 'run', pane, command], session);
+    if (out === null)
+        return false;
+    const body = parsed(out);
+    return body === null || body.type !== 'error';
+}
+// Not proof an agent is there: herdr answers with agent_info for a pane that has none.
+export function agentRename(pane, name, session) {
+    const out = capture(['agent', 'rename', pane, name], session);
+    if (out === null)
+        return false;
+    const body = parsed(out);
+    return body === null || body.type !== 'error';
+}
+export function workspaceClose(workspace, session) {
+    const out = capture(['workspace', 'close', workspace], session);
+    if (out === null)
+        return false;
+    const body = parsed(out);
+    return body !== null && body.type !== 'error';
+}
+// Stops a session. Never deletes one: clearing a stopped session is the owner's command to run.
+export function sessionStop(name) {
+    const out = capture(['session', 'stop', name]);
+    if (out === null)
+        return false;
+    const body = parsed(out);
+    return body === null || body.type !== 'error';
+}
+// The visible lines of a pane, or null. `session` undefined reaches the caller's own server.
+export function paneRead(pane, lines, session) {
+    try {
+        const full = [...(session ? ['--session', session] : []), 'pane', 'read', pane, '--source', 'visible', '--lines', String(lines)];
+        return execFileSync('herdr', full, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 });
+    }
+    catch {
+        return null;
+    }
+}
+// The words to type for a herdr command, for a repair line.
+export function herdrCommand(session, ...args) {
+    return ['herdr', ...(session && session !== 'default' ? ['--session', session] : []), ...args].join(' ');
+}
+// The two functions that type. Their callers have just seen the pane at an empty idle prompt,
+// look at it again between the text and the Enter, and type nothing anywhere else.
+export function typeText(pane, text, session) {
+    try {
+        execFileSync('herdr', [...(session ? ['--session', session] : []), 'pane', 'send-text', pane, text], { stdio: 'ignore', timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function pressEnter(pane, session) {
+    try {
+        execFileSync('herdr', [...(session ? ['--session', session] : []), 'pane', 'send-keys', pane, 'enter'], { stdio: 'ignore', timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// The status herdr reports for one pane's agent, or null.
+export function agentStatus(pane, session) {
+    return agentList(session)?.find((agent) => agent.pane === pane)?.status ?? null;
+}
+// The herdr versions this version of `team` was run with.
+export const HERDR_TESTED = { from: '0.7.1', to: '0.7.1' };
+// What `herdr --version` prints, without the name, or null when herdr can't be run.
+export function herdrVersion() {
+    try {
+        const out = execFileSync('herdr', ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 });
+        return out.trim().replace(/^herdr\s+/, '') || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { parseYaml, toValue, YamlError } from './yaml.ts';
+export type { YamlEntry, YamlNode, YamlScalar, YamlValue } from './yaml.ts';
+export { validateTeamFile } from './file/validate.ts';
+export { findRoot, loadTeamFile, TEAM_FILE } from './file/load.ts';
+export { DEFAULT_COMMIT_TEMPLATE, DEFAULT_FORBIDDEN, DEFAULT_PR_TEMPLATE, renderSignature } from './file/signature.ts';
+export type { LoadResult, Mode, Position, Problem, Seat, TeamFile, ValidateResult } from './file/types.ts';
+export { callerOf, currentCaller, describeCaller, isOwner, mayChangeTeam, placeCaller, readAncestors } from './caller.ts';
+export type { Caller, CallerSources, Process } from './caller.ts';
+export { CLIS, PROFILES } from './clis.ts';
+export type { Command, Io } from './io.ts';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { parseYaml, toValue, YamlError } from "./yaml.js";
+export { validateTeamFile } from "./file/validate.js";
+export { findRoot, loadTeamFile, TEAM_FILE } from "./file/load.js";
+export { DEFAULT_COMMIT_TEMPLATE, DEFAULT_FORBIDDEN, DEFAULT_PR_TEMPLATE, renderSignature } from "./file/signature.js";
+export { callerOf, currentCaller, describeCaller, isOwner, mayChangeTeam, placeCaller, readAncestors } from "./caller.js";
+export { CLIS, PROFILES } from "./clis.js";

package/dist/io.d.ts

@@ -0,0 +1,10 @@
+import type { Caller } from './caller.ts';
+export type Io = {
+    stdout(text: string): void;
+    stderr(text: string): void;
+    cwd: string;
+    env: Record<string, string | undefined>;
+    stdinIsTTY: boolean;
+    caller?: Caller;
+};
+export type Command = (argv: string[], io: Io) => Promise<number>;

package/dist/io.js

@@ -0,0 +1 @@
+export {};

package/dist/launch/deliver.d.ts

@@ -0,0 +1,10 @@
+export interface Delivery {
+    screen(): string | undefined;
+    status(): string | null;
+    type(text: string): boolean;
+    enter(): boolean;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/** A first message is accepted only after working is observed with the composer empty again. */
+export declare function deliverRules(cli: string, text: string, seconds: number, io: Delivery): Promise<boolean>;

package/dist/launch/deliver.js

@@ -0,0 +1,39 @@
+import { classifyComposer, readScreen } from "../watch/screen.js";
+/** A first message is accepted only after working is observed with the composer empty again. */
+export async function deliverRules(cli, text, seconds, io) {
+    const free = () => ['idle', 'done'].includes(io.status() ?? '');
+    if (!free() || readScreen(cli, io.screen()).kind !== 'idle' || !io.type(text))
+        return false;
+    const deadline = io.now() + seconds * 1000;
+    // Terminal rendering can lag send-text. Never send Enter until the pasted text is visible.
+    for (;;) {
+        const kind = readScreen(cli, io.screen()).kind;
+        if (!free())
+            return false;
+        if (kind === 'unsent')
+            break;
+        if (kind !== 'idle' || io.now() >= deadline)
+            return false;
+        const before = io.now();
+        await io.sleep(100);
+        if (io.now() <= before)
+            return false;
+    }
+    // Re-read immediately before Enter; a dialog that appeared after the paste gets no key.
+    if (!free() || readScreen(cli, io.screen()).kind !== 'unsent' || !io.enter())
+        return false;
+    for (;;) {
+        const status = io.status();
+        const screen = io.screen();
+        const composer = screen === undefined ? { kind: 'unknown' } : classifyComposer(cli, screen.split('\n'));
+        if (status === 'working' && composer.kind === 'idle')
+            return true;
+        const kind = readScreen(cli, io.screen()).kind;
+        if (kind === 'trust' || kind === 'permission' || kind === 'question' || io.now() >= deadline)
+            return false;
+        const before = io.now();
+        await io.sleep(100);
+        if (io.now() <= before)
+            return false;
+    }
+}

package/dist/launch/execute.d.ts

@@ -0,0 +1,46 @@
+import type { Step } from './plan.ts';
+export type ScreenKind = 'idle' | 'working' | 'permission' | 'trust' | 'question' | 'unsent' | 'unknown';
+/** What a live `up` or `down` can do, apart from deciding it. Tests stand in for all of it. */
+export type Host = {
+    startServer(session: string): boolean;
+    sessionUp(session: string): boolean | null;
+    /** Makes a folder and the parents it needs. Present on `up` and `add`, whose plans carry a lobby. */
+    makeDir?(path: string): boolean;
+    createWorkspace(session: string, cwd: string, label: string): {
+        pane: string;
+        workspace: string;
+    } | null;
+    paneRun(session: string, pane: string, command: string): boolean;
+    typeLine(session: string, pane: string, text: string): boolean;
+    deliverRules?(session: string, pane: string, cli: string, text: string, seconds: number): Promise<boolean>;
+    renameAgent(session: string, pane: string, name: string): boolean;
+    closeWorkspace(session: string, workspace: string): boolean;
+    stopSession(session: string): boolean;
+    kill(pid: number): boolean;
+    /** Pane ids herdr lists an agent in, or null when the list can't be read. */
+    agentPanes(session: string): string[] | null;
+    classify(session: string, pane: string, cli: string): ScreenKind;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    /** Null when this seat may launch. A string is the reason it may not. */
+    allow(seat: string): string | null;
+    record(seat: string, patch: {
+        stage: 'launched' | 'named' | 'ready';
+        pane?: string;
+        workspace?: string;
+        rules?: 'option' | 'message';
+    }): void;
+    /** The seat is really running, so the next seat's ceiling check counts it. */
+    running(seat: string): void;
+    drop(seat: string): void;
+    say(line: string): void;
+    log(who: string, what: string): void;
+};
+export type Report = {
+    serverFailed: boolean;
+    watchFailed: boolean;
+    /** A seat or the watch was left behind, so the session must not be stopped. */
+    held: boolean;
+};
+/** Runs a plan. Steps carry the operation beside the command the dry run prints. */
+export declare function executePlan(steps: readonly Step[], session: string, host: Host): Promise<Report>;