Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion docs/athens/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ Requirements:
- Podman
- `just`
- Mkosi meeting the minimum in `mkosi.conf`
- OpenSSL (`just genkey` runs `openssl` on the host)
- `sudo` access (`just build-image` and `just clean` run Mkosi as root)
- `zstd`
- `systemd`

Expand All @@ -36,6 +38,12 @@ The Mkosi image and partition artifacts are written to `mkosi.output/`. This
path remains the existing disk-image build; it does not produce an OCI image.
It does not produce a qualified installer ISO or production release.

The committed configuration sets no root password. For a root login on a local
test build, write a password to `mkosi.images/os/mkosi.rootpw` (mode `0600`,
git-ignored) before building; Mkosi reads it in place of `RootPassword=`. Mkosi
stores that password inside the image's `/usr`, so do not hand such an image to
anyone else.

Build the separate Athens bootc OCI image with BuildStream, then export its OCI
layout to `buildstream-oci/`:

Expand All @@ -49,7 +57,9 @@ just lint-oci
`just export-oci` checks out the already-built `oci/athens.bst` artifact and
requires the `buildstream-oci/` destination not to exist. `just load-oci`
imports that local OCI layout into Podman without a registry operation;
`just lint-oci` runs `bootc container lint` on the imported image.
`just lint-oci` runs `bootc container lint` on the imported image, then
`scripts/check-image-access.sh`, which fails if the image has an account with an
empty password, a stored root password, a `NOPASSWD` sudo rule or an autologin.
The target layers only Athens's Pantheon/codecs content over the GNOME OS OCI
base runtime and sets the `containers.bootc` image label. It does not produce a
disk image or push to a registry.
Expand All @@ -67,6 +77,28 @@ image or prove boot/install/deployment behavior. The OCI bootc path is
experimental and local-only; the local lint recipe has not been run, nor has
the image been tested through bootc installation/update flows.

Pull requests and pushes to `bst` also run `actions-security.yml`, which checks
the workflows themselves:

