cclaw-cli 0.46.6 → 0.46.8

package/dist/retro-gate.js

@@ -0,0 +1,83 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "./constants.js";
+import { exists } from "./fs-utils.js";
+function activeArtifactsPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "artifacts");
+}
+function retroArtifactPath(projectRoot) {
+    return path.join(activeArtifactsPath(projectRoot), "09-retro.md");
+}
+function parseIsoTimestamp(value) {
+    if (!value || value.trim().length === 0)
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function inInclusiveWindow(timestamp, windowStartMs, windowEndMs) {
+    if (windowStartMs !== null && timestamp < windowStartMs)
+        return false;
+    if (windowEndMs !== null && timestamp > windowEndMs)
+        return false;
+    return true;
+}
+export async function evaluateRetroGate(projectRoot, state) {
+    const required = state.completedStages.includes("ship");
+    const artifactFile = retroArtifactPath(projectRoot);
+    let hasRetroArtifact = false;
+    if (await exists(artifactFile)) {
+        try {
+            const raw = await fs.readFile(artifactFile, "utf8");
+            hasRetroArtifact = raw.trim().length > 0;
+        }
+        catch {
+            hasRetroArtifact = false;
+        }
+    }
+    let compoundEntries = state.retro.compoundEntries;
+    const windowStartMs = parseIsoTimestamp(state.closeout.retroDraftedAt);
+    const windowEndMs = parseIsoTimestamp(state.closeout.retroAcceptedAt) ?? parseIsoTimestamp(state.retro.completedAt);
+    const shouldFallbackScan = compoundEntries <= 0 && (windowStartMs !== null || windowEndMs !== null);
+    const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
+    if (shouldFallbackScan && (await exists(knowledgeFile))) {
+        try {
+            const raw = await fs.readFile(knowledgeFile, "utf8");
+            compoundEntries = 0;
+            for (const line of raw.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (parsed.type !== "compound") {
+                        continue;
+                    }
+                    const created = typeof parsed.created === "string" ? parseIsoTimestamp(parsed.created) : null;
+                    if (created === null || !inInclusiveWindow(created, windowStartMs, windowEndMs)) {
+                        continue;
+                    }
+                    const source = typeof parsed.source === "string"
+                        ? parsed.source.trim().toLowerCase()
+                        : null;
+                    const legacyRetroStage = parsed.stage === "retro";
+                    if (source === "retro" || legacyRetroStage) {
+                        compoundEntries += 1;
+                    }
+                }
+                catch {
+                    // ignore malformed lines for retro gate calculation
+                }
+            }
+        }
+        catch {
+            compoundEntries = 0;
+        }
+    }
+    const completed = required ? (hasRetroArtifact && compoundEntries > 0) : true;
+    return {
+        required,
+        completed,
+        compoundEntries,
+        hasRetroArtifact
+    };
+}

package/dist/run-archive.d.ts

@@ -0,0 +1,55 @@
+import { type FlowState } from "./flow-state.js";
+import type { FlowStage } from "./types.js";
+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"];
+}
+export interface ArchiveRunOptions {
+    skipRetro?: boolean;
+    skipRetroReason?: string;
+}
+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;

package/dist/run-archive.js

