iosm-cli 0.1.0

package/docs/configuration.md

@@ -0,0 +1,301 @@
+# Configuration & Environment
+
+Complete reference for `iosm-cli` settings, environment variables, profiles, and permission controls.
+
+---
+
+## Configuration Directories
+
+### Global (User-Level)
+
+```
+~/.iosm/agent/
+├── settings.json          # Global settings
+├── mcp.json               # User MCP servers
+├── models.json            # Model configuration and preferences
+├── auth.json              # Provider credentials (OAuth + API keys via /login)
+├── keybindings.json       # Custom keyboard shortcuts
+├── extensions/            # Global extensions (auto-discovered)
+├── skills/                # Global skills
+├── prompts/               # Global prompt templates
+├── themes/                # Global TUI themes
+├── sessions/              # Persisted sessions
+└── session-traces/        # JSONL trace files
+```
+
+### Project-Level
+
+```
+.iosm/
+├── settings.json          # Project-specific settings
+├── extensions/            # Project extensions
+├── skills/                # Project skills
+├── prompts/               # Project prompt templates
+├── themes/                # Project themes
+├── agents/                # Custom agent definitions
+├── subagents/             # Subagent run transcripts
+│   ├── runs/
+│   └── teams/
+└── cycles/                # IOSM cycle artifacts
+
+.mcp.json                  # Project MCP servers (repository root)
+```
+
+---
+
+## Settings Hierarchy
+
+Settings are merged in this order (later wins):
+
+```
+1. Global settings    (~/.iosm/agent/settings.json)   ← lowest priority
+2. Project settings   (.iosm/settings.json)
+3. CLI flags                                            ← highest priority
+```
+
+### Settings File Example
+
+```json
+{
+  "model": {
+    "provider": "anthropic",
+    "id": "claude-sonnet-4-20250514",
+    "thinking": "medium"
+  },
+  "tools": {
+    "enabled": ["read", "bash", "edit", "write", "grep", "find", "ls"],
+    "bashTimeout": 30000,
+    "maxOutputLines": 2000
+  },
+  "session": {
+    "autoCompact": true,
+    "compactThreshold": 100000,
+    "maxRetries": 3
+  },
+  "terminal": {
+    "shell": "/bin/zsh",
+    "cols": 120
+  },
+  "permissions": {
+    "autoApprove": false
+  }
+}
+```
+
+## MCP Configuration
+
+Manage MCP servers from CLI and interactive mode:
+
+```bash
+# CLI
+iosm mcp list
+iosm mcp add filesystem --transport stdio --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --arg .
+iosm mcp tools
+
+# Interactive
+/mcp
+/mcp add                      # guided wizard
+/mcp add filesystem --transport stdio --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --arg .
+```
+
+MCP configs are loaded with project override precedence:
+
+1. `~/.iosm/agent/mcp.json`
+2. `.mcp.json` (project root)
+
+---
+
+## Environment Variables
+
+### Provider API Keys
+
+| Variable | Provider | Notes |
+|----------|----------|-------|
+| `ANTHROPIC_API_KEY` | Anthropic (Claude) | Primary recommended provider |
+| `OPENAI_API_KEY` | OpenAI (GPT) | |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI | Requires endpoint config |
+| `GEMINI_API_KEY` | Google Gemini | |
+| `GROQ_API_KEY` | Groq | |
+| `CEREBRAS_API_KEY` | Cerebras | |
+| `XAI_API_KEY` | xAI (Grok) | |
+| `OPENROUTER_API_KEY` | OpenRouter | Multi-provider gateway |
+| `MISTRAL_API_KEY` | Mistral | |
+| `MINIMAX_API_KEY` | MiniMax | |
+| `KIMI_API_KEY` | Kimi | |
+| `OPENCODE_API_KEY` | OpenCode | |
+| `AI_GATEWAY_API_KEY` | AI Gateway | |
+| `AWS_PROFILE` | AWS Bedrock | Also: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` |
+
+### Runtime Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `IOSM_CODING_AGENT_DIR` | `~/.iosm/agent` | Override global config directory |
+| `IOSM_PACKAGE_DIR` | Auto | Override package base directory |
+| `IOSM_OFFLINE` | `false` | Disable startup network operations (`1`/`true`/`yes`) |
+| `IOSM_SESSION_TRACE` | `false` | Enable JSONL session trace logging |
+| `IOSM_SESSION_TRACE_DIR` | Auto | Override trace directory location |
+| `IOSM_SHARE_VIEWER_URL` | Default | Custom base URL for `/share` links |
+| `IOSM_AI_ANTIGRAVITY_VERSION` | Auto | Override Antigravity user-agent version |
+| `IOSM_SKIP_VERSION_CHECK` | `false` | Disable update/version checks |
+
+### Example: Shell Configuration
+
+Add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+# Provider key
+export ANTHROPIC_API_KEY="sk-ant-api03-..."
+
+# Optional: enable tracing
+export IOSM_SESSION_TRACE=1
+export IOSM_SESSION_TRACE_DIR="$HOME/.iosm/traces"
+
+# Optional: offline mode for air-gapped environments
+# export IOSM_OFFLINE=1
+```
+
+---
+
+## Profiles
+
+Profiles control the agent's behavior, available tools, and system prompt.
+
+### Primary Profiles
+
+| Profile | Tools | Behavior |
+|---------|-------|----------|
+| `full` | All (read, bash, edit, write, grep, find, ls) | Default full development capabilities |
+| `plan` | Read-only (read, grep, find, ls) | Architecture planning and code review |
+| `iosm` | All + IOSM context | IOSM cycle execution with artifact synchronization |
+
+### Advanced Profiles
+
+| Profile | Use Case |
+|---------|----------|
+| `explore` | Exploratory codebase analysis |
+| `iosm_analyst` | Deep IOSM metric analysis |
+| `iosm_verifier` | IOSM quality gate verification |
+| `cycle_planner` | IOSM cycle planning specialist |
+
+### Usage
+
+```bash
+# CLI flag
+iosm --profile plan
+iosm --profile iosm
+
+# Interactive: cycle with Shift+Tab
+# full → plan → iosm → full → ...
+
+# In orchestration
+/orchestrate --profiles explore,full,iosm_verifier
+```
+
+---
+
+## Permissions
+
+Permissions control tool execution approval behavior.
+
+### Interactive Commands
+
+```bash
+# View current permission status
+/permissions
+
+# Enable auto-approve (YOLO mode)
+/yolo on
+
+# Disable auto-approve
+/yolo off
+
+# Check status
+/yolo status
+```
+
+### What Permissions Control
+
+- **Tool calls**: Whether the agent can execute tools without user confirmation
+- **File writes**: Whether `edit` and `write` tools require approval
+- **Shell commands**: Whether `bash` executions require approval
+- **Destructive actions**: Special handling for `rm`, `sudo`, etc.
+
+### Safety Defaults
+
+By default, `iosm-cli` asks for confirmation before:
+- Executing shell commands
+- Writing or editing files
+- Performing destructive operations
+
+Use extensions like `permission-gate.ts` or `protected-paths.ts` for additional safety layers.
+
+---
+
+## Provider-Specific Configuration
+
+### Anthropic
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-api03-..."
+
+iosm --model claude-sonnet-4-20250514
+iosm --model sonnet:high          # With thinking
+```
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY="sk-..."
+
+iosm --model gpt-4o
+iosm --model openai/gpt-4o-mini
+```
+
+### Google Gemini
+
+```bash
+export GEMINI_API_KEY="AI..."
+
+iosm --model gemini-2.5-pro
+```
+
+### AWS Bedrock
+
+```bash
+export AWS_PROFILE="default"
+# or
+export AWS_ACCESS_KEY_ID="..."
+export AWS_SECRET_ACCESS_KEY="..."
+export AWS_REGION="us-east-1"
+
+iosm --provider bedrock --model anthropic.claude-v2
+```
+
+### Azure OpenAI
+
+```bash
+export AZURE_OPENAI_API_KEY="..."
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
+
+iosm --provider azure --model gpt-4o
+```
+
+### OAuth-Based Providers
+
+Some providers support OAuth login (for example, Qwen CLI free OAuth):
+
+```bash
+iosm
+# In interactive mode:
+/login
+# Follow the authentication flow
+```
+
+---
+
+## Further Reading
+
+- [CLI Reference](./cli-reference.md) — All command-line flags
+- [Interactive Mode](./interactive-mode.md) — Keybindings and slash commands
+- [Extensions](./extensions-packages-themes.md) — Extension system and customization

