claude-flow 3.49.0 → 3.51.0

package/v3/@claude-flow/cli/dist/src/missions/store.js

@@ -0,0 +1,209 @@
+/**
+ * ADR-406 M0 — durable mission storage.
+ *
+ * Store decision (audit in the PR): ruflo's authoritative state already lives
+ * in project files guarded by a lock and replaced atomically (the policy
+ * ledger in `.claude-flow/policy/`, claims, workspace leases). `better-sqlite3`
+ * is an optional dependency the CLI must run without, and `sql.js` keeps the
+ * database in memory and persists by whole-file export, which is neither
+ * append-durable nor safe across processes. So a mission is:
+ *
+ *   .claude-flow/missions/<missionId>/events.jsonl   append-only, hash-chained
+ *   .claude-flow/missions/<missionId>/snapshot.json  materialized cache (rebuildable)
+ *   .claude-flow/missions/<missionId>/lock           per-mission writer lock
+ *
+ * The log is the truth; the snapshot is only a cache that must agree with it.
+ * Each event is one write of one line followed by fsync. A crash can leave at
+ * most an unterminated last line, which readers ignore and the next locked
+ * writer truncates. Writers take the policy runtime's lock (`acquireLock`),
+ * which recognises a dead owner by pid, pid namespace and boot id.
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, truncateSync, writeSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { acquireLock } from '../services/policy-runtime.js';
+import { MISSION_ID } from './schemas.js';
+import { replay } from './fold.js';
+export const MISSIONS_DIR = join('.claude-flow', 'missions');
+export class MissionStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = 'MissionStoreError';
+    }
+}
+function fsyncPath(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        fsyncSync(fd);
+    }
+    catch {
+        /* directory fsync is unsupported on some platforms; the file itself was synced */
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** tmp + fsync + rename + directory fsync. */
+export function writeFileAtomic(path, text, mode = 0o600) {
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    const fd = openSync(tmp, 'w', mode);
+    try {
+        writeSync(fd, text);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+    fsyncPath(join(path, '..'));
+}
+export function parseLog(buffer) {
+    const events = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const nl = buffer.indexOf(0x0a, offset);
+        if (nl === -1)
+            return { events, validBytes: offset, tornTail: true };
+        const line = buffer.subarray(offset, nl).toString('utf8');
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // A terminated line is a completed write; unparsable means tampering or corruption.
+            throw new MissionStoreError('mission-log-corrupt', `unparsable line at byte ${offset}`);
+        }
+        offset = nl + 1;
+    }
+    return { events, validBytes: offset, tornTail: false };
+}
+export class MissionStore {
+    root;
+    constructor(projectRoot) {
+        this.root = join(resolve(projectRoot), MISSIONS_DIR);
+    }
+    missionDir(missionId) {
+        if (!MISSION_ID.test(missionId))
+            throw new MissionStoreError('invalid-mission-id', missionId);
+        return join(this.root, missionId);
+    }
+    logPath(id) { return join(this.missionDir(id), 'events.jsonl'); }
+    snapshotPath(id) { return join(this.missionDir(id), 'snapshot.json'); }
+    exists(missionId) {
+        return existsSync(this.logPath(missionId));
+    }
+    listMissionIds() {
+        if (!existsSync(this.root))
+            return [];
+        return readdirSync(this.root).filter((n) => MISSION_ID.test(n) && existsSync(join(this.root, n, 'events.jsonl'))).sort();
+    }
+    /** Atomic claim of a new mission id: `mkdir` fails if another request won. */
+    claim(missionId) {
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        try {
+            mkdirSync(this.missionDir(missionId), { mode: 0o700 });
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    readLog(missionId) {
+        const path = this.logPath(missionId);
+        if (!existsSync(path))
+            return { events: [], validBytes: 0, tornTail: false };
+        return parseLog(readFileSync(path));
+    }
+    /** Snapshot when it agrees with the log, then fold the tail; otherwise full replay. */
+    loadView(missionId, log = this.readLog(missionId)) {
+        const snapshotFile = this.snapshotPath(missionId);
+        if (existsSync(snapshotFile)) {
+            try {
+                const snap = JSON.parse(readFileSync(snapshotFile, 'utf8'));
+                const anchor = log.events[snap.sequence - 1];
+                if (anchor && anchor.hash === snap.hash && snap.view.lastHash === snap.hash) {
+                    return replay(log.events.slice(snap.sequence), snap.view);
+                }
+            }
+            catch {
+                /* unreadable cache: rebuild from the log */
+            }
+        }
+        return replay(log.events);
+    }
+    /**
+     * Run `fn` under the mission's writer lock with a freshly replayed view.
+     * Events `fn` returns are appended (each fsynced) only after `fn` validated
+     * them, then the snapshot is refreshed.
+     */
+    async withMission(missionId, fn) {
+        const dir = this.missionDir(missionId);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const release = await acquireLock(join(dir, 'lock'));
+        try {
+            const log = this.readLog(missionId);
+            if (log.tornTail)
+                truncateSync(this.logPath(missionId), log.validBytes);
+            const view = this.loadView(missionId, log);
+            const outcome = fn(view, log);
+            if (outcome.events.length) {
+                this.append(missionId, outcome.events);
+                if (outcome.view)
+                    this.writeSnapshot(missionId, outcome.view);
+            }
+            return outcome.result;
+        }
+        finally {
+            release();
+        }
+    }
+    append(missionId, events) {
+        const fd = openSync(this.logPath(missionId), 'a', 0o600);
+        try {
+            for (const event of events) {
+                const line = Buffer.from(`${JSON.stringify(event)}\n`, 'utf8');
+                let written = 0;
+                while (written < line.length)
+                    written += writeSync(fd, line, written, line.length - written);
+                fsyncSync(fd);
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    writeSnapshot(missionId, view) {
+        writeFileAtomic(this.snapshotPath(missionId), JSON.stringify({
+            schemaVersion: 1,
+            missionId,
+            sequence: view.record.lastEventSequence,
+            hash: view.lastHash,
+            view,
+        }));
+    }
+    /** For diagnostics and tests: the log file's size in bytes. */
+    logSize(missionId) {
+        const path = this.logPath(missionId);
+        return existsSync(path) ? statSync(path).size : 0;
+    }
+    /** Workspace-level lock for the observation file. */
+    async withWorkspaceLock(fn) {
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        const release = await acquireLock(join(this.root, 'observation.lock'));
+        try {
+            return fn();
+        }
+        finally {
+            release();
+        }
+    }
+    writeWorkspaceFile(name, text) {
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        writeFileAtomic(join(this.root, name), text, 0o644);
+    }
+}
+//# sourceMappingURL=store.js.map

package/v3/@claude-flow/cli/dist/src/missions/transitions.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ADR-406 §19.4 — mission state transitions as a data table, and the reducer
+ * that folds an event log into a `MissionView`.
+ *
+ * The table is the single authority: `checkTransition` (before an append) and
+ * `applyEvent` (during replay) both consult it, so a log that replays is a log
+ * whose every control event was a permitted transition. Observations never
+ * change state or revision; a disconnected executor is an observation, not a
+ * failure.
+ */
+import { type ControlEventType, type MissionRecord, type MissionState, type PlanBody } from './schemas.js';
+export type TaskStatus = 'pending' | 'running' | 'recorded-done' | 'failed' | 'unknown';
+export interface EvidenceEntry {
+    readonly evidenceId: string;
+    readonly criterionId: string;
+    readonly taskId: string | null;
+    readonly artifactDigest: string;
+    readonly producer: string;
+    /** True only when the service authenticated the producer; never caller-asserted. */
+    readonly verified: boolean;
+    readonly planRevision: number;
+    readonly criteriaDigest: string;
+    readonly at: string;
+}
+export interface BudgetLedger {
+    readonly currency: string;
+    readonly ceilingMinor: number;
+    readonly estimatedMinor: number;
+    readonly reservedMinor: number;
+    readonly settledMinor: number;
+    readonly unresolvedMinor: number;
+}
+export interface MissionView {
+    readonly record: MissionRecord;
+    readonly planBody: PlanBody | null;
+    readonly budget: BudgetLedger | null;
+    readonly tasks: Readonly<Record<string, {
+        readonly status: TaskStatus;
+        readonly invocationId?: string;
+    }>>;
+    readonly evidence: readonly EvidenceEntry[];
+    readonly executor: {
+        readonly executorId: string;
+        readonly connection: string;
+        readonly observedAt: string;
+        readonly lastAckExecutionId: string | null;
+    } | null;
+    readonly lease: {
+        readonly executorId: string | null;
+        readonly epoch: number;
+    };
+    readonly unresolvedOperations: readonly string[];
+    readonly blockedReason: string | null;
+    readonly lastHash: string;
+}
+export declare class TransitionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+type Guard = (view: MissionView, payload: Record<string, unknown>) => string | null;
+export interface TransitionRule {
+    readonly event: ControlEventType;
+    readonly from: readonly MissionState[];
+    readonly to: MissionState;
+    readonly guard: Guard;
+}
+export declare function digestOf(value: unknown): string;
+/** Well-formedness for §19.4 row 1: graph acyclic, deps resolvable, budget fits. */
+export declare function validatePlan(raw: unknown): {
+    plan: PlanBody;
+    error: null;
+} | {
+    plan: null;
+    error: string;
+};
+export declare const TRANSITIONS: readonly TransitionRule[];
+export declare function ruleFor(event: ControlEventType, from: MissionState): TransitionRule | undefined;
+/** Throws `TransitionError` unless `type` is permitted from the view's state. */
+export declare function checkTransition(view: MissionView, type: ControlEventType, payload: Record<string, unknown>): TransitionRule;
+export {};
+//# sourceMappingURL=transitions.d.ts.map

package/v3/@claude-flow/cli/dist/src/missions/transitions.js

@@ -0,0 +1,178 @@
+/**
+ * ADR-406 §19.4 — mission state transitions as a data table, and the reducer
+ * that folds an event log into a `MissionView`.
+ *
+ * The table is the single authority: `checkTransition` (before an append) and
+ * `applyEvent` (during replay) both consult it, so a log that replays is a log
+ * whose every control event was a permitted transition. Observations never
+ * change state or revision; a disconnected executor is an observation, not a
+ * failure.
+ */
+import { createHash } from 'node:crypto';
+import { TERMINAL_STATES, planBodySchema, } from './schemas.js';
+import { canonicalJson } from '../mods/command-registry/catalog.js';
+export class TransitionError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = 'TransitionError';
+    }
+}
+const ACTIVE = ['queued', 'running', 'pauseRequested', 'paused', 'blocked', 'verifying'];
+const NONTERMINAL = [
+    'draft', 'planned', 'awaitingAuthorization', 'queued', 'running', 'pauseRequested', 'paused', 'blocked', 'verifying',
+];
+// Loss of contact is never proof of failure (§19.3, §19.4 last row).
+const CONNECTIVITY_CAUSES = new Set(['disconnected', 'timeout', 'connection-lost', 'unreachable', 'unknown', 'stale']);
+export function digestOf(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+}
+/** Well-formedness for §19.4 row 1: graph acyclic, deps resolvable, budget fits. */
+export function validatePlan(raw) {
+    const parsed = planBodySchema.safeParse(raw);
+    if (!parsed.success)
+        return { plan: null, error: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ') };
+    const plan = parsed.data;
+    const ids = new Set();
+    for (const t of plan.tasks) {
+        if (ids.has(t.id))
+            return { plan: null, error: `duplicate task id ${t.id}` };
+        ids.add(t.id);
+    }
+    const criteria = new Set(plan.acceptance.map((c) => c.id));
+    if (criteria.size !== plan.acceptance.length)
+        return { plan: null, error: 'duplicate acceptance criterion id' };
+    if (!plan.acceptance.some((c) => c.mandatory))
+        return { plan: null, error: 'at least one mandatory acceptance criterion is required' };
+    for (const t of plan.tasks) {
+        for (const d of t.dependsOn)
+            if (!ids.has(d))
+                return { plan: null, error: `task ${t.id} depends on unknown task ${d}` };
+        for (const c of t.acceptanceEvidence)
+            if (!criteria.has(c))
+                return { plan: null, error: `task ${t.id} names unknown criterion ${c}` };
+    }
+    // Kahn's algorithm: every task must be reachable from a dependency-free task.
+    const indegree = new Map(plan.tasks.map((t) => [t.id, t.dependsOn.length]));
+    const queue = plan.tasks.filter((t) => t.dependsOn.length === 0).map((t) => t.id);
+    let visited = 0;
+    while (queue.length) {
+        const id = queue.shift();
+        visited++;
+        for (const t of plan.tasks) {
+            if (!t.dependsOn.includes(id))
+                continue;
+            const left = (indegree.get(t.id) ?? 0) - 1;
+            indegree.set(t.id, left);
+            if (left === 0)
+                queue.push(t.id);
+        }
+    }
+    if (visited !== plan.tasks.length)
+        return { plan: null, error: 'task graph has a cycle' };
+    const estimated = plan.tasks.reduce((sum, t) => sum + t.estimatedCostMinor, 0);
+    if (estimated > plan.budget.ceilingMinor)
+        return { plan: null, error: `estimated cost ${estimated} exceeds ceiling ${plan.budget.ceilingMinor}` };
+    return { plan, error: null };
+}
+const planGuard = (mustDiffer) => (view, payload) => {
+    const result = validatePlan(payload.plan);
+    if (result.error !== null)
+        return `plan invalid: ${result.error}`;
+    if (payload.digest !== digestOf(result.plan))
+        return 'plan digest does not match plan body';
+    if (mustDiffer && payload.digest === view.record.plan.digest)
+        return 'plan unchanged';
+    return null;
+};
+const admissionGuard = (view, payload) => {
+    if (!view.planBody || !view.budget)
+        return 'no plan to admit';
+    if (payload.planDigest !== view.record.plan.digest)
+        return 'authorization does not cover the current plan revision';
+    if (typeof payload.authorizationRef !== 'string' || !payload.authorizationRef)
+        return 'authorizationRef required';
+    const reservation = payload.reservationMinor;
+    if (typeof reservation !== 'number' || !Number.isInteger(reservation) || reservation < 0)
+        return 'reservationMinor must be a non-negative integer';
+    const b = view.budget;
+    if (b.settledMinor + b.reservedMinor + b.unresolvedMinor + reservation > b.ceilingMinor)
+        return 'budget reservation exceeds the authorized ceiling';
+    return null;
+};
+const epochGuard = (view, payload) => payload.leaseEpoch === view.lease.epoch ? null : `stale lease epoch ${String(payload.leaseEpoch)} (current ${view.lease.epoch})`;
+export const TRANSITIONS = Object.freeze([
+    { event: 'plan.validated', from: ['draft'], to: 'planned', guard: planGuard(false) },
+    { event: 'plan.revised', from: ['planned', 'awaitingAuthorization', 'paused', 'blocked'], to: 'planned', guard: planGuard(true) },
+    { event: 'authorization.missing', from: ['planned'], to: 'awaitingAuthorization', guard: (v) => (v.planBody ? null : 'no concrete plan') },
+    { event: 'admission.accepted', from: ['planned', 'awaitingAuthorization'], to: 'queued', guard: admissionGuard },
+    {
+        event: 'executor.acknowledged', from: ['queued'], to: 'running',
+        guard: (v, p) => (typeof p.executorId !== 'string' || !p.executorId ? 'executorId required' : epochGuard(v, p)),
+    },
+    { event: 'pause.accepted', from: ['running'], to: 'pauseRequested', guard: () => null },
+    { event: 'quiescence.confirmed', from: ['pauseRequested'], to: 'paused', guard: epochGuard },
+    { event: 'blocked', from: ['running', 'queued'], to: 'blocked', guard: (_v, p) => (typeof p.reason === 'string' && p.reason ? null : 'reason required') },
+    { event: 'resume.admitted', from: ['paused', 'blocked'], to: 'queued', guard: admissionGuard },
+    {
+        event: 'tasks.settled', from: ['running'], to: 'verifying',
+        guard: (v) => {
+            if (v.unresolvedOperations.length)
+                return `unresolved operations: ${v.unresolvedOperations.join(', ')}`;
+            const open = Object.entries(v.tasks).filter(([, t]) => t.status !== 'recorded-done' && t.status !== 'failed');
+            return open.length ? `tasks not settled: ${open.map(([id]) => id).join(', ')}` : null;
+        },
+    },
+    {
+        event: 'acceptance.passed', from: ['verifying'], to: 'completed',
+        guard: (v, p) => {
+            const artifact = p.artifactDigest;
+            if (typeof artifact !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(artifact))
+                return 'artifactDigest required';
+            for (const c of (v.planBody?.acceptance ?? []).filter((x) => x.mandatory)) {
+                const ok = v.evidence.some((e) => e.criterionId === c.id && e.verified
+                    && e.planRevision === v.record.plan.revision
+                    && e.criteriaDigest === v.record.acceptance.criteriaDigest
+                    && e.artifactDigest === artifact);
+                if (!ok)
+                    return `criterion ${c.id} lacks verified evidence for this plan, criteria and artifact`;
+            }
+            return null;
+        },
+    },
+    { event: 'acceptance.failed', from: ['verifying'], to: 'failed', guard: (_v, p) => (typeof p.reason === 'string' && p.reason ? null : 'reason required') },
+    { event: 'cancel.admitted', from: NONTERMINAL, to: 'cancelRequested', guard: () => null },
+    {
+        event: 'cancel.settled', from: ['cancelRequested'], to: 'cancelled',
+        guard: (v, p) => {
+            const acked = Array.isArray(p.acknowledgedExecutors) ? p.acknowledgedExecutors : [];
+            return v.lease.executorId && !acked.includes(v.lease.executorId) ? `executor ${v.lease.executorId} has not acknowledged settlement` : null;
+        },
+    },
+    {
+        event: 'failure.verified', from: ACTIVE, to: 'failed',
+        guard: (_v, p) => {
+            if (typeof p.cause !== 'string' || CONNECTIVITY_CAUSES.has(p.cause))
+                return 'lost connectivity is not verified failure';
+            return typeof p.evidenceRef === 'string' && p.evidenceRef ? null : 'evidenceRef required';
+        },
+    },
+]);
+export function ruleFor(event, from) {
+    return TRANSITIONS.find((r) => r.event === event && r.from.includes(from));
+}
+/** Throws `TransitionError` unless `type` is permitted from the view's state. */
+export function checkTransition(view, type, payload) {
+    const from = view.record.state;
+    if (TERMINAL_STATES.has(from))
+        throw new TransitionError('terminal', `mission is ${from}; its history is immutable`);
+    const rule = ruleFor(type, from);
+    if (!rule)
+        throw new TransitionError('invalid-transition', `${type} is not permitted from ${from}`);
+    const reason = rule.guard(view, payload);
+    if (reason)
+        throw new TransitionError('guard-failed', `${type} from ${from}: ${reason}`);
+    return rule;
+}
+//# sourceMappingURL=transitions.js.map

package/v3/@claude-flow/cli/dist/src/mods/apply.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Turn the ruflo mods on (or off) for a project (ADR-404): merge the
+ * settings, sync the policy projection, then make the plugins loadable with
+ * `claude`. One path for `ruflo mods install`, `ruflo init` (and its wizard)
+ * and `ruflo init upgrade --mods`; `removeMods` is `ruflo mods uninstall`.
+ */
+import { type Added, type InstallResult, type MarketplaceEntry, type Scope } from './install.js';
+import { type Exec } from './plugin-repair.js';
+export interface ApplyOptions {
+    scope: Scope;
+    dryRun?: boolean;
+    /** Run `claude plugin marketplace …` and `claude plugin install …` (default true). */
+    pluginInstall?: boolean;
+    /**
+     * Skip the `claude` step under a test runner or CI (VITEST / CI set): an
+     * init there must never clone from GitHub into whatever config dir is live.
+     */
+    skipInTestEnv?: boolean;
+    /** The marketplace to declare when the settings have none (default github ruvnet/ruflo). */
+    marketplace?: MarketplaceEntry;
+    /** Injectable for tests. */
+    exec?: Exec;
+}
+export interface ApplyResult {
+    install: InstallResult;
+    /** Whether every required plugin was left loadable (true when the step was skipped by request). */
+    resolvable: boolean;
+    /** Why the `claude` step did not run, when it did not. */
+    skipped?: string;
+}
+/** One line per thing a run added; empty on a re-run. */
+export declare function describeAdded(added: Added): string[];
+/** What default-on means, said exactly (ADR-404 Amendment 1). */
+export declare const LOAD_NOTE: string[];
+export declare function applyMods(root: string, opts: ApplyOptions): Promise<ApplyResult>;
+/**
+ * `ruflo mods uninstall`: `claude plugin uninstall` exactly the plugins ruflo
+ * installed, then remove exactly the settings keys it added.
+ */
+export declare function removeMods(root: string, opts?: {
+    dryRun?: boolean;
+    exec?: Exec;
+}): Promise<{
+    settingsFiles: string[];
+    removed: boolean;
+    dryRun: boolean;
+    uninstalled: string[];
+    failed: string[];
+}>;
+//# sourceMappingURL=apply.d.ts.map