@openfleet-tools/cli 0.0.0-stage → 0.1.0

package/dist/state.d.ts

@@ -0,0 +1,68 @@
+import { type ProjectPaths } from "./workspace.js";
+export declare const STATE_SCHEMA_VERSION = 1;
+/** `specifying` covers the whole grill, including the final spec review; the user's answer moves it to `running`. */
+export declare const PROJECT_STATUSES: readonly ["specifying", "running", "finalizing", "done", "cancelled"];
+export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
+/** `failed`: retries and the coordinator's guided attempt both failed. `blocked`: a dependency failed. */
+export declare const CHILD_PHASES: readonly ["pending", "planning", "plan-review", "implementing", "testing", "post-test", "done", "failed", "blocked"];
+export type ChildPhase = (typeof CHILD_PHASES)[number];
+export type Role = "planner" | "implementer" | "tester";
+export type CompletionMode = "staged" | "draft-pr";
+export interface ChildState {
+    /** Key in repos.json. */
+    repo: string;
+    /** Package path inside a monorepo, if this child targets one package. */
+    package?: string;
+    /** Absolute path of the source repository checkout. */
+    repoPath?: string;
+    worktree?: string;
+    branch?: string;
+    baseBranch?: string;
+    /** Commit the worktree branched from; snapshots diff against it. */
+    baseSha?: string;
+    phase: ChildPhase;
+    /** Role of the currently active agent for this child. */
+    role?: Role;
+    /** Set by the coordinator just before spawning; consumed by the subagentStart hook. */
+    pendingSpawn?: Role;
+    retries: number;
+    dependsOn: string[];
+    agentIds: Partial<Record<Role, string>>;
+    plan?: string;
+    prUrl?: string;
+    lastSnapshot?: string;
+    notes?: string;
+}
+export interface Question {
+    id: string;
+    from: string;
+    text: string;
+    status: "open" | "answered";
+    answer?: string;
+    /** `spec`: answered from spec.md/contracts. `coordinator`: decided by the coordinator (logged as an `assumption`). */
+    answeredBy?: "spec" | "coordinator";
+}
+export interface ProjectState {
+    v: typeof STATE_SCHEMA_VERSION;
+    name: string;
+    status: ProjectStatus;
+    createdAt: string;
+    updatedAt: string;
+    /** Copilot CLI session id of the coordinator session, used by `resume`. */
+    sessionId?: string;
+    completionMode?: CompletionMode;
+    specApproved?: boolean;
+    /** Keyed by child id: `<repo>` or `<repo>:<package>`. */
+    children: Record<string, ChildState>;
+    questions: Question[];
+}
+export declare function newState(name: string, sessionId?: string): ProjectState;
+export declare function readState(p: ProjectPaths): ProjectState;
+/** RFC 7396 JSON merge patch: objects merge, `null` deletes, everything else replaces. */
+export declare function mergePatch<T>(target: T, patch: unknown): T;
+/**
+ * Read-modify-write state.json under the project's state lock. Emits
+ * `phase.changed` events for project status and child phase transitions.
+ */
+export declare function updateState(p: ProjectPaths, mutate: (s: ProjectState) => ProjectState | void, actor?: string): ProjectState;
+export declare function patchState(p: ProjectPaths, patch: unknown, actor?: string): ProjectState;

package/dist/state.js

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import { appendEvent } from "./events.js";
+import { readJson, writeJson } from "./fsutil.js";
+import { withLock } from "./lock.js";
+import { UserError } from "./workspace.js";
+export const STATE_SCHEMA_VERSION = 1;
+/** `specifying` covers the whole grill, including the final spec review; the user's answer moves it to `running`. */
+export const PROJECT_STATUSES = ["specifying", "running", "finalizing", "done", "cancelled"];
+/** `failed`: retries and the coordinator's guided attempt both failed. `blocked`: a dependency failed. */
+export const CHILD_PHASES = [
+    "pending",
+    "planning",
+    "plan-review",
+    "implementing",
+    "testing",
+    "post-test",
+    "done",
+    "failed",
+    "blocked",
+];
+export function newState(name, sessionId) {
+    const now = new Date().toISOString();
+    return {
+        v: STATE_SCHEMA_VERSION,
+        name,
+        status: "specifying",
+        createdAt: now,
+        updatedAt: now,
+        ...(sessionId ? { sessionId } : {}),
+        children: {},
+        questions: [],
+    };
+}
+export function readState(p) {
+    if (!fs.existsSync(p.state))
+        throw new UserError(`Project "${p.name}" not found (${p.state}).`);
+    return readJson(p.state);
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** RFC 7396 JSON merge patch: objects merge, `null` deletes, everything else replaces. */
+export function mergePatch(target, patch) {
+    if (!isPlainObject(patch))
+        return patch;
+    const base = isPlainObject(target) ? { ...target } : {};
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null)
+            delete base[k];
+        else
+            base[k] = mergePatch(base[k], v);
+    }
+    return base;
+}
+function normalizeChildren(state) {
+    for (const [id, child] of Object.entries(state.children)) {
+        child.repo ??= id.split(":")[0] ?? id;
+        child.phase ??= "pending";
+        child.retries ??= 0;
+        child.dependsOn ??= [];
+        child.agentIds ??= {};
+    }
+}
+function validateTransitions(prev, next) {
+    if (prev.status !== next.status && !PROJECT_STATUSES.includes(next.status)) {
+        throw new UserError(`Unknown project status "${next.status}". Use one of: ${PROJECT_STATUSES.join(", ")}.`);
+    }
+    for (const [id, child] of Object.entries(next.children)) {
+        if (prev.children[id]?.phase !== child.phase && !CHILD_PHASES.includes(child.phase)) {
+            throw new UserError(`Unknown phase "${child.phase}" for child ${id}. Use one of: ${CHILD_PHASES.join(", ")}.`);
+        }
+    }
+}
+/**
+ * Read-modify-write state.json under the project's state lock. Emits
+ * `phase.changed` events for project status and child phase transitions.
+ */
+export function updateState(p, mutate, actor = "coordinator") {
+    const changes = [];
+    const next = withLock(p.stateLock, () => {
+        const prev = readState(p);
+        const draft = structuredClone(prev);
+        const result = mutate(draft) ?? draft;
+        normalizeChildren(result);
+        validateTransitions(prev, result);
+        result.updatedAt = new Date().toISOString();
+        if (prev.status !== result.status)
+            changes.push({ target: null, from: prev.status, to: result.status });
+        for (const [id, child] of Object.entries(result.children)) {
+            const before = prev.children[id]?.phase;
+            if (before !== child.phase)
+                changes.push({ target: id, from: before, to: child.phase });
+        }
+        writeJson(p.state, result);
+        return result;
+    });
+    for (const c of changes) {
+        appendEvent(p, {
+            actor,
+            type: "phase.changed",
+            target: c.target,
+            payload: { scope: c.target ? "child" : "project", from: c.from ?? null, to: c.to },
+        });
+    }
+    return next;
+}
+export function patchState(p, patch, actor) {
+    if (!isPlainObject(patch))
+        throw new UserError("State patch must be a JSON object.");
+    return updateState(p, (s) => mergePatch(s, patch), actor);
+}

