cclaw-cli 7.7.1 → 8.1.0

package/dist/internal/tdd-red-evidence.d.ts

@@ -1,7 +0,0 @@
-import type { Writable } from "node:stream";
-interface InternalIo {
-    stdout: Writable;
-    stderr: Writable;
-}
-export declare function runTddRedEvidenceCommand(projectRoot: string, tokens: string[], io: InternalIo): Promise<number>;
-export {};

package/dist/internal/tdd-red-evidence.js

@@ -1,153 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { RUNTIME_ROOT } from "../constants.js";
-import { readFlowState } from "../runs.js";
-import { hasFailingTestForPath, parseTddCycleLog, pathMatchesTarget } from "../tdd-cycle.js";
-// normalizePath and the path matcher live in src/tdd-cycle.ts so all
-// TDD-related guards (internal CLI, runtime hook, unit tests) agree on
-// what "path X matches recorded file Y" means.
-function parseArgs(tokens) {
-    const args = { quiet: false };
-    for (const token of tokens) {
-        if (token === "--quiet") {
-            args.quiet = true;
-            continue;
-        }
-        if (token.startsWith("--path=")) {
-            const value = token.slice("--path=".length).trim();
-            if (!value) {
-                throw new Error("--path must not be empty.");
-            }
-            args.targetPath = value;
-            continue;
-        }
-        if (token.startsWith("--run-id=")) {
-            const value = token.slice("--run-id=".length).trim();
-            if (value) {
-                args.runId = value;
-            }
-            continue;
-        }
-        throw new Error(`Unknown flag for tdd-red-evidence: ${token}`);
-    }
-    if (!args.targetPath) {
-        throw new Error("Missing required flag: --path=<production-file-path>");
-    }
-    return args;
-}
-function parseAutoEvidence(text) {
-    const out = [];
-    for (const rawLine of text.split(/\r?\n/gu)) {
-        const line = rawLine.trim();
-        if (!line)
-            continue;
-        try {
-            const parsed = JSON.parse(line);
-            const exitCode = parsed.exitCode;
-            if (typeof exitCode !== "number" || exitCode === 0)
-                continue;
-            const runId = typeof parsed.runId === "string" && parsed.runId.length > 0
-                ? parsed.runId
-                : "active";
-            const rawPaths = Array.isArray(parsed.paths)
-                ? parsed.paths
-                : typeof parsed.path === "string"
-                    ? [parsed.path]
-                    : [];
-            const paths = rawPaths
-                .filter((value) => typeof value === "string")
-                .map((value) => value.trim())
-                .filter((value) => value.length > 0);
-            if (paths.length === 0)
-                continue;
-            out.push({
-                runId,
-                exitCode,
-                paths
-            });
-        }
-        catch {
-            // ignore malformed lines
-        }
-    }
-    return out;
-}
-function hasFailingAutoEvidenceForPath(entries, targetPath, options = {}) {
-    for (const entry of entries) {
-        if (options.runId && entry.runId !== options.runId)
-            continue;
-        for (const filePath of entry.paths) {
-            if (pathMatchesTarget(filePath, targetPath))
-                return true;
-        }
-    }
-    return false;
-}
-export async function runTddRedEvidenceCommand(projectRoot, tokens, io) {
-    const args = parseArgs(tokens);
-    const flowState = await readFlowState(projectRoot).catch(() => null);
-    // Strict runId scoping: a previous implementation fell back to no
-    // filter when both `--runId` and `flowState.activeRunId` were missing,
-    // which let evidence rows from past runs satisfy the current check
-    // (false positive). Now: require an explicit or inferred runId or
-    // fail loud so the caller cannot silently inherit cross-run state.
-    const effectiveRunId = args.runId ?? flowState?.activeRunId;
-    if (!effectiveRunId || effectiveRunId.trim().length === 0) {
-        const reason = "tdd-red-evidence: cannot scope check — no --runId provided and " +
-            "flow-state.json has no activeRunId. Pass --runId=<id> explicitly " +
-            "or run `npx cclaw-cli sync` to reconcile state.";
-        if (!args.quiet) {
-            io.stdout.write(`${JSON.stringify({
-                ok: false,
-                path: args.targetPath,
-                runId: null,
-                error: reason,
-                sources: { tddCycleLog: false, autoEvidence: false }
-            }, null, 2)}\n`);
-        }
-        else {
-            io.stderr.write(`${reason}\n`);
-        }
-        return 2;
-    }
-    const tddLogPath = path.join(projectRoot, RUNTIME_ROOT, "state", "tdd-cycle-log.jsonl");
-    const autoEvidencePath = path.join(projectRoot, RUNTIME_ROOT, "state", "tdd-red-evidence.jsonl");
-    let cycleLogHasRed = false;
-    let autoEvidenceHasRed = false;
-    try {
-        const raw = await fs.readFile(tddLogPath, "utf8");
-        // Strict parse: drop malformed/underspecified rows rather than
-        // backfilling runId=active / stage=tdd defaults, which used to
-        // silently glue foreign entries to the current run.
-        const entries = parseTddCycleLog(raw, { strict: true });
-        cycleLogHasRed = hasFailingTestForPath(entries, args.targetPath, {
-            runId: effectiveRunId
-        });
-    }
-    catch {
-        cycleLogHasRed = false;
-    }
-    try {
-        const raw = await fs.readFile(autoEvidencePath, "utf8");
-        const entries = parseAutoEvidence(raw);
-        autoEvidenceHasRed = hasFailingAutoEvidenceForPath(entries, args.targetPath, {
-            runId: effectiveRunId
-        });
-    }
-    catch {
-        autoEvidenceHasRed = false;
-    }
-    const hasRed = cycleLogHasRed || autoEvidenceHasRed;
-    if (!args.quiet) {
-        io.stdout.write(`${JSON.stringify({
-            ok: hasRed,
-            path: args.targetPath,
-            runId: effectiveRunId,
-            sources: {
-                tddCycleLog: cycleLogHasRed,
-                autoEvidence: autoEvidenceHasRed
-            }
-        }, null, 2)}\n`);
-    }
-    return hasRed ? 0 : 2;
-}

