|
| 1 | +# Zotero Plugin Registry - AI Agent Instructions |
| 2 | + |
| 3 | +## Architecture Overview |
| 4 | + |
| 5 | +**Monorepo Structure**: pnpm workspace with four main packages: |
| 6 | +- **bot**: CLI tool that processes plugins (fetches metadata, parses `update.json`) |
| 7 | +- **shared**: Common types, schemas, and exports shared by bot and frontend |
| 8 | +- **frontend**: (Vue/React app for displaying plugin listings) |
| 9 | +- **plugins**: Directory containing plugin metadata files (`plugins/<plugin-id>/meta.json`) |
| 10 | + |
| 11 | +**Data Flow**: `meta.json` (manual) → bot processes → generates `meta.generated.json` + `latest.json` → consumed by frontend/indexing |
| 12 | + |
| 13 | +## Critical Knowledge |
| 14 | + |
| 15 | +### Plugin Data Model |
| 16 | +- **Plugin ID ** (e.g., `[email protected]`): Unique identifier, used as directory name |
| 17 | +- **meta.json**: Manual metadata containing `id`, `name`, `update_json` URL, `description`, `homepage`, `tags` |
| 18 | +- **update.json**: Hosted by plugin developer, follows Zotero extension manifest format with version/compatibility data |
| 19 | +- **Tags**: Predefined enum (`metadata`, `interface`, `attachment`, `notes`, `reader`, `productivity`, `visualization`, `integration`, `ai`, `writing`, `developer`, `favorite`, `others`) |
| 20 | +- See [shared/src/types.ts](shared/src/types.ts) for complete type definitions |
| 21 | + |
| 22 | +### Bot Processing Pipeline |
| 23 | +1. **CLI Entry** ([bot/src/cli.ts](bot/src/cli.ts)): Accepts optional plugin ID, defaults to all plugins |
| 24 | +2. **Process Plugins** ([bot/src/processor.ts](bot/src/processor.ts)): Reads `meta.json`, fetches remote `update.json` |
| 25 | +3. **Parse Versions**: Extracts version data from `addons[pluginId].updates` array in update.json |
| 26 | +4. **Extract Compatibility**: Maps `applications.zotero` and `applications.gecko` min/max versions |
| 27 | +5. **Cache**: Stores hash in `.cache.json` to detect update.json changes |
| 28 | +6. **Report**: ([bot/src/report.ts](bot/src/report.ts)) Handles GitHub integration and error reporting |
| 29 | + |
| 30 | +### Authentication & External Access |
| 31 | +- **GitHub Token**: Required environment variable `GITHUB_TOKEN` for API-rate-limited GitHub requests |
| 32 | +- **HTTP Fetch** ([bot/src/utils.ts](bot/src/utils.ts)): |
| 33 | + - Detects GitHub URLs and adds Bearer token |
| 34 | + - Used for fetching remote `update.json` files |
| 35 | + - 10-second timeout for all requests |
| 36 | + - Axios-based with response type support (json, arraybuffer, etc.) |
| 37 | + |
| 38 | +## Developer Workflows |
| 39 | + |
| 40 | +### Build Commands |
| 41 | +```bash |
| 42 | +# Install dependencies (pnpm v10.24.0 required via corepack) |
| 43 | +pnpm install |
| 44 | + |
| 45 | +# Process all plugins |
| 46 | +pnpm run build |
| 47 | + |
| 48 | +# Process specific plugin by ID |
| 49 | + |
| 50 | + |
| 51 | +# Generate TypeScript schema from types |
| 52 | +pnpm run -C shared generate-schema |
| 53 | +``` |
| 54 | + |
| 55 | +### Adding New Plugins |
| 56 | +1. Create `plugins/<plugin-id>/` directory |
| 57 | +2. Add `meta.json` with required fields: `id`, `name`, `update_json`, optionally `description`, `homepage`, `tags` |
| 58 | +3. Run bot to generate `meta.generated.json` and `latest.json` |
| 59 | +4. Commit and open PR |
| 60 | + |
| 61 | +### Code Quality |
| 62 | +- **Linting**: `eslint` with `@antfu/eslint-config`, allows `console` statements |
| 63 | +- **Pre-commit**: Husky runs `lint-staged` on all changed files |
| 64 | +- Fix linting: `pnpm run lint:fix` |
| 65 | + |
| 66 | +## Project Conventions |
| 67 | + |
| 68 | +### TypeScript Patterns |
| 69 | +- **Monorepo imports**: Use workspace protocol, e.g., `@zotero-plugin-registry/shared` |
| 70 | +- **Module system**: ESM (`"type": "module"` in all package.json files) |
| 71 | +- **Async/await**: Standard for all I/O operations |
| 72 | + |
| 73 | +### File Organization |
| 74 | +- Shared types live in `shared/src/types.ts`, exported via package exports in `shared/package.json` |
| 75 | +- Schema generation: Run `scripts/generate-schema.sh` to create `meta.schema.json` from types |
| 76 | +- Plugin metadata format is validated against `meta.schema.json` |
| 77 | + |
| 78 | +### Error Handling |
| 79 | +- **ProcessResult**: Captures both `success: string[]` and `errors: PluginError[]` |
| 80 | +- Continues processing remaining plugins even if one fails |
| 81 | +- Exit code 1 when errors occur (for CI/CD) |
| 82 | + |
| 83 | +## Integration Points |
| 84 | + |
| 85 | +### External Dependencies |
| 86 | +- **octokit**: GitHub API client (not actively used in current code but included) |
| 87 | +- **axios**: HTTP requests with auth headers |
| 88 | +- **adm-zip**: XPI file handling (structure for future use) |
| 89 | +- **globby**: File globbing for plugin discovery |
| 90 | +- **jsonc**: JSON with comments parsing |
| 91 | +- **es-toolkit**: Utility library |
| 92 | +- **fs-extra**: File system operations |
| 93 | + |
| 94 | +### CI/CD Considerations |
| 95 | +- GITHUB_TOKEN must be available in environment for GitHub URL requests |
| 96 | +- Error reporting to GitHub issues/PRs (via `report.ts`, implementation details present) |
| 97 | +- Build artifacts: `meta.generated.json` and `latest.json` files per plugin |
| 98 | + |
| 99 | +## Common Task Patterns |
| 100 | + |
| 101 | +**Adding features to processor**: Modify [bot/src/processor.ts](bot/src/processor.ts), ensure `ProcessResult` is properly populated with successes/errors |
| 102 | + |
| 103 | +**Updating shared types**: Edit [shared/src/types.ts](shared/src/types.ts), then run schema generation to update validation |
| 104 | + |
| 105 | +**Debugging plugin processing**: Check `.cache.json` in plugin directory to understand last-fetch state; verify `update_json` URL format matches Zotero manifest structure |
| 106 | + |
| 107 | +**Working with pnpm**: Always use workspace commands: `pnpm run -C <package>` or `pnpm run --only <package>` for scoped tasks |
0 commit comments