From a806755d0f9ea08328fb64eebb85385e4e8d05a7 Mon Sep 17 00:00:00 2001 From: Lucas Shamanic Date: Mon, 12 Jan 2026 23:47:06 +0000 Subject: [PATCH] feat(schema): refine and expand extension metadata schema - Introduce `scope`, `tags`, `min_version`, `homepage`, and `installation` fields for enhanced discoverability and guidance. - Remove `install` and `compatibility` objects, replacing them with a simplified `installation` string field. - Add `examples/` directory with full exemplar files for each extension type. - Update `schema-design.md` to reflect new schema, clarify field definitions, and improve documentation structure. --- data/schema.json | 64 ++-- docs/schema-design.md | 682 ++++++++++------------------------------- examples/README.md | 40 +++ examples/agent.yaml | 89 ++++++ examples/fork.yaml | 89 ++++++ examples/plugin.yaml | 81 +++++ examples/project.yaml | 72 +++++ examples/resource.yaml | 80 +++++ examples/theme.yaml | 59 ++++ 9 files changed, 697 insertions(+), 559 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/agent.yaml create mode 100644 examples/fork.yaml create mode 100644 examples/plugin.yaml create mode 100644 examples/project.yaml create mode 100644 examples/resource.yaml create mode 100644 examples/theme.yaml diff --git a/data/schema.json b/data/schema.json index 14f4f8c..b279a3c 100644 --- a/data/schema.json +++ b/data/schema.json @@ -8,64 +8,56 @@ "name": { "type": "string", "minLength": 1, - "description": "Name of the project or tool" + "description": "Display name of the project or tool" }, "repo": { "type": "string", "format": "uri", - "description": "URL to the repository" + "description": "URL to the repository (https://github.com/...)" }, -"tagline": { + "tagline": { "type": "string", "minLength": 1, "maxLength": 120, - "description": "Short punchy summary of the project (shown in collapsed view)" + "description": "Short punchy summary (shown in collapsed view)" }, "description": { "type": "string", "minLength": 1, "description": "Full description of the project (shown when expanded)" }, - "install": { - "type": "object", - "description": "Installation instructions", - "properties": { - "type": { - "type": "string", - "enum": ["config", "npm", "pip", "go", "script", "manual"], - "description": "Type of installation method" - } + "scope": { + "type": "array", + "items": { + "type": "string", + "enum": ["global", "project"] }, - "required": ["type"], - "additionalProperties": false - }, - "compatibility": { - "type": "object", - "description": "Compatibility information", - "properties": { - "platforms": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Supported platforms" - }, - "opencode": { - "type": "string", - "description": "Compatible Opencode version" - } - }, - "required": ["platforms", "opencode"], - "additionalProperties": false + "minItems": 1, + "uniqueItems": true, + "description": "Installation scope: global (~/.config/opencode/) or project (.opencode/). Defaults to [global] if omitted." }, "tags": { "type": "array", "items": { "type": "string" }, - "description": "Tags for categorization" + "description": "Tags for filtering and discoverability" + }, + "min_version": { + "type": "string", + "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+", + "description": "Minimum OpenCode version required (semver format, e.g. '1.0.0')" + }, + "homepage": { + "type": "string", + "format": "uri", + "description": "Documentation URL if different from repository" + }, + "installation": { + "type": "string", + "description": "Detailed installation instructions in markdown format" } }, "required": ["name", "repo", "tagline", "description"], - "additionalProperties": false + "additionalProperties": true } diff --git a/docs/schema-design.md b/docs/schema-design.md index 03be8b0..1f4b803 100644 --- a/docs/schema-design.md +++ b/docs/schema-design.md @@ -1,7 +1,5 @@ # OpenCode Extension Schema Design -> **Working Document** - This document serves as both a planning guide for implementation and a precursor to official documentation. Content may evolve as implementation progresses. - This document describes the YAML schema for the awesome-opencode registry, a data-driven catalog of OpenCode extensions. It covers extension types, configuration locations, schema fields, and downstream compatibility. --- @@ -15,7 +13,8 @@ The awesome-opencode registry is a curated collection of extensions that enhance - **Human Readable**: YAML format ensures contributors can easily read and edit entries - **Downstream Ready**: Schema designed for seamless consumption by platforms like opencode.cafe - **Discoverable**: Tags and metadata support filtering and search -- **Scope-Aware**: Clear distinction between global and project-level installations +- **Extensible**: Schema allows additional fields for future enhancements +- **Type by Location**: Extension type is derived from directory, not stored in YAML ### Directory Structure @@ -34,6 +33,8 @@ awesome-opencode/ │ │ └── *.yaml # Guides, configs, MCP servers, tools, commands │ └── forks/ │ └── *.yaml +├── examples/ +│ └── *.yaml # Exemplar files showing all fields └── docs/ └── schema-design.md ``` @@ -191,102 +192,91 @@ If `scope` is set to `[global, project]` and both global and project configs def --- -## 4. Current YAML Schema +## 4. YAML Schema -The current awesome-opencode entries use a minimal schema focused on core metadata. +The awesome-opencode registry uses a flexible schema with four required fields and several optional fields for enhanced discoverability. -### Current Required Fields +### Required Fields | Field | Type | Description | |-------|------|-------------| | `name` | string | Display name for the extension (human-readable) | | `repo` | string | Repository URL (HTTPS format, e.g., `https://github.com/user/repo`) | -| `description` | string | Short description (max 100 characters) | +| `tagline` | string | Short punchy summary, max 120 characters | +| `description` | string | Full description (can be multi-line) | -### Current Optional Fields +### Optional Fields -| Field | Type | Description | -|-------|------|-------------| -| `full_description` | string | Extended explanation of functionality | +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `scope` | array | `[global]` | Installation scope: `[global]`, `[project]`, or `[global, project]` | +| `tags` | array | `[]` | Strings for filtering and discoverability | +| `min_version` | string | - | Minimum OpenCode version required (semver, e.g., `"1.0.0"`) | +| `homepage` | string | - | Documentation URL if different from repository | +| `installation` | string | - | Detailed installation instructions (markdown format) | -### Example (Current Format) +### Type Derivation + +Extension type is **not stored in YAML** - it's derived from the directory location: + +| Directory | Type | +|-----------|------| +| `data/plugins/` | `plugin` | +| `data/themes/` | `theme` | +| `data/agents/` | `agent` | +| `data/projects/` | `project` | +| `data/resources/` | `resource` | +| `data/forks/` | `fork` | + +### Minimal Valid Entry ```yaml -name: CodeGPT -repo: https://github.com/company/codegpt -tagline: AI-powered code completion and refactoring -description: | - CodeGPT provides intelligent code completion using GPT models. - Features include: - - Real-time suggestions - - Context-aware refactoring - - Multi-language support +name: My Extension +repo: https://github.com/user/my-extension +tagline: A brief description of what this does +description: A longer explanation of the extension. ``` ---- - -## 5. Proposed Schema Additions - -The following fields are being added to enhance discoverability, installation guidance, and downstream compatibility. - -### New Required Fields - -| Field | Type | Description | -|-------|------|-------------| -| `type` | enum | Extension type: `plugin`, `theme`, `agent`, `project`, `resource`, or `fork` | -| `scope` | array | Installation scope: `[global]`, `[project]`, or `[global, project]` | - -### New Optional Fields - -| Field | Type | Description | -|-------|------|-------------| -| `tags` | array | Strings for filtering and discoverability (e.g., `["ai", "productivity"]`) | -| `min_version` | string | Minimum OpenCode version required (e.g., `"1.0.0"`) | -| `homepage` | string | Documentation URL if different from repository | -| `installation` | markdown | Detailed installation instructions | - -### Example (Proposed Format) +### Complete Entry (All Fields) ```yaml -name: CodeGPT -repo: https://github.com/company/codegpt -type: plugin -scope: [global, project] -tagline: AI-powered code completion and refactoring +name: My Extension +repo: https://github.com/user/my-extension +tagline: A brief tagline (max 120 chars) description: | - CodeGPT provides intelligent code completion using GPT models. - Features include: - - Real-time suggestions - - Context-aware refactoring - - Multi-language support + A longer description explaining + the extension in detail. +scope: + - global + - project tags: - - ai - - completion - productivity + - ai min_version: "1.0.0" -homepage: https://codegpt.dev/docs +homepage: https://example.com/docs installation: | - ## Prerequisites - - OpenCode 1.0.0 or later - - Node.js 18+ for local plugins - ## Installation - ### Global - 1. Run `opencode install codegpt` - 2. Restart OpenCode - - ## Configuration - Add to `opencode.json`: - ```json - { - "plugins": ["codegpt"] - } + ```bash + git clone https://github.com/user/my-extension ~/.config/opencode/plugin/my-extension ``` ``` +### Examples Directory + +Full exemplar files for each extension type are available in `examples/`: + +| Type | Example File | +|------|-------------| +| Plugin | `examples/plugin.yaml` | +| Theme | `examples/theme.yaml` | +| Agent | `examples/agent.yaml` | +| Project | `examples/project.yaml` | +| Resource | `examples/resource.yaml` | +| Fork | `examples/fork.yaml` | + --- -## 6. Installation Template +## 5. Installation Template The `installation` field uses a structured template that contributors fill in. Not all sections are required—include what's relevant for the extension. @@ -338,7 +328,7 @@ How to uninstall the extension --- -## 7. Downstream Compatibility +## 6. Downstream Compatibility The awesome-opencode schema is designed for seamless conversion to downstream platforms like opencode.cafe. @@ -348,23 +338,15 @@ The awesome-opencode schema is designed for seamless conversion to downstream pl |-----------------------|-------------------|-------| | `name` | `displayName` | Display name for UI | | `repo` | `repoUrl` | Repository URL | -| `description` | `description` | Short description | -| `type` | `type` | Mapped directly (see below) | +| `tagline` | `tagline` | Short summary | +| `description` | `description` | Full description | +| (directory) | `type` | Derived from directory path | +| (filename) | `productId` | Derived from filename | +| `scope` | `scope` | Defaults to `["global"]` | | `tags` | `tags` | Array of strings | | `homepage` | `homepageUrl` | Documentation URL | | `installation` | `installation` | Markdown content | -| (filename) | `productId` | Derived from filename | - -### Type Mapping - -| awesome-opencode Type | opencode.cafe Type | -|-----------------------|-------------------| -| `plugin` | `plugin` | -| `theme` | `theme` | -| `agent` | `agent` | -| `project` | `project` | -| `resource` | `resource` | -| `fork` | `fork` | +| `min_version` | `minVersion` | Semver string | ### Conversion Example @@ -373,9 +355,8 @@ The awesome-opencode schema is designed for seamless conversion to downstream pl ```yaml name: CodeGPT repo: https://github.com/company/codegpt -type: plugin -scope: [global, project] tagline: AI-powered code completion +description: Intelligent code completion using GPT models. ``` **JSON Output (opencode.cafe format):** @@ -383,22 +364,25 @@ tagline: AI-powered code completion ```json { "productId": "codegpt", + "type": "plugin", "displayName": "CodeGPT", "repoUrl": "https://github.com/company/codegpt", - "type": "plugin", "tagline": "AI-powered code completion", - "tags": [], - "installation": "" + "description": "Intelligent code completion using GPT models.", + "scope": ["global"], + "tags": [] } ``` +Note: `type` is derived from `data/plugins/` → `plugin`, and `productId` from filename `codegpt.yaml` → `codegpt`. + --- -## 8. Future Vision +## 7. Future Vision This section outlines planned features and improvements for the awesome-opencode ecosystem. -### 8.1 Agent-Powered Plugin Manager +### 7.1 Agent-Powered Plugin Manager A future plugin/agent that uses the `installation` markdown as context to assist with setup. The agent would: - Parse the installation instructions @@ -408,7 +392,7 @@ A future plugin/agent that uses the `installation` markdown as context to assist This is **not** an automated CLI executor - it's an AI assistant with context about how to install the extension. -### 8.2 Interactive TUI with Scope Selection +### 7.2 Interactive TUI with Scope Selection A terminal UI that: - Reads the `scope` field to present appropriate options @@ -427,485 +411,137 @@ A terminal UI that: └─────────────────────────────────────────┘ ``` -### 8.3 Automatic Backup and Restore +### 7.3 Automatic Backup and Restore When an agent assists with installation, it can: - Read the "Files Modified" section to know what to backup - Store backups before making changes - Enable clean removal with rollback capability -### 8.4 Export and Sync Scripts - -Scripts to export the registry for downstream platforms: - -```bash -# Export to opencode.cafe JSON format -./scripts/export-json.sh - -# Export to custom format -./scripts/export.sh --format=custom --output=dist/ -``` - -### 8.5 Contributing Workflow +### 7.4 Contributing Workflow Improvements Future improvements to the contribution process: 1. **Schema Validation**: CI checks YAML validity and required fields 2. **Preview Tool**: Generate opencode.cafe JSON preview for PRs -3. **Category Detection**: Auto-suggest category based on `type` field -4. **Link Checking**: Verify `repo` and `homepage` URLs are accessible +3. **Link Checking**: Verify `repo` and `homepage` URLs are accessible --- -## Appendix A: Quick Reference +## 8. Quick Reference ### Extension Type to Directory Mapping -| Type | Directory | File Extension | -|------|-----------|----------------| -| `plugin` | `data/plugins/` | `.yaml` | -| `theme` | `data/themes/` | `.yaml` | -| `agent` | `data/agents/` | `.yaml` | -| `project` | `data/projects/` | `.yaml` | -| `resource` | `data/resources/` | `.yaml` | -| `fork` | `data/forks/` | `.yaml` | +| Type | Directory | +|------|-----------| +| `plugin` | `data/plugins/` | +| `theme` | `data/themes/` | +| `agent` | `data/agents/` | +| `project` | `data/projects/` | +| `resource` | `data/resources/` | +| `fork` | `data/forks/` | ### Minimal Valid Entry ```yaml name: My Extension repo: https://github.com/user/my-extension -type: plugin -scope: [global] tagline: A brief description +description: A longer explanation of what this extension does. ``` ### Complete Entry (All Fields) +See `examples/` directory for full exemplar files. + ```yaml name: My Extension repo: https://github.com/user/my-extension -type: plugin -scope: [global, project] -tagline: A brief tagline (≤120 chars) +tagline: A brief tagline (max 120 chars) description: | A longer description explaining the extension in detail. +scope: + - global + - project tags: - productivity - ai min_version: "1.0.0" -homepage: https://user.dev/docs +homepage: https://example.com/docs installation: | ## Installation - Run `opencode install my-extension` + ```bash + git clone https://github.com/user/my-extension ~/.config/opencode/plugin/my-extension + ``` ``` ---- +### Commands -## 9. Implementation Plan: Schema Additions - -**Created**: 2026-01-11 -**Last Updated**: 2026-01-11 -**Status**: planning - -This section provides a phased implementation plan for adding the new schema fields (`type`, `scope`, `tags`, `min_version`, `homepage`, `installation`) to the awesome-opencode registry. - ---- - -### Current State Overview - -| Component | Status | -|-----------|--------| -| YAML entries (61 files) | Existing, uses basic schema | -| JSON schema (`data/schema.json`) | Out of sync with proposed fields | -| Generation script (`scripts/generate-readme.js`) | Needs update for new fields | -| Validation script (`scripts/validate.js`) | Needs update for new fields | -| Contributing guide (`contributing.md`) | Needs documentation update | - ---- - -### Phase 1: Schema Update -**Goal**: Update `data/schema.json` with new fields - -#### Phase 1 Deliverables -- [ ] JSON schema validates new `type` field (required enum) -- [ ] JSON schema validates new `scope` field (required array) -- [ ] JSON schema validates new optional fields (`tags`, `min_version`, `homepage`, `installation`) -- [ ] Validation script runs without errors - -#### Phase 1 Tasks - -- [ ] **Task 1.1**: Add `type` field as required enum - - [ ] Open `data/schema.json` and read current structure - - [ ] Add `type` property with enum values: `plugin`, `theme`, `agent`, `project`, `resource`, `fork` - - [ ] Set `type` to required in schema - - [ ] Add description for each enum value - -- [ ] **Task 1.2**: Add `scope` field as required array - - [ ] Add `scope` property with items enum: `global`, `project` - - [ ] Set `minItems: 1` (at least one scope required) - - [ ] Set `uniqueItems: true` (no duplicates) - - [ ] Set `scope` to required in schema - -- [ ] **Task 1.3**: Add `tags` field as optional string array - - [ ] Add `tags` property with type `array` of `string` - - [ ] Leave `tags` as optional (not in required array) - -- [ ] **Task 1.4**: Add `min_version` field as optional string - - [ ] Add `min_version` property with type `string` - - [ ] Add semver regex pattern for validation - - [ ] Leave `min_version` as optional - -- [ ] **Task 1.5**: Add `homepage` field as optional URL - - [ ] Add `homepage` property with type `string` - - [ ] Add URI format pattern (http/https) - - [ ] Leave `homepage` as optional - -- [ ] **Task 1.6**: Add `installation` field as optional markdown - - [ ] Add `installation` property with type `string` - - [ ] Add description indicating markdown format - - [ ] Leave `installation` as optional - -- [ ] **Task 1.7**: Validate schema structure - - [ ] Run `node scripts/validate.js` to check schema validity - - [ ] Fix any JSON syntax errors - - [ ] Verify schema against JSON Schema specification - -#### Phase 1 Manual Testing -**Testing Requirements**: User performs hands-on testing in terminal - -- [ ] Run validation script: `node scripts/validate.js` -- [ ] Verify schema loads without errors -- [ ] Check that new fields are recognized in validation output -- [ ] Test with a sample YAML file containing new fields - -#### Phase 1 Review Process -**User Review Required**: Do NOT proceed to Phase 2 without user sign-off - -**Review Checklist**: -- [ ] Schema validates without errors -- [ ] All new field types are correct (required vs optional) -- [ ] Enum values match documented extension types -- [ ] User approves proceeding to next phase - -**Go/No-Go Decision**: [_______] (User fills in date and sign-off) -- [ ] **GO** - Proceed to Phase 2 -- [ ] **NO-GO** - Fix issues first - -**Issues to Fix**: -- [ ] Issue 1: [Description] -- [ ] Issue 2: [Description] - ---- - -### Phase 2: Migrate Existing Entries -**Goal**: Add new required fields (`type`, `scope`) to all 61 YAML entries - -#### Phase 2 Deliverables -- [ ] All 61 YAML entries have `type` field -- [ ] All 61 YAML entries have `scope` field -- [ ] Validation passes for all entries - -#### Phase 2 Tasks - -- [ ] **Task 2.1**: Map category folders to extension types - - [ ] `data/plugins/` → `type: plugin` - - [ ] `data/themes/` → `type: theme` - - [ ] `data/agents/` → `type: agent` - - [ ] `data/projects/` → `type: project` - - [ ] `data/resources/` → `type: resource` - - [ ] `data/forks/` → `type: fork` - -- [ ] **Task 2.2**: Add `type` field to all entries - - [ ] Use `grep` to find all YAML files in `data/` subdirectories - - [ ] For each file in `data/plugins/`, add `type: plugin` after `description` - - [ ] For each file in `data/themes/`, add `type: theme` - - [ ] Continue for all category folders (use edit with replaceAll for efficiency) - - [ ] Verify files were modified correctly - -- [ ] **Task 2.3**: Add `scope` field to all entries - - [ ] Add `scope: [global, project]` to all entries (most extensions work both places) - - [ ] Consider special cases: - - Themes: May be `[global]` only - - Resources: May vary based on content type - - [ ] Add appropriate scope based on extension type analysis - -- [ ] **Task 2.4**: Run validation on all entries - - [ ] Execute `node scripts/validate.js` - - [ ] Fix any entries that fail validation - - [ ] Re-run validation until all 61 entries pass - -#### Phase 2 Manual Testing -**Testing Requirements**: User verifies migration was successful - -- [ ] Check 3-5 random YAML files for correct `type` field -- [ ] Check 3-5 random YAML files for correct `scope` field -- [ ] Run `node scripts/validate.js` and verify all entries pass -- [ ] Confirm count: 61 entries should be valid - -#### Phase 2 Review Process -**User Review Required**: Do NOT proceed to Phase 3 without user sign-off - -**Review Checklist**: -- [ ] All YAML files have `type` field matching their directory -- [ ] All YAML files have `scope` field -- [ ] Validation script shows 61 valid entries -- [ ] No schema validation errors -- [ ] User approves proceeding to next phase - -**Go/No-Go Decision**: [_______] (User fills in date and sign-off) -- [ ] **GO** - Proceed to Phase 3 -- [ ] **NO-GO** - Fix issues first - -**Issues to Fix**: -- [ ] Issue 1: [Description] -- [ ] Issue 2: [Description] - ---- - -### Phase 3: Update Generation Script -**Goal**: Update `scripts/generate-readme.js` to use new fields - -#### Phase 3 Deliverables -- [ ] Template includes new fields in output -- [ ] Backwards compatibility maintained (optional fields can be missing) -- [ ] README regenerates successfully - -#### Phase 3 Tasks - -- [ ] **Task 3.1**: Update README template - - [ ] Open `templates/README.template.md` - - [ ] Add badges or labels for `type` field (e.g., "[plugin]", "[theme]") - - [ ] Add tags display section if `tags` field is present - - [ ] Ensure template handles missing optional fields gracefully - -- [ ] **Task 3.2**: Update generation script logic - - [ ] Open `scripts/generate-readme.js` - - [ ] Ensure script reads new fields from YAML entries - - [ ] Add logic to skip optional fields if empty/missing - - [ ] Add type badges to extension listing output - -- [ ] **Task 3.3**: Regenerate README - - [ ] Run `node scripts/generate-readme.js` - - [ ] Check `README.md` for new field displays - - [ ] Verify backwards compatibility (entries without optional fields render correctly) - - [ ] Check that type badges appear correctly - -#### Phase 3 Manual Testing -**Testing Requirements**: User verifies README output - -- [ ] Open `README.md` and verify type badges are visible -- [ ] Check that entries with tags display them -- [ ] Verify entries without optional fields render without errors -- [ ] Review README for formatting issues - -#### Phase 3 Review Process -**User Review Required**: Do NOT proceed to Phase 4 without user sign-off - -**Review Checklist**: -- [ ] New fields appear in generated README -- [ ] Backwards compatibility works (no breaking changes) -- [ ] Formatting looks correct (badges, tags, etc.) -- [ ] User approves proceeding to next phase - -**Go/No-Go Decision**: [_______] (User fills in date and sign-off) -- [ ] **GO** - Proceed to Phase 4 -- [ ] **NO-GO** - Fix issues first - -**Issues to Fix**: -- [ ] Issue 1: [Description] -- [ ] Issue 2: [Description] - ---- - -### Phase 4: Update Contributing Guide -**Goal**: Document new fields in `contributing.md` - -#### Phase 4 Deliverables -- [ ] Contributing guide includes complete YAML format reference -- [ ] All new fields documented with examples -- [ ] Type and scope options documented - -#### Phase 4 Tasks - -- [ ] **Task 4.1**: Update `contributing.md` with new required fields - - [ ] Open `contributing.md` - - [ ] Add `type` field to YAML format reference - - [ ] Add `scope` field to YAML format reference - - [ ] Mark these as **required** fields - -- [ ] **Task 4.2**: Add installation template example - - [ ] Add `installation` field documentation - - [ ] Include markdown example with all sections - - [ ] Mark `installation` as **optional** - -- [ ] **Task 4.3**: Document type and scope options - - [ ] Add section listing all valid `type` values with descriptions - - [ ] Add section explaining `scope` values (`global`, `project`, `[global, project]`) - - [ ] Add `tags`, `min_version`, `homepage` documentation - -#### Phase 4 Manual Testing -**Testing Requirements**: User reviews documentation - -- [ ] Open `contributing.md` and verify new sections are present -- [ ] Check that YAML examples are valid -- [ ] Verify field descriptions match schema -- [ ] Test that documentation is clear for new contributors - -#### Phase 4 Review Process -**User Review Required**: Do NOT proceed to Phase 5 without user sign-off - -**Review Checklist**: -- [ ] All new fields documented in contributing guide -- [ ] Examples are accurate and complete -- [ ] Required vs optional fields clearly marked -- [ ] User approves proceeding to next phase - -**Go/No-Go Decision**: [_______] (User fills in date and sign-off) -- [ ] **GO** - Proceed to Phase 5 -- [ ] **NO-GO** - Fix issues first - -**Issues to Fix**: -- [ ] Issue 1: [Description] -- [ ] Issue 2: [Description] - ---- - -### Phase 5: Export Script (Future) -**Goal**: Create script for downstream JSON export - -#### Phase 5 Deliverables -- [ ] `scripts/export-json.js` script created -- [ ] Script outputs opencode.cafe compatible JSON -- [ ] Field mapping documented - -#### Phase 5 Tasks - -- [ ] **Task 5.1**: Create export script - - [ ] Create `scripts/export-json.js` - - [ ] Load all YAML entries from `data/` directories - - [ ] Map fields according to downstream compatibility table (Section 7): - - `name` → `displayName` - - `repo` → `repoUrl` - - `type` → `type` (direct map) - - `tags` → `tags` - - `homepage` → `homepageUrl` - - `installation` → `installation` - - filename → `productId` - -- [ ] **Task 5.2**: Generate productId from filename - - [ ] Extract filename without extension (e.g., `codegpt.yaml` → `codegpt`) - - [ ] Use as `productId` in output JSON - -- [ ] **Task 5.3**: Test export output - - [ ] Run `node scripts/export-json.js` - - [ ] Verify output is valid JSON array - - [ ] Check that field mapping is correct - - [ ] Validate against opencode.cafe schema (if available) - -#### Phase 5 Manual Testing -**Testing Requirements**: User verifies export script - -- [ ] Run `node scripts/export-json.js` > dist/output.json -- [ ] Verify output is valid JSON -- [ ] Check 2-3 entries for correct field mapping -- [ ] Verify `productId` is derived from filename - -#### Phase 5 Review Process -**User Review Required**: Phase 5 completion is optional (future enhancement) - -**Review Checklist**: -- [ ] Export script runs successfully -- [ ] Output JSON is valid -- [ ] Field mapping matches specification -- [ ] User approves Phase 5 completion - -**Go/No-Go Decision**: [_______] (User fills in date and sign-off) -- [ ] **GO** - Phase 5 complete -- [ ] **NO-GO** - Fix issues first - -**Issues to Fix**: -- [ ] Issue 1: [Description] -- [ ] Issue 2: [Description] - ---- - -### Important Notes - -#### What NOT To Do -- **DO NOT run `npm install`** - The project may have existing dependencies; only run if explicitly instructed -- **DO NOT push changes to remote** - Always ask user before committing or pushing -- **DO NOT modify unrelated files** - Stay within the scope of this implementation plan -- **DO NOT delete existing data** - Back up or migrate data, never remove without confirmation -- **DO NOT change existing field behavior** - Only add new fields, don't modify existing ones - -#### Commands to Use ```bash # Validate schema and entries node scripts/validate.js # Regenerate README node scripts/generate-readme.js - -# Export JSON (Phase 5) -node scripts/export-json.js ``` -#### File Locations -- Schema: `data/schema.json` -- YAML entries: `data/{category}/*.yaml` -- Generation script: `scripts/generate-readme.js` -- Validation script: `scripts/validate.js` -- Template: `templates/README.template.md` -- Contributing guide: `contributing.md` -- Export script: `scripts/export-json.js` (to be created) +--- + +## 9. Future Work + +Remaining tasks for the awesome-opencode registry. + +### 9.1 Update Contributing Guide + +Update `contributing.md` to: +- Reference `examples/` directory for full field documentation +- Document optional fields (`scope`, `tags`, `min_version`, `homepage`, `installation`) +- Explain scope behavior and defaults + +### 9.2 README Generation Enhancements (Optional) + +Update `scripts/generate-readme.js` to optionally display: +- Tags for entries that have them +- Scope indicators +- Type badges derived from directory + +### 9.3 Export Script for Downstream Platforms + +Create `scripts/export-json.js` to generate JSON for platforms like opencode.cafe: + +```javascript +// Pseudocode +for each file in data/{category}/*.yaml: + entry = parseYAML(file) + entry.type = category // derived from directory + entry.productId = filename // derived from filename + output.push(mapFields(entry)) +writeJSON(output) +``` + +**Field mapping:** +| YAML | JSON Output | +|------|-------------| +| `name` | `displayName` | +| `repo` | `repoUrl` | +| `tagline` | `tagline` | +| `description` | `description` | +| (directory) | `type` | +| (filename) | `productId` | +| `scope` | `scope` (default `["global"]`) | +| `tags` | `tags` (default `[]`) | +| `homepage` | `homepageUrl` | +| `installation` | `installation` | +| `min_version` | `minVersion` | + +**Usage:** +```bash +node scripts/export-json.js > dist/registry.json +node scripts/export-json.js --pretty > dist/registry.json +``` --- -## Success Criteria - -### Schema Migration Complete When -- [ ] `data/schema.json` includes all new fields with correct types -- [ ] All 61 YAML entries have `type` and `scope` fields -- [ ] `node scripts/validate.js` passes without errors -- [ ] `node scripts/generate-readme.js` produces valid README with new fields -- [ ] `contributing.md` documents all new fields - -### Quality Criteria -- [ ] Backwards compatibility maintained (optional fields can be missing) -- [ ] No breaking changes to existing data -- [ ] TypeScript compilation passes (if applicable) -- [ ] Linting passes (if applicable) -- [ ] All tests passing (if tests exist) - ---- - -## Progress Log - -**Started**: [Date] -**Last Updated**: 2026-01-11 - -### Completed Tasks -- [ ] [Date] Task completed - [Brief description] -- [ ] [Date] Another task completed - [Brief description] - -### Issues Encountered -- [Date] Issue description and how it was resolved -- [Date] Another issue and resolution - -### Phase Status -- Phase 1: [pending | in_progress | testing | review | completed] -- Phase 2: [pending | in_progress | testing | review | completed] -- Phase 3: [pending | in_progress | testing | review | completed] -- Phase 4: [pending | in_progress | testing | review | completed] -- Phase 5: [pending | in_progress | testing | review | completed] (future) - ---- - -**End of Implementation Plan** - ---- - -*Document Version: 1.1* -*Last Updated: January 2026* +*Document Version: 1.2* +*Last Updated: 2026-01-12* diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..f9c7928 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,40 @@ +# Examples + +This directory contains exemplar YAML files showing the full schema for each extension type. + +**These are reference examples, not actual entries.** + +## Usage + +When adding a new entry to `data/{category}/`, use the corresponding example as a reference: + +| Adding to... | Reference | +|-------------|-----------| +| `data/plugins/` | [plugin.yaml](plugin.yaml) | +| `data/themes/` | [theme.yaml](theme.yaml) | +| `data/agents/` | [agent.yaml](agent.yaml) | +| `data/projects/` | [project.yaml](project.yaml) | +| `data/resources/` | [resource.yaml](resource.yaml) | +| `data/forks/` | [fork.yaml](fork.yaml) | + +## Required vs Optional Fields + +### Required (all entries must have) +- `name` - Display name +- `repo` - Repository URL (https://github.com/...) +- `tagline` - Short description (max 120 chars) +- `description` - Full description (can be multi-line) + +### Optional (include if relevant) +- `scope` - Installation scope: `[global]`, `[project]`, or `[global, project]` (defaults to `[global]`) +- `tags` - Array of strings for filtering +- `min_version` - Minimum OpenCode version (semver) +- `homepage` - Documentation URL if different from repo +- `installation` - Markdown installation instructions + +## Notes + +- **Type is derived from directory** - No `type` field needed; it's inferred from the folder +- **Scope is optional** - Defaults to `[global]`; add if project-level install is relevant +- **Installation is markdown** - Use headers, code blocks, lists as needed +- **Schema allows additional fields** - Future fields can be added without breaking existing entries diff --git a/examples/agent.yaml b/examples/agent.yaml new file mode 100644 index 0000000..2cd897f --- /dev/null +++ b/examples/agent.yaml @@ -0,0 +1,89 @@ +# Example Agent Entry +# Agents are custom AI configurations and skills for specialized tasks. +# This category includes both agent configs and reusable skills. +# Place actual entries in: data/agents/your-agent-name.yaml + +# ============================================================================ +# REQUIRED FIELDS +# ============================================================================ + +name: Example Security Reviewer +repo: https://github.com/example/opencode-security-agent +tagline: AI agent specialized in security code review +description: | + A custom agent configuration for security-focused code review. + Includes: + - Custom system prompts for security analysis + - Predefined tools for vulnerability scanning + - Skills for OWASP Top 10 detection + +# ============================================================================ +# OPTIONAL FIELDS +# ============================================================================ + +# Scope defines where the extension can be installed (defaults to [global]) +# Agents can be installed globally or per-project +scope: + - global # ~/.config/opencode/agent/ + - project # .opencode/agent/ + +tags: + - security + - code-review + - agent + - skill + +min_version: "1.0.0" + +homepage: https://example.com/docs/security-agent + +installation: | + ## Prerequisites + - OpenCode 1.0.0 or later + + ## Installation + + ### Global (all projects) + ```bash + # Copy agent configuration + mkdir -p ~/.config/opencode/agent/security-reviewer + curl -o ~/.config/opencode/agent/security-reviewer/agent.json \ + https://raw.githubusercontent.com/example/opencode-security-agent/main/agent.json + ``` + + ### Project-only + ```bash + # Copy to project agent directory + mkdir -p .opencode/agent/security-reviewer + curl -o .opencode/agent/security-reviewer/agent.json \ + https://raw.githubusercontent.com/example/opencode-security-agent/main/agent.json + ``` + + ## Installing Skills + If this agent includes skills: + ```bash + # Global skill + mkdir -p ~/.config/opencode/skill/security-review + curl -o ~/.config/opencode/skill/security-review/SKILL.md \ + https://raw.githubusercontent.com/example/opencode-security-agent/main/SKILL.md + ``` + + ## Configuration + Add to your `opencode.json`: + ```json + { + "agents": { + "security-reviewer": { + "enabled": true + } + } + } + ``` + + ## Files Modified + - `~/.config/opencode/agent/security-reviewer/agent.json` + - `~/.config/opencode/skill/security-review/SKILL.md` (if using skills) + + ## Removal + 1. Delete the agent directory + 2. Remove config entry from `opencode.json` diff --git a/examples/fork.yaml b/examples/fork.yaml new file mode 100644 index 0000000..f9506bc --- /dev/null +++ b/examples/fork.yaml @@ -0,0 +1,89 @@ +# Example Fork Entry +# Forks are modified builds of OpenCode with custom features or patches. +# Place actual entries in: data/forks/your-fork-name.yaml + +# ============================================================================ +# REQUIRED FIELDS +# ============================================================================ + +name: Example Enterprise Fork +repo: https://github.com/example/opencode-enterprise +tagline: OpenCode fork with enterprise authentication and audit logging +description: | + A fork of OpenCode designed for enterprise environments. + + Additions: + - SAML/SSO authentication + - Audit logging for compliance + - Custom model routing + - Air-gapped deployment support + +# ============================================================================ +# OPTIONAL FIELDS +# ============================================================================ + +# Note: Forks don't use 'scope' - they replace the entire OpenCode installation + +tags: + - enterprise + - fork + - authentication + - audit + +min_version: "1.0.0" + +homepage: https://example.com/opencode-enterprise + +installation: | + ## Prerequisites + - Go 1.21+ (for building from source) + - Or: Docker (for containerized deployment) + + ## Installation from Source + ```bash + # Clone the fork + git clone https://github.com/example/opencode-enterprise + cd opencode-enterprise + + # Build + go build -o opencode-enterprise ./cmd/opencode + + # Install (replaces standard opencode) + sudo mv opencode-enterprise /usr/local/bin/opencode + ``` + + ## Docker Installation + ```bash + docker pull example/opencode-enterprise:latest + alias opencode='docker run -it --rm \ + -v ~/.config/opencode:/root/.config/opencode \ + -v $(pwd):/workspace \ + example/opencode-enterprise' + ``` + + ## Configuration + Enterprise-specific configuration in `opencode.json`: + ```json + { + "enterprise": { + "sso": { + "provider": "okta", + "domain": "company.okta.com" + }, + "audit": { + "enabled": true, + "destination": "s3://audit-logs/" + } + } + } + ``` + + ## Files Modified + - `/usr/local/bin/opencode` (replaced binary) + - `~/.config/opencode/opencode.json` (enterprise config) + + ## Reverting to Standard OpenCode + ```bash + # Reinstall standard OpenCode + curl -fsSL https://opencode.ai/install | bash + ``` diff --git a/examples/plugin.yaml b/examples/plugin.yaml new file mode 100644 index 0000000..d36e831 --- /dev/null +++ b/examples/plugin.yaml @@ -0,0 +1,81 @@ +# Example Plugin Entry +# Plugins are JS/TS modules that extend OpenCode's core functionality. +# Place actual entries in: data/plugins/your-plugin-name.yaml + +# ============================================================================ +# REQUIRED FIELDS +# ============================================================================ + +name: Example Plugin +repo: https://github.com/example/opencode-example-plugin +tagline: A brief description of what this plugin does (max 120 chars) +description: | + A longer description explaining the plugin in detail. + Can be multiple lines and include: + - Feature highlights + - Use cases + - Key benefits + +# ============================================================================ +# OPTIONAL FIELDS +# ============================================================================ + +# Scope defines where the extension can be installed (defaults to [global]) +# Most plugins work in both locations - omit or specify only what's relevant +scope: + - global # ~/.config/opencode/plugin/ + - project # .opencode/plugin/ + +# Tags for filtering and discoverability +tags: + - productivity + - ai + - authentication + +# Minimum OpenCode version required (semver format) +min_version: "1.0.0" + +# Documentation URL if different from repository +homepage: https://example.com/docs/opencode-plugin + +# Detailed installation instructions (markdown format) +# Include sections relevant to your plugin +installation: | + ## Prerequisites + - OpenCode 1.0.0 or later + - Node.js 18+ (for local development) + + ## Installation + + ### Global (all projects) + ```bash + # Clone to global plugins directory + git clone https://github.com/example/opencode-example-plugin ~/.config/opencode/plugin/example-plugin + ``` + + ### Project-only + ```bash + # Clone to project plugins directory + git clone https://github.com/example/opencode-example-plugin .opencode/plugin/example-plugin + ``` + + ## Configuration + Add to your `opencode.json`: + ```json + { + "plugins": { + "example-plugin": { + "enabled": true, + "option1": "value" + } + } + } + ``` + + ## Files Modified + - `~/.config/opencode/opencode.json` (config entry) + - `~/.config/opencode/plugin/example-plugin/` (plugin files) + + ## Removal + 1. Remove the plugin directory + 2. Remove the config entry from `opencode.json` diff --git a/examples/project.yaml b/examples/project.yaml new file mode 100644 index 0000000..0995b90 --- /dev/null +++ b/examples/project.yaml @@ -0,0 +1,72 @@ +# Example Project Entry +# Projects are standalone applications and utilities built for/with OpenCode. +# These are complete apps, not extensions. +# Place actual entries in: data/projects/your-project-name.yaml + +# ============================================================================ +# REQUIRED FIELDS +# ============================================================================ + +name: Example OpenCode Dashboard +repo: https://github.com/example/opencode-dashboard +tagline: Web-based dashboard for monitoring OpenCode sessions +description: | + A standalone web application for monitoring and managing + OpenCode sessions across multiple projects. + + Features: + - Real-time session monitoring + - Token usage analytics + - Multi-project overview + +# ============================================================================ +# OPTIONAL FIELDS +# ============================================================================ + +# Scope is often not relevant for standalone projects +# Include only if the project can be installed globally vs per-project + +tags: + - dashboard + - monitoring + - web-ui + - analytics + +min_version: "1.0.0" + +homepage: https://example.com/opencode-dashboard + +installation: | + ## Prerequisites + - Node.js 18+ + - OpenCode 1.0.0 or later + + ## Installation + ```bash + # Clone the repository + git clone https://github.com/example/opencode-dashboard + cd opencode-dashboard + + # Install dependencies + npm install + + # Start the dashboard + npm start + ``` + + ## Configuration + Create a `.env` file: + ```bash + OPENCODE_LOG_DIR=~/.config/opencode/logs + PORT=3000 + ``` + + ## Usage + Open `http://localhost:3000` in your browser. + + ## Docker (Alternative) + ```bash + docker run -p 3000:3000 \ + -v ~/.config/opencode:/opencode:ro \ + example/opencode-dashboard + ``` diff --git a/examples/resource.yaml b/examples/resource.yaml new file mode 100644 index 0000000..ab6531b --- /dev/null +++ b/examples/resource.yaml @@ -0,0 +1,80 @@ +# Example Resource Entry +# Resources include guides, configs, MCP servers, tools, and commands. +# Place actual entries in: data/resources/your-resource-name.yaml + +# ============================================================================ +# REQUIRED FIELDS +# ============================================================================ + +name: Example MCP Server +repo: https://github.com/example/opencode-mcp-database +tagline: MCP server for database access and querying +description: | + A Model Context Protocol (MCP) server that provides + OpenCode with database access capabilities. + + Supports: + - PostgreSQL, MySQL, SQLite + - Read-only query execution + - Schema introspection + +# ============================================================================ +# OPTIONAL FIELDS +# ============================================================================ + +# Scope defines where the extension can be installed (defaults to [global]) +# For MCP servers, scope indicates global vs project-specific config +scope: + - global # System-wide MCP server + - project # Project-specific database access + +tags: + - mcp-server + - database + - postgresql + - mysql + +min_version: "1.0.0" + +homepage: https://example.com/docs/mcp-database + +installation: | + ## Prerequisites + - Node.js 18+ + - Database connection credentials + + ## Installation + ```bash + # Install globally via npm + npm install -g @example/opencode-mcp-database + ``` + + ## Configuration + Add to your `opencode.json`: + ```json + { + "mcpServers": { + "database": { + "command": "opencode-mcp-database", + "args": ["--connection", "postgresql://localhost/mydb"] + } + } + } + ``` + + ## Environment Variables + Alternatively, configure via environment: + ```bash + export DATABASE_URL="postgresql://localhost/mydb" + ``` + + ## Security Notes + - Use read-only database credentials + - Consider connection pooling for production + - Review query permissions carefully + + ## Removal + ```bash + npm uninstall -g @example/opencode-mcp-database + ``` + Remove the `mcpServers.database` entry from `opencode.json`. diff --git a/examples/theme.yaml b/examples/theme.yaml new file mode 100644 index 0000000..a2b5713 --- /dev/null +++ b/examples/theme.yaml @@ -0,0 +1,59 @@ +# Example Theme Entry +# Themes customize the OpenCode editor appearance. +# Place actual entries in: data/themes/your-theme-name.yaml + +# ============================================================================ +# REQUIRED FIELDS +# ============================================================================ + +name: Example Dark Theme +repo: https://github.com/example/opencode-example-theme +tagline: A beautiful dark theme with vibrant accents +description: | + A dark theme designed for extended coding sessions. + Features high contrast syntax highlighting and + carefully chosen colors to reduce eye strain. + +# ============================================================================ +# OPTIONAL FIELDS +# ============================================================================ + +# Scope defines where the extension can be installed (defaults to [global]) +# Themes are typically global-only +scope: + - global # ~/.config/opencode/themes/ + +tags: + - dark + - high-contrast + - syntax-highlighting + +min_version: "1.0.0" + +homepage: https://example.com/themes/dark + +installation: | + ## Installation + + ### Global + ```bash + # Download theme JSON + curl -o ~/.config/opencode/themes/example-dark.json \ + https://raw.githubusercontent.com/example/opencode-example-theme/main/theme.json + ``` + + ## Configuration + Add to your `opencode.json`: + ```json + { + "theme": "example-dark" + } + ``` + + ## Files Modified + - `~/.config/opencode/themes/example-dark.json` + - `~/.config/opencode/opencode.json` (theme reference) + + ## Removal + 1. Delete `~/.config/opencode/themes/example-dark.json` + 2. Change `theme` in `opencode.json` to another theme