team 0.0.1 → 0.1.1

package/dist/check/message.js

@@ -0,0 +1,101 @@
+import { renderings, shape } from "./signature.js";
+/** The text's lines, trailing spaces trimmed. */
+export function splitLines(text) {
+    return text.split(/\r?\n/).map((line) => line.trimEnd());
+}
+/** Every line that matches a forbidden pattern. */
+export function findForbidden(lines, patterns) {
+    const findings = [];
+    lines.forEach((text, index) => {
+        for (const pattern of patterns) {
+            if (pattern.regex.test(text)) {
+                findings.push({
+                    kind: 'forbidden',
+                    message: `forbidden pattern ${pattern.source}`,
+                    line: index + 1,
+                    text,
+                });
+            }
+        }
+    });
+    return findings;
+}
+/** The indexes of the last run of non-empty lines: [start, end). */
+function lastParagraph(lines) {
+    let end = lines.length;
+    while (end > 0 && lines[end - 1] === '')
+        end--;
+    let start = end;
+    while (start > 0 && lines[start - 1] !== '')
+        start--;
+    return [start, end];
+}
+const TRAILER_LINE = /^[A-Za-z0-9-]+\s*:\s*\S/;
+const WHERE = {
+    'last-line': { commit: 'the last line', pr: 'the last line' },
+    trailer: { commit: 'the final trailer block', pr: 'the last paragraph' },
+    anywhere: { commit: 'a line of its own', pr: 'a line of its own' },
+};
+/** Empty when the text carries a signature of the team's at the position the rule says. */
+export function checkSignature(input) {
+    const { lines, rule, ledger, trailers } = input;
+    const accepted = renderings(rule.template, ledger);
+    const [start, end] = lastParagraph(lines);
+    const where = WHERE[rule.position][trailers ? 'commit' : 'pr'];
+    let candidates;
+    if (rule.position === 'last-line')
+        candidates = lines.slice(Math.max(end - 1, 0), end);
+    else if (rule.position === 'anywhere')
+        candidates = lines;
+    else
+        candidates = trailers ? trailers.map((line) => line.trimEnd()) : lines.slice(start, end);
+    if (candidates.some((line) => accepted.has(line)))
+        return [];
+    const signed = lines.findIndex((line) => accepted.has(line));
+    if (signed !== -1) {
+        const text = lines[signed];
+        const inLastParagraph = signed >= start && signed < end;
+        if (trailers && rule.position === 'trailer' && inLastParagraph) {
+            const prose = lines.slice(start, end).filter((line) => !TRAILER_LINE.test(line));
+            if (prose.length > 0) {
+                return [
+                    {
+                        kind: 'signature-in-prose',
+                        message: `the signature shares its paragraph with prose (${prose.map((line) => JSON.stringify(line)).join(', ')}), ` +
+                            'so git reads no trailer block: put it in a paragraph of its own, with trailers only',
+                        line: signed + 1,
+                        text,
+                    },
+                ];
+            }
+        }
+        return [
+            {
+                kind: 'signature-misplaced',
+                message: `the signature is not in ${where}`,
+                line: signed + 1,
+                text,
+            },
+        ];
+    }
+    const form = shape(rule.template);
+    const unknown = [];
+    lines.forEach((text, index) => {
+        if (form.test(text)) {
+            unknown.push({
+                kind: 'signature-unknown',
+                message: 'a signature no seat of this team has had (the model, the version and the role must all match one seat)',
+                line: index + 1,
+                text,
+            });
+        }
+    });
+    if (unknown.length > 0)
+        return unknown;
+    return [
+        {
+            kind: 'signature-missing',
+            message: `no signature: expected ${JSON.stringify(rule.template)} in ${where}`,
+        },
+    ];
+}

package/dist/check/run.d.ts

@@ -0,0 +1,31 @@
+import { type CheckConfig } from './config.ts';
+import { type Finding } from './message.ts';
+export interface CheckOptions {
+    /** A folder of the repository to read. */
+    cwd: string;
+    /** A range when it holds `..`, else one commit. */
+    ref: string;
+    /** Overrides the file's `identity.since` for this run. */
+    since?: string;
+    /** A pull request's body, to check as well. */
+    pullRequestBody?: string;
+}
+export interface CommitReport {
+    hash: string;
+    subject: string;
+    /** Why the commit needs no signature; its forbidden patterns are still checked. */
+    exempt?: 'merge' | 'human';
+    findings: Finding[];
+}
+export interface CheckReport {
+    commits: CommitReport[];
+    skipped: number;
+    since?: string;
+    /** Present when a PR body was checked. */
+    pullRequest?: Finding[];
+    ok: boolean;
+}
+/** Checks the commits of `ref`, and a PR body when one is given. Read only. */
+export declare function runCheck(config: CheckConfig, options: CheckOptions): CheckReport;
+/** The report as `check` prints it: each offending commit and line, then a summary. */
+export declare function formatReport(report: CheckReport): string;

