cclaw-cli 0.46.7 → 0.46.8

package/dist/run-persistence.js

@@ -0,0 +1,380 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { canTransition, createInitialCloseoutState, createInitialFlowState, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
+import { ensureFeatureSystem, syncActiveFeatureSnapshot } from "./feature-system.js";
+import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+export class InvalidStageTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to, message) {
+        super(message);
+        this.from = from;
+        this.to = to;
+        this.name = "InvalidStageTransitionError";
+    }
+}
+const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
+const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
+const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
+const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
+function validateFlowTransition(prev, next) {
+    if (prev.activeRunId !== next.activeRunId) {
+        // New run — only reset paths may change the runId, but those set allowReset.
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change activeRunId from "${prev.activeRunId}" to "${next.activeRunId}" without allowReset.`);
+    }
+    for (const completed of prev.completedStages) {
+        if (!next.completedStages.includes(completed)) {
+            throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage "${completed}" was previously completed but is missing from the new state.`);
+        }
+    }
+    if (prev.currentStage === next.currentStage) {
+        return;
+    }
+    if (!canTransition(prev.currentStage, next.currentStage)) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `no transition rule allows "${prev.currentStage}" -> "${next.currentStage}". Use /cc-next to advance stages or archive the run to reset.`);
+    }
+}
+function flowStatePath(projectRoot) {
+    return path.join(projectRoot, FLOW_STATE_REL_PATH);
+}
+function flowStateLockPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", ".flow-state.lock");
+}
+function runsRoot(projectRoot) {
+    return path.join(projectRoot, RUNS_DIR_REL_PATH);
+}
+function activeArtifactsPath(projectRoot) {
+    return path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH);
+}
+function isFlowStage(value) {
+    return typeof value === "string" && FLOW_STAGE_SET.has(value);
+}
+function sanitizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+function sanitizeCompletedStages(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const unique = new Set();
+    const stages = [];
+    for (const item of value) {
+        if (isFlowStage(item) && !unique.has(item)) {
+            unique.add(item);
+            stages.push(item);
+        }
+    }
+    return stages;
+}
+function sanitizeGuardEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const next = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw === "string") {
+            next[key] = raw;
+        }
+    }
+    return next;
+}
+function sanitizeStageGateCatalog(value, fallback) {
+    const uniqueStrings = (items) => [...new Set(items)];
+    const next = {};
+    for (const stage of COMMAND_FILE_ORDER) {
+        const base = fallback[stage];
+        next[stage] = {
+            required: [...base.required],
+            recommended: [...base.recommended],
+            conditional: [...base.conditional],
+            triggered: [...base.triggered],
+            passed: [...base.passed],
+            blocked: [...base.blocked]
+        };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return next;
+    }
+    const rawCatalog = value;
+    for (const stage of COMMAND_FILE_ORDER) {
+        const rawStage = rawCatalog[stage];
+        if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
+            continue;
+        }
+        const typed = rawStage;
+        const stageState = next[stage];
+        const allowedGateIds = new Set([
+            ...stageState.required,
+            ...stageState.recommended,
+            ...stageState.conditional
+        ]);
+        const conditionalGateIds = new Set(stageState.conditional);
+        const passed = sanitizeStringArray(typed.passed).filter((gate) => allowedGateIds.has(gate));
+        const blocked = sanitizeStringArray(typed.blocked).filter((gate) => allowedGateIds.has(gate));
+        const triggeredFromState = sanitizeStringArray(typed.triggered).filter((gate) => conditionalGateIds.has(gate));
+        const touchedConditionals = [...passed, ...blocked].filter((gate) => conditionalGateIds.has(gate));
+        next[stage] = {
+            required: [...stageState.required],
+            recommended: [...stageState.recommended],
+            conditional: [...stageState.conditional],
+            triggered: uniqueStrings([...triggeredFromState, ...touchedConditionals]),
+            passed,
+            blocked
+        };
+    }
+    return next;
+}
+function coerceTrack(value) {
+    return isFlowTrack(value) ? value : "standard";
+}
+function sanitizeSkippedStages(value, track) {
+    const trackDefault = skippedStagesForTrack(track);
+    if (!Array.isArray(value)) {
+        return trackDefault;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const raw of value) {
+        if (isFlowStage(raw) && !seen.has(raw)) {
+            seen.add(raw);
+            out.push(raw);
+        }
+    }
+    return out.length > 0 ? out : trackDefault;
+}
+function sanitizeStaleStages(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const out = {};
+    for (const [stage, raw] of Object.entries(value)) {
+        if (!isFlowStage(stage))
+            continue;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const typed = raw;
+        const rewindId = typeof typed.rewindId === "string" ? typed.rewindId : "";
+        const reason = typeof typed.reason === "string" ? typed.reason : "";
+        const markedAt = typeof typed.markedAt === "string" ? typed.markedAt : "";
+        const acknowledgedAt = typeof typed.acknowledgedAt === "string" ? typed.acknowledgedAt : undefined;
+        if (!rewindId || !reason || !markedAt) {
+            continue;
+        }
+        out[stage] = {
+            rewindId,
+            reason,
+            markedAt,
+            acknowledgedAt
+        };
+    }
+    return out;
+}
+function sanitizeRewinds(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            continue;
+        }
+        const typed = raw;
+        if (typeof typed.id !== "string" ||
+            !isFlowStage(typed.fromStage) ||
+            !isFlowStage(typed.toStage) ||
+            typeof typed.reason !== "string" ||
+            typeof typed.timestamp !== "string") {
+            continue;
+        }
+        const invalidatedStages = Array.isArray(typed.invalidatedStages)
+            ? typed.invalidatedStages.filter((stage) => isFlowStage(stage))
+            : [];
+        out.push({
+            id: typed.id,
+            fromStage: typed.fromStage,
+            toStage: typed.toStage,
+            reason: typed.reason,
+            timestamp: typed.timestamp,
+            invalidatedStages
+        });
+    }
+    return out;
+}
+function sanitizeRetroState(value) {
+    const fallback = {
+        required: false,
+        completedAt: undefined,
+        compoundEntries: 0
+    };
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return fallback;
+    }
+    const typed = value;
+    const required = typeof typed.required === "boolean" ? typed.required : false;
+    const completedAt = typeof typed.completedAt === "string" ? typed.completedAt : undefined;
+    const compoundEntriesRaw = typed.compoundEntries;
+    const compoundEntries = typeof compoundEntriesRaw === "number" && Number.isFinite(compoundEntriesRaw) && compoundEntriesRaw >= 0
+        ? Math.floor(compoundEntriesRaw)
+        : 0;
+    return {
+        required,
+        completedAt,
+        compoundEntries
+    };
+}
+function isShipSubstate(value) {
+    return typeof value === "string" && SHIP_SUBSTATES.includes(value);
+}
+function sanitizeCloseoutState(value) {
+    const fallback = createInitialCloseoutState();
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return fallback;
+    }
+    const typed = value;
+    const shipSubstate = isShipSubstate(typed.shipSubstate) ? typed.shipSubstate : fallback.shipSubstate;
+    const retroDraftedAt = typeof typed.retroDraftedAt === "string" ? typed.retroDraftedAt : undefined;
+    const retroAcceptedAt = typeof typed.retroAcceptedAt === "string" ? typed.retroAcceptedAt : undefined;
+    const retroSkipped = typeof typed.retroSkipped === "boolean" ? typed.retroSkipped : undefined;
+    const retroSkipReason = typeof typed.retroSkipReason === "string" ? typed.retroSkipReason : undefined;
+    const compoundCompletedAt = typeof typed.compoundCompletedAt === "string" ? typed.compoundCompletedAt : undefined;
+    const compoundSkipped = typeof typed.compoundSkipped === "boolean" ? typed.compoundSkipped : undefined;
+    const promotedRaw = typed.compoundPromoted;
+    const compoundPromoted = typeof promotedRaw === "number" && Number.isFinite(promotedRaw) && promotedRaw >= 0
+        ? Math.floor(promotedRaw)
+        : 0;
+    return {
+        shipSubstate,
+        retroDraftedAt,
+        retroAcceptedAt,
+        retroSkipped,
+        retroSkipReason,
+        compoundCompletedAt,
+        compoundSkipped,
+        compoundPromoted
+    };
+}
+function coerceFlowState(parsed) {
+    const track = coerceTrack(parsed.track);
+    const next = createInitialFlowState("active", track);
+    const activeRunIdRaw = parsed.activeRunId;
+    const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
+        ? activeRunIdRaw.trim()
+        : next.activeRunId;
+    return {
+        activeRunId,
+        currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
+        completedStages: sanitizeCompletedStages(parsed.completedStages),
+        guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
+        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog),
+        track,
+        skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
+        staleStages: sanitizeStaleStages(parsed.staleStages),
+        rewinds: sanitizeRewinds(parsed.rewinds),
+        retro: sanitizeRetroState(parsed.retro),
+        closeout: sanitizeCloseoutState(parsed.closeout)
+    };
+}
+export class CorruptFlowStateError extends Error {
+    statePath;
+    quarantinedPath;
+    constructor(statePath, quarantinedPath, cause) {
+        super(`Corrupt flow-state.json detected at ${statePath}. ` +
+            `Quarantined to ${quarantinedPath}. ` +
+            `Inspect the quarantined file, reconcile by hand, then re-run your command ` +
+            `or delete ${statePath} to start over. ` +
+            `Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "CorruptFlowStateError";
+        this.statePath = statePath;
+        this.quarantinedPath = quarantinedPath;
+        if (cause instanceof Error) {
+            this.cause = cause;
+        }
+    }
+}
+function quarantineTimestamp(date = new Date()) {
+    return date.toISOString().replace(/[:.]/gu, "-");
+}
+async function quarantineCorruptState(statePath, cause) {
+    const quarantinedPath = `${statePath}.corrupt-${quarantineTimestamp()}.json`;
+    try {
+        await fs.rename(statePath, quarantinedPath);
+    }
+    catch (renameErr) {
+        try {
+            const raw = await fs.readFile(statePath, "utf8");
+            await fs.writeFile(quarantinedPath, raw, "utf8");
+            await fs.unlink(statePath).catch(() => undefined);
+        }
+        catch {
+            throw new CorruptFlowStateError(statePath, quarantinedPath, renameErr);
+        }
+    }
+    throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
+}
+export async function readFlowState(projectRoot) {
+    await ensureFeatureSystem(projectRoot);
+    const statePath = flowStatePath(projectRoot);
+    if (!(await exists(statePath))) {
+        return createInitialFlowState();
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(statePath, "utf8");
+    }
+    catch (readErr) {
+        throw new CorruptFlowStateError(statePath, statePath, readErr);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (parseErr) {
+        await quarantineCorruptState(statePath, parseErr);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        await quarantineCorruptState(statePath, new Error("flow-state.json did not deserialize to a JSON object"));
+    }
+    return coerceFlowState(parsed);
+}
+export async function writeFlowState(projectRoot, state, options = {}) {
+    await ensureFeatureSystem(projectRoot);
+    await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
+        const statePath = flowStatePath(projectRoot);
+        if (!options.allowReset && (await exists(statePath))) {
+            try {
+                const raw = await fs.readFile(statePath, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    const prev = coerceFlowState(parsed);
+                    validateFlowTransition(prev, state);
+                }
+            }
+            catch (err) {
+                if (err instanceof InvalidStageTransitionError) {
+                    throw err;
+                }
+                // A corrupt prior file is surfaced by readFlowState elsewhere; don't
+                // block a legitimate write attempt on parse errors here.
+            }
+        }
+        const safe = coerceFlowState({ ...state });
+        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`);
+    });
+    await syncActiveFeatureSnapshot(projectRoot);
+}
+export async function ensureRunSystem(projectRoot, _options = {}) {
+    await ensureFeatureSystem(projectRoot);
+    await ensureDir(runsRoot(projectRoot));
+    await ensureDir(activeArtifactsPath(projectRoot));
+    const statePath = flowStatePath(projectRoot);
+    const state = await readFlowState(projectRoot);
+    if (!(await exists(statePath))) {
+        await writeFlowState(projectRoot, state, { allowReset: true });
+    }
+    await syncActiveFeatureSnapshot(projectRoot);
+    return state;
+}

