eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Add JSON output format for CLI commands

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-01 20:44:27 +00:00
parent 0382978af0
commit e51bc28b05
13 changed files with 849 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
internal/cli/format.go Normal file
View File

@@ -0,0 +1,22 @@
package cli
import (
"flag"
"fmt"
"io"
"gitea.maximumdirect.net/eric/distributor/internal/app"
)
func addFormatFlag(flags *flag.FlagSet) *string {
return flags.String("format", string(app.OutputFormatText), "output format: text or json")
}
func parseOutputFormat(stderr io.Writer, command, raw string) (app.OutputFormat, bool) {
format := app.OutputFormat(raw)
if err := app.ValidateOutputFormat(format); err != nil {
fmt.Fprintf(stderr, "%s: %s --format: %s\n", app.Name, command, err)
return "", false
}
return app.NormalizeOutputFormat(format), true
}

20
internal/cli/inspect.go
View File

@@ -2,6 +2,7 @@ package cli
import (
"context"
"flag"
"fmt"
"io"
@@ -13,11 +14,21 @@ func inspectCommand(ctx context.Context, args []string, stdout, stderr io.Writer
printInspectHelp(stdout)
return exitOK
}
path, ok := parseOptionalPathArg(stderr, "inspect", args)
flags := flag.NewFlagSet("inspect", flag.ContinueOnError)
flags.SetOutput(stderr)
formatFlag := addFormatFlag(flags)
if err := flags.Parse(args); err != nil {
return exitUsage
}
format, ok := parseOutputFormat(stderr, "inspect", *formatFlag)
if !ok {
return exitUsage
}
if err := app.Inspect(ctx, app.InspectOptions{Path: path, Stdout: stdout}); err != nil {
path, ok := parseOptionalPathArg(stderr, "inspect", flags.Args())
if !ok {
return exitUsage
}
if err := app.Inspect(ctx, app.InspectOptions{Path: path, Stdout: stdout, OutputFormat: format}); err != nil {
return fail(stderr, err)
}
return exitOK
@@ -25,7 +36,10 @@ func inspectCommand(ctx context.Context, args []string, stdout, stderr io.Writer
func printInspectHelp(w io.Writer) {
fmt.Fprint(w, `Usage:
distributor inspect <path>
distributor inspect [--format text|json] <path>
Options:
--format text|json Output format
Print a normalized summary of local source bundles.
`)

263
internal/cli/root_test.go
View File

@@ -3,6 +3,9 @@ package cli
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"os"
"path/filepath"
"strings"
@@ -12,6 +15,29 @@ import (
"gitea.maximumdirect.net/eric/distributor/internal/testutil"
)
func decodeEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]any {
t.Helper()
decoder := json.NewDecoder(strings.NewReader(stdout.String()))
var envelope map[string]any
if err := decoder.Decode(&envelope); err != nil {
t.Fatalf("decode JSON envelope: %v; stdout = %q", err, stdout.String())
}
var extra any
if err := decoder.Decode(&extra); err != io.EOF {
t.Fatalf("stdout contains more than one JSON document: %q", stdout.String())
}
return envelope
}
func envelopeResult(t *testing.T, envelope map[string]any) map[string]any {
t.Helper()
result, ok := envelope["result"].(map[string]any)
if !ok {
t.Fatalf("result = %#v, want object", envelope["result"])
}
return result
}
func TestExecuteRootHelp(t *testing.T) {
var stdout, stderr bytes.Buffer
@@ -44,6 +70,43 @@ func TestExecuteVersion(t *testing.T) {
}
}
func TestExecuteVersionJSON(t *testing.T) {
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"version", "--format", "json"}, &stdout, &stderr)
if code != exitOK {
t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
}
envelope := decodeEnvelope(t, &stdout)
if envelope["command"] != "version" || envelope["ok"] != true {
t.Fatalf("envelope = %#v, want version ok", envelope)
}
result := envelopeResult(t, envelope)
if result["application"] != "distributor" || result["version"] != "dev" {
t.Fatalf("result = %#v, want application/version", result)
}
if stderr.Len() != 0 {
t.Fatalf("stderr = %q, want empty", stderr.String())
}
}
func TestExecuteRejectsInvalidFormat(t *testing.T) {
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"version", "--format", "xml"}, &stdout, &stderr)
if code != exitUsage {
t.Fatalf("exit code = %d, want %d", code, exitUsage)
}
if stdout.Len() != 0 {
t.Fatalf("stdout = %q, want empty", stdout.String())
}
if !strings.Contains(stderr.String(), "format must be text or json") {
t.Fatalf("stderr = %q, want invalid format error", stderr.String())
}
}
func TestExecuteValidate(t *testing.T) {
var stdout, stderr bytes.Buffer
@@ -57,6 +120,24 @@ func TestExecuteValidate(t *testing.T) {
}
}
func TestExecuteValidateJSON(t *testing.T) {
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"validate", "--format", "json", filepath.Join("..", "bundle", "testdata", "valid_bundle")}, &stdout, &stderr)
if code != exitOK {
t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
}
envelope := decodeEnvelope(t, &stdout)
if envelope["command"] != "validate" || envelope["ok"] != true {
t.Fatalf("envelope = %#v, want validate ok", envelope)
}
result := envelopeResult(t, envelope)
if result["bundle_count"] != float64(1) {
t.Fatalf("result = %#v, want one bundle", result)
}
}
func TestExecuteValidateArgs(t *testing.T) {
validPath := filepath.Join("..", "bundle", "testdata", "valid_bundle")
tests := []struct {
@@ -115,6 +196,32 @@ func TestExecuteInspect(t *testing.T) {
}
}
func TestExecuteInspectJSON(t *testing.T) {
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"inspect", "--format", "json", filepath.Join("..", "bundle", "testdata", "valid_bundle")}, &stdout, &stderr)
if code != exitOK {
t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
}
envelope := decodeEnvelope(t, &stdout)
if envelope["command"] != "inspect" || envelope["ok"] != true {
t.Fatalf("envelope = %#v, want inspect ok", envelope)
}
result := envelopeResult(t, envelope)
bundles, ok := result["bundles"].([]any)
if !ok || len(bundles) != 1 {
t.Fatalf("bundles = %#v, want one bundle", result["bundles"])
}
bundle, ok := bundles[0].(map[string]any)
if !ok {
t.Fatalf("bundle = %#v, want object", bundles[0])
}
if bundle["id"] != "weather.daily.brentwood.2026-05-30" || bundle["file_count"] != float64(2) || bundle["total_size"] != float64(24) {
t.Fatalf("bundle = %#v, want normalized metadata", bundle)
}
}
func TestExecuteInspectArgs(t *testing.T) {
validPath := filepath.Join("..", "bundle", "testdata", "valid_bundle")
tests := []struct {
@@ -180,6 +287,162 @@ func TestExecuteRunDryRun(t *testing.T) {
}
}
func TestExecuteRunJSONDryRun(t *testing.T) {
sourceRoot := t.TempDir()
testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
configPath := testutil.WriteMinimalLocalConfig(t, sourceRoot, t.TempDir())
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"run", "--config", configPath, "--dry-run", "--format", "json"}, &stdout, &stderr)
if code != exitOK {
t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
}
envelope := decodeEnvelope(t, &stdout)
if envelope["command"] != "run" || envelope["ok"] != true {
t.Fatalf("envelope = %#v, want run ok", envelope)
}
result := envelopeResult(t, envelope)
if result["dry_run"] != true {
t.Fatalf("result = %#v, want dry_run true", result)
}
actions, ok := result["actions"].([]any)
if !ok || len(actions) != 1 {
t.Fatalf("actions = %#v, want one action", result["actions"])
}
action, ok := actions[0].(map[string]any)
if !ok || action["action"] != "publish_new" {
t.Fatalf("action = %#v, want publish_new", actions[0])
}
if stderr.Len() != 0 {
t.Fatalf("stderr = %q, want empty", stderr.String())
}
}
func TestExecuteRunJSONWarningsAreStructured(t *testing.T) {
name := "DISTRIBUTOR_TEST_CLI_JSON_SECRET"
t.Setenv(name, "process-value")
sourceRoot := t.TempDir()
destinationRoot := t.TempDir()
secretsRoot := t.TempDir()
testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
if err := os.WriteFile(filepath.Join(secretsRoot, name), []byte("secret-value\n"), 0o600); err != nil {
t.Fatalf("write secret: %v", err)
}
configPath := filepath.Join(t.TempDir(), "config.yml")
if err := os.WriteFile(configPath, []byte(`
secrets:
directory: `+secretsRoot+`
pipelines:
- id: reports
source:
backend: local
path: `+sourceRoot+`
destinations:
- id: archive
backend: local
path: `+destinationRoot+`
`), 0o600); err != nil {
t.Fatalf("write config: %v", err)
}
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"run", "--config", configPath, "--dry-run", "--format", "json"}, &stdout, &stderr)
if code != exitOK {
t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
}
envelope := decodeEnvelope(t, &stdout)
warnings, ok := envelope["warnings"].([]any)
if !ok || len(warnings) != 1 {
t.Fatalf("warnings = %#v, want one warning", envelope["warnings"])
}
warning, ok := warnings[0].(map[string]any)
if !ok || !strings.Contains(fmt.Sprint(warning["message"]), name) {
t.Fatalf("warning = %#v, want secret name", warnings[0])
}
if strings.Contains(stdout.String(), "Warning:") || strings.Contains(stdout.String(), "process-value") || strings.Contains(stdout.String(), "secret-value") {
t.Fatalf("stdout exposed text warning or secret values: %q", stdout.String())
}
if stderr.Len() != 0 {
t.Fatalf("stderr = %q, want empty", stderr.String())
}
}
func TestExecuteRunJSONFatalSetupErrorWritesNoJSON(t *testing.T) {
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"run", "--config", filepath.Join(t.TempDir(), "missing.yml"), "--format", "json"}, &stdout, &stderr)
if code != exitError {
t.Fatalf("exit code = %d, want %d", code, exitError)
}
if stdout.Len() != 0 {
t.Fatalf("stdout = %q, want empty", stdout.String())
}
if !strings.Contains(stderr.String(), "no such file or directory") {
t.Fatalf("stderr = %q, want setup error", stderr.String())
}
}
func TestExecuteRunJSONPartialFailure(t *testing.T) {
sourceRoot := t.TempDir()
firstDestination := t.TempDir()
secondDestination := t.TempDir()
testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
if err := os.WriteFile(filepath.Join(firstDestination, "unmanaged.txt"), []byte("data"), 0o600); err != nil {
t.Fatalf("write unmanaged file: %v", err)
}
configPath := filepath.Join(t.TempDir(), "config.yml")
if err := os.WriteFile(configPath, []byte(`
pipelines:
- id: reports
source:
backend: local
path: `+sourceRoot+`
destinations:
- id: archive-one
backend: local
path: `+firstDestination+`
- id: archive-two
backend: local
path: `+secondDestination+`
`), 0o600); err != nil {
t.Fatalf("write config: %v", err)
}
var stdout, stderr bytes.Buffer
code := Execute(context.Background(), []string{"run", "--config", configPath, "--format", "json"}, &stdout, &stderr)
if code != exitError {
t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitError, stderr.String())
}
if stderr.Len() != 0 {
t.Fatalf("stderr = %q, want empty for partial JSON result", stderr.String())
}
envelope := decodeEnvelope(t, &stdout)
if envelope["command"] != "run" || envelope["ok"] != false {
t.Fatalf("envelope = %#v, want failed run envelope", envelope)
}
errors, ok := envelope["errors"].([]any)
if !ok || len(errors) != 1 {
t.Fatalf("errors = %#v, want one error", envelope["errors"])
}
result := envelopeResult(t, envelope)
summary, ok := result["summary"].(map[string]any)
if !ok || summary["status"] != "failed" || summary["failed"] != float64(1) {
t.Fatalf("summary = %#v, want failed summary", result["summary"])
}
actions, ok := result["actions"].([]any)
if !ok || len(actions) != 2 {
t.Fatalf("actions = %#v, want two actions", result["actions"])
}
if _, err := os.Stat(filepath.Join(secondDestination, storage.StateFileName)); err != nil {
t.Fatalf("second destination state stat error = %v", err)
}
}
func TestExecuteRunForceDryRunReportsWithoutWriting(t *testing.T) {
sourceRoot := t.TempDir()
destinationRoot := t.TempDir()

21
internal/cli/run.go
View File

@@ -20,19 +20,28 @@ func runCommand(ctx context.Context, args []string, stdout, stderr io.Writer) in
configPath := flags.String("config", "", "path to config file")
dryRun := flags.Bool("dry-run", false, "load and validate config without publishing")
force := flags.Bool("force", false, "allow explicit destructive replacement for supported conflicts")
formatFlag := addFormatFlag(flags)
if err := flags.Parse(args); err != nil {
return exitUsage
}
if rejectPositionalArgs(stderr, "run", flags.Args()) {
return exitUsage
}
format, ok := parseOutputFormat(stderr, "run", *formatFlag)
if !ok {
return exitUsage
}
if err := app.Run(ctx, app.RunOptions{
ConfigPath: *configPath,
DryRun: *dryRun,
Force: *force,
Stdout: stdout,
ConfigPath: *configPath,
DryRun: *dryRun,
Force: *force,
Stdout: stdout,
OutputFormat: format,
}); err != nil {
if app.IsJSONOutput(format) && app.IsPartialResultError(err) {
return exitError
}
return fail(stderr, err)
}
return exitOK
@@ -40,12 +49,14 @@ func runCommand(ctx context.Context, args []string, stdout, stderr io.Writer) in
func printRunHelp(w io.Writer) {
fmt.Fprint(w, `Usage:
distributor run --config <path> [--dry-run] [--force]
distributor run --config <path> [--dry-run] [--force] [--format text|json]
Options:
--config <path> Path to config file
--dry-run Load and validate config without publishing
--force Allow explicit destructive replacement for supported conflicts
--format text|json
Output format
Run discovers configured source bundles, plans each destination, publishes
selected outputs unless --dry-run is set, and prints a final status summary.

20
internal/cli/validate.go
View File

@@ -2,6 +2,7 @@ package cli
import (
"context"
"flag"
"fmt"
"io"
@@ -13,11 +14,21 @@ func validateCommand(ctx context.Context, args []string, stdout, stderr io.Write
printValidateHelp(stdout)
return exitOK
}
path, ok := parseOptionalPathArg(stderr, "validate", args)
flags := flag.NewFlagSet("validate", flag.ContinueOnError)
flags.SetOutput(stderr)
formatFlag := addFormatFlag(flags)
if err := flags.Parse(args); err != nil {
return exitUsage
}
format, ok := parseOutputFormat(stderr, "validate", *formatFlag)
if !ok {
return exitUsage
}
if err := app.Validate(ctx, app.ValidateOptions{Path: path, Stdout: stdout}); err != nil {
path, ok := parseOptionalPathArg(stderr, "validate", flags.Args())
if !ok {
return exitUsage
}
if err := app.Validate(ctx, app.ValidateOptions{Path: path, Stdout: stdout, OutputFormat: format}); err != nil {
return fail(stderr, err)
}
return exitOK
@@ -25,7 +36,10 @@ func validateCommand(ctx context.Context, args []string, stdout, stderr io.Write
func printValidateHelp(w io.Writer) {
fmt.Fprint(w, `Usage:
distributor validate <path>
distributor validate [--format text|json] <path>
Options:
--format text|json Output format
Validate a local source bundle directory or a tree containing source bundles.
`)

33
internal/cli/version.go
View File

@@ -2,6 +2,7 @@ package cli
import (
"context"
"flag"
"fmt"
"io"
@@ -13,16 +14,44 @@ func versionCommand(_ context.Context, args []string, stdout, stderr io.Writer)
printVersionHelp(stdout)
return exitOK
}
if rejectExtraArgs(stderr, "version", args) {
flags := flag.NewFlagSet("version", flag.ContinueOnError)
flags.SetOutput(stderr)
formatFlag := addFormatFlag(flags)
if err := flags.Parse(args); err != nil {
return exitUsage
}
if rejectExtraArgs(stderr, "version", flags.Args()) {
return exitUsage
}
format, ok := parseOutputFormat(stderr, "version", *formatFlag)
if !ok {
return exitUsage
}
if app.IsJSONOutput(format) {
err := app.WriteJSONEnvelope(stdout, "version", true, nil, versionResult{
Application: app.Name,
Version: app.Version,
}, nil)
if err != nil {
return fail(stderr, err)
}
return exitOK
}
fmt.Fprintln(stdout, app.VersionString())
return exitOK
}
type versionResult struct {
Application string `json:"application"`
Version string `json:"version"`
}
func printVersionHelp(w io.Writer) {
fmt.Fprint(w, `Usage:
distributor version
distributor version [--format text|json]
Options:
--format text|json Output format
Print version information.
`)