vf-ext-development

Veryfront Extension Development

Overview

A Veryfront extension is a deno.json-described package that default-exports an ExtensionFactory. The factory returns an object that declares its contracts, declares its capabilities, and optionally provides implementations through static provides or dynamic setup(ctx).

Core principle: The manifest and the factory must agree. CI fails the build if veryfront.contracts / veryfront.capabilities in deno.json drift from what the factory returns.

When to Use

• Creating a new extension under extensions/
• Adding/removing a contract or capability on an existing extension
• Adding a new contract type to the framework (also touches the recommendations registry and the extensions README)
• Writing tests for an extension factory or its contract implementation
• Triaging lint:extension-contracts / lint:extension-capabilities failures

Scaffold

veryfront extension init ext-my-cache       # writes extensions/ext-my-cache/{deno.json,src/index.ts,src/index.test.ts}
veryfront extension validate extensions/ext-my-cache

Always use the ext- prefix. scripts/lint/audit-extension-{capabilities,contracts}.ts only scan directories whose name starts with ext-; an extension at extensions/my-cache/ is silently skipped by both lint tasks. veryfront extension init does not add the prefix for you — pass it explicitly.

Package Structure

extensions/ext-<name>/
├── deno.json         # Manifest — name, contracts, capabilities, imports
├── README.md         # Required for first-party extensions
└── src/
    ├── index.ts      # Default-exported ExtensionFactory
    ├── index.test.ts # Factory + setup/teardown tests
    └── <impl>.ts     # Implementation modules + colocated *.test.ts

Manifest (deno.json)

{
  "name": "@veryfront/ext-cache-redis",
  "version": "0.1.0",
  "exports": "./src/index.ts",
  "veryfront": {
    "extension": true,
    "contracts": { "provides": ["TokenCacheStore"], "requires": [] },
    "capabilities": [
      { "type": "net:outbound", "hosts": ["*"] },
      { "type": "env:read", "keys": ["REDIS_URL", "REDIS_PREFIX", "REDIS_PASSWORD"] }
    ]
  },
  "imports": {
    "redis": "npm:[email protected]",
    "veryfront/extensions": "../../src/extensions/index.ts",
    "veryfront/extensions/cache": "../../src/extensions/cache/index.ts"
  }
}