@@ -0,0 +1,270 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "./constants.js";
+import { createInitialFlowState } from "./flow-state.js";
+import { readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.js";
+import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+import { evaluateRetroGate } from "./retro-gate.js";
+import { ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
+const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
+const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
+const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
+/** State filenames explicitly excluded from the archive snapshot. */
+const STATE_SNAPSHOT_EXCLUDE = new Set([
+    ".flow-state.lock",
+    ".delegation.lock"
+]);
+function runsRoot(projectRoot) {
+    return path.join(projectRoot, RUNS_DIR_REL_PATH);
+}
+function activeArtifactsPath(projectRoot) {
+    return path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH);
+}
+function stateDirPath(projectRoot) {
+    return path.join(projectRoot, STATE_DIR_REL_PATH);
+}
+async function snapshotStateDirectory(projectRoot, destinationRoot) {
+    const sourceDir = stateDirPath(projectRoot);
+    if (!(await exists(sourceDir))) {
+        return [];
+    }
+    await ensureDir(destinationRoot);
+    const copied = [];
+    let entries;
+    try {
+        entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (STATE_SNAPSHOT_EXCLUDE.has(entry.name))
+            continue;
+        if (entry.name.startsWith(".") && !entry.name.endsWith(".json"))
+            continue;
+        const from = path.join(sourceDir, entry.name);
+        const to = path.join(destinationRoot, entry.name);
+        try {
+            if (entry.isDirectory()) {
+                await fs.cp(from, to, { recursive: true });
+                copied.push(`${entry.name}/`);
+            }
+            else if (entry.isFile()) {
+                await fs.copyFile(from, to);
+                copied.push(entry.name);
+            }
+        }
+        catch {
+            // best-effort snapshot; continue on individual failures
+        }
+    }
+    return copied.sort((a, b) => a.localeCompare(b));
+}
+function toArchiveDate(date = new Date()) {
+    const yyyy = date.getFullYear().toString();
+    const mm = (date.getMonth() + 1).toString().padStart(2, "0");
+    const dd = date.getDate().toString().padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}`;
+}
+function slugifyFeatureName(value) {
+    const slug = value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+/u, "")
+        .replace(/-+$/u, "");
+    if (slug.length === 0) {
+        return "feature";
+    }
+    return slug.slice(0, 64);
+}
+async function inferFeatureNameFromArtifacts(projectRoot) {
+    const ideaPath = path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH, "00-idea.md");
+    if (!(await exists(ideaPath))) {
+        return "feature";
+    }
+    try {
+        const raw = await fs.readFile(ideaPath, "utf8");
+        const firstMeaningful = raw
+            .split(/\r?\n/gu)
+            .map((line) => line.trim())
+            .find((line) => line.length > 0);
+        if (!firstMeaningful) {
+            return "feature";
+        }
+        return firstMeaningful.replace(/^[-#*\s]+/u, "").trim() || "feature";
+    }
+    catch {
+        return "feature";
+    }
+}
+async function uniqueArchiveId(projectRoot, baseId) {
+    let index = 1;
+    let candidate = baseId;
+    while (await exists(path.join(runsRoot(projectRoot), candidate))) {
+        index += 1;
+        candidate = `${baseId}-${index}`;
+    }
+    return candidate;
+}
+export async function listRuns(projectRoot) {
+    const root = runsRoot(projectRoot);
+    if (!(await exists(root))) {
+        return [];
+    }
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const runs = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const runPath = path.join(root, entry.name);
+        let createdAt = new Date().toISOString();
+        try {
+            const stat = await fs.stat(runPath);
+            createdAt = stat.birthtime?.toISOString?.() ?? stat.mtime.toISOString();
+        }
+        catch {
+            // keep fallback timestamp
+        }
+        runs.push({
+            id: entry.name,
+            title: entry.name,
+            createdAt
+        });
+    }
+    return runs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export async function archiveRun(projectRoot, featureName, options = {}) {
+    await ensureRunSystem(projectRoot);
+    const activeFeature = await readActiveFeature(projectRoot);
+    const artifactsDir = activeArtifactsPath(projectRoot);
+    const runsDir = runsRoot(projectRoot);
+    await ensureDir(runsDir);
+    await ensureDir(artifactsDir);
+    const feature = (featureName?.trim() && featureName.trim().length > 0)
+        ? featureName.trim()
+        : await inferFeatureNameFromArtifacts(projectRoot);
+    const archiveBaseId = `${toArchiveDate()}-${slugifyFeatureName(feature)}`;
+    const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
+    const archivePath = path.join(runsDir, archiveId);
+    const archiveArtifactsPath = path.join(archivePath, "artifacts");
+    let sourceState = await readFlowState(projectRoot);
+    const retroGate = await evaluateRetroGate(projectRoot, sourceState);
+    const shipCompleted = sourceState.completedStages.includes("ship");
+    const skipRetro = options.skipRetro === true;
+    const skipRetroReason = options.skipRetroReason?.trim();
+    if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
+        throw new Error("archive --skip-retro requires --retro-reason=<text>.");
+    }
+    const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
+        typeof sourceState.closeout.retroSkipReason === "string" &&
+        sourceState.closeout.retroSkipReason.trim().length > 0;
+    const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
+    if (shipCompleted && !readyForArchive && !skipRetro) {
+        throw new Error("Archive blocked: closeout is not ready_to_archive. " +
+            "Resume /cc-next until closeout reaches ready_to_archive, " +
+            "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
+    }
+    if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
+        throw new Error("Archive blocked: retro gate is required after ship completion. " +
+            "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
+    }
+    if (retroGate.completed) {
+        const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();
+        sourceState = {
+            ...sourceState,
+            retro: {
+                required: retroGate.required,
+                completedAt,
+                compoundEntries: retroGate.compoundEntries
+            }
+        };
+        await writeFlowState(projectRoot, sourceState, { allowReset: true });
+    }
+    const retroSummary = {
+        required: retroGate.required,
+        completed: retroGate.completed,
+        skipped: skipRetro || retroSkippedInCloseout,
+        skipReason: skipRetro
+            ? skipRetroReason
+            : retroSkippedInCloseout
+                ? sourceState.closeout.retroSkipReason
+                : undefined,
+        compoundEntries: retroGate.compoundEntries
+    };
+    await ensureDir(archivePath);
+    await fs.rename(artifactsDir, archiveArtifactsPath);
+    await ensureDir(artifactsDir);
+    const archiveStatePath = path.join(archivePath, "state");
+    const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
+    const resetState = createInitialFlowState();
+    await writeFlowState(projectRoot, resetState, { allowReset: true });
+    const archivedAt = new Date().toISOString();
+    const manifest = {
+        version: 1,
+        archiveId,
+        archivedAt,
+        featureName: feature,
+        activeFeature,
+        sourceRunId: sourceState.activeRunId,
+        sourceCurrentStage: sourceState.currentStage,
+        sourceCompletedStages: sourceState.completedStages,
+        snapshottedStateFiles,
+        retro: retroSummary
+    };
+    await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    const knowledgeStats = await readKnowledgeStats(projectRoot);
+    await syncActiveFeatureSnapshot(projectRoot);
+    return {
+        archiveId,
+        archivePath,
+        archivedAt,
+        featureName: feature,
+        activeFeature,
+        resetState,
+        snapshottedStateFiles,
+        knowledge: knowledgeStats,
+        retro: retroSummary
+    };
+}
+const KNOWLEDGE_SOFT_THRESHOLD = 50;
+async function readKnowledgeStats(projectRoot) {
+    const knowledgePath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
+    let activeEntryCount = 0;
+    if (await exists(knowledgePath)) {
+        const text = await fs.readFile(knowledgePath, "utf8");
+        activeEntryCount = countActiveKnowledgeEntries(text);
+    }
+    return {
+        activeEntryCount,
+        softThreshold: KNOWLEDGE_SOFT_THRESHOLD,
+        overThreshold: activeEntryCount > KNOWLEDGE_SOFT_THRESHOLD,
+        knowledgePath: `${RUNTIME_ROOT}/knowledge.jsonl`
+    };
+}
+/**
+ * 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 function countActiveKnowledgeEntries(text) {
+    const allowed = new Set(["rule", "pattern", "lesson", "compound"]);
+    let count = 0;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.type === "string" && allowed.has(parsed.type)) {
+                count += 1;
+            }
+        }
+        catch {
+            // Skip malformed lines silently; curation surfaces them separately.
+        }
+    }
+    return count;
+}

package/dist/run-persistence.d.ts

@@ -0,0 +1,26 @@
+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 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>;
+interface EnsureRunSystemOptions {
+    createIfMissing?: boolean;
+}
+export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
+export {};