cli: Instructions file for Codex

AGENTS.md

This file follows the open AGENTS.md convention from https://agents.md. Treat it as the agent-facing README for this repository: use it to get oriented, make changes in the existing style, and run the right checks before handing work back.

Project Overview

@halo-dev/cli is a TypeScript, ESM-based CLI for managing Halo instances.

• Runtime: Node.js >= 22
• Published binary: halo
• Source entry: src/cli.ts
• Local development entry: tsx src/cli.ts
• Build output: dist/cli.mjs
• Package manager: Vite+ wraps the underlying package manager; prefer vp commands for project tooling.

The root CLI currently exposes these business areas:

• auth
• post
• single-page
• search
• plugin
• theme
• attachment
• backup
• moment
• comment
• notification
• shop
• completion

Setup Commands

• Install dependencies after pulling changes: vp install
• Run the CLI from source: vp exec tsx src/cli.ts --help
• Run a command from source: vp exec tsx src/cli.ts <command> ...
• Build the published CLI: vp run build

Do not use pnpm, npm, or yarn directly for dependency management unless the user explicitly asks for it. Vite+ is the project toolchain wrapper.

Validation Commands

Use the smallest useful check while iterating, then run broader checks before finishing a meaningful change.

• Fast TypeScript regression check: pnpm typecheck
• Lint: vp lint
• Full project check: vp check
• Tests: vp test
• Build: vp run build

pnpm typecheck is intentionally kept here because it is currently the fastest way to catch TypeScript regressions in this CLI. For Vite+, do not run commands such as vp vitest or vp oxlint; use vp test and vp lint.

Vite+ Rules

This project uses Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task.

• Run vp help or vp <command> --help for command details.
• Use vp run <script> when you need a package.json script whose name conflicts with a Vite+ built-in command.
• Use vp dlx for one-off package binaries.
• Import Vite+ APIs from vite-plus, for example import { defineConfig } from "vite-plus";.
• Import test APIs from vite-plus/test, for example import { expect, test, vi } from "vite-plus/test";.
• Do not add direct dependencies on Vitest, Oxlint, Oxfmt, or tsdown just to use their CLIs or APIs.
• Type-aware linting is available through vp lint --type-aware; do not add oxlint-tsgolint for that purpose.