@bike4mind/cli 0.15.3 → 0.17.0

package/README.md

@@ -578,6 +578,55 @@ Coming soon:
 ⏳ Session search and management
 ⏳ Tool execution monitoring
 
+## Running as a `claude` engine inside a host app
+
+The CLI can be driven by a host app (e.g. a kanban-style agent pipeline) as a
+drop-in replacement for `claude` — running a pipeline **stage** or a **board AI /
+YAML** pane with full parity (board tools over HTTP MCP, the 3-layer brief
+injected, the spec auto-fired on turn 1, and the live-card `processing` /
+`action_required` / `ready` signal).
+
+A host that only launches an engine whose executable basename is exactly `claude`
+can be pointed at a **symlink** named `claude`:
+
+```bash
+# Create a claude-named symlink to the CLI entry point somewhere on disk:
+ln -s "$(pwd)/apps/cli/bin/bike4mind-cli.mjs" /usr/local/bin/claude-b4m/claude
+
+# In the host, set the engine's `terminal_command` to that symlink path:
+#   /usr/local/bin/claude-b4m/claude
+```
+
+Use a **direct symlink** whose basename is `claude` — not a `package.json` bin
+alias (it would shadow the real `claude`) and not a wrapper shell script (argv
+gets mangled). No other setup is required; the CLI replicates claude's launch-flag
+and lifecycle-hook contract.
+
+### Supported claude-compatible flags
+
+These are parsed in `bin/bike4mind-cli.mjs` into `B4M_*` env vars consumed by the
+runtime. Unknown flags are tolerated (never hard-error) and the interactive TUI is
+preserved (a positional prompt seeds **and** submits turn 1 without switching to
+headless `-p`):
+
+| Flag | Effect |
+| --- | --- |
+| `--mcp-config <file>` | Inject MCP servers from a claude-shape JSON (`{ "mcpServers": {...} }`). Supports HTTP transport (`type: "http"`, `url`, `headers`) with per-launch Bearer auth. |
+| `--strict-mcp-config` | Use ONLY `--mcp-config` servers; ignore file-config and `.mcp.json` (board YAML pane). |
+| `--append-system-prompt <text>` | Append text verbatim to the end of the system prompt (the 3-layer brief). |
+| `--allowedTools <patterns>` | Auto-approve matching tools without a permission prompt (glob `mcp__manifold__*` or a space-separated explicit list). |
+| `--settings <json>` | Inline JSON; the `hooks` subset drives lifecycle hooks (see below). Malformed JSON is ignored, never fatal. |
+| `--session-id <uuid>` / `--resume <uuid>` | Pin / resume a session (board pane). `/clear` and `/compact` keep the pinned uuid; a bad `--resume` prints `No conversation found with session ID <uuid>` and exits non-zero so the host can self-heal the pane. |
+| `<positional prompt>` | Seeds and auto-fires turn 1 while staying interactive. |
+
+### Lifecycle hooks (`--settings.hooks`)
+
+Mirrors claude's hook contract for the host's `action_required` signal: a
+`Notification`/`permission_prompt` command writes a sentinel file while an
+interactive permission prompt blocks; `PostToolUse` / `Stop` / `UserPromptSubmit`
+commands remove it. Each hook command runs via a real shell with its stdin piped
+then closed (EOF), so a blocking `cat > <file>` hook returns immediately.
+
 ## License
 
 Private - Bike4Mind

package/bin/bike4mind-cli.mjs

@@ -111,10 +111,48 @@ const argv = await yargs(hideBin(process.argv))
     type: 'string',
     description: 'Add local Ollama models to the model picker (e.g. http://localhost:11434)',
   })
+  // ─── claude-compatible flags (host drop-in masquerade) ──────────────────────
+  // Declared so a host's claude launch flags parse into named options instead of
+  // leaking into the positional `argv._` task. See apps/cli README "host app".
+  .option('mcp-config', {
+    type: 'string',
+    description: 'Path to a JSON file of MCP servers to inject ({ "mcpServers": {...} })',
+  })
+  .option('strict-mcp-config', {
+    type: 'boolean',
+    description: 'Use ONLY --mcp-config servers; ignore file-config and .mcp.json',
+    default: false,
+  })
+  .option('append-system-prompt', {
+    type: 'string',
+    description: 'Text appended verbatim to the end of the composed system prompt',
+  })
+  .option('allowedTools', {
+    type: 'array',
+    string: true,
+    description: 'Tool names/globs auto-approved without a permission prompt (e.g. mcp__manifold__*)',
+  })
+  .option('settings', {
+    type: 'string',
+    description: 'Inline JSON settings (currently: lifecycle hooks) merged over user config',
+  })
+  .option('session-id', {
+    type: 'string',
+    description: 'Pin this session to a fixed uuid (first launch of a resumable pane)',
+  })
+  .option('resume', {
+    type: 'string',
+    description: 'Resume an existing session by uuid',
+  })
   .option('api-url', {
     type: 'string',
     description: 'Set a custom API URL (self-hosted instance) and clear auth tokens, then exit',
   })
+  .option('no-remote-skills', {
+    type: 'boolean',
+    description: 'Skip fetching B4M-web skills for this run (local files only)',
+    default: false,
+  })
   .option('reset-api', {
     type: 'boolean',
     description: 'Reset the API URL to the Bike4Mind default and clear auth tokens, then exit',
@@ -196,6 +234,42 @@ if (argv['add-dir'] && argv['add-dir'].length > 0) {
 if (argv['ollama-host']) {
   process.env.B4M_OLLAMA_HOST = argv['ollama-host'];
 }
+if (argv['no-remote-skills']) {
+  process.env.B4M_NO_REMOTE_SKILLS = '1';
+}
+
+// ─── claude-compatible flags → B4M_* env (read by src/index.tsx init) ─────────
+// Mirrors the established bin→env→init channel (cf. --add-dir → B4M_ADDITIONAL_DIRS).
+if (argv['mcp-config']) {
+  process.env.B4M_MCP_CONFIG_FILE = resolve(argv['mcp-config']);
+}
+if (argv['strict-mcp-config']) {
+  process.env.B4M_STRICT_MCP_CONFIG = '1';
+}
+if (argv['append-system-prompt']) {
+  process.env.B4M_APPEND_SYSTEM_PROMPT = argv['append-system-prompt'];
+}
+if (argv.allowedTools && argv.allowedTools.length > 0) {
+  // Each element may itself be a space-separated list (the host's board pane passes
+  // "a b c" as a single argv token); flatten on whitespace into discrete patterns.
+  const patterns = argv.allowedTools.flatMap((s) => String(s).split(/\s+/)).filter(Boolean);
+  process.env.B4M_ALLOWED_TOOLS = JSON.stringify(patterns);
+}
+if (argv.settings) {
+  process.env.B4M_SETTINGS_JSON = argv.settings;
+}
+if (argv['session-id']) {
+  process.env.B4M_SESSION_ID = argv['session-id'];
+}
+if (argv.resume) {
+  process.env.B4M_RESUME_ID = argv.resume;
+}
+// Positional task (claude `<prompt>` form): seeds AND submits turn 1, stays interactive.
+// Only when it's not a known subcommand and headless -p wasn't used.
+const KNOWN_SUBCOMMANDS = new Set(['mcp', 'update', 'doctor']);
+if (argv.prompt === undefined && argv._.length > 0 && !KNOWN_SUBCOMMANDS.has(String(argv._[0]))) {
+  process.env.B4M_INITIAL_PROMPT = String(argv._[0]);
+}
 
 // Auto-detect environment: prefer production mode when dist exists
 const distPath = join(__dirname, '../dist/index.mjs');