Skip to content

docs(cli,daemon): regenerate cobra docs and toolbox swagger after rename#718

Merged
DorianZheng merged 1 commit into
mainfrom
chore/regen-cli-daemon-docs
Jun 10, 2026
Merged

docs(cli,daemon): regenerate cobra docs and toolbox swagger after rename#718
DorianZheng merged 1 commit into
mainfrom
chore/regen-cli-daemon-docs

Conversation

@DorianZheng

@DorianZheng DorianZheng commented Jun 10, 2026

Copy link
Copy Markdown
Member

Closes the "Regenerate cli cobra docs + daemon swaggo docs" checkbox from #711.

CLI Go source and daemon toolbox source are fully renamed (verified 0 sandbox tokens before regenerating), but the committed generated docs predated the rename — cobra markdown/YAML still said "Create a new sandbox" etc., and the toolbox swagger carried one stale token.

Changes (all generator output + one script fix)

  • apps/cli/docs/*.md, apps/cli/hack/docs/*.yaml — regenerated via hack/generate-cli-docs.sh (go run main.go generate-docs). Diff = sandbox→box description catch-up + genuine drift catch-up (newly documented flags such as --force, snapshot delete usage gaining SNAPSHOT_NAME).
  • apps/daemon/pkg/toolbox/docs/{docs.go,swagger.json,swagger.yaml} — regenerated via the daemon docs target command (swag fmt && swag init … && prettier). Now 0 sandbox tokens.
  • apps/cli/hack/generate-cli-docs.sh (+3) — adds a prettier pass over hack/docs/**/*.yaml: the committed YAML is prettier-formatted while raw cobra output is not, so without this every regen produces ~700 lines of quoting/indent churn (observed 1172→478 changed lines). Mirrors what the daemon docs target already does.

Verification

  • 0 sandbox tokens in all regenerated outputs (git grep -i sandbox over the three docs trees: empty).
  • Every changed line mechanically classified: rename catch-up, prettier/cobra whitespace normalization, or the named new-flag drift — nothing unexplained.
  • shellcheck clean on the script.

