npm package: @prata.ma/anvil
Description: User-facing Anvil library and CLI facade for governed workspaces.
Latest version: 0.1.0

# @prata.ma/anvil

User-facing Anvil library and CLI facade for governed workspaces.

## Overview

`@prata.ma/anvil` is the main package boundary for Anvil itself. It owns the `anvil.yaml` manifest contract, schema-backed validation, governed project and global sync behavior, catalog and profile resolution, lock handling, and the `anvil` / `anv` CLI surface that exposes those capabilities.

Within the workspace, this package is the top-level facade that composes lower-level Anvil-related packages into a user-facing surface. Consumers should depend on `@prata.ma/anvil` for manifest loading, sync orchestration, schema access, and the supported CLI instead of reaching into internal command modules or block-deployment helpers directly.

## Installation

Install the package from npm when using Anvil outside this monorepo.

### npm

```json
{
  "dependencies": {
    "@prata.ma/anvil": "^0.0.0"
  }
}
```

## Usage

`@prata.ma/anvil` supports both library-style usage and the packaged CLI surface.

### Library

```ts
import {
  anvilSync,
  getAnvilSchemaPath,
  loadAnvilManifest,
  validateAnvilManifest,
} from '@prata.ma/anvil'

const loadedManifest = loadAnvilManifest(process.cwd())

if (!loadedManifest) {
  throw new Error('No anvil.yaml found')
}

const validation = validateAnvilManifest(loadedManifest.manifest)
if (!validation.valid) {
  throw new Error(validation.issues.map(issue => issue.message).join('; '))
}

console.log(getAnvilSchemaPath())
await anvilSync(loadedManifest)
```

### CLI

```bash
anvil status # Show workspace status
anvil manifest validate # Validate anvil.yaml
anvil sync # Run governed project sync
anvil sync --global # Run standalone global sync
anvil sync --prune # Remove undeclared tool-target content, then sync
anvil skill list # Show installed skills
anvil skill add <source> # Add skill declarations to anvil.yaml, then sync
anvil skill remove <name> # Remove declared skills from anvil.yaml, then sync
anvil skill update # Re-sync declared project/global skill manifests
anvil skill check <source> # Validate a skill source before install
anvil hub query "status" # Query configured hub context
anv # Launch the interactive shortcut when running in a TTY
```

### Patterns

The package is typically used in one of two ways:

- as a library facade for manifest parsing, root resolution, recipe loading, and sync orchestration
- as the `anvil` CLI for workspace-facing command flows such as `catalog`, `hub`, `manifest`, `plugin`, `skill`, `status`, and `sync`

## API

`@prata.ma/anvil` exposes a documented library surface and two CLI binaries.

### Exports

- `@prata.ma/anvil` - root library facade
- `@prata.ma/anvil/manifest` - manifest loading, parsing, validation, and root-resolution helpers
- `@prata.ma/anvil/schema` - packaged `anvil.yaml` JSON schema
- root exports from `src/index.ts`, including manifest helpers, recipe helpers, sync helpers, and `getAnvilPackageStatus()`

### Commands

The package ships two binaries:

- `anvil` - standard CLI entrypoint
- `anv` - shorthand launcher entrypoint

Top-level CLI command areas currently include catalog, hub, manifest, plugin, skill, status, and sync.

#### Workspace

```bash
anvil status
anvil sync
anvil sync --global
anvil sync --prune
```

#### Manifest

```bash
anvil manifest validate
```

#### Skills And Plugins

```bash
anvil skill add <source>
anvil skill check <source>
anvil skill find <query>
anvil skill list
anvil skill remove <name>
anvil skill update
anvil plugin add <source>
anvil plugin list
anvil plugin remove <name>
```

Skill commands are manifest-driven:

- `anvil skill add` records skill declarations in `anvil.yaml` and then runs sync
- `anvil skill remove` removes declared skill refs from `anvil.yaml` and then runs sync
- `anvil skill update` re-syncs the current declared project and optional global manifests
- sync now owns skill materialization and stale managed cleanup instead of the CLI writing directly into deployed skill targets

#### Catalog And Hub

