feat(#29): --output-json for dataset push (PR-b)

internal/cli/coverage_test.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
 	"os"
 	"path/filepath"
@@ -13,6 +14,7 @@ import (
 
 	"github.com/tracebloc/cli/internal/cluster"
 	"github.com/tracebloc/cli/internal/push"
+	"github.com/tracebloc/cli/internal/submit"
 	"github.com/tracebloc/cli/internal/ui"
 )
 
@@ -61,6 +63,64 @@ func TestPrintPushPreflight_RendersKeyFacts(t *testing.T) {
 	}
 }
 
+// TestWritePushJSON checks the --output-json result serializes to
+// valid JSON with the expected fields.
+func TestWritePushJSON(t *testing.T) {
+	spec := map[string]any{"table": "reg_train", "category": "tabular_regression", "intent": "train"}
+	s := &submit.Summary{IngestorID: "run-1", TotalRecords: 240, InsertedRecords: 240, APISentRecords: 240}
+
+	var buf bytes.Buffer
+	writePushJSON(&buf, "succeeded", spec, s, "ns1", "ingest-job-x")
+
+	var got pushJSONResult
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+ t.Fatalf("output is not valid JSON: %v\n%s", err, buf.String())
+	}
+	if got.Status != "succeeded" || got.Table != "reg_train" || got.JobName != "ingest-job-x" {
+ t.Errorf("unexpected result: %+v", got)
+	}
+	if got.Summary == nil || got.Summary.InsertedRecords != 240 {
+ t.Errorf("summary missing/wrong: %+v", got.Summary)
+	}
+}
+
+// TestClassifyPushOutcome pins the --output-json status ↔ exit-code
+// contract (Bugbot #38): the status must agree with the exit code on
+// every path — a partial-failure must NOT report "succeeded", and a
+// watch error must still classify (so JSON gets emitted). wantCode 0
+// means no exitError (success).
+func TestClassifyPushOutcome(t *testing.T) {
+	resp := &submit.SubmitResponse{Namespace: "ns1", JobName: "ingest-job-x"}
+	cases := []struct {
+ name string
+ res *submit.Result
+ err error
+ wantStat string
+ wantCode int
+	}{
+ {"clean", &submit.Result{Submit: resp, Watch: &submit.WatchResult{Outcome: submit.JobOutcomeSucceeded, Summary: &submit.Summary{TotalRecords: 10, InsertedRecords: 10}}}, nil, "succeeded", 0},
+ {"partial", &submit.Result{Submit: resp, Watch: &submit.WatchResult{Outcome: submit.JobOutcomeSucceeded, Summary: &submit.Summary{TotalRecords: 10, InsertedRecords: 7, FailedRecords: 3}}}, nil, "completed_with_failures", 9},
+ {"failed", &submit.Result{Submit: resp, Watch: &submit.WatchResult{Outcome: submit.JobOutcomeFailed}}, nil, "failed", 9},
+ {"detached", &submit.Result{Submit: resp}, nil, "detached", 0},
+ {"watch error", &submit.Result{Submit: resp}, &submit.WatchError{Err: errors.New("stream broke")}, "watch_error", 9},
+	}
+	for _, c := range cases {
+ t.Run(c.name, func(t *testing.T) {
+ gotStat, gotErr := classifyPushOutcome(c.res, c.err)
+ if gotStat != c.wantStat {
+ t.Errorf("status = %q, want %q", gotStat, c.wantStat)
+ }
+ code := 0
+ if gotErr != nil {
+ code = gotErr.Code()
+ }
+ if code != c.wantCode {
+ t.Errorf("exit code = %d, want %d", code, c.wantCode)
+ }
+ })
+	}
+}
+
 // TestExitError_Methods pins the exit-code carrier: Error() surfaces
 // the wrapped message (or a fallback when nil), and Code() returns the
 // process exit code main() propagates.

