test(cli): hold the collection, metadata and tarball commands' edits

A mutation run over these files left edits no test refused: the
argument wiring of templates metadata, features info, generate-docs
and features test, features test's flag conflicts, the template
metadata failures, createTarArchive's entry names, empty user names
and footer, extracted file modes, the 2xx-only tarball download and
the per-user Linux cache folder. Each test asserts what a caller sees,
without Docker, reusing readRegistry and httptest servers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: aledbf

internal/cli/collection_commands_repo_held_test.go

@@ -0,0 +1,182 @@
+package cli
+
+import (
+	"archive/tar"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// generate-docs documents the folder its positional argument names, else the
+// one --project-folder names; the working directory (the default ".") is left
+// alone either way.
+func TestGenerateDocsCommandsProjectFolder(t *testing.T) {
+	t.Chdir(t.TempDir())
+	writeFeature(t, ".", "decoy", `{"id":"decoy","version":"1.0.0","name":"Decoy"}`)
+	commands := map[string]struct {
+		cmd      func() *cobra.Command
+		metadata string
+		flags    []string
+	}{
+		"features":  {realFeaturesGenerateDocsCmd, "devcontainer-feature.json", []string{"--namespace", "o/r"}},
+		"templates": {realTemplatesGenerateDocsCmd, "devcontainer-template.json", nil},
+	}
+	for name, c := range commands {
+		for _, positional := range []bool{true, false} {
+			project := t.TempDir()
+			if err := os.WriteFile(filepath.Join(project, c.metadata), []byte(`{"id":"solo","version":"1.0.0","name":"Solo"}`), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			args := []string{"--project-folder", project}
+			if positional {
+				args = []string{project}
+			}
+			cmd := c.cmd()
+			cmd.SilenceUsage, cmd.SilenceErrors = true, true
+			cmd.SetOut(&bytes.Buffer{})
+			cmd.SetErr(&bytes.Buffer{})
+			cmd.SetArgs(append(args, c.flags...))
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("%s %v: %v", name, args, err)
+			}
+			if _, err := os.Stat(filepath.Join(project, "README.md")); err != nil {
+				t.Errorf("%s %v: README not generated in the project folder: %v", name, args, err)
+			}
+		}
+	}
+	if _, err := os.Stat(filepath.Join("decoy", "README.md")); !errors.Is(err, os.ErrNotExist) {
+		t.Errorf("the working directory was documented: %v", err)
+	}
+}
+
+func runFeaturesTestCmd(t *testing.T, args ...string) (string, error) {
+	t.Helper()
+	cmd := realFeaturesTestCmd()
+	cmd.SilenceUsage, cmd.SilenceErrors = true, true
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&bytes.Buffer{})
+	cmd.SetArgs(args)
+	err := cmd.Execute()
+	return out.String(), err
+}
+
+// features test refuses the flag combinations TS refuses, before it looks at
+// the collection; each flag alone is accepted and reaches the collection check.
+func TestFeaturesTestCommandFlagConflicts(t *testing.T) {
+	empty := t.TempDir()
+	conflicts := map[string][]string{
+		"Cannot combine --global-scenarios-only and --features":       {"--global-scenarios-only", "--features", "a"},
+		"Cannot combine --skip-scenarios and --global-scenarios-only": {"--global-scenarios-only", "--skip-scenarios"},
+	}
+	for want, args := range conflicts {
+		if _, err := runFeaturesTestCmd(t, append(args, "-p", empty)...); err == nil || err.Error() != want {
+			t.Errorf("%v: err = %v, want %q", args, err, want)
+		}
+	}
+	for _, args := range [][]string{{"--features", "a"}, {"--global-scenarios-only"}, {"--skip-scenarios"}} {
+		if _, err := runFeaturesTestCmd(t, append(args, "-p", empty)...); exitCode(err) != 1 {
+			t.Errorf("%v: err = %v, want the collection check's exit 1", args, err)
+		}
+	}
+}
+
+// features test checks the collection its positional target names, or
+// --project-folder's when the target is missing or "."; a collection without
+// src/ and test/ exits 1 naming the folder on stdout.
+func TestFeaturesTestCommandTarget(t *testing.T) {
+	project, target := t.TempDir(), t.TempDir()
+	cases := []struct {
+		args []string
+		want string
+	}{
+		{[]string{target, "-p", project}, target},
+		{[]string{".", "-p", project}, project},
+		{[]string{"-p", project}, project},
+	}
+	for _, c := range cases {
+		out, err := runFeaturesTestCmd(t, c.args...)
+		if exitCode(err) != 1 {
+			t.Errorf("%v: err = %v, want exit 1", c.args, err)
+		}
+		if want := "[-] Folder '" + c.want + "' does not contain the required 'src' and 'test' folders.\n"; !strings.HasSuffix(out, want) {
+			t.Errorf("%v: stdout = %q, want it to end with %q", c.args, out, want)
+		}
+	}
+}
+
+// orderedObjectKeys lists an object's own keys in source order, whatever its
+// values nest, and nothing for anything but an object.
+func TestOrderedObjectKeys(t *testing.T) {
+	raw := `{"z":{"x":"y","k":{"deep":[1,{"q":"r"}]}},"a":["s",{"t":"u"}],"m":"v","b":null}`
+	if got, want := orderedObjectKeys(json.RawMessage(raw)), []string{"z", "a", "m", "b"}; !slices.Equal(got, want) {
+		t.Errorf("keys = %q, want %q", got, want)
+	}
+	for _, raw := range []string{``, `["a","b"]`, `"a"`, `{`} {
+		if got := orderedObjectKeys(json.RawMessage(raw)); len(got) != 0 {
+			t.Errorf("%s: keys = %q, want none", raw, got)
+		}
+	}
+}
+
+// createTarArchive roots the entries at "./", with forward slashes and a
+// trailing slash on directories, and records no user or group names, as
+// node-tar does.
+func TestCreateTarArchiveEntries(t *testing.T) {
+	src := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(src, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(src, "sub", "install.sh"), []byte("echo hi\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	archive := filepath.Join(t.TempDir(), "out.tgz")
+	if err := createTarArchive(archive, src); err != nil {
+		t.Fatal(err)
+	}
+	f, err := os.Open(archive)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	tr := tar.NewReader(f)
+	var names []string
+	for {
+		h, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+		names = append(names, h.Name)
+		if h.Uname != "" || h.Gname != "" {
+			t.Errorf("%s: uname %q, gname %q, want both empty", h.Name, h.Uname, h.Gname)
+		}
+		if h.Name == "./sub/install.sh" {
+			if b, _ := io.ReadAll(tr); string(b) != "echo hi\n" {
+				t.Errorf("install.sh = %q", b)
+			}
+		}
+	}
+	if want := []string{"./", "./sub/", "./sub/install.sh"}; !slices.Equal(names, want) {
+		t.Errorf("entries = %q, want %q", names, want)
+	}
+	// The archive is finished: whole 512-byte blocks ending in the two zero
+	// blocks that mark the end of a tar.
+	data, err := os.ReadFile(archive)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(data)%512 != 0 || len(data) < 1024 || !bytes.Equal(data[len(data)-1024:], make([]byte, 1024)) {
+		t.Errorf("archive of %d bytes does not end in the tar footer", len(data))
+	}
+}

internal/cli/disallowed_repo_held_test.go

@@ -0,0 +1,24 @@
+package cli
+
+import (
+	"os"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+// On Linux the cache folder carries the user's name, as TS getCacheFolder's
+// does, so two users of one machine do not share it.
+func TestCacheFolderNamesTheLinuxUser(t *testing.T) {
+	if runtime.GOOS != "linux" {
+		t.Skip("the per-user folder is Linux's")
+	}
+	u, err := user.Current()
+	if err != nil || u.Username == "" {
+		t.Skipf("no current user name: %v", err)
+	}
+	if got, want := cacheFolder(), filepath.Join(os.TempDir(), "devcontainercli-"+u.Username); got != want {
+		t.Errorf("cacheFolder() = %q, want %q", got, want)
+	}
+}

internal/cli/feature_install_repo_held_test.go

@@ -0,0 +1,65 @@
+package cli
+
+import (
+	"archive/tar"
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// A regular file keeps the mode its tar entry records, so a Feature's
+// install.sh stays executable; an entry recording no mode keeps the mode the
+// file was created with instead of becoming unreadable.
+func TestExtractTarGzFileModes(t *testing.T) {
+	var buf bytes.Buffer
+	tw := tar.NewWriter(&buf)
+	for name, mode := range map[string]int64{"install.sh": 0o750, "nomode.txt": 0} {
+		if err := tw.WriteHeader(&tar.Header{Name: name, Mode: mode, Size: 2, Typeflag: tar.TypeReg}); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := tw.Write([]byte("hi")); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := tw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	archive := filepath.Join(t.TempDir(), "feature.tar")
+	if err := os.WriteFile(archive, buf.Bytes(), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	dest := t.TempDir()
+	if err := extractTarGz(archive, dest); err != nil {
+		t.Fatal(err)
+	}
+	if fi, err := os.Stat(filepath.Join(dest, "install.sh")); err != nil || fi.Mode().Perm() != 0o750 {
+		t.Errorf("install.sh: %v, %v, want mode 0750", fi.Mode(), err)
+	}
+	if b, err := os.ReadFile(filepath.Join(dest, "nomode.txt")); err != nil || string(b) != "hi" {
+		t.Errorf("nomode.txt: %q, %v, want it readable", b, err)
+	}
+}
+
+// A tarball download succeeds only on a 2xx answer, as TS treats only
+// 200-299 as success: a 300 fails it.
+func TestDownloadFeatureTarballStatus(t *testing.T) {
+	for status, ok := range map[int]bool{200: true, 299: true, 300: false} {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(status)
+			_, _ = w.Write([]byte("tgz"))
+		}))
+		data, _, err := downloadFeatureTarball(context.Background(), nil, srv.URL+"/f.tgz", nil)
+		srv.Close()
+		if ok && (err != nil || string(data) != "tgz") {
+			t.Errorf("HTTP %d: %q, %v, want the body", status, data, err)
+		}
+		if !ok && (err == nil || !strings.Contains(err.Error(), "HTTP 300")) {
+			t.Errorf("HTTP %d: err = %v, want the status", status, err)
+		}
+	}
+}

internal/cli/features_info_repo_held_test.go

@@ -0,0 +1,28 @@
+package cli
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+// info <mode> <feature> takes the mode from its first argument and the
+// Feature from its second.
+func TestFeaturesInfoCommandArguments(t *testing.T) {
+	reg := newReadRegistry(t)
+	reg.manifests["ns/tool"] = featureManifest("tool")
+	reg.tags["ns/tool"] = []string{"1.0.0"}
+
+	cmd := realFeaturesInfoCmd()
+	cmd.SilenceUsage, cmd.SilenceErrors = true, true
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&bytes.Buffer{})
+	cmd.SetArgs([]string{"tags", reg.host + "/ns/tool:1", "--output-format", "json"})
+	if err := cmd.ExecuteContext(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+	if got := strings.Join(strings.Fields(out.String()), ""); got != `{"publishedTags":["1.0.0"]}` {
+		t.Errorf("stdout = %s, want the Feature's tags", out.String())
+	}
+}

internal/cli/templates_metadata_repo_held_test.go

@@ -0,0 +1,69 @@
+package cli
+
+import (
+	"bytes"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// templateManifest is a Template manifest whose annotations are the given
+// JSON object body.
+func templateManifest(annotations string) []byte {
+	return []byte(`{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json",` +
+		`"config":{"mediaType":"application/vnd.devcontainers","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2},` +
+		`"layers":[],"annotations":{` + annotations + `}}`)
+}
+
+func runTemplatesMetadataCmd(t *testing.T, templateID string) (string, error) {
+	t.Helper()
+	cmd := realTemplatesMetadataCmd()
+	cmd.SilenceUsage, cmd.SilenceErrors = true, true
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&bytes.Buffer{})
+	cmd.SetArgs([]string{templateID})
+	err := cmd.ExecuteContext(t.Context())
+	return out.String(), err
+}
+
+// templates metadata <id> prints the manifest's metadata annotation as
+// JSON.stringify(JSON.parse(annotation)) does: compacted, keys in source order.
+func TestTemplatesMetadataPrintsTheAnnotation(t *testing.T) {
+	reg := newReadRegistry(t)
+	metadata := `{ "id": "tpl", "version": "1.0.0", "a": [1, 2] }`
+	reg.manifests["ns/tpl"] = templateManifest(`"dev.containers.metadata":` + strconv.Quote(metadata))
+
+	got, err := runTemplatesMetadataCmd(t, reg.host+"/ns/tpl:latest")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := `{"id":"tpl","version":"1.0.0","a":[1,2]}` + "\n"; got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
+// Every failure prints an empty object on stdout, as TS does before exiting 1,
+// and returns the reason.
+func TestTemplatesMetadataFailures(t *testing.T) {
+	reg := newReadRegistry(t)
+	reg.manifests["ns/none"] = templateManifest(`"other":"x"`)
+	reg.manifests["ns/empty"] = templateManifest(`"dev.containers.metadata":""`)
+	reg.manifests["ns/broken"] = templateManifest(`"dev.containers.metadata":"{\"id\":"`)
+	cases := []struct{ name, id, want string }{
+		{"unparsable id", "UPPER/Not A Ref", "parse template identifier"},
+		{"no manifest", reg.host + "/ns/missing:latest", "fetch manifest for template"},
+		{"no annotation", reg.host + "/ns/none:latest", "does not contain metadata"},
+		{"empty annotation", reg.host + "/ns/empty:latest", "does not contain metadata"},
+		{"invalid annotation", reg.host + "/ns/broken:latest", "has invalid metadata"},
+	}
+	for _, c := range cases {
+		got, err := runTemplatesMetadataCmd(t, c.id)
+		if err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%s: err = %v, want %q", c.name, err, c.want)
+		}
+		if got != "{}\n" {
+			t.Errorf("%s: stdout = %q, want an empty object", c.name, got)
+		}
+	}
+}