package/docs/development-and-testing.md

@@ -0,0 +1,295 @@
+# Development & Testing
+
+Guide for contributing to `iosm-cli` — repository layout, build system, testing, and release process.
+
+---
+
+## Repository Layout
+
+```
+iosm-cli/
+├── src/                          # Application source (TypeScript)
+│   ├── cli.ts                    # CLI entry point
+│   ├── main.ts                   # Main application logic
+│   ├── config.ts                 # Path resolution and configuration
+│   ├── index.ts                  # Public SDK exports
+│   ├── migrations.ts             # Session/settings migrations
+│   ├── cli/                      # CLI argument parsing
+│   │   ├── args.ts               # Argument definitions and parsing
+│   │   ├── config-selector.ts    # Config selection UI
+│   │   ├── file-processor.ts     # @file attachment handling
+│   │   ├── list-models.ts        # --list-models implementation
+│   │   └── session-picker.ts     # --resume session selection
+│   ├── core/                     # Runtime engine
+│   │   ├── agent-session.ts      # Core agent session (main loop)
+│   │   ├── agent-profiles.ts     # Profile definitions
+│   │   ├── agent-teams.ts        # Team orchestration
+│   │   ├── model-registry.ts     # Multi-provider model registry
+│   │   ├── model-resolver.ts     # Model matching and resolution
+│   │   ├── session-manager.ts    # Session persistence engine
+│   │   ├── settings-manager.ts   # Settings hierarchy
+│   │   ├── package-manager.ts    # Package install/remove/update
+│   │   ├── resource-loader.ts    # Extension/skill/prompt/theme loader
+│   │   ├── subagents.ts          # Subagent orchestration
+│   │   ├── parallel-task-agent.ts # Parallel task execution
+│   │   ├── sdk.ts                # Public SDK factory
+│   │   ├── system-prompt.ts      # System prompt construction
+│   │   ├── hooks.ts              # Hook system
+│   │   ├── skills.ts             # Skill discovery and loading
+│   │   ├── prompt-templates.ts   # Prompt template system
+│   │   ├── bash-executor.ts      # Shell command execution
+│   │   ├── tools/                # Built-in tools
+│   │   │   ├── read.ts           # File reading
+│   │   │   ├── bash.ts           # Shell execution
+│   │   │   ├── edit.ts           # File editing
+│   │   │   ├── write.ts          # File creation
+│   │   │   ├── grep.ts           # Content search
+│   │   │   ├── find.ts           # File finding
+│   │   │   ├── ls.ts             # Directory listing
+│   │   │   ├── task.ts           # Task management
+│   │   │   └── todo.ts           # Todo tool
+│   │   ├── extensions/           # Extension system
+│   │   ├── compaction/           # Context compaction
+│   │   └── export-html/          # HTML export templates
+│   ├── iosm/                     # IOSM methodology
+│   │   ├── init.ts               # Workspace bootstrapping
+│   │   ├── cycle.ts              # Cycle lifecycle
+│   │   ├── metrics.ts            # Metric calculation
+│   │   ├── config.ts             # IOSM config parsing
+│   │   ├── automation.ts         # IOSM autopilot
+│   │   ├── guide.ts              # Playbook generation
+│   │   ├── agent-verification.ts # Post-init verification
+│   │   └── types.ts              # IOSM type definitions
+│   ├── modes/                    # Output modes
+│   │   ├── interactive/          # TUI (43 files)
+│   │   ├── rpc/                  # JSON-RPC server
+│   │   └── print-mode.ts         # Single-shot print
+│   └── utils/                    # Utilities
+│       ├── git.ts                # Git operations
+│       ├── shell.ts              # Shell config detection
+│       ├── clipboard.ts          # Clipboard access
+│       ├── image-resize.ts       # Image processing
+│       └── ...
+├── test/                         # Vitest test suite (73 files)
+├── examples/
+│   ├── extensions/               # 66 extension examples
+│   └── sdk/                      # 12 SDK examples
+├── docs/                         # Documentation
+├── scripts/                      # Build/migration scripts
+├── iosm-spec.md                  # IOSM methodology specification
+├── package.json
+├── tsconfig.base.json            # Base TypeScript config
+├── tsconfig.build.json           # Build config
+├── tsconfig.examples.json        # Examples config
+└── vitest.config.ts              # Test configuration
+```
+
+---
+
+## Build Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| Install | `npm install` | Install all dependencies |
+| Type-check | `npm run check` | Run TypeScript type-checking without emit |
+| Build | `npm run build` | Compile TypeScript + copy assets |
+| Watch | `npm run dev` | Watch mode for development |
+| Test | `npm test` | Run full Vitest test suite |
+| Clean | `npm run clean` | Remove `dist/` directory |
+| Binary | `npm run build:binary` | Build standalone Bun binary |
+| Deploy Local | `npm run deploy-local` | Build and sync to global install |
+
+### Development Workflow
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Start watch mode (rebuilds on file changes)
+npm run dev
+
+# 3. In another terminal, run your local build
+node dist/cli.js
+
+# Or link globally for testing
+npm link
+iosm
+```
+
+### Type-Checking
+
+```bash
+# Quick type check
+npm run check
+
+# Watch mode with type-checking
+npx tsc -p tsconfig.build.json --watch --noEmit
+```
+
+---
+
+## Testing
+
+Tests are written with [Vitest](https://vitest.dev/) and run in Node.js environment.
+
+### Running Tests
+
+```bash
+# Full test suite
+npm test
+
+# Single test file
+npm test -- test/tools.test.ts
+
+# Tests matching a pattern
+npm test -- --grep "session"
+
+# Watch mode
+npx vitest --watch
+
+# With coverage
+npx vitest --coverage
+```
+
+### Test Structure
+
+Tests are organized by feature area:
+
+| Area | Test Files | Coverage |
+|------|-----------|----------|
+| **Tools** | `tools.test.ts` | All 7 built-in tools |
+| **Session** | `session-manager/`, `session-*.test.ts` | Persistence, branching, migration |
+| **Extensions** | `extensions-*.test.ts` | Discovery, running, hooks, input events |
+| **Compaction** | `compaction*.test.ts` | Context summarization |
+| **Model** | `model-registry.test.ts`, `model-resolver.test.ts` | Multi-provider model management |
+| **IOSM** | `iosm-*.test.ts` | Init, cycles, metrics, automation |
+| **CLI** | `args.test.ts` | Argument parsing |
+| **Packages** | `package-manager*.test.ts` | Package install/update/remove |
+| **RPC** | `rpc.test.ts` | JSON-RPC protocol |
+| **SDK** | `sdk-*.test.ts` | Programmatic API |
+| **Subagents** | `subagent*.test.ts` | Orchestration |
+| **UI** | `interactive-mode-status.test.ts`, etc. | TUI components |
+
+### Writing Tests
+
+```typescript
+import { describe, it, expect } from "vitest";
+
+describe("MyFeature", () => {
+  it("should do the expected thing", async () => {
+    const result = await myFunction();
+    expect(result).toBe(expected);
+  });
+});
+```
+
+### Test Notes
+
+- Some integration tests require network access and are skipped when prerequisites are absent
+- Tests use a shared `utilities.ts` for common test helpers and fixtures
+- Test fixtures are stored in `test/fixtures/`
+
+---
+
+## Migration & Maintenance
+
+### Session Migration
+
+For migrating sessions from older formats:
+
+```bash
+bash scripts/migrate-sessions.sh
+```
+
+### Configuration Fallbacks
+
+Runtime path and config fallback logic lives in `src/config.ts`. This handles:
+- User agent directory resolution
+- Version detection
+- Legacy path compatibility
+
+### Documentation Alignment
+
+When adding CLI features, keep in sync:
+1. `src/cli/args.ts` — Argument definitions
+2. `docs/cli-reference.md` — User-facing documentation
+3. `README.md` — If the feature is significant
+
+---
+
+## Release Hygiene
+
+### Pre-Release Checklist
+
+```bash
+# 1. Type-check passes
+npm run check
+
+# 2. All tests pass
+npm test
+
+# 3. Build succeeds
+npm run build
+
+# 4. Verify documentation
+#    - README.md reflects current CLI behavior
+#    - docs/ are up to date
+#    - CHANGELOG.md has new entries
+
+# 5. .gitignore covers all generated artifacts
+#    - dist/, node_modules/, .iosm/, coverage/
+```
+
+### Publishing
+
+```bash
+# Runs clean + build automatically via prepublishOnly
+npm publish
+```
+
+---
+
+## Architecture Overview
+
+```
+┌────────────────────────────────────────────────┐
+│                    CLI Layer                     │
+│  cli.ts → args.ts → main.ts                    │
+├────────────────────────────────────────────────┤
+│                   Mode Layer                     │
+│  Interactive Mode │ Print Mode │ RPC Mode        │
+├────────────────────────────────────────────────┤
+│                  Core Runtime                    │
+│  AgentSession ─── ModelRegistry ─── Tools       │
+│       │               │                │        │
+│  SessionManager  ModelResolver    Bash/Edit/... │
+│       │               │                │        │
+│  Subagents      ResourceLoader   Permissions    │
+│       │               │                         │
+│  EventBus       Extensions/Skills/Themes        │
+├────────────────────────────────────────────────┤
+│                 IOSM Domain                      │
+│  Init │ Cycles │ Metrics │ Config │ Guide       │
+├────────────────────────────────────────────────┤
+│                  Utilities                       │
+│  Git │ Shell │ Clipboard │ Images │ Frontmatter │
+└────────────────────────────────────────────────┘
+```
+
+### Key Data Flow
+
+1. **CLI** parses arguments and resolves configuration
+2. **Main** initializes the mode (interactive/print/rpc)
+3. **AgentSession** manages conversation loop, model calls, tool execution
+4. **Tools** execute file operations and shell commands
+5. **Extensions** hook into lifecycle events
+6. **IOSM** manages improvement cycles and metrics
+7. **SessionManager** persists conversation state
+
+---
+
+## Further Reading
+
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Contribution guide
+- [CLI Reference](./cli-reference.md) — Flag documentation
+- [Extensions](./extensions-packages-themes.md) — Extension API