feat: add repo read-file and repo read-dir (cli#13580)

Signed-off-by: Babak K. Shandiz <babakks@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: babakks

acceptance/testdata/repo/repo-read-dir.txtar

@@ -0,0 +1,71 @@
+# List directory contents of a repository without cloning.
+
+# Use gh as a credential helper
+exec gh auth setup-git
+
+# Create a private repo with a default branch
+exec gh repo create $ORG/$SCRIPT_NAME-$RANDOM_STRING --private --add-readme
+defer gh repo delete --yes $ORG/$SCRIPT_NAME-$RANDOM_STRING
+
+# Clone the repo and add a docs dir plus an executable script
+exec gh repo clone $ORG/$SCRIPT_NAME-$RANDOM_STRING
+cd $SCRIPT_NAME-$RANDOM_STRING
+mkdir docs
+mkdir script
+cp $WORK/guide.md docs/guide.md
+cp $WORK/run.sh script/run.sh
+chmod 755 script/run.sh
+exec git add -A
+exec git commit -m 'Add docs and script'
+exec git push origin main
+
+# Add a v2 branch with an extra file in docs, to exercise --ref
+exec git checkout -b v2
+cp $WORK/extra.md docs/extra.md
+exec git add -A
+exec git commit -m 'Add docs/extra.md on v2'
+exec git push -u origin v2
+exec git checkout main
+
+# List the repository root. Non-TTY output is tab-separated as type, name,
+# octal mode, and byte size. Directories report mode 040000 and size 0; the
+# auto-generated README has a non-deterministic size, so match it as digits.
+exec gh repo read-dir
+stdout '^file\tREADME\.md\t100644\t\d+$'
+stdout '^dir\tdocs\t040000\t0$'
+stdout '^dir\tscript\t040000\t0$'
+
+# List a subdirectory
+exec gh repo read-dir docs
+stdout '^file\tguide\.md\t100644\t19$'
+! stdout 'extra\.md'
+
+# Executable files are reported as a file with octal mode 100755
+exec gh repo read-dir script --json name,type,modeOctal --jq '.entries[] | .name + " " + .type + " " + .modeOctal'
+stdout '^run\.sh file 100755$'
+
+# JSON output lists directory entries
+exec gh repo read-dir --json name,type --jq '.entries[] | select(.type=="dir") | .name'
+stdout '^docs$'
+stdout '^script$'
+
+# A ref can select a different tree
+exec gh repo read-dir docs --ref v2
+stdout 'guide\.md'
+stdout 'extra\.md'
+
+# Error: the path points to a file, not a directory
+! exec gh repo read-dir README.md
+stderr 'is a file, not a directory'
+
+# Error: the path does not exist
+! exec gh repo read-dir does-not-exist
+stderr 'could not find'
+
+-- guide.md --
+This is the guide.
+-- extra.md --
+Extra file on v2.
+-- run.sh --
+#!/bin/bash
+echo "hello"

acceptance/testdata/repo/repo-read-file.txtar

@@ -0,0 +1,88 @@
+# Read files from a repository without cloning, in several modes.
+
+# Use gh as a credential helper
+exec gh auth setup-git
+
+# Create a private repo with a default branch
+exec gh repo create $ORG/$SCRIPT_NAME-$RANDOM_STRING --private --add-readme
+defer gh repo delete --yes $ORG/$SCRIPT_NAME-$RANDOM_STRING
+
+# Clone the repo and add a text file under a subdirectory
+exec gh repo clone $ORG/$SCRIPT_NAME-$RANDOM_STRING
+cd $SCRIPT_NAME-$RANDOM_STRING
+mkdir docs
+cp $WORK/guide.md docs/guide.md
+exec git add -A
+exec git commit -m 'Add docs/guide.md'
+exec git push origin main
+
+# Add a v2 branch where the same file has different content, to exercise --ref
+exec git checkout -b v2
+cp $WORK/guide-v2.md docs/guide.md
+exec git add -A
+exec git commit -m 'Update docs/guide.md on v2'
+exec git push -u origin v2
+exec git checkout main
+
+# Create a small binary file (PNG signature) via the Contents API
+exec gh api -X PUT repos/$ORG/$SCRIPT_NAME-$RANDOM_STRING/contents/assets/logo.png -f message='Add binary' -f content=iVBORw0KGgo=
+
+# Create a text file containing ANSI terminal escape sequences via the Contents API
+exec gh api -X PUT repos/$ORG/$SCRIPT_NAME-$RANDOM_STRING/contents/ansi.txt -f message='Add ansi' -f content=G1szMW1oZWxsbxtbMG0K
+
+# Read a file from the default branch: raw content goes to stdout
+exec gh repo read-file docs/guide.md
+cmp stdout $WORK/guide.md
+
+# Read the same file at a specific ref
+exec gh repo read-file docs/guide.md --ref v2
+cmp stdout $WORK/guide-v2.md
+
+# Save a file to disk, and confirm --clobber is required to overwrite
+exec gh repo read-file docs/guide.md --output out.txt
+cmp out.txt $WORK/guide.md
+! exec gh repo read-file docs/guide.md --output out.txt
+stderr 'already exists'
+exec gh repo read-file docs/guide.md --output out.txt --clobber
+cmp out.txt $WORK/guide.md
+
+# Save into a directory: a trailing separator writes under the remote basename
+exec gh repo read-file docs/guide.md --output download-dir/
+cmp download-dir/guide.md $WORK/guide.md
+
+# Save to an explicit path inside a directory, creating it as needed
+exec gh repo read-file docs/guide.md --output download-dir/out.txt
+cmp download-dir/out.txt $WORK/guide.md
+
+# JSON output exposes file metadata
+exec gh repo read-file docs/guide.md --json name,path,size,type --jq '.name'
+stdout '^guide\.md$'
+
+# Read a binary file: the raw bytes written to stdout match the saved copy,
+# and the base64 content is exposed via --json
+exec gh repo read-file assets/logo.png --output downloaded.png
+exists downloaded.png
+exec gh repo read-file assets/logo.png
+cmp stdout downloaded.png
+exec gh repo read-file assets/logo.png --json size,type,content --jq '.content'
+stdout '^iVBORw0KGgo=$'
+
+# A file with terminal escape sequences is refused by default, but readable
+# with --allow-escape-sequences
+! exec gh repo read-file ansi.txt
+stderr 'terminal escape sequences'
+exec gh repo read-file ansi.txt --allow-escape-sequences
+stdout 'hello'
+
+# Error: the path is a directory
+! exec gh repo read-file docs
+stderr 'is a directory'
+
+# Error: the path does not exist
+! exec gh repo read-file does/not/exist.md
+stderr 'Not Found'
+
+-- guide.md --
+Hello from the default branch!
+-- guide-v2.md --
+Hello from the v2 branch!

internal/text/text.go

@@ -149,3 +149,26 @@ func FormatSlice(values []string, lineLength uint, indent uint, prependWith stri
 	}
 	return builder.String()
 }