package/dist/runs.d.ts

@@ -1,79 +1,2 @@
-import { type FlowState } from "./flow-state.js";
-import type { FlowStage } from "./types.js";
-export declare class InvalidStageTransitionError extends Error {
-    readonly from: FlowStage;
-    readonly to: FlowStage;
-    constructor(from: FlowStage, to: FlowStage, message: string);
-}
-export interface WriteFlowStateOptions {
-    /**
-     * When true, skip prior-state validation. Used for run archival, initial
-     * bootstrap, or explicit recovery; never set from normal stage handlers.
-     */
-    allowReset?: boolean;
-}
-export interface CclawRunMeta {
-    id: string;
-    title: string;
-    createdAt: string;
-}
-export interface ArchiveRunResult {
-    archiveId: string;
-    archivePath: string;
-    archivedAt: string;
-    featureName: string;
-    activeFeature: string;
-    resetState: FlowState;
-    snapshottedStateFiles: string[];
-    /** Knowledge curation hint: total active entries + soft threshold (50). */
-    knowledge: {
-        activeEntryCount: number;
-        softThreshold: number;
-        overThreshold: boolean;
-        knowledgePath: string;
-    };
-    retro: {
-        required: boolean;
-        completed: boolean;
-        skipped: boolean;
-        skipReason?: string;
-        compoundEntries: number;
-    };
-}
-export interface ArchiveManifest {
-    version: 1;
-    archiveId: string;
-    archivedAt: string;
-    featureName: string;
-    activeFeature: string;
-    sourceRunId: string;
-    sourceCurrentStage: FlowStage;
-    sourceCompletedStages: FlowStage[];
-    snapshottedStateFiles: string[];
-    retro: ArchiveRunResult["retro"];
-}
-interface EnsureRunSystemOptions {
-    createIfMissing?: boolean;
-}
-export interface ArchiveRunOptions {
-    skipRetro?: boolean;
-    skipRetroReason?: string;
-}
-export declare class CorruptFlowStateError extends Error {
-    readonly statePath: string;
-    readonly quarantinedPath: string;
-    constructor(statePath: string, quarantinedPath: string, cause: unknown);
-}
-export declare function readFlowState(projectRoot: string): Promise<FlowState>;
-export declare function writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
-export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
-export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
-export declare function archiveRun(projectRoot: string, featureName?: string, options?: ArchiveRunOptions): Promise<ArchiveRunResult>;
-/**
- * Counts entries in the canonical JSONL knowledge store. An "active" entry is one
- * non-empty line that parses as JSON with the required `type` field belonging to the
- * allowed set. Malformed lines are ignored (not counted) but do not throw so that a
- * hand-edited file cannot break doctor/archive flows.
- */
-export declare function countActiveKnowledgeEntries(text: string): number;
-export {};
+export { CorruptFlowStateError, InvalidStageTransitionError, type WriteFlowStateOptions, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
+export { archiveRun, countActiveKnowledgeEntries, listRuns, type ArchiveManifest, type ArchiveRunOptions, type ArchiveRunResult, type CclawRunMeta } from "./run-archive.js";