Vetwo Registry

The official Git-based Registry for the Vetwo ecosystem. Stores, validates, indexes, and distributes reusable resources for every Vetwo tool.

What Is This?

This is not a marketplace website. It is the single source of truth for every reusable resource inside Vetwo. Tools like @vetwo/repo-fetch, @vetwo/create, and @vetwo/doctor all consume this Registry through the official SDK.

Quick Start

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run the interactive wizard
pnpm registry:wizard

# Or build the registry directly
pnpm registry:build

# Validate all resources
pnpm registry:validate

How Tools Consume the Registry

import { RegistryClient } from '@vetwo/registry-sdk';

const registry = new RegistryClient();
await registry.load();

// Search
const results = await registry.search('next');

// Find a specific resource
const plugin = await registry.find('@vetwo/plugin-next');

// Resolve dependencies and compatibility
const resolved = await registry.resolve(plugin.id);

// Plan installation
const plan = await registry.planInstallation(plugin.id);

Repository Structure

vetwo-registry/
├── resources/              # All registry resources (source of truth)
│   ├── plugins/
│   ├── modules/
│   ├── templates/
│   ├── presets/
│   ├── snippets/
│   ├── recipes/
│   ├── examples/
│   ├── themes/
│   └── configs/
├── registry/               # Generated registry files (DO NOT edit manually)
│   ├── index.json
│   ├── plugins.json
│   ├── modules.json
│   ├── statistics.json
│   ├── search-index.json
│   ├── checksums.json
│   └── ...
├── packages/
│   ├── registry-builder/   # Scanner, validator, generator, CLI
│   ├── registry-sdk/       # Official SDK for consuming the Registry
│   ├── registry-schema/    # Zod validation schemas
│   ├── registry-types/     # TypeScript type definitions
│   └── registry-utils/     # Filesystem, hashing, logging utilities
├── docs/                   # Documentation
├── .github/workflows/      # CI: validate, test, verify generated files
├── turbo.json
├── pnpm-workspace.yaml
└── README.md

Packages

Package	Description
@vetwo/registry-sdk	Official SDK for consuming the Registry
@vetwo/registry-builder	Scanner, validator, generator, CLI wizard
@vetwo/registry-schema	Zod schemas for resource.json validation
@vetwo/registry-types	All public TypeScript types
@vetwo/registry-utils	Filesystem, hashing, logger, path helpers

Documentation

Architecture

• Overview - High-level architecture with flow diagrams
• Monorepo Layout - Turborepo, pnpm workspaces, build order
• Packages - Each package's responsibility and public API
• Data Flow - From resource authoring to SDK consumption
• Dependency Graph - How packages depend on each other
• Resource Lifecycle - From creation to verification
• Pipeline - Registry generation pipeline in detail
• SDK Architecture - Service-based architecture
• Scalability - Current limits and future plans
• Design Principles - 10 enforced principles

Concepts

• Resource | Manifest | Registry
• Builder | SDK | Target
• Owner | Category | Search Index
• Checksum | Dependency | Compatibility

Resource Types

• Plugins | Modules | Templates
• Presets | Snippets | Recipes
• Examples | Themes | Configs
• Manifest Specification | Authoring Guide | Shipping Spec

Builder

• Overview - Architecture, scanning, validation, generation
• Generated Files - Every output file documented

SDK

• Overview - Service architecture, RegistryClient
• API Reference - Every public method documented
• Events - Typed event system
• Caching - TTL-based caching, lazy loading

CLI

• Commands - All 7 commands with examples

Development

• Setup | Testing | Conventions
• Contributing

Reference

• Packages | Types | Registry Files | Manifest Fields

Examples

• Create a Plugin | Create a Template | Create a Module
• Use the SDK

Decisions

• 001 - Turborepo | 002 - JSON Registry | 003 - Unified Manifest
• 004 - Targets & Owner | 005 - SDK Separation | 006 - Service Architecture

Creating a Resource

1. Choose the resource type directory (e.g. resources/plugins/)
2. Create a new directory with a lowercase kebab-case name
3. Add a resource.json manifest
4. Add a README.md
5. Add a LICENSE file
6. Run the registry builder to validate and generate indexes

