95 lines
4.7 KiB
Markdown
95 lines
4.7 KiB
Markdown
# `ninja` — BlockNinja developer CLI
|
|
|
|
The `ninja` command: build/verify/publish CMS plugins & themes, drive the plugin
|
|
registry, and capture theme preview screenshots. Its own repo since WO-WZ-023
|
|
(remote `git.dev.alexdunmow.com/block/cli`); formerly lived inside `cms`.
|
|
|
|
Go module `git.dev.alexdunmow.com/block/cli` (Go 1.26). Cobra CLI. Talks to the
|
|
orchestrator over Connect-RPC; builds `.bnp` artifacts with `block/core` +
|
|
wazero; screenshots with chromedp.
|
|
|
|
## Build / install / test
|
|
|
|
```bash
|
|
make build # → ./bin/ninja
|
|
make install # go install ./cmd/ninja → $GOBIN (yields `ninja` on PATH)
|
|
make test # go test ./... (compiles guest wasm fixtures: needs GOOS=wasip1 + core proxy)
|
|
make proto # regenerate the vendored orchestrator client (see below)
|
|
make safety-check # cd ../check-safety && go run . ../cli
|
|
```
|
|
|
|
> **`make install` matters.** `ninja plugin publish` / `ninja plugin build` use
|
|
> the binary on your PATH, not the repo. After changing build/pack behaviour you
|
|
> MUST `make install` before any publish or the old binary ships. The classic
|
|
> failure: an installed binary that predates `.bnp` preview-packing silently
|
|
> republishes a theme **without** its `preview.png`, wiping the live preview.
|
|
> Verify with `ninja theme screenshot --help | grep screenshots-dir` and by
|
|
> extracting a fresh `.bnp` (`ninja plugin verify <file.bnp>` → `preview=true`).
|
|
|
|
## Command surface
|
|
|
|
- `ninja plugin build | verify <f.bnp> | publish | init | status | bump [major|minor|patch]`
|
|
- `ninja plugin list | delete | delete-version | pull | version | abi`
|
|
- `ninja plugin tags add|rm|set|clear`
|
|
- `ninja scope create|default|set|list`
|
|
- `ninja account list|set|show` · `ninja login | whoami | logout`
|
|
- `ninja theme screenshot` (preview + `--pages`/`--screenshots-dir` multi-page capture)
|
|
|
|
## `.bnp` artifacts
|
|
|
|
A `.bnp` is a **zstd-compressed tar** (NOT gzip — `tar tzf` won't read it; use
|
|
`tar tf` or `ninja plugin verify`). `internal/bnp` owns build+verify; wasm
|
|
plugins and codeless plugins/themes both pack into one. Optionally packs a root
|
|
`preview.png` and a `screenshots/` dir (validated: png/jpg/jpeg/webp, ≤8MB/file,
|
|
≤12 files, no subdirs). `internal/shot` renders pages via chromedp for
|
|
`ninja theme screenshot`.
|
|
|
|
**Publish builds the artifact itself.** `ninja plugin publish` builds the `.bnp`
|
|
and ships it — the artifact is the ONLY publish form (the legacy source-archive
|
|
path is deleted). `--bnp <file>` ships a prebuilt one. Instances download the
|
|
artifact and never compile.
|
|
|
|
## Orchestrator target (dev vs prod)
|
|
|
|
Global `--host` flag: orchestrator base URL. **Default is
|
|
`https://my.blockninjacms.com` — PRODUCTION.** For local dev always pass
|
|
`--host https://my.blockninja.dev` (or set it as the active host via
|
|
`ninja login`). Never publish dev/test plugins to the prod registry by omitting
|
|
`--host`.
|
|
|
|
Auth is **device flow** (`ninja login` → `AuthService.StartDevice`/`PollDevice`).
|
|
Credentials (per-host token + active account) persist to
|
|
`<os.UserConfigDir>/ninja/credentials.json` (Linux: `~/.config/ninja/…`).
|
|
`internal/creds` reads/writes it; `internal/orchclient` builds the Connect client.
|
|
|
|
## Vendored orchestrator proto (NOT a submodule)
|
|
|
|
`proto/orchestrator/v1/plugin_registry.proto` is a **hand-vendored COPY** of the
|
|
orchestrator's proto, not a git submodule. `make proto` regenerates
|
|
`internal/api/orchestrator/v1/` from it. `buf.gen.yaml` runs in **managed mode**
|
|
and overrides `go_package_prefix` → `git.dev.alexdunmow.com/block/cli/internal/api`
|
|
so the generated Go lands in this module regardless of the proto's declared
|
|
`go_package`. Needs `buf` + `protoc-gen-go` + `protoc-gen-connect-go` on PATH.
|
|
|
|
**To pick up new orchestrator RPCs** (e.g. registry gallery/review methods): copy
|
|
the updated `plugin_registry.proto` (and any new proto) from the orchestrator's
|
|
proto into `proto/`, run `make proto`, then add client methods in
|
|
`internal/orchclient`. There is no automatic sync — the copy is deliberate so the
|
|
CLI pins a known server surface.
|
|
|
|
## Workspace couplings
|
|
|
|
- `make safety-check` shells into the sibling `../check-safety` tool — the CLI is
|
|
scanned like the other repos. Run it before publishing CLI changes.
|
|
- Depends on `git.dev.alexdunmow.com/block/core` (the plugin SDK) via the Gitea
|
|
module proxy. **Never** use `replace` directives — tag/push `core`, then bump.
|
|
- The `.bnp` format + pack/validation rules are shared truth with the CMS host
|
|
loader and the orchestrator registry ingestion; changing them is a cross-repo
|
|
contract change.
|
|
|
|
## Working in here
|
|
|
|
- Standalone repo: commit/push only within `cli/`. Work on `main`.
|
|
- Ask before publishing anything to a registry — publish is outward-facing and
|
|
hits a real orchestrator (prod by default).
|