diff --git a/README.md b/README.md
index 805651f..3a58a53 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ brew install khanakia/tap/volt # or: curl release archive, or task instal
| `volt build
--version vX.Y.Z` | cross-compile matrix → archives + `checksums.txt`; ldflags stamping verified in the produced binary |
| `volt release ` | 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 ` | install scripts (`install.sh`, `install.ps1`) for the CLI in ``, for a repo whose root is not a single CLI; they find the newest release of that CLI's own tag stream (`/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_.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 |
@@ -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}}"
diff --git a/apps/volt/README.md b/apps/volt/README.md
index d097938..c4779e0 100644
--- a/apps/volt/README.md
+++ b/apps/volt/README.md
@@ -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)
@@ -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)
diff --git a/apps/volt/changelog/changelog.go b/apps/volt/changelog/changelog.go
index 8beae7d..89a4561 100644
--- a/apps/volt/changelog/changelog.go
+++ b/apps/volt/changelog/changelog.go
@@ -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()
}
diff --git a/apps/volt/changelog/changelog_test.go b/apps/volt/changelog/changelog_test.go
index d6d86e3..f1ef3b3 100644
--- a/apps/volt/changelog/changelog_test.go
+++ b/apps/volt/changelog/changelog_test.go
@@ -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)
}
}
}
diff --git a/apps/volt/forge/forge.go b/apps/volt/forge/forge.go
index 080bd5e..2cc10f8 100644
--- a/apps/volt/forge/forge.go
+++ b/apps/volt/forge/forge.go
@@ -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
diff --git a/apps/volt/forge/forge_test.go b/apps/volt/forge/forge_test.go
index a38cdc4..b10c78f 100644
--- a/apps/volt/forge/forge_test.go
+++ b/apps/volt/forge/forge_test.go
@@ -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)
diff --git a/apps/volt/forge/gitlab.go b/apps/volt/forge/gitlab.go
index 5932093..f3507e4 100644
--- a/apps/volt/forge/gitlab.go
+++ b/apps/volt/forge/gitlab.go
@@ -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 }
diff --git a/apps/volt/forge_helpers.go b/apps/volt/forge_helpers.go
index 23a3565..dae1588 100644
--- a/apps/volt/forge_helpers.go
+++ b/apps/volt/forge_helpers.go
@@ -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"),
diff --git a/apps/volt/gen_cmd.go b/apps/volt/gen_cmd.go
index 6194adb..b409ea8 100644
--- a/apps/volt/gen_cmd.go
+++ b/apps/volt/gen_cmd.go
@@ -4,7 +4,6 @@ package main
import (
"fmt"
- "os"
"os/exec"
"path/filepath"
"strings"
@@ -29,18 +28,21 @@ var (
func newGenCommand() *cobra.Command {
var force bool
cmd := &cobra.Command{
- Use: "gen [skills]",
+ Use: "gen [skills | install ]",
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 install.sh + install.ps1 at the repo root for the CLI
+ in — 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
@@ -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 " 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
@@ -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)
@@ -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 \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 `: 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 {
@@ -165,23 +238,44 @@ wire it in (one of):
// version, then stripping it. cwd at the repo root ⇒ "" (bare tags);
// a CLI subdir ⇒ "/"; a library subdir ⇒ "/".
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 {
diff --git a/apps/volt/gen_cmd_test.go b/apps/volt/gen_cmd_test.go
index 88647da..b59d84e 100644
--- a/apps/volt/gen_cmd_test.go
+++ b/apps/volt/gen_cmd_test.go
@@ -1,12 +1,15 @@
package main
import (
+ "bytes"
"os"
"os/exec"
"path/filepath"
+ "strings"
"testing"
"github.com/khanakia/voltkit/apps/volt/detect"
+ "github.com/khanakia/voltkit/apps/volt/forge"
)
// tagPrefix must mirror relname.Compose exactly — rule one's shapes. The
@@ -57,3 +60,89 @@ func TestTagPrefixMirrorsRuleOne(t *testing.T) {
})
}
}
+
+// TestGenInstallForSubdirCLI pins `volt gen install `: a repo whose root
+// is not a single CLI gets install scripts for the CLI in dir, carrying that
+// CLI's tag prefix (rule one, as release composes it) and a header naming the
+// command that regenerates them. A library directory, a directory outside the
+// repository, and a missing are refused rather than guessed at.
+func TestGenInstallForSubdirCLI(t *testing.T) {
+ root := t.TempDir()
+ for _, c := range [][]string{{"git", "-C", root, "init", "-q"}} {
+ if out, err := exec.Command(c[0], c[1:]...).CombinedOutput(); err != nil {
+ t.Fatalf("%v: %v\n%s", c, err, out)
+ }
+ }
+ files := map[string]string{
+ "go.mod": "module example.com/m\n\ngo 1.22\n",
+ "lib.go": "package m\n",
+ "cmd/notes/main.go": "package main\n\nfunc main() {}\n",
+ "cmd/notes/.volt.yml": "extra_binaries: [../notes-sync]\n",
+ "cmd/notes-sync/main.go": "package main\n\nfunc main() {}\n",
+ "pkg/textutil/textutil.go": "package textutil\n",
+ }
+ for p, body := range files {
+ full := filepath.Join(root, filepath.FromSlash(p))
+ if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(full, []byte(body), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ }
+ orig, err := os.Getwd()
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = os.Chdir(orig) })
+ if err := os.Chdir(root); err != nil {
+ t.Fatal(err)
+ }
+ cmd := newGenCommand()
+ var out bytes.Buffer
+ cmd.SetOut(&out)
+ cmd.SetErr(&out)
+
+ if err := genInstall(cmd, forge.GitHub{}, "o/n", "./cmd/notes", false); err != nil {
+ t.Fatalf("gen install: %v\n%s", err, out.String())
+ }
+ sh, err := os.ReadFile(filepath.Join(root, "install.sh"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, want := range []string{
+ `TAG_PREFIX="notes/"`,
+ `BINARY="notes"`,
+ `EXTRA_BINARIES="notes-sync"`,
+ "https://github.com/o/n.git",
+ "https://github.com/o/n/releases/download/${TAG}",
+ "# Regenerate: volt gen install cmd/notes\n",
+ } {
+ if !strings.Contains(string(sh), want) {
+ t.Errorf("install.sh lacks %q", want)
+ }
+ }
+ ps, err := os.ReadFile(filepath.Join(root, "install.ps1"))
+ if err != nil || !strings.Contains(string(ps), `$TagPrefix = "notes/"`) || !strings.Contains(string(ps), `"notes-sync" -split " "`) {
+ t.Errorf("install.ps1 = %v, lacks the tag prefix", err)
+ }
+ // Regenerating unchanged is quiet and allowed.
+ out.Reset()
+ if err := genInstall(cmd, forge.GitHub{}, "o/n", "cmd/notes", false); err != nil || !strings.Contains(out.String(), "unchanged install.sh") {
+ t.Errorf("regenerate = %v\n%s", err, out.String())
+ }
+
+ if err := genInstall(cmd, forge.GitHub{}, "o/n", "pkg/textutil", false); err == nil || !strings.Contains(err.Error(), "not a CLI") {
+ t.Errorf("a library dir must be refused: %v", err)
+ }
+ outside := t.TempDir()
+ if err := os.WriteFile(filepath.Join(outside, "go.mod"), []byte("module x\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(outside, "main.go"), []byte("package main\n\nfunc main() {}\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if err := genInstall(cmd, forge.GitHub{}, "o/n", outside, false); err == nil || !strings.Contains(err.Error(), "outside the repository") {
+ t.Errorf("a dir outside the repository must be refused: %v", err)
+ }
+}
diff --git a/apps/volt/genfiles/genfiles.go b/apps/volt/genfiles/genfiles.go
index d266f9b..02112b2 100644
--- a/apps/volt/genfiles/genfiles.go
+++ b/apps/volt/genfiles/genfiles.go
@@ -70,10 +70,10 @@ var GitLabCI = []File{
// because the download URL bases arrive as template variables (FG-D4)
// rendered through the forge's URL shapes at gen time.
//
-// CLIOnly: install scripts install A binary from the repo root's release. A
-// library has no binary, and a multi-CLI monorepo has no single one —
-// "latest" is repo-wide, so it is whichever CLI released last. Both cases
-// skip these files, loudly.
+// CLIOnly: plain `volt gen` writes install scripts only when the repo root
+// is a single CLI; a library has no binary and a multi-CLI repo has no
+// single one, so both skip, loudly. `volt gen install ` writes them for
+// the CLI in instead, resolving that CLI's own tag stream (TagPrefix).
var InstallScripts = []File{
{RelPath: "install.sh", Template: "install.sh", Comment: "#", CLIOnly: true},
{RelPath: "install.ps1", Template: "install.ps1", Comment: "#", CLIOnly: true},
@@ -85,15 +85,31 @@ type Vars struct {
Repo string // "owner/name" (may nest on GitLab: group/sub/proj)
Binary string
Version string // volt's own version, recorded in the header
- // DownloadBase is the versioned download URL base with a literal
- // ${VERSION} the SCRIPT expands at run time, no trailing slash — e.g.
- // "https://github.com/o/n/releases/download/${VERSION}".
+ // DownloadBase is the versioned download URL base with a literal ${TAG}
+ // the SCRIPT expands at run time, no trailing slash — e.g.
+ // "https://github.com/o/n/releases/download/${TAG}". TAG is the release
+ // tag: TagPrefix followed by the version.
DownloadBase string
+ // TagPrefix is the release-tag prefix of the CLI's stream: "" for a
+ // root CLI (tags bare, v1.2.0), "/" for a CLI in a subdirectory
+ // (notes/v1.2.0) — relname's rule one. With a prefix, "latest" is
+ // useless (it is repo-global, any stream), so the script resolves the
+ // newest tag of its own stream with `git ls-remote` against CloneURL.
+ TagPrefix string
+ // CloneURL is the anonymous clone URL the script lists tags from.
+ CloneURL string
+ // ExtraBinaries are the companion programs shipped in the same archive
+ // as Binary (.volt.yml extra_binaries, by name); the scripts install
+ // them beside it.
+ ExtraBinaries []string
+ // Regenerate is the command recorded in the header as the way to
+ // regenerate the file; "" means "volt gen".
+ Regenerate string
// LatestBase is the latest-release download base, no trailing slash;
// "" when the forge has no latest redirect — the script then requires
// an explicit version, loudly.
LatestBase string
- // DownloadBasePS mirrors DownloadBase with PowerShell's $Version
+ // DownloadBasePS mirrors DownloadBase with PowerShell's $Tag
// variable syntax — the two scripts interpolate differently, so each
// gets its own literal.
DownloadBasePS string
@@ -209,7 +225,11 @@ func render(f File, v Vars, extras map[string]string) ([]byte, error) {
}
fmt.Fprintf(&out, "%s Code generated by volt %s — DO NOT EDIT.\n", c, v.Version)
fmt.Fprintf(&out, "%s\n", c)
- fmt.Fprintf(&out, "%s Regenerate: volt gen\n", c)
+ regen := v.Regenerate
+ if regen == "" {
+ regen = "volt gen"
+ }
+ fmt.Fprintf(&out, "%s Regenerate: %s\n", c, regen)
fmt.Fprintf(&out, "%s To change: edit .volt.yml, or the template in volt itself — edits here are lost.\n", c)
sum := sha256.Sum256(rest)
fmt.Fprintf(&out, "%s %s%x\n", c, hashMarker, sum[:hashLen/2])
@@ -225,6 +245,8 @@ func renderBytes(text string, v Vars, extras map[string]string) ([]byte, error)
"DownloadBase": v.DownloadBase, "DownloadBasePS": v.DownloadBasePS,
"LatestBase": v.LatestBase, "RawScriptURL": v.RawScriptURL,
"RawScriptURLPS": v.RawScriptURLPS,
+ "TagPrefix": v.TagPrefix, "CloneURL": v.CloneURL,
+ "ExtraBinaries": strings.Join(v.ExtraBinaries, " "),
}
for k, val := range extras {
data[k] = val
diff --git a/apps/volt/genfiles/install_script_test.go b/apps/volt/genfiles/install_script_test.go
new file mode 100644
index 0000000..434243f
--- /dev/null
+++ b/apps/volt/genfiles/install_script_test.go
@@ -0,0 +1,254 @@
+package genfiles
+
+import (
+ "crypto/sha256"
+ "fmt"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "runtime"
+ "strings"
+ "testing"
+)
+
+// installFixture is a fake release server: a local git repository carrying
+// tags from several streams (the source `git ls-remote` reads), and a
+// directory per tag holding the archive and checksums.txt the way a volt
+// release publishes them, served to the script as file://.
+type installFixture struct {
+ repo, rel string
+ os, arch string
+}
+
+func newInstallFixture(t *testing.T) installFixture {
+ t.Helper()
+ for _, tool := range []string{"sh", "git", "tar", "curl"} {
+ if _, err := exec.LookPath(tool); err != nil {
+ t.Skipf("%s not on PATH", tool)
+ }
+ }
+ if runtime.GOOS == "windows" {
+ t.Skip("install.sh is the macOS/Linux installer")
+ }
+ root := t.TempDir()
+ fx := installFixture{repo: filepath.Join(root, "repo"), rel: filepath.Join(root, "rel"), os: runtime.GOOS, arch: runtime.GOARCH}
+ run := func(dir string, args ...string) {
+ t.Helper()
+ c := exec.Command(args[0], args[1:]...)
+ c.Dir = dir
+ if out, err := c.CombinedOutput(); err != nil {
+ t.Fatalf("%v: %v\n%s", args, err, out)
+ }
+ }
+ if err := os.MkdirAll(fx.repo, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ run(fx.repo, "git", "init", "-q")
+ run(fx.repo, "git", "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "x")
+ // notes/v0.10.0 must beat notes/v0.9.0 (numeric, not lexical); the other
+ // streams' tags are newer and must be ignored.
+ for _, tag := range []string{"notes/v0.2.0", "notes/v0.9.0", "notes/v0.10.0", "other/v9.0.0", "v5.0.0", "notes/v1.0.0-rc.1"} {
+ run(fx.repo, "git", "tag", tag)
+ }
+ for _, tag := range []string{"notes/v0.2.0", "notes/v0.10.0", "v5.0.0"} {
+ fx.publish(t, tag, true)
+ }
+ return fx
+}
+
+// publish lays out one release: the archive for this machine (when withAsset)
+// and checksums.txt listing it.
+func (fx installFixture) publish(t *testing.T, tag string, withAsset bool) {
+ t.Helper()
+ version := tag[strings.LastIndex(tag, "/")+1:]
+ dir := filepath.Join(fx.rel, filepath.FromSlash(tag))
+ pkg := filepath.Join(dir, "pkg")
+ if err := os.MkdirAll(pkg, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ bin := "notes"
+ if !strings.HasPrefix(tag, "notes/") {
+ bin = "root"
+ }
+ script := fmt.Sprintf("#!/bin/sh\necho %s %s\n", bin, tag)
+ if err := os.WriteFile(filepath.Join(pkg, "notes"), []byte(script), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ asset := fmt.Sprintf("notes_%s_%s_%s.tar.gz", version, fx.os, fx.arch)
+ if !withAsset {
+ asset = fmt.Sprintf("notes_%s_plan9_mips.tar.gz", version)
+ }
+ // A companion program in the same archive, as extra_binaries packs it.
+ if err := os.WriteFile(filepath.Join(pkg, "notes-sync"), []byte("#!/bin/sh\necho sync "+tag+"\n"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ c := exec.Command("tar", "czf", filepath.Join(dir, asset), "notes", "notes-sync")
+ c.Dir = pkg
+ if out, err := c.CombinedOutput(); err != nil {
+ t.Fatalf("tar: %v\n%s", err, out)
+ }
+ raw, err := os.ReadFile(filepath.Join(dir, asset))
+ if err != nil {
+ t.Fatal(err)
+ }
+ sum := sha256.Sum256(raw)
+ if err := os.WriteFile(filepath.Join(dir, "checksums.txt"), []byte(fmt.Sprintf("%x %s\n", sum, asset)), 0o644); err != nil {
+ t.Fatal(err)
+ }
+}
+
+// script generates install.sh for the fixture with the given tag prefix.
+func (fx installFixture) script(t *testing.T, prefix string, extras ...string) string {
+ t.Helper()
+ root := t.TempDir()
+ vars := Vars{
+ Repo: "o/n", Binary: "notes", Version: "v0.1.0",
+ DownloadBase: "file://" + fx.rel + "/${TAG}", LatestBase: "",
+ RawScriptURL: "https://example.invalid/install.sh", TagPrefix: prefix, CloneURL: fx.repo,
+ ExtraBinaries: extras,
+ }
+ if _, err := Generate(root, InstallScripts[0], vars, false); err != nil {
+ t.Fatal(err)
+ }
+ return filepath.Join(root, "install.sh")
+}
+
+func (fx installFixture) install(t *testing.T, script string, env ...string) (string, string, error) {
+ t.Helper()
+ dest := t.TempDir()
+ c := exec.Command("sh", script)
+ c.Env = append(append(os.Environ(), "INSTALL_DIR="+dest), env...)
+ out, err := c.CombinedOutput()
+ return dest, string(out), err
+}
+
+func installed(t *testing.T, dest string) string {
+ t.Helper()
+ out, err := exec.Command(filepath.Join(dest, "notes")).CombinedOutput()
+ if err != nil {
+ return "(not installed)"
+ }
+ return strings.TrimSpace(string(out))
+}
+
+// TestInstallShResolvesItsOwnTagStream pins the multi-stream fix: a CLI whose
+// tags carry a prefix installs the newest release of ITS stream -- compared
+// numerically, stable versions only -- never another stream's, and never the
+// repo-global "latest", which in such a repo is whichever stream released
+// last.
+func TestInstallShResolvesItsOwnTagStream(t *testing.T) {
+ fx := newInstallFixture(t)
+ s := fx.script(t, "notes/")
+ dest, out, err := fx.install(t, s)
+ if err != nil {
+ t.Fatalf("install: %v\n%s", err, out)
+ }
+ if got := installed(t, dest); got != "notes notes/v0.10.0" {
+ t.Errorf("installed %q, want the newest notes/ release (notes/v0.10.0)\n%s", got, out)
+ }
+ // A pinned version, with or without the stream prefix.
+ for _, pin := range []string{"v0.2.0", "notes/v0.2.0"} {
+ dest, out, err := fx.install(t, s, "VERSION="+pin)
+ if err != nil || installed(t, dest) != "notes notes/v0.2.0" {
+ t.Errorf("VERSION=%s: %v %q\n%s", pin, err, installed(t, dest), out)
+ }
+ }
+}
+
+// TestInstallShRootCLITagsBare keeps the single-CLI shape unchanged: no prefix,
+// the tag is the bare version.
+func TestInstallShRootCLITagsBare(t *testing.T) {
+ fx := newInstallFixture(t)
+ dest, out, err := fx.install(t, fx.script(t, ""), "VERSION=v5.0.0")
+ if err != nil || installed(t, dest) != "root v5.0.0" {
+ t.Errorf("root CLI: %v %q\n%s", err, installed(t, dest), out)
+ }
+}
+
+// TestInstallShRefusals pins what the installer must not do: install a
+// release that has no build for this machine (said plainly, not as a failed
+// download), install an archive whose checksum does not match, or guess when
+// no release of its stream exists.
+func TestInstallShRefusals(t *testing.T) {
+ fx := newInstallFixture(t)
+ s := fx.script(t, "notes/")
+
+ fx.publish(t, "notes/v0.9.0", false)
+ dest, out, err := fx.install(t, s, "VERSION=v0.9.0")
+ if err == nil || !strings.Contains(out, "has no "+fx.os+"/"+fx.arch+" build of notes") || installed(t, dest) != "(not installed)" {
+ t.Errorf("a release without this platform: %v\n%s", err, out)
+ }
+
+ asset := filepath.Join(fx.rel, "notes", "v0.2.0", fmt.Sprintf("notes_v0.2.0_%s_%s.tar.gz", fx.os, fx.arch))
+ f, err := os.OpenFile(asset, os.O_APPEND|os.O_WRONLY, 0)
+ if err != nil {
+ t.Fatal(err)
+ }
+ _, _ = f.WriteString("tampered")
+ _ = f.Close()
+ dest, out, err = fx.install(t, s, "VERSION=v0.2.0")
+ if err == nil || !strings.Contains(out, "checksum verification FAILED") || installed(t, dest) != "(not installed)" {
+ t.Errorf("a tampered archive: %v\n%s", err, out)
+ }
+
+ dest, out, err = fx.install(t, fx.script(t, "absent/"))
+ if err == nil || !strings.Contains(out, "no absent/v* release found") || installed(t, dest) != "(not installed)" {
+ t.Errorf("a stream with no release: %v\n%s", err, out)
+ }
+}
+
+// TestInstallHeaderNamesItsRegenerateCommand: a file from `volt gen install
+// ` must say so, or the next person runs plain `volt gen`, which skips
+// install scripts in such a repo, and concludes the file is orphaned.
+func TestInstallHeaderNamesItsRegenerateCommand(t *testing.T) {
+ root := t.TempDir()
+ vars := v
+ vars.Regenerate = "volt gen install cmd/notes"
+ if _, err := Generate(root, InstallScripts[0], vars, false); err != nil {
+ t.Fatal(err)
+ }
+ raw, _ := os.ReadFile(filepath.Join(root, "install.sh"))
+ if !strings.Contains(string(raw), "# Regenerate: volt gen install cmd/notes\n") {
+ t.Errorf("header does not name the command:\n%s", string(raw)[:300])
+ }
+ root = t.TempDir()
+ gen(t, root, InstallScripts[0], false)
+ raw, _ = os.ReadFile(filepath.Join(root, "install.sh"))
+ if !strings.Contains(string(raw), "# Regenerate: volt gen\n") {
+ t.Errorf("default header changed:\n%s", string(raw)[:300])
+ }
+}
+
+// TestInstallShInstallsCompanionBinaries pins extra_binaries on the install
+// side: the programs shipped beside the main binary land beside it, runnable,
+// and one the release does not carry is named and skipped rather than failing
+// an install of a release cut before the companion existed.
+func TestInstallShInstallsCompanionBinaries(t *testing.T) {
+ fx := newInstallFixture(t)
+ dest, out, err := fx.install(t, fx.script(t, "notes/", "notes-sync", "notes-absent"), "VERSION=v0.2.0")
+ if err != nil {
+ t.Fatalf("install: %v\n%s", err, out)
+ }
+ if got := installed(t, dest); got != "notes notes/v0.2.0" {
+ t.Errorf("main binary = %q", got)
+ }
+ sync, err := exec.Command(filepath.Join(dest, "notes-sync")).CombinedOutput()
+ if err != nil || strings.TrimSpace(string(sync)) != "sync notes/v0.2.0" {
+ t.Errorf("companion not installed or not runnable: %v %q\n%s", err, sync, out)
+ }
+ if !strings.Contains(out, "NOTE: notes-absent is not in release notes/v0.2.0; skipped.") {
+ t.Errorf("a companion the release lacks must be named:\n%s", out)
+ }
+ if !strings.Contains(out, "Installed notes notes-sync to ") {
+ t.Errorf("the summary must list what was installed:\n%s", out)
+ }
+ // With no companions configured, none are installed even if the archive
+ // happens to hold one.
+ dest, _, err = fx.install(t, fx.script(t, "notes/"), "VERSION=v0.2.0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if _, err := os.Stat(filepath.Join(dest, "notes-sync")); err == nil {
+ t.Error("an unconfigured companion was installed")
+ }
+}
diff --git a/apps/volt/genfiles/templates/install.ps1 b/apps/volt/genfiles/templates/install.ps1
index d1939c2..ea85e48 100644
--- a/apps/volt/genfiles/templates/install.ps1
+++ b/apps/volt/genfiles/templates/install.ps1
@@ -7,14 +7,30 @@ $ErrorActionPreference = "Stop"
$Repo = "[[.Repo]]"
$Binary = "[[.Binary]]"
+# Companion programs shipped in the same archive and installed beside it.
+$ExtraBinaries = "[[.ExtraBinaries]]" -split " " | Where-Object { $_ }
$InstallDir = if ($env:INSTALL_DIR) { $env:INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA $Binary }
$Version = if ($env:VERSION) { $env:VERSION } else { "" }
+# The release-tag prefix of this CLI's stream: empty for a root CLI (v1.2.0),
+# "/" for one in a subdirectory (/v1.2.0).
+$TagPrefix = "[[.TagPrefix]]"
$arch = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }
+if ($Version -and $TagPrefix -and $Version.StartsWith($TagPrefix)) { $Version = $Version.Substring($TagPrefix.Length) }
+if (-not $Version -and $TagPrefix) {
+ # "latest" is repo-global and may be another stream's release: list this
+ # stream's tags instead (git ls-remote has no API rate limit).
+ if (-not (Get-Command git -ErrorAction SilentlyContinue)) { Write-Error "git is needed to find the newest $Binary release - or set `$env:VERSION"; exit 1 }
+ $Version = git ls-remote --tags --refs "[[.CloneURL]]" "${TagPrefix}v*" |
+ ForEach-Object { ($_ -split "refs/tags/$TagPrefix")[1] } |
+ Where-Object { $_ -match '^v\d+\.\d+\.\d+$' } |
+ Sort-Object { [version]($_.Substring(1)) } | Select-Object -Last 1
+ if (-not $Version) { Write-Error "no ${TagPrefix}v* release found in $Repo - set `$env:VERSION"; exit 1 }
+}
# The redirect endpoint has no rate limit; the JSON API allows 60/hr/IP.
-if ($Version) { $base = "[[.DownloadBasePS]]" }
-else { $base = "[[.LatestBase]]" }
+if ($Version) { $Tag = "$TagPrefix$Version"; $base = "[[.DownloadBasePS]]" }
+else { $Tag = "latest"; $base = "[[.LatestBase]]" }
if (-not $base) { Write-Error "this forge has no 'latest' redirect - pass a version"; exit 1 }
$tmp = Join-Path $env:TEMP ([System.IO.Path]::GetRandomFileName())
@@ -22,7 +38,7 @@ New-Item -ItemType Directory -Path $tmp | Out-Null
try {
Invoke-WebRequest -Uri "$base/checksums.txt" -OutFile (Join-Path $tmp "checksums.txt")
$line = Get-Content (Join-Path $tmp "checksums.txt") | Where-Object { $_ -match "_windows_$arch\.zip$" } | Select-Object -First 1
- if (-not $line) { throw "no windows/$arch asset in this release of $Repo" }
+ if (-not $line) { throw "release $Tag of $Repo has no windows/$arch build of $Binary" }
$sum, $asset = $line -split "\s+", 2
$zip = Join-Path $tmp $asset
Write-Host "Downloading $asset..."
@@ -35,6 +51,11 @@ try {
Expand-Archive -Path $zip -DestinationPath $tmp -Force
New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
Copy-Item (Join-Path $tmp "$Binary.exe") (Join-Path $InstallDir "$Binary.exe") -Force
+ foreach ($extra in $ExtraBinaries) {
+ $src = Join-Path $tmp "$extra.exe"
+ if (Test-Path $src) { Copy-Item $src (Join-Path $InstallDir "$extra.exe") -Force }
+ else { Write-Host "NOTE: $extra is not in release $Tag; skipped." }
+ }
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$InstallDir*") {
diff --git a/apps/volt/genfiles/templates/install.sh b/apps/volt/genfiles/templates/install.sh
index 07618d3..2c65c6c 100644
--- a/apps/volt/genfiles/templates/install.sh
+++ b/apps/volt/genfiles/templates/install.sh
@@ -3,14 +3,21 @@
#
# Usage:
# curl -fsSL [[.RawScriptURL]] | sh
-# VERSION=v1.2.0 curl -fsSL ... | sh # pin a version
-# INSTALL_DIR=~/.local/bin curl -fsSL ... | sh # no sudo needed
+# curl -fsSL [[.RawScriptURL]] | VERSION=v1.2.0 sh # pin a version
+# curl -fsSL [[.RawScriptURL]] | INSTALL_DIR=$HOME/.local/bin sh # no sudo needed
set -eu
REPO="[[.Repo]]"
BINARY="[[.Binary]]"
+# Companion programs shipped in the same archive and installed beside
+# ${BINARY}; empty when there are none.
+EXTRA_BINARIES="[[.ExtraBinaries]]"
INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}"
VERSION="${VERSION:-}"
+# The release-tag prefix of this CLI's stream: empty when the CLI is the repo
+# root (tags v1.2.0), "/" when it lives in a subdirectory (tags
+# /v1.2.0). A VERSION given with the prefix is accepted too.
+TAG_PREFIX="[[.TagPrefix]]"
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
@@ -24,32 +31,52 @@ case "$OS" in
*) echo "Unsupported OS: $OS (use install.ps1 on Windows)" >&2; exit 1 ;;
esac
-# /releases/latest/download/ is a redirect with NO rate limit; the JSON API
-# is limited to 60 anonymous requests/hour/IP and would 403 on shared IPs.
if [ -n "$VERSION" ]; then
+ VERSION=${VERSION#"$TAG_PREFIX"}
+elif [ -n "$TAG_PREFIX" ]; then
+ # "latest" is repo-global: in a repo with several release streams it is
+ # whichever was published last, possibly one with no binaries. So list this
+ # stream's tags instead; git ls-remote has no API rate limit.
+ command -v git >/dev/null 2>&1 || { echo "git is needed to find the newest ${BINARY} release — or pass VERSION=vX.Y.Z" >&2; exit 1; }
+ VERSION=$(git ls-remote --tags --refs "[[.CloneURL]]" "${TAG_PREFIX}v*" 2>/dev/null \
+ | sed "s|.*refs/tags/${TAG_PREFIX}v||" | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' \
+ | sort -t. -k1,1n -k2,2n -k3,3n | tail -n1 | sed 's/^/v/')
+ [ -n "$VERSION" ] || { echo "no ${TAG_PREFIX}v* release found in ${REPO} — pass VERSION=vX.Y.Z" >&2; exit 1; }
+fi
+
+if [ -n "$VERSION" ]; then
+ TAG="${TAG_PREFIX}${VERSION}"
BASE="[[.DownloadBase]]"
else
+ # /releases/latest/download/ is a redirect with NO rate limit; the JSON API
+ # is limited to 60 anonymous requests/hour/IP and would 403 on shared IPs.
BASE="[[.LatestBase]]"
# A forge with no latest-release redirect renders this empty — then a
# version is required, loudly (FG-D4).
- [ -z "${BASE}" ] && { echo "this forge has no 'latest' redirect — pass a version: install.sh vX.Y.Z" >&2; exit 1; }
- VERSION="latest"
-fi
-# Asset names mirror volt's platform.AssetName — generated from the same
-# constants, so they cannot drift from what the build produced.
-ASSET="${BINARY}_${VERSION}_${OS}_${ARCH}.tar.gz"
-if [ "$VERSION" = "latest" ]; then
- # latest/download serves assets by exact name; we cannot know the version
- # half of the name, so fetch checksums.txt first and read it from there.
- ASSET=$(curl -fsSL "${BASE}/checksums.txt" | awk '{print $2}' | grep "_${OS}_${ARCH}\.tar\.gz$" | head -n1)
- [ -n "$ASSET" ] || { echo "no ${OS}/${ARCH} asset in the latest release of ${REPO}" >&2; exit 1; }
+ [ -z "${BASE}" ] && { echo "this forge has no 'latest' redirect — pass a version: VERSION=vX.Y.Z" >&2; exit 1; }
+ TAG="latest"
fi
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
-echo "Downloading ${ASSET} from ${REPO} (${VERSION})..."
+curl -fsSL -o "${tmp}/checksums.txt" "${BASE}/checksums.txt" || {
+ echo "no release ${TAG} of ${BINARY} in ${REPO} (could not fetch ${BASE}/checksums.txt)" >&2; exit 1; }
+
+# Asset names mirror volt's platform.AssetName — generated from the same
+# constants, so they cannot drift from what the build produced. The asset is
+# read from checksums.txt, which lists exactly what the release holds, so a
+# platform the release does not build is reported as such rather than as a
+# failed download.
+if [ "$TAG" = "latest" ]; then
+ ASSET=$(awk '{print $2}' "${tmp}/checksums.txt" | grep "_${OS}_${ARCH}\.tar\.gz$" | head -n1)
+else
+ ASSET="${BINARY}_${VERSION}_${OS}_${ARCH}.tar.gz"
+ awk '{print $2}' "${tmp}/checksums.txt" | grep -qx "$ASSET" || ASSET=""
+fi
+[ -n "$ASSET" ] || { echo "release ${TAG} of ${REPO} has no ${OS}/${ARCH} build of ${BINARY}" >&2; exit 1; }
+
+echo "Downloading ${ASSET} from ${REPO} (${TAG})..."
curl -fsSL -o "${tmp}/${ASSET}" "${BASE}/${ASSET}"
-curl -fsSL -o "${tmp}/checksums.txt" "${BASE}/checksums.txt"
# Verify BEFORE installing — never pipe an unverified binary into PATH.
# sha256sum is coreutils; stock macOS ships only shasum — support both.
@@ -67,20 +94,33 @@ tar xzf "${tmp}/${ASSET}" -C "$tmp"
if [ -x "${INSTALL_DIR}/${BINARY}" ]; then
echo "Replacing $("${INSTALL_DIR}/${BINARY}" --version 2>/dev/null || echo "existing install")"
fi
+mkdir -p "$INSTALL_DIR" 2>/dev/null || true
if [ -w "$INSTALL_DIR" ]; then
- mv "${tmp}/${BINARY}" "${INSTALL_DIR}/${BINARY}"
+ MV="mv"
elif command -v sudo >/dev/null 2>&1; then
- sudo mv "${tmp}/${BINARY}" "${INSTALL_DIR}/${BINARY}"
+ MV="sudo mv"
else
echo "${INSTALL_DIR} is not writable and sudo is unavailable." >&2
echo "Re-run with INSTALL_DIR set to a writable directory, e.g.:" >&2
- echo " INSTALL_DIR=\$HOME/.local/bin sh install.sh" >&2
+ echo " curl -fsSL [[.RawScriptURL]] | INSTALL_DIR=\$HOME/.local/bin sh" >&2
exit 1
fi
-chmod +x "${INSTALL_DIR}/${BINARY}"
+chmod +x "${tmp}/${BINARY}"
+$MV "${tmp}/${BINARY}" "${INSTALL_DIR}/${BINARY}"
+INSTALLED="${BINARY}"
+for extra in $EXTRA_BINARIES; do
+ # A release older than the companion may not carry it: say so, keep going.
+ if [ -f "${tmp}/${extra}" ]; then
+ chmod +x "${tmp}/${extra}"
+ $MV "${tmp}/${extra}" "${INSTALL_DIR}/${extra}"
+ INSTALLED="${INSTALLED} ${extra}"
+ else
+ echo "NOTE: ${extra} is not in release ${TAG}; skipped." >&2
+ fi
+done
case ":$PATH:" in
*":${INSTALL_DIR}:"*) ;;
*) echo "NOTE: ${INSTALL_DIR} is not on your PATH." >&2 ;;
esac
-echo "Installed ${BINARY} to ${INSTALL_DIR}/${BINARY}"
+echo "Installed ${INSTALLED} to ${INSTALL_DIR}"
diff --git a/apps/volt/gobuild/extra_binaries_test.go b/apps/volt/gobuild/extra_binaries_test.go
new file mode 100644
index 0000000..41497ef
--- /dev/null
+++ b/apps/volt/gobuild/extra_binaries_test.go
@@ -0,0 +1,120 @@
+package gobuild
+
+import (
+ "archive/tar"
+ "compress/gzip"
+ "io"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// scaffoldWithHelpers is scaffoldCLI plus companion programs and a library
+// package in subdirectories of the same module.
+func scaffoldWithHelpers(t *testing.T) string {
+ t.Helper()
+ dir := scaffoldCLI(t)
+ for rel, body := range map[string]string{
+ "plugins/notes-sync/main.go": "package main\n\nfunc main() { println(\"sync\") }\n",
+ "plugins/notes-gc/main.go": "package main\n\nfunc main() { println(\"gc\") }\n",
+ "other/notes-sync/main.go": "package main\n\nfunc main() {}\n",
+ "lib/lib.go": "package lib\n",
+ } {
+ full := filepath.Join(dir, filepath.FromSlash(rel))
+ if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(full, []byte(body), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ }
+ return dir
+}
+
+// tarEntries lists name -> mode for a .tar.gz.
+func tarEntries(t *testing.T, path string) map[string]os.FileMode {
+ t.Helper()
+ f, err := os.Open(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = f.Close() }()
+ gz, err := gzip.NewReader(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+ out := map[string]os.FileMode{}
+ tr := tar.NewReader(gz)
+ for {
+ h, err := tr.Next()
+ if err == io.EOF {
+ break
+ }
+ if err != nil {
+ t.Fatal(err)
+ }
+ out[h.Name] = h.FileInfo().Mode()
+ }
+ return out
+}
+
+// TestExtraBinariesShipInTheSameArchive pins extra_binaries: a tool's
+// companion programs are built for the platform and packed beside the main
+// binary, executable, so one download holds a set that cannot be mismatched.
+// Only the main binary's stamp is verified; a helper without the version
+// symbol is not a warning.
+func TestExtraBinariesShipInTheSameArchive(t *testing.T) {
+ if hostOS() == "windows" {
+ t.Skip("reads a .tar.gz; windows archives are .zip")
+ }
+ dir := scaffoldWithHelpers(t)
+ dist := t.TempDir()
+ cfg := hostCfg(dir)
+ cfg.ExtraBinaries = []string{"plugins/notes-sync", "./plugins/notes-gc/"}
+
+ res, err := Run(Options{Dir: dir, Version: "v0.1.0", DistDir: dist}, cfg)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(res.Warnings) != 0 {
+ t.Errorf("a helper without the stamp symbol must not warn: %v", res.Warnings)
+ }
+ got := tarEntries(t, filepath.Join(dist, res.Assets[0]))
+ for _, name := range []string{filepath.Base(dir), "notes-sync", "notes-gc"} {
+ mode, ok := got[name]
+ if !ok {
+ t.Errorf("archive lacks %s: %v", name, got)
+ continue
+ }
+ if mode&0o111 == 0 {
+ t.Errorf("%s is not executable in the archive: %v", name, mode)
+ }
+ }
+ if len(got) != 3 {
+ t.Errorf("archive entries = %v, want exactly the three binaries", got)
+ }
+}
+
+// TestExtraBinariesRefusals: a name that would collide in the archive, and a
+// directory that is not a program, fail the build rather than publish an
+// archive missing or overwriting a binary.
+func TestExtraBinariesRefusals(t *testing.T) {
+ dir := scaffoldWithHelpers(t)
+ for name, tc := range map[string]struct {
+ extras []string
+ want string
+ }{
+ "two extras with one name": {[]string{"plugins/notes-sync", "other/notes-sync"}, "already plugins/notes-sync"},
+ "an extra named as the main": {[]string{"."}, "already the main binary"},
+ "a library directory": {[]string{"lib"}, "not a program"},
+ "a directory that is absent": {[]string{"nope"}, "extra_binaries nope"},
+ } {
+ cfg := hostCfg(dir)
+ cfg.ExtraBinaries = tc.extras
+ _, err := Run(Options{Dir: dir, Version: "v0.1.0", DistDir: t.TempDir()}, cfg)
+ if err == nil || !strings.Contains(err.Error(), tc.want) {
+ t.Errorf("%s: err = %v, want it to mention %q", name, err, tc.want)
+ }
+ }
+}
diff --git a/apps/volt/gobuild/gobuild.go b/apps/volt/gobuild/gobuild.go
index 5aa378b..dc4520f 100644
--- a/apps/volt/gobuild/gobuild.go
+++ b/apps/volt/gobuild/gobuild.go
@@ -16,6 +16,7 @@ import (
"github.com/khanakia/voltkit/apps/volt/archive"
"github.com/khanakia/voltkit/apps/volt/buildmeta"
+ "github.com/khanakia/voltkit/apps/volt/detect"
"github.com/khanakia/voltkit/apps/volt/platform"
"github.com/khanakia/voltkit/apps/volt/voltcfg"
)
@@ -151,8 +152,9 @@ func buildOne(opts Options, cfg voltcfg.Config, vars buildmeta.Vars, p platform.
}
binName := cfg.Binary + p.ExeSuffix()
- outPath := filepath.Join(scratch, p.OS+"_"+p.Arch, binName)
- if err := os.MkdirAll(filepath.Dir(outPath), 0o755); err != nil {
+ platDir := filepath.Join(scratch, p.OS+"_"+p.Arch)
+ outPath := filepath.Join(platDir, binName)
+ if err := os.MkdirAll(platDir, 0o755); err != nil {
return "", nil, err
}
@@ -161,23 +163,10 @@ func buildOne(opts Options, cfg voltcfg.Config, vars buildmeta.Vars, p platform.
"GOOS="+p.OS,
"GOARCH="+p.Arch,
)
- if cfg.CGO {
- // cgo cross-compilation needs a C compiler per target; rendered from
- // the toolchain templates. Pre-flight (missing toolchain, darwin
- // target) is validated before we ever get here — see Preflight.
- if cc, err := vars.Render(cfg.Toolchain.CC); err == nil && cc != "" {
- env = append(env, "CC="+cc)
- }
- if cxx, err := vars.Render(cfg.Toolchain.CXX); err == nil && cxx != "" {
- env = append(env, "CXX="+cxx)
- }
- }
+ env = append(env, cgoToolchainEnv(cfg, vars, p)...)
- cmd := exec.Command("go", "build", "-trimpath", "-ldflags", ldflags, "-o", outPath, ".")
- cmd.Dir = opts.Dir
- cmd.Env = env
- if out, err := cmd.CombinedOutput(); err != nil {
- return "", nil, fmt.Errorf("go build: %s", strings.TrimSpace(string(out)))
+ if err := compile(opts.Dir, outPath, ldflags, env); err != nil {
+ return "", nil, err
}
// Verify the stamp landed, not just that the build was green: Go
@@ -186,6 +175,39 @@ func buildOne(opts Options, cfg voltcfg.Config, vars buildmeta.Vars, p platform.
warns := verifyStamps(outPath, stamps)
entries := []archive.Entry{{Name: binName, Path: outPath, Mode: 0o755}}
+ // Companion binaries ride in the same archive. Names must be unique:
+ // two entries with one name would leave whichever the archiver wrote
+ // last, silently.
+ seen := map[string]string{binName: "the main binary"}
+ for _, rel := range cfg.ExtraBinaries {
+ extraDir := filepath.Join(opts.Dir, rel)
+ // The name is the directory's own, resolved: "." and "../x/" name
+ // the directory they point at, not themselves.
+ abs, err := filepath.Abs(extraDir)
+ if err != nil {
+ return "", nil, fmt.Errorf("extra_binaries %s: %w", rel, err)
+ }
+ name := filepath.Base(abs) + p.ExeSuffix()
+ if prev, dup := seen[name]; dup {
+ return "", nil, fmt.Errorf("extra_binaries: %s would be named %s, which is already %s", rel, name, prev)
+ }
+ seen[name] = rel
+ // `go build -o` on a package that is not main succeeds and writes a
+ // package archive under the binary's name: asked of the toolchain
+ // rather than inferred from whether a file appeared.
+ kind, err := detect.Dir(extraDir)
+ if err != nil {
+ return "", nil, fmt.Errorf("extra_binaries %s: %w", rel, err)
+ }
+ if kind != detect.KindCLI {
+ return "", nil, fmt.Errorf("extra_binaries %s: not a program (package main)", rel)
+ }
+ out := filepath.Join(platDir, name)
+ if err := compile(extraDir, out, ldflags, env); err != nil {
+ return "", nil, fmt.Errorf("extra_binaries %s: %w", rel, err)
+ }
+ entries = append(entries, archive.Entry{Name: name, Path: out, Mode: 0o755})
+ }
for _, extra := range cfg.ExtraFiles {
entries = append(entries, archive.Entry{
Name: filepath.Base(extra),
@@ -207,6 +229,17 @@ func buildOne(opts Options, cfg voltcfg.Config, vars buildmeta.Vars, p platform.
return asset, warns, nil
}
+// compile builds the package main in dir to outPath.
+func compile(dir, outPath, ldflags string, env []string) error {
+ cmd := exec.Command("go", "build", "-trimpath", "-ldflags", ldflags, "-o", outPath, ".")
+ cmd.Dir = dir
+ cmd.Env = env
+ if out, err := cmd.CombinedOutput(); err != nil {
+ return fmt.Errorf("go build: %s", strings.TrimSpace(string(out)))
+ }
+ return nil
+}
+
// stamp is one -X assignment, kept for post-build verification.
type stamp struct {
Symbol string
@@ -217,6 +250,30 @@ type stamp struct {
// flag string plus every -X stamp it applied (for verification). Symbols are
// emitted in sorted order so the command line — and therefore the binary — is
// reproducible across runs.
+// cgoToolchainEnv returns the CC/CXX assignments for building p with cgo,
+// rendered from the toolchain templates; nil when cgo is off.
+//
+// The native target gets none: the host's own compiler builds it, which is
+// what Preflight already promises ("native target: the host toolchain
+// suffices"). Applying the cross toolchain there broke the one build that
+// needed nothing — `zig cc -target {{.ZigTarget}}` rendered with an empty
+// triple on a darwin host, and zig rejected it — so a repo had to write a
+// conditional template to get its own platform built. Pre-flight (missing
+// toolchain, darwin target from another OS) has run before this.
+func cgoToolchainEnv(cfg voltcfg.Config, vars buildmeta.Vars, p platform.Platform) []string {
+ if !cfg.CGO || (p.OS == hostOS() && p.Arch == hostArch()) {
+ return nil
+ }
+ var env []string
+ if cc, err := vars.Render(cfg.Toolchain.CC); err == nil && cc != "" {
+ env = append(env, "CC="+cc)
+ }
+ if cxx, err := vars.Render(cfg.Toolchain.CXX); err == nil && cxx != "" {
+ env = append(env, "CXX="+cxx)
+ }
+ return env
+}
+
func renderLDFlags(lf voltcfg.LDFlags, vars buildmeta.Vars) (string, []stamp, error) {
var flags []string
if lf.Strip != nil && *lf.Strip {
diff --git a/apps/volt/gobuild/preflight_test.go b/apps/volt/gobuild/preflight_test.go
index 16e36dd..5f94f9e 100644
--- a/apps/volt/gobuild/preflight_test.go
+++ b/apps/volt/gobuild/preflight_test.go
@@ -5,6 +5,8 @@ import (
"strings"
"testing"
+ "github.com/khanakia/voltkit/apps/volt/buildmeta"
+ "github.com/khanakia/voltkit/apps/volt/platform"
"github.com/khanakia/voltkit/apps/volt/voltcfg"
)
@@ -47,3 +49,34 @@ func TestPreflightNativeOnlySkipsToolchainDemands(t *testing.T) {
t.Fatalf("--native-only needs no cross toolchain: %v", err)
}
}
+
+// TestCgoToolchainEnvLeavesTheNativeTargetAlone pins that the cross toolchain
+// is applied to cross targets only. The native target builds with the host's
+// compiler; handing it `zig cc -target ` failed the one platform that
+// needed no toolchain at all.
+func TestCgoToolchainEnvLeavesTheNativeTargetAlone(t *testing.T) {
+ cfg := voltcfg.Config{CGO: true, Toolchain: voltcfg.Toolchain{CC: "zig cc -target {{.ZigTarget}}", CXX: "zig c++ -target {{.ZigTarget}}"}}
+ native := platform.Platform{OS: hostOS(), Arch: hostArch()}
+ if env := cgoToolchainEnv(cfg, buildmeta.Vars{}, native); len(env) != 0 {
+ t.Errorf("native target got a cross toolchain: %v", env)
+ }
+ // A cross target: linux on the architecture this host is not.
+ other := "arm64"
+ if hostArch() == "arm64" {
+ other = "amd64"
+ }
+ cross := platform.Platform{OS: "linux", Arch: other}
+ triple, ok := cross.ZigTarget()
+ if !ok {
+ t.Fatalf("no zig triple for %v", cross)
+ }
+ env := cgoToolchainEnv(cfg, buildmeta.Vars{ZigTarget: triple}, cross)
+ if len(env) != 2 || env[0] != "CC=zig cc -target "+triple || env[1] != "CXX=zig c++ -target "+triple {
+ t.Errorf("cross target env = %v", env)
+ }
+ // cgo off: nothing, whatever the toolchain says.
+ cfg.CGO = false
+ if env := cgoToolchainEnv(cfg, buildmeta.Vars{ZigTarget: triple}, cross); env != nil {
+ t.Errorf("cgo off must set no compiler: %v", env)
+ }
+}
diff --git a/apps/volt/voltcfg/config.go b/apps/volt/voltcfg/config.go
index 8b2cba0..7f7c361 100644
--- a/apps/volt/voltcfg/config.go
+++ b/apps/volt/voltcfg/config.go
@@ -34,6 +34,14 @@ type Config struct {
// ExtraFiles are shipped inside each archive next to the binary
// (README, LICENSE). Paths are relative to the released directory.
ExtraFiles []string `yaml:"extra_files"`
+ // ExtraBinaries are other `package main` directories, relative to the
+ // released directory, built for every platform and shipped in the SAME
+ // archive as the main binary, each named after its directory. For a
+ // tool with companion programs it needs on PATH (plugins, helpers):
+ // one download and one install give a set that cannot be mismatched.
+ // They take the main binary's build settings; only the main binary's
+ // version stamp is verified, since a helper need not carry the symbol.
+ ExtraBinaries []string `yaml:"extra_binaries"`
LDFlags LDFlags `yaml:"ldflags"`