diff --git a/README.md b/README.md index 8f098a5..3039c9f 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ Planned commands include: - `basectl setup ` - `basectl test` - `basectl test ` +- `basectl onboard` The important idea is that the user should not need to memorize a different bootstrap story for every repository in the workspace. Planned commands are @@ -152,6 +153,11 @@ basectl doctor basectl doctor --dev ``` +`basectl onboard` is a planned guided setup experience for technically-adjacent +users who want a checklist-style first Base setup. Its design is captured in +[docs/basectl-onboard.md](docs/basectl-onboard.md). Product-specific onboarding +should still live in project installers that call Base internally. + ### 2. Shell Environment Management Base should manage shell environments at two levels: diff --git a/TODO.md b/TODO.md index 883a3a7..cc07c8c 100644 --- a/TODO.md +++ b/TODO.md @@ -39,14 +39,18 @@ they are merged. - Cover manifest validation, dry-run command planning, daemon-check failures, Compose command failures, and activate-time startup behavior. -- [ ] Design `basectl onboard`. - - Goal: provide a guided checklist-style setup experience without making `basectl setup` itself interactive-heavy. - - Expected behavior: explain each prerequisite, confirm before performing major steps, and call existing setup/check primitives internally. - - [ ] Package Base as a Homebrew formula or tap. - Goal: make Base installation feel native on macOS. - Expected behavior: support an install path such as `brew install codeforester/base/basectl`. +- [ ] Implement `basectl onboard`. + - Goal: provide the guided checklist-style Base setup experience described in + `docs/basectl-onboard.md`. + - Expected behavior: orchestrate existing setup, check, doctor, profile, and + project-discovery primitives without duplicating their logic. + - Starting point: implement the v1 Bash subcommand with dry-run, prompted, + `--yes`, `--dev`, and `--no-profile` flows. + - [ ] Add initial Linux support plan. - Goal: define the first supported Linux target, likely Ubuntu/Debian. - Expected design topics: `/etc/os-release` detection, `apt` equivalents for Homebrew-managed bootstrap dependencies, shell startup differences, and CI implications. diff --git a/cli/bash/commands/basectl/README.md b/cli/bash/commands/basectl/README.md index 5b65cab..9e8bc47 100644 --- a/cli/bash/commands/basectl/README.md +++ b/cli/bash/commands/basectl/README.md @@ -34,6 +34,10 @@ that delegate to `basectl`. - `version` - `help` +## Planned subcommands + +- `onboard` + ## Notes - `basectl setup` is the default local bootstrap path. @@ -52,5 +56,8 @@ that delegate to `basectl`. - `basectl update` updates the Base repository from Git and then runs `basectl setup`. - `basectl projects list` scans a workspace for `base_manifest.yaml` files and prints discovered project names and paths. - `basectl version` prints the installed Base version from the repo-root `VERSION` file. +- `basectl onboard` is planned as a guided first-run checklist around existing + setup, check, doctor, profile, and project-discovery primitives. See + `docs/basectl-onboard.md`. - basectl-specific bootstrap subcommands live under `cli/bash/commands/basectl/subcommands/`. - basectl tests live under `cli/bash/commands/basectl/tests/`. diff --git a/docs/basectl-onboard.md b/docs/basectl-onboard.md new file mode 100644 index 0000000..83db3b9 --- /dev/null +++ b/docs/basectl-onboard.md @@ -0,0 +1,152 @@ +# `basectl onboard` Design + +`basectl onboard` is a future guided setup experience for Base itself. + +It should help technically-adjacent users through the first Base setup without +turning `basectl setup` into an interactive, hand-holding command. The setup +command should remain the direct, scriptable reconciler. The onboard command can +be slower, friendlier, and more explanatory because that is its purpose. + +## Audience + +`basectl onboard` is for someone who can use a terminal but does not yet know +what Base will do to their machine. + +Examples: + +- a DevOps learner setting up a Mac for a Base-managed project +- a new developer joining a workspace that uses Base +- a technically-adjacent user who wants confirmation before each major setup + step + +It is not the right layer for product-specific onboarding. A project such as +Banyanlabs should still own its own `install.sh` or packaged installer and call +Base internally. See [Project Installers](project-installers.md) for that +boundary. + +## Relationship To Existing Commands + +`basectl onboard` should orchestrate existing Base primitives: + +- `basectl check` for quick environment state +- `basectl doctor` for human-readable diagnosis and suggested fixes +- `basectl setup` for actual reconciliation +- `basectl setup --dev` when the user opts into Base developer prerequisites +- `basectl update-profile` for shell startup integration +- `basectl projects list` to show discovered projects after setup +- `basectl activate base` as the final suggested next step + +It should not duplicate Homebrew, Python, venv, manifest, or shell-profile logic. +Those responsibilities already belong to the setup/check/profile commands. + +## Command Shape + +Initial command shape: + +```bash +basectl onboard [options] +``` + +Planned options: + +```text + --dev Include Base developer prerequisites. + --dry-run Explain and show planned actions without making changes. + --yes Accept default answers for non-destructive prompts. + --no-profile Skip shell profile updates. + -v Enable DEBUG logging for underlying commands. + -h, --help Show help text. +``` + +The command should default to the `base` project. Project-specific guided +onboarding remains a project installer responsibility. + +## Experience Flow + +The first implementation should be simple and checklist-oriented: + +1. Print a short explanation of what Base is about to verify. +2. Run `basectl check`. +3. If checks fail, explain that setup can reconcile the missing pieces. +4. Ask for confirmation before running `basectl setup`. +5. If `--dev` was requested, include developer prerequisites in setup. +6. Ask for confirmation before running `basectl update-profile`, unless + `--no-profile` was set. +7. Run `basectl doctor` to summarize the final state. +8. Print discovered projects with `basectl projects list` when available. +9. Suggest `basectl` or `basectl activate base` as the next interactive step. + +The command should show the exact Base command before it runs it. For example: + +```text +Next: basectl setup +This installs or verifies Homebrew, Xcode Command Line Tools, Base Python, and +Base-managed artifacts. +Proceed? [y/N] +``` + +## Prompting Rules + +Prompts should be explicit but sparse: + +- Prompt before operations that can install software or edit shell startup files. +- Do not prompt before read-only checks. +- Treat Enter as the conservative answer when there is risk. +- `--yes` may accept normal setup/profile prompts, but should not bypass fatal + safety checks such as unsupported operating systems. +- `--dry-run` should not prompt for actions it will not perform. + +## Output Style + +The command should be friendly without hiding the mechanics: + +- Use plain English headings such as `Check`, `Setup`, `Shell Profile`, and + `Next Steps`. +- Keep underlying command output visible so users can see long-running progress. +- Keep logs on stderr, following Base's existing logging convention. +- Use `basectl doctor` output for final health reporting rather than inventing a + separate diagnosis format. + +## Failure Behavior + +Failures should be recoverable and specific: + +- If `basectl check` fails, continue to the setup prompt. +- If `basectl setup` fails, run or recommend `basectl doctor` and stop before + profile updates. +- If `basectl update-profile` fails, leave setup success intact and explain how + to rerun that step. +- Preserve the failing command's exit status when onboarding cannot complete. + +## Non-Goals + +`basectl onboard` should not: + +- become a replacement for `basectl setup` +- become a product-specific installer +- clone project repositories +- manage secrets or credentials +- hide underlying command output behind a full-screen interface in v1 +- introduce a dependency on a TUI framework before the simple checklist version + proves insufficient + +## Implementation Notes + +The first implementation can be a Bash subcommand under +`cli/bash/commands/basectl/subcommands/onboard.sh`. + +That keeps it close to the setup/check/profile primitives it orchestrates and +avoids adding Python dependencies for interactive prompting. If a richer UI is +needed later, the Bash command can delegate to a Python package while preserving +the same public command. + +Tests should cover: + +- help text +- dry-run flow +- declined setup prompt +- accepted setup prompt +- `--yes` non-interactive flow +- `--dev` passing through to setup and doctor +- `--no-profile` skipping profile updates +- setup failure stopping later steps diff --git a/docs/project-installers.md b/docs/project-installers.md index 69f7cbc..1fef18d 100644 --- a/docs/project-installers.md +++ b/docs/project-installers.md @@ -92,7 +92,8 @@ Project installers should not: ## Relationship To `basectl onboard` -`basectl onboard` is still useful, but it should target a different layer. +`basectl onboard` is still useful, but it should target a different layer. Its +command design is captured in [basectl-onboard.md](basectl-onboard.md). `basectl onboard` should be a guided Base setup experience for technically-adjacent users who are installing Base itself. A project installer