+
+// FormatSize formats a byte count using binary units (B, KB, MB, GB, TB, PB).
+// Values below a kilobyte are shown as whole bytes; larger values are shown with
+// one decimal place of precision.
+func FormatSize(n int64) string {
+	const unit = 1024
+	if n < unit {
+		return fmt.Sprintf("%d B", n)
+	}
+
+	units := []string{"KB", "MB", "GB", "TB", "PB"}
+
+	// Stop at the largest known unit so an out-of-range index can never occur,
+	// even for byte counts beyond a petabyte.
+	div, exp := int64(unit), 0
+	for v := n / unit; v >= unit && exp < len(units)-1; v /= unit {
+		div *= unit
+		exp++
+	}
+
+	value := float64(n) / float64(div)
+	return fmt.Sprintf("%.1f %s", value, units[exp])
+}

internal/text/text_test.go

@@ -1,6 +1,7 @@
 package text
 
 import (
+	"math"
 	"testing"
 	"time"
 
@@ -181,3 +182,33 @@ func TestDisplayURL(t *testing.T) {
 		})
 	}
 }
+
+func TestFormatSize(t *testing.T) {
+	tests := []struct {
+		n    int64
+		want string
+	}{
+		{0, "0 B"},
+		{1, "1 B"},
+		{512, "512 B"},
+		{1023, "1023 B"},
+		{1024, "1.0 KB"},
+		{1536, "1.5 KB"},
+		{2048, "2.0 KB"},
+		{10240, "10.0 KB"},
+		{524288, "512.0 KB"},
+		{1048576, "1.0 MB"},
+		{1572864, "1.5 MB"},
+		{5242880, "5.0 MB"},
+		{1073741824, "1.0 GB"},
+		{1610612736, "1.5 GB"},
+		{1099511627776, "1.0 TB"},
+		{1125899906842624, "1.0 PB"},
+		{1152921504606846976, "1024.0 PB"}, // 1 EB clamps to the largest known unit
+		{math.MaxInt64, "8192.0 PB"},       // maximum int never indexes past PB
+	}
+
+	for _, tt := range tests {
+		assert.Equal(t, tt.want, FormatSize(tt.n))
+	}
+}