Note: unlike the API clients (#716 added a drift gate), these docs have no CI gate — staleness will accumulate again until regenerated; a sibling drift job is a possible follow-up.

Summary by CodeRabbit

  • Documentation

    • Updated CLI documentation to use "box" terminology instead of "sandbox" across all commands and help text.
    • Improved documentation formatting and alignment in command reference guides.
  • New Features

    • Added boxlite autocomplete command for shell completion support.
    • Enhanced boxlite snapshot delete to accept both snapshot ID and snapshot name.
    • Added --force flag to boxlite stop command for force-stopping boxes.

CLI Go source and daemon toolbox source are fully renamed, but the
generated docs were last produced before the rename: cobra markdown/yaml
still said 'Create a new sandbox' etc. and the toolbox swagger carried one
stale token. Re-run the generators; output now has zero sandbox tokens.

generate-cli-docs.sh gains a prettier pass over hack/docs YAML — the
committed YAML is prettier-formatted while raw cobra output is not, so
without it every regen produces ~700 lines of quoting/indent churn. The
daemon docs target already does the same.

Part of the #711 post-rename regen items.

Signed-off-by: dorianzheng <xingzhengde72@gmail.com>
@DorianZheng DorianZheng requested a review from a team as a code owner June 10, 2026 05:42
@coderabbitai

coderabbitai Bot commented Jun 10, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9e69d1fa-80e4-48cc-a4d7-2ec54516df5c

📥 Commits

Reviewing files that changed from the base of the PR and between e9ae0e6 and 855cf98.

📒 Files selected for processing (53)
  • apps/cli/docs/boxlite.md
  • apps/cli/docs/boxlite_archive.md
  • apps/cli/docs/boxlite_autocomplete.md
  • apps/cli/docs/boxlite_create.md
  • apps/cli/docs/boxlite_delete.md
  • apps/cli/docs/boxlite_docs.md
  • apps/cli/docs/boxlite_exec.md
  • apps/cli/docs/boxlite_info.md
  • apps/cli/docs/boxlite_list.md
  • apps/cli/docs/boxlite_login.md
  • apps/cli/docs/boxlite_logout.md
  • apps/cli/docs/boxlite_mcp.md
  • apps/cli/docs/boxlite_mcp_config.md
  • apps/cli/docs/boxlite_mcp_init.md
  • apps/cli/docs/boxlite_mcp_start.md
  • apps/cli/docs/boxlite_organization.md
  • apps/cli/docs/boxlite_organization_create.md
  • apps/cli/docs/boxlite_organization_delete.md
  • apps/cli/docs/boxlite_organization_list.md
  • apps/cli/docs/boxlite_organization_use.md
  • apps/cli/docs/boxlite_preview-url.md
  • apps/cli/docs/boxlite_snapshot.md
  • apps/cli/docs/boxlite_snapshot_create.md
  • apps/cli/docs/boxlite_snapshot_delete.md
  • apps/cli/docs/boxlite_snapshot_list.md
  • apps/cli/docs/boxlite_snapshot_push.md
  • apps/cli/docs/boxlite_ssh.md
  • apps/cli/docs/boxlite_start.md
  • apps/cli/docs/boxlite_stop.md
  • apps/cli/docs/boxlite_version.md
  • apps/cli/docs/boxlite_volume.md
  • apps/cli/docs/boxlite_volume_create.md
  • apps/cli/docs/boxlite_volume_delete.md
  • apps/cli/docs/boxlite_volume_get.md
  • apps/cli/docs/boxlite_volume_list.md
  • apps/cli/hack/docs/boxlite.yaml
  • apps/cli/hack/docs/boxlite_archive.yaml
  • apps/cli/hack/docs/boxlite_create.yaml
  • apps/cli/hack/docs/boxlite_delete.yaml
  • apps/cli/hack/docs/boxlite_exec.yaml
  • apps/cli/hack/docs/boxlite_info.yaml
  • apps/cli/hack/docs/boxlite_list.yaml
  • apps/cli/hack/docs/boxlite_preview-url.yaml
  • apps/cli/hack/docs/boxlite_snapshot_create.yaml
  • apps/cli/hack/docs/boxlite_snapshot_delete.yaml
  • apps/cli/hack/docs/boxlite_snapshot_push.yaml
  • apps/cli/hack/docs/boxlite_ssh.yaml
  • apps/cli/hack/docs/boxlite_start.yaml
  • apps/cli/hack/docs/boxlite_stop.yaml
  • apps/cli/hack/generate-cli-docs.sh
  • apps/daemon/pkg/toolbox/docs/docs.go
  • apps/daemon/pkg/toolbox/docs/swagger.json
  • apps/daemon/pkg/toolbox/docs/swagger.yaml

📝 Walkthrough

Walkthrough

This PR systematically updates BoxLite CLI and API documentation from "sandbox" to "box" terminology. It replaces sandbox-oriented command descriptions and parameter names with box equivalents across YAML source files and their generated Markdown outputs, standardizes SEE ALSO section formatting with tab-delimited alignment, and enhances the CLI docs build process with Prettier formatting.

Changes

Documentation Terminology and Format Updates

Layer / File(s) Summary
Command documentation terminology updates
apps/cli/hack/docs/boxlite*.yaml, apps/cli/docs/boxlite*.md
All major boxlite subcommand documentation (create, delete, exec, info, list, preview-url, snapshot variants, ssh, start, stop, archive) updated from sandbox-focused to box-focused terminology in YAML sources and generated Markdown files, including command descriptions, option help text, and parameter placeholders (e.g., [BOX_ID | BOX_NAME] replaces [SANDBOX_ID | SANDBOX_NAME]).
SEE ALSO section formatting standardization
apps/cli/hack/docs/*.yaml, apps/cli/docs/*.md
Normalized whitespace and tab alignment in SEE ALSO sections across all documentation files for consistent link-to-description spacing in both YAML source and generated Markdown outputs.
Build automation and API documentation
apps/cli/hack/generate-cli-docs.sh, apps/daemon/pkg/toolbox/docs/docs.go, apps/daemon/pkg/toolbox/docs/swagger.json, apps/daemon/pkg/toolbox/docs/swagger.yaml
CLI docs generation script enhanced to run Prettier on generated YAML files; Swagger/OpenAPI endpoint descriptions updated from sandbox to box terminology for GET /process/session/entrypoint/logs.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Poem

📦 From sandbox walls we've set them free,
Now boxes hold what used to be,
With Prettier's touch, our docs align,
The rebranding shines, a tidy design. ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs(cli,daemon): regenerate cobra docs and toolbox swagger after rename' accurately summarizes the main change: regenerating documentation files after renaming 'sandbox' to 'box' terminology across CLI and daemon components.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/regen-cli-daemon-docs

Comment @coderabbitai help to get the list of available commands and usage tips.

@DorianZheng DorianZheng merged commit 8a62978 into main Jun 10, 2026
32 checks passed
@DorianZheng DorianZheng deleted the chore/regen-cli-daemon-docs branch June 10, 2026 06:33
DorianZheng added a commit that referenced this pull request Jun 10, 2026
…lient, fix dead env vars + stale refs

- regenerate toolbox-api-client from the (already-renamed) committed
  daemon swagger: 7.12.0 → pinned 7.23.0 generator, kills the last
  4 generated "sandbox entrypoint" doc-comments; missed by #716/#718
  which covered only the product clients
- add toolbox-api-client to the api-client-drift gate with
  --excludeTaskDependencies (committed daemon swagger is the contract;
  daemon-source↔swagger drift stays ungated, needs swag toolchain)
- fix nx paths broken since the apps/ workspace flattening: generator
  -i specs in toolbox/runner client project.json (apps/daemon→daemon,
  apps/runner→runner — toolbox regen failed outright on the stale
  path) and nx.json cache inputs (go.work, daemon swagger), which
  pointed at nonexistent files and never invalidated caches
- e2e bootstrap.sh + infra-local api.env wrote ADMIN_MAX_*_PER_SANDBOX
  but the API reads ADMIN_MAX_*_PER_BOX (configuration.ts:292) with
  default 0 — admin-org per-box quotas were silently unset
- stack-reset.sh and infra-local README TRUNCATE/SELECT table
  `sandbox`, which migration 1781016743403 renamed to `box`; also
  /api/sandbox routes → /api/box and {{sandboxId}} → {{boxId}} per
  the configuration DTO example
- sweep remaining sandbox vocabulary from e2e cases, teardown,
  runner-update-binary.sh, and infra-local docs (comments,
  docstrings, test function names; no selector references them)
- includes 3 files prettier-normalized by the repo's `make lint:fix`
  pre-commit autofixer (eslint.config.mjs, Sidebar.tsx,
  Onboarding.tsx) — out of format on main; the hook is repo-wide
  and re-applies them on every commit until committed

Part of #711.

Signed-off-by: dorianzheng <xingzhengde72@gmail.com>
DorianZheng added a commit that referenced this pull request Jun 10, 2026
…lient, fix dead env vars + stale refs (#723)

Part of #711 — closes out the "Part 1 of N" remainder. A repo-wide sweep
found the rename effectively complete in source
(`runner`/`cli`/`daemon`/`dashboard`/`proxy` at zero tokens; `apps/api`
leftovers are historical migrations, correct as-is). What remained is
below.

## Generated client (the bulk of the diff)

**`toolbox-api-client` regenerated** from the committed
`apps/daemon/pkg/toolbox/docs/swagger.json` (which #718 already renamed
— `git grep "sandbox entrypoint"` has zero hits outside the generated
client). This kills the last 4 generated `sandbox entrypoint session`
doc-comments and moves the client from generator 7.12.0 to the pinned
7.23.0, same modernization #721 did for analytics (hence the
`src/docs/*.md` additions — 7.23 emits them, and the drift gate requires
committed == emitted).

Determinism verified: regen run twice locally (with and without
`--excludeTaskDependencies`), byte-identical both times.

**Drift gate now covers it** (`api-client-drift.yml`): regen via
`--excludeTaskDependencies` so the committed daemon swagger is the
contract and the job needs no Go/swag toolchain. Daemon-source↔swagger
drift stays ungated (the cli/daemon-docs sibling gate noted in #711
remains a follow-up). actionlint + shellcheck clean.

## Why the toolbox client was never regenerated: broken nx paths

The regen target failed outright: `-i
apps/daemon/pkg/toolbox/docs/swagger.json` resolves relative to the nx
workspace root, which *is* `apps/` → `apps/apps/daemon/...` (spec not
found). Kept from upstream daytona's repo layout; #716 fixed only the
product clients' targets. Fixed here:

- `libs/toolbox-api-client/project.json` — `-i
daemon/pkg/toolbox/docs/swagger.json`
- `libs/runner-api-client/project.json` — same latent bug (`-i
runner/...` + its `{workspaceRoot}` input)
- `nx.json` — `apiClient`/`goProduction` named inputs pointed at
`{workspaceRoot}/apps/...` paths that don't exist, so swagger/go.work
changes never invalidated task caches

## Functional config fixes

- **`scripts/test/e2e/bootstrap.sh` +
`apps/infra-local/configs/api.env`** wrote
`ADMIN_MAX_{CPU,MEMORY,DISK}_PER_SANDBOX`, but the API reads
`ADMIN_MAX_*_PER_BOX` (`apps/api/src/config/configuration.ts:292-294`)
with default `0` — admin-org per-box quotas were silently unset.
- **`apps/infra-local/scripts/stack-reset.sh` + README runbook
snippets** ran `TRUNCATE TABLE sandbox, ...` / `SELECT ... FROM sandbox`
— that table was renamed to `box` by migration `1781016743403`, so these
failed as written. Also `/api/sandbox` → `/api/box` (route is
`@Controller('box')`) and `{{sandboxId}}` → `{{boxId}}` (matches the
`configuration.dto.ts` example). infra-local merged in #595 on a
pre-#706 vocabulary.

## Vocabulary sweep (no behavior change)

Comments, docstrings, and three e2e test function names
(`test_*_above_per_sandbox_limit_*` → `per_box`; no `-k` selector,
workflow, or Makefile references them) across `scripts/test/e2e/`,
`scripts/deploy/runner-update-binary.sh`, and `apps/infra-local/`.
File/path references verified against the tree (`box.service.ts`,
`volume.manager.ts:47`, `box_sync.go`, `CREATE_BOX` journal tokens). All
three trees now grep-clean for `sandbox`.

Also includes 3 files prettier-normalized by the repo's `make lint:fix`
pre-commit autofixer (`eslint.config.mjs`, `Sidebar.tsx`,
`Onboarding.tsx`) — they were out of format on `main` and the repo-wide
hook re-applies them on every commit until committed.

## Verification

- Regen byte-identical across repeated runs, including the exact CI
invocation
- `actionlint` + `shellcheck` on the workflow; `shellcheck` on all 6
edited shell scripts (only pre-existing findings on untouched lines);
`py_compile` on all 7 edited Python files
- Every text replacement applied with an exact-unique-match assertion
(count==1 before replace)
- OS-isolation uses of "sandbox" (jailer/seatbelt/bwrap, docs/faq)
deliberately untouched — different concept per the rename's scope

Signed-off-by: dorianzheng <xingzhengde72@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant