From 541257860085e453fab2f8c6f4c16df8b78b08b4 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Wed, 31 Dec 2025 14:07:14 +0900 Subject: [PATCH] docs: regenerate AGENTS.md hierarchy via init-deep MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with assistance of OhMyOpenCode (https://github.com/code-yeongyu/oh-my-opencode) --- AGENTS.md | 28 ++++++++++--- src/cli/AGENTS.md | 93 ++++++++++++++++++++++++++++++++++++++++++++ src/shared/AGENTS.md | 82 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 198 insertions(+), 5 deletions(-) create mode 100644 src/cli/AGENTS.md create mode 100644 src/shared/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index fcaa8d3..c680a06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # PROJECT KNOWLEDGE BASE -**Generated:** 2025-12-28T19:26:00+09:00 -**Commit:** 122e918 +**Generated:** 2025-12-31T14:05:00+09:00 +**Commit:** 502e9f5 **Branch:** dev ## OVERVIEW @@ -20,7 +20,8 @@ oh-my-opencode/ │ ├── features/ # Claude Code compatibility - see src/features/AGENTS.md │ ├── config/ # Zod schema, TypeScript types │ ├── auth/ # Google Antigravity OAuth (antigravity/) -│ ├── shared/ # Utilities: deep-merge, pattern-matcher, logger, etc. +│ ├── shared/ # Utilities: deep-merge, pattern-matcher, logger, etc. - see src/shared/AGENTS.md +│ ├── cli/ # CLI installer, doctor, run - see src/cli/AGENTS.md │ └── index.ts # Main plugin entry (OhMyOpenCodePlugin) ├── script/ # build-schema.ts, publish.ts, generate-changelog.ts ├── assets/ # JSON schema @@ -34,7 +35,7 @@ oh-my-opencode/ | Add agent | `src/agents/` | Create .ts, add to builtinAgents in index.ts, update types.ts | | Add hook | `src/hooks/` | Create dir with createXXXHook(), export from index.ts | | Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to builtinTools | -| Add MCP | `src/mcp/` | Create config, add to index.ts | +| Add MCP | `src/mcp/` | Create config, add to index.ts and types.ts | | LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) | | AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding | | Google OAuth | `src/auth/antigravity/` | OAuth plugin for Google models | @@ -42,6 +43,9 @@ oh-my-opencode/ | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders | | Background agents | `src/features/background-agent/` | manager.ts for task management | | Interactive terminal | `src/tools/interactive-bash/` | tmux session management | +| CLI installer | `src/cli/install.ts` | Interactive TUI installation | +| Doctor checks | `src/cli/doctor/checks/` | Health checks for environment | +| Shared utilities | `src/shared/` | Cross-cutting utilities | ## CONVENTIONS @@ -64,6 +68,8 @@ oh-my-opencode/ - **Year 2024**: NEVER use 2024 in code/prompts (use current year) - **Rush completion**: Never mark tasks complete without verification - **Over-exploration**: Stop searching when sufficient context found +- **High temperature**: Don't use >0.3 for code-related agents +- **Broad tool access**: Prefer explicit `include` over unrestricted access ## UNIQUE STYLES @@ -109,8 +115,19 @@ bun test # Run tests ## CI PIPELINE -- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master +- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master, rolling `next` draft release - **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish +- **sisyphus-agent.yml**: Agent-in-CI for automated issue handling via `@sisyphus-dev-ai` mentions + +## COMPLEXITY HOTSPOTS + +| File | Lines | Description | +|------|-------|-------------| +| `src/index.ts` | 690 | Main plugin orchestration, all hook/tool initialization | +| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 670 | Session compaction, multi-stage recovery pipeline | +| `src/cli/config-manager.ts` | 669 | JSONC parsing, environment detection, installation | +| `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting, endpoint fallbacks | +| `src/tools/lsp/client.ts` | 611 | LSP protocol, stdin/stdout buffering, JSON-RPC | ## NOTES @@ -119,3 +136,4 @@ bun test # Run tests - **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN) - **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project) - **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker +- **JSONC support**: Config files support comments (`// comment`, `/* block */`) and trailing commas diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md new file mode 100644 index 0000000..d1a90b2 --- /dev/null +++ b/src/cli/AGENTS.md @@ -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 diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md new file mode 100644 index 0000000..2c9e008 --- /dev/null +++ b/src/shared/AGENTS.md @@ -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