docs: regenerate AGENTS.md hierarchy via init-deep
🤖 Generated with assistance of OhMyOpenCode (https://github.com/code-yeongyu/oh-my-opencode)
This commit is contained in:
YeonGyu-Kim
93
src/cli/AGENTS.md
Normal file
93
src/cli/AGENTS.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# CLI KNOWLEDGE BASE
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Command-line interface for oh-my-opencode. Interactive installer, health diagnostics (doctor), and runtime commands. Entry point: `bunx oh-my-opencode`.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
cli/
|
||||
├── index.ts # Commander.js entry point, subcommand routing
|
||||
├── install.ts # Interactive TUI installer
|
||||
├── config-manager.ts # Config detection, parsing, merging (669 lines)
|
||||
├── types.ts # CLI-specific types
|
||||
├── doctor/ # Health check system
|
||||
│ ├── index.ts # Doctor command entry
|
||||
│ ├── constants.ts # Check categories, descriptions
|
||||
│ ├── types.ts # Check result interfaces
|
||||
│ └── checks/ # 17 individual health checks
|
||||
├── get-local-version/ # Version detection utility
|
||||
│ ├── index.ts
|
||||
│ └── formatter.ts
|
||||
└── run/ # OpenCode session launcher
|
||||
├── index.ts
|
||||
└── completion.test.ts
|
||||
```
|
||||
|
||||
## CLI COMMANDS
|
||||
|
||||
| Command | Purpose | Key File |
|
||||
|---------|---------|----------|
|
||||
| `install` | Interactive setup wizard | `install.ts` |
|
||||
| `doctor` | Environment health checks | `doctor/index.ts` |
|
||||
| `run` | Launch OpenCode session | `run/index.ts` |
|
||||
|
||||
## DOCTOR CHECKS
|
||||
|
||||
17 checks in `doctor/checks/`:
|
||||
|
||||
| Check | Validates |
|
||||
|-------|-----------|
|
||||
| `version.ts` | OpenCode version >= 1.0.150 |
|
||||
| `config.ts` | Plugin registered in opencode.json |
|
||||
| `bun.ts` | Bun runtime available |
|
||||
| `node.ts` | Node.js version compatibility |
|
||||
| `git.ts` | Git installed |
|
||||
| `anthropic-auth.ts` | Claude authentication |
|
||||
| `openai-auth.ts` | OpenAI authentication |
|
||||
| `google-auth.ts` | Google/Gemini authentication |
|
||||
| `lsp-*.ts` | Language server availability |
|
||||
| `mcp-*.ts` | MCP server connectivity |
|
||||
|
||||
## INSTALLATION FLOW
|
||||
|
||||
1. **Detection**: Find existing `opencode.json` / `opencode.jsonc`
|
||||
2. **TUI Prompts**: Claude subscription? ChatGPT? Gemini?
|
||||
3. **Config Generation**: Build `oh-my-opencode.json` based on answers
|
||||
4. **Plugin Registration**: Add to `plugin` array in opencode.json
|
||||
5. **Auth Guidance**: Instructions for `opencode auth login`
|
||||
|
||||
## CONFIG-MANAGER
|
||||
|
||||
The largest file (669 lines) handles:
|
||||
|
||||
- **JSONC support**: Parses comments and trailing commas
|
||||
- **Multi-source detection**: User (~/.config/opencode/) + Project (.opencode/)
|
||||
- **Schema validation**: Zod-based config validation
|
||||
- **Migration**: Handles legacy config formats
|
||||
- **Error collection**: Aggregates parsing errors for doctor
|
||||
|
||||
## HOW TO ADD A DOCTOR CHECK
|
||||
|
||||
1. Create `src/cli/doctor/checks/my-check.ts`:
|
||||
```typescript
|
||||
import type { DoctorCheck } from "../types"
|
||||
|
||||
export const myCheck: DoctorCheck = {
|
||||
name: "my-check",
|
||||
category: "environment",
|
||||
check: async () => {
|
||||
// Return { status: "pass" | "warn" | "fail", message: string }
|
||||
}
|
||||
}
|
||||
```
|
||||
2. Add to `src/cli/doctor/checks/index.ts`
|
||||
3. Update `constants.ts` if new category
|
||||
|
||||
## ANTI-PATTERNS (CLI)
|
||||
|
||||
- **Blocking prompts in non-TTY**: Check `process.stdout.isTTY` before TUI
|
||||
- **Hardcoded paths**: Use shared utilities for config paths
|
||||
- **Ignoring JSONC**: User configs may have comments
|
||||
- **Silent failures**: Doctor checks must return clear status/message
|
||||
82
src/shared/AGENTS.md
Normal file
82
src/shared/AGENTS.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# SHARED UTILITIES KNOWLEDGE BASE
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Cross-cutting utility functions used across agents, hooks, tools, and features. Path resolution, config management, text processing, and Claude Code compatibility helpers.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
shared/
|
||||
├── index.ts # Barrel export (import { x } from "../shared")
|
||||
├── claude-config-dir.ts # Resolve ~/.claude directory
|
||||
├── command-executor.ts # Shell command execution with variable expansion
|
||||
├── config-errors.ts # Global config error tracking
|
||||
├── config-path.ts # User/project config path resolution
|
||||
├── data-path.ts # XDG data directory resolution
|
||||
├── deep-merge.ts # Type-safe recursive object merging
|
||||
├── dynamic-truncator.ts # Token-aware output truncation
|
||||
├── file-reference-resolver.ts # @filename syntax resolution
|
||||
├── file-utils.ts # Symlink resolution, markdown detection
|
||||
├── frontmatter.ts # YAML frontmatter parsing
|
||||
├── hook-disabled.ts # Check if hook is disabled in config
|
||||
├── jsonc-parser.ts # JSON with Comments parsing
|
||||
├── logger.ts # File-based logging to OS temp
|
||||
├── migration.ts # Legacy name compatibility (omo -> Sisyphus)
|
||||
├── model-sanitizer.ts # Normalize model names
|
||||
├── pattern-matcher.ts # Tool name matching with wildcards
|
||||
├── snake-case.ts # Case conversion for objects
|
||||
└── tool-name.ts # Normalize tool names to PascalCase
|
||||
```
|
||||
|
||||
## UTILITY CATEGORIES
|
||||
|
||||
| Category | Utilities | Used By |
|
||||
|----------|-----------|---------|
|
||||
| Path Resolution | `getClaudeConfigDir`, `getUserConfigPath`, `getProjectConfigPath`, `getDataDir` | Features, Hooks |
|
||||
| Config Management | `deepMerge`, `parseJsonc`, `isHookDisabled`, `configErrors` | index.ts, CLI |
|
||||
| Text Processing | `resolveCommandsInText`, `resolveFileReferencesInText`, `parseFrontmatter` | Commands, Rules |
|
||||
| Output Control | `dynamicTruncate` | Tools (Grep, LSP) |
|
||||
| Normalization | `transformToolName`, `objectToSnakeCase`, `sanitizeModelName` | Hooks, Agents |
|
||||
| Compatibility | `migration.ts` | Config loading |
|
||||
|
||||
## WHEN TO USE WHAT
|
||||
|
||||
| Task | Utility | Notes |
|
||||
|------|---------|-------|
|
||||
| Find Claude Code configs | `getClaudeConfigDir()` | Never hardcode `~/.claude` |
|
||||
| Merge settings (default → user → project) | `deepMerge(base, override)` | Arrays replaced, objects merged |
|
||||
| Parse user config files | `parseJsonc()` | Supports comments and trailing commas |
|
||||
| Check if hook should run | `isHookDisabled(name, disabledHooks)` | Respects `disabled_hooks` config |
|
||||
| Truncate large tool output | `dynamicTruncate(text, budget, reserved)` | Token-aware, prevents overflow |
|
||||
| Resolve `@file` references | `resolveFileReferencesInText()` | maxDepth=3 prevents infinite loops |
|
||||
| Execute shell commands | `resolveCommandsInText()` | Supports `!`\`command\`\` syntax |
|
||||
| Handle legacy agent names | `migrateLegacyAgentNames()` | `omo` → `Sisyphus` |
|
||||
|
||||
## CRITICAL PATTERNS
|
||||
|
||||
### Dynamic Truncation
|
||||
```typescript
|
||||
import { dynamicTruncate } from "../shared"
|
||||
// Keep 50% headroom, max 50k tokens
|
||||
const output = dynamicTruncate(result, remainingTokens, 0.5)
|
||||
```
|
||||
|
||||
### Deep Merge Priority
|
||||
```typescript
|
||||
const final = deepMerge(defaults, userConfig)
|
||||
final = deepMerge(final, projectConfig) // Project wins
|
||||
```
|
||||
|
||||
### Safe JSONC Parsing
|
||||
```typescript
|
||||
const { config, error } = parseJsoncSafe(content)
|
||||
if (error) return fallback
|
||||
```
|
||||
|
||||
## ANTI-PATTERNS (SHARED)
|
||||
|
||||
- **Hardcoding paths**: Use `getClaudeConfigDir()`, `getUserConfigPath()`
|
||||
- **Manual JSON.parse**: Use `parseJsonc()` for user files (comments allowed)
|
||||
- **Ignoring truncation**: Large outputs MUST use `dynamicTruncate`
|
||||
- **Direct string concat for configs**: Use `deepMerge` for proper priority
|
||||
Reference in New Issue
Block a user