s-app-scoder-agent 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sơn Nguyễn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,369 @@
-# Temporary Holding Version
+# scoder — Autonomous Coding Agent CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/nbhson/app-scoder-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/nbhson/app-scoder-agent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/app-scoder-agent)](https://www.npmjs.com/package/app-scoder-agent)
+
+**scoder** is a command-line coding agent that autonomously writes, edits, and builds code until your project compiles without errors. It mirrors the workflow of opencode, cline, and Claude Code, but runs as a single standalone CLI tool.
+
+## Installation
+
+**Requirements:** Node.js ≥ 18
+
+### Install from GitHub (current method)
+
+The package is not yet on the npm registry — install straight from this repo:
+
+```bash
+# Clones, builds (via the prepare script), and installs the `scoder` command globally
+npm install -g github:nbhson/app-scoder-agent
+```
+
+Or manually from a local clone:
+
+```bash
+git clone https://github.com/nbhson/app-scoder-agent.git
+cd app-scoder-agent
+npm install
+npm run build
+npm install -g .        # or: npm link
+```
+
+> Upgrading: pull the latest code and re-run `npm install -g .` (or point the global install at the repo again).
+
+### Try without installing
+
+```bash
+npx github:nbhson/app-scoder-agent "your task here"
+```
+
+### From npm (planned)
+
+Once published to the npm registry, installation will be a one-liner:
+
+```bash
+npm install -g app-scoder-agent
+# or run ad-hoc:
+npx app-scoder-agent "your task"
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+export SCODER_API_KEY=sk-...          # any OpenAI-compatible key (OpenAI, Groq, OpenRouter, Ollama, …)
+export OPENAI_BASE_URL=https://api.openai.com/v1  # optional, for custom endpoints
+
+# Run a task
+scoder "add a ping function to src/network.ts"
+
+# Interactive REPL
+scoder
+```
+
+## How It Works
+
+```
+You (task) → LLM plans → Tools execute code → Build runs → Success? → Done
+                              ↑                  |
+                              └── Build failed? ─┘ (auto-loop)
+```
+
+**Key constraint:** scoder runs autonomously without stopping for confirmation prompts. If the build fails, it reads the error, patches the code, and retries automatically — until the build passes or the max-step limit is reached.
+
+## Tool Set
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read a file with line numbers |
+| `write_file` | Overwrite/create a file |
+| `edit_file` | Find-and-replace (unique match required) |
+| `list_files` | Recursive directory listing |
+| `run_command` | Execute any shell command (subject to permission policy) |
+
+File writes (`write_file` / `edit_file`) are symlink-safe: paths are resolved via `realpath` and cannot escape the working directory, even through a malicious symlink. `read_file` refuses files larger than 2MB with guidance to use `grep`/`head`/`tail`.
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SCODER_API_KEY` | — | API key (required) |
+| `SCODER_MODEL` | `gpt-4o-mini` | Model name |
+| `SCODER_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible endpoint |
+| `SCODER_BUILD_CMD` | auto-detected | Build/compile command |
+| `SCODER_MAX_STEPS` | `40` | Max loop iterations before giving up |
+| `SCODER_PERMISSION` | `auto` | Permission mode: `auto` \| `ask` \| `readonly` |
+| `SCODER_STREAM` | `1` | `0` to disable streaming LLM output |
+| `SCODER_NO_APIKEY_WARNING` | — | Set to `1` to suppress the apiKey-in-rc warning |
+
+### Per-project config file (.scoderrc.json)
+
+For any OpenAI-compatible endpoint, just point `baseUrl`, `apiKey`, and `model` at it — no code changes needed. Create `.scoderrc.json` in your project root (see `.scoderrc.example.json`):
+
+```json
+{
+  "baseUrl": "https://api.groq.com/openai/v1",
+  "apiKey": "gsk_...",
+  "model": "llama-3.3-70b-versatile"
+}
+```
+
+Then simply run `scoder "your task"` — values are picked up automatically.
+
+#### All fields
+
+| Field | Default | Description |
+|---|---|---|
+| `baseUrl` | `https://api.openai.com/v1` | OpenAI-compatible endpoint (must support `/chat/completions` with tool calling) |
+| `apiKey` | — | API key (⚠️ prefer `SCODER_API_KEY` env var, see warning below) |
+| `model` | `gpt-4o-mini` | Model name served by the endpoint |
+| `buildCmd` | auto-detected | Build/compile command (stop condition) |
+| `maxSteps` | `40` | Max autonomous loop iterations |
+| `stream` | `true` | Stream LLM output token-by-token |
+| `provider` | auto-detected | `openai` \| `anthropic` |
+| `permission` | `auto` | `auto` \| `ask` \| `readonly` |
+| `mcpServers` | — | MCP stdio servers (see below) |
+| `permissions` | — | `{ mode, allowCommands, denyCommands }` |
+
+#### Precedence
+
+Values are merged from highest to lowest priority — your `.scoderrc.json` value only applies when no flag/env is set:
+
+1. **CLI flags** — `-m`, `--base-url`, `-k`, `--provider`, `-B`
+2. **Environment variables** — `SCODER_API_KEY` / `OPENAI_API_KEY`, `SCODER_BASE_URL`, `SCODER_MODEL`, …
+3. **`.scoderrc.json`** (or `.scoderrc`) in the project root — project-local only; there is no global rc file. For a machine-wide default, set the `SCODER_*` env vars in your shell profile instead
+4. Built-in defaults
+
+> 💡 If your config in `.scoderrc.json` seems ignored, check `echo $SCODER_API_KEY` — env vars override the file.
+
+#### Examples for common providers
+
+```jsonc
+// Local Ollama
+{
+  "baseUrl": "http://localhost:11434/v1",
+  "apiKey": "ollama",
+  "model": "qwen2.5-scoder:32b"
+}
+```
+
+```jsonc
+// DeepSeek
+{
+  "baseUrl": "https://api.deepseek.com/v1",
+  "apiKey": "sk-...",
+  "model": "deepseek-chat"
+}
+```
+
+#### Notes
+
+- Models starting with `claude-`, or a `baseUrl` containing `api.anthropic.com`, automatically switch to the native Anthropic provider — no `provider` field needed.
+- If an `apiKey` is present in the rc file, scoder prints a warning on every run. Silence it with `SCODER_NO_APIKEY_WARNING=1`.
+
+> ⚠️ **Security:** never commit `apiKey` in `.scoderrc.json` — add the file to `.gitignore` and prefer `SCODER_API_KEY` env var or the `-k` flag. A pre-commit check is available at `scripts/check-secrets.mjs`.
+
+## Permissions & Safety
+
+scoder ships with a layered permission system for `run_command`:
+
+| Mode | Behavior |
+|------|----------|
+| `auto` (default) | Autonomous — runs shell commands without confirmation (original behavior) |
+| `ask` | Prompts before each shell command not covered by `allowCommands` |
+| `readonly` | Shell commands are disabled entirely; the agent can only read/list files. MCP tools are also disabled (they bypass the permission policy) |
+
+Layered checks, in order:
+
+1. **Catastrophic deny list** — `rm -rf /`, `dd of=/dev/...`, fork bombs, `curl | sh`, etc. are **always denied**, in every mode.
+2. **`denyCommands`** (config) — always denied.
+3. **Session allowlist** — commands you approved with `[a] always allow` in this session.
+4. **`allowCommands`** (config) — auto-approved.
+5. **Mode** — `auto` runs everything else; `ask` prompts; `readonly` denies.
+
+In `ask` mode the prompt offers `[y] yes / [a] always allow "<prefix>" / [n] no / [q] quit`. With `-y` (non-interactive), commands needing confirmation are denied instead of hanging CI.
+
+## MCP Servers (stdio)
+
+scoder can use tools from [MCP](https://modelcontextprotocol.io) servers configured in `.scoderrc.json`:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" }
+    }
+  }
+}
+```
+
+- Tools are exposed to the LLM as `mcp__<server>__<tool>` (no name collisions with built-ins)
+- Servers connect at agent start; a failing server only logs a warning — the agent keeps running with its built-in tools
+- `{env:VAR}` substitution keeps secrets out of config files
+- Built-in tools always take priority over MCP tools with colliding names
+- ⚠️ **MCP tools bypass the built-in permission system** (no command classification, no diff preview). In `readonly` mode they are therefore disabled entirely; in `auto`/`ask` mode they run unsandboxed — only add MCP servers you trust.
+
+## Sessions
+
+Every run auto-saves its state (messages, steps, build result) to `.scoder/sessions/<id>.json` after each step. If the run is interrupted (Ctrl+C, crash, max steps), you can continue where it left off:
+
+```bash
+scoder list                      # list saved sessions
+scoder resume last               # continue the most recent session
+scoder resume <id> "follow-up"   # resume + add a new instruction
+```
+
+Sessions older than 7 days are pruned automatically on the next run. Use `--no-save` to disable (e.g. in CI).
+
+## Streaming
+
+LLM output is streamed token-by-token by default (`SCODER_STREAM=0` to disable). If a provider doesn't support streaming, scoder automatically falls back to non-streaming requests.
+
+## Logging
+
+Enable a structured JSONL event log with `--log-file` (or `SCODER_LOG_FILE=1`, or `SCODER_LOG_FILE=/path/to/log.jsonl`):
+
+```bash
+scoder --log-file "fix the failing test"
+cat .scoder/logs/<session-id>.jsonl | jq 'select(.type == "error")'
+```
+
+Events: `step` (with token usage), `tool` (args, ok, elapsedMs, denied reason), `build`, `finish`. One JSON object per line — pipe to `jq` or any log consumer.
+
+## Reliability
+
+scoder is designed for unattended use. Key guarantees:
+
+- **Request timeouts** — LLM calls have a 120s timeout; on timeout, the agent retries or fails gracefully (never hangs indefinitely).
+- **SIGINT handling** — pressing Ctrl+C cancels the in-flight LLM request immediately, kills the running shell command (SIGTERM → SIGKILL), saves the session, and exits with status 130. You can resume with `scoder resume last`.
+- **Graceful retries** — transient LLM API failures (HTTP 429/5xx, network errors) are retried with exponential backoff and jitter (up to 3 retries, honoring `Retry-After`). Client errors (401/403/404) fail fast.
+- **Double-build prevention** — when the agent itself runs the build command, scoder reuses that result instead of running the build twice.
+- **Build diff preview** — run `scoder --permission ask` to see a unified diff before every file write/edit.
+
+> **Design note:** the build command (stop condition) always runs without a permission prompt, even in `readonly` mode — the agent must be able to verify its stop condition. Builds are invoked as-is from your config (`buildCmd`) or auto-detection, never invented by the LLM. Shell commands *chosen by the LLM* (`run_command` tool) go through the full permission policy above.
+
+### Auto-detected build commands
+
+scoder detects the build command automatically:
+
+| Project type | Detected command |
+|---|---|
+| `package.json` with `scripts.build` | `npm run build` |
+| `Makefile` | `make` |
+| `go.mod` | `go build ./...` |
+| `Cargo.toml` | `cargo build` |
+| `tsconfig.json` | `npx tsc --noEmit` |
+| `pyproject.toml` | `python -m compileall .` |
+
+## CLI Options
+
+```
+scoder [options] "<task>"     Run a task autonomously until the build passes
+scoder                       Start interactive session
+scoder --help | --version     Help and version
+```
+
+| Flag | Description |
+|------|-------------|
+| `-m <model>` | Model to use |
+| `--base-url <url>` | OpenAI-compatible API base URL |
+| `-k <key>` | API key |
+| `-B, --build <cmd>` | Build command (stop condition) |
+| `-d, --dir <path>` | Working directory |
+| `-s, --max-steps <n>` | Max iterations (default 40) |
+| `--permission <mode>` | `auto` \| `ask` \| `readonly` shell-command policy (default `auto`) |
+| `-y` | Non-interactive mode (denies commands needing confirmation) |
+| `--provider <name>` | `openai` \| `anthropic` (env SCODER_PROVIDER; auto-detected) |
+| `--no-save` | Disable session auto-save to `.scoder/sessions/` |
+
+## Examples
+
+```bash
+# Run a task (auto-saves session to .scoder/sessions/)
+scoder -B "npm test" "fix the null pointer in UserService"
+
+# Resume after a crash or interrupt
+scoder resume last "now add unit tests for the fix"
+
+# Interactive mode with permission guard
+scoder --permission ask "npm install express and wire up a route"
+
+# Custom LLM (Groq, Ollama, vLLM, OpenRouter…)
+scoder --base-url https://api.groq.com/openai/v1 -k $GROQ_KEY \
+  "add input validation to the CLI"
+
+# Anthropic (auto-detected when model starts with 'claude-')
+scoder -m claude-sonnet-4-5 "refactor the parser module"
+
+# CI: non-interactive, no session saving
+scoder --no-save -y "run the full migration"
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  CLI (src/index.ts)                         │
+│   arg parsing, REPL, SIGINT handling        │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│  Agent (src/agent.ts)                       │
+│   Closed-loop orchestrator                  │
+│   history trimming, error injection         │
+└───────┬───────────────────────┬─────────────┘
+        │                       │
+┌───────▼───────┐    ┌─────────▼──────────┐
+│  LLM Client   │    │  Tool Registry       │
+│ (src/llm.ts)  │    │ (src/tools.ts)       │
+│ OpenAI compat │    │ read/write/run/list │
+└───────────────┘    └──────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────┐
+│  Build Checker (src/build.ts)               │
+│   run build → exit 0 = stop condition met   │
+└─────────────────────────────────────────────┘
+```
+
+## Integration Testing
+
+```bash
+npm test          # runs: lint → typecheck → build → 116 unit tests + e2e + MCP smoke
+npm run lint      # eslint flat config (typescript-eslint + eqeqeq, prefer-const...)
+npm run typecheck # tsc --noEmit
+```
+
+Test suites (run with `npm test` — auto-discovers `test/*.test.mjs`):
+- `test/permissions.test.mjs` — catastrophic patterns, mode classification, allowlist word-boundary, timeout-denies
+- `test/permission-prompt.test.mjs` — interactive prompt timeout behavior
+- `test/tools.test.mjs` — safePath traversal, symlink escape, file-size cap, write/edit/list
+- `test/core.test.mjs` — unified diff, retry backoff, context trimming
+- `test/config.test.mjs` — env/rc/cli precedence, logFile mapping, permission lists
+- `test/session.test.mjs` — session store, smart prune, resolve
+- `test/anthropic.test.mjs` — message translation + native SSE streaming
+- `test/llm.test.mjs` — OpenAI-compatible chat + SSE streaming + redaction
+- `test/run-e2e.mjs` — closed-loop integration (mock LLM server)
+- `test/run-mcp-test.mjs` — MCP smoke (mock stdio server)
+
+Coverage (lines): **90.3%** overall — see `npm run coverage`.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Task completed — build passed |
+| `1` | Build failed after max steps |
+| `2` | Fatal error (no API key, network error, etc.) |
+
+## License
+
+MIT