@openfleet-tools/cli 0.0.0 → 0.1.0

package/core/templates/agents/openfleet-tester.agent.md

@@ -0,0 +1,42 @@
+---
+name: openfleet-tester
+description: OpenFleet per-repo tester. Builds and tests one worktree and verifies that contract tests exist and pass. Does not modify source.
+tools: ["read", "search", "execute"]
+---
+
+You are an **OpenFleet tester** for exactly one child. The `# OpenFleet assignment` block at the top of your prompt names the child, the worktree, the spec, the contracts and the plan.
+
+You are **read-only on source**. Do not edit, create or delete files in the worktree. You may only create throwaway files under the system temp directory. If something must change, report it as a finding for the implementer.
+
+## Steps
+
+Every shell command must start with `cd <worktree> &&`.
+
+1. Run the child's **build** command from `spec.md`.
+2. Run the child's **test** command from `spec.md`.
+3. **Contract tests:** for each contract that this child produces or consumes (see the spec and plan), confirm that a contract test exists, that it uses the shared fixture from `contracts/`, and that it ran and passed in step 2. A missing contract test is a failure.
+4. Check each acceptance criterion for this child in `spec.md`. Use code reading or targeted commands.
+5. Record each command you run:
+
+   ```sh
+   npx openfleet event <project> --actor "<child id>/tester" --type test.run --target "<child id>" \
+     --payload '{"command": "<cmd>", "exitCode": <n>, "passed": <true|false>, "summary": "<one line>"}'
+   ```
+
+   Run this from the workspace root, not from the worktree.
+
+## Findings
+
+When something fails, write findings that the implementer can act on without re-running everything: the failing command, the relevant output excerpt (trimmed), the file and line if known, and the likely cause. Do not paste whole logs.
+
+## Report
+
+End with:
+
+````
+```openfleet-report
+{"status": "done" | "failed", "child": "<child id>", "summary": "<pass/fail summary>", "findings": ["<finding>", "…"]}
+```
+````
+
+Use `status: "done"` only when build, tests and all contract tests pass, and every acceptance criterion is met.

package/dist/attribution.d.ts

@@ -0,0 +1,21 @@
+import { type ChildState, type ProjectState, type Role } from "./state.js";
+import { type ProjectPaths, type Workspace } from "./workspace.js";
+export declare function roleOf(child: ChildState): Role | undefined;
+/** Copilot namespaces plugin agents as `<plugin>:<agent>`. */
+export declare const PLUGIN_NAME = "openfleet";
+export declare function bareAgentName(agentName: string | undefined): string | undefined;
+export declare function qualifiedAgentName(agent: string): string;
+export declare function roleFromAgentName(agentName: string | undefined): Role | "coordinator" | undefined;
+export declare function actorFor(childId: string, role: string | undefined): string;
+export interface Located {
+    project: ProjectPaths;
+    state: ProjectState;
+    childId: string;
+    child: ChildState;
+    /** Path relative to the child's worktree. */
+    rel: string;
+}
+/** Candidate projects: the explicit one if given, otherwise every project in the workspace. */
+export declare function candidateProjects(ws: Workspace, project?: string): ProjectPaths[];
+/** Attribute an absolute file path to project → child worktree (longest match wins). */
+export declare function locatePath(ws: Workspace, absPath: string, project?: string): Located | undefined;

