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"`