package/dist/internal/waiver-grant.d.ts

@@ -1,62 +0,0 @@
-import { type FlowStage } from "../types.js";
-import type { Writable } from "node:stream";
-interface InternalIo {
-    stdout: Writable;
-    stderr: Writable;
-}
-export declare const WAIVER_TOKEN_DEFAULT_TTL_MINUTES = 30;
-export declare const WAIVER_TOKEN_MAX_TTL_MINUTES = 120;
-export declare const WAIVER_REASON_PATTERN: RegExp;
-export interface WaiverRecord {
-    token: string;
-    stage: FlowStage;
-    reason: string;
-    issuedAt: string;
-    expiresAt: string;
-    consumedAt: string | null;
-    issuerSubsystem: string;
-    consumedBy?: string;
-}
-export interface WaiverLedger {
-    schemaVersion: number;
-    pending: WaiverRecord[];
-    consumed: WaiverRecord[];
-}
-export interface IssueWaiverTokenOptions {
-    stage: FlowStage;
-    reason: string;
-    expiresInMinutes?: number;
-    issuerSubsystem?: string;
-    now?: Date;
-}
-export interface ConsumeWaiverOptions {
-    stage: FlowStage;
-    token: string;
-    consumedBy?: string;
-    now?: Date;
-}
-export declare function formatWaiverToken(stage: FlowStage, fingerprint: string, expiresAt: Date): string;
-export declare function issueWaiverToken(projectRoot: string, options: IssueWaiverTokenOptions): Promise<WaiverRecord>;
-export type ConsumeWaiverFailureReason = "not-found" | "wrong-stage" | "expired" | "already-consumed";
-export interface ConsumeWaiverSuccess {
-    ok: true;
-    record: WaiverRecord;
-}
-export interface ConsumeWaiverFailure {
-    ok: false;
-    reason: ConsumeWaiverFailureReason;
-    record?: WaiverRecord;
-    detail: string;
-}
-export type ConsumeWaiverResult = ConsumeWaiverSuccess | ConsumeWaiverFailure;
-export declare function consumeWaiverToken(projectRoot: string, options: ConsumeWaiverOptions): Promise<ConsumeWaiverResult>;
-export interface WaiverGrantArgs {
-    stage: FlowStage;
-    reason: string;
-    ttlMinutes: number;
-    json: boolean;
-    quiet: boolean;
-}
-export declare function parseWaiverGrantArgs(tokens: string[]): WaiverGrantArgs;
-export declare function runWaiverGrant(projectRoot: string, args: WaiverGrantArgs, io: InternalIo): Promise<number>;
-export {};

