# AGENTS.md

## Project Overview

Skills Vault is a CLI for backing up and restoring [Agent Skills](https://agentskills.io).

The CLI entrypoint is `src/cli.ts`. It dispatches four commands:

- `backup`: snapshot installed skills into `skvlt.yaml`
- `restore`: install skills from a manifest
- `doctor`: inspect the local Skills Vault environment
- `completion`: print shell completion scripts

The codebase is intentionally small and organized around pure helpers plus command modules.

## Repository Layout

- `src/cli.ts`: top-level CLI entrypoint and JSON/text output normalization
- `src/commands/*.ts`: user-facing commands
- `src/internal/args`: argument parsing
- `src/internal/cli`: themed output helpers
- `src/internal/install`: install planning, concurrency, and global state checks
- `src/internal/manifest`: manifest parsing/building types and helpers
- `src/internal/paths`: default paths and path formatting helpers
- `src/internal/process`: process wrappers for `bunx` and installed-skill inspection
- `test/*.test.ts`: Bun test coverage for command behavior, packaging, and edge cases
- `.github/workflows`: CI, release, and dependency review workflows

## Tooling And Runtime

- Runtime/package manager: `bun` (`packageManager: bun@1.3.11`)
- Language: TypeScript run directly with Bun
- Formatter: Prettier
- Test runner: `bun test`
- Packaging target: npm package with `src` included in `files`

Use Bun for local development. Do not replace scripts with npm/yarn/pnpm equivalents unless the project is explicitly being migrated.

## Setup Commands

Install dependencies:

```sh
bun install --frozen-lockfile
```

Show the CLI help locally:

```sh
bun run ./src/cli.ts --help
```

Run the packaged command through Bun:

```sh
bun run ./src/cli.ts doctor
```

## Development Workflow

Useful repo scripts:

```sh
bun run backup
bun run backup:dry-run
bun run restore
bun run restore:dry-run
bun run test
bun run format
bun run format:check
bun run check
```

`bun run check` is the main pre-publish gate. It runs formatting checks, the full Bun test suite, and `npm pack --dry-run --json`.

If you touch GitHub workflow files, also run:

```sh
bunx prettier --check ".github/**/*.yml"
```

## Testing Instructions

Run the full test suite:

```sh
bun test
```

Run a single test file:

```sh
bun test test/cli.test.ts
```

Target a specific test name when iterating:

```sh
bun test --test-name-pattern "prints top-level help"
```

Testing expectations:

- Add or update tests for any behavior change in CLI output, argument parsing, install planning, or manifest handling.
- Prefer focused unit tests around `runCli(...)`, command entrypoints, and internal helpers with injected dependencies.
- Keep tests deterministic. Stub process and filesystem dependencies instead of relying on the caller machine state when possible.
- Packaging-related changes should still pass `test/packaging.test.ts` and `npm pack --dry-run --json`.

## Command-Specific Notes

### Backup

- Default manifest path is `./skvlt.yaml`.
- Global scope reads from `~/.agents/.skill-lock.json`.
- Project-scope backup currently requires `--lock-file`.

Examples:

```sh
bun run ./src/cli.ts backup
bun run ./src/cli.ts backup --dry-run
bun run ./src/cli.ts backup --project-scope --lock-file ./skills-lock.json
```

### Restore

- Restore defaults to the scope recorded in the manifest.
- `--project-scope` forces project installation even if the manifest says global.
- Dry-run shows the derived `bunx skills add ...` commands.
- Live installs are intentionally serialized in lock-safe mode even when previewed concurrency is higher.

Examples:

```sh
bun run ./src/cli.ts restore --all
bun run ./src/cli.ts restore --only-source xixu-me/skills
bun run ./src/cli.ts restore --dry-run
```

### Doctor

- `doctor` checks the Bun runtime, `bunx skills --help`, manifest presence, and global skill state consistency.
- It is the fastest sanity check when debugging local environment issues.

### Completion

- Supported shells are `bash`, `zsh`, and `powershell`.

## Code Style Guidelines

- Follow existing TypeScript + ESM patterns and keep imports grouped cleanly.
- Prefer small helpers with explicit types over large monolithic functions.
- Preserve the current command result shape: `exitCode`, `stdout`, `stderr`, optional `errorCode`, and optional structured `payload`.
- Match the existing output style helpers in `src/internal/cli/theme` instead of formatting raw strings ad hoc.
- Reuse path helpers in `src/internal/paths` for user-facing paths.
- Keep comments sparse and high-signal. The codebase uses short doc comments only where behavior needs context.
- Stick to ASCII unless a file already requires something else.

## Build, Packaging, And Release

Pre-publish verification:

```sh
bun run check
```

Manual tarball check:

```sh
npm pack --dry-run --json
```

CI behavior:

- CI runs on `main` pushes and pull requests on Ubuntu and Windows.
- CI installs with `bun install --frozen-lockfile`.
- CI checks formatting, workflow formatting, tests, and a smoke install of the packed tarball.

Release behavior:

- Release runs on `v*.*.*` tags and `workflow_dispatch`.
- Release verifies the Git tag version matches `package.json`.
- npm publish uses trusted publishing via GitHub OIDC; do not add legacy token-based publish steps unless the release model changes.

## Pull Request Guidance

Before submitting a change, run:

```sh
bun run check
```

Also run the workflow formatting check if you changed `.github/workflows/*.yml`.

When changing package metadata or release behavior, verify:

- the `bin.skvlt` entry still points to `src/cli.ts`
- publishable assets are still included as expected
- the tarball smoke path still works after `npm pack`

## Troubleshooting

- If restore reports global state mismatch, inspect `~/.agents/.skill-lock.json` and `~/.agents/skills`.
- If local environment checks fail, start with `bun run ./src/cli.ts doctor`.
- If packaging tests fail, confirm all publish-required files referenced by tests are present in the repo snapshot.
- If command output assertions fail, check whether ANSI formatting or help text structure changed unintentionally.