git:20260321.a08188e to git:20260520.4a18955

- <!--VITE PLUS START-->

-

- # Using Vite+, the Unified Toolchain for the Web

-

- This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, but it invokes Vite through `vp dev` and `vp build`.

-

- ## Vite+ Workflow

-

- `vp` is a global binary that handles the full development lifecycle. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.

-

- ### Start

-

- - create - Create a new project from a template

- - migrate - Migrate an existing project to Vite+

- - config - Configure hooks and agent integration

- - staged - Run linters on staged files

- - install (`i`) - Install dependencies

- - env - Manage Node.js versions

-

- ### Develop

-

- - dev - Run the development server

- - check - Run format, lint, and TypeScript type checks

- - lint - Lint code

- - fmt - Format code

- - test - Run tests

-

- ### Execute

-

- - run - Run monorepo tasks

- - exec - Execute a command from local `node_modules/.bin`

- - dlx - Execute a package binary without installing it as a dependency

- - cache - Manage the task cache

-

- ### Build

-

- - build - Build for production

- - pack - Build libraries

- - preview - Preview production build

-

- ### Manage Dependencies

-

- Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the `packageManager` field in `package.json` or package manager-specific lockfiles.

-

- - add - Add packages to dependencies

- - remove (`rm`, `un`, `uninstall`) - Remove packages from dependencies

- - update (`up`) - Update packages to latest versions

- - dedupe - Deduplicate dependencies

- - outdated - Check for outdated packages

- - list (`ls`) - List installed packages

- - why (`explain`) - Show why a package is installed

- - info (`view`, `show`) - View package information from the registry

- - link (`ln`) / unlink - Manage local package links

- - pm - Forward a command to the package manager

-

- ### Maintain

-

- - upgrade - Update `vp` itself to the latest version

-

- These commands map to their corresponding tools. For example, `vp dev --port 3000` runs Vite's dev server and works the same as Vite. `vp test` runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using `vp --version`. This is useful when researching documentation, features, and bugs.

-

- ## Common Pitfalls

-

- - **Using the package manager directly:** Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.

- - **Always use Vite commands to run tools:** Don't attempt to run `vp vitest` or `vp oxlint`. They do not exist. Use `vp test` and `vp lint` instead.