package/dist/workspace.d.ts

@@ -0,0 +1,36 @@
+export declare const DIR = "openfleet";
+export interface Workspace {
+    /** Directory containing the `openfleet/` folder. */
+    root: string;
+    /** `<root>/openfleet` */
+    dir: string;
+    core: string;
+    extensions: string;
+    projects: string;
+    reposFile: string;
+    lockFile: string;
+}
+export declare function workspaceAt(root: string): Workspace;
+/** Walk up from `start` to find the nearest OpenFleet workspace. */
+export declare function findWorkspace(start: string): Workspace | undefined;
+export declare function requireWorkspace(start?: string): Workspace;
+export interface ProjectPaths {
+    name: string;
+    dir: string;
+    spec: string;
+    state: string;
+    contracts: string;
+    plans: string;
+    events: string;
+    seq: string;
+    eventsLock: string;
+    stateLock: string;
+    patches: string;
+    worktrees: string;
+}
+export declare function projectPaths(ws: Workspace, name: string): ProjectPaths;
+export declare function validateProjectName(name: string | undefined): string;
+export declare function listProjectNames(ws: Workspace): string[];
+/** Errors that should be printed without a stack trace. */
+export declare class UserError extends Error {
+}

package/dist/workspace.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isDir, isFile, realish } from "./fsutil.js";
+export const DIR = "openfleet";
+const PROJECT_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export function workspaceAt(root) {
+    const dir = path.join(root, DIR);
+    return {
+        root,
+        dir,
+        core: path.join(dir, "core"),
+        extensions: path.join(dir, "extensions"),
+        projects: path.join(dir, "projects"),
+        reposFile: path.join(dir, "repos.json"),
+        lockFile: path.join(dir, "extensions.lock.json"),
+    };
+}
+function isWorkspaceRoot(root) {
+    return isFile(path.join(root, DIR, "repos.json"));
+}
+/** Walk up from `start` to find the nearest OpenFleet workspace. */
+export function findWorkspace(start) {
+    let cur = realish(start);
+    for (;;) {
+        if (isWorkspaceRoot(cur))
+            return workspaceAt(cur);
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return undefined;
+        cur = parent;
+    }
+}
+export function requireWorkspace(start = process.cwd()) {
+    const ws = findWorkspace(start);
+    if (!ws) {
+        throw new UserError(`No OpenFleet workspace found from ${start}. Run \`npm create @openfleet-tools\` (or \`npx openfleet init\`) first.`);
+    }
+    return ws;
+}
+export function projectPaths(ws, name) {
+    const dir = path.join(ws.projects, name);
+    return {
+        name,
+        dir,
+        spec: path.join(dir, "spec.md"),
+        state: path.join(dir, "state.json"),
+        contracts: path.join(dir, "contracts"),
+        plans: path.join(dir, "plans"),
+        events: path.join(dir, "events.jsonl"),
+        seq: path.join(dir, ".events.seq"),
+        eventsLock: path.join(dir, ".events.lock"),
+        stateLock: path.join(dir, ".state.lock"),
+        patches: path.join(dir, "patches"),
+        worktrees: path.join(dir, "worktrees"),
+    };
+}
+export function validateProjectName(name) {
+    if (!name || !PROJECT_NAME.test(name)) {
+        throw new UserError(`Invalid project name "${name ?? ""}". Use lowercase letters, digits and dashes (e.g. better-auth).`);
+    }
+    return name;
+}
+export function listProjectNames(ws) {
+    if (!isDir(ws.projects))
+        return [];
+    return fs
+        .readdirSync(ws.projects, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && isFile(path.join(ws.projects, d.name, "state.json")))
+        .map((d) => d.name)
+        .sort();
+}
+/** Errors that should be printed without a stack trace. */
+export class UserError extends Error {
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@openfleet-tools/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Coordinate one change across many repos with GitHub Copilot CLI.",
+  "license": "MIT",
+  "homepage": "https://openfleet.tools",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yashicon21/openfleet.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/yashicon21/openfleet/issues"
+  },
+  "type": "module",
+  "bin": {
+    "openfleet": "dist/bin.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "core"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "copilot",
+    "multi-repo",
+    "agents",
+    "coordination"
+  ],
+  "dependencies": {
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/bin.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.