package/dist/internal/waiver-grant.js

@@ -1,294 +0,0 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { RUNTIME_ROOT } from "../constants.js";
-import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "../fs-utils.js";
-import { FLOW_STAGES } from "../types.js";
-/**
- * Tokens issued by `cclaw internal waiver-grant` live under the runtime
- * root. The ledger also tracks `consumed[]` entries so consumption is
- * traceable and one-shot.
- */
-const WAIVER_LEDGER_REL_PATH = `${RUNTIME_ROOT}/.waivers.json`;
-const WAIVER_LEDGER_LOCK_REL_PATH = `${RUNTIME_ROOT}/.waivers.json.lock`;
-export const WAIVER_TOKEN_DEFAULT_TTL_MINUTES = 30;
-export const WAIVER_TOKEN_MAX_TTL_MINUTES = 120;
-export const WAIVER_REASON_PATTERN = /^[a-z][a-z0-9_-]{2,}$/u;
-const WAIVER_TOKEN_PREFIX = "WV";
-const WAIVER_LEDGER_SCHEMA_VERSION = 1;
-function waiverLedgerPath(projectRoot) {
-    return path.join(projectRoot, WAIVER_LEDGER_REL_PATH);
-}
-function waiverLedgerLockPath(projectRoot) {
-    return path.join(projectRoot, WAIVER_LEDGER_LOCK_REL_PATH);
-}
-function sanitizeWaiverRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    const row = value;
-    const token = typeof row.token === "string" ? row.token : "";
-    const stage = row.stage;
-    const reason = typeof row.reason === "string" ? row.reason : "";
-    const issuedAt = typeof row.issuedAt === "string" ? row.issuedAt : "";
-    const expiresAt = typeof row.expiresAt === "string" ? row.expiresAt : "";
-    const consumedAt = typeof row.consumedAt === "string" ? row.consumedAt : null;
-    const issuerSubsystem = typeof row.issuerSubsystem === "string" ? row.issuerSubsystem : "";
-    const consumedBy = typeof row.consumedBy === "string" ? row.consumedBy : undefined;
-    if (token.length === 0 ||
-        typeof stage !== "string" ||
-        !FLOW_STAGES.includes(stage) ||
-        reason.length === 0 ||
-        issuedAt.length === 0 ||
-        expiresAt.length === 0 ||
-        issuerSubsystem.length === 0) {
-        return null;
-    }
-    return {
-        token,
-        stage: stage,
-        reason,
-        issuedAt,
-        expiresAt,
-        consumedAt,
-        issuerSubsystem,
-        ...(consumedBy ? { consumedBy } : {})
-    };
-}
-async function readWaiverLedger(projectRoot) {
-    const statePath = waiverLedgerPath(projectRoot);
-    if (!(await exists(statePath))) {
-        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
-    }
-    let raw;
-    try {
-        raw = await fs.readFile(statePath, "utf8");
-    }
-    catch {
-        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
-    }
-    const typed = parsed;
-    const pending = Array.isArray(typed.pending)
-        ? typed.pending
-            .map((item) => sanitizeWaiverRecord(item))
-            .filter((item) => item !== null)
-        : [];
-    const consumed = Array.isArray(typed.consumed)
-        ? typed.consumed
-            .map((item) => sanitizeWaiverRecord(item))
-            .filter((item) => item !== null)
-        : [];
-    return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending, consumed };
-}
-async function writeWaiverLedger(projectRoot, ledger) {
-    const next = {
-        schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION,
-        pending: ledger.pending,
-        consumed: ledger.consumed
-    };
-    await writeFileSafe(waiverLedgerPath(projectRoot), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
-}
-function formatExpiresSlug(expiresAt) {
-    // Minute-precision slug for the token: e.g. `20260502T220500Z`
-    return expiresAt.toISOString().replace(/[-:]/gu, "").replace(/\..+$/u, "").concat("Z");
-}
-function minuteFingerprint(stage, reason, issuedAt) {
-    const payload = `${stage}|${reason}|${issuedAt.toISOString()}|${Math.random().toString(16).slice(2, 12)}`;
-    return createHash("sha256").update(payload, "utf8").digest("hex").slice(0, 8);
-}
-export function formatWaiverToken(stage, fingerprint, expiresAt) {
-    return `${WAIVER_TOKEN_PREFIX}-${stage}-${fingerprint}-${formatExpiresSlug(expiresAt)}`;
-}
-export async function issueWaiverToken(projectRoot, options) {
-    if (!FLOW_STAGES.includes(options.stage)) {
-        throw new Error(`waiver-grant: --stage must be one of ${FLOW_STAGES.join(", ")}.`);
-    }
-    const reason = options.reason.trim();
-    if (reason.length === 0) {
-        throw new Error("waiver-grant: --reason is required.");
-    }
-    if (!WAIVER_REASON_PATTERN.test(reason)) {
-        throw new Error("waiver-grant: --reason must match /^[a-z][a-z0-9_-]{2,}$/ (short lowercase slug, e.g. architect_unavailable).");
-    }
-    const ttlRaw = typeof options.expiresInMinutes === "number" && Number.isFinite(options.expiresInMinutes)
-        ? Math.floor(options.expiresInMinutes)
-        : WAIVER_TOKEN_DEFAULT_TTL_MINUTES;
-    if (ttlRaw < 1) {
-        throw new Error("waiver-grant: --ttl must be >= 1 minute.");
-    }
-    if (ttlRaw > WAIVER_TOKEN_MAX_TTL_MINUTES) {
-        throw new Error(`waiver-grant: --ttl must be <= ${WAIVER_TOKEN_MAX_TTL_MINUTES} minutes.`);
-    }
-    const issuedAtDate = options.now ?? new Date();
-    const expiresAtDate = new Date(issuedAtDate.getTime() + ttlRaw * 60 * 1000);
-    const fingerprint = minuteFingerprint(options.stage, reason, issuedAtDate);
-    const token = formatWaiverToken(options.stage, fingerprint, expiresAtDate);
-    const record = {
-        token,
-        stage: options.stage,
-        reason,
-        issuedAt: issuedAtDate.toISOString(),
-        expiresAt: expiresAtDate.toISOString(),
-        consumedAt: null,
-        issuerSubsystem: options.issuerSubsystem?.trim() || "cli"
-    };
-    await ensureDir(path.dirname(waiverLedgerPath(projectRoot)));
-    await withDirectoryLock(waiverLedgerLockPath(projectRoot), async () => {
-        const ledger = await readWaiverLedger(projectRoot);
-        ledger.pending.push(record);
-        await writeWaiverLedger(projectRoot, ledger);
-    });
-    return record;
-}
-export async function consumeWaiverToken(projectRoot, options) {
-    const token = options.token.trim();
-    if (token.length === 0) {
-        return {
-            ok: false,
-            reason: "not-found",
-            detail: "waiver token is required"
-        };
-    }
-    const now = (options.now ?? new Date()).getTime();
-    return withDirectoryLock(waiverLedgerLockPath(projectRoot), async () => {
-        const ledger = await readWaiverLedger(projectRoot);
-        const pendingIdx = ledger.pending.findIndex((entry) => entry.token === token);
-        const consumedMatch = ledger.consumed.find((entry) => entry.token === token);
-        if (pendingIdx < 0) {
-            if (consumedMatch) {
-                return {
-                    ok: false,
-                    reason: "already-consumed",
-                    record: consumedMatch,
-                    detail: `waiver token ${token} was already consumed at ${consumedMatch.consumedAt ?? "unknown time"}`
-                };
-            }
-            return {
-                ok: false,
-                reason: "not-found",
-                detail: `no pending waiver token "${token}" found in ${WAIVER_LEDGER_REL_PATH}`
-            };
-        }
-        const record = ledger.pending[pendingIdx];
-        if (record.stage !== options.stage) {
-            return {
-                ok: false,
-                reason: "wrong-stage",
-                record,
-                detail: `waiver token ${token} was issued for stage "${record.stage}", not "${options.stage}"`
-            };
-        }
-        const expiresAt = Date.parse(record.expiresAt);
-        if (Number.isFinite(expiresAt) && expiresAt < now) {
-            return {
-                ok: false,
-                reason: "expired",
-                record,
-                detail: `waiver token ${token} expired at ${record.expiresAt}`
-            };
-        }
-        const consumedAtIso = (options.now ?? new Date()).toISOString();
-        const consumedRecord = {
-            ...record,
-            consumedAt: consumedAtIso,
-            ...(options.consumedBy ? { consumedBy: options.consumedBy } : {})
-        };
-        ledger.pending.splice(pendingIdx, 1);
-        ledger.consumed.push(consumedRecord);
-        await writeWaiverLedger(projectRoot, ledger);
-        return { ok: true, record: consumedRecord };
-    });
-}
-export function parseWaiverGrantArgs(tokens) {
-    let stage;
-    let reason;
-    let ttlMinutes = WAIVER_TOKEN_DEFAULT_TTL_MINUTES;
-    let json = false;
-    let quiet = false;
-    for (let i = 0; i < tokens.length; i += 1) {
-        const token = tokens[i];
-        const nextToken = tokens[i + 1];
-        const readValue = (flag) => {
-            if (token.startsWith(`${flag}=`))
-                return token.slice(flag.length + 1);
-            if (token === flag && nextToken && !nextToken.startsWith("--")) {
-                i += 1;
-                return nextToken;
-            }
-            throw new Error(`${flag} requires a value.`);
-        };
-        if (token === "--json") {
-            json = true;
-            continue;
-        }
-        if (token === "--quiet") {
-            quiet = true;
-            continue;
-        }
-        if (token === "--stage" || token.startsWith("--stage=")) {
-            const raw = readValue("--stage").trim();
-            if (!FLOW_STAGES.includes(raw)) {
-                throw new Error(`waiver-grant: --stage must be one of ${FLOW_STAGES.join(", ")}.`);
-            }
-            stage = raw;
-            continue;
-        }
-        if (token === "--reason" || token.startsWith("--reason=")) {
-            reason = readValue("--reason").trim();
-            continue;
-        }
-        if (token === "--ttl" || token.startsWith("--ttl=")) {
-            const raw = readValue("--ttl").trim();
-            if (!/^[0-9]+$/u.test(raw)) {
-                throw new Error("waiver-grant: --ttl must be an integer number of minutes.");
-            }
-            ttlMinutes = Number(raw);
-            continue;
-        }
-        throw new Error(`Unknown flag for internal waiver-grant: ${token}`);
-    }
-    if (!stage) {
-        throw new Error(`internal waiver-grant requires --stage=<${FLOW_STAGES.join("|")}>.`);
-    }
-    if (!reason) {
-        throw new Error(`internal waiver-grant requires --reason=<short-slug> (e.g. architect_unavailable).`);
-    }
-    return { stage, reason, ttlMinutes, json, quiet };
-}
-export async function runWaiverGrant(projectRoot, args, io) {
-    const record = await issueWaiverToken(projectRoot, {
-        stage: args.stage,
-        reason: args.reason,
-        expiresInMinutes: args.ttlMinutes,
-        issuerSubsystem: "cli"
-    });
-    if (args.json) {
-        io.stdout.write(`${JSON.stringify({
-            ok: true,
-            command: "waiver-grant",
-            token: record.token,
-            stage: record.stage,
-            reason: record.reason,
-            issuedAt: record.issuedAt,
-            expiresAt: record.expiresAt,
-            ttlMinutes: args.ttlMinutes,
-            consumption: `cclaw-cli internal advance-stage ${record.stage} --accept-proactive-waiver=${record.token} --accept-proactive-waiver-reason="${record.reason}"`
-        })}\n`);
-        return 0;
-    }
-    io.stdout.write(`${record.token}\n`);
-    if (!args.quiet) {
-        io.stdout.write(`Waiver token issued for stage="${record.stage}" reason="${record.reason}" expires=${record.expiresAt}.\n`);
-        io.stdout.write(`Consume with: node ${RUNTIME_ROOT}/hooks/stage-complete.mjs ${record.stage} --accept-proactive-waiver=${record.token} --accept-proactive-waiver-reason="${record.reason}"\n`);
-    }
-    return 0;
-}

package/dist/internal/wave-status.d.ts

@@ -1,74 +0,0 @@
-import type { Writable } from "node:stream";
-import type { ExecutionTopology } from "../types.js";
-interface InternalIo {
-    stdout: Writable;
-    stderr: Writable;
-}
-export interface WaveStatusWaveSummary {
-    waveId: string;
-    members: string[];
-    closedMembers: string[];
-    openMembers: string[];
-    readyMembers: string[];
-    blockedMembers: string[];
-    status: "closed" | "open" | "partial" | "empty";
-}
-/**
- * 7.7.1 — `controller-inline` is added so the controller knows it must
- * fulfil the ready slices in this turn (no slice-builder dispatch). The
- * remaining values (`single-slice`, `wave-fanout`, `blocked`, `none`) keep
- * their pre-7.7.1 contract.
- */
-export interface WaveStatusNextDispatch {
-    waveId: string | null;
-    readyToDispatch: string[];
-    pathConflicts: string[];
-    mode: "single-slice" | "wave-fanout" | "blocked" | "none" | "controller-inline";
-    topology: Exclude<ExecutionTopology, "auto"> | "none";
-    topologyReason: string;
-    maxBuilders: number;
-    /**
-     * Optional natural-language hint for the controller, populated when the
-     * router selects a non-default mode (currently only `inline`).
-     */
-    controllerHint?: string;
-}
-export interface WaveStatusReport {
-    activeRunId: string;
-    currentStage: string;
-    waves: WaveStatusWaveSummary[];
-    nextDispatch: WaveStatusNextDispatch;
-    warnings: string[];
-}
-export interface RunWaveStatusOptions {
-    /**
-     * Override the artifacts directory; useful for fixture tests that
-     * place an `05-plan.md` outside `.cclaw/artifacts`. Defaults to
-     * `<projectRoot>/.cclaw/artifacts`.
-     */
-    artifactsDir?: string;
-    /**
-     * Event ingestion mode:
-     * - auto: prefer live stream file; fallback to delegation-events.jsonl.
-     * - live: force live stream first; fallback to delegation-events.jsonl with warning.
-     * - file: skip stream file and use delegation-events.jsonl only.
-     */
-    streamMode?: "auto" | "live" | "file";
-    /**
-     * Optional absolute stream path override (tests).
-     */
-    streamPath?: string;
-}
-/**
- * Deterministic helper for the TDD controller. Reads the managed
- * `<!-- parallel-exec-managed-start -->` block from
- * `<artifacts-dir>/05-plan.md` plus the `wave-plans/` directory and
- * reports waves + the next dispatchable members so the controller does
- * NOT have to page through a long plan to find the active wave.
- *
- * Always exits 0 unless the plan is malformed (no managed block AND no
- * wave-plans directory), in which case exit 2 with a structured error.
- */
-export declare function runWaveStatus(projectRoot: string, options?: RunWaveStatusOptions): Promise<WaveStatusReport>;
-export declare function runWaveStatusCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
-export {};