Vpkg Package System

What is Vpkg?

Vpkg (Vandor Package) is Vandor's system for delivering transport and infrastructure code into your project on demand. Instead of baking an HTTP server, a database driver, a cache client, and a message queue into every project from the start, Vpkg lets you install only what you actually need.

Think of it like shadcn/ui for backend infrastructure. Vpkg is not a Go module replacement. It does not add entries to your go.mod. Instead, it copies carefully structured code directly into your project. You own that code completely. You can read it, modify it, and debug it like any other code you wrote yourself.

The 8 Official Packages

Vandor v0.4 ships with eight official packages that cover the most common infrastructure needs:

Package Tiers

Not all Vpkg packages are created equal. Vandor uses a tiered system to communicate trust and quality:

Official Packages (@official/)

Maintained by the Vandor core team. These packages are:

• Tested against every Vandor release
• Guaranteed to follow the folder contract and import rules
• Covered by Vandor's semantic versioning guarantees
• The eight packages listed above

Verified Packages (@verified/)

Created by the community but reviewed and verified by the Vandor team. These packages:

• Pass automated compatibility checks
• Follow the Vpkg manifest specification
• Are reviewed for security and code quality
• May not be tested against every Vandor release

Community Packages (@community/)

Created and maintained by community members. These packages:

• Follow the Vpkg manifest specification
• Are not reviewed by the Vandor team
• May vary in quality and maintenance status
• Use at your own discretion

Package Manifest

Every Vpkg package is defined by a vpkg.manifest.yaml file. This is the package's contract with Vandor -- it declares what the package does, where it writes files, what commands it provides, and what permissions it needs.

apiVersion: vpkg/v1
name: "@official/http-humachi"
version: "0.4.0"
tier: official
kind: transport

description: "HTTP server using Huma v2 framework with Chi router"

# Where the package writes files
targets:
  - path: internal/transport/http
    type: transport
  - path: internal/bootstrap/runtime
    type: runtime
  - path: config/fragments/http.yaml
    type: config-fragment

# Package-scoped commands
actions:
  - name: add-handler
    description: "Scaffold a new HTTP handler for a context"
    command: "generate-handler"
  - name: add-middleware
    description: "Add a middleware to the HTTP stack"
    command: "generate-middleware"

# Project-global shortcuts
aliases:
  - name: "add:http-handler"
    action: add-handler
    description: "Shortcut to scaffold an HTTP handler"
  - name: "add:http-middleware"
    action: add-middleware
    description: "Shortcut to add HTTP middleware"