See the Authoring Guide for complete instructions.

Resource Layout

resources/plugins/my-plugin/
├── resource.json      # Required: manifest
├── README.md          # Required: documentation
├── LICENSE            # Required: license file
├── CHANGELOG.md       # Optional: version history
├── src/               # Optional: source code
├── examples/          # Optional: usage examples
└── tests/             # Optional: tests

resource.json Schema

{
  "id": "@vetwo/plugin-my-plugin",
  "type": "plugin",
  "name": "my-plugin",
  "displayName": "My Plugin",
  "version": "1.0.0",
  "description": "A short description of the plugin",
  "category": "ui",
  "tags": ["ui", "component"],
  "keywords": ["plugin", "ui"],
  "license": "MIT",
  "author": {
    "name": "Your Name",
    "github": "your-username"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "compatibility": {
    "frameworks": ["vue", "react"],
    "runtimes": ["node", "browser"],
    "platforms": ["linux", "macos", "windows"]
  },
  "dependencies": {},
  "peerDependencies": {},
  "optionalDependencies": {},
  "conflicts": [],
  "targets": ["*"],
  "entry": "src",
  "owner": {
    "organization": "your-org",
    "repository": "your-repo",
    "package": "@vetwo/plugin-my-plugin"
  }
}

See the Manifest Specification for every field documented.

Validation Rules

The builder validates every resource:

Check	Severity
Manifest schema validity	Error
Directory name matches name field	Error
Duplicate resource IDs	Error
Missing targets	Error
Missing owner fields	Error
Unknown target package	Warning
Missing README.md	Warning
Missing LICENSE	Warning
Missing entry directory	Warning
Missing documentation field	Warning

Registry Generation

Running the builder generates 19 files in registry/:

File	Description
index.json	Master index with all resources, categories, tags, statistics, checksums
search-index.json	Flat array of all resources for search
statistics.json	Aggregate counts by type, category, target
checksums.json	SHA-256 checksums for integrity verification
categories.json	Resources grouped by category
tags.json	Resources grouped by tag
shared.json	Resource IDs targeting all projects (["*"])
by-project.json	Resources grouped by target project
by-repository.json	Resources grouped by repository
by-package.json	Resources grouped by package
plugins.json	All plugin-type resources
modules.json	All module-type resources
templates.json	All template-type resources
presets.json	All preset-type resources
snippets.json	All snippet-type resources
recipes.json	All recipe-type resources
examples.json	All example-type resources
themes.json	All theme-type resources
configs.json	All config-type resources

Generation is deterministic — running twice without changes produces identical output (except generatedAt timestamps).

See Generated Files for complete file specifications.

CLI

# Interactive wizard
pnpm registry:wizard

# Build registry (non-interactive)
pnpm registry:build

# Validate only
pnpm registry:validate

Options

--resources <path>   Path to resources directory (default: ./resources)
--output <path>      Path to output directory (default: ./registry)
--verbose            Enable verbose logging

See CLI Commands for complete command documentation.

CI/CD

The GitHub Actions workflow:

1. Installs dependencies and builds all packages
2. Runs lint, typecheck, and tests (Node 20 and 22)
3. Validates all resources
4. Generates the registry
5. Fails if generated files are stale (contributors must regenerate locally)

This ensures the registry is always in sync with the resource definitions.

Resource Types

Type	Directory	ID Pattern	Description
plugin	resources/plugins/	@vetwo/plugin-<name>	Project plugins
module	resources/modules/	@vetwo/mod-<name>	Reusable modules
template	resources/templates/	@vetwo/tpl-<name>	Project templates
preset	resources/presets/	@vetwo/preset-<name>	Configuration presets
snippet	resources/snippets/	@vetwo/snippet-<name>	Code snippets
recipe	resources/recipes/	@vetwo/recipe-<name>	Step-by-step guides
example	resources/examples/	@vetwo/example-<name>	Example projects
theme	resources/themes/	@vetwo/theme-<name>	Visual themes
config	resources/configs/	@vetwo/config-<name>	Shared configurations

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Typecheck
pnpm typecheck

See Development Setup for detailed instructions.

License

MIT