erosolar-cli 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,277 @@
+# Erosolar CLI
+
+Erosolar CLI is a modular, profile aware command-line assistant that bundles a locally running AI agent, tool runtime, and capability registry into a single npm package. It ships with both the balanced **Erosolar** profile (`general`) and the deterministic **Erosolar Code** profile (`erosolar-code`), plus a provider registry that can drive OpenAI, Anthropic, DeepSeek, xAI Grok, Google Gemini, or any custom LLM you register. The CLI bootstraps a structured workspace context, exposes file/search/bash tooling, and lets you opt into external capabilities (like Tavily web search) without editing source code.
+
+> This README is the canonical reference for the published npm module. Update it together with `SOURCE_OF_TRUTH.json` or `ARCHITECTURE.json` when behavior changes.
+
+## Why Erosolar CLI?
+
+- **Single binary experience** – `npm i -g erosolar-cli` installs the interactive `erosolar` command and ready-to-run TypeScript runtime.
+- **Profile aware** – switch between general reasoning or deterministic coding prompts via `/agents`, `--profile`, or environment overrides.
+- **Provider agnostic** – swap between OpenAI, Anthropic, DeepSeek, xAI, Gemini, or custom providers without forking the CLI.
+- **Deterministic tooling** – filesystem/search/bash tools log every invocation and emit reproducible summaries.
+- **Composable runtime** – plug in new `CapabilityModule`s or `ToolPlugin`s to expose internal APIs, SaaS connectors, or research workflows.
+- **Operator ergonomics** – bracketed paste handling, slash commands, saved preferences, and context summarization make long sessions manageable.
+
+## Installation
+
+### Prerequisites
+
+- Node.js **20.0.0 or newer** (check with `node -v`).
+- API keys for the models you plan to use (see [Provider support](#provider-support--api-keys)).
+- macOS/Linux shell. Windows works inside WSL2.
+
+### Install the CLI
+
+```bash
+npm install -g erosolar-cli        # global install
+# or keep it local
+npm install erosolar-cli --save-dev
+# or run ad-hoc without installing
+npx erosolar --version
+```
+
+Verify the install:
+
+```bash
+erosolar --help
+```
+
+The binary lives at `dist/bin/erosolar.js` and is exposed through the `erosolar` bin entry.
+
+## Quick Start
+
+1. **Launch the shell**
+   ```bash
+   erosolar                          # boots the default erosolar-code profile
+   erosolar --profile general        # balanced workflow
+   erosolar "Explain src/index.ts"   # run once without entering REPL
+   ```
+2. **Configure secrets** – inside the shell run `/secrets` and paste your `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc. Secrets are saved to `~/.codex/secrets.json` (override with `CODEX_HOME`).
+3. **Choose a model** – run `/model` to switch providers or presets (OpenAI GPT-5, Claude, DeepSeek, Grok, Gemini, …). Preferences persist in `~/.erosolar/settings.json`.
+4. **Toggle tools** – `/tools` enables/disables filesystem, search, bash, or Tavily suites per profile.
+5. **Chat or automate** – type instructions, paste code blocks (bracketed paste supported), or kick off `/agents` to switch the default profile for future launches.
+
+The shell prints every tool invocation (e.g., `Read(src/app.ts)`), shows diffs for writes, and summarizes bash output so you can audit what happened.
+
+## CLI Basics
+
+### Launch options
+
+- `erosolar` – start interactive mode (default profile `erosolar-code`).
+- `erosolar "Fix lint"` – run a single turn and exit.
+- `erosolar --profile general` / `-p general` – override profile.
+- `EROSOLAR_PROFILE=general erosolar` – set default profile via env var.
+
+### Slash commands
+
+| Command     | Description |
+|-------------|-------------|
+| `/model`    | Choose provider/model, temperature, max tokens, or thought level presets (direct/balanced/deep). |
+| `/secrets`  | List, add, or update API keys. Stored encrypted-at-rest in `~/.codex/secrets.json`. |
+| `/tools`    | Enable/disable capability suites (filesystem, search, bash, Tavily). Preferences save to `~/.erosolar/settings.json`. |
+| `/agents`   | (When enabled) switch the default profile for future launches. |
+| `/clear`    | Reset the working conversation. |
+| `/log`      | Show the recent transcript. |
+| `/exit`     | Quit the shell. |
+
+## Agent Profiles
+
+| Name            | Label          | Default provider/model | Intent | Env overrides |
+|-----------------|----------------|------------------------|--------|---------------|
+| `general`       | **Erosolar**   | OpenAI `gpt-5.1`       | Balanced research/writing/coding. | `GENERAL_MODEL`, `GENERAL_PROVIDER`, `GENERAL_SYSTEM_PROMPT` |
+| `erosolar-code` | **Erosolar Code** | OpenAI `gpt-5.1-codex` | Rapid, deterministic code edits with aggressive tool usage. | `EROSOLAR_CODE_MODEL`, `EROSOLAR_CODE_PROVIDER`, `EROSOLAR_CODE_SYSTEM_PROMPT` |
+
+Each profile is registered in `src/config.ts`. Add new profiles via `registerAgentProfile()` or override defaults with environment variables before launching the CLI. `EROSOLAR_PROFILE` selects which profile boots by default.
+
+## Provider support & API keys
+
+| Provider ID | Sample models | Required secret | CLI usage |
+|-------------|---------------|-----------------|-----------|
+| `openai`    | `gpt-5.1`, `gpt-5.1-codex`, `gpt-5-pro`, `gpt-5-mini`, `gpt-5-nano` | `OPENAI_API_KEY` | `/model → OpenAI` |
+| `anthropic` | `claude-sonnet-4.5`, `claude-opus-4.1`, `claude-haiku-4.5` | `ANTHROPIC_API_KEY` | `/model → Anthropic` |
+| `deepseek`  | `deepseek-reasoner`, `deepseek-chat` | `DEEPSEEK_API_KEY` | `/model → DeepSeek` |
+| `xai`       | `grok-4`, `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`, `grok-code-fast-1` | `XAI_API_KEY` | `/model → xAI` |
+| `google`    | `gemini-2.5-pro`, `gemini-2.5-flash` | `GEMINI_API_KEY` | `/model → Google Gemini` |
+| `tavily`    | `tavily_search`, `tavily_extract` tools | `TAVILY_API_KEY` | Enable via `/tools` |
+
+Secrets are read from environment variables first, then from `~/.codex/secrets.json`. Use `/secrets` to manage them interactively.
+
+## Built-in tools & capability suites
+
+The CLI composes tools via `CapabilityModule`s. The default Node runtime registers:
+
+- **Filesystem suite (`filesystemCapability.ts`)** – `read_file`, `write_file` (with diff previews), `list_files`, `search_files`. Uses deterministic ignore lists and protects against accidental binary writes.
+- **Search suite (`searchCapability.ts`)** – `grep_search`, `find_definition` over repo text. Regex friendly, case sensitive toggle, built-in binary detection.
+- **Bash suite (`bashCapability.ts`)** – `execute_bash` runs commands inside a sandbox rooted at `<workspace>/.erosolar/shell-sandbox`. HOME/TMP/XDG paths are rewritten unless `EROSOLAR_PRESERVE_HOME=1` is set. Streaming mode placeholder exists (`execute_bash_stream`).
+- **Tavily suite (`tavilyCapability.ts`)** – opt-in live web search/extract. Requires `TAVILY_API_KEY` and the `/tools` toggle.
+- **Runtime metadata tools (`core/toolRuntime.ts`)** – `context_snapshot`, `capabilities_overview`, `profile_details` for deterministic context recall.
+
+Tool invocations are narrated via the interactive shell (`Read(src/api.ts)`, `Bash(npm test)`). Warnings surface when tools are disabled or missing secrets so you can remediate without rerunning the CLI.
+
+## Workspace context & prompts
+
+On launch, `buildWorkspaceContext()` (see `src/workspace.ts`) captures:
+
+1. The current working directory path.
+2. A trimmed file tree (depth 2, up to 200 entries, ignoring `.git`, `node_modules`, `dist`).
+3. Contents/snippets of `README.md`, `SOURCE_OF_TRUTH.json`, `ARCHITECTURE.json`, and `package.json` when present.
+
+The snapshot is appended to the active system prompt and exposed via the `context_snapshot` tool so the agent always has a deterministic view of the repo even before reading files manually.
+
+## Architectural overview
+
+```
+┌────────────┐   ┌────────────────┐   ┌─────────────┐   ┌──────────────┐
+│ Interactive│→→│ AgentSession    │→→│ AgentRuntime │→→│ Provider SDK  │
+│ Shell      │   │ (profile/model │   │ (conversation│   │ (OpenAI, etc.)│
+│ (/model…)  │   │  resolution)   │   │  loop + tools)│   │              │
+└────┬───────┘   └────────┬───────┘   └──────┬──────┘   └──────┬───────┘
+     │ Workspace context        │ ToolRuntime/logging     │
+     ▼                         ▼                         ▼
+  Capability modules (filesystem/search/bash/Tavily/…) loaded via AgentHost/RuntimeAdapter
+```
+
+- **Interactive shell (`src/shell/interactiveShell.ts`)** renders prompts, manages slash commands, handles bracketed paste, streams assistant tokens, and persists preferences.
+- **AgentHost (`src/runtime/agentHost.ts`)** loads capability modules and resolves tool suites before the session starts.
+- **CapabilityModule interface** describes any pluggable feature: return tool suites, metadata, and teardown logic. Modules can be registered by adapters, plugins, or downstream apps.
+- **RuntimeAdapter (`src/adapters/types.ts`)** creates modules for specific targets (Node CLI, browser sandbox, server worker). The Node adapter wires in filesystem/search/bash/Tavily plugins.
+- **AgentSession (`src/runtime/agentSession.ts`)** resolves the profile config, builds the tool runtime, and instantiates providers.
+- **AgentRuntime (`src/core/agent.ts`)** runs the LLM loop, interleaving provider calls and tool execution.
+
+Thanks to this separation, you can reuse the runtime in Electron apps, remote agents, or serverless workers without rewriting orchestration.
+
+## Extending the CLI
+
+### Add a custom capability
+
+```ts
+import type { CapabilityModule, CapabilityContext, CapabilityContribution } from 'erosolar-cli/runtime';
+
+export class MyApiCapability implements CapabilityModule {
+  id = 'capability.my_api';
+  async create(context: CapabilityContext): Promise<CapabilityContribution> {
+    return {
+      id: 'my_api.tools',
+      description: 'Custom SaaS actions',
+      toolSuite: {
+        id: 'my-api',
+        tools: [
+          {
+            name: 'create_ticket',
+            description: 'Open a ticket via REST',
+            parameters: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
+            handler: async ({ title }) => {
+              const url = await createTicket(title as string, context.env.MY_API_TOKEN);
+              return `Opened ticket ${url}`;
+            },
+          },
+        ],
+      },
+    };
+  }
+}
+```
+
+Register it via a tool plugin:
+
+```ts
+import { registerToolPlugin } from 'erosolar-cli/plugins/tools';
+registerToolPlugin({
+  id: 'tool.my_api',
+  targets: ['node', 'cloud'],
+  create: () => new MyApiCapability(),
+});
+```
+
+### Register another provider
+
+```ts
+import { registerProvider } from 'erosolar-cli/providers/providerFactory.js';
+registerProvider('my-llm', (config) => new MyProviderSdk({
+  apiKey: process.env.MY_API_KEY!,
+  model: config.model,
+}));
+```
+
+Expose it through `/model` by adding presets in `src/shell/interactiveShell.ts`.
+
+### Add an agent profile
+
+```ts
+import { registerAgentProfile } from 'erosolar-cli/core/agentProfiles.js';
+registerAgentProfile({
+  name: 'docs',
+  label: 'Docs Agent',
+  description: 'Summaries only',
+  defaultProvider: 'openai',
+  defaultModel: 'gpt-5-mini',
+  defaultSystemPrompt: 'Only answer with documentation.',
+});
+```
+
+## Configuration reference
+
+- `EROSOLAR_PROFILE` – boot this profile unless `--profile` overrides it.
+- `<PROFILE>_MODEL`, `<PROFILE>_PROVIDER`, `<PROFILE>_SYSTEM_PROMPT` – lock a profile to custom defaults. Examples: `GENERAL_MODEL=claude-sonnet-4.5`, `EROSOLAR_CODE_SYSTEM_PROMPT="..."`.
+- `EROSOLAR_PRESERVE_HOME=1` – skip rewriting `$HOME`/`XDG_*` paths when running bash commands.
+- `CODEX_HOME` – change where CLI secrets are stored (defaults to `~/.codex`).
+- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `GEMINI_API_KEY`, `TAVILY_API_KEY` – provider credentials.
+- `GENERAL_MODEL`, `EROSOLAR_CODE_MODEL` – shorthand for the two built-in profiles.
+- `PATH`, `TMPDIR`, etc. – inherited by bash tools after sandboxing.
+
+User preferences (model presets, enabled tools, saved profile) live in `~/.erosolar/settings.json`.
+
+## Development workflow
+
+```bash
+git clone https://github.com/bo/bo-cli.git
+cd bo-cli
+npm install
+npm run dev        # ts-node/tsx entry for iterating without building
+npm run build      # clean + tsc compile to dist/
+npm run start      # run the compiled CLI
+npm run clean      # remove dist/
+```
+
+Notes:
+
+- The repo uses strict ES modules and TypeScript 5.3+.
+- `dist/bin/erosolar.js` must stay executable; `npm run postbuild` sets `chmod 755`.
+- Keep new files ASCII by default; use comments sparingly (see `apply_patch` guidelines in this repo).
+- `ARCHITECTURE.json`, `MODULAR_RUNTIME.md`, and `Agents.md` document the same defaults—update them if you change prompts or modules.
+
+## Release & publishing checklist
+
+1. Update docs/metadata (README, `package.json` description, architectural JSON files if needed).
+2. Run `npm run build` to refresh `dist/`.
+3. Inspect the diff and run any smoke tests (e.g., `npx tsx src/bin/erosolar.ts --version`).
+4. Bump the version: `npm version patch` (or `minor`/`major`) to keep npm in sync.
+5. Publish: `npm publish`.
+6. Verify on npmjs.com that the README renders and the new version lists the correct files.
+
+The `files` array in `package.json` already limits what goes to npm (`dist`, README, docs JSON, license, preinstall script).
+
+## Repository layout
+
+- `src/bin/erosolar.ts` – CLI entrypoint.
+- `src/shell/` – interactive shell UX, slash commands, tool logging.
+- `src/runtime/` – AgentHost, AgentSession, adapters.
+- `src/capabilities/` & `src/tools/` – filesystem/search/bash/Tavily implementations.
+- `src/plugins/` – provider + tool plugin registries.
+- `src/providers/` – LLM client shims (OpenAI Responses, Chat Completions, etc.).
+- `src/core/` – agent runtime, tool runtime, preferences, secrets.
+- `dist/` – compiled JS published to npm (generated by `npm run build`).
+
+## Troubleshooting
+
+- **“Missing required environment variable …”** – run `/secrets` or export the needed API key before launching. Provider plugins throw if secrets are absent.
+- **“Provider X is not registered”** – ensure you imported the plugin that registers it (`registerDefaultProviderPlugins()` is called automatically in `AgentSession`; custom runtimes must do the same).
+- **Filesystem writes fail or appear outside the repo** – bash commands run inside `<workspace>/.erosolar/shell-sandbox`. Set `EROSOLAR_PRESERVE_HOME=1` if you need real HOME access (only when safe).
+- **Context too large** – the shell automatically summarizes older transcripts when 90% of the context window is used, but you can force `/clear` to reset.
+- **Node <20** – install the required LTS (`nvm install 20 && nvm use 20`).
+- **Publishing errors** – ensure you are logged in to npm (`npm whoami`), bump the version, and verify `npm run build` before `npm publish`.
+
+## License
+
+MIT © Erosolar AI. See `LICENSE` for the full text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erosolar-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Modular Erosolar CLI with general + Erosolar Code profiles and pluggable providers",
   "main": "dist/bin/erosolar.js",
   "type": "module",
@@ -14,7 +14,7 @@
     "scripts/preinstall-clean-bins.mjs"
   ],
   "bin": {
-    "erosolar": "./dist/bin/erosolar.js"
+    "erosolar": "dist/bin/erosolar.js"
   },
   "scripts": {
     "preinstall": "node scripts/preinstall-clean-bins.mjs",