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
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ brew install khanakia/tap/volt # or: curl release archive, or task instal
| `volt build <dir> --version vX.Y.Z` | cross-compile matrix → archives + `checksums.txt`; ldflags stamping verified in the produced binary |
| `volt release <dir> <version>` | tests → reserve tag → build → publish → **verify the published artifact**; `--bump patch\|minor\|major`, `--snapshot` (publish nothing), `--from-tag` (CI/recovery, idempotent) |
| `volt gen` | write workflow stubs + install scripts, hash-guarded: hand-edited files are refused with a diff, never clobbered |
| `volt gen install <dir>` | install scripts (`install.sh`, `install.ps1`) for the CLI in `<dir>`, for a repo whose root is not a single CLI; they find the newest release of that CLI's own tag stream (`<binary>/vX.Y.Z`) instead of the repo-global "latest" |
| `volt gen skills` | wire [`skillcmd`](./skillcmd) into a project: guarded wiring file + a one-time starter skill; releases then attach `skills_<version>.tar.gz` automatically |
| `volt doctor` | is this repo releasable? tools, auth, remote, version-pin drift |
| `volt update` | self-update from volt's own releases, checksum-verified |
Expand All @@ -44,6 +45,7 @@ Works identically on a single-CLI repo, a library repo, a monorepo of CLIs, and
```yaml
binary: mycli # default: the directory name
platforms: [darwin/arm64, linux/amd64, windows/amd64]
extra_binaries: [../mycli-plugin] # companion programs packed into the same archive and installed beside it
ldflags:
vars: # REPLACES the default stamp map
main.version: "{{.Version}}"
Expand Down
3 changes: 3 additions & 0 deletions apps/volt/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ volt release --from-tag notes/v1.4.0 # (re)publish an existing tag — CI /
# releases are the command above, or Run workflow with a tag
volt release ./cmd/notes --snapshot # build everything, publish nothing
volt gen # workflow stubs + install scripts, hash-guarded
volt gen install ./cmd/notes # install scripts for one CLI of a multi-binary repo (its own tag stream)
volt gen skills # skillcmd wiring + one-time starter skill (see voltkit/skillcmd)
volt doctor # is this repo releasable? (tools, auth, remote, pins)
volt cover --badge coverage.svg # coverage + self-contained README badge (--check for CI)
Expand All @@ -37,6 +38,8 @@ None required. An optional `.volt.yml` beside the built directory overrides what
binary: mycli # default: the directory name; also the CLI tag prefix (mycli/vX.Y.Z)
platforms: [darwin/arm64, darwin/amd64, linux/amd64, linux/arm64, windows/amd64]
extra_files: [README.md, LICENSE] # shipped inside each release archive
extra_binaries: [../mycli-plugin] # other `package main` dirs built and packed into the SAME archive,
# each named after its directory; install scripts install them too

ldflags:
strip: true # -s -w (default true; set false for debug symbols)
Expand Down
13 changes: 9 additions & 4 deletions apps/volt/changelog/changelog.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,19 +21,24 @@ const FileName = "CHANGELOG.md"
// pass "1.4.0" for tag v1.4.0). Resolution order:
//
// 1. the `## [1.4.0]` section of dir/CHANGELOG.md, if non-blank
// 2. a generated one-liner naming the tag and linking the changelog
// 2. a generated one-liner naming the tag and linking the changelog at
// changelogURL, the forge-built link to the file ("" omits the link)
//
// The blank check matters: a section heading followed only by whitespace must
// fall through — a run of blank lines is not release notes (hit for real in
// ubgo/buildinfo's awk version).
func Notes(dir, tag, bareVersion, repo string) string {
func Notes(dir, tag, bareVersion, changelogURL string) string {
if body := section(filepath.Join(dir, FileName), bareVersion); strings.TrimSpace(body) != "" {
return strings.TrimSpace(body) + "\n"
}
var b strings.Builder
fmt.Fprintf(&b, "Release `%s`.\n", tag)
if repo != "" {
fmt.Fprintf(&b, "\nSee [CHANGELOG.md](https://github.com/%s/blob/main/%s) for details.\n", repo, FileName)
if changelogURL != "" {
// The URL arrives whole from the forge. Wrapping it in a GitHub URL
// here, as this once did, published every fallback note with
// https://github.com/https://github.com/o/n/blob/main/CHANGELOG.md/blob/main/CHANGELOG.md
// and named a forge outside the forge package.
fmt.Fprintf(&b, "\nSee [%s](%s) for details.\n", FileName, changelogURL)
}
return b.String()
}
Expand Down
9 changes: 7 additions & 2 deletions apps/volt/changelog/changelog_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,13 @@ func TestNotesFallsBackWhenMissing(t *testing.T) {
if !strings.Contains(got, "Release `notes/v1.4.0`") {
t.Errorf("%s: fallback not used: %q", name, got)
}
if !strings.Contains(got, "CHANGELOG.md") {
t.Errorf("%s: fallback must link the changelog: %q", name, got)
// The exact link: a substring check passed while the URL was being
// wrapped inside a second one.
if want := "See [CHANGELOG.md](https://github.com/khanakia/notes/blob/main/CHANGELOG.md) for details."; !strings.Contains(got, want) {
t.Errorf("%s: fallback must link the changelog as %q: %q", name, want, got)
}
if strings.Count(got, "https://") != 1 {
t.Errorf("%s: the link must hold one URL: %q", name, got)
}
}
}
6 changes: 6 additions & 0 deletions apps/volt/forge/forge.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,12 @@ type Forge interface {
// branch — install scripts print it as their own "curl | sh" hint.
RawFileURL(repo Repo, path string) string

// CloneURL is the anonymous https clone URL. An install script for a
// CLI with a prefixed tag stream (notes/v1.2.0) resolves its newest
// release with `git ls-remote` against it, because "latest" is
// repo-global and may be another stream's release.
CloneURL(repo Repo) string

// CIFiles is this forge's generated CI file set (FG-D2) — rendered by
// `volt gen` through the shared hash-guard engine in genfiles.
CIFiles() []genfiles.File
Expand Down
1 change: 1 addition & 0 deletions apps/volt/forge/forge_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,7 @@ func TestAuxiliaryURLShapes(t *testing.T) {
gh.ArchiveTarballURL("o/n", "abc123"): "https://codeload.github.com/o/n/tar.gz/abc123",
gh.CloneURL("o/n"): "https://github.com/o/n.git",
GitLab{}.RawFileURL("o/n", "install.sh"): "https://gitlab.com/o/n/-/raw/main/install.sh",
GitLab{}.CloneURL("group/sub/n"): "https://gitlab.com/group/sub/n.git",
} {
if got != want {
t.Errorf("got %q, want %q", got, want)
Expand Down
5 changes: 5 additions & 0 deletions apps/volt/forge/gitlab.go
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,11 @@ func (GitLab) RawFileURL(repo Repo, path string) string {
return fmt.Sprintf("https://gitlab.com/%s/-/raw/main/%s", repo, path)
}

// CloneURL implements Forge.
func (GitLab) CloneURL(repo Repo) string {
return fmt.Sprintf("https://gitlab.com/%s.git", repo)
}

// CIFiles implements Forge — one .gitlab-ci.yml (FG-D2).
func (GitLab) CIFiles() []genfiles.File { return genfiles.GitLabCI }

Expand Down
5 changes: 3 additions & 2 deletions apps/volt/forge_helpers.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,9 @@ func forgeVars(f forge.Forge, repo forge.Repo, binary string) genfiles.Vars {
Repo: repo.String(),
Binary: binary,
Version: voltVersion,
DownloadBase: trim(f.AssetURL(repo, "${VERSION}", "")),
DownloadBasePS: trim(f.AssetURL(repo, "$Version", "")),
DownloadBase: trim(f.AssetURL(repo, "${TAG}", "")),
DownloadBasePS: trim(f.AssetURL(repo, "$Tag", "")),
CloneURL: f.CloneURL(repo),
LatestBase: latest,
RawScriptURL: f.RawFileURL(repo, "install.sh"),
RawScriptURLPS: f.RawFileURL(repo, "install.ps1"),
Expand Down
172 changes: 133 additions & 39 deletions apps/volt/gen_cmd.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ package main

import (
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
Expand All @@ -29,18 +28,21 @@ var (
func newGenCommand() *cobra.Command {
var force bool
cmd := &cobra.Command{
Use: "gen [skills]",
Use: "gen [skills | install <dir>]",
Short: "Write generated files: workflow stubs, install scripts — or the skills wiring",
Long: `Every file carries a "DO NOT EDIT" header with a body hash. Regeneration
refuses to overwrite a hand-edited file (and prints the diff); --force
overwrites. Files volt never touches: CHANGELOG.md, README.md, .volt.yml.

volt gen the standard set: workflow stubs + install scripts
volt gen skills the skillcmd wiring file, plus a one-time starter skill
when skills/ does not exist yet (SKILLCMD_SPEC)`,
Args: cobra.MaximumNArgs(1),
volt gen the standard set: workflow stubs + install scripts
volt gen skills the skillcmd wiring file, plus a one-time starter skill
when skills/ does not exist yet (SKILLCMD_SPEC)
volt gen install <dir> install.sh + install.ps1 at the repo root for the CLI
in <dir> — for a repo whose root is not a single CLI
(several binaries, or a library with a CLI beside it);
the scripts resolve that CLI's own tag stream`,
Args: cobra.MaximumNArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
out := cmd.OutOrStdout()
cfg, err := voltcfg.Load(".")
if err != nil {
return err
Expand All @@ -56,8 +58,14 @@ overwrites. Files volt never touches: CHANGELOG.md, README.md, .volt.yml.
if len(args) == 1 && args[0] == "skills" {
return genSkills(cmd, cfg, f, repo, force)
}
if len(args) == 1 {
return fmt.Errorf(`unknown gen target %q — only "skills" exists`, args[0])
if len(args) >= 1 && args[0] == "install" {
if len(args) != 2 {
return fmt.Errorf("volt gen install needs the CLI's directory, e.g. volt gen install ./cmd/notes")
}
return genInstall(cmd, f, repo, args[1], force)
}
if len(args) >= 1 {
return fmt.Errorf(`unknown gen target %q — "skills" and "install <dir>" exist`, args[0])
}
// Root kind decides whether the install scripts apply: they
// install THE binary of a single-CLI repo. A library root or a
Expand All @@ -67,28 +75,10 @@ overwrites. Files volt never touches: CHANGELOG.md, README.md, .volt.yml.
rootIsCLI = true
}
v := forgeVars(f, forge.Repo(repo), cfg.Binary)
refused := 0
// The forge decides WHICH CI files exist (FG-D2); install
// scripts are forge-shared with forge-shaped URLs inside.
files := append(append([]genfiles.File{}, f.CIFiles()...), genfiles.InstallScripts...)
for _, gf := range files {
if gf.CLIOnly && !rootIsCLI {
_, _ = fmt.Fprintf(out, "skipped %s — repo root is not a single CLI (install scripts need one binary to install)\n", gf.RelPath)
continue
}
res, err := genfiles.Generate(".", gf, v, force)
if err != nil {
return err
}
switch res.Outcome {
case genfiles.Written:
_, _ = fmt.Fprintf(out, "wrote %s\n", gf.RelPath)
case genfiles.Unchanged:
_, _ = fmt.Fprintf(out, "unchanged %s\n", gf.RelPath)
case genfiles.Refused:
refused++
_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "REFUSED %s — hand-edited; --force to overwrite\n%s", gf.RelPath, res.Diff)
}
v.ExtraBinaries = extraBinaryNames(".", cfg)
refused, err := writeGenerated(cmd, append(append([]genfiles.File{}, f.CIFiles()...), genfiles.InstallScripts...), v, rootIsCLI, force)
if err != nil {
return err
}
if refused > 0 {
return fmt.Errorf("%d file(s) refused — review the diffs above", refused)
Expand All @@ -100,6 +90,89 @@ overwrites. Files volt never touches: CHANGELOG.md, README.md, .volt.yml.
return cmd
}

// writeGenerated renders files through the hash guard and reports each
// outcome; CLIOnly files are skipped, loudly, unless includeCLIOnly.
// It returns how many files were refused as hand-edited.
func writeGenerated(cmd *cobra.Command, files []genfiles.File, v genfiles.Vars, includeCLIOnly, force bool) (int, error) {
out := cmd.OutOrStdout()
refused := 0
for _, gf := range files {
if gf.CLIOnly && !includeCLIOnly {
_, _ = fmt.Fprintf(out, "skipped %s — repo root is not a single CLI (install scripts need one binary to install); for a CLI in a subdirectory: volt gen install <dir>\n", gf.RelPath)
continue
}
res, err := genfiles.Generate(".", gf, v, force)
if err != nil {
return refused, err
}
switch res.Outcome {
case genfiles.Written:
_, _ = fmt.Fprintf(out, "wrote %s\n", gf.RelPath)
case genfiles.Unchanged:
_, _ = fmt.Fprintf(out, "unchanged %s\n", gf.RelPath)
case genfiles.Refused:
refused++
_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "REFUSED %s — hand-edited; --force to overwrite\n%s", gf.RelPath, res.Diff)
}
}
return refused, nil
}

// extraBinaryNames resolves .volt.yml's extra_binaries, given relative to the
// released directory, to the names the build gives them: each directory's own
// base name, exactly as gobuild names the archive entries.
func extraBinaryNames(dir string, cfg voltcfg.Config) []string {
var names []string
for _, rel := range cfg.ExtraBinaries {
abs, err := filepath.Abs(filepath.Join(dir, rel))
if err != nil {
continue
}
names = append(names, filepath.Base(abs))
}
return names
}

// genInstall implements `volt gen install <dir>`: the install scripts for the
// CLI in dir, written at the repo root. The scripts carry that CLI's tag
// prefix (rule one, via relname.Compose — the same composer release uses), so
// they find its newest release in its own stream rather than trusting the
// repo-global "latest", which in a multi-stream repo is whichever stream
// released last.
func genInstall(cmd *cobra.Command, f forge.Forge, repo, dir string, force bool) error {
kind, err := detect.Dir(dir)
if err != nil {
return err
}
if kind != detect.KindCLI {
return fmt.Errorf("%s is not a CLI (no package main): install scripts install a binary", dir)
}
cfg, err := voltcfg.Load(dir)
if err != nil {
return err
}
rel, err := repoRel(dir)
if err != nil {
return err
}
prefix, err := tagPrefixFor(kind, rel, cfg.Binary)
if err != nil {
return err
}
v := forgeVars(f, forge.Repo(repo), cfg.Binary)
v.TagPrefix = prefix
v.ExtraBinaries = extraBinaryNames(dir, cfg)
v.Regenerate = "volt gen install " + filepath.ToSlash(rel)
refused, err := writeGenerated(cmd, genfiles.InstallScripts, v, true, force)
if err != nil {
return err
}
if refused > 0 {
return fmt.Errorf("%d file(s) refused — review the diffs above", refused)
}
return nil
}

// genSkills implements `volt gen skills`: the guarded wiring file, the
// one-time starter skill, and the module dependency (SKILLCMD_SPEC).
func genSkills(cmd *cobra.Command, cfg voltcfg.Config, f forge.Forge, repo string, force bool) error {
Expand Down Expand Up @@ -165,23 +238,44 @@ wire it in (one of):
// version, then stripping it. cwd at the repo root ⇒ "" (bare tags);
// a CLI subdir ⇒ "<binary>/"; a library subdir ⇒ "<path>/".
func tagPrefix(kind detect.Kind, binary string) (string, error) {
rel, err := repoRel(".")
if err != nil {
return "", err
}
return tagPrefixFor(kind, rel, binary)
}

// repoRel returns dir relative to the repository's top level.
func repoRel(dir string) (string, error) {
top, err := exec.Command("git", "rev-parse", "--show-toplevel").Output()
if err != nil {
return "", fmt.Errorf("not inside a git repository: %w", err)
}
cwd, err := os.Getwd()
abs, err := filepath.Abs(dir)
if err != nil {
return "", err
}
rel, err := filepath.Rel(strings.TrimSpace(string(top)), cwd)
root := strings.TrimSpace(string(top))
// Resolve symlinks on both sides: git reports the physical top level, and
// a path through a symlinked parent would otherwise leave the tree.
if r, err := filepath.EvalSymlinks(root); err == nil {
root = r
}
if a, err := filepath.EvalSymlinks(abs); err == nil {
abs = a
}
rel, err := filepath.Rel(root, abs)
if err != nil {
// Symlinked paths can defeat Rel; resolve both sides and retry.
rt, _ := filepath.EvalSymlinks(strings.TrimSpace(string(top)))
rc, _ := filepath.EvalSymlinks(cwd)
if rel, err = filepath.Rel(rt, rc); err != nil {
return "", err
}
return "", err
}
if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
return "", fmt.Errorf("%s is outside the repository", dir)
}
return rel, nil
}

// tagPrefixFor is tagPrefix for a directory given relative to the repo root.
func tagPrefixFor(kind detect.Kind, rel, binary string) (string, error) {
const probe = "v0.0.0" // any valid version; only the prefix survives
tag, err := relname.Compose(kind, rel, binary, probe)
if err != nil {
Expand Down
Loading
Loading