SHARED UTILITIES KNOWLEDGE BASE

OVERVIEW

84 cross-cutting utilities across 6 subdirectories. Import via barrel: import { log, deepMerge } from "../../shared"

STRUCTURE

shared/
├── logger.ts                  # File logging (/tmp/oh-my-opencode.log) — 62 imports
├── dynamic-truncator.ts       # Token-aware context window management (201 lines)
├── model-resolver.ts          # 3-step resolution (Override → Fallback → Default)
├── model-availability.ts      # Provider model fetching & fuzzy matching (358 lines)
├── model-requirements.ts      # Agent/category fallback chains (160 lines)
├── model-resolution-pipeline.ts # Pipeline orchestration (175 lines)
├── model-resolution-types.ts  # Resolution request/provenance types
├── model-sanitizer.ts         # Model name sanitization
├── model-name-matcher.ts      # Model name matching (91 lines)
├── model-suggestion-retry.ts  # Suggest models on failure (129 lines)
├── model-cache-availability.ts # Cache availability checking
├── fallback-model-availability.ts # Fallback model logic (67 lines)
├── available-models-fetcher.ts # Fetch models from providers (114 lines)
├── models-json-cache-reader.ts # Read models.json cache
├── provider-models-cache-model-reader.ts # Provider cache reader
├── connected-providers-cache.ts # Provider caching (196 lines)
├── system-directive.ts        # Unified message prefix & types (61 lines) — 11 imports
├── session-utils.ts           # Session cursor, orchestrator detection
├── session-cursor.ts          # Message cursor tracking (85 lines)
├── session-injected-paths.ts  # Injected file path tracking
├── permission-compat.ts       # Tool restriction enforcement (86 lines)
├── agent-tool-restrictions.ts # Tool restriction definitions
├── agent-variant.ts           # Agent variant from config (91 lines)
├── agent-display-names.ts     # Agent display name mapping
├── first-message-variant.ts   # First message variant types
├── opencode-config-dir.ts     # ~/.config/opencode resolution (138 lines)
├── claude-config-dir.ts       # ~/.claude resolution
├── data-path.ts               # XDG-compliant storage (47 lines)
├── jsonc-parser.ts            # JSONC with comment support (66 lines)
├── frontmatter.ts             # YAML frontmatter extraction (31 lines) — 10 imports
├── deep-merge.ts              # Recursive merge (proto-pollution safe, MAX_DEPTH=50)
├── shell-env.ts               # Cross-platform shell environment (111 lines)
├── opencode-version.ts        # Semantic version comparison (74 lines)
├── external-plugin-detector.ts # Plugin conflict detection (137 lines)
├── opencode-server-auth.ts    # Authentication utilities (69 lines)
├── safe-create-hook.ts        # Hook error wrapper (24 lines)
├── pattern-matcher.ts         # Pattern matching (40 lines)
├── file-utils.ts              # File operations (40 lines) — 9 imports
├── file-reference-resolver.ts # File reference resolution (85 lines)
├── snake-case.ts              # Case conversion (44 lines)
├── tool-name.ts               # Tool naming conventions
├── truncate-description.ts    # Description truncation
├── port-utils.ts              # Port management (48 lines)
├── zip-extractor.ts           # ZIP extraction (83 lines)
├── binary-downloader.ts       # Binary download (60 lines)
├── skill-path-resolver.ts     # Skill path resolution
├── hook-disabled.ts           # Hook disable checking
├── config-errors.ts           # Config error types
├── disabled-tools.ts          # Disabled tools tracking
├── record-type-guard.ts       # Record type guard
├── open-code-client-accessors.ts # Client accessor utilities
├── open-code-client-shapes.ts # Client shape types
├── command-executor/          # Shell execution (6 files, 213 lines)
├── git-worktree/              # Git status/diff parsing (8 files, 311 lines)
├── migration/                 # Legacy config migration (5 files, 341 lines)
│   ├── config-migration.ts    # Migration orchestration (126 lines)
│   ├── agent-names.ts         # Agent name mapping (70 lines)
│   ├── hook-names.ts          # Hook name mapping (36 lines)
│   └── model-versions.ts      # Model version migration (49 lines)
└── tmux/                      # Tmux TUI integration (12 files, 427 lines)
    └── tmux-utils/            # Pane spawn, close, replace, layout, health

MOST IMPORTED

Utility	Imports	Purpose
logger.ts	62	Background task visibility
data-path.ts	11	XDG storage resolution
model-requirements.ts	11	Agent fallback chains
system-directive.ts	11	System message filtering
frontmatter.ts	10	YAML metadata extraction
permission-compat.ts	9	Tool restrictions
file-utils.ts	9	File operations
dynamic-truncator.ts	7	Token-aware truncation

KEY PATTERNS

3-Step Model Resolution (Override → Fallback → Default):

resolveModelWithFallback({ userModel, fallbackChain, availableModels })

System Directive Filtering:

if (isSystemDirective(message)) return  // Skip system-generated
const directive = createSystemDirective("TODO CONTINUATION")

ANTI-PATTERNS

Raw JSON.parse: Use jsonc-parser.ts for comment support
Hardcoded paths: Use opencode-config-dir.ts or data-path.ts
console.log: Use logger.ts for background task visibility
Unbounded output: Use dynamic-truncator.ts to prevent overflow
Manual version check: Use opencode-version.ts for semver safety

5.8 KiB Raw Blame History