@opencoven/coven-code 0.0.1

package/README.md

@@ -0,0 +1,145 @@
+# Coven Code
+
+A small Node CLI for local Coven Code workflows. It runs deterministic local
+command, thread, tool, MCP, skill, plugin, and SDK flows so integration behavior
+can be exercised end-to-end without a hosted service.
+
+## Quickstart
+
+```sh
+npm test
+npm start
+npm run coven-code -- --help
+npm run coven-code -- -x "what is 2+2?"
+echo "list markdown files" | npm run coven-code
+```
+
+The package exposes `coven-code` and `coven-code-sdk` bins.
+
+## Documentation
+
+- [CLI reference](docs/CLI.md) - commands, flags, interactive mode, execute mode, JSON streaming, and thread workflows
+- [Configuration](docs/CONFIGURATION.md) - settings files, environment variables, precedence, and common examples
+- [MCP, skills, and plugins](docs/MCP-SKILLS-PLUGINS.md) - extension points for tools, MCP servers, skills, and project plugins
+- [SDK](docs/SDK.md) - package exports, install helper, execution API, permissions, and thread helpers
+- [Development](docs/DEVELOPMENT.md) - repository layout, local checks, release notes, and safety expectations
+- [Coven Dogfood Protocol](docs/DOGFOOD-PROTOCOL.md) - daily task packets, harness assignment, handoff, verification, retrospectives, and issue capture
+
+## Interactive Mode
+
+Running `coven-code` with no arguments in a terminal starts the `neo-blessed`
+panel TUI. Type `/` in the composer to open the slash-command menu with live
+filtering and a details panel for commands, skills, and plugin actions.
+
+```text
+$ coven-code
+Coven Code 0.0.0-recreate
+/Users/example/project
+[chat]  lane   tools   threads   config   help    mode: smart   effort: high
+--------------------------------------------------------------------------------
+Ready. Type a prompt or /help.
+--------------------------------------------------------------------------------
+>
+```
+
+The classic readline REPL remains available for scripts, demos, and compatibility:
+
+```sh
+COVEN_CODE_REPL=1 coven-code
+```
+
+Line history is stored at `${XDG_CONFIG_HOME:-~/.config}/coven-code/repl_history`.
+Use `COVEN_CODE_REPL_HISTORY_FILE` to override the path or
+`COVEN_CODE_REPL_HISTORY=0` to disable history in the classic REPL.
+
+`COVEN_CODE_TUI_SCRIPTED=1` is reserved for deterministic tests and automation
+that need to drive the TUI with newline-separated input.
+
+## Execute Mode
+
+```sh
+coven-code -x "prompt"
+coven-code -x "see @README.md" </dev/null
+coven-code -x "..." --stream-json
+coven-code -x "..." --stream-json --stream-json-input < msgs.jsonl
+coven-code --continue T-... -x "continue a thread"
+coven-code --toolbox ./toolbox -x "use tb__my_tool"
+coven-code --skills ./skills -x "use the data-map skill"
+```
+
+Settings use the `covenCode.*` prefix. User settings live under
+`${XDG_CONFIG_HOME:-~/.config}/coven-code/settings.json`; workspace settings
+live under `.coven-code/settings.json`.
+
+Useful settings and env vars:
+
+- `covenCode.fuzzy.alwaysIncludePaths`
+- `covenCode.tools.enable` / `covenCode.tools.disable`
+- `covenCode.permissions`
+- `covenCode.commands.allowlist`
+- `covenCode.mcpServers`
+- `covenCode.mcpPermissions`
+- `covenCode.mcpRegistry.url`
+- `covenCode.notifications.enabled`
+- `covenCode.updates.mode`
+- `covenCode.defaultVisibility`
+- `COVEN_CODE_TOOLBOX`
+- `COVEN_CODE_API_KEY`
+- `COVEN_CODE_SKIP_UPDATE_CHECK`
+- `COVEN_CODE_FORCE_BEL`
+- `COVEN_CODE_CLI_PATH`
+- `COVEN_CODE_HOME`
+
+## Implemented Surface
+
+Core:
+
+- `coven-code --help`, `coven-code --version`
+- panel TUI with transcript, lane status, tabs, status rail, composer, keyboard shortcuts, and command palette
+- lane view for isolated worktree/branch context, harness selection, terminal output, changed files, diff summary, verification state, and PR/merge/cleanup status
+- compatibility REPL with `/new`, `/continue`, `/queue`, `/mode`, `/reasoning`, persistent history, and multiline prompts
+- command-palette aliases for thread archive, visibility, diagnostics, IDE, skills, plugins, and help
+- one-shot execute mode with `-x` / `--execute`
+- `@file`, glob, image, explicit thread, and `@@query` thread-search references
+- `--stream-json`, `--stream-json-thinking`, `--stream-json-input`, and `--reasoning-effort`
+- local persisted threads with labels, visibility, archive state, reports, and maps
+
+Tools and permissions:
+
+- built-in tools: `Bash`, `Read`, `Grep`, `glob`, `create_file`, `edit_file`, `undo_edit`, `Task`, `oracle`, `librarian`, `painter`, `mermaid`, `look_at`, `web_search`, `read_web_page`, `find_thread`, `finder`, and `read_mcp_resource`
+- `coven-code tools list|make|show|use`
+- toolbox discovery through `COVEN_CODE_TOOLBOX`, `--toolbox`, and `${XDG_CONFIG_HOME:-~/.config}/coven-code/tools`
+- `coven-code permissions list|add|edit|test`
+- delegated permission helpers receive `AGENT=coven-code` and `COVEN_CODE_THREAD_ID`
+
+MCP, skills, and plugins:
+
+- `coven-code mcp add|list|doctor|approve`
+- remote MCP headers, OAuth credential storage in `~/.coven-code/oauth`, token refresh, Streamable HTTP sessions, and SSE fallback
+- MCP registry enforcement that blocks unlisted servers and fails closed when the registry is unreachable
+- skill discovery from configured roots, `.agents/skills`, legacy `.claude/skills` roots, and built-ins
+- `coven-code skill list|show`
+- project plugins from `.coven-code/plugins/*.ts` and user plugins from `${XDG_CONFIG_HOME:-~/.config}/coven-code/plugins/*.ts`
+- plugin tools, commands, lifecycle events, configuration, status items, UI fallbacks, and helper APIs
+
+SDK:
+
+- `coven-code-sdk install [--force]`
+- package root exports `execute`, `createUserMessage`, `createPermission`, and `threads`
+- SDK execution streams local `coven-code --stream-json` messages
+- SDK options map to CLI args for cwd, env, mode, reasoning effort, thinking, labels, visibility, archive, continuation, settings, toolbox, skills, MCP config, permissions, enabled tools, system prompt, logging, and permission bypass
+
+## Development Checks
+
+Run the full local verification gate before committing or publishing:
+
+```sh
+git diff --check
+node ./bin/coven-code.mjs --help
+node ./bin/coven-code.mjs -x "what is 2+2?"
+npm test
+```
+
+The project is intentionally dependency-free at runtime. Keep new behavior
+covered in `test/cli.test.mjs`, avoid hosted-service assumptions, and keep
+examples deterministic.

