cclaw-cli 0.1.0

package/dist/runs.js

@@ -0,0 +1,446 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { ARTIFACT_TEMPLATES } from "./content/templates.js";
+import { createInitialFlowState } from "./flow-state.js";
+import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+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 RUN_META_FILE = "run.json";
+const RUN_HANDOFF_FILE = "00-handoff.md";
+const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
+function flowStatePath(projectRoot) {
+    return path.join(projectRoot, FLOW_STATE_REL_PATH);
+}
+function runsRoot(projectRoot) {
+    return path.join(projectRoot, RUNS_DIR_REL_PATH);
+}
+function activeArtifactsPath(projectRoot) {
+    return path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH);
+}
+function runRoot(projectRoot, runId) {
+    return path.join(runsRoot(projectRoot), requireSafeRunId(runId));
+}
+function runArtifactsPath(projectRoot, runId) {
+    return path.join(runRoot(projectRoot, runId), "artifacts");
+}
+function runMetaPath(projectRoot, runId) {
+    return path.join(runRoot(projectRoot, runId), RUN_META_FILE);
+}
+function runHandoffPath(projectRoot, runId) {
+    return path.join(runRoot(projectRoot, runId), RUN_HANDOFF_FILE);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function pad2(value) {
+    return value.toString().padStart(2, "0");
+}
+function buildRunId(date = new Date()) {
+    const yyyy = date.getUTCFullYear();
+    const mm = pad2(date.getUTCMonth() + 1);
+    const dd = pad2(date.getUTCDate());
+    const hh = pad2(date.getUTCHours());
+    const min = pad2(date.getUTCMinutes());
+    const ss = pad2(date.getUTCSeconds());
+    const random = Math.random().toString(36).slice(2, 6);
+    return `run-${yyyy}${mm}${dd}-${hh}${min}${ss}-${random}`;
+}
+function normalizeTitle(title) {
+    const trimmed = (title ?? "").trim();
+    if (trimmed.length === 0) {
+        return "New feature run";
+    }
+    return trimmed;
+}
+function isSafeRunId(value) {
+    return /^[A-Za-z0-9_-]{1,128}$/u.test(value);
+}
+function sanitizeRunId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return isSafeRunId(trimmed) ? trimmed : undefined;
+}
+function requireSafeRunId(runId) {
+    const safe = sanitizeRunId(runId);
+    if (!safe) {
+        throw new Error(`Invalid run id "${runId}"`);
+    }
+    return safe;
+}
+function snapshotState(state) {
+    return {
+        currentStage: state.currentStage,
+        completedStages: [...state.completedStages],
+        guardEvidence: { ...state.guardEvidence },
+        stageGateCatalog: JSON.parse(JSON.stringify(state.stageGateCatalog))
+    };
+}
+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 next = {};
+    for (const stage of COMMAND_FILE_ORDER) {
+        const base = fallback[stage];
+        next[stage] = {
+            required: [...base.required],
+            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 allowedGateIds = new Set(next[stage].required);
+        next[stage] = {
+            required: [...next[stage].required],
+            passed: sanitizeStringArray(typed.passed).filter((gate) => allowedGateIds.has(gate)),
+            blocked: sanitizeStringArray(typed.blocked).filter((gate) => allowedGateIds.has(gate))
+        };
+    }
+    return next;
+}
+function coerceFlowState(parsed, activeRunIdOverride) {
+    const overrideTrim = sanitizeRunId(activeRunIdOverride);
+    const parsedActiveRun = sanitizeRunId(parsed.activeRunId);
+    const seedRunId = overrideTrim ?? parsedActiveRun;
+    const next = createInitialFlowState(seedRunId);
+    return {
+        activeRunId: overrideTrim ?? parsedActiveRun ?? next.activeRunId,
+        currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
+        completedStages: sanitizeCompletedStages(parsed.completedStages),
+        guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
+        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog)
+    };
+}
+function createdAtFromRunId(runId) {
+    const match = /^run-(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})-[a-z0-9]+$/iu.exec(runId);
+    if (!match) {
+        return null;
+    }
+    const [, year, month, day, hour, minute, second] = match;
+    const date = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second)));
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+async function readJsonFile(filePath) {
+    if (!(await exists(filePath)))
+        return null;
+    try {
+        return JSON.parse(await fs.readFile(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function listImmediateFiles(dirPath) {
+    if (!(await exists(dirPath)))
+        return [];
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    return entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
+}
+async function clearImmediateFiles(dirPath) {
+    if (!(await exists(dirPath)))
+        return;
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isFile()) {
+            await fs.rm(path.join(dirPath, entry.name), { force: true });
+        }
+    }
+}
+async function copyImmediateFiles(fromDir, toDir) {
+    await ensureDir(toDir);
+    const fileNames = await listImmediateFiles(fromDir);
+    for (const fileName of fileNames) {
+        const sourcePath = path.join(fromDir, fileName);
+        const targetPath = path.join(toDir, fileName);
+        await fs.copyFile(sourcePath, targetPath);
+    }
+}
+function handoffMarkdown(runMeta, state) {
+    return `# Run Handoff
+
+## Run
+- ID: ${runMeta.id}
+- Title: ${runMeta.title}
+- Created: ${runMeta.createdAt}
+- Archived: ${runMeta.archivedAt ?? "active"}
+
+## Flow Snapshot
+- Active stage: ${state.currentStage}
+- Completed stages: ${state.completedStages.join(", ") || "(none)"}
+- Active run ID in flow-state: ${state.activeRunId}
+
+## Paths
+- Active artifacts: \`${RUNTIME_ROOT}/artifacts/\`
+- Canonical run artifacts: \`${RUNTIME_ROOT}/runs/${runMeta.id}/artifacts/\`
+
+## Resume
+1. Continue with the stage command for \`${state.currentStage}\`
+2. If needed, sync artifacts from \`${RUNTIME_ROOT}/runs/${runMeta.id}/artifacts/\`
+`;
+}
+export async function readFlowState(projectRoot) {
+    const statePath = flowStatePath(projectRoot);
+    const parsed = await readJsonFile(statePath);
+    if (!parsed || typeof parsed !== "object") {
+        return createInitialFlowState();
+    }
+    return coerceFlowState(parsed);
+}
+export async function writeFlowState(projectRoot, state) {
+    const safe = coerceFlowState({ ...state }, state.activeRunId);
+    await writeFileSafe(flowStatePath(projectRoot), `${JSON.stringify(safe, null, 2)}\n`);
+}
+export async function listRuns(projectRoot) {
+    const root = runsRoot(projectRoot);
+    if (!(await exists(root)))
+        return [];
+    const dirs = await fs.readdir(root, { withFileTypes: true });
+    const metas = [];
+    for (const dir of dirs) {
+        if (!dir.isDirectory())
+            continue;
+        const runId = dir.name;
+        if (!isSafeRunId(runId))
+            continue;
+        const meta = await readJsonFile(runMetaPath(projectRoot, runId));
+        if (meta && typeof meta.id === "string" && meta.id === runId) {
+            metas.push(meta);
+            continue;
+        }
+        let fallbackCreatedAt = createdAtFromRunId(runId);
+        if (!fallbackCreatedAt) {
+            try {
+                const stat = await fs.stat(path.join(root, runId));
+                fallbackCreatedAt = stat.birthtime?.toISOString?.() ?? stat.mtime.toISOString();
+            }
+            catch {
+                fallbackCreatedAt = null;
+            }
+        }
+        metas.push({
+            id: runId,
+            title: runId,
+            createdAt: fallbackCreatedAt ?? nowIso()
+        });
+    }
+    return metas.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+async function ensureRunMetadata(projectRoot, meta) {
+    await writeFileSafe(runMetaPath(projectRoot, meta.id), `${JSON.stringify(meta, null, 2)}\n`);
+}
+async function persistRunStateSnapshot(projectRoot, runId, state) {
+    const meta = await readJsonFile(runMetaPath(projectRoot, runId));
+    if (!meta)
+        return;
+    const safeState = coerceFlowState({ ...state }, state.activeRunId);
+    await ensureRunMetadata(projectRoot, {
+        ...meta,
+        stateSnapshot: snapshotState(safeState)
+    });
+}
+async function seedArtifactsFromTemplates(targetDir) {
+    await ensureDir(targetDir);
+    for (const [fileName, content] of Object.entries(ARTIFACT_TEMPLATES)) {
+        await writeFileSafe(path.join(targetDir, fileName), content);
+    }
+}
+async function syncActiveArtifactsToRun(projectRoot, runId) {
+    const fromDir = activeArtifactsPath(projectRoot);
+    const toDir = runArtifactsPath(projectRoot, runId);
+    await ensureDir(toDir);
+    await clearImmediateFiles(toDir);
+    await copyImmediateFiles(fromDir, toDir);
+}
+async function loadRunArtifactsToActive(projectRoot, runId) {
+    const fromDir = runArtifactsPath(projectRoot, runId);
+    const toDir = activeArtifactsPath(projectRoot);
+    await ensureDir(toDir);
+    await clearImmediateFiles(toDir);
+    await copyImmediateFiles(fromDir, toDir);
+}
+async function createRun(projectRoot, options) {
+    const runId = buildRunId();
+    const meta = {
+        id: runId,
+        title: normalizeTitle(options?.title),
+        createdAt: nowIso()
+    };
+    await ensureDir(runRoot(projectRoot, runId));
+    await ensureRunMetadata(projectRoot, meta);
+    const runArtifactsDir = runArtifactsPath(projectRoot, runId);
+    if (options?.seedFromActiveArtifacts && (await exists(activeArtifactsPath(projectRoot)))) {
+        await ensureDir(runArtifactsDir);
+        await copyImmediateFiles(activeArtifactsPath(projectRoot), runArtifactsDir);
+    }
+    else {
+        await seedArtifactsFromTemplates(runArtifactsDir);
+    }
+    return meta;
+}
+async function ensureRunHandoff(projectRoot, runId) {
+    const state = await readFlowState(projectRoot);
+    const meta = await readJsonFile(runMetaPath(projectRoot, runId));
+    if (!meta)
+        return;
+    await writeFileSafe(runHandoffPath(projectRoot, runId), handoffMarkdown(meta, state));
+}
+export async function ensureRunSystem(projectRoot) {
+    await ensureDir(runsRoot(projectRoot));
+    await ensureDir(activeArtifactsPath(projectRoot));
+    let state = await readFlowState(projectRoot);
+    let activeRunId = state.activeRunId;
+    const activeRunExists = activeRunId.trim().length > 0 && (await exists(runArtifactsPath(projectRoot, activeRunId)));
+    if (!activeRunExists) {
+        const activeHasArtifacts = (await listImmediateFiles(activeArtifactsPath(projectRoot))).length > 0;
+        const initialRun = await createRun(projectRoot, {
+            title: activeHasArtifacts ? "Migrated active run" : "Initial feature run",
+            seedFromActiveArtifacts: activeHasArtifacts
+        });
+        activeRunId = initialRun.id;
+        state = { ...state, activeRunId };
+        await writeFlowState(projectRoot, state);
+    }
+    const runArtifactsDir = runArtifactsPath(projectRoot, activeRunId);
+    if ((await listImmediateFiles(runArtifactsDir)).length === 0) {
+        await seedArtifactsFromTemplates(runArtifactsDir);
+    }
+    if ((await listImmediateFiles(activeArtifactsPath(projectRoot))).length === 0) {
+        await loadRunArtifactsToActive(projectRoot, activeRunId);
+    }
+    else {
+        await syncActiveArtifactsToRun(projectRoot, activeRunId);
+    }
+    await persistRunStateSnapshot(projectRoot, activeRunId, state);
+    await ensureRunHandoff(projectRoot, activeRunId);
+    return state;
+}
+export async function startNewFeatureRun(projectRoot, title) {
+    await ensureRunSystem(projectRoot);
+    const state = await readFlowState(projectRoot);
+    await syncActiveArtifactsToRun(projectRoot, state.activeRunId);
+    await persistRunStateSnapshot(projectRoot, state.activeRunId, state);
+    await ensureRunHandoff(projectRoot, state.activeRunId);
+    const nextRun = await createRun(projectRoot, {
+        title,
+        seedFromActiveArtifacts: false
+    });
+    const nextState = {
+        ...createInitialFlowState(nextRun.id),
+        activeRunId: nextRun.id
+    };
+    await writeFlowState(projectRoot, nextState);
+    await persistRunStateSnapshot(projectRoot, nextRun.id, nextState);
+    await loadRunArtifactsToActive(projectRoot, nextRun.id);
+    await ensureRunHandoff(projectRoot, nextRun.id);
+    return nextRun;
+}
+export async function resumeRun(projectRoot, runId) {
+    await ensureRunSystem(projectRoot);
+    const safeRunId = requireSafeRunId(runId);
+    const targetMeta = await readJsonFile(runMetaPath(projectRoot, safeRunId));
+    if (!targetMeta) {
+        throw new Error(`Run "${safeRunId}" not found under ${RUNTIME_ROOT}/runs/`);
+    }
+    const state = await readFlowState(projectRoot);
+    await syncActiveArtifactsToRun(projectRoot, state.activeRunId);
+    await persistRunStateSnapshot(projectRoot, state.activeRunId, state);
+    await ensureRunHandoff(projectRoot, state.activeRunId);
+    const nextState = targetMeta.stateSnapshot
+        ? coerceFlowState({
+            ...createInitialFlowState(safeRunId),
+            ...targetMeta.stateSnapshot,
+            activeRunId: safeRunId
+        }, safeRunId)
+        : coerceFlowState({
+            ...createInitialFlowState(safeRunId),
+            activeRunId: safeRunId
+        }, safeRunId);
+    await writeFlowState(projectRoot, nextState);
+    await persistRunStateSnapshot(projectRoot, safeRunId, nextState);
+    await loadRunArtifactsToActive(projectRoot, safeRunId);
+    await ensureRunHandoff(projectRoot, safeRunId);
+    return targetMeta;
+}
+export async function archiveRun(projectRoot, runId) {
+    await ensureRunSystem(projectRoot);
+    const state = await readFlowState(projectRoot);
+    const targetRunId = runId ? requireSafeRunId(runId) : state.activeRunId;
+    const targetMeta = await readJsonFile(runMetaPath(projectRoot, targetRunId));
+    if (!targetMeta) {
+        throw new Error(`Run "${targetRunId}" not found under ${RUNTIME_ROOT}/runs/`);
+    }
+    if (targetRunId === state.activeRunId) {
+        await syncActiveArtifactsToRun(projectRoot, targetRunId);
+        await persistRunStateSnapshot(projectRoot, targetRunId, state);
+    }
+    const archivedMeta = {
+        ...targetMeta,
+        archivedAt: nowIso()
+    };
+    await ensureRunMetadata(projectRoot, archivedMeta);
+    await ensureRunHandoff(projectRoot, targetRunId);
+    if (targetRunId !== state.activeRunId) {
+        const activeMeta = await readJsonFile(runMetaPath(projectRoot, state.activeRunId));
+        if (!activeMeta) {
+            throw new Error(`Active run "${state.activeRunId}" is missing metadata`);
+        }
+        return { archived: archivedMeta, active: activeMeta };
+    }
+    const nextRun = await createRun(projectRoot, {
+        title: "Post-archive run",
+        seedFromActiveArtifacts: false
+    });
+    const nextState = {
+        ...createInitialFlowState(nextRun.id),
+        activeRunId: nextRun.id
+    };
+    await writeFlowState(projectRoot, nextState);
+    await persistRunStateSnapshot(projectRoot, nextRun.id, nextState);
+    await loadRunArtifactsToActive(projectRoot, nextRun.id);
+    await ensureRunHandoff(projectRoot, nextRun.id);
+    return { archived: archivedMeta, active: nextRun };
+}

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+export declare const FLOW_STAGES: readonly ["brainstorm", "scope", "design", "spec", "plan", "test", "build", "review", "ship"];
+export type FlowStage = (typeof FLOW_STAGES)[number];
+export declare const HARNESS_IDS: readonly ["claude", "cursor", "opencode", "codex"];
+export type HarnessId = (typeof HARNESS_IDS)[number];
+export interface CclawConfig {
+    version: string;
+    flowVersion: string;
+    harnesses: HarnessId[];
+}
+export interface TransitionRule {
+    from: FlowStage;
+    to: FlowStage;
+    guards: string[];
+}
+export interface CliContext {
+    cwd: string;
+    stdout: NodeJS.WriteStream;
+    stderr: NodeJS.WriteStream;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+export const FLOW_STAGES = [
+    "brainstorm",
+    "scope",
+    "design",
+    "spec",
+    "plan",
+    "test",
+    "build",
+    "review",
+    "ship"
+];
+export const HARNESS_IDS = ["claude", "cursor", "opencode", "codex"];

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "cclaw-cli",
+  "version": "0.1.0",
+  "description": "Installer-first flow toolkit for coding agents",
+  "type": "module",
+  "bin": {
+    "cclaw": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean:dist": "node -e \"import('node:fs/promises').then((fs) => fs.rm('dist', { recursive: true, force: true }))\"",
+    "build": "npm run clean:dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke:runtime": "npm run build && node scripts/smoke-init.mjs",
+    "lint:hooks": "npm run build && node scripts/lint-generated-hooks.mjs",
+    "build:plugin-manifests": "npm run build && node scripts/build-plugin-manifests.mjs",
+    "release:check": "npm run build && npm run test && node scripts/lint-generated-hooks.mjs && node scripts/build-plugin-manifests.mjs && npm pack --dry-run && node scripts/smoke-init.mjs",
+    "release:bundle": "npm run release:check && npm pack"
+  },
+  "keywords": [
+    "cli",
+    "agent",
+    "workflow",
+    "tdd",
+    "npx"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}