cclaw-cli 8.1.0 → 8.1.1

package/README.md

@@ -1,6 +1,6 @@
 # cclaw
 
-**cclaw is a lightweight harness-first flow toolkit for coding agents.** It installs three slash commands, six on-demand specialists, twelve auto-trigger skills (including TDD cycle and conversation-language), ten artifact templates, four stage runbooks, eight reference patterns, five research playbooks, five recovery playbooks, thirteen worked examples, an antipatterns library, a decision protocol, a meta-skill, and a tiny runtime — together a deep content layer wrapped around a runtime under 1 KLOC — so Claude Code, Cursor, OpenCode, or Codex can move from idea to shipped change with a clear plan, AC traceability, TDD per AC, and almost no ceremony.
+**cclaw is a lightweight harness-first flow toolkit for coding agents.** It installs three slash commands, six on-demand specialists, twelve auto-trigger skills (including TDD cycle and conversation-language), ten artifact templates, four stage runbooks, eight reference patterns, five research playbooks, five recovery playbooks, thirteen worked examples, an antipatterns library, a decision protocol, a meta-skill, an interactive harness picker, and a tiny runtime — together a deep content layer wrapped around a runtime under 1 KLOC — so Claude Code, Cursor, OpenCode, or Codex can move from idea to shipped change with a clear plan, AC traceability, TDD per AC, and almost no ceremony.
 
 ```text
         idea
@@ -54,16 +54,17 @@ Requirements: Node.js 20+ and a git project.
 
 ```bash
 cd /path/to/your/repo
