cclaw-cli 7.7.1 → 8.1.1

package/dist/fs-utils.js

@@ -1,161 +1,5 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getActiveManagedResourceSession } from "./managed-resources.js";
-export async function ensureDir(dirPath) {
-    await fs.mkdir(dirPath, { recursive: true });
-}
-/**
- * Strip a leading UTF-8 BOM (U+FEFF) if present. Many editors (VS Code on
- * Windows, Notepad, some CI tools) silently prepend a BOM when saving
- * UTF-8; when the file is then split on `\n` the first line keeps the
- * invisible BOM and `JSON.parse` rejects it, which caused the first
- * knowledge.jsonl entry to be silently dropped on load. Treat BOM as a
- * no-op at read time so the rest of the pipeline sees clean UTF-8.
- */
-export function stripBom(text) {
-    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * Acquire a lightweight lock by creating a directory.
- * The lock is removed in a finally block.
- */
-export async function withDirectoryLock(lockPath, fn, options = {}) {
-    const retries = options.retries ?? 200;
-    const retryDelayMs = options.retryDelayMs ?? 20;
-    const staleAfterMs = options.staleAfterMs ?? 60_000;
-    await ensureDir(path.dirname(lockPath));
-    let acquired = false;
-    let lastError = null;
-    for (let attempt = 0; attempt < retries; attempt += 1) {
-        try {
-            await fs.mkdir(lockPath);
-            acquired = true;
-            break;
-        }
-        catch (error) {
-            lastError = error;
-            const code = error?.code;
-            if (code !== "EEXIST") {
-                throw error;
-            }
-            try {
-                const stat = await fs.stat(lockPath);
-                if (!stat.isDirectory()) {
-                    // A non-directory lives at the lock path (e.g. a stray file).
-                    // Retrying mkdir() will keep returning EEXIST forever, and no
-                    // other cclaw process is holding the lock - the path is simply
-                    // unusable. Fail loudly rather than burning the full retry
-                    // budget, so the caller sees a deterministic error.
-                    throw new Error(`Lock path exists but is not a directory: ${lockPath}`);
-                }
-                if (Date.now() - stat.mtimeMs > staleAfterMs) {
-                    await fs.rm(lockPath, { recursive: true, force: true });
-                    continue;
-                }
-            }
-            catch (statError) {
-                if (statError instanceof Error &&
-                    statError.message.startsWith("Lock path exists but is not a directory")) {
-                    throw statError;
-                }
-                // Lock directory disappeared between retries.
-            }
-            await sleep(retryDelayMs);
-        }
-    }
-    if (!acquired) {
-        const details = lastError instanceof Error ? lastError.message : String(lastError);
-        throw new Error(`Failed to acquire lock: ${lockPath} (attempts=${retries}, retryDelayMs=${retryDelayMs}, staleAfterMs=${staleAfterMs}, lastError=${details})`);
-    }
-    try {
-        return await fn();
-    }
-    finally {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch((cleanupError) => {
-            // Lock cleanup failure should not shadow the original operation result,
-            // but keep a diagnostic breadcrumb for flaky FS environments.
-            const details = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
-            // eslint-disable-next-line no-console
-            console.warn(`cclaw lock cleanup failed for ${lockPath}: ${details}`);
-        });
-    }
-}
-export async function writeFileSafe(filePath, content, options = {}) {
-    const managedSession = getActiveManagedResourceSession();
-    if (managedSession?.shouldManage(filePath)) {
-        await managedSession.writeFileSafe(filePath, content, options);
-        return;
-    }
-    await ensureDir(path.dirname(filePath));
-    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-    const targetMode = options.mode;
-    await fs.writeFile(tempPath, content, { encoding: "utf8", ...(targetMode !== undefined ? { mode: targetMode } : {}) });
-    // On Windows, `fs.rename` can fail transiently with EPERM / EBUSY / EACCES
-    // when the target file is briefly held open by another process (antivirus,
-    // search indexer, or a concurrent cclaw hook). Retry with small backoff
-    // before falling back to a non-atomic copy + unlink.
-    const renameRetryableCodes = new Set(["EPERM", "EBUSY", "EACCES"]);
-    let attempt = 0;
-    const maxAttempts = 6;
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
-        try {
-            await fs.rename(tempPath, filePath);
-            if (targetMode !== undefined) {
-                await fs.chmod(filePath, targetMode).catch(() => undefined);
-            }
-            return;
-        }
-        catch (error) {
-            const code = error?.code;
-            // `rename` fails with EXDEV when the temp file and target live on
-            // different filesystems (container bind mounts, tmpfs + rootfs,
-            // cross-volume setups). Fall back to copy + unlink so atomic writes
-            // still work — copyFile is not fully atomic but is the best we can
-            // do across devices, and we remove the temp even if copy fails.
-            if (code === "EXDEV") {
-                try {
-                    await fs.copyFile(tempPath, filePath);
-                    if (targetMode !== undefined) {
-                        await fs.chmod(filePath, targetMode).catch(() => undefined);
-                    }
-                }
-                finally {
-                    await fs.unlink(tempPath).catch(() => undefined);
-                }
-                return;
-            }
-            if (code !== undefined && renameRetryableCodes.has(code) && attempt < maxAttempts) {
-                attempt += 1;
-                const waitMs = 10 * attempt + Math.floor(Math.random() * 10);
-                await new Promise((resolve) => setTimeout(resolve, waitMs));
-                continue;
-            }
-            if (code !== undefined && renameRetryableCodes.has(code)) {
-                // Last-resort fallback on Windows: copy-then-unlink. Not atomic,
-                // but the caller is expected to have serialized via a directory
-                // lock so this only loses atomicity under extreme contention.
-                try {
-                    await fs.copyFile(tempPath, filePath);
-                    if (targetMode !== undefined) {
-                        await fs.chmod(filePath, targetMode).catch(() => undefined);
-                    }
-                    return;
-                }
-                finally {
-                    await fs.unlink(tempPath).catch(() => undefined);
-                }
-            }
-            // Other errors: try to clean up the temp to avoid littering the
-            // directory with orphaned `.tmp-<pid>-*` files, then rethrow.
-            await fs.unlink(tempPath).catch(() => undefined);
-            throw error;
-        }
-    }
-}
 export async function exists(filePath) {
     try {
         await fs.access(filePath);
@@ -165,11 +9,34 @@ export async function exists(filePath) {
         return false;
     }
 }
-export async function removeIfExists(targetPath) {
-    if (await exists(targetPath)) {
-        await fs.rm(targetPath, { recursive: true, force: true });
-    }
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
 }
-export function resolveProjectPath(cwd, relativePath) {
-    return path.resolve(cwd, relativePath);
+export async function writeFileSafe(filePath, content) {
+    await ensureDir(path.dirname(filePath));
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    await fs.writeFile(tempPath, content, "utf8");
+    await fs.rename(tempPath, filePath);
+}
+export async function readJsonIfExists(filePath) {
+    if (!(await exists(filePath)))
+        return null;
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+export async function removePath(filePath) {
+    await fs.rm(filePath, { recursive: true, force: true });
+}
+export async function listMarkdownFiles(dir) {
+    if (!(await exists(dir)))
+        return [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => path.join(dir, entry.name));
+}
+export async function listSubdirs(dir) {
+    if (!(await exists(dir)))
+        return [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => path.join(dir, entry.name));
 }

package/dist/gitignore.d.ts

@@ -1,3 +1,4 @@
-export declare function ensureGitignore(projectRoot: string): Promise<void>;
+export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw transient state", ".cclaw/state/", ".cclaw/worktrees/"];
+export declare function ensureGitignorePatterns(projectRoot: string): Promise<void>;
 export declare function removeGitignorePatterns(projectRoot: string): Promise<void>;
 export declare function gitignoreHasRequiredPatterns(projectRoot: string): Promise<boolean>;

package/dist/gitignore.js

@@ -1,46 +1,63 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { REQUIRED_GITIGNORE_PATTERNS } from "./constants.js";
 import { exists, writeFileSafe } from "./fs-utils.js";
-export async function ensureGitignore(projectRoot) {
-    const gitignorePath = path.join(projectRoot, ".gitignore");
-    const currentContent = (await exists(gitignorePath))
-        ? await fs.readFile(gitignorePath, "utf8")
-        : "";
-    const lines = currentContent.split(/\r?\n/);
-    const normalized = new Set(lines.map((line) => line.trim()).filter(Boolean));
-    const missing = REQUIRED_GITIGNORE_PATTERNS.filter((pattern) => !normalized.has(pattern));
-    if (missing.length === 0) {
+/**
+ * cclaw .gitignore patterns.
+ *
+ * Only the *transient* parts of .cclaw/ are ignored. The artifact tree
+ * (`.cclaw/flows/`, `.cclaw/lib/`, `.cclaw/config.yaml`, `.cclaw/ideas.md`,
+ * `.cclaw/knowledge.jsonl`, hooks, etc.) is meant to be committed so the
+ * team and graph tools can index the work history.
+ *
+ * - `.cclaw/state/` — per-developer flow-state.json. Mutates every session.
+ * - `.cclaw/worktrees/` — transient git worktrees created by the
+ *   parallel-build pattern. These already contain regular checked-out trees;
+ *   never commit them as nested data.
+ */
+const SECTION_HEADER = "# cclaw transient state";
+export const REQUIRED_GITIGNORE_PATTERNS = [
+    SECTION_HEADER,
+    ".cclaw/state/",
+    ".cclaw/worktrees/"
+];
+function gitignorePath(projectRoot) {
+    return path.join(projectRoot, ".gitignore");
+}
+export async function ensureGitignorePatterns(projectRoot) {
+    const target = gitignorePath(projectRoot);
+    const current = (await exists(target)) ? await fs.readFile(target, "utf8") : "";
+    const lines = current.split(/\r?\n/);
+    const present = new Set(lines.map((line) => line.trim()).filter(Boolean));
+    const missing = REQUIRED_GITIGNORE_PATTERNS.filter((pattern) => !present.has(pattern));
+    if (missing.length === 0)
         return;
-    }
-    const base = lines.join("\n").replace(/\s+$/u, "");
-    const suffix = `${base.length > 0 ? "\n" : ""}${missing.join("\n")}\n`;
-    // `writeFileSafe` performs a tmp-file + rename so a crash mid-write
-    // cannot leave `.gitignore` in a half-written state; the previous
-    // direct `fs.writeFile` could truncate the file on SIGKILL.
-    await writeFileSafe(gitignorePath, `${base}${suffix}`);
+    const trimmedBase = current.replace(/\s+$/u, "");
+    const separator = trimmedBase.length > 0 ? "\n\n" : "";
+    const next = `${trimmedBase}${separator}${missing.join("\n")}\n`;
+    await writeFileSafe(target, next);
 }
 export async function removeGitignorePatterns(projectRoot) {
-    const gitignorePath = path.join(projectRoot, ".gitignore");
-    if (!(await exists(gitignorePath)))
+    const target = gitignorePath(projectRoot);
+    if (!(await exists(target)))
+        return;
+    const current = await fs.readFile(target, "utf8");
+    const drop = new Set(REQUIRED_GITIGNORE_PATTERNS);
+    const cleaned = current
+        .split(/\r?\n/)
+        .filter((line) => !drop.has(line.trim()))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    if (cleaned.length === 0) {
+        await fs.rm(target, { force: true });
         return;
-    const content = await fs.readFile(gitignorePath, "utf8");
-    const lines = content.split(/\r?\n/);
-    const patternsSet = new Set(REQUIRED_GITIGNORE_PATTERNS);
-    const cleaned = lines.filter((line) => !patternsSet.has(line.trim()));
-    const result = cleaned.join("\n").replace(/\n{3,}/g, "\n\n").trim();
-    if (result.length === 0) {
-        await fs.rm(gitignorePath, { force: true });
-    }
-    else {
-        await writeFileSafe(gitignorePath, `${result}\n`);
     }
+    await writeFileSafe(target, `${cleaned}\n`);
 }
 export async function gitignoreHasRequiredPatterns(projectRoot) {
-    const gitignorePath = path.join(projectRoot, ".gitignore");
-    if (!(await exists(gitignorePath))) {
+    const target = gitignorePath(projectRoot);
+    if (!(await exists(target)))
         return false;
-    }
-    const content = await fs.readFile(gitignorePath, "utf8");
-    return REQUIRED_GITIGNORE_PATTERNS.every((pattern) => content.includes(pattern));
+    const current = await fs.readFile(target, "utf8");
+    return REQUIRED_GITIGNORE_PATTERNS.every((pattern) => current.includes(pattern));
 }

package/dist/harness-detect.d.ts

@@ -0,0 +1,10 @@
+import { type HarnessId } from "./types.js";
+/**
+ * Detect which harnesses are already wired up in the project root.
+ * Used by `cclaw init` when the operator does not pass --harness=<id>.
+ *
+ * Markers are intentionally minimal — presence of any one marker per harness
+ * is enough to elect it. Returns harnesses in canonical (HARNESS_IDS) order.
+ */
+export declare function detectHarnesses(projectRoot: string): Promise<HarnessId[]>;
+export declare const NO_HARNESS_DETECTED_MESSAGE: string;

package/dist/harness-detect.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { exists } from "./fs-utils.js";
+const HARNESS_MARKERS = [
+    { harness: "claude", markers: [".claude", "CLAUDE.md"] },
+    { harness: "cursor", markers: [".cursor"] },
+    { harness: "opencode", markers: [".opencode", "opencode.json", "opencode.jsonc"] },
+    { harness: "codex", markers: [".codex", ".agents/skills"] }
+];
+/**
+ * Detect which harnesses are already wired up in the project root.
+ * Used by `cclaw init` when the operator does not pass --harness=<id>.
+ *
+ * Markers are intentionally minimal — presence of any one marker per harness
+ * is enough to elect it. Returns harnesses in canonical (HARNESS_IDS) order.
+ */
+export async function detectHarnesses(projectRoot) {
+    const detected = [];
+    for (const { harness, markers } of HARNESS_MARKERS) {
+        for (const marker of markers) {
+            if (await exists(path.join(projectRoot, marker))) {
+                detected.push(harness);
+                break;
+            }
+        }
+    }
+    return detected;
+}
+export const NO_HARNESS_DETECTED_MESSAGE = "No harness detected in project root. Pass --harness=<id>[,<id>] (claude,cursor,opencode,codex) " +
+    "or create a marker first (e.g. `mkdir .cursor` for Cursor, `mkdir .claude` for Claude Code).";

package/dist/harness-prompt.d.ts

@@ -0,0 +1,26 @@
+import { type HarnessId } from "./types.js";
+export interface PickerState {
+    selected: ReadonlySet<HarnessId>;
+    cursor: number;
+    message?: string;
+}
+export type PickerOutcome = "confirm" | "cancel" | "continue";
+export interface PickerUpdate {
+    state: PickerState;
+    outcome: PickerOutcome;
+}
+export declare function createPickerState(preselect?: readonly HarnessId[], cursor?: number): PickerState;
+export declare function applyKey(state: PickerState, key: string): PickerUpdate;
+export declare function selectionToList(state: PickerState): HarnessId[];
+export interface IsInteractiveStreams {
+    stdin?: NodeJS.ReadStream;
+    stdout?: NodeJS.WriteStream;
+}
+export declare function isInteractive(streams?: IsInteractiveStreams): boolean;
+export interface PromptOptions {
+    detected: readonly HarnessId[];
+    preselect?: readonly HarnessId[];
+    stdin?: NodeJS.ReadStream;
+    stdout?: NodeJS.WriteStream;
+}
+export declare function runPicker(options: PromptOptions): Promise<HarnessId[]>;

package/dist/harness-prompt.js

@@ -0,0 +1,142 @@
+import process from "node:process";
+import { HARNESS_IDS } from "./types.js";
+const HARNESS_LABELS = {
+    claude: "Claude Code",
+    cursor: "Cursor",
+    opencode: "OpenCode",
+    codex: "Codex"
+};
+const HARNESS_TARGETS = {
+    claude: ".claude/",
+    cursor: ".cursor/",
+    opencode: ".opencode/",
+    codex: ".codex/"
+};
+export function createPickerState(preselect = [], cursor = 0) {
+    const valid = preselect.filter((id) => HARNESS_IDS.includes(id));
+    return {
+        selected: new Set(valid.length > 0 ? valid : ["cursor"]),
+        cursor: Math.max(0, Math.min(cursor, HARNESS_IDS.length - 1))
+    };
+}
+export function applyKey(state, key) {
+    if (key === "\u0003" || key === "\u001b") {
+        return { state: { ...state, message: "Cancelled." }, outcome: "cancel" };
+    }
+    if (key === "\u001b[A" || key === "k" || key === "K") {
+        const next = (state.cursor - 1 + HARNESS_IDS.length) % HARNESS_IDS.length;
+        return { state: { ...state, cursor: next, message: undefined }, outcome: "continue" };
+    }
+    if (key === "\u001b[B" || key === "j" || key === "J") {
+        const next = (state.cursor + 1) % HARNESS_IDS.length;
+        return { state: { ...state, cursor: next, message: undefined }, outcome: "continue" };
+    }
+    if (key === " ") {
+        const current = HARNESS_IDS[state.cursor];
+        if (!current)
+            return { state, outcome: "continue" };
+        const selected = new Set(state.selected);
+        if (selected.has(current))
+            selected.delete(current);
+        else
+            selected.add(current);
+        return { state: { ...state, selected, message: undefined }, outcome: "continue" };
+    }
+    if (key === "a" || key === "A") {
+        return {
+            state: { ...state, selected: new Set(HARNESS_IDS), message: undefined },
+            outcome: "continue"
+        };
+    }
+    if (key === "n" || key === "N") {
+        return {
+            state: { ...state, selected: new Set(), message: undefined },
+            outcome: "continue"
+        };
+    }
+    if (key === "\r" || key === "\n") {
+        if (state.selected.size === 0) {
+            return {
+                state: { ...state, message: "Select at least one harness." },
+                outcome: "continue"
+            };
+        }
+        return { state, outcome: "confirm" };
+    }
+    return { state, outcome: "continue" };
+}
+export function selectionToList(state) {
+    return HARNESS_IDS.filter((id) => state.selected.has(id));
+}
+export function isInteractive(streams = {}) {
+    const stdin = streams.stdin ?? process.stdin;
+    const stdout = streams.stdout ?? process.stdout;
+    return Boolean(stdin.isTTY === true &&
+        stdout.isTTY === true &&
+        typeof stdin.setRawMode === "function");
+}
+function renderFrame(state, detected, stdout) {
+    stdout.write("\u001b[2J\u001b[H");
+    stdout.write("cclaw — choose harness(es) to install for\n\n");
+    HARNESS_IDS.forEach((harness, index) => {
+        const pointer = index === state.cursor ? ">" : " ";
+        const checked = state.selected.has(harness) ? "x" : " ";
+        const tag = detected.has(harness) ? "  (detected)" : "";
+        stdout.write(`  ${pointer} [${checked}] ${HARNESS_LABELS[harness].padEnd(12)} ${HARNESS_TARGETS[harness]}${tag}\n`);
+    });
+    stdout.write("\nUp/Down or k/j to move  ·  Space to toggle  ·  a all  ·  n none  ·  Enter to confirm  ·  Esc/Ctrl-C to cancel\n");
+    if (state.message)
+        stdout.write(`\n${state.message}\n`);
+}
+export async function runPicker(options) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const detectedSet = new Set(options.detected);
+    const initial = options.preselect && options.preselect.length > 0 ? options.preselect : options.detected;
+    let state = createPickerState(initial);
+    const wasRaw = Boolean(stdin.isRaw);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            stdin.off("data", onData);
+            try {
+                stdin.setRawMode?.(wasRaw);
+            }
+            catch {
+                // ignore — terminal might already be torn down
+            }
+            if (!wasRaw)
+                stdin.pause();
+            stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            if (settled)
+                return;
+            const key = chunk.toString("utf8");
+            const update = applyKey(state, key);
+            state = update.state;
+            renderFrame(state, detectedSet, stdout);
+            if (update.outcome === "confirm") {
+                settled = true;
+                cleanup();
+                resolve(selectionToList(state));
+                return;
+            }
+            if (update.outcome === "cancel") {
+                settled = true;
+                cleanup();
+                reject(new Error("Harness selection cancelled."));
+            }
+        };
+        try {
+            stdin.setRawMode?.(true);
+            stdin.resume();
+            stdin.on("data", onData);
+            renderFrame(state, detectedSet, stdout);
+        }
+        catch (err) {
+            cleanup();
+            reject(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}

package/dist/install.d.ts

@@ -1,19 +1,39 @@
-import type { FlowTrack, HarnessId } from "./types.js";
-export interface InitOptions {
-    projectRoot: string;
-    harnesses?: HarnessId[];
-    track?: FlowTrack;
+import { type NodeHookSpec } from "./content/node-hooks.js";
+import { type HarnessId } from "./types.js";
+export interface HarnessLayout {
+    id: HarnessId;
+    commandsDir: string;
+    agentsDir: string;
+    skillsDir: string;
+    hooksConfig: {
+        dir: string;
+        fileName: string;
+    } | null;
 }
 export interface SyncOptions {
+    cwd: string;
     harnesses?: HarnessId[];
-    check?: boolean;
+    /**
+     * When true (default for `init` from a real TTY), `cclaw` shows the
+     * interactive harness picker if no `--harness` flag and no existing
+     * `.cclaw/config.yaml` are available. Set to false in CI/non-TTY paths
+     * (smoke scripts, programmatic callers) to fall back to auto-detect or
+     * a hard error if nothing is found.
+     */
+    interactive?: boolean;
+}
+export interface SyncResult {
+    installedHarnesses: HarnessId[];
+    configPath: string;
 }
-export declare function initCclaw(options: InitOptions): Promise<void>;
-export declare function syncCclaw(projectRoot: string, options?: SyncOptions): Promise<void>;
-/**
- * Refresh generated files in `.cclaw/` without touching user-authored
- * artifacts or state. Config remains harness-only with managed version
- * stamps.
- */
-export declare function upgradeCclaw(projectRoot: string): Promise<void>;
-export declare function uninstallCclaw(projectRoot: string): Promise<void>;
+export declare function ensureRuntimeRoot(projectRoot: string): Promise<void>;
+export declare function syncCclaw(options: SyncOptions): Promise<SyncResult>;
+export declare function initCclaw(options: SyncOptions): Promise<SyncResult>;
+export declare function uninstallCclaw(options: {
+    cwd: string;
+}): Promise<void>;
+export declare function upgradeCclaw(options: SyncOptions): Promise<SyncResult>;
+export declare function planSeedForSlug(slug: string): string;
+export declare const HARNESS_LAYOUT_TABLE: Record<"claude" | "cursor" | "opencode" | "codex", HarnessLayout>;
+export type { NodeHookSpec };
+export declare const COMMIT_HELPER_HOOK: NodeHookSpec;