package/dist/attribution.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { isInside, realish } from "./fsutil.js";
+import { readState } from "./state.js";
+import { listProjectNames, projectPaths } from "./workspace.js";
+const PHASE_ROLE = {
+    planning: "planner",
+    "plan-review": "planner",
+    implementing: "implementer",
+    testing: "tester",
+};
+export function roleOf(child) {
+    return child.role ?? PHASE_ROLE[child.phase];
+}
+/** Copilot namespaces plugin agents as `<plugin>:<agent>`. */
+export const PLUGIN_NAME = "openfleet";
+export function bareAgentName(agentName) {
+    return agentName?.startsWith(`${PLUGIN_NAME}:`) ? agentName.slice(PLUGIN_NAME.length + 1) : agentName;
+}
+export function qualifiedAgentName(agent) {
+    return agent.includes(":") ? agent : `${PLUGIN_NAME}:${agent}`;
+}
+export function roleFromAgentName(agentName) {
+    switch (bareAgentName(agentName)) {
+        case "openfleet-planner":
+            return "planner";
+        case "openfleet-implementer":
+            return "implementer";
+        case "openfleet-tester":
+            return "tester";
+        case "openfleet-coordinator":
+            return "coordinator";
+        default:
+            return undefined;
+    }
+}
+export function actorFor(childId, role) {
+    return `${childId}/${role ?? "unknown"}`;
+}
+function safeState(p) {
+    try {
+        return readState(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Candidate projects: the explicit one if given, otherwise every project in the workspace. */
+export function candidateProjects(ws, project) {
+    const names = project ? [project] : listProjectNames(ws);
+    return names.map((n) => projectPaths(ws, n));
+}
+/** Attribute an absolute file path to project → child worktree (longest match wins). */
+export function locatePath(ws, absPath, project) {
+    let best;
+    let bestLen = -1;
+    const target = realish(absPath);
+    for (const p of candidateProjects(ws, project)) {
+        const state = safeState(p);
+        if (!state)
+            continue;
+        for (const [childId, child] of Object.entries(state.children)) {
+            if (!child.worktree)
+                continue;
+            const wt = realish(child.worktree);
+            if (!isInside(wt, target) || wt.length <= bestLen)
+                continue;
+            bestLen = wt.length;
+            best = { project: p, state, childId, child, rel: path.relative(wt, target) };
+        }
+    }
+    return best;
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+main();

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+export declare const HELP = "openfleet \u2014 coordinate one change across many repos with GitHub Copilot CLI\n\nUsage: npx openfleet <command> [options] [-- <copilot args>]\n\nWorkspace\n  init                         Create openfleet/ in the current directory and install core\n  update                       Replace openfleet/core with this CLI version and re-sync extensions\n\nProjects\n  new <name> [\"<request>\"] [--ask]\n                               Create a project and launch the coordinator\n  resume <name> [--fresh] [--ask]\n                               Continue a project (--fresh starts a new Copilot session)\n  status [name] [--json]       Show a project's children, phases and open questions\n  list                         List projects\n  clean <name> [--branches] [--force]\n                               Remove the project's worktrees (and branches)\n\nExtensions\n  add <git-url[#ref]|path>     Install or update an extension\n  remove <name>                Uninstall an extension\n  extensions                   List installed extensions\n\nAgent helpers (used by OpenFleet agents)\n  state <project> [--patch <json>] [--actor <a>]\n  event <project> --type <t> [--actor <a>] [--target <child>] [--payload <json>] [--patch-file <f>]\n  worktree <project> <child> --repo <key> --branch <b> [--package <p>] [--base <ref>]\n\n  help, version\nSessions auto-approve tool use (`--allow-all-tools`). File access stays limited to the workspace,\nits worktrees and known repos, and URL access still prompts. Pass `--ask` to `new`, `resume` or an\nextension command to be prompted for every tool instead.\nArguments after `--` are passed to copilot unchanged (e.g. `-- --yolo`).\n";
+export declare function run(argv: string[]): number;
+export declare function main(argv?: string[]): void;

package/dist/cli.js

@@ -0,0 +1,134 @@
+import { parseArgs } from "node:util";
+import { packageVersion } from "./core.js";
+import { cmdAdd, cmdExtensions, cmdRemove, runExtensionCommand } from "./commands/extensions.js";
+import { cmdEvent, cmdState, cmdWorktree } from "./commands/internal.js";
+import { out } from "./commands/output.js";
+import { cmdClean, cmdList, cmdNew, cmdResume, cmdStatus } from "./commands/project.js";
+import { cmdInit, cmdUpdate } from "./commands/workspace.js";
+import { UserError } from "./workspace.js";
+export const HELP = `openfleet — coordinate one change across many repos with GitHub Copilot CLI
+
+Usage: npx openfleet <command> [options] [-- <copilot args>]
+
+Workspace
+  init                         Create openfleet/ in the current directory and install core
+  update                       Replace openfleet/core with this CLI version and re-sync extensions
+
+Projects
+  new <name> ["<request>"] [--ask]
+                               Create a project and launch the coordinator
+  resume <name> [--fresh] [--ask]
+                               Continue a project (--fresh starts a new Copilot session)
+  status [name] [--json]       Show a project's children, phases and open questions
+  list                         List projects
+  clean <name> [--branches] [--force]
+                               Remove the project's worktrees (and branches)
+
+Extensions
+  add <git-url[#ref]|path>     Install or update an extension
+  remove <name>                Uninstall an extension
+  extensions                   List installed extensions
+
+Agent helpers (used by OpenFleet agents)
+  state <project> [--patch <json>] [--actor <a>]
+  event <project> --type <t> [--actor <a>] [--target <child>] [--payload <json>] [--patch-file <f>]
+  worktree <project> <child> --repo <key> --branch <b> [--package <p>] [--base <ref>]
+
+  help, version
+Sessions auto-approve tool use (\`--allow-all-tools\`). File access stays limited to the workspace,
+its worktrees and known repos, and URL access still prompts. Pass \`--ask\` to \`new\`, \`resume\` or an
+extension command to be prompted for every tool instead.
+Arguments after \`--\` are passed to copilot unchanged (e.g. \`-- --yolo\`).
+`;
+function splitPassthrough(argv) {
+    const i = argv.indexOf("--");
+    return i < 0 ? [argv, []] : [argv.slice(0, i), argv.slice(i + 1)];
+}
+function parse(args, options) {
+    return parseArgs({ args, options, allowPositionals: true, strict: true });
+}
+export function run(argv) {
+    const [args, passthrough] = splitPassthrough(argv);
+    const [command, ...rest] = args;
+    switch (command) {
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            out(HELP);
+            return 0;
+        case "version":
+        case "--version":
+        case "-v":
+            out(packageVersion());
+            return 0;
+        case "init":
+            return cmdInit();
+        case "update":
+            return cmdUpdate();
+        case "new": {
+            const { values, positionals } = parse(rest, { ask: { type: "boolean" } });
+            return cmdNew(positionals, passthrough, { ask: values.ask });
+        }
+        case "resume": {
+            const { values, positionals } = parse(rest, { fresh: { type: "boolean" }, ask: { type: "boolean" } });
+            return cmdResume(positionals, passthrough, { fresh: values.fresh, ask: values.ask });
+        }
+        case "status": {
+            const { values, positionals } = parse(rest, { json: { type: "boolean" } });
+            return cmdStatus(positionals, { json: values.json });
+        }
+        case "list":
+            return cmdList();
+        case "clean": {
+            const { values, positionals } = parse(rest, { branches: { type: "boolean" }, force: { type: "boolean" } });
+            return cmdClean(positionals, values);
+        }
+        case "add":
+            return cmdAdd(parse(rest, {}).positionals);
+        case "remove":
+            return cmdRemove(parse(rest, {}).positionals);
+        case "extensions":
+            return cmdExtensions();
+        case "state": {
+            const { values, positionals } = parse(rest, { patch: { type: "string" }, actor: { type: "string" } });
+            return cmdState(positionals, values);
+        }
+        case "event": {
+            const { values, positionals } = parse(rest, {
+                type: { type: "string" },
+                actor: { type: "string" },
+                target: { type: "string" },
+                payload: { type: "string" },
+                "patch-file": { type: "string" },
+            });
+            return cmdEvent(positionals, values);
+        }
+        case "worktree": {
+            const { values, positionals } = parse(rest, {
+                repo: { type: "string" },
+                branch: { type: "string" },
+                package: { type: "string" },
+                base: { type: "string" },
+            });
+            return cmdWorktree(positionals, values);
+        }
+        default: {
+            const ask = rest.includes("--ask");
+            const code = runExtensionCommand(command, rest.filter((a) => a !== "--ask"), passthrough, { ask });
+            if (code === undefined)
+                throw new UserError(`Unknown command "${command}". Run \`npx openfleet help\`.`);
+            return code;
+        }
+    }
+}
+export function main(argv = process.argv.slice(2)) {
+    try {
+        process.exitCode = run(argv);
+    }
+    catch (err) {
+        const isUser = err instanceof UserError || err.code?.startsWith("ERR_PARSE_ARGS");
+        process.stderr.write(`openfleet: ${isUser ? err.message : err.stack ?? String(err)}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/extensions.d.ts

@@ -0,0 +1,7 @@
+export declare function cmdAdd(args: string[]): number;
+export declare function cmdRemove(args: string[]): number;
+export declare function cmdExtensions(): number;
+/** Try to run an extension-declared command. Returns undefined when no extension declares it. */
+export declare function runExtensionCommand(command: string, args: string[], passthrough: string[], opts?: {
+    ask?: boolean;
+}): number | undefined;

package/dist/commands/extensions.js

@@ -0,0 +1,60 @@
+import { syncExtensions, installedCoreVersion, packageVersion } from "../core.js";
+import { readCoreIndex } from "../coreindex.js";
+import { addExtension, describePermissions, readLock, removeExtension } from "../extensions.js";
+import { launch } from "../launcher.js";
+import { requireWorkspace, UserError } from "../workspace.js";
+import { out, warn } from "./output.js";
+export function cmdAdd(args) {
+    const ws = requireWorkspace();
+    const source = args[0];
+    if (!source)
+        throw new UserError("Usage: openfleet add <git-url[#ref]|path>");
+    const coreVersion = installedCoreVersion(ws) ?? packageVersion();
+    const { entry, manifest, replaced } = addExtension(ws, source, coreVersion);
+    syncExtensions(ws, warn);
+    out(`${replaced ? "Updated" : "Added"} extension ${manifest.name}@${manifest.version} (${entry.sha === "local" ? "local" : entry.sha.slice(0, 12)}).`);
+    out(manifest.mode === "phase"
+        ? `Mode: phase, slot ${manifest.slot} (runs as agent openfleet:openfleet-ext-${manifest.name}).`
+        : `Mode: augment, appended to the ${manifest.role} agent's instructions.`);
+    out("Declared permissions:");
+    out(describePermissions(manifest));
+    const cmds = Object.keys(manifest.commands ?? {});
+    if (cmds.length)
+        out(`Commands: ${cmds.map((c) => `npx openfleet ${c}`).join(", ")}`);
+    return 0;
+}
+export function cmdRemove(args) {
+    const ws = requireWorkspace();
+    const name = args[0];
+    if (!name)
+        throw new UserError("Usage: openfleet remove <extension>");
+    removeExtension(ws, name);
+    syncExtensions(ws, warn);
+    out(`Removed extension ${name}.`);
+    return 0;
+}
+export function cmdExtensions() {
+    const ws = requireWorkspace();
+    const lock = readLock(ws);
+    if (!lock.extensions.length) {
+        out("No extensions installed. Add one with `npx openfleet add <git-url|path>`.");
+        return 0;
+    }
+    for (const e of lock.extensions) {
+        out(`${e.enabled ? "✓" : "✗"} ${e.name}@${e.version}  ${e.source}  ${e.sha === "local" ? "local" : e.sha.slice(0, 12)}${e.disabledReason ? `  (disabled: ${e.disabledReason})` : ""}`);
+    }
+    return 0;
+}
+/** Try to run an extension-declared command. Returns undefined when no extension declares it. */
+export function runExtensionCommand(command, args, passthrough, opts = {}) {
+    const ws = requireWorkspace();
+    const cmd = readCoreIndex(ws)?.commands[command];
+    if (!cmd)
+        return undefined;
+    const prompt = [
+        `Run the OpenFleet extension command \`openfleet ${command}\` from extension \`${cmd.extension}\`.`,
+        `Use the skill \`${cmd.skill}\` and follow its instructions exactly.`,
+        args.length ? `Arguments: ${args.join(" ")}` : "No arguments were given.",
+    ].join("\n");
+    return launch({ ws, agent: cmd.agent, prompt, name: `openfleet ${command}`, passthrough, ask: opts.ask });
+}

package/dist/commands/internal.d.ts

@@ -0,0 +1,19 @@
+export interface EventFlags {
+    type?: string;
+    actor?: string;
+    target?: string;
+    payload?: string;
+    "patch-file"?: string;
+}
+export declare function cmdEvent(args: string[], flags: EventFlags): number;
+export declare function cmdState(args: string[], flags: {
+    patch?: string;
+    actor?: string;
+}): number;
+export interface WorktreeFlags {
+    repo?: string;
+    branch?: string;
+    package?: string;
+    base?: string;
+}
+export declare function cmdWorktree(args: string[], flags: WorktreeFlags): number;

package/dist/commands/internal.js

@@ -0,0 +1,117 @@
+// Helper commands used by OpenFleet agents (see the openfleet-records skill).
+import fs from "node:fs";
+import path from "node:path";
+import { appendEvent } from "../events.js";
+import { addWorktree, git, headSha, isGitRepo } from "../git.js";
+import { readRepos } from "../repos.js";
+import { patchState, readState, updateState } from "../state.js";
+import { projectPaths, requireWorkspace, UserError, validateProjectName } from "../workspace.js";
+import { out } from "./output.js";
+function parseJson(raw, what) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new UserError(`Invalid JSON for ${what}: ${err.message}`);
+    }
+}
+export function cmdEvent(args, flags) {
+    const ws = requireWorkspace();
+    const name = validateProjectName(args[0]);
+    const p = projectPaths(ws, name);
+    readState(p);
+    if (!flags.type)
+        throw new UserError("--type is required");
+    const payload = parseJson(flags.payload, "--payload") ?? {};
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        throw new UserError("--payload must be a JSON object");
+    }
+    const patch = flags["patch-file"] ? fs.readFileSync(flags["patch-file"], "utf8") : undefined;
+    const ev = appendEvent(p, {
+        actor: flags.actor ?? "coordinator",
+        type: flags.type,
+        target: flags.target ?? null,
+        payload: payload,
+        ...(patch !== undefined ? { patch } : {}),
+    });
+    out(JSON.stringify({ seq: ev.seq }));
+    return 0;
+}
+export function cmdState(args, flags) {
+    const ws = requireWorkspace();
+    const name = validateProjectName(args[0]);
+    const p = projectPaths(ws, name);
+    const state = flags.patch !== undefined ? patchState(p, parseJson(flags.patch, "--patch"), flags.actor) : readState(p);
+    out(JSON.stringify(state, null, 2));
+    return 0;
+}
+/** Resolve a repos.json entry to a local checkout, cloning `url` into `openfleet/repos/<key>` if needed. */
+function resolveRepoPath(wsRoot, wsDir, key, entry) {
+    if (entry.path) {
+        const abs = path.resolve(wsRoot, entry.path);
+        if (!isGitRepo(abs))
+            throw new UserError(`repos.json "${key}".path is not a git repository: ${abs}`);
+        return abs;
+    }
+    if (!entry.url)
+        throw new UserError(`repos.json "${key}" needs a "path" or "url".`);
+    const dest = path.join(wsDir, "repos", key);
+    if (!isGitRepo(dest)) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        git(wsRoot, ["clone", "--quiet", entry.url, dest]);
+    }
+    return dest;
+}
+export function cmdWorktree(args, flags) {
+    const ws = requireWorkspace();
+    const name = validateProjectName(args[0]);
+    const childId = args[1];
+    if (!childId || !/^[A-Za-z0-9._-]+(:[A-Za-z0-9._@/-]+)?$/.test(childId)) {
+        throw new UserError("Usage: openfleet worktree <project> <child id> --repo <key> --branch <branch>");
+    }
+    const p = projectPaths(ws, name);
+    const state = readState(p);
+    const repoKey = flags.repo ?? state.children[childId]?.repo ?? childId.split(":")[0];
+    const entry = readRepos(ws).repos[repoKey];
+    if (!entry)
+        throw new UserError(`Repo "${repoKey}" is not in openfleet/repos.json.`);
+    const branch = flags.branch ?? state.children[childId]?.branch;
+    if (!branch)
+        throw new UserError("--branch is required");
+    const repoPath = resolveRepoPath(ws.root, ws.dir, repoKey, entry);
+    const worktree = path.join(p.worktrees, childId.replace(/[:/]/g, "__"));
+    const base = flags.base ?? entry.defaultBranch;
+    const existed = fs.existsSync(worktree);
+    if (!existed)
+        addWorktree(repoPath, worktree, branch, base);
+    const baseSha = state.children[childId]?.baseSha ?? headSha(worktree);
+    const next = updateState(p, (s) => {
+        const prev = s.children[childId];
+        s.children[childId] = {
+            phase: "pending",
+            retries: 0,
+            dependsOn: [],
+            agentIds: {},
+            ...prev,
+            repo: repoKey,
+            repoPath,
+            worktree,
+            branch,
+            ...(base ? { baseBranch: base } : {}),
+            ...(baseSha ? { baseSha } : {}),
+            ...(flags.package ?? prev?.package ? { package: flags.package ?? prev?.package } : {}),
+        };
+    });
+    if (!existed) {
+        appendEvent(p, {
+            actor: "coordinator",
+            type: "worktree.created",
+            target: childId,
+            payload: { repo: repoKey, repoPath, worktree, branch, base: base ?? null, baseSha: baseSha ?? null },
+        });
+    }
+    out(JSON.stringify(next.children[childId], null, 2));
+    return 0;
+}

package/dist/commands/output.d.ts

@@ -0,0 +1,2 @@
+export declare function out(msg?: string): void;
+export declare function warn(msg: string): void;

package/dist/commands/output.js

@@ -0,0 +1,6 @@
+export function out(msg = "") {
+    process.stdout.write(msg + "\n");
+}
+export function warn(msg) {
+    process.stderr.write(`warning: ${msg}\n`);
+}

package/dist/commands/project.d.ts

@@ -0,0 +1,23 @@
+import { type ProjectState } from "../state.js";
+import { type Workspace } from "../workspace.js";
+/** Other active projects touching any of the same repos. */
+export declare function findOverlaps(ws: Workspace, name: string): {
+    project: string;
+    repos: string[];
+}[];
+export declare function createProject(ws: Workspace, name: string): ProjectState;
+export declare function cmdNew(args: string[], passthrough: string[], opts?: {
+    ask?: boolean;
+}): number;
+export declare function cmdResume(args: string[], passthrough: string[], opts?: {
+    fresh?: boolean;
+    ask?: boolean;
+}): number;
+export declare function cmdList(): number;
+export declare function cmdStatus(args: string[], opts?: {
+    json?: boolean;
+}): number;
+export declare function cmdClean(args: string[], opts?: {
+    branches?: boolean;
+    force?: boolean;
+}): number;