@rcrsr/rill-ext-claude-code 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,109 @@
+# @rcrsr/rill-ext-claude-code
+
+Rill extension for executing [Claude Code](https://docs.anthropic.com/en/docs/claude-code) operations from rill scripts. Provides `prompt`, `skill`, and `command` host functions with streaming output parsing, token tracking, and process lifecycle management.
+
+> **Experimental.** Breaking changes will occur until v1.0.
+
+## Install
+
+```bash
+npm install @rcrsr/rill-ext-claude-code
+```
+
+**Peer dependencies:** `@rcrsr/rill`, `node-pty`
+
+## Quick Start
+
+```typescript
+import { parse, execute, createRuntimeContext, prefixFunctions } from '@rcrsr/rill';
+import { createClaudeCodeExtension } from '@rcrsr/rill-ext-claude-code';
+
+const ext = createClaudeCodeExtension({ defaultTimeout: 60000 });
+const functions = prefixFunctions('claude_code', ext);
+const ctx = createRuntimeContext({ functions });
+
+const script = `claude_code::prompt("Explain TCP handshakes")`;
+const result = await execute(parse(script), ctx);
+
+await ext.dispose?.();
+```
+
+## Host Functions
+
+All functions return a dict with `result`, `tokens`, `cost`, `exitCode`, and `duration`.
+
+### claude_code::prompt(text, options?)
+
+Execute a Claude Code prompt.
+
+```rill
+claude_code::prompt("Analyze this code for security issues") => $response
+$response.result -> log
+$response.tokens.output -> log
+```
+
+### claude_code::skill(name, args?)
+
+Execute a Claude Code skill (slash command).
+
+```rill
+claude_code::skill("commit", [message: "fix: resolve login bug"])
+```
+
+### claude_code::command(name, args?)
+
+Execute a Claude Code command.
+
+```rill
+claude_code::command("review-pr", [pr: "123"]) => $review
+$review.result -> log
+```
+
+## Configuration
+
+```typescript
+const ext = createClaudeCodeExtension({
+  binaryPath: '/usr/local/bin/claude',  // default: 'claude'
+  defaultTimeout: 60000,                // default: 30000 (ms)
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `binaryPath` | string | `'claude'` | Path to Claude Code CLI binary |
+| `defaultTimeout` | number | `30000` | Default timeout in ms (max: 300000) |
+
+The factory validates the binary path and timeout eagerly. It throws if the binary is not found in `$PATH` or the timeout is out of range.
+
+## Result Shape
+
+```typescript
+interface ClaudeCodeResult {
+  result: string;      // combined text from assistant messages
+  tokens: TokenCounts; // prompt, cacheWrite5m, cacheWrite1h, cacheRead, output
+  cost: number;        // total cost in USD
+  exitCode: number;    // CLI process exit code (0 = success)
+  duration: number;    // execution duration in ms
+}
+```
+
+## Lifecycle
+
+Call `dispose()` on the extension to clean up active processes:
+
+```typescript
+const ext = createClaudeCodeExtension();
+// ... use extension ...
+await ext.dispose?.();
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Extensions Guide](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) | Extension contract and patterns |
+| [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) | Runtime context and host functions |
+
+## License
+
+MIT

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@rcrsr/rill-ext-claude-code",
-  "version": "0.1.0",
+  "version": "0.1.1",
+  "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "peerDependencies": {
     "node-pty": "^1.0.0",
-    "@rcrsr/rill": "^0.6.0"
+    "@rcrsr/rill": "^0.6.2"
   },
   "devDependencies": {
     "@types/which": "^3.0.4",
-    "@rcrsr/rill": "^0.6.0"
+    "@rcrsr/rill": "^0.6.2"
   },
   "files": [
     "dist"