Skip to content

AGENTS.md

Latest commit

 

History

History
177 lines (139 loc) · 7.08 KB

AGENTS.md

File metadata and controls

177 lines (139 loc) · 7.08 KB
Raw

@STYLE.md

Vector CLI Development Context

Development Loop

Make changes, run make check, fix what it catches, repeat until green, then push. make check runs fmt-check + vet + lint + test + test-e2e + surface + skill-drift + tidy-check. Treat it as your inner-loop companion, not a final hurdle.

Repository Structure

vector-cli/
├── cmd/vector/          # Main entrypoint (main.go)
├── internal/
│   ├── api/             # HTTP client and error handling
│   ├── appctx/          # Application context (App struct)
│   ├── cli/             # Root command wiring
│   ├── commands/        # Command implementations (one file per group)
│   ├── config/          # Configuration, keyring, paths
│   ├── output/          # Output formatting (Writer, Table, JSON, KeyValue)
│   ├── surface/         # CLI surface snapshot generator
│   └── version/         # Version info (injected via ldflags)
├── e2e/                 # BATS end-to-end tests (Prism mock server)
├── man/                 # Manpage generation
├── scripts/             # CI helper scripts (drift detection)
└── skills/              # Embedded agent skill documents
    └── vector/          # SKILL.md — agent reference for vector-cli

Vector Pro API Reference

Base URL: https://api.builtfast.com

All resource paths are under /api/v1/vector/. Key resources:

  • /sites — CRUD, suspend, unsuspend, clone, purge-cache, logs, wp-reconfig
  • /sites/{id}/environments — environment management
  • /sites/{id}/environments/{id}/deployments — deployments
  • /sites/{id}/backups — backup management
  • /sites/{id}/backups/{id}/download — backup download
  • /sites/{id}/restores — restore management
  • /sites/{id}/waf/blocked-ips — WAF blocked IPs
  • /sites/{id}/waf/blocked-referrers — WAF blocked referrers
  • /sites/{id}/waf/allowed-referrers — WAF allowed referrers
  • /sites/{id}/waf/rate-limits — WAF rate limits
  • /sites/{id}/archives — site archives
  • /sites/{id}/ssh-keys — site SSH keys
  • /sites/{id}/db/export — database export
  • /sites/{id}/db/import-sessions — database import
  • /sites/{id}/events — site events
  • /sites/{id}/environments/{id}/ssl — SSL certificates
  • /sites/{id}/environments/{id}/secrets — environment secrets
  • /sites/{id}/environments/{id}/db — environment database info
  • /account — account details
  • /account/ssh-keys — account SSH keys
  • /account/api-keys — API key management
  • /account/secrets — account secrets
  • /webhooks — webhook management
  • /php-versions — available PHP versions
  • /auth/whoami — authentication check
  • /mcp/config — MCP server configuration

Testing

make check is the local CI gate. Run it before pushing.

make check             # All checks (local CI gate)
make test              # Go unit tests only
make lint              # golangci-lint
make vet               # go vet
make fmt               # Format code (gofmt -s)
make fmt-check         # Check formatting (fails if not formatted)
make tidy              # go mod tidy
make tidy-check        # Verify go.mod/go.sum are tidy (non-mutating)
make race-test         # Tests with race detector
make test-e2e          # BATS e2e tests (requires Prism)
make build             # Build binary to ./bin/vector
make surface           # Regenerate .surface snapshot
make check-surface     # Verify .surface is up to date
make check-skill-drift # Verify SKILL.md matches .surface
make vuln              # govulncheck for dependency vulnerabilities
make replace-check     # Guard against replace directives in go.mod
make release-check     # Full pre-flight: check + replace-check + vuln + race

When iterating on a specific area, use targeted targets for faster feedback, then finish with make check before pushing.

E2E tests use a Prism mock server that validates requests against e2e/openapi.yaml. The test helper (e2e/test_helper.bash) starts Prism automatically.

Requirements: Go 1.26+, golangci-lint, bats-core, Node.js/npx (for Prism), govulncheck (for make vuln).

Surface Snapshot

The .surface file at the repo root is a deterministic, sorted snapshot of every command, argument, and flag in the CLI. It is generated by internal/surface/surface.go and committed to version control.

Purpose: catch accidental command/flag changes in CI and provide a stable reference for skill drift detection.

Format — one line per entry, sorted lexicographically:

CMD vector site list
ARG vector site show 0 site-id
FLAG vector site list --page type=string
FLAG vector --json type=bool          # persistent flag on root

Regenerate after adding/removing/renaming commands, flags, or arguments:

make surface                          # regenerate .surface
# or: go test ./internal/cli/ -run TestSurface -update

CI enforcement: make check includes check-surface, which fails with a diff if .surface is stale. Always run make surface after command/flag changes and commit the updated file.

Skill System

skills/vector/SKILL.md is an agent-facing reference document embedded into the binary via skills/embed.go. It teaches AI agents how to use vector-cli: authentication, commands, flags, workflows, error codes, and decision trees.

Commands

  • vector skill — prints SKILL.md to stdout (no auth required)
  • vector skill install — installs SKILL.md to ~/.agents/skills/vector/ and symlinks it into ~/.claude/skills/vector/; writes a .version stamp
  • vector skill uninstall — removes installed skill files and symlinks

Auto-refresh

RefreshSkillsIfVersionChanged() runs at CLI startup (in internal/cli/execute.go). When the installed .version stamp differs from the current CLI version, it silently re-installs the skill files. Skipped for dev builds and when the skill has never been installed.

Keeping SKILL.md in sync

Every command and flag mentioned in SKILL.md must match an entry in .surface. After command/flag changes:

  1. Run make surface to regenerate .surface
  2. Update skills/vector/SKILL.md if commands, flags, or workflows changed
  3. Run make check — the check-skill-drift target will catch any mismatches

Drift detection

scripts/check-skill-drift.sh scans SKILL.md for vector <cmd> and --<flag> references and verifies each one exists in .surface. Known/accepted mismatches can be baselined in .surface-skill-drift.

make check-skill-drift                # run drift check standalone

Workflow: Command or Flag Changes

When you add, remove, or rename a command or flag:

  1. Make the code change in internal/commands/
  2. make surface — regenerate .surface
  3. Update skills/vector/SKILL.md if the change affects agent-visible behavior
  4. Update man/man1/vector.1 — the e2e manpage test enforces this
  5. make check — validates fmt, vet, lint, tests, e2e, surface, skill drift, and tidy