Skip to content
Merged
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
7 changes: 7 additions & 0 deletions .ai/skills/new-command.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,13 @@ _, _ = fmt.Fprint(ioStreams.Out, content)

The pager auto-detects: prints directly if content fits terminal, otherwise shows scrollable viewport.

### 13. Command Reference Text

`docs/commands.md` and `docs/reference/` are generated from `Use`/`Short`/`Long`/`Example` and flags, and the
release job regenerates and commits them, so the published docs match the released binary. Put user-facing text
in the command definition and leave the generated files out of your PR; `TestRun` in `cmd/gen-docs` checks the
generator on every `make test`.

## Dependencies

- `cmdutil "github/verda-cloud/verda-cli/internal/verda-cli/cmd/util"` -- Factory, IOStreams, DebugJSON, helpers
Expand Down
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
docs/commands.md linguist-generated=true
docs/reference/** linguist-generated=true
15 changes: 11 additions & 4 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,16 +56,23 @@ jobs:
# which is the bug this fixes. --tag labels the unreleased section with VERSION.
git-cliff --unreleased --tag ${{ github.event.inputs.version }} --strip header -o RELEASE_NOTES.md

- name: Commit changelog and tag release
# Before the commit/tag step: the tag must carry docs that match its code,
# and a generator failure must stop the release before anything is pushed.
- name: Generate command docs
run: make docs VERSION=${{ github.event.inputs.version }}

- name: Commit changelog and docs, tag release
run: |
VERSION="${{ github.event.inputs.version }}"
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git remote set-url origin https://x-access-token:${{ secrets.RELEASE_TOKEN }}@github.com/${{ github.repository }}
git add CHANGELOG.md
# [skip ci]: the changelog already reflects this release; no need to
git add CHANGELOG.md docs/commands.md
# -A: pages of removed commands are deleted, not left behind.
git add -A docs/reference
# [skip ci]: changelog and docs already reflect this release; no need to
# re-trigger the Update Changelog workflow on this push.
git commit -m "chore(release): update changelog for ${VERSION} [skip ci]"
git commit -m "chore(release): update changelog and command docs for ${VERSION} [skip ci]"
git tag "${VERSION}"
git push origin main --tags

Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ Skipping these steps leads to pattern violations, broken dual-mode, and pricing
- [ ] `make lint` passes with zero issues (do not rely on pre-commit to surface these)
- [ ] `make test` passes (unit tests with -race; lint is the separate `make lint` item above)
- [ ] `make fix.check` passes (run `make fix` to apply pending `go fix` modernizations)
- [ ] `docs/commands.md` and `docs/reference/` unchanged in the diff (the release job regenerates them; user-facing text lives in the command's `Short`/`Long`/`Example`)
- [ ] `--help` renders correctly for changed commands
- [ ] Interactive and non-interactive modes both work
- [ ] Interactive Selects pass `tui.WithShowHints(true)` so the hint bar renders
Expand Down
3 changes: 3 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ make build # Build binary to ./bin/verda
make test # Run all tests (go test -race)
make lint # Lint only (golangci-lint); also run by pre-commit hooks
make fix # Apply go fix modernizers; CI runs `make fix.check`
make docs VERSION=vX.Y.Z # Release job only: generates docs/commands.md + docs/reference/ for that version
make pre-commit # Full pre-commit suite
```

Expand All @@ -20,13 +21,15 @@ Never use raw `go test ./...` — always `make test` (go test -race). Lint is se

```
cmd/verda/ # Entrypoint
cmd/gen-docs/ # `make docs`: writes docs/commands.md + docs/reference/ (release-owned output)
internal/verda-cli/
cmd/cmd.go # Root command, command groups
cmd/util/ # Factory, IOStreams, helpers, pricing, hostname
cmd/<domain>/ # One dir per domain (see per-command docs below)
CLAUDE.md # Domain knowledge, gotchas, edge cases
README.md # Usage examples, flags, architecture notes
options/ # Global CLI options, credentials
docgen/ # Renders the command reference from the cobra tree
internal/skills/ # Embedded AI skill files (go:embed)
pkg/ # In-tree TUI core, log, version (formerly verdagostack)
```
Expand Down
8 changes: 7 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ GOLANGCI_LINT := GOTOOLCHAIN=go$(GO_VERSION) go run github.com/golangci/golangci
# Toolchain pinned because each Go release adds or removes fixers; the integration tag brings tests/integration into scope.
GOFIX := GOTOOLCHAIN=go$(GO_VERSION) go fix -tags=integration

.PHONY: all build clean run.sandbox lint lint.fix security fix fix.check test test.integration test-s3-integration fmt changelog changelog.unreleased hooks.install pre-commit help
.PHONY: all build clean run.sandbox lint lint.fix security fix fix.check docs test test.integration test-s3-integration fmt changelog changelog.unreleased hooks.install pre-commit help

## Build -------------------------------------------------------------------

Expand Down Expand Up @@ -75,6 +75,12 @@ endif
changelog.unreleased: ## Regenerate CHANGELOG.md with pending commits under [Unreleased]
@git-cliff -o CHANGELOG.md

docs: ## Generate docs/commands.md and docs/reference/ for a release (requires VERSION, e.g. make docs VERSION=v1.0.0)
ifndef VERSION
$(error VERSION is required. Usage: make docs VERSION=v1.0.0)
endif
@go run ./cmd/gen-docs -version $(VERSION)

## Git Hooks ---------------------------------------------------------------

hooks.install: ## Configure git to use githooks/ as the hooks directory
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,9 @@ Multiple profiles are supported — switch with `verda auth use PROFILE`.

| Doc | Description |
|-----|-------------|
| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples |
| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples (regenerated at each release) |
| [Authentication](docs/guides/authentication.md) | Credential resolution order and environment variables |
| [Scripting and Agent Mode](docs/guides/scripting.md) | Structured output, `--wait`, and `--agent` mode |
| [Agent Error Format](docs/agent-errors.md) | Structured error specification for `--agent` mode |

## Contributing
Expand Down
86 changes: 86 additions & 0 deletions cmd/gen-docs/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
// Copyright 2026 Verda Cloud Oy
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Command gen-docs writes docs/commands.md and docs/reference/ from the verda
// command tree. The release job runs it via `make docs VERSION=vX.Y.Z`.
package main

import (
"bytes"
"flag"
"fmt"
"maps"
"os"
"path/filepath"
"slices"
"strings"

"github.com/verda-cloud/verda-cli/internal/verda-cli/cmd"
cmdutil "github.com/verda-cloud/verda-cli/internal/verda-cli/cmd/util"
"github.com/verda-cloud/verda-cli/internal/verda-cli/docgen"
)

func main() {
version := flag.String("version", "", "Release the docs describe, e.g. v1.2.3 (required)")
flag.Parse()
if err := run("docs", *version); err != nil {
fmt.Fprintln(os.Stderr, "gen-docs:", err)
os.Exit(1)
}
}

func run(out, version string) error {
cleanup, err := isolateEnv()
if err != nil {
return err
}
defer cleanup()
var discard bytes.Buffer
root, _ := cmd.NewRootCommand(cmdutil.IOStreams{In: &bytes.Buffer{}, Out: &discard, ErrOut: &discard})
files, err := docgen.Generate(root, version)
if err != nil {
return err
}
// Stale pages of removed commands must not survive a regeneration.
if err := os.RemoveAll(filepath.Join(out, docgen.ReferenceDir)); err != nil {
return err
}
for _, name := range slices.Sorted(maps.Keys(files)) {
path := filepath.Join(out, filepath.FromSlash(name))
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { //nolint:gosec // committed public docs
return err
}
if err := os.WriteFile(path, files[name], 0o644); err != nil { //nolint:gosec // committed public docs
return err
}
}
return nil
}

// isolateEnv: no inherited VERDA_* (batchjob gate off) and a throwaway home, so building
// the tree can't touch a real config dir; TestRun catches any home-derived help text.
func isolateEnv() (cleanup func(), err error) {
for _, kv := range os.Environ() {
if name, _, _ := strings.Cut(kv, "="); strings.HasPrefix(name, "VERDA_") {
_ = os.Unsetenv(name)
}
}
home, err := os.MkdirTemp("", "verda-gen-docs-")
if err != nil {
return nil, err
}
_ = os.Setenv("HOME", home)
_ = os.Setenv("VERDA_HOME", filepath.Join(home, ".verda"))
return func() { _ = os.RemoveAll(home) }, nil
}
96 changes: 96 additions & 0 deletions cmd/gen-docs/main_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
// Copyright 2026 Verda Cloud Oy
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
"os"
"path/filepath"
"strings"
"testing"

"github.com/verda-cloud/verda-cli/internal/verda-cli/docgen"
)

// TestRun builds the docs from the real command tree, as the release job does, so a
// generator failure surfaces in CI rather than first in a release.
func TestRun(t *testing.T) {
// t.Setenv restores HOME and VERDA_HOME; other VERDA_* that isolateEnv unsets stay unset.
t.Setenv("HOME", t.TempDir())
t.Setenv("VERDA_HOME", t.TempDir())

first, second := t.TempDir(), t.TempDir()
for _, dir := range []string{first, second} {
if err := run(dir, "v1.2.3"); err != nil {
t.Fatalf("run: %v", err)
}
}

index := readFile(t, filepath.Join(first, docgen.IndexFile))
if !strings.Contains(index, "> Verda CLI **v1.2.3**") {
t.Errorf("commands.md does not name the release; got:\n%s", index)
}
readFile(t, filepath.Join(first, docgen.ReferenceDir, "vm.md"))

// Each run gets a fresh temp home, so any home-derived help text differs between runs.
for _, name := range listFiles(t, first) {
a, b := readFile(t, filepath.Join(first, name)), readFile(t, filepath.Join(second, name))
if a != b {
t.Errorf("%s differs between runs; help text must not depend on the environment", name)
}
}
}

func TestRun_RejectsBadVersion(t *testing.T) {
t.Setenv("HOME", t.TempDir())
t.Setenv("VERDA_HOME", t.TempDir())
out := t.TempDir()
for _, version := range []string{"", "latest"} {
if err := run(out, version); err == nil {
t.Errorf("run(%q) = nil, want an error", version)
}
}
if entries, _ := os.ReadDir(out); len(entries) > 0 {
t.Errorf("a rejected run must write nothing; got %d entries", len(entries))
}
}

func readFile(t *testing.T, path string) string {
t.Helper()
b, err := os.ReadFile(path) //nolint:gosec // test temp dir
if err != nil {
t.Fatal(err)
}
return string(b)
}

func listFiles(t *testing.T, root string) []string {
t.Helper()
var names []string
err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
if err != nil || d.IsDir() {
return err
}
rel, err := filepath.Rel(root, path)
names = append(names, rel)
return err
})
if err != nil {
t.Fatal(err)
}
if len(names) < 2 {
t.Fatalf("got %d generated files, want an index and reference pages", len(names))
}
return names
}
Loading
Loading