cclaw-cli 0.51.29 → 0.55.2

package/dist/internal/advance-stage/helpers.js

@@ -0,0 +1,145 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FLOW_STAGES } from "../../types.js";
+export function unique(values) {
+    return [...new Set(values)];
+}
+export function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+export function parseStringList(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+export function isFlowStageValue(value) {
+    return typeof value === "string" && FLOW_STAGES.includes(value);
+}
+export function parseGuardEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const next = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw !== "string")
+            continue;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        next[key] = trimmed;
+    }
+    return next;
+}
+export function emptyGateState() {
+    return {
+        required: [],
+        recommended: [],
+        conditional: [],
+        triggered: [],
+        passed: [],
+        blocked: []
+    };
+}
+export function stringifyGateEvidenceValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean")
+        return value ? "passed" : "failed";
+    if (typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+export function parseEvidenceByGate(raw) {
+    if (!raw || raw.trim().length === 0) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--evidence-json must be valid JSON object: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("--evidence-json must deserialize to an object.");
+    }
+    const next = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        const normalized = stringifyGateEvidenceValue(value).trim();
+        if (normalized.length === 0)
+            continue;
+        next[key] = normalized;
+    }
+    return next;
+}
+export function parseCsv(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+export async function pathExists(projectRoot, relPath) {
+    try {
+        await fs.stat(path.join(projectRoot, relPath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listExistingFiles(projectRoot, relPaths) {
+    const matches = [];
+    for (const relPath of relPaths) {
+        try {
+            const stat = await fs.stat(path.join(projectRoot, relPath));
+            if (stat.isFile())
+                matches.push(relPath);
+        }
+        catch {
+            // continue
+        }
+    }
+    return matches;
+}
+export async function listFilesUnder(projectRoot, relDir, limit = 20) {
+    const root = path.join(projectRoot, relDir);
+    const out = [];
+    async function walk(absDir) {
+        if (out.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= limit)
+                return;
+            if (entry.name.startsWith("."))
+                continue;
+            const abs = path.join(absDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(abs);
+            }
+            else if (entry.isFile()) {
+                out.push(path.relative(projectRoot, abs).split(path.sep).join("/"));
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}

package/dist/internal/advance-stage/hook.d.ts

@@ -0,0 +1,8 @@
+import type { HookArgs } from "./parsers.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runHookCommand(projectRoot: string, args: HookArgs, io: InternalIo): Promise<number>;
+export {};

package/dist/internal/advance-stage/hook.js

@@ -0,0 +1,40 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { RUNTIME_ROOT } from "../../constants.js";
+export async function runHookCommand(projectRoot, args, io) {
+    const runHookPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", "run-hook.mjs");
+    try {
+        await fs.access(runHookPath);
+    }
+    catch {
+        io.stderr.write(`cclaw internal hook: missing hook runtime at ${runHookPath}. Run \`cclaw sync\` first.\n`);
+        return 1;
+    }
+    return await new Promise((resolve) => {
+        const child = spawn(process.execPath, [runHookPath, args.hookName], {
+            cwd: projectRoot,
+            env: process.env,
+            stdio: ["inherit", "pipe", "pipe"]
+        });
+        child.stdout.on("data", (chunk) => {
+            io.stdout.write(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            io.stderr.write(chunk);
+        });
+        child.on("error", (err) => {
+            io.stderr.write(`cclaw internal hook: failed to launch runtime (${err instanceof Error ? err.message : String(err)}).\n`);
+            resolve(1);
+        });
+        child.on("close", (code, signal) => {
+            if (signal) {
+                io.stderr.write(`cclaw internal hook: runtime terminated by signal ${signal}.\n`);
+                resolve(1);
+                return;
+            }
+            resolve(typeof code === "number" ? code : 1);
+        });
+    });
+}

package/dist/internal/advance-stage/parsers.d.ts

@@ -0,0 +1,54 @@
+import { type FlowStage, type FlowTrack } from "../../types.js";
+import type { ArchiveDisposition } from "../../runs.js";
+export interface AdvanceStageArgs {
+    stage: FlowStage;
+    passedGateIds: string[];
+    evidenceByGate: Record<string, string>;
+    waiveDelegations: string[];
+    waiverReason?: string;
+    acceptProactiveWaiver: boolean;
+    acceptProactiveWaiverReason?: string;
+    quiet: boolean;
+    json: boolean;
+}
+export interface VerifyFlowStateDiffArgs {
+    afterJson?: string;
+    afterFile?: string;
+    quiet: boolean;
+}
+export interface VerifyCurrentStateArgs {
+    quiet: boolean;
+}
+export interface HookArgs {
+    hookName: string;
+}
+export interface RewindArgs {
+    mode: "rewind" | "ack";
+    targetStage: FlowStage;
+    reason?: string;
+    quiet: boolean;
+    json: boolean;
+}
+export interface StartFlowArgs {
+    track: FlowTrack;
+    className?: string;
+    prompt?: string;
+    reason?: string;
+    stack?: string;
+    forceReset: boolean;
+    reclassify: boolean;
+    quiet: boolean;
+}
+export interface CancelRunArgs {
+    reason: string;
+    disposition: Extract<ArchiveDisposition, "cancelled" | "abandoned">;
+    name?: string;
+    quiet: boolean;
+}
+export declare function parseAdvanceStageArgs(tokens: string[]): AdvanceStageArgs;
+export declare function parseVerifyFlowStateDiffArgs(tokens: string[]): VerifyFlowStateDiffArgs;
+export declare function parseVerifyCurrentStateArgs(tokens: string[]): VerifyCurrentStateArgs;
+export declare function parseRewindArgs(tokens: string[]): RewindArgs;
+export declare function parseHookArgs(tokens: string[]): HookArgs;
+export declare function parseStartFlowArgs(tokens: string[]): StartFlowArgs;
+export declare function parseCancelRunArgs(tokens: string[]): CancelRunArgs;

package/dist/internal/advance-stage/parsers.js

@@ -0,0 +1,307 @@
+import { FLOW_STAGES } from "../../types.js";
+import { isFlowTrack } from "../../flow-state.js";
+import { isFlowStageValue, parseCsv, parseEvidenceByGate, unique } from "./helpers.js";
+export function parseAdvanceStageArgs(tokens) {
+    const [stageRaw, ...flagTokens] = tokens;
+    if (!isFlowStageValue(stageRaw)) {
+        throw new Error(`internal advance-stage requires a stage positional argument (${FLOW_STAGES.join(", ")}).`);
+    }
+    let evidenceJson;
+    let passed = [];
+    let waiveDelegations = [];
+    let waiverReason;
+    let acceptProactiveWaiver = false;
+    let acceptProactiveWaiverReason;
+    let quiet = false;
+    let json = false;
+    for (let i = 0; i < flagTokens.length; i += 1) {
+        const token = flagTokens[i];
+        const nextToken = flagTokens[i + 1];
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--evidence-json") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--evidence-json requires a JSON object value.");
+            }
+            evidenceJson = nextToken;
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--evidence-json=")) {
+            evidenceJson = token.slice("--evidence-json=".length);
+            continue;
+        }
+        if (token === "--passed") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--passed requires a comma-separated gate list.");
+            }
+            passed = [...passed, ...parseCsv(nextToken)];
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--passed=")) {
+            passed = [...passed, ...parseCsv(token.slice("--passed=".length))];
+            continue;
+        }
+        if (token === "--waive-delegation") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--waive-delegation requires a comma-separated agent list.");
+            }
+            waiveDelegations = [...waiveDelegations, ...parseCsv(nextToken)];
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--waive-delegation=")) {
+            waiveDelegations = [
+                ...waiveDelegations,
+                ...parseCsv(token.slice("--waive-delegation=".length))
+            ];
+            continue;
+        }
+        if (token === "--waiver-reason") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--waiver-reason requires a text value.");
+            }
+            waiverReason = nextToken.trim();
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--waiver-reason=")) {
+            waiverReason = token.slice("--waiver-reason=".length).trim();
+            continue;
+        }
+        if (token === "--accept-proactive-waiver") {
+            acceptProactiveWaiver = true;
+            continue;
+        }
+        if (token === "--accept-proactive-waiver-reason") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--accept-proactive-waiver-reason requires a text value.");
+            }
+            acceptProactiveWaiverReason = nextToken.trim();
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--accept-proactive-waiver-reason=")) {
+            acceptProactiveWaiverReason = token.slice("--accept-proactive-waiver-reason=".length).trim();
+            continue;
+        }
+        throw new Error(`Unknown flag for internal advance-stage: ${token}`);
+    }
+    return {
+        stage: stageRaw,
+        passedGateIds: unique(passed),
+        evidenceByGate: parseEvidenceByGate(evidenceJson),
+        waiveDelegations: unique(waiveDelegations),
+        waiverReason,
+        acceptProactiveWaiver,
+        acceptProactiveWaiverReason,
+        quiet,
+        json
+    };
+}
+export function parseVerifyFlowStateDiffArgs(tokens) {
+    let afterJson;
+    let afterFile;
+    let quiet = false;
+    for (const token of tokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token.startsWith("--after-json=")) {
+            afterJson = token.replace("--after-json=", "");
+            continue;
+        }
+        if (token.startsWith("--after-file=")) {
+            afterFile = token.replace("--after-file=", "");
+            continue;
+        }
+        throw new Error(`Unknown flag for internal verify-flow-state-diff: ${token}`);
+    }
+    if (!afterJson && !afterFile) {
+        throw new Error("internal verify-flow-state-diff requires --after-json=<json> or --after-file=<path>.");
+    }
+    return { afterJson, afterFile, quiet };
+}
+export function parseVerifyCurrentStateArgs(tokens) {
+    let quiet = false;
+    for (const token of tokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        throw new Error(`Unknown flag for internal verify-current-state: ${token}`);
+    }
+    return { quiet };
+}
+export function parseRewindArgs(tokens) {
+    let quiet = false;
+    let json = false;
+    const positional = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const nextToken = tokens[i + 1];
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if (token === "--ack") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--ack requires a stage value.");
+            }
+            if (!isFlowStageValue(nextToken)) {
+                throw new Error(`--ack stage must be one of: ${FLOW_STAGES.join(", ")}.`);
+            }
+            i += 1;
+            return { mode: "ack", targetStage: nextToken, quiet, json };
+        }
+        if (token.startsWith("--ack=")) {
+            const stage = token.slice("--ack=".length);
+            if (!isFlowStageValue(stage)) {
+                throw new Error(`--ack stage must be one of: ${FLOW_STAGES.join(", ")}.`);
+            }
+            return { mode: "ack", targetStage: stage, quiet, json };
+        }
+        positional.push(token);
+    }
+    const [targetStage, ...reasonParts] = positional;
+    if (!isFlowStageValue(targetStage)) {
+        throw new Error(`internal rewind requires a target stage (${FLOW_STAGES.join(", ")}) or --ack <stage>.`);
+    }
+    const reason = reasonParts.join(" ").trim();
+    if (reason.length === 0) {
+        throw new Error('internal rewind requires a reason, for example: cclaw internal rewind tdd "review_blocked_by_critical".');
+    }
+    return { mode: "rewind", targetStage, reason, quiet, json };
+}
+export function parseHookArgs(tokens) {
+    const [hookName, ...rest] = tokens;
+    const normalizedHook = typeof hookName === "string" ? hookName.trim() : "";
+    if (normalizedHook.length === 0) {
+        throw new Error("internal hook requires a hook name: cclaw internal hook <name>.");
+    }
+    if (rest.length > 0) {
+        throw new Error(`Unknown arguments for internal hook: ${rest.join(" ")}`);
+    }
+    return { hookName: normalizedHook };
+}
+export function parseStartFlowArgs(tokens) {
+    let track;
+    let className;
+    let prompt;
+    let reason;
+    let stack;
+    let forceReset = false;
+    let reclassify = 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 === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--force-reset") {
+            forceReset = true;
+            continue;
+        }
+        if (token === "--reclassify") {
+            reclassify = true;
+            continue;
+        }
+        if (token === "--track" || token.startsWith("--track=")) {
+            const raw = readValue("--track").trim();
+            if (!isFlowTrack(raw)) {
+                throw new Error(`--track must be one of: standard, medium, quick.`);
+            }
+            track = raw;
+            continue;
+        }
+        if (token === "--class" || token.startsWith("--class=")) {
+            className = readValue("--class").trim();
+            continue;
+        }
+        if (token === "--prompt" || token.startsWith("--prompt=")) {
+            prompt = readValue("--prompt").trim();
+            continue;
+        }
+        if (token === "--reason" || token.startsWith("--reason=")) {
+            reason = readValue("--reason").trim();
+            continue;
+        }
+        if (token === "--stack" || token.startsWith("--stack=")) {
+            stack = readValue("--stack").trim();
+            continue;
+        }
+        throw new Error(`Unknown flag for internal start-flow: ${token}`);
+    }
+    if (!track) {
+        throw new Error("internal start-flow requires --track=<standard|medium|quick>.");
+    }
+    return { track, className, prompt, reason, stack, forceReset, reclassify, quiet };
+}
+export function parseCancelRunArgs(tokens) {
+    let reason;
+    let disposition = "cancelled";
+    let name;
+    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 === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--reason" || token.startsWith("--reason=")) {
+            reason = readValue("--reason").trim();
+            continue;
+        }
+        if (token === "--name" || token.startsWith("--name=")) {
+            const raw = readValue("--name").trim();
+            name = raw.length > 0 ? raw : undefined;
+            continue;
+        }
+        if (token === "--disposition" || token.startsWith("--disposition=")) {
+            const raw = readValue("--disposition").trim();
+            if (raw !== "cancelled" && raw !== "abandoned") {
+                throw new Error("--disposition must be cancelled or abandoned.");
+            }
+            disposition = raw;
+            continue;
+        }
+        throw new Error(`Unknown flag for internal cancel-run: ${token}`);
+    }
+    if (!reason || reason.length === 0) {
+        throw new Error("internal cancel-run requires --reason=<text>.");
+    }
+    return { reason, disposition, name, quiet };
+}

package/dist/internal/advance-stage/review-loop.d.ts

@@ -0,0 +1,7 @@
+import type { FlowStage } from "../../types.js";
+export declare const AUTO_REVIEW_LOOP_GATE_BY_STAGE: Partial<Record<FlowStage, string>>;
+export declare function pickReviewLoopEnvelope(value: unknown): Record<string, unknown> | null;
+export declare function validateReviewLoopGateEvidence(stage: "scope" | "design", evidence: string): string | null;
+export declare function validateUserApprovalEvidence(evidence: string): string | null;
+export declare function validateGateEvidenceShape(projectRoot: string, stage: FlowStage, gateId: string, evidence: string): Promise<string | null>;
+export declare function reviewLoopArtifactFixHint(stage: FlowStage, gateId: string): string;