```bash
anvil catalog review
anvil catalog agent add <name>
anvil catalog block add <name>
anvil catalog command add <name>
anvil catalog plugin add <name>
anvil catalog profile add <name>
anvil catalog reference add <name>
anvil catalog rule add <name>
anvil catalog skill add <name>
anvil catalog template add <name>
anvil hub pull
anvil hub query <text>
anvil hub status
anvil hub sync --product
anvil hub sync --state
anvil hub sync --system
```

### Configuration

- `anvil.yaml` is the primary workspace manifest consumed by the package.
- `@prata.ma/anvil/schema` and `getAnvilSchemaPath()` expose the schema contract for that manifest.
- `anvilSync()` materializes governed content into `.anvil/` and generated compatibility outputs.
- Catalog agents are now authored as one markdown file at `content/agents/<name>.md`, staged into `.anvil/agents`, and rendered into tool-specific agent targets for OpenCode, Claude, Cursor, and Codex.
- The CLI `anvil sync` command owns the final enriched project lock snapshot after external manifest-backed skills and plugins are resolved.
- `anvil sync --global` routes the same sync command through the standalone global Anvil root under `~/.config/anvil/`.
- `anvil sync --prune` removes undeclared content from the agreed tool targets before sync after one grouped confirmation prompt, and aborts if that prompt is declined or cancelled.
- Project and global `anvil-lock.yaml` files are managed sync snapshots for provenance and ownership diagnostics, while deployed `metadata.anvil` markers remain the authoritative cleanup signal.
- Project and global sync now print the same `Deployed`, `Skipped`, and `Undeclared` summary surface, with conservative cleanup still preserving unmanaged deployed items.
- Lock snapshots now include deterministic instruction-budget metrics: top-level `summary` plus per-entry `lines`, `chars`, and `tokens` for managed agents, rules, commands, references, skills, and block rollups.
- Root-generated lock entries use synthetic managed refs such as `anvil:root-agents` and `anvil:root-agents-override` instead of filename-shaped keys.

## Development

Use the package-local scripts while working in `@packages/anvil`, and keep user-facing behavior routed through the documented facade and command layers instead of scattering it across unrelated packages.

### Commands

```bash
pnpm --filter @prata.ma/anvil build
pnpm --filter @prata.ma/anvil lint
pnpm --filter @prata.ma/anvil test
pnpm --filter @prata.ma/anvil test:type
```

### Testing

The current Vitest coverage exercises manifest parsing and validation, block deployment, sync behavior, catalog review generation, installer and lock helpers, marker-based stale-managed cleanup, live one-file agent deployment, project/global Codex parity, and representative CLI command flows such as manifest-driven `skill add`, `skill remove`, and `skill update`.

### Conventions

- Keep the CLI layer thin: command modules should delegate real behavior into importable library code.
- Preserve `@prata.ma/anvil` as the public facade exception that composes other Anvil-owned packages.
- Keep manifest and sync behavior deterministic because generated governance outputs depend on it.
- Treat internal command modules and `src/lib/*` helpers as implementation details unless they are explicitly exported.
- Keep lock snapshots and deployed markers aligned, but do not let lock state reclaim primary cleanup authority from `metadata.anvil`.
- Keep lock summaries aggregated from leaf instruction-bearing entries so block rollups do not double count the same content.
- Keep `anvilSync()` focused on managed deployment work; let the CLI sync command own the final project lock snapshot when external declarations are involved.

## Status

This package is active and central to the current workspace model.

### Maturity

`@prata.ma/anvil` is active for workspace dogfooding and public-package preparation.

### Scope

The package currently supports manifest loading and validation, schema access, governed project and global sync, block deployment, catalog tooling, plugin and skill management, and the main Anvil CLI facade. It is the supported user-facing package boundary for workspace governance operations.

## Notes

- This package is being prepared for publication as `@prata.ma/anvil`; release validation should be proven from packed artifacts before a live npm publish.
- The supported library surface is limited to the documented exports; deep imports into `src/commands/*` or `src/lib/*` should not be treated as stable public API.
- `scripts/postbuild.mjs` is part of the package contract because it copies `.mjs` outputs to `.js` and stages catalog assets into build output after `tsdown` completes.