cclaw-cli 7.7.0 → 8.1.0

package/dist/run-archive.js

@@ -1,391 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { RUNTIME_ROOT } from "./constants.js";
-import { createInitialFlowState } from "./flow-state.js";
-import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
-import { readKnowledgeSafely } from "./knowledge-store.js";
-import { evaluateRetroGate } from "./retro-gate.js";
-import { ensureRunSystem, flowStateLockPathFor, readFlowState, writeFlowState } from "./run-persistence.js";
-export const ARCHIVE_DISPOSITIONS = ["completed", "cancelled", "abandoned"];
-const ARCHIVE_DIR_REL_PATH = `${RUNTIME_ROOT}/archive`;
-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"
-]);
-const DELEGATION_LOG_FILE = "delegation-log.json";
-const TDD_CYCLE_LOG_FILE = "tdd-cycle-log.jsonl";
-const CRITICAL_STATE_SNAPSHOT_FILES = new Set([
-    "flow-state.json",
-    DELEGATION_LOG_FILE,
-    TDD_CYCLE_LOG_FILE
-]);
-function archiveRoot(projectRoot) {
-    return path.join(projectRoot, ARCHIVE_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);
-}
-function archiveLockPath(projectRoot) {
-    return path.join(projectRoot, RUNTIME_ROOT, "state", ".archive.lock");
-}
-function compoundCloseoutComplete(state) {
-    return (state.closeout.compoundCompletedAt !== undefined ||
-        state.closeout.compoundPromoted > 0 ||
-        (state.closeout.compoundSkipped === true &&
-            typeof state.closeout.compoundSkipReason === "string" &&
-            state.closeout.compoundSkipReason.trim().length > 0));
-}
-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 (error) {
-            if (CRITICAL_STATE_SNAPSHOT_FILES.has(entry.name)) {
-                const details = error instanceof Error ? error.message : String(error);
-                throw new Error(`Archive snapshot failed for critical state file "${entry.name}" (${details}).`);
-            }
-            // Non-critical snapshot files are best-effort and may be skipped.
-        }
-    }
-    return copied.sort((a, b) => a.localeCompare(b));
-}
-async function resetCarryoverStateFiles(projectRoot, activeRunId) {
-    const stateDir = stateDirPath(projectRoot);
-    await ensureDir(stateDir);
-    await writeFileSafe(path.join(stateDir, DELEGATION_LOG_FILE), `${JSON.stringify({ runId: activeRunId, entries: [] }, null, 2)}\n`, { mode: 0o600 });
-    await writeFileSafe(path.join(stateDir, TDD_CYCLE_LOG_FILE), "", { mode: 0o600 });
-}
-async function restoreStateSnapshot(projectRoot, archiveStatePath) {
-    if (!(await exists(archiveStatePath)))
-        return;
-    const stateDir = stateDirPath(projectRoot);
-    await ensureDir(stateDir);
-    const entries = await fs.readdir(archiveStatePath, { withFileTypes: true });
-    for (const entry of entries) {
-        const from = path.join(archiveStatePath, entry.name);
-        const to = path.join(stateDir, entry.name);
-        if (entry.isDirectory()) {
-            await fs.rm(to, { recursive: true, force: true });
-            await fs.cp(from, to, { recursive: true });
-        }
-        else if (entry.isFile()) {
-            await fs.copyFile(from, to);
-        }
-    }
-}
-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 slugifyRunName(value) {
-    const slug = value
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/gu, "-")
-        .replace(/^-+/u, "")
-        .replace(/-+$/u, "");
-    if (slug.length === 0) {
-        return "run";
-    }
-    return slug.slice(0, 64);
-}
-async function inferRunNameFromArtifacts(projectRoot) {
-    const ideaPath = path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH, "00-idea.md");
-    if (!(await exists(ideaPath))) {
-        return "run";
-    }
-    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 "run";
-        }
-        return firstMeaningful.replace(/^[-#*\s]+/u, "").trim() || "run";
-    }
-    catch {
-        return "run";
-    }
-}
-async function uniqueArchiveId(projectRoot, baseId) {
-    let index = 1;
-    let candidate = baseId;
-    while (await exists(path.join(archiveRoot(projectRoot), candidate))) {
-        index += 1;
-        candidate = `${baseId}-${index}`;
-    }
-    return candidate;
-}
-export async function listRuns(projectRoot) {
-    const root = archiveRoot(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, runName, options = {}) {
-    await ensureRunSystem(projectRoot);
-    // Hold BOTH archive.lock and flow-state.lock for the entire archive:
-    // the outer archive lock serializes two concurrent archives; the
-    // inner flow-state lock prevents CLI / hook paths from mutating
-    // flow-state between the archive snapshot and the subsequent reset,
-    // which used to cause lost-update races.
-    return withDirectoryLock(archiveLockPath(projectRoot), async () => {
-        return withDirectoryLock(flowStateLockPathFor(projectRoot), async () => {
-            const artifactsDir = activeArtifactsPath(projectRoot);
-            const archiveDir = archiveRoot(projectRoot);
-            await ensureDir(archiveDir);
-            await ensureDir(artifactsDir);
-            const archiveRunName = (runName?.trim() && runName.trim().length > 0)
-                ? runName.trim()
-                : await inferRunNameFromArtifacts(projectRoot);
-            const archiveBaseId = `${toArchiveDate()}-${slugifyRunName(archiveRunName)}`;
-            const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
-            const archivePath = path.join(archiveDir, archiveId);
-            const archiveArtifactsPath = path.join(archivePath, "artifacts");
-            let sourceState = await readFlowState(projectRoot);
-            const retroGate = await evaluateRetroGate(projectRoot, sourceState);
-            const disposition = options.disposition ?? "completed";
-            const dispositionReason = options.dispositionReason?.trim();
-            const nonCompletedDisposition = disposition !== "completed";
-            if (nonCompletedDisposition && (!dispositionReason || dispositionReason.length === 0)) {
-                throw new Error("archive --disposition=cancelled|abandoned requires --reason=<text>.");
-            }
-            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>.");
-            }
-            if (nonCompletedDisposition && skipRetro) {
-                throw new Error("archive --skip-retro is only valid for completed archives; use --reason with cancelled/abandoned.");
-            }
-            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";
-            const inShipCloseout = sourceState.currentStage === "ship";
-            if (!nonCompletedDisposition && readyForArchive && !compoundCloseoutComplete(sourceState)) {
-                throw new Error("Archive blocked: compound closeout is incomplete. " +
-                    "Promote compound guidance or skip compound review with an explicit reason before archiving.");
-            }
-            if (!nonCompletedDisposition && inShipCloseout && skipRetro) {
-                throw new Error("Archive blocked: --skip-retro is not allowed while current stage is ship. " +
-                    "Complete closeout to ready_to_archive via /cc.");
-            }
-            if (!nonCompletedDisposition && inShipCloseout && !readyForArchive) {
-                throw new Error("Archive blocked: closeout is not ready_to_archive. " +
-                    "Resume /cc until closeout reaches ready_to_archive.");
-            }
-            if (!nonCompletedDisposition && shipCompleted && !readyForArchive && !skipRetro) {
-                throw new Error("Archive blocked: closeout is not ready_to_archive. " +
-                    "Resume /cc until closeout reaches ready_to_archive, " +
-                    "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
-            }
-            if (!nonCompletedDisposition && retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
-                throw new Error("Archive blocked: retro gate is required after ship completion. " +
-                    "Run /cc (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, skipLock: 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);
-            // Drop an `.archive-in-progress` sentinel immediately so that a crash
-            // between the artifact rename and the final manifest write leaves a
-            // recoverable marker (sync reports these; re-running archive on an
-            // orphan attempts to complete or roll back). The sentinel is removed
-            // only after the manifest lands successfully.
-            const sentinelPath = path.join(archivePath, ".archive-in-progress");
-            const archivedAt = new Date().toISOString();
-            await writeFileSafe(sentinelPath, `${JSON.stringify({ archiveId, startedAt: archivedAt, sourceRunId: sourceState.activeRunId }, null, 2)}\n`);
-            const stateBeforeReset = sourceState;
-            let artifactsMoved = false;
-            let stateReset = false;
-            try {
-                await fs.rename(artifactsDir, archiveArtifactsPath);
-                artifactsMoved = true;
-                await ensureDir(artifactsDir);
-                const archiveStatePath = path.join(archivePath, "state");
-                const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
-                const resetState = createInitialFlowState();
-                await writeFlowState(projectRoot, resetState, { allowReset: true, skipLock: true });
-                stateReset = true;
-                await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
-                const manifest = {
-                    version: 2,
-                    archiveId,
-                    archivedAt,
-                    runName: archiveRunName,
-                    sourceRunId: sourceState.activeRunId,
-                    sourceCurrentStage: sourceState.currentStage,
-                    sourceCompletedStages: sourceState.completedStages,
-                    snapshottedStateFiles,
-                    disposition,
-                    ...(dispositionReason ? { dispositionReason } : {}),
-                    retro: retroSummary
-                };
-                await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-                // Manifest landed — sentinel is no longer needed.
-                await fs.unlink(sentinelPath).catch(() => undefined);
-                const knowledgeStats = await readKnowledgeStats(projectRoot);
-                return {
-                    archiveId,
-                    archivePath,
-                    archivedAt,
-                    runName: archiveRunName,
-                    resetState,
-                    snapshottedStateFiles,
-                    disposition,
-                    ...(dispositionReason ? { dispositionReason } : {}),
-                    knowledge: knowledgeStats,
-                    retro: retroSummary
-                };
-            }
-            catch (err) {
-                // Best-effort rollback: if artifacts were moved but the subsequent
-                // steps failed, put artifacts back so the user is not left without
-                // a working run. The sentinel is intentionally left behind for
-                // inspection; sync reports it.
-                if (artifactsMoved) {
-                    try {
-                        await fs.rm(artifactsDir, { recursive: true, force: true });
-                        await fs.rename(archiveArtifactsPath, artifactsDir);
-                    }
-                    catch {
-                        // Rollback failed — sentinel + orphaned archive dir will be
-                        // surfaced by sync and can be reconciled manually.
-                    }
-                }
-                if (stateReset) {
-                    try {
-                        await restoreStateSnapshot(projectRoot, path.join(archivePath, "state"));
-                        await writeFlowState(projectRoot, stateBeforeReset, { allowReset: true, skipLock: true });
-                    }
-                    catch {
-                        // If rollback of state fails, keep sentinel + archive remnants for
-                        // manual reconciliation.
-                    }
-                }
-                throw err;
-            }
-        });
-    }, {
-        retries: 400,
-        retryDelayMs: 25,
-        staleAfterMs: 120_000
-    });
-}
-const KNOWLEDGE_SOFT_THRESHOLD = 50;
-async function readKnowledgeStats(projectRoot) {
-    const { entries } = await readKnowledgeSafely(projectRoot);
-    const activeEntryCount = entries.length;
-    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 sync/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/runs.d.ts

@@ -1,2 +0,0 @@
-export { CorruptFlowStateError, FlowStateGuardMismatchError, InvalidStageTransitionError, type FlowStateGuardSidecar, type FlowStateRepairResult, type WriteFlowStateOptions, ensureRunSystem, flowStateGuardSidecarPathFor, flowStateRepairLogPathFor, readFlowState, readFlowStateGuarded, repairFlowStateGuard, verifyFlowStateGuard, writeFlowState, writeFlowStateGuarded } from "./run-persistence.js";
-export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns, type ArchiveDisposition, type ArchiveManifest, type ArchiveRunOptions, type ArchiveRunResult, type CclawRunMeta } from "./run-archive.js";

package/dist/runs.js

@@ -1,2 +0,0 @@
-export { CorruptFlowStateError, FlowStateGuardMismatchError, InvalidStageTransitionError, ensureRunSystem, flowStateGuardSidecarPathFor, flowStateRepairLogPathFor, readFlowState, readFlowStateGuarded, repairFlowStateGuard, verifyFlowStateGuard, writeFlowState, writeFlowStateGuarded } from "./run-persistence.js";
-export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns } from "./run-archive.js";

package/dist/stack-detection.d.ts

@@ -1,116 +0,0 @@
-export interface StackReviewRouteProfile {
-    stack: string;
-    /**
-     * Signals shown in review routing documentation/skills.
-     * These are human-facing pointers, not strict parsers.
-     */
-    reviewSignals: string[];
-    /** Root-level markers used by start-flow context discovery. */
-    discoveryMarkers: string[];
-    focus: string;
-}
-export declare const STACK_REVIEW_ROUTE_PROFILES: readonly StackReviewRouteProfile[];
-/**
- * Unified root-marker list used by start-flow context discovery.
- * Keep this in one place so stage skill routing and start-flow scanning
- * evolve together.
- */
-export declare const STACK_DISCOVERY_MARKERS: readonly string[];
-/**
- * Directory markers (checked with pathExists) for stack discovery.
- */
-export declare const STACK_DISCOVERY_DIR_MARKERS: readonly string[];
-export type StackAdapterId = "rust" | "node" | "python" | "go" | "ruby" | "php" | "swift" | "dotnet" | "elixir" | "java" | "unknown";
-/** Twin describing manifest → lockfile coupling for a stack. */
-export interface ManifestLockfileTwin {
-    /** Manifest glob (path relative to repo root). */
-    manifestGlob: string;
-    /** Lockfile glob that the manifest's package manager regenerates. */
-    lockfileGlob: string;
-}
-/**
- * Wiring-aggregator contract — describes whether a new file in a stack
- * needs an explicit aggregator/parent module update for the new module to
- * be reachable from the rest of the project.
- *
- * - `aggregatorPattern` is a human-facing description; consumers should
- *   call `resolveAggregatorFor(filePath, repoState?)` to compute the
- *   concrete aggregator path.
- * - `resolveAggregatorFor` returns the concrete repo-relative path of
- *   the aggregator file required to wire `filePath`, or `null` when no
- *   aggregator is required (e.g. file IS the aggregator, or the stack
- *   layout makes wiring implicit).
- * - `repoState.headFiles` lets the resolver check whether sibling
- *   aggregators already exist (so e.g. node-ts only requires
- *   `index.ts` updates when an `index.ts` already exists in that
- *   directory).
- */
-export interface WiringAggregatorContract {
-    aggregatorPattern: string;
-    /**
-     * Resolve the aggregator path required to wire `filePath` into its
-     * parent module, given a snapshot of repo state. Return `null` when
-     * no aggregator update is required.
-     */
-    resolveAggregatorFor(filePath: string, repoState?: {
-        headFiles?: ReadonlySet<string>;
-    }): string | null;
-}
-/**
- * Universal stack-adapter contract used by hooks (slice-commit lockfile
- * twins), linters (`plan_module_introducing_slice_wires_root`), and
- * future stack-specific evidence validators.
- *
- * Each stack returns:
- * - `id` — short stable identifier; routes used elsewhere should match.
- * - `displayName` — used in user-facing prose so error messages stay
- *   stack-agnostic at the surface ("Rust workspace" vs "Node project"
- *   are forbidden in generic code; use `adapter.displayName` instead).
- * - `manifestGlobs` — repo-relative manifest paths the stack uses.
- * - `lockfileTwins` — manifest→lockfile twin entries; auto-detected
- *   from disk at adapter init so node projects with yarn.lock get
- *   `yarn.lock`, pnpm gets `pnpm-lock.yaml`, etc.
- * - `testCommandHints` — example test command lines for prompts and
- *   evidence validators (advisory; not authoritative).
- * - `wiringAggregator` — see contract above. `undefined` when the
- *   stack has no aggregator pattern (Go, Java, Ruby, Swift, .NET,
- *   Elixir use implicit/automatic wiring).
- */
-export interface StackAdapter {
-    id: StackAdapterId;
-    displayName: string;
-    manifestGlobs: string[];
-    lockfileTwins: ManifestLockfileTwin[];
-    testCommandHints: string[];
-    wiringAggregator?: WiringAggregatorContract;
-}
-interface LoadStackAdapterOptions {
-    /**
-     * Override the project root for tests. Defaults to the supplied
-     * argument; primarily here so callers can inject a synthesized
-     * directory in fixtures.
-     */
-    projectRoot?: string;
-}
-/**
- * Load the stack-adapter for a project. Walks the registered factories
- * in order; the first detector that returns true wins. Returns the
- * `unknown` adapter (no-op) when no detector matches.
- *
- * Adapter init reads the filesystem to auto-detect lockfile twins
- * (e.g. yarn.lock vs package-lock.json). Callers should cache the
- * adapter for the lifetime of the operation rather than calling this
- * per-row.
- */
-export declare function loadStackAdapter(projectRoot: string, options?: LoadStackAdapterOptions): Promise<StackAdapter>;
-/**
- * Synthesize a stack adapter from explicit lockfile-twin overrides.
- * Useful in tests that want to pin twins without a real filesystem
- * scan, and for the linter test suite.
- */
-export declare function buildStackAdapterForTests(partial: Partial<StackAdapter> & {
-    id: StackAdapterId;
-    displayName: string;
-}): StackAdapter;
-export declare const UNKNOWN_STACK: StackAdapter;
-export {};