a-novel-kit/stack

The a-novel CLI — one tool to build, test, run, and release every project across the a-novel and a-novel-kit organizations, in place of the per-repo Makefiles and scripts.
What this is
This repository — the **stack** — hosts that CLI and anchors local checkouts of
the projects it operates on:
app/ and kit/ are not submodules — they are plain clones managed by
a-novel core sync, kept out of this repo's history.
Install
Building the CLI needs Go; a-novel core setup then preflights your environment
and requires git and a running Podman. The rest of the toolchain (Node + pnpm,
gh) and the per-OS install commands live in the
developer onboarding guide.
go install pulls and builds the binary straight from the module path — no
upfront clone. core setup then clones the stack repo itself into
~/git-projects/a-novel (the default stack) when it's missing, so you don't
bootstrap the workspace by hand. It is otherwise idempotent, and installs a block
in your shell rc (zsh, bash and fish are supported) that auto-starts the
background daemon and loads tab-completion in every new shell.
Verify:
After a git pull that touches cli/, run a-novel install to rebuild and
reinstall — the new binary takes over from the running daemon in place, so
services already running stay up.
If a service needs an API secret (e.g. OPENAI_API_KEY), provision it once,
encrypted and locally:
Secrets are AES-256-GCM-encrypted at rest, never printed, and injected into the
child env of test/run/ui via a value-free .a-novel/secrets.yaml manifest
in the service repo. See
cli/README.md
for the full model.
The UI — start here
For day-to-day work, open the terminal UI:
It is a full-screen dashboard: a services list on the left, a tabbed detail and
live log viewer on the right, and a command palette (press **Esc**) that covers
the entire CLI surface, each command a :verb entry. Press **?** for a
searchable key and command reference; **q** quits.
The UI is a thin client over the same daemon as the command line, so anything
you do in it is visible to the CLI and vice-versa. If you learn one command,
learn this one.
Non-interactive commands
Everything the UI does is also a discrete command — what you reach for in
scripts, in CI, or when you already know exactly what you want.
**Build and test** discover their targets in the working tree, show an
interactive picker by default, and run the selection in parallel. -y skips
the picker and runs everything, sequentially unless -j sets a limit (also the
default when there is no TTY):
**Run services.** The daemon auto-starts a target's dependencies — Postgres,
migrations — before the target itself:
**Release.** Releases are cut in CI: trigger the repo's release workflow and
pick a release type (patch / minor / major). The release-core action bumps the
version, refreshes doc refs, commits, tags vX.Y.Z, pushes, and creates the
GitHub Release. There is no local release command; the only verb under
a-novel publish is stamp (the doc-version stamper that prepublish:doc
calls).
Run a-novel --help for any command's full flags. The complete
reference — command tree, daemon architecture, state directories, the compose
contract — is in cli/README.md.
> Lint, format and generate are deliberately **not** CLI verbs: each repo
> exposes them as uniform pnpm scripts (pnpm lint:go, pnpm format:go,
> pnpm generate:go, …).
GitHub access
Two identities talk to GitHub: **you** (the operator, via gh) and the **org