59 lines
4.0 KiB
Markdown
59 lines
4.0 KiB
Markdown
|
# OpenCode Module Documentation
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
This module provides OpenCode server integration utilities for the web server runtime, including configuration management, provider authentication, and UI authentication with rate limiting.
|
||
|
|
|
||
|
|
## Entrypoints and structure
|
||
|
|
- `packages/web/server/lib/opencode/index.js`: public entrypoint (currently baseline placeholder).
|
||
|
|
- `packages/web/server/lib/opencode/auth.js`: provider authentication file operations.
|
||
|
|
- `packages/web/server/lib/opencode/shared.js`: shared utilities for config, markdown, skills, and git helpers.
|
||
|
|
- `packages/web/server/lib/opencode/ui-auth.js`: UI session authentication with rate limiting.
|
||
|
|
|
||
|
|
## Public exports (auth.js)
|
||
|
|
- `readAuthFile()`: Reads and parses `~/.local/share/opencode/auth.json`.
|
||
|
|
- `writeAuthFile(auth)`: Writes auth file with automatic backup.
|
||
|
|
- `removeProviderAuth(providerId)`: Removes a provider's auth entry.
|
||
|
|
- `getProviderAuth(providerId)`: Returns auth for a specific provider or null.
|
||
|
|
- `listProviderAuths()`: Returns list of provider IDs with configured auth.
|
||
|
|
- `AUTH_FILE`: Auth file path constant.
|
||
|
|
- `OPENCODE_DATA_DIR`: OpenCode data directory path constant.
|
||
|
|
|
||
|
|
## Public exports (shared.js)
|
||
|
|
- `OPENCODE_CONFIG_DIR`, `AGENT_DIR`, `COMMAND_DIR`, `SKILL_DIR`, `CONFIG_FILE`, `CUSTOM_CONFIG_FILE`: Path constants.
|
||
|
|
- `AGENT_SCOPE`, `COMMAND_SCOPE`, `SKILL_SCOPE`: Scope constants with USER and PROJECT values.
|
||
|
|
- `ensureDirs()`: Creates required OpenCode directories.
|
||
|
|
- `parseMdFile(filePath)`, `writeMdFile(filePath, frontmatter, body)`: Markdown file operations with YAML frontmatter.
|
||
|
|
- `getConfigPaths(workingDirectory)`, `readConfigLayers(workingDirectory)`, `readConfig(workingDirectory)`: Config file operations with layer merging (user, project, custom).
|
||
|
|
- `writeConfig(config, filePath)`: Writes config with automatic backup.
|
||
|
|
- `getJsonEntrySource(layers, sectionKey, entryName)`: Resolves which config layer provides an entry.
|
||
|
|
- `getJsonWriteTarget(layers, preferredScope)`: Determines write target for config updates.
|
||
|
|
- `getAncestors(startDir, stopDir)`, `findWorktreeRoot(startDir)`: Git worktree helpers.
|
||
|
|
- `isPromptFileReference(value)`, `resolvePromptFilePath(reference)`, `writePromptFile(filePath, content)`: Prompt file reference handling.
|
||
|
|
- `walkSkillMdFiles(rootDir)`: Recursively finds all SKILL.md files.
|
||
|
|
- `addSkillFromMdFile(skillsMap, skillMdPath, scope, source)`: Parses and indexes a skill file.
|
||
|
|
- `resolveSkillSearchDirectories(workingDirectory)`: Returns skill search path order (config, project, home, custom).
|
||
|
|
- `listSkillSupportingFiles(skillDir)`, `readSkillSupportingFile(skillDir, relativePath)`, `writeSkillSupportingFile(skillDir, relativePath, content)`, `deleteSkillSupportingFile(skillDir, relativePath)`: Skill supporting file management.
|
||
|
|
|
||
|
|
## Public exports (ui-auth.js)
|
||
|
|
- `createUiAuth({ password, cookieName, sessionTtlMs })`: Creates UI auth instance with methods:
|
||
|
|
- `enabled`: Boolean indicating if auth is configured.
|
||
|
|
- `requireAuth(req, res, next)`: Express middleware to enforce authentication.
|
||
|
|
- `handleSessionStatus(req, res)`: Returns authentication status.
|
||
|
|
- `handleSessionCreate(req, res)`: Handles login with rate limiting.
|
||
|
|
- `ensureSessionToken(req, res)`: Returns or creates session token.
|
||
|
|
- `dispose()`: Cleans up timers and state.
|
||
|
|
|
||
|
|
## Storage and configuration
|
||
|
|
- Provider auth: `~/.local/share/opencode/auth.json`.
|
||
|
|
- User config: `~/.config/opencode/opencode.json`.
|
||
|
|
- Project config: `<workingDirectory>/.opencode/opencode.json` or `opencode.json`.
|
||
|
|
- Custom config: `OPENCODE_CONFIG` env var path.
|
||
|
|
- Rate limit config: `OPENCHAMBER_RATE_LIMIT_MAX_ATTEMPTS`, `OPENCHAMBER_RATE_LIMIT_NO_IP_MAX_ATTEMPTS` env vars.
|
||
|
|
|
||
|
|
## Notes for contributors
|
||
|
|
- This module serves as foundation for OpenCode-related server utilities.
|
||
|
|
- Index.js is currently a baseline placeholder; direct imports use submodule paths.
|
||
|
|
- All file writes include automatic backup before modification.
|
||
|
|
- Config merging follows priority: custom > project > user.
|
||
|
|
- UI auth uses scrypt for password hashing with constant-time comparison.
|