cclaw-cli 7.7.1 → 8.1.0

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/install.d.ts

@@ -1,19 +1,31 @@
-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;
 }
-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 interface SyncResult {
+    installedHarnesses: HarnessId[];
+    configPath: string;
+}
+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;