package/dist/check/run.js

@@ -0,0 +1,77 @@
+import { forbiddenPatterns } from "./config.js";
+import { selectCommits } from "./git.js";
+import { checkSignature, findForbidden, splitLines } from "./message.js";
+function exemption(commit, config, humans) {
+    if (config.commits.exemptMerge && commit.parents.length > 1)
+        return 'merge';
+    if (humans.has(commit.authorEmail.toLowerCase()))
+        return 'human';
+    return undefined;
+}
+/** Checks the commits of `ref`, and a PR body when one is given. Read only. */
+export function runCheck(config, options) {
+    const patterns = forbiddenPatterns(config);
+    const humans = new Set(config.humans.map((email) => email.toLowerCase()));
+    const selection = selectCommits(options.cwd, options.ref, options.since ?? config.since);
+    const commits = selection.commits.map((commit) => {
+        const lines = splitLines(commit.message);
+        const exempt = exemption(commit, config, humans);
+        const findings = findForbidden(lines, patterns);
+        if (!exempt) {
+            findings.push(...checkSignature({ lines, rule: config.commits, ledger: config.ledger, trailers: commit.trailers }));
+        }
+        return { hash: commit.hash, subject: commit.subject, exempt, findings };
+    });
+    let pullRequest;
+    if (options.pullRequestBody !== undefined) {
+        const lines = splitLines(options.pullRequestBody);
+        pullRequest = [
+            ...findForbidden(lines, patterns),
+            ...checkSignature({ lines, rule: config.pullRequests, ledger: config.ledger }),
+        ];
+    }
+    const ok = commits.every((commit) => commit.findings.length === 0) && (pullRequest?.length ?? 0) === 0;
+    return { commits, skipped: selection.skipped, since: selection.since, pullRequest, ok };
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function findingLines(finding) {
+    const where = finding.line === undefined ? '' : `line ${finding.line}: `;
+    const lines = [`  ${where}${finding.message}`];
+    if (finding.text !== undefined)
+        lines.push(`    ${finding.text}`);
+    return lines;
+}
+/** The report as `check` prints it: each offending commit and line, then a summary. */
+export function formatReport(report) {
+    const out = [];
+    for (const commit of report.commits) {
+        if (commit.findings.length === 0)
+            continue;
+        out.push(`${commit.hash.slice(0, 10)} ${commit.subject}`);
+        for (const finding of commit.findings)
+            out.push(...findingLines(finding));
+    }
+    if (report.pullRequest && report.pullRequest.length > 0) {
+        out.push('pull request body');
+        for (const finding of report.pullRequest)
+            out.push(...findingLines(finding));
+    }
+    const failed = report.commits.filter((commit) => commit.findings.length > 0).length;
+    const exempt = report.commits.filter((commit) => commit.exempt).length;
+    const parts = [`${plural(report.commits.length, 'commit')} checked`];
+    if (exempt > 0)
+        parts.push(`${exempt} by a human or a merge`);
+    if (report.skipped > 0)
+        parts.push(`${report.skipped} skipped (since ${report.since?.slice(0, 10)})`);
+    if (report.pullRequest)
+        parts.push('1 pull request body checked');
+    const problems = [];
+    if (failed > 0)
+        problems.push(`${plural(failed, 'commit')} refused`);
+    if (report.pullRequest && report.pullRequest.length > 0)
+        problems.push('the pull request body refused');
+    out.push(`team check: ${parts.join(', ')}: ${report.ok ? 'ok' : problems.join(', ')}`);
+    return `${out.join('\n')}\n`;
+}

package/dist/check/signature.d.ts

@@ -0,0 +1,10 @@
+import type { SeatIdentity } from './config.ts';
+/** The signature line a seat writes, from the project's template. */
+export declare function render(template: string, seat: SeatIdentity): string;
+/** Every accepted signature line. */
+export declare function renderings(template: string, ledger: readonly SeatIdentity[]): Set<string>;
+/**
+ * Matches a line that has the template's fixed words around any values: a
+ * signature by its form, whether or not a seat ever had those values.
+ */
+export declare function shape(template: string): RegExp;

package/dist/check/signature.js

@@ -0,0 +1,22 @@
+import { renderSignature } from "../file/signature.js";
+const PLACEHOLDER = /\{(display|role|model|version)\}/g;
+/** The signature line a seat writes, from the project's template. */
+export function render(template, seat) {
+    return renderSignature(template, seat).trimEnd();
+}
+/** Every accepted signature line. */
+export function renderings(template, ledger) {
+    return new Set(ledger.map((seat) => render(template, seat)));
+}
+/**
+ * Matches a line that has the template's fixed words around any values: a
+ * signature by its form, whether or not a seat ever had those values.
+ */
+export function shape(template) {
+    const literals = template
+        .trimEnd()
+        .split(PLACEHOLDER)
+        .filter((_, index) => index % 2 === 0);
+    const escaped = literals.map((literal) => literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    return new RegExp(`^${escaped.join('(.+?)')}$`);
+}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import type { Command, Io } from './io.ts';
+export declare const commands: Record<string, () => Promise<{
+    default: Command;
+    USAGE: string;
+}>>;
+export declare function version(): string;
+export declare function main(argv: string[], io: Io): Promise<number>;
+export declare function processIo(): Io;

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// Each command is loaded only when it is called. A slice adds its line here. The table is exported
+// so a test can walk it: every command, `--help`, `-h` and a usage line.
+export const commands = {
+    approve: () => import("./commands/approve.js"),
+    check: () => import("./commands/check.js"),
+    doctor: () => import("./commands/doctor.js"),
+    down: () => import("./commands/down.js"),
+    init: () => import("./commands/init.js"),
+    status: () => import("./commands/status.js"),
+    up: () => import("./commands/up.js"),
+    watch: () => import("./commands/watch.js"),
+    worktree: () => import("./commands/worktree.js"),
+    add: () => import("./commands/add.js"),
+    remove: () => import("./commands/remove.js"),
+};
+const USAGE = `team: set up, change and watch a project's team of AI agents
+
+Usage: team <command> [options]
+
+Commands:
+{commands}
+
+Options:
+  --version   print the version
+  --help      print this text
+
+The team is declared in <project>/.agents/team.yaml.
+`;
+export function version() {
+    const text = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    return JSON.parse(text).version;
+}
+export async function main(argv, io) {
+    const [name, ...rest] = argv;
+    const names = Object.keys(commands);
+    const usage = USAGE.replace('{commands}', names.length ? names.map((n) => `  ${n}`).join('\n') : '  (none in this build)');
+    if (!name || name === '--help' || name === '-h' || name === 'help') {
+        io.stdout(usage);
+        return name ? 0 : 2;
+    }
+    if (name === '--version' || name === '-V') {
+        io.stdout(`${version()}\n`);
+        return 0;
+    }
+    const load = commands[name];
+    if (!load) {
+        io.stderr(`team: unknown command "${name}"\n\n${usage}`);
+        return 2;
+    }
+    const command = await load();
+    // The one path for every command's `--help`/`-h`: it prints the command's usage and stops,
+    // before any option parsing, file reading, caller check or herdr call in the command itself.
+    if (rest.includes('--help') || rest.includes('-h')) {
+        io.stdout(command.USAGE);
+        return 0;
+    }
+    return command.default(rest, io);
+}
+export function processIo() {
+    return {
+        stdout: (text) => void process.stdout.write(text),
+        stderr: (text) => void process.stderr.write(text),
+        cwd: process.cwd(),
+        env: process.env,
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+    };
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main(process.argv.slice(2), processIo()).then((code) => { process.exitCode = code; }, (error) => {
+        process.stderr.write(`team: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/clis.d.ts

@@ -0,0 +1,7 @@
+export type Profile = {
+    cli: string;
+    processes: string[];
+};
+export declare const PROFILES: Profile[];
+export declare const CLIS: string[];
+export declare const CLI_PROCESSES: string[];

package/dist/clis.js

@@ -0,0 +1,9 @@
+export const PROFILES = [
+    { cli: 'claude-code', processes: ['claude'] },
+    { cli: 'codex', processes: ['codex'] },
+    { cli: 'cursor', processes: ['cursor-agent'] },
+    { cli: 'grok', processes: ['grok'] },
+    { cli: 'antigravity', processes: ['agy'] },
+];
+export const CLIS = PROFILES.map((profile) => profile.cli);
+export const CLI_PROCESSES = PROFILES.flatMap((profile) => profile.processes);

package/dist/commands/add.d.ts

@@ -0,0 +1,23 @@
+import { type DoctorSources } from '../commands/doctor.ts';
+import { type Launch } from '../commands/up.ts';
+import { type HerdrAgent } from '../herdr.ts';
+import type { Command, Io } from '../io.ts';
+import { type Machine } from '../watch/machine.ts';
+export type AddSources = {
+    home: string;
+    sessionState(session: string): 'absent' | 'running' | 'stopped' | null;
+    agents(session: string): HerdrAgent[] | null;
+    workspaces(session: string): {
+        id: string;
+        label: string;
+    }[] | null;
+    doctor: DoctorSources;
+    machine?: (root: string) => Machine;
+    now(): Date;
+    launch: Launch;
+};
+export declare const realSources: AddSources;
+export declare const USAGE = "Usage: team add <name> [--dry-run] [--session <name>] [--file <path>]\n       team add --temporary --like <seat> --until <result:path|merged:branch> [--worktree <task>] [--dry-run] [--session <name>] [--file <path>]\n";
+export declare const add: Command;
+export default add;
+export declare function runAdd(argv: string[], io: Io, sources?: AddSources): Promise<number>;