cclaw-cli 0.1.0

package/dist/fs-utils.js

@@ -0,0 +1,28 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+export async function writeFileSafe(filePath, content) {
+    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)}`);
+    await fs.writeFile(tempPath, content, "utf8");
+    await fs.rename(tempPath, filePath);
+}
+export async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function removeIfExists(targetPath) {
+    if (await exists(targetPath)) {
+        await fs.rm(targetPath, { recursive: true, force: true });
+    }
+}
+export function resolveProjectPath(cwd, relativePath) {
+    return path.resolve(cwd, relativePath);
+}

package/dist/gitignore.d.ts

@@ -0,0 +1,3 @@
+export declare function ensureGitignore(projectRoot: string): Promise<void>;
+export declare function removeGitignorePatterns(projectRoot: string): Promise<void>;
+export declare function gitignoreHasRequiredPatterns(projectRoot: string): Promise<boolean>;

package/dist/gitignore.js

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { REQUIRED_GITIGNORE_PATTERNS } from "./constants.js";
+import { exists } 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) {
+        return;
+    }
+    const base = lines.join("\n").replace(/\s+$/u, "");
+    const suffix = `${base.length > 0 ? "\n" : ""}${missing.join("\n")}\n`;
+    await fs.writeFile(gitignorePath, `${base}${suffix}`, "utf8");
+}
+export async function removeGitignorePatterns(projectRoot) {
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    if (!(await exists(gitignorePath)))
+        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 fs.writeFile(gitignorePath, `${result}\n`, "utf8");
+    }
+}
+export async function gitignoreHasRequiredPatterns(projectRoot) {
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    if (!(await exists(gitignorePath))) {
+        return false;
+    }
+    const content = await fs.readFile(gitignorePath, "utf8");
+    return REQUIRED_GITIGNORE_PATTERNS.every((pattern) => content.includes(pattern));
+}

package/dist/harness-adapters.d.ts

@@ -0,0 +1,12 @@
+import type { HarnessId } from "./types.js";
+export declare const CCLAW_MARKER_START = "<!-- cclaw-start -->";
+export declare const CCLAW_MARKER_END = "<!-- cclaw-end -->";
+export interface HarnessAdapter {
+    id: HarnessId;
+    commandDir: string;
+}
+export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
+/** Removes the cclaw AGENTS.md block. */
+export declare function stripCclawBlock(content: string): string;
+export declare function removeCclawFromAgentsMd(projectRoot: string): Promise<void>;
+export declare function syncHarnessShims(projectRoot: string, harnesses: HarnessId[]): Promise<void>;

package/dist/harness-adapters.js

@@ -0,0 +1,175 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { CCLAW_AGENTS, agentMarkdown, agentsAgentsMdBlock } from "./content/agents.js";
+import { autoplanAgentsMdBlock } from "./content/autoplan.js";
+import { learningsAgentsMdBlock } from "./content/learnings.js";
+import { sessionHooksAgentsMdBlock } from "./content/session-hooks.js";
+import { hooksAgentsMdBlock } from "./content/hooks.js";
+import { subagentsAgentsMdBlock } from "./content/subagents.js";
+import { stageSkillFolder } from "./content/skills.js";
+import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+export const CCLAW_MARKER_START = "<!-- cclaw-start -->";
+export const CCLAW_MARKER_END = "<!-- cclaw-end -->";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const RUNTIME_AGENTS_BLOCK_SOURCE = `${escapeRegExp(CCLAW_MARKER_START)}[\\s\\S]*?${escapeRegExp(CCLAW_MARKER_END)}`;
+const RUNTIME_AGENTS_BLOCK_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "u");
+const RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "gu");
+export const HARNESS_ADAPTERS = {
+    claude: { id: "claude", commandDir: ".claude/commands" },
+    cursor: { id: "cursor", commandDir: ".cursor/commands" },
+    opencode: { id: "opencode", commandDir: ".opencode/commands" },
+    codex: { id: "codex", commandDir: ".codex/commands" }
+};
+function shimFileName(stage) {
+    return `cc-${stage}.md`;
+}
+function shimContent(harness, stage) {
+    const skillFolder = stageSkillFolder(stage);
+    return `---
+name: cc-${stage}
+description: Generated shim for ${harness}. Runs one flow stage with command+skill context.
+source: generated-by-cclaw
+---
+
+# cclaw ${stage}
+
+Load and execute:
+1. \`.cclaw/skills/${skillFolder}/SKILL.md\`
+2. \`.cclaw/commands/${stage}.md\`
+
+This command is stage-scoped: do only this stage and then hand off to the next one.
+Use \`.cclaw/state/flow-state.json\` for transition guards and status tracking.
+Do not skip required handoff gates.
+`;
+}
+function agentsMdBlock() {
+    const stageList = COMMAND_FILE_ORDER.map((s) => `| \`/cc-${s}\` | \`.cclaw/skills/${stageSkillFolder(s)}/SKILL.md\` + \`.cclaw/commands/${s}.md\` |`).join("\n");
+    return `${CCLAW_MARKER_START}
+## Cclaw — Structured Development Flow
+
+> Auto-generated by \`cclaw sync\`. Do not edit manually — run \`npx cclaw sync\`.
+
+### Activation Rule
+
+Before responding to a coding request:
+1. Read \`.cclaw/state/flow-state.json\` for the current stage.
+2. If a stage applies, invoke the matching \`/cc-*\` command.
+3. If no stage applies, respond normally.
+
+### Intent → Stage Routing
+
+| Command | Loads |
+|---|---|
+${stageList}
+| \`/cc-learn\` | \`.cclaw/skills/learnings/SKILL.md\` + \`.cclaw/commands/learn.md\` |
+| \`/cc-autoplan\` | \`.cclaw/skills/autoplan/SKILL.md\` + \`.cclaw/commands/autoplan.md\` |
+
+**Stage order:** brainstorm > scope > design > spec > plan > test > build > review > ship.
+One stage per invocation. Gates must pass before handoff. Artifacts in \`.cclaw/artifacts/\`.
+
+### Verification Discipline
+
+No completion claims without fresh evidence. No "Done" / "All good" / "Tests pass" without running the command in this message.
+
+### File Map
+
+| Path | Purpose |
+|---|---|
+| \`.cclaw/commands/*.md\` | Stage commands (thin orchestrators) |
+| \`.cclaw/skills/*/SKILL.md\` | Full stage instructions |
+| \`.cclaw/rules/\` | RULES.md + rules.json |
+| \`.cclaw/state/flow-state.json\` | Flow state & gate tracking |
+| \`.cclaw/artifacts/*.md\` | Stage evidence artifacts |
+| \`.cclaw/agents/*.md\` | Specialist agent personas |
+| \`.cclaw/learnings.jsonl\` | Project knowledge base |
+
+${learningsAgentsMdBlock()}
+${autoplanAgentsMdBlock()}
+${agentsAgentsMdBlock()}
+${subagentsAgentsMdBlock()}
+${sessionHooksAgentsMdBlock()}
+${hooksAgentsMdBlock()}
+${CCLAW_MARKER_END}`;
+}
+/** Removes the cclaw AGENTS.md block. */
+export function stripCclawBlock(content) {
+    let updated = content.replace(RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN, "");
+    return updated.replace(/\n{3,}/g, "\n\n").trim();
+}
+async function syncAgentsMd(projectRoot) {
+    const agentsPath = path.join(projectRoot, "AGENTS.md");
+    const block = agentsMdBlock();
+    if (!(await exists(agentsPath))) {
+        await writeFileSafe(agentsPath, `# AGENTS\n\n${block}\n`);
+        return;
+    }
+    const content = await fs.readFile(agentsPath, "utf8");
+    if (RUNTIME_AGENTS_BLOCK_PATTERN.test(content)) {
+        const stripped = stripCclawBlock(content);
+        const updated = stripped.length > 0 ? `${stripped}\n\n${block}\n` : `${block}\n`;
+        await writeFileSafe(agentsPath, updated);
+    }
+    else {
+        await writeFileSafe(agentsPath, `${content.trimEnd()}\n\n${block}\n`);
+    }
+}
+export async function removeCclawFromAgentsMd(projectRoot) {
+    const agentsPath = path.join(projectRoot, "AGENTS.md");
+    if (!(await exists(agentsPath)))
+        return;
+    const content = await fs.readFile(agentsPath, "utf8");
+    if (!RUNTIME_AGENTS_BLOCK_PATTERN.test(content))
+        return;
+    const stripped = stripCclawBlock(content);
+    if (stripped.replace(/\s/g, "").length === 0) {
+        await fs.rm(agentsPath, { force: true });
+    }
+    else {
+        await writeFileSafe(agentsPath, `${stripped}\n`);
+    }
+}
+function utilityShimContent(harness, command, skillFolder, commandFile) {
+    return `---
+name: cc-${command}
+description: Generated shim for ${harness}. Utility command — not a flow stage.
+source: generated-by-cclaw
+---
+
+# cclaw ${command}
+
+Load and execute:
+1. \`.cclaw/skills/${skillFolder}/SKILL.md\`
+2. \`.cclaw/commands/${commandFile}\`
+
+This is a utility command (not a flow stage). It does not advance flow state.
+`;
+}
+async function syncAgentFiles(projectRoot) {
+    const agentsDir = path.join(projectRoot, RUNTIME_ROOT, "agents");
+    await ensureDir(agentsDir);
+    for (const agent of CCLAW_AGENTS) {
+        await writeFileSafe(path.join(agentsDir, `${agent.name}.md`), agentMarkdown(agent));
+    }
+}
+export async function syncHarnessShims(projectRoot, harnesses) {
+    for (const harness of harnesses) {
+        const adapter = HARNESS_ADAPTERS[harness];
+        if (!adapter) {
+            continue;
+        }
+        const commandDir = path.join(projectRoot, adapter.commandDir);
+        await ensureDir(commandDir);
+        for (const stage of COMMAND_FILE_ORDER) {
+            const fullPath = path.join(commandDir, shimFileName(stage));
+            await writeFileSafe(fullPath, shimContent(harness, stage));
+        }
+        // Utility command shims
+        await writeFileSafe(path.join(commandDir, "cc-learn.md"), utilityShimContent(harness, "learn", "learnings", "learn.md"));
+        await writeFileSafe(path.join(commandDir, "cc-autoplan.md"), utilityShimContent(harness, "autoplan", "autoplan", "autoplan.md"));
+    }
+    await syncAgentFiles(projectRoot);
+    await syncAgentsMd(projectRoot);
+}

package/dist/install.d.ts

@@ -0,0 +1,9 @@
+import type { HarnessId } from "./types.js";
+export interface InitOptions {
+    projectRoot: string;
+    harnesses?: HarnessId[];
+}
+export declare function initCclaw(options: InitOptions): Promise<void>;
+export declare function syncCclaw(projectRoot: string): Promise<void>;
+export declare function upgradeCclaw(projectRoot: string): Promise<void>;
+export declare function uninstallCclaw(projectRoot: string): Promise<void>;