-npx cclaw-cli init                            # auto-detect harness from project root
-npx cclaw-cli init --harness=claude,cursor,opencode,codex   # explicit selection
+npx cclaw-cli init                            # interactive picker; auto-detected harness pre-selected
+npx cclaw-cli init --harness=claude,cursor,opencode,codex   # explicit, no picker
 ```
 
 `init` resolves harnesses in this order:
 
 1. `--harness=<id>[,<id>]` flag if passed.
 2. Existing `.cclaw/config.yaml` (so subsequent `init` / `sync` / `upgrade` are deterministic).
-3. Auto-detect from project root markers: `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.agents/skills/`, `CLAUDE.md`, `opencode.json`, `opencode.jsonc`.
-4. If nothing detected and no flag passed → exit with an actionable error. cclaw never silently picks a harness for you.
+3. **Interactive picker** when stdin/stdout are a TTY: a checkbox over the four harnesses with auto-detected ones pre-selected and tagged `(detected)`. Up/Down or k/j to move, Space to toggle, `a` to select all, `n` to deselect all, Enter to confirm, Esc/Ctrl-C to cancel.
+4. Non-TTY (CI, piped input, `npm exec --yes`): auto-detect from project root markers: `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.agents/skills/`, `CLAUDE.md`, `opencode.json`, `opencode.jsonc`.
+5. If nothing detected and no flag passed → exit with an actionable error. cclaw never silently picks a harness for you.
 
 Then work entirely inside your harness:
 

package/dist/cli.js

@@ -18,9 +18,11 @@ Commands:
 Harness selection:
   - If --harness=<id>[,<id>] is passed, install for those.
   - Otherwise, the existing .cclaw/config.yaml (if any) wins.
-  - Otherwise, cclaw auto-detects from project root markers (.claude/, .cursor/,
-    .opencode/, .codex/, .agents/skills/, CLAUDE.md, opencode.json).
-  - If nothing is detected and no flag is passed, init exits with an error.
+  - Otherwise, in an interactive TTY, cclaw shows a checkbox picker
+    (auto-detected harnesses pre-selected; Up/Down · Space · Enter).
+  - In non-TTY (CI, npx --yes, piped input), cclaw auto-detects from project
+    root markers (.claude/, .cursor/, .opencode/, .codex/, .agents/skills/,
+    CLAUDE.md, opencode.json) and exits with an error if nothing is found.
 
 Flow control (plan / build / review / ship) lives inside the harness via the /cc command, not in this CLI. There is no \`cclaw plan\`, \`cclaw status\`, \`cclaw ship\`, or \`cclaw migrate\` — by design.
 
@@ -55,17 +57,29 @@ export async function runCli(argv, context) {
     const args = parseArgs(argv);
     switch (args.command) {
         case "init": {
-            const result = await initCclaw({ cwd: context.cwd, harnesses: args.harnesses });
+            const result = await initCclaw({
+                cwd: context.cwd,
+                harnesses: args.harnesses,
+                interactive: true
+            });
             info(`[cclaw] init complete. Harnesses: ${result.installedHarnesses.join(", ")}`);
             return 0;
         }
         case "sync": {
-            const result = await syncCclaw({ cwd: context.cwd, harnesses: args.harnesses });
+            const result = await syncCclaw({
+                cwd: context.cwd,
+                harnesses: args.harnesses,
+                interactive: true
+            });
             info(`[cclaw] sync complete. Harnesses: ${result.installedHarnesses.join(", ")}`);
             return 0;
         }
         case "upgrade": {
-            const result = await upgradeCclaw({ cwd: context.cwd, harnesses: args.harnesses });
+            const result = await upgradeCclaw({
+                cwd: context.cwd,
+                harnesses: args.harnesses,
+                interactive: true
+            });
             info(`[cclaw] upgrade complete. Harnesses: ${result.installedHarnesses.join(", ")}`);
             return 0;
         }

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const CCLAW_VERSION = "8.1.0";
+export declare const CCLAW_VERSION = "8.1.1";
 export declare const RUNTIME_ROOT = ".cclaw";
 export declare const STATE_REL_PATH = ".cclaw/state";
 export declare const HOOKS_REL_PATH = ".cclaw/hooks";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const CCLAW_VERSION = "8.1.0";
+export const CCLAW_VERSION = "8.1.1";
 export const RUNTIME_ROOT = ".cclaw";
 export const STATE_REL_PATH = `${RUNTIME_ROOT}/state`;
 export const HOOKS_REL_PATH = `${RUNTIME_ROOT}/hooks`;

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

@@ -13,6 +13,14 @@ export interface HarnessLayout {
 export interface SyncOptions {
     cwd: string;
     harnesses?: HarnessId[];
+    /**
+     * 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[];

package/dist/install.js

@@ -21,6 +21,7 @@ import { ensureRunSystem } from "./run-persistence.js";
 import { createDefaultConfig, readConfig, renderConfig } from "./config.js";
 import { detectHarnesses, NO_HARNESS_DETECTED_MESSAGE } from "./harness-detect.js";
 import { ensureGitignorePatterns, removeGitignorePatterns } from "./gitignore.js";
+import { isInteractive, runPicker } from "./harness-prompt.js";
 import { HARNESS_IDS } from "./types.js";
 import { ironLawsMarkdown } from "./content/iron-laws.js";
 const HARNESS_LAYOUTS = {
@@ -191,22 +192,24 @@ async function writeConfig(projectRoot, config) {
     await writeFileSafe(configPath, renderConfig(config));
     return configPath;
 }
-async function resolveHarnesses(projectRoot, fromOptions, fromConfig) {
+async function resolveHarnesses(projectRoot, fromOptions, fromConfig, interactive) {
     if (fromOptions && fromOptions.length > 0)
         return fromOptions;
     if (fromConfig && fromConfig.length > 0)
         return fromConfig;
     const detected = await detectHarnesses(projectRoot);
-    if (detected.length === 0) {
-        throw new Error(NO_HARNESS_DETECTED_MESSAGE);
+    if (interactive && isInteractive()) {
+        return runPicker({ detected });
     }
-    return detected;
+    if (detected.length > 0)
+        return detected;
+    throw new Error(NO_HARNESS_DETECTED_MESSAGE);
 }
 export async function syncCclaw(options) {
     const projectRoot = options.cwd;
     await ensureRuntimeRoot(projectRoot);
     const existing = await readConfig(projectRoot);
-    const harnesses = await resolveHarnesses(projectRoot, options.harnesses, existing?.harnesses);
+    const harnesses = await resolveHarnesses(projectRoot, options.harnesses, existing?.harnesses, options.interactive ?? false);
     for (const harness of harnesses) {
         if (!HARNESS_IDS.includes(harness)) {
             throw new Error(`Unknown harness: ${harness}. Supported: ${HARNESS_IDS.join(", ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "8.1.0",
+  "version": "8.1.1",
   "description": "Lightweight harness-first flow toolkit for coding agents",
   "type": "module",
   "bin": {