internal/cli/dataset.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -83,8 +84,9 @@ func newDatasetPushCmd() *cobra.Command {
  numberOfKeypoints int
 
  // Operations flags.
- dryRun bool
- noInput bool
+ dryRun bool
+ noInput bool
+ outputJSON bool
 
  // Ingestor SA name override. Used as the ServiceAccountName
  // of the ephemeral stage Pod, so the Pod inherits whatever
@@ -157,12 +159,22 @@ Exit codes:
  // for whatever's still missing. Off a TTY / with --no-input,
  // prompter stays nil and runDatasetPush keeps flag-only
  // behavior.
- interactive := !noInput && isInteractiveTTY()
+ interactive := !noInput && !outputJSON && isInteractiveTTY()
  var pr prompter
  if interactive {
  pr = surveyPrompter{}
  }
- return runDatasetPush(cmd.Context(), cmd.OutOrStdout(), cmd.ErrOrStderr(),
+ // In --output-json mode, human output goes to stderr so
+ // stdout carries only the JSON result.
+ humanOut := cmd.OutOrStdout()
+ printer := printerFor(cmd)
+ var jsonOut io.Writer
+ if outputJSON {
+ humanOut = cmd.ErrOrStderr()
+ printer = printerForWriter(cmd, cmd.ErrOrStderr())
+ jsonOut = cmd.OutOrStdout()
+ }
+ return runDatasetPush(cmd.Context(), humanOut, cmd.ErrOrStderr(),
  runDatasetPushArgs{
  LocalPath: localPath,
  Kubeconfig: kubeconfigPath,
@@ -181,10 +193,12 @@ Exit codes:
  Detach: detach,
  IdempotencyKey: idempotencyKey,
  ImageDigest: imageDigest,
- Printer: printerFor(cmd),
+ Printer: printer,
  Interactive: interactive,
  Prompter: pr,
  CategorySet: cmd.Flags().Changed("category"),
+ OutputJSON: outputJSON,
+ JSONOut: jsonOut,
  })
  },
 	}
@@ -228,6 +242,8 @@ Exit codes:
  "validate + discover + walk, but don't create any cluster resources")
 	cmd.Flags().BoolVar(&noInput, "no-input", false,
  "disable interactive prompts; fail on missing required values (for CI/scripts)")
+	cmd.Flags().BoolVar(&outputJSON, "output-json", false,
+ "emit a machine-readable JSON result on stdout (human output → stderr; implies --no-input)")
 	cmd.Flags().StringVar(&ingestorSAName, "ingestor-sa", "",
  "override the ingestor ServiceAccount name (default: \"ingestor\"); "+
  "set this if you customized ingestionAuthz.serviceAccountName in the parent client chart")