- - **Running scripts:** Vite+ built-in commands (`vp dev`, `vp build`, `vp test`, etc.) always run the Vite+ built-in tool, not any `package.json` script of the same name. To run a custom script that shares a name with a built-in command, use `vp run <script>`. For example, if you have a custom `dev` script that runs multiple services concurrently, run it with `vp run dev`, not `vp dev` (which always starts Vite's dev server).

- - **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly:** Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.

- - **Use Vite+ wrappers for one-off binaries:** Use `vp dlx` instead of package-manager-specific `dlx`/`npx` commands.

- - **Import JavaScript modules from `vite-plus`:** Instead of importing from `vite` or `vitest`, all modules should be imported from the project's `vite-plus` dependency. For example, `import { defineConfig } from 'vite-plus';` or `import { expect, test, vi } from 'vite-plus/test';`. You must not install `vitest` to import test utilities.

- - **Type-Aware Linting:** There is no need to install `oxlint-tsgolint`, `vp lint --type-aware` works out of the box.

-

- ## Review Checklist for Agents

-

- - [ ] Run `vp install` after pulling remote changes and before getting started.

- - [ ] Run `vp check` and `vp test` to validate changes.

- <!--VITE PLUS END-->

- # Project Status

- This repository is a TypeScript CLI for managing Halo instances.

- ## Runtime and Packaging

- - Language: TypeScript, ESM

- - CLI entry: `src/cli.ts`

-

- ## Current Command Surface

- The root CLI currently registers these business areas:

-

- ## Command Architecture

-

- This project no longer implements large nested command trees directly on the root `cac` instance.

-

- Use this pattern instead:

-

- 1. Register a placeholder root command in `src/cli.ts` via `registerXxxCommands(cli)`.

- 2. Implement a dedicated sub-CLI in `src/commands/xxx/index.ts` with its own `cac("halo xxx")` instance.

- 3. Export `tryRunXxxCommand(args, runtime)`.

- 4. In `src/cli.ts`, dispatch in order by calling `tryRunXxxCommand(...)` before the final root parse.

-

- This pattern is important because it gives correct help output for:

-

- - `halo xxx`

- - `halo xxx --help`

- - nested subcommands like `halo comment reply`

-

- If a business area has a nested namespace, create another dedicated sub-CLI for that nested branch instead of trying to handle help manually in a single root command.

-

- Within a command area, prefer colocating command-specific helpers with the command itself, for example:

-

- - `src/commands/post/index.ts`

- - `src/commands/post/format.ts`

- - `src/commands/post/input.ts`

- - `src/commands/post/types.ts`

- - `src/commands/post/__test__/...`

-

- Do not move command-local types, input parsing, browser helpers, file helpers, or tests back into shared roots unless they are reused across multiple business areas.

-

- ## Runtime and Auth Model

-

- Authentication and HTTP clients are centralized in `src/utils/runtime.ts`.

- - `RuntimeContext` is intentionally narrow: it resolves profiles and constructs clients.

- - `RuntimeContext.getClientsForOptions(...)` returns:

- - `clients.axios`

- - `clients.console`

- - `clients.core`

- - Shared auth/config models live in `src/shared/profile.ts`

- - Auth supports:

- - Basic Auth

- - Bearer token

- - Profile storage is handled by `src/utils/config-store.ts`

- - Profile metadata is stored in `config.json`, but actual basic/bearer credentials are stored in the system keyring via `@napi-rs/keyring`

- - URL normalization lives in `src/utils/url.ts`

- - Package upload helpers live in `src/utils/package-file.ts`

- - Config path defaults to:

- - `$HALO_CLI_CONFIG_DIR/config.json` if set

- - otherwise `$XDG_CONFIG_HOME/halo/config.json`

- - otherwise `~/.config/halo/config.json`

- ## Implemented Business Areas

- ### `auth`

- - login

- - current

- - profile list/current/get/use/delete/doctor

- - supports multi-profile management

- - deleting a profile must also remove its stored credentials from the system keyring

- - `profile doctor` validates configured profiles against available keyring credentials and should be kept useful for recovery workflows

- ### `post`

- - list/get/create/update/delete/open/import-json/export-json

- - uses Halo UC post APIs

- - draft content is persisted through content annotations

- - create/update support taxonomy resolution and creation for categories/tags

- - `import-json` / `export-json` use the same `{ post, content }` shape returned by `post get --json`

- - importing checks `metadata.name`; if the post already exists, it requires confirmation before updating unless `--force` is used

- - `export-json` writes the same payload to `./<post-name>.json` by default; `--output <path>` overrides the destination

- ### `search`

- - public site search

- - does not require authenticated console access when `--url` is provided

- ### `plugin`

- - list/get/enable/disable/install/uninstall/upgrade and related management flows

- - includes App Store-aware upgrade logic

- ### `theme`

- - list/get/current/install/upgrade/activate/reload/delete

- - uses Halo theme console/core APIs

- - includes App Store-aware upgrade logic similar to `plugin`

- - local installation uses multipart upload to the theme install endpoint because the generated SDK install signature is not file-parameter-friendly

- - `list` marks the currently activated theme in table output

- ### `attachment`

- - list/get/delete/upload/download

- - upload/download include progress feedback in TTY mode

- ### `backup`

- - list/get/create/download/delete

- - `create --wait` polls until completion

- ### `moment`

- - list/get/create/update/delete

- - does not use `@halo-dev/api-client` for business APIs

- - uses manual `axios` requests against the moments plugin UC endpoints

- - this was necessary because the main Halo SDK does not expose moments business APIs

- ### `comment`

- - `comment list`

- - `comment get`

- - `comment approve`

- - `comment delete`

- - `comment create-reply`

- - `comment reply list`

- - `comment reply get`

- - `comment reply approve`

- - `comment reply delete`

- Comment approval behavior follows the Halo console frontend:

- - approving a comment uses `core.content.comment.patchComment` with JSON Patch

- - approving a reply uses `core.content.reply.patchReply` with JSON Patch

- - creating a reply uses `console.content.comment.createReply`, which creates an already approved reply in console context

- ### `notification`

- - `notification list`

- - `notification get`

- - `notification delete`

- - `notification mark-as-read`

- - `notification mark-as-read --all`

- Notification management uses the Halo user-space UC notification APIs exposed in `@halo-dev/api-client`.

- Single-notification lookup is implemented by filtering the authenticated user's notification list by `metadata.name`.

- ## Formatting and Output Conventions

- Shared output helpers live in `src/utils/output.ts`.

- - Prefer adding business-specific `printXxxList(...)` and `printXxx(...)` helpers in the owning command area, usually `src/commands/<module>/format.ts`

- - Keep `src/utils/output.ts` limited to generic JSON/detail rendering helpers such as `printJson(...)` and `printDetailObject(...)`

- - Table output is standardized via `cli-table3`

- - Time formatting uses `dayjs`

- - Byte formatting uses `pretty-bytes`

- - JSON output is controlled by `--json`

- When adding a new business area, keep raw object printing out of command files as much as possible and route business formatting through the command-local formatter first, falling back to `src/utils/output.ts` only for generic helpers.

- ## Testing Conventions

- - Co-locate command tests under `src/commands/<module>/__test__/`

- - Keep cross-cutting utility tests under `src/utils/__test__/`

- - Keep shared integration tests under `src/shared/**/__test__/`

- - When moving command logic into a command folder, move its tests with it rather than leaving them in a shared `src/commands/__test__/` root

- ## UX Conventions

- - Use `@inquirer/prompts` for interactive flows only when running in TTY mode

- - Use `CliError` for user-facing validation errors

- - Any dangerous operation must require an explicit confirmation step in TTY mode before execution. This applies not only to delete/uninstall flows, but also to other risky state-changing actions such as disable or similar mutating operations.

- - Require `--force` for dangerous operations in non-interactive mode so confirmation can be skipped explicitly and consistently.

- - Prefer consistent success/cancel/delete messaging with existing commands

- - For long-running upload/download/polling flows, use `ora` when stdout is a TTY and `--json` is not enabled

- ## Validation Workflow

- For dependency management and general project tooling, prefer Vite+ as described above.

- For this CLI specifically, the most useful validation commands are:

- - `pnpm typecheck`

- - `vp lint`

- - `vp check`

- - `vp test`

- `pnpm typecheck` is currently the fastest way to catch TypeScript regressions during command development.

- ## Extension Guidance

- When implementing a new command area:

- 1. Check whether `@halo-dev/api-client` already exposes the needed console/core/public API.

- 2. If it does, prefer the SDK over manual HTTP.

- 3. If it does not, inspect upstream Halo or plugin code under `current-repos/` and implement with manual `axios` requests.

- 4. Keep root command registration minimal and put real logic in a dedicated sub-CLI file under `src/commands/`.

- 5. Add command-local helpers such as `format.ts`, `types.ts`, `input.ts`, or `files.ts` under the owning command directory when they are not shared across business areas.

- 6. Put command tests under `src/commands/<module>/__test__/`.

- 7. Use `src/utils/output.ts` only for generic output helpers shared across multiple areas.

- 8. Use `src/shared/` for true shared models or integrations, for example `src/shared/profile.ts` or `src/shared/integrations/app-store.ts`.

- 9. Validate with typecheck and lint before finishing.

- ## Upstream Reference Repositories

- The workspace currently includes reference repos under `current-repos/`:

- - `halo/`

- - `plugin-app-store/`

- - `plugin-moments/`

- - `vscode-extension-halo/`

- These are used as implementation references for API behavior, frontend console behavior, and feature parity.