AGENTS.md

1# utils — Shared Utilities (Core)
2 
3**Generated:** 2026-06-16
4 
5## OVERVIEW
6 
7Harness-neutral pure-TypeScript core package (`@oh-my-opencode/utils`). Consumed by both adapters (`packages/omo-opencode`, `packages/omo-codex`) and 15+ sibling Core packages. Barrel-exports 36 modules across runtime shims, config tooling, file utilities, prompt gating, git parsing, migration maps, and codegraph primitives.
8 
9## CATEGORY MAP
10 
11| Group | Key Files | Role |
12|-------|-----------|------|
13| **Config** | `omo-config.ts` | Legacy codegraph config validator: `validateOmoConfig()` plus the `CodegraphConfig` / harness-block types re-exported from `@oh-my-opencode/omo-config-core`. The unified `omo.jsonc` loader and migration engine live in `@oh-my-opencode/omo-config-core`, not here |
14| **Deep Merge** | `deep-merge.ts` | `deepMerge()` — recursive, prototype-pollution safe (`__proto__`/`constructor`/`prototype` filtered), max depth 50 |
15| **Frontmatter** | `frontmatter.ts` | `parseFrontmatter()` — default YAML (`js-yaml` JSON_SCHEMA) + rule-mode parser with multiline glob arrays |
16| **File Utils** | `file-utils.ts`, `atomic-write.ts`, `xdg-data-dir.ts` | Symlink resolution, atomic writes with tolerant fsync, XDG data dir with tmp fallback |
17| **Runtime Shims** | `runtime/spawn.ts`, `runtime/which.ts`, `runtime/file.ts` | `spawn()` / `spawnSync()` — prefers `Bun.spawn`, falls back to Node `child_process`; unified `SpawnedProcess` interface |
18| **Prompt Gate** | `prompt-async-gate.ts` + `prompt-async-gate/*.ts` | `dispatchInternalPrompt()` — reservation + queue + semantic dedupe + live-route fallback; the mandated gate for all internal `session.prompt` calls |
19| **Git Worktree** | `git-worktree/*.ts` | Porcelain status parser, diff stat collection, `formatFileChanges()` |
20| **Migration** | `migration.ts`, `migration/*.ts` | Agent-name, hook-name, model-version, agent-category migration maps; `migrateConfigFile()` |
21| **Command Exec** | `command-executor/execute-command.ts`, `execute-hook-command.ts` | `executeCommand()` via `node:child_process` `exec`; stderr inlined in return string |
22| **Codegraph** | `codegraph/*.ts` | Workspace manifest, environment detection, provision helpers |
23| **Misc** | `snake-case.ts`, `jsonc-parser.ts`, `record-type-guard.ts`, `port-utils.ts`, `logger.ts` | Key transformation, safe JSONC parse, type guards, port finder, injectable shared logger stub |
24 
25## NOTES
26 
27- **Dependencies:** `js-yaml`, `jsonc-parser` (only production deps).
28- **No path aliases:** relative imports only; strict `ESNext` + `bundler` moduleResolution.
29- **Runtime portability:** `runtime/spawn.ts` wraps both Bun and Node APIs so downstream packages can run under Electron-hosted OpenCode.
30- **Prompt-async-gate is critical infrastructure:** every internal prompt dispatch across the plugin must route through `dispatchInternalPrompt()` to prevent duplicate injections and race conditions. See the root [`AGENTS.md`](../../AGENTS.md) "Internal message injection is dangerous" section.
31