- The `lockfile` job runs `gh actions-lock --verify` (the
[`github/gh-actions-lock`](https://github.com/github/gh-actions-lock)
extension, version pinned in the job). It fails when
`.github/workflows/actions.lock` no longer matches the `uses:` lines in the
workflows, or when a locked pin no longer verifies upstream.
- The `zizmor` job runs the zizmor workflow security linter and fails on any
finding.

The contract tests include `tests/test_access_invariants.py`. It fails when a
file either image build reads sets a root password, blanks a password, adds a
`NOPASSWD` sudo rule or turns on an autologin. Access for a test build belongs
in git-ignored local configuration, as under "Build locally".

`actions.lock` is generated; do not edit it by hand. After adding a workflow
or changing any `uses:` line (including a Dependabot action bump), install the
extension once with `gh extension install github/gh-actions-lock`, run
`gh actions-lock` from the repository root, and commit the updated lockfile in
the same pull request.

The GNOME OS junction's secure-boot key sources use its checked-in key-generation
template in the default `snakeoil` mode. No signing key is committed or used for
production signing; this does not establish a distributable secure-boot trust
Expand Down
146 changes: 146 additions & 0 deletions docs/bluefin-cli/development.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
---
sidebar_position: 9
title: "development"
---

This guide maps the repository so you can find where a change belongs. For
build, test, and lint commands, see [`CONTRIBUTING.md`](https://github.com/tuna-os/bluefin-cli/blob/main/CONTRIBUTING.md). For
the test layers, see [`testing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/testing.md). For architecture rules that
reviewers enforce, see [AGENTS.md](https://github.com/tuna-os/bluefin-cli/blob/main/AGENTS.md).

## Top-level layout

| Path | What it holds |
|---|---|
| `main.go` | Entry point. Hands control to the `cmd` package. |
| `cmd/` | Cobra commands and the TUI destinations they open. |
| `internal/` | Reusable behavior, grouped by package. |
| `docs/` | User and developer docs. `docs/commands/` is generated. |
| `docs/adr/` | Architecture decision records. |
| `scripts/` | Shell suites for TUI smoke tests, state tests, and shell experience. |
| `test/` | Go integration tests. |
| `src/bluefin-cli/` | Dev container feature files. |
| `tools/release/` | Release tooling. |
| `justfile` | Task recipes. Run `just --list`. |

The repository builds two binaries from one source tree: `bluefin-cli`
(standard) and `bluefin-cli-plus` (`-tags extra`). See
[vanilla-vs-extra.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/vanilla-vs-extra.md).

## `cmd/`: command wiring

Each file registers a Cobra command on the root command in `cmd/root.go`
(for example `doctor.go`, `install.go`, `shell.go`, `profile.go`, `update.go`).
Keep argument parse and wiring code here. Put reusable behavior in `internal/`.

The `menu*.go`, `shell_menu.go`, and `install_menu.go` files assemble the
interactive menu:

- `menu.go` defines the `menu` command, starts the TUI with `app.Run`, and
runs the background update check.
- `menu_model.go` describes the main menu as data (items, icons, descriptions).
- `menu_router.go` maps a selected menu value to a handler.
- `menu_native.go` holds in-shell flows: forms, text views, and runner screens
that capture command output.
- `menu_vanilla.go`, `menu_extra.go`, and `menu_extra_actions.go` hold the
parts that differ between builds.

### Build-tag split

Features that only ship in the plus build (wallpapers, fonts, sunset) sit
behind the `extra` build tag. Files marked `//go:build extra` hold the real
code. `cmd/extra_stubs.go` (`//go:build !extra`) supplies no-op stand-ins so
the standard build compiles. After you change a conditional feature, check both
builds. `cmd/variant_contract_test.go` and the `*_extra_test.go` files cover
this split.

## `internal/`: packages

| Package | Owns |
|---|---|
| `tui/app` | The persistent Bubble Tea program: screen stack, header and footer, command palette, and runners. See below. |
| `tui` and `tui/theme` | Shared styles and theme definitions for the TUI. |
| `shell` | Shell experience for Bash, Zsh, Fish, ash, Nushell, and PowerShell: enabling and disabling, rendering the init script, status, and uninstall. |
| `install` | Packages, bundles, Brewfiles, and wallpaper collections. Embeds Brewfiles and wallpaper metadata from `install/resources/`. |
| `pkgmanager` | Package manager selection on Alpine-family hosts (coldbrew, then apk). |
| `config` | Persisted configuration file. |
| `env` | Config directory lookup and terminal environment detection. |
| `profile` | Portable profiles: export, import, diff, and gist sync. |
| `update` | Checksum-verified self-update. |
| `doctor` | Diagnostic probes, `--fix` remediation, shell startup benchmark, and report rendering (`doctor/render`). |
| `status` | The status report. |
| `motd` | Message-of-the-day handling. |
| `starship` | Starship install and preset themes. |
| `terminal` | Terminal emulator and font setup. |
| `wallpaper` | Native per-platform wallpaper setting. |
| `sunset` | Sunset and sunrise theme and wallpaper switching. |
| `countme` | The Fedora countme protocol implementation. |

### The TUI (`internal/tui/app`)

- A `Screen` (`app.go`) is one level of the navigation stack: `Title`, `Init`,
`Update`, `View`, and `KeyHints`.
- Screen types: `MenuScreen` (`menu.go`), `FormScreen` (`form.go`),
`TextScreen` (`text.go`), and `RunnerScreen` (`runner.go`) for captured
task output. `wallpaper_picker.go`, `game.go`, and `dino.go` hold special
screens and art.
- An `Action` (`action.go`) is a registered capability. Menus and the
`ctrl+p` command palette read the same registry, so each action is
reachable from both. Modules call `app.Register` for their own actions.
- `exec.go` releases the terminal for an external interactive program. Use it
only when a command must own the terminal.

### Shell integration (`internal/shell`)

- `shells.go` is the registry of managed shells: rc path, init line, and
syntax flavor. Add a shell there.
- `resources/` holds the init scripts (`shell.sh`, `shell.fish`, `shell.nu`,
`shell.ps1`). `nu_aliases.go` generates the Nushell aliases.
- Installation backends are separate from the shell init code: `installers.go`
(shared entry points and Homebrew), `windows_tools.go` (winget),
`install_alpine.go` (coldbrew/apk). `shell.go` keeps enablement, the init
output, and status.

### Embedded resources (`internal/install/resources`)

Brewfiles and wallpaper metadata ship inside the binary. Update them with
`just update-resources`, which also rewrites `PROVENANCE.json`. Do not edit
them by hand.

## How a command reaches `internal/`

1. `main.go` calls into `cmd`, which runs the root Cobra command.
2. The subcommand's `RunE` in `cmd/<name>.go` parses flags and calls a
function in the matching `internal/` package.
3. For the TUI, `bluefin-cli menu` calls `app.Run` with the main menu screen.
Menu selections go through the router to screens or actions, which call
the same `internal/` functions the CLI commands use.

## Where to start

- **Add a command.** Create `cmd/<name>.go`, register it with
`rootCmd.AddCommand` in `init`, put the logic in `internal/`, then run
`just gen-docs` to regenerate `docs/commands/`. CI fails on a stale diff.
- **Add a TUI destination.** Make a type that satisfies `app.Screen`, or
register an `app.Action`. Reuse `RunnerScreen` for tasks that show command
output.
- **Fix or extend shell integration.** Start in `internal/shell`
(`shells.go`, `resources/`), and see the scope rules in
[AGENTS.md](https://github.com/tuna-os/bluefin-cli/blob/main/AGENTS.md).
- **Add a package or bundle.** Update the embedded resources with
`just update-resources`. See [brewfile-guide.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/brewfile-guide.md).
- **Change config or profile behavior.** Use `internal/config` and
`internal/profile`. See [configuration.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/configuration.md) and
[profiles.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/profiles.md).

## Test layout

- Unit tests sit beside the code as `*_test.go` in each package.
- `cmd/*_test.go` covers command and menu wiring, including build-variant
contracts.
- `test/` holds Go integration tests that the containerized suite
(`just test`) runs.
- `scripts/` holds the shell suites: `tui-smoke.sh`, `tui-state.sh`, and
`shell-experience.sh`.

See [`testing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/testing.md) for how to run each layer and add tests.
2 changes: 1 addition & 1 deletion docs/bluefin-cli/getting-started.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 9
sidebar_position: 10
title: "getting started"
---

Expand Down
2 changes: 1 addition & 1 deletion docs/bluefin-cli/gnome.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 10
sidebar_position: 11
title: "gnome"
---

Expand Down
76 changes: 44 additions & 32 deletions docs/bluefin-cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,14 @@ Never post account credentials or API keys in issues or pull requests.

## 🚀 Installation

> **Status (2026-10-07):** each release ships prebuilt binary assets:
> tarballs for Linux, macOS and Windows, plus native deb and rpm packages.
> The one-liner scripts and direct downloads below work today. A note
> marks each package-manager path that does not work yet.
> **Status (2026-11-19):** each release ships prebuilt binary assets:
> archives for Linux, macOS and Windows, plus native deb and rpm packages
> (see `.goreleaser.yaml`). The latest tag in the repository is v0.11.23; the
> [releases page](https://github.com/tuna-os/bluefin-cli/releases/latest) is
> authoritative for the current version. Package-manager channels depend on
> external registries that this repository cannot check. Their states come
> from [`docs/release-publishing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md), last
> recorded 2026-10-17, and a note marks each path that is not available.

### One-liner (Linux / macOS)

Expand All @@ -53,8 +57,8 @@ For more Linux and macOS steps, see the [Linux Setup Guide](https://github.com/t
curl -fsSL https://raw.githubusercontent.com/tuna-os/bluefin-cli/main/install.sh | sh
```

> **Status (2026-10-07):** the script downloads the binary from GitHub release
> assets, published on every release since v0.10.6.
> **Status (2026-11-19):** the script downloads the binary from GitHub release
> assets. Releases have published these assets since v0.10.6.

### One-liner (Windows PowerShell)

Expand All @@ -70,51 +74,57 @@ Then enable shell integration:
bluefin-cli shell powershell on
```

> **Status (2026-10-07):** same as the Linux/macOS one-liner — the script
> downloads from GitHub release assets, published on every release since
> v0.10.6.
> **Status (2026-11-19):** same as the Linux/macOS one-liner — the script
> downloads from GitHub release assets. Releases have published these assets
> since v0.10.6.

### Homebrew (Linux / macOS)

The preview formula is available from `ublue-os/homebrew-experimental-tap`,
synced from the source-build formula in
[`contrib/homebrew/bluefin-cli.rb`](https://github.com/tuna-os/bluefin-cli/blob/main/contrib/homebrew/bluefin-cli.rb):
```bash
brew tap tuna-os/tap
brew install tuna-os/tap/bluefin-cli
```

> **Status (2026-11-19):** GoReleaser publishes the binary formula to
> [`tuna-os/homebrew-tap`](https://github.com/tuna-os/homebrew-tap) on each
> release, with the `HOMEBREW_TAP_SSH_KEY` deploy key. The tap has received
> each release since v0.11.17, and its `Formula/bluefin-cli.rb` is at v0.11.23.
> The [release policy](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md) keeps this channel at
> **preview** until a maintainer records a `brew install` check.

A source-build preview formula is also available from
`ublue-os/homebrew-experimental-tap`. A maintainer syncs it by hand from
[`contrib/homebrew/bluefin-cli.rb`](https://github.com/tuna-os/bluefin-cli/blob/main/contrib/homebrew/bluefin-cli.rb), so it
can lag behind the current release:

```bash
brew tap ublue-os/homebrew-experimental-tap
brew install bluefin-cli
```

> **Status (2026-10-17):** use `ublue-os/homebrew-experimental-tap` above.
> The primary tap [`tuna-os/homebrew-tap`](https://github.com/tuna-os/homebrew-tap)
> is not available yet. The GoReleaser configuration includes the Homebrew
> publisher. It pushes to the tap with the `HOMEBREW_TAP_SSH_KEY` deploy key,
> but the team has not verified a publication yet
> ([#295](https://github.com/tuna-os/bluefin-cli/issues/295)). For maintainer
> key and setup details, see
> [`docs/release-publishing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md). Once published,
> `brew tap tuna-os/tap && brew install bluefin-cli` will be the primary path.

### Winget (Windows)

```powershell
winget install --id Hanthor.BluefinCLI --exact
```

> **Status (2026-10-07):** the winget repository has `Hanthor.BluefinCLI`
> **v0.8.1** (microsoft/winget-pkgs#407090). That version predates the
> current v0.11.x release line — **installable, though not current**. A
> newer manifest awaits review; `.github/workflows/winget.yml` is the manual
> fallback to resubmit one.
> **Status (last recorded 2026-10-17; not re-verified):** the winget
> repository had `Hanthor.BluefinCLI` **v0.8.1** (microsoft/winget-pkgs#407090).
> That version predates the current v0.11.x release line — **installable,
> though not current**. Check the
> [winget-pkgs listing](https://github.com/microsoft/winget-pkgs/tree/master/manifests/h/Hanthor/BluefinCLI)
> for the live version. `.github/workflows/winget.yml` is the manual fallback
> to resubmit one.

### Chocolatey (Windows)

```powershell
choco install bluefin-cli
```

> **Status (2026-10-07):** the Chocolatey community repository has no
> `bluefin-cli` package yet — **not available**.
> **Status (last recorded 2026-10-17; not re-verified):** no `bluefin-cli`
> package was in the Chocolatey community repository — **not available**.
> The release invocation skips this publisher.

### Scoop (Windows)

Expand All @@ -123,7 +133,7 @@ scoop bucket add tuna-os https://github.com/tuna-os/scoop-bucket
scoop install bluefin-cli
```

> **Status (2026-10-07):** still not published — `tuna-os/scoop-bucket`
> **Status (last recorded 2026-10-17; not re-verified):** not published — `tuna-os/scoop-bucket`
> ships no manifests at all. Like the Homebrew tap above, GoReleaser skips
> the Scoop publisher because no one has set the `SCOOP_BUCKET_TOKEN`
> repository secret; see
Expand All @@ -147,8 +157,8 @@ sudo rpm -i bluefin-cli_<version>_linux_amd64.rpm
yay -S bluefin-cli-bin
```

> **Status (2026-10-07):** no `bluefin-cli-bin` package exists in the AUR yet
> — **not available**.
> **Status (last recorded 2026-10-17; not re-verified):** no
> `bluefin-cli-bin` package existed in the AUR — **not available**.

### Go Install

Expand Down Expand Up @@ -424,6 +434,8 @@ grep # ugrep (if installed)
output, and fixes for common setup problems.
- [`docs/testing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/testing.md): how to run the TUI tests, the test
layers, and how to add a test.
- [`docs/development.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/development.md): where each part of the code
lives and where to start a change.

Maintainers can find package-channel credentials and release checks in
[release details](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md). The
Expand Down
2 changes: 1 addition & 1 deletion docs/bluefin-cli/menus.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 11
sidebar_position: 12
title: "menus"
---

Expand Down
2 changes: 1 addition & 1 deletion docs/bluefin-cli/profiles.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 12
sidebar_position: 13
title: "profiles"
---

Expand Down
Loading