opencode-starterkit 1.0.1

package/README.md

@@ -0,0 +1,47 @@
+# opencode-starterkit
+
+Bootstrap package for a two-layer OpenCode setup.
+
+## Install model
+
+### 1. Global baseline
+
+```bash
+npx opencode-starterkit install
+```
+
+This installs shared baseline directly into the real OpenCode global surface under `~/.config/opencode` and exposes the `ocp` project command.
+
+### 2. Thin project overlay
+
+```bash
+ocp install
+```
+
+This creates a thin `.opencode/` overlay for the current repo and bootstraps a per-project `memory.db*` runtime state.
+
+## Project target shape
+
+```text
+.opencode/
+  opencode.json
+  memory.db
+  memory.db-shm
+  memory.db-wal
+  memory/
+    project/
+      project.md
+      state.md
+      roadmap.md
+      tech-stack.md
+      user.md
+      gotchas.md
+```
+
+## Current status
+
+Functional bootstrap in progress:
+- package includes a vendored baseline from VAT in `baseline/`
+- `opencode-starterkit install` syncs baseline into global OpenCode paths
+- `ocp install` creates thin project overlay and bootstraps `memory.db*`
+- remaining work: safer global config merge + wizard polish + canary on more repos

package/baseline/.env.example

@@ -0,0 +1,196 @@
+# OpenCodeKit - Environment Variables Template
+# ============================================================================
+# Copy this file to .env and fill in your actual values
+# Location: .opencode/.env (project-specific) or ~/.config/opencode/.env (global)
+# ============================================================================
+
+# Configure bash command timeout (default: 120000ms = 2 minutes)
+export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=300000
+export OPENCODE_DISABLE_AUTOCOMPACT=0  # Disable broken compaction
+export OPENCODE_DISABLE_PRUNE=0        # Disable potentially buggy pruning
+export OPENCODE_EXPERIMENTAL_TURN_SUMMARY=1
+export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=1
+export OPENCODE_EXPERIMENTAL_EXA=1
+export OPENCODE_EXPERIMENTAL_OXFMT=1
+export OPENCODE_DISABLE_PROJECT_CONFIG=0  # Disable project config loading (v1.1.29+)
+export OPENCODE_DISABLE_FILETIME_CHECK=0  # Disable file modification time checks (v1.1.29+)
+
+# =============================================================================
+# MCP SERVICES (Remote APIs)
+# =============================================================================
+
+# Context7 - Up-to-date library documentation from 37.6k+ libraries
+# GitHub: https://github.com/upstash/context7
+# Get API key: https://context7.com
+CONTEXT7_API_KEY=ctx7sk-a42497b1-bc40-46aa-a274-4c2dd26c87aa
+
+# Exa - Advanced web search and code context from 3.3k repos
+# GitHub: https://github.com/exa-labs/exa-mcp-server
+# Get API key: https://exa.ai
+EXA_API_KEY=your_exa_api_key_here
+
+# GitLab Knowledge Graph (gkg) - Local codebase semantic search
+# Documentation: https://gitlab-org.gitlab.io/rust/knowledge-graph/
+# Install: https://gitlab-org.gitlab.io/rust/knowledge-graph/getting-started/install/
+# Note: Runs locally on http://localhost:27495/mcp (no API key needed)
+
+# GitHub Grep (gh_grep) - Search 1M+ public GitHub repositories
+# GitHub: https://github.com/Shachlan/grep.app-mcp
+# Note: Public service at https://mcp.grep.app (no API key needed)
+
+# =============================================================================
+# BACKLOG.MD MCP (Task Management)
+# =============================================================================
+# Markdown-native task manager with git-based project board
+# GitHub: https://github.com/MrLesk/Backlog.md (4k+ stars)
+# Install: npm install -g backlog-md
+# Note: Runs locally, no API key needed (enabled by default)
+
+# =============================================================================
+# MCP CODE-MODE (Optional - for Python code execution)
+# =============================================================================
+# GitHub: https://github.com/draphonix/mcp-code-mode
+# Enable in opencode.json: "code-mode": { "enabled": true }
+
+# OpenAI API (for code-mode LLM)
+# Get API key: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=your_openai_api_key_here
+
+# Google Gemini API (alternative for code-mode)
+# Get API key: https://aistudio.google.com/apikey
+# GEMINI_API_KEY=your_gemini_api_key_here
+
+# =============================================================================
+# FIGMA MCP (Optional - for Figma integration)
+# =============================================================================
+# Framelink MCP for Figma - Extract layout info and design tokens
+# GitHub: https://github.com/GLips/Figma-Context-MCP (11.9k+ stars)
+# Enable in opencode.json: "Framelink MCP for Figma": { "enabled": true }
+# Get API key: Figma -> Settings -> Personal Access Tokens
+
+# FIGMA_API_KEY=your_figma_api_key_here
+
+# =============================================================================
+# AI MULTIMODAL SKILL (Optional - for media processing with Gemini)
+# =============================================================================
+# Used by: @.opencode/skills/stack/ai-multimodal/
+# Same as GEMINI_API_KEY above if already set
+
+# GEMINI_API_KEY=your_gemini_api_key_here
+
+# Optional: Use Vertex AI instead of AI Studio
+# GEMINI_USE_VERTEX=true
+# VERTEX_PROJECT_ID=your-gcp-project-id
+# VERTEX_LOCATION=us-central1
+
+# =============================================================================
+# DEVOPS SKILL (Optional - for cloud deployments)
+# =============================================================================
+# Used by: @.opencode/skills/core/devops/
+
+# Cloudflare (Workers, R2, D1, Pages)
+# Get from: https://dash.cloudflare.com
+# CLOUDFLARE_API_TOKEN=your_cloudflare_api_token_here
+# CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id_here
+
+# Google Cloud Platform
+# Download service account key: IAM & Admin -> Service Accounts -> Create Key
+# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+# GCP_PROJECT_ID=your-project-id
+# GCP_REGION=us-central1
+
+# Docker Registry (optional)
+# DOCKER_USERNAME=your_docker_username
+# DOCKER_PASSWORD=your_docker_password
+
+# =============================================================================
+# CUSTOM MCP SERVERS (Add your own)
+# =============================================================================
+# Add any environment variables your custom MCP servers need here
+# Example:
+# MY_CUSTOM_API_KEY=your_custom_api_key_here
+
+# =============================================================================
+# SECURITY NOTES
+# =============================================================================
+# 1. NEVER commit .env files to version control
+# 2. Add .env to .gitignore (already included in template)
+# 3. Use different credentials for dev/staging/production
+# 4. Rotate API keys regularly
+# 5. Use least-privilege principle for all tokens
+# 6. Keep .env.example in version control (with placeholder values only)
+
+# =============================================================================
+# PRIORITY & PRECEDENCE
+# =============================================================================
+# Environment variables are loaded in this order (first found wins):
+# 1. Project-specific: .opencode/.env (takes precedence)
+# 2. Global config: ~/.config/opencode/.env (fallback)
+# 3. System environment: export CONTEXT7_API_KEY=... (lowest priority)
+
+# =============================================================================
+# REQUIRED vs OPTIONAL
+# =============================================================================
+# REQUIRED (for core MCP functionality):
+# - CONTEXT7_API_KEY (library docs)
+# - EXA_API_KEY (web search + code context)
+
+# LOCAL MCP SERVERS (no API key needed):
+# - gkg (GitLab Knowledge Graph) - Install first, runs on localhost:27495
+# - backlog (Backlog.md) - Install via npm, runs locally
+# - gh_grep (GitHub Grep) - Public service, no install needed
+
+# OPTIONAL (enable specific features):
+# - OPENAI_API_KEY or GEMINI_API_KEY (code-mode execution)
+# - FIGMA_API_KEY (Figma integration)
+# - CLOUDFLARE_* (cloud deployments)
+# - GCP_* (Google Cloud deployments)
+
+# =============================================================================
+# GETTING STARTED (Minimal Setup)
+# =============================================================================
+# 1. Copy this file:
+#    cp .opencode/.env.example .opencode/.env
+#
+# 2. Add required keys (minimum):
+#    CONTEXT7_API_KEY=...
+#    EXA_API_KEY=...
+#
+# 3. Verify .env is in .gitignore:
+#    grep ".env" .gitignore
+#
+# 4. Test configuration:
+#    opencode # Should load without errors
+
+# =============================================================================
+# TROUBLESHOOTING
+# =============================================================================
+# "API key not found" errors:
+# - Check .env file location (.opencode/.env or ~/.config/opencode/.env)
+# - Verify no typos in variable names (case-sensitive)
+# - Ensure .env file has no quotes around values (CONTEXT7_API_KEY=abc not "abc")
+# - Restart OpenCode after adding new variables
+
+# "MCP server failed to start":
+# - Check MCP server is enabled in opencode.json
+# - Verify command path exists (e.g., python, npx)
+# - Check server-specific logs in ~/.config/opencode/logs/
+
+# =============================================================================
+# RESOURCES
+# =============================================================================
+# OpenCode Documentation: https://opencode.ai/docs
+
+# MCP Services:
+# - Context7: https://context7.com (API key) | https://github.com/upstash/context7
+# - Exa: https://exa.ai (API key) | https://github.com/exa-labs/exa-mcp-server
+# - GitLab Knowledge Graph: https://gitlab-org.gitlab.io/rust/knowledge-graph/
+# - GitHub Grep: https://github.com/Shachlan/grep.app-mcp
+# - Backlog.md: https://github.com/MrLesk/Backlog.md
+# - MCP Code Mode: https://github.com/draphonix/mcp-code-mode
+# - Figma Context MCP: https://github.com/GLips/Figma-Context-MCP
+
+# Other APIs:
+# - Gemini API: https://aistudio.google.com/apikey
+# - OpenAI API: https://platform.openai.com/api-keys
+# - Cloudflare: https://dash.cloudflare.com