# What the package needs access to
permissions:
  - read: internal/core/contexts/*/domain
  - write: internal/transport/http
  - write: internal/bootstrap/runtime
  - write: config/fragments

Key Manifest Fields

apiVersion: The manifest schema version. Currently vpkg/v1.

kind: What category of package this is. Determines which directories it can target. Values: transport, infrastructure, tooling.

targets: The specific paths where the package writes files. Vandor enforces that packages only write to their declared targets.

actions: Commands that the package provides. These are scoped to the package -- you run them with vandor vpkg exec <package> <action>.

aliases: Global shortcuts that map to actions. These become top-level commands like vandor add:http-handler. Aliases must be globally unique across all installed packages.

permissions: What the package needs to read from and write to. Vandor uses this for security and integrity checks.

Actions and Aliases

Vpkg packages can do more than just install static files. They can provide interactive commands through the actions and aliases system.

Actions (Package-Scoped)

Actions are commands defined by a package. You run them through the Vpkg exec command:

# Run an action from a specific package
vandor vpkg exec @official/http-humachi add-handler

# This might prompt: "Which context?" and scaffold a handler

Actions are namespaced to their package, so different packages can have actions with the same name without conflicts.

Aliases (Project-Global)

Aliases are shortcuts that map to package actions. They let you run common operations without remembering which package provides them:

# Instead of:
vandor vpkg exec @official/http-humachi add-handler

# You can use the alias:
vandor add:http-handler

Aliases are registered globally in your project. If two packages try to register the same alias, Vandor will flag the conflict during installation.

Common Alias Patterns

# HTTP transport aliases
vandor add:http-handler          # Scaffold an HTTP handler
vandor add:http-middleware       # Add middleware

# Database aliases
vandor add:entgo-schema          # Create a new Entgo schema
vandor migrate:diff              # Generate migration diff
vandor migrate:apply             # Apply pending migrations

# Asynq aliases
vandor add:async-task            # Scaffold a new async task handler

# Scheduler aliases
vandor add:cron-job              # Scaffold a new scheduled job

Installing Packages

Basic Installation

# Install a single package
vandor vpkg add @official/http-humachi

# Install multiple packages
vandor vpkg add @official/entgo @official/atlas

What Happens During Installation

When you run vandor vpkg add, Vandor follows a precise sequence:

1. Resolve: Read the package manifest and determine what needs to be installed. Check version compatibility with your Vandor version and other installed packages.

2. Validate: Verify that the package's targets do not conflict with existing files or other packages. Check that aliases are globally unique.

3. Plan: Generate a plan showing what files will be created, what configuration will be added, and what Go dependencies will be needed.

4. Apply: Copy the package code into your project at the declared target paths.

5. Register: Update vpkg.yaml with the new package entry and add ownership metadata.

6. Update Lock: Regenerate vpkg.lock with the resolved state, including integrity hashes for all managed files.

vpkg.yaml (Desired State)

This file declares which packages your project wants installed. It is the source of truth for your project's infrastructure dependencies.

apiVersion: vpkg/v1
packages:
  - name: "@official/http-humachi"
    version: "0.4.0"
  - name: "@official/entgo"
    version: "0.4.0"
  - name: "@official/atlas"
    version: "0.4.0"
  - name: "@official/redis-cache"
    version: "0.4.0"

You commit this file to version control. When a teammate clones your project, they run vandor vpkg sync to install all declared packages.

vpkg.lock (Resolved State)

This file records the exact resolved state of all installed packages, including integrity hashes for every managed file. It ensures reproducible installations across machines and CI environments.

apiVersion: vpkg/v1
resolved:
  - name: "@official/http-humachi"
    version: "0.4.0"
    integrity: "sha256:abc123..."
    files:
      - path: internal/transport/http/server.go
        hash: "sha256:def456..."
      - path: internal/transport/http/module.go
        hash: "sha256:ghi789..."
      # ...

You commit this file to version control as well.

Target Policy

Vpkg packages cannot write anywhere they want. Vandor enforces a strict target policy.

Allowed Paths

Blocked Paths

Ownership Tracking

Vpkg tracks which files it manages through integrity hashes in vpkg.lock. This enables several important capabilities:

Conflict Detection: If you manually edit a Vpkg-managed file, Vandor knows. When you try to update the package, it warns you about the conflict and lets you choose how to resolve it.

Clean Updates: When a package releases a new version, Vandor can diff the old and new versions and apply only the changes, respecting any customizations you have made.

Removal: When you remove a package with vandor vpkg remove, Vandor knows exactly which files to delete. It will not accidentally remove files you created yourself.

Doctor Command

The Vpkg doctor command checks the health of your package installation:

vandor vpkg doctor

It verifies:

• All declared packages in vpkg.yaml are installed
• All managed files match their integrity hashes in vpkg.lock
• No package targets conflict with each other
• No alias conflicts exist
• Import rules are not violated (no Vpkg code importing core internals incorrectly)
• All required Go dependencies are present in go.mod

If doctor finds issues, it reports them with suggested fixes:

[WARN] @official/http-humachi: internal/transport/http/server.go has been modified
       Run 'vandor vpkg sync' to reconcile or 'vandor vpkg reset @official/http-humachi' to restore

[ERROR] @official/entgo: missing Go dependency github.com/ent/ent v0.13.x
        Run 'go get github.com/ent/ent@latest' to fix

[OK] @official/atlas: all files match, no issues
[OK] @official/redis-cache: all files match, no issues

Package Commands Reference

Here is a quick reference for all Vpkg commands:

# Add a package to your project
vandor vpkg add <package>

# Remove a package from your project
vandor vpkg remove <package>

# List all installed packages
vandor vpkg list

# Search the registry for packages
vandor vpkg search <query>

# Sync installed packages with vpkg.yaml
vandor vpkg sync

# Show detailed info about a package
vandor vpkg info <package>

# Run a package action
vandor vpkg exec <package> <action>

# Run a global alias
vandor vpkg exec-alias <alias>
# or use the shortcut:
vandor <alias>

# Check package health
vandor vpkg doctor

# Browse the package registry
vandor vpkg registry

Vpkg vs Other Systems

vs Go Modules

Go modules manage external library dependencies through go.mod. Vpkg is different:

• Go modules: Downloads compiled packages into a cache. You cannot see or modify the source code easily.
• Vpkg: Copies source code into your project. You own it, read it, modify it, and debug it.

Vpkg and Go modules coexist. Vpkg packages often bring Go module dependencies with them (the package code might import github.com/go-chi/chi), but Vpkg itself is not a Go module.

vs shadcn/ui

The philosophy is the same. shadcn/ui copies React component source code into your project. Vpkg copies Go infrastructure source code into your project. Both reject the "opaque dependency" model in favor of full ownership.

The difference is scope: shadcn/ui provides UI components, Vpkg provides backend infrastructure components (HTTP servers, database access, caching, job queues).

vs Helm Charts / Docker Compose

Helm and Docker Compose manage infrastructure at the deployment level (containers, services, networking). Vpkg manages infrastructure at the code level (the Go code that connects to those services). They are complementary, not competing.

Practical Example

Let's walk through adding HTTP transport to a project.

Step 1: Install the Package

vandor vpkg add @official/http-humachi

This creates files in your project:

internal/transport/http/
├── server.go          # HTTP server setup with Chi + Huma
├── module.go          # uber-fx module registration
├── middleware/
│   ├── cors.go        # CORS middleware
│   ├── logging.go     # Request logging middleware
│   └── recovery.go    # Panic recovery middleware
└── handler/
    └── health.go      # Health check endpoint (example)

Step 2: Check What Changed

vandor vpkg doctor
# [OK] @official/http-humachi: installed successfully

Your vpkg.yaml now includes:

packages:
  - name: "@official/http-humachi"
    version: "0.4.0"

Step 3: Use an Alias to Scaffold a Handler

vandor add:http-handler
# Prompts: Which context? > order
# Prompts: Which use case? > place_order
# Creates: internal/transport/http/handler/order/place_order_handler.go

Step 4: The Handler Imports Core Interfaces

// internal/transport/http/handler/order/place_order_handler.go
package order

import (
    "myapp/internal/core/contexts/order/application/usecase"
)

type PlaceOrderHandler struct {
    placeOrder *usecase.PlaceOrder
}

func NewPlaceOrderHandler(placeOrder *usecase.PlaceOrder) *PlaceOrderHandler {
    return &PlaceOrderHandler{placeOrder: placeOrder}
}

func (h *PlaceOrderHandler) Handle(ctx context.Context, input *PlaceOrderRequest) (*PlaceOrderResponse, error) {
    result, err := h.placeOrder.Execute(ctx, usecase.PlaceOrderInput{
        CustomerID: input.CustomerID,
        Items:      mapRequestItems(input.Items),
    })
    if err != nil {
        return nil, err
    }
    return &PlaceOrderResponse{OrderID: result.OrderID}, nil
}

Notice how the handler imports from internal/core/ (the use case interface). This is the correct direction. The core layer never imports from internal/transport/.

Best Practices

1. Install What You Need, When You Need It

Do not pre-install packages "just in case." Each package adds code, configuration, and Go dependencies to your project. Install packages when your requirements demand them.

2. Run Doctor Regularly

After making changes to Vpkg-managed files, run vandor vpkg doctor to check for issues. It catches problems early.

3. Commit vpkg.yaml and vpkg.lock

Both files should be in version control. vpkg.yaml is your desired state, and vpkg.lock ensures reproducible installations.

4. Customize After Understanding

Vpkg-managed code is yours to modify, but understand what it does before changing it. Read the package's generated code and understand the patterns it uses.

5. Use Aliases for Common Operations

Instead of remembering which package provides which action, use aliases. They make the most common operations quick and discoverable.

Next Steps