How northword/zotero-plugin-scaffold works
Main Components
• Monorepo Structure: Represent the overall project as a monorepo containing multiple npm packages.
• Packages: There are three major internal packages:
– “create”: Handles generating scaffolding for new Zotero plugin projects.
– “eslint-config”: Provides standardized ESLint configurations and scripts (including configurations and type generation).
– “scaffold”: This is the core package that contains the CLI, core utilities, and modules for building, testing, releasing, and even starting Zotero in development mode. It includes several submodules:
– CLI entry point (src/cli.ts) to parse commands.
– Core modules:
• Builder (in core/builder.ts)
• Linter (in core/linter.ts)
• Releaser (with submodules like bump management, GitHub integration, Zotero-specific release logic)
• Tester (includes headless testing and HTTP reporting)
• Server component (src/core/server.ts) that may start local services (for plugin testing or live reload)
• Documentation: The “docs” folder (with a VitePress site) shows an external view of how to use these tools.
• CI/CD Pipeline: Represent GitHub workflows (under .github/workflows) that automate testing (ci.yml) and issue management (issuebot.yml).
• Supporting Configuration Tools: Files such as .husky hooks for pre-commit, package.json in the root and in each package, and pnpm workspace configuration files.
Relationships and Interactions
• Underlying utility modules – such as utils for file operations, logging, watchers, and integration with Zotero runner – serve the core services. Represent these as shared libraries within the scaffold package.
Architectural Patterns & Design Principles
• Modular Design: The project is partitioned into discrete packages, which is ideal for separation of concerns. Each package (create, eslint-config, scaffold) is responsible for its own functionality.
• Layered Services: Within the scaffold, distinguish between core “business logic” (builder, linter, releaser, tester) and “utility services” (file operations, logging, watchers, preference management).
• Testability: Including both unit (in test/unit) and end-to-end tests (test/e2e) emphasizes a design that separates concerns and facilitates testing.
Relevant Technologies, Frameworks, and Tools
• TypeScript: Everything is built in TypeScript.
• Node.js & npm (pnpm): The entire ecosystem relies on Node.js with package management (pnpm in a workspace).
• GitHub Actions: For CI/CD automation.
• Husky: For Git hooks.
• VitePress: For documentation hosting.
• ESLint and related tooling: Provided through the eslint-config package.
Instructing the Principal Software Engineer
• That each component (package) is clearly labeled.
– Monorepo-level components (packages).
– Internal modules within the scaffold package (command, services, utilities).
– External integrations (GitHub Actions, Zotero client interactions).
• Be very detailed: don’t shy away from splitting the system into many fine-grained components if it means clarity.
• Also, include peripheral elements like the documentation system and CI/CD pipeline to provide a full picture of how the tool is used in development and integration.