@@ -278,6 +294,12 @@ type runDatasetPushArgs struct {
 	Prompter prompter
 	CategorySet bool
 
+	// OutputJSON routes human output to stderr and emits a JSON result
+	// to JSONOut (stdout); set together by the RunE in --output-json
+	// mode (which also forces non-interactive).
+	OutputJSON bool
+	JSONOut io.Writer
+
 	// Phase 4 (#152) fields. See the flag declarations for the
 	// per-knob rationale; all three are optional.
 	Detach bool
@@ -528,6 +550,9 @@ func runDatasetPush(ctx context.Context, out, errOut io.Writer, a runDatasetPush
 	// 8. Dry-run stop. Acknowledged success.
 	if a.DryRun {
  _, _ = fmt.Fprintln(out, "Dry-run complete — no cluster resources were created.")
+ if a.OutputJSON {
+ writePushJSON(a.JSONOut, "dry-run", spec, nil, "", "")
+ }
  return nil
 	}
 
@@ -625,48 +650,73 @@ func runDatasetPush(ctx context.Context, out, errOut io.Writer, a runDatasetPush
  Out: out,
  Printer: a.Printer,
 	})
+	// Classify once: a machine-readable status + the process exit error
+	// in lockstep, so --output-json emits exactly one result object on
+	// EVERY path (success / partial / failure / submit-or-watch error)
+	// whose status matches the exit code. (Bugbot #38.)
+	status, exitErr := classifyPushOutcome(submitRes, err)
+
+	if a.OutputJSON {
+ var summary *submit.Summary
+ var ns, jobName string
+ if submitRes != nil {
+ if submitRes.Watch != nil {
+ summary = submitRes.Watch.Summary
+ }
+ if submitRes.Submit != nil {
+ ns, jobName = submitRes.Submit.Namespace, submitRes.Submit.JobName
+ }
+ }
+ writePushJSON(a.JSONOut, status, spec, summary, ns, jobName)
+	}
+
+	if exitErr != nil {
+ return exitErr
+	}
+	return nil
+}
+
+// classifyPushOutcome maps the result of submit.Run to a machine-
+// readable status string + the process exit error, kept in lockstep so
+// --output-json's status always agrees with the exit code (a nil
+// *exitError = success, exit 0). It also covers the error paths
+// (auth/submit/watch) so --output-json can still emit a result object
+// when submit.Run returns an error. (Bugbot #38.)
+func classifyPushOutcome(res *submit.Result, err error) (string, *exitError) {
 	if err != nil {
  switch {
  case submit.IsAuthError(err):
- return &exitError{code: 5, err: err}
+ return "auth_error", &exitError{code: 5, err: err}
  case submit.IsWatchError(err):
- // Watch-phase failure: jobs-manager already accepted
- // the run, the cluster is doing the work, the CLI
- // just couldn't follow along. Exit 9 (ingest-side)
- // not 8 (submit-side). Bugbot flagged the
- // previously-undifferentiated mapping on PR #10.
- return &exitError{code: 9, err: err}
+ // jobs-manager accepted the run; the cluster is doing the
+ // work, the CLI just couldn't follow along — ingest-side
+ // (exit 9), not submit-side (8).
+ return "watch_error", &exitError{code: 9, err: err}
  default:
- return &exitError{code: 8, err: err}
+ return "submit_error", &exitError{code: 8, err: err}
  }
 	}
-
-	// Detach paths (--detach flag OR SIGINT-mid-watch) are
-	// success — cluster keeps running; the orchestrator already
-	// printed the reconnect hint.
-	if submitRes.Watch == nil || submitRes.Watch.Outcome == submit.JobOutcomeDetached {
- return nil
+	// --detach (no watch) or SIGINT-mid-watch: success; cluster runs on.
+	if res == nil || res.Watch == nil || res.Watch.Outcome == submit.JobOutcomeDetached {
+ return "detached", nil
 	}
-
-	// Watch outcomes. Both Failed and Unknown route to exit 9
-	// (Unknown = finalJobStatus timed out without seeing a
-	// terminal condition, which we can't claim as success).
-	// Bugbot flagged the prior switch's missing Unknown branch
-	// on PR #10.
-	switch submitRes.Watch.Outcome {
+	switch res.Watch.Outcome {
 	case submit.JobOutcomeFailed:
- return &exitError{code: 9, err: errors.New("ingestion Job exited non-zero — see logs above")}
+ return "failed", &exitError{code: 9, err: errors.New("ingestion Job exited non-zero — see logs above")}
 	case submit.JobOutcomeUnknown:
- return &exitError{code: 9, err: errors.New(
+ return "unknown", &exitError{code: 9, err: errors.New(
  "ingestion Job's final status couldn't be determined within the watch window — " +
- "check `kubectl get job -n " + submitRes.Submit.Namespace + " " + submitRes.Submit.JobName + "` for the outcome")}
+ "check `kubectl get job -n " + res.Submit.Namespace + " " + res.Submit.JobName + "` for the outcome")}
 	case submit.JobOutcomeSucceeded:
- if submitRes.Watch.Summary != nil && submitRes.Watch.Summary.HasFailures() {
- return &exitError{code: 9, err: errors.New(
+ // Job exited 0, but rows can still have failed — exit 9, and the
+ // JSON status must say so, NOT "succeeded". (Bugbot #38.)
+ if res.Watch.Summary != nil && res.Watch.Summary.HasFailures() {
+ return "completed_with_failures", &exitError{code: 9, err: errors.New(
  "ingestion Job completed but the summary reports failures — see panel above")}
  }
+ return "succeeded", nil
 	}
-	return nil
+	return "unknown", nil
 }
 
 // printPushPreflight is the customer-facing summary. Mirrors
@@ -738,3 +788,58 @@ func printPushPreflight(
  layout.FileCount(), push.HumanBytes(layout.TotalBytes), spec["table"])
 	}
 }
+
+// pushJSONResult is the machine-readable shape emitted by --output-json.
+// It's a presentation type owned by the CLI layer, so submit.Summary
+// stays json-tag-free and this wire format can evolve independently.
+type pushJSONResult struct {
+	Status string `json:"status"` // dry-run|succeeded|completed_with_failures|failed|detached|unknown|auth_error|submit_error|watch_error
+	Table string `json:"table"`
+	Category string `json:"category"`
+	Intent string `json:"intent"`
+	Namespace string `json:"namespace,omitempty"`
+	JobName string `json:"job_name,omitempty"`
+	Summary *pushJSONSummary `json:"summary,omitempty"`
+}
+
+type pushJSONSummary struct {
+	IngestorID string `json:"ingestor_id,omitempty"`
+	TotalRecords int64 `json:"total_records"`
+	InsertedRecords int64 `json:"inserted_records"`
+	SentToAPI int64 `json:"sent_to_api"`
+	SkippedRecords int64 `json:"skipped_records"`
+	FileTransferFailures int64 `json:"file_transfer_failures"`
+	DBInsertFailures int64 `json:"db_insert_failures"`
+	SuccessRate float64 `json:"success_rate"`
+}
+
+// writePushJSON serializes the push result to w (stdout in
+// --output-json mode). Errors are dropped: marshaling our own struct
+// can't fail in practice, and the exit code remains the contract.
+func writePushJSON(w io.Writer, status string, spec map[string]any, s *submit.Summary, ns, jobName string) {
+	res := pushJSONResult{
+ Status: status,
+ Table: fmt.Sprintf("%v", spec["table"]),
+ Category: fmt.Sprintf("%v", spec["category"]),
+ Intent: fmt.Sprintf("%v", spec["intent"]),
+ Namespace: ns,
+ JobName: jobName,
+	}
+	if s != nil {
+ res.Summary = &pushJSONSummary{
+ IngestorID: s.IngestorID,
+ TotalRecords: s.TotalRecords,
+ InsertedRecords: s.InsertedRecords,
+ SentToAPI: s.APISentRecords,
+ SkippedRecords: s.SkippedRecords,
+ FileTransferFailures: s.FileTransferFailures,
+ DBInsertFailures: s.FailedRecords,
+ SuccessRate: s.SuccessRate(),
+ }
+	}
+	b, err := json.MarshalIndent(res, "", " ")
+	if err != nil {
+ return
+	}
+	_, _ = fmt.Fprintln(w, string(b))
+}

internal/cli/root.go

@@ -7,6 +7,8 @@
 package cli
 
 import (
+	"io"
+
 	"github.com/spf13/cobra"
 
 	"github.com/tracebloc/cli/internal/ui"
@@ -105,8 +107,15 @@ what's planned next.`,
 // in ui.New; --plain just forces it off. Commands call this at the top
 // of their RunE.
 func printerFor(cmd *cobra.Command) *ui.Printer {
+	return printerForWriter(cmd, cmd.OutOrStdout())
+}
+
+// printerForWriter is printerFor for an explicit writer — used by
+// dataset push's --output-json mode, which routes human output to
+// stderr so stdout carries only the JSON result.
+func printerForWriter(cmd *cobra.Command, w io.Writer) *ui.Printer {
 	if plain, _ := cmd.Flags().GetBool("plain"); plain {
- return ui.New(cmd.OutOrStdout(), ui.WithColor(false))
+ return ui.New(w, ui.WithColor(false))
 	}
-	return ui.New(cmd.OutOrStdout())
+	return ui.New(w)
 }