XCOpenCodeWeb/web/server/lib/opencode/DOCUMENTATION.md

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.