package/bin/coven-code-sdk.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { runInstallCommand } from '../src/sdk-install.mjs';
+
+runInstallCommand(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exit(exitCode);
+  })
+  .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+  });

package/bin/coven-code.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { main, UsageError } from '../src/main.mjs';
+import { CLI_NAME } from '../src/constants.mjs';
+
+process.stdout.on('error', (error) => {
+  if (error?.code === 'EPIPE') process.exit(0);
+  throw error;
+});
+process.on('SIGPIPE', () => process.exit(0));
+
+main().catch((error) => {
+  if (error instanceof UsageError) {
+    console.error(`${CLI_NAME}: ${error.message}`);
+    console.error(`Run \`${CLI_NAME} --help\` for usage.`);
+    process.exit(2);
+  }
+  console.error(error.stack || String(error));
+  process.exit(1);
+});

package/docs/CLI.md

@@ -0,0 +1,192 @@
+# CLI Reference
+
+## Entry Points
+
+During development, run the CLI through npm:
+
+```sh
+npm run coven-code -- --help
+npm run coven-code -- -x "what is 2+2?"
+```
+
+Installed package binaries:
+
+```sh
+coven-code --help
+coven-code-sdk install
+```
+
+The direct local entrypoint is:
+
+```sh
+node ./bin/coven-code.mjs
+```
+
+## Interactive Mode
+
+Run with no arguments in a TTY:
+
+```sh
+coven-code
+```
+
+The default interactive surface is a full-screen `neo-blessed` panel TUI with a
+transcript, tabs, compact status line, command palette, slash-command menu, and
+composer. It keeps a current local thread and accepts slash commands:
+
+```text
+Coven Code 0.0.0-recreate
+[chat]  lane   tools   threads   config   help    mode: smart   effort: high
+--------------------------------------------------------------------------------
+Ready. Type a prompt or /help.
+--------------------------------------------------------------------------------
+> /help
+```
+
+Supported interactive behaviors include:
+
+- panel tabs for chat, lane, tools, threads, config, and help
+- `/lane refresh` to load current worktree, branch, changed files, and diff summary
+- `/lane harness <smart|deep|rush|large|next>` to select the active lane harness
+- `/lane verify` to run the detected verification command and keep its output in the lane panel
+- `/lane status` and `/lane diff` to inspect the visible lane model
+- `/` opens a filtered command menu with details for built-ins, skills, and
+  plugin commands
+- Tab completes the selected slash command; Enter accepts it; Esc closes the menu
+- command palette actions for common thread and tool workflows
+- persistent line history
+- `/new` to start a fresh thread
+- `/continue` to resume a thread
+- `/queue` to queue a follow-up prompt
+- `/mode` to inspect or change the active mode
+- `/reasoning` to inspect or change reasoning effort
+- command aliases for tools, skills, plugins, threads, diagnostics, and IDE
+  inspection
+- multiline prompts with trailing backslash continuation
+
+Use the classic readline REPL explicitly when a plain prompt is better for
+scripts, demos, or compatibility:
+
+```sh
+COVEN_CODE_REPL=1 coven-code
+```
+
+Disable classic REPL history for demos or tests:
+
+```sh
+COVEN_CODE_REPL_HISTORY=0 coven-code
+```
+
+`COVEN_CODE_TUI_SCRIPTED=1` is a deterministic test and automation hook for
+feeding newline-separated TUI input. It is not intended as a normal user mode.
+
+## Execute Mode
+
+Use `--execute` or `-x` for one turn and exit:
+
+```sh
+coven-code -x "what is 2+2?"
+coven-code -x "summarize @README.md"
+coven-code --continue T-example -x "continue this thread"
+```
+
+Piped stdin is combined with the prompt:
+
+```sh
+echo "list markdown files" | coven-code
+echo "additional context" | coven-code -x "answer using this context"
+```
+
+`-x`, `--stream-json`, `--stream-json-input`, stdin piping, and subcommands
+keep their existing noninteractive behavior; the panel TUI only changes the
+bare no-argument TTY path.
+
+## File, Image, Glob, and Thread References
+
+Execute prompts can reference local context:
+
+```sh
+coven-code -x "summarize @README.md"
+coven-code -x "inspect @docs/*.md"
+coven-code -x "describe @image.png"
+coven-code -x "compare this with @T-existing-thread"
+coven-code -x "continue from @@search words"
+```
+
+Text references are capped to keep prompts bounded. Binary files are skipped
+unless handled as supported media references.
+
+## Stream JSON
+
+Use `--stream-json` for structured JSONL suitable for frontends and SDKs:
+
+```sh
+coven-code -x "what is 2+2?" --stream-json
+coven-code -x "inspect this" --stream-json --stream-json-thinking
+```
+
+Use `--stream-json-input` to read user messages from JSONL stdin:
+
+```sh
+coven-code --stream-json --stream-json-input < messages.jsonl
+```
+
+Stream JSON emits initialization, user, assistant, tool use, tool result, and
+final result messages.
+
+## Tools
+
+```sh
+coven-code tools list
+coven-code tools show Bash
+coven-code tools make --bash my-tool
+coven-code tools use tb__my-tool
+```
+
+Built-in tools include `Bash`, `Read`, `Grep`, `glob`, `create_file`,
+`edit_file`, `undo_edit`, `Task`, `oracle`, `librarian`, `painter`, `mermaid`,
+`look_at`, `web_search`, `read_web_page`, `find_thread`, `finder`, and
+`read_mcp_resource`.
+
+## Permissions
+
+```sh
+coven-code permissions list
+coven-code permissions list --builtin
+coven-code permissions add allow Bash command.name git
+coven-code permissions test Bash command.name git
+```
+
+Permission rules can allow or reject tool calls by tool name, action, command,
+arguments, server names, URLs, and nested context fields.
+
+## Threads
+
+```sh
+coven-code threads list
+coven-code threads show T-example
+coven-code threads search "query"
+coven-code threads continue T-example -x "follow up"
+coven-code threads archive T-example
+coven-code threads visibility T-example workspace
+coven-code threads map T-example
+coven-code threads report T-example
+```
+
+Threads are local records that preserve prompts, labels, visibility, archive
+state, diagnostic reports, and reference edges.
+
+## Other Commands
+
+```sh
+coven-code login
+coven-code update
+coven-code usage
+coven-code review
+coven-code config edit
+coven-code config edit --workspace
+coven-code ide connect
+coven-code agents-md list
+```
+
+`agents list` is an alias for `agents-md list`.

package/docs/CONFIGURATION.md

@@ -0,0 +1,107 @@
+# Configuration
+
+## Settings Files
+
+Coven Code reads settings from these places:
+
+- user settings: `${XDG_CONFIG_HOME:-~/.config}/coven-code/settings.json`
+- workspace settings: `.coven-code/settings.json`
+- explicit settings file: `--settings-file <path>`
+- managed settings used by tests and embedding environments
+
+Settings use the `covenCode.*` namespace.
+
+Workspace settings override user settings where both define the same key.
+Managed settings override both. Explicit command-line flags override settings
+for the current run.
+
+## Editing Settings
+
+```sh
+coven-code config edit
+coven-code config edit --workspace
+```
+
+Settings files may use JSONC syntax, including comments and trailing commas.
+
+## Common Settings
+
+```jsonc
+{
+  "covenCode.tools.disable": ["web_search"],
+  "covenCode.tools.enable": ["Bash", "Read", "Grep"],
+  "covenCode.commands.allowlist": ["git", "npm", "node"],
+  "covenCode.permissions": [
+    {
+      "effect": "allow",
+      "tool": "Bash",
+      "match": {
+        "command.name": "git"
+      }
+    }
+  ],
+  "covenCode.mcpServers": {
+    "local-tools": {
+      "command": "node",
+      "args": ["./tools/server.mjs"]
+    }
+  },
+  "covenCode.mcpPermissions": [],
+  "covenCode.mcpRegistry.url": "https://example.invalid/registry.json",
+  "covenCode.notifications.enabled": true,
+  "covenCode.updates.mode": "skip",
+  "covenCode.defaultVisibility": "workspace",
+  "covenCode.showCosts": true
+}
+```
+
+## Environment Variables
+
+```sh
+COVEN_CODE_API_KEY
+COVEN_CODE_HOME
+COVEN_CODE_CLI_PATH
+COVEN_CODE_TOOLBOX
+COVEN_CODE_REPL_HISTORY
+COVEN_CODE_REPL_HISTORY_FILE
+COVEN_CODE_SKIP_UPDATE_CHECK
+COVEN_CODE_FORCE_BEL
+COVEN_CODE_URL
+```
+
+`COVEN_CODE_HOME` controls the local state root used by SDK-managed installs
+and tests. `COVEN_CODE_CLI_PATH` points SDK execution at a specific CLI binary.
+
+Use isolated state for demos and tests:
+
+```sh
+COVEN_CODE_HOME="$(mktemp -d)" \
+XDG_CONFIG_HOME="$(mktemp -d)" \
+COVEN_CODE_REPL_HISTORY=0 \
+COVEN_CODE_SKIP_UPDATE_CHECK=1 \
+npm run coven-code -- -x "what is 2+2?"
+```
+
+## Visibility
+
+Thread visibility accepts:
+
+- `private`
+- `public`
+- `workspace`
+- `group`
+- `unlisted`
+
+SDK compatibility maps documented team visibility to workspace visibility.
+
+## Permissions Model
+
+Permission rules are evaluated before tool execution. Built-in defaults can be
+listed with:
+
+```sh
+coven-code permissions list --builtin
+```
+
+Workspace permission settings override user settings. This keeps repository
+policy close to the project under test.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,104 @@
+# Development
+
+## Requirements
+
+- Node.js 20 or newer
+- npm for this package's current lockfile and scripts
+
+The runtime intentionally has a small dependency surface. `neo-blessed` owns the
+live panel TUI so Coven Code does not maintain a fragile raw escape-code input
+loop. Keep any future dependency additions similarly narrow and justified.
+
+## Repository Layout
+
+```text
+bin/                    CLI entrypoints
+docs/                   User-facing documentation
+src/agent/              Local deterministic agent behavior
+src/cli/                Argument parsing, TUI/REPL, references, stream helpers
+src/commands/           Top-level command implementations
+src/mcp/                MCP discovery, permissions, probing, registry checks
+src/plugins/            Project/user plugin discovery and lifecycle
+src/settings/           Settings paths and merge logic
+src/skills/             Skill discovery and built-in skills
+src/threads/            Local thread persistence
+src/tools/              Built-in and toolbox tool surfaces
+test/                   Node test suite
+```
+
+## Local Verification
+
+Run this before every commit:
+
+```sh
+git diff --check
+node ./bin/coven-code.mjs --help
+node ./bin/coven-code.mjs -x "what is 2+2?"
+npm test
+```
+
+Expected result:
+
+- no whitespace errors
+- help renders
+- execute mode prints `4`
+- test suite exits with zero failures
+
+## Isolated Demo State
+
+Use temporary state when demonstrating the CLI so the run does not write to the
+operator's normal config or REPL history:
+
+```sh
+COVEN_CODE_HOME="$(mktemp -d)" \
+XDG_CONFIG_HOME="$(mktemp -d)" \
+COVEN_CODE_REPL_HISTORY=0 \
+COVEN_CODE_SKIP_UPDATE_CHECK=1 \
+npm run coven-code -- -x "what is 2+2?"
+```
+
+For interactive demos, bare `coven-code` opens the `neo-blessed` panel TUI. Use
+`/` in the composer to verify the slash-command menu, filtering, details panel,
+Tab completion, Enter acceptance, and Esc close behavior. Use the classic
+readline surface only when the demo needs a plain prompt:
+
+```sh
+COVEN_CODE_REPL=1 \
+COVEN_CODE_REPL_HISTORY=0 \
+COVEN_CODE_SKIP_UPDATE_CHECK=1 \
+npm run coven-code
+```
+
+`COVEN_CODE_TUI_SCRIPTED=1` is reserved for deterministic TUI tests and
+automation. It feeds newline-separated input through the TUI loop without
+changing execute mode, stream JSON, stdin piping, or subcommand behavior.
+
+## Testing Expectations
+
+Add or update tests in `test/cli.test.mjs` for any CLI behavior change. TUI
+changes should cover the model/renderer, key handling, scripted smoke path, and
+classic REPL compatibility when needed. Slash-command changes should test the
+catalog source and at least one rendered/filtering TUI state. Prefer
+deterministic local tests over network calls. When a feature integrates with MCP,
+plugins, skills, or toolbox tools, test both discovery and execution paths.
+
+## Safety
+
+- Do not commit secrets, tokens, generated credentials, or local config state.
+- Keep examples deterministic and local.
+- Keep docs and command help aligned.
+- Do not rely on hosted services for default behavior.
+- Keep private workspace paths and machine-specific URLs out of docs.
+
+## Release Notes
+
+The package currently uses version `0.0.0` while the CLI surface is rebuilt.
+Before publishing, update versioning deliberately and verify:
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+The `.npmignore` file excludes internal superpowers planning notes while
+including the user-facing docs in this directory.