// `carlos pipeline` — release pipelines v2
// (docs/superpowers/specs/2026-08-20-release-pipelines-v2-design.md): show
// or shape an app's declared channel list, and see what an edit is waiting
// on.
//
// API mode only, deliberately, like fleets and logs: a pipeline is
// console-tracked policy (spec §2/§4), with nothing in the bucket for a
// direct-mode CLI to read or write in its place. Every subcommand composes
// its whole write client-side — GET the current list, mutate it, PUT the
// whole thing back — because the console is the validator and the gate
// (guardedEdit, member-count ceiling, shape checks all live server-side);
// this file never second-guesses any of that, it only builds the list a
// human meant and lets the console answer.
package main

import (
	"context"
	"errors"
	"flag"
	"fmt"
	"io"
	"log"
	"strings"
)

const pipelineUsage = `usage: carlos pipeline <command>

commands:
  show                       show an app's channels and any pending changes
                              (this is also what a bare "carlos pipeline"
                              runs)
  init   --template edge-production|full-ladder
                              replace the pipeline with a starter template
  set    --channel <name> [--bake <dur>] [--passkey[=false]]
         [--promote-approvals N] [--change-approvals N]
                              edit one existing channel's bake window or
                              rules — flags not given are left as they were
  add    --channel <name> [--after <name>] [--bake <dur>] [--passkey]
         [--promote-approvals N] [--change-approvals N]
                              insert a new channel (default: appended at the
                              end of the list; --after inserts right after
                              that existing channel)
  remove --channel <name>     drop a channel from the pipeline

Every command above also takes [--app <a>] [--account <sqid-or-name>]
[--account-id <sqid>] [--console <origin>] — the same account/app resolution
every other API-mode verb uses (defaults apply when a flag is omitted and
only one candidate exists).

carlos pipeline works through a logged-in console (carlos auth login) —
there is no bucket-direct pipeline editor to fall back to; --bake, --passkey,
--promote-approvals and --change-approvals set release.ChannelRules exactly as
the console's own pipeline settings page does. promote and rollback are
unaffected in direct mode.

set/add/remove all read the CURRENT channel list first and PUT the whole
list back — an edit that touches a channel the stored pipeline already
guards with --change-approvals does not land from here: the console turns it
into a proposal instead (0 confirmations; finish with the printed console
URL), exactly as it does for a guarded promote or rollback.
`

// runPipeline dispatches `carlos pipeline`'s subcommands. Unlike RunEnv/
// RunFleets/RunLedger, an unrecognized first word is not itself an error —
// it falls through to runPipelineShow's own flag parsing, which is where
// "show" lives as the DEFAULT (bare `carlos pipeline`, or `carlos pipeline
// --app foo` with no subcommand word at all) — the same shape runInstances
// (cli.go) gives its own bare-listing default.
func runPipeline(args []string) {
	if len(args) > 0 {
		switch args[0] {
		case "init":
			runPipelineInit(args[1:])
			return
		case "set":
			runPipelineSet(args[1:])
			return
		case "add":
			runPipelineAdd(args[1:])
			return
		case "remove":
			runPipelineRemove(args[1:])
			return
		case "show":
			runPipelineShow(args[1:])
			return
		}
	}
	runPipelineShow(args)
}

// pipelineSignedInSession resolves API mode and fatals with a
// pipeline-specific message when this shell is in direct bucket mode —
// mirrors fleetsSignedInSession (fleets.go) exactly: a pipeline is
// console-tracked policy with nothing in the bucket to fall back to, so
// there is no second, bucket-direct implementation of any of this to keep
// in sync.
func pipelineSignedInSession(consoleFlag string) *apiSession {
	sess, err := resolveMode(consoleFlag)
	if err != nil {
		log.Fatal(err)
	}
	if sess == nil {
		log.Fatal("carlos pipeline works through a console, and this shell is in direct bucket mode\n" +
			"(CARLOS_DEPLOYMENT_BUCKET/CARLOS_DEPLOYMENT_DIR is set). A pipeline is console-tracked\n" +
			"policy with no bucket-direct editor: unset the store env and run\n" +
			"carlos auth login --console <url> instead. promote and rollback are unaffected.")
	}
	return sess
}

// pipelineFlagSet builds the --app/--account/--account-id/--console flags every
// pipeline subcommand shares, with fs.Usage set to the shared doc block
// (the "current style" this binary's more heavily-documented verbs use —
// logs.go's runLogs is the model) so "-h" on any subcommand explains every
// subcommand, not just the one typed.
func pipelineFlagSet(name string) (fs *flag.FlagSet, app, acctRaw, acctIDRaw, consoleFlag *string) {
	fs = flag.NewFlagSet(name, flag.ExitOnError)
	app = appFlag(fs, "")
	// API mode never opens the local registry — the third return
	// (accountFlags' direct-mode resolver) has no use here and is dropped.
	acctRaw, acctIDRaw, _ = accountFlags(fs)
	consoleFlag = consoleOption(fs, "console origin to work through (default: the only logged-in one)")
	fs.Usage = flagUsage(fs, pipelineUsage)
	return fs, app, acctRaw, acctIDRaw, consoleFlag
}

// pipelineOrDefault is GetPipeline's (nil, nil) "no pipeline.json" case
// turned into the same one-channel starter release.DefaultPipelineChannels()
// gives the console's own settings page (pipelinepage.go) — so a fresh app's
// `carlos pipeline show` reads the same "edge" starter row the console would
// draft for it, and `set`/`add`/`remove` compose on top of that same
// starting point rather than an empty list. Always returns a fresh slice:
// callers mutate what they get back, and must never alias a cached response.
func pipelineOrDefault(p *apiPipeline) []apiPipelineChannel {
	if p == nil || len(p.Channels) == 0 {
		return []apiPipelineChannel{{Name: "edge"}}
	}
	out := make([]apiPipelineChannel, len(p.Channels))
	copy(out, p.Channels)
	return out
}

// pipelineTemplate is the two starters spec §5 names, byte-for-byte what the
// console's own settings page offers (edgeProductionTemplate/
// fullLadderTemplate, internal/console/pipelinepage.go) — CONTROLLER RULING:
// any template that sets a rule on a channel also sets change_approvals, so
// a passkey nobody can strip with one bearer-token PUT.
func pipelineTemplate(name string) ([]apiPipelineChannel, bool) {
	switch name {
	case "edge-production":
		return []apiPipelineChannel{
			{Name: "edge"},
			{Name: "production", Bake: "24h", Passkey: true, ChangeApprovals: 1},
		}, true
	case "full-ladder":
		return []apiPipelineChannel{
			{Name: "edge"},
			{Name: "beta", Bake: "24h"},
			{Name: "stable", Bake: "72h", Passkey: true, ChangeApprovals: 1},
		}, true
	default:
		return nil, false
	}
}

// applyPipelinePut is set/add/remove/init's shared tail: PUT the composed
// list, and tell a landed write, a proposal, and a genuine refusal apart —
// the same errors.As check runPromote/runRollback use, so a
// `carlos pipeline` edit that the console proposes instead of landing prints
// the SAME "proposed" line those verbs print rather than the misleading
// "unexpected response (status 202)" apiErrorFromBody would otherwise give
// it.
func applyPipelinePut(sess *apiSession, acct apiAcct, app string, channels []apiPipelineChannel) {
	set, err := sess.pipelinePut(context.Background(), acct, app, channels)
	if err != nil {
		var prop *apiProposedError
		if errors.As(err, &prop) {
			printProposed(stdout, prop)
			return
		}
		log.Fatal(err)
	}
	fmt.Fprintf(stdout, "%s the pipeline for %s\n", colorFor(stdout).ok("set"), app)
	printPipelineChannels(stdout, set.Channels)
}

// printPipelineChannels is `show`'s multi-channel rendering, and every write
// verb's confirmation echo: ORDER/BAKE/RULES, one row per channel, in
// pipeline order — position IS the promotion order, which is why it is
// spelled into the ORDER cell rather than left to be inferred from row
// position alone (a table copied into a chat message still says "2 beta").
func printPipelineChannels(w io.Writer, channels []apiPipelineChannel) {
	t := newTable(w)
	fmt.Fprintln(t, "ORDER\tBAKE\tRULES")
	for i, c := range channels {
		fmt.Fprintf(t, "%d %s\t%s\t%s\n", i+1, c.Name, pipelineBakeCell(c.Bake), pipelineRulesCell(c))
	}
	t.Flush()
}

func pipelineBakeCell(bake string) string {
	if bake == "" {
		return "-"
	}
	return bake
}

// pipelineRulesCell names a channel's ChannelRules in the same vocabulary
// --promote-approvals/--change-approvals/--passkey use, so what a human reads
// here is what they'd type to reproduce it.
func pipelineRulesCell(c apiPipelineChannel) string {
	var parts []string
	if c.Passkey {
		parts = append(parts, "passkey")
	}
	if c.PromoteApprovals > 0 {
		parts = append(parts, fmt.Sprintf("promote:%d", c.PromoteApprovals))
	}
	if c.ChangeApprovals > 0 {
		parts = append(parts, fmt.Sprintf("change:%d", c.ChangeApprovals))
	}
	if len(parts) == 0 {
		return "-"
	}
	return strings.Join(parts, ", ")
}

// printPipelinePending renders `show`'s pending-changes section — nothing at
// all when there is nothing pending, matching the console app page's own
// card, which likewise only appears when PendingChangesFor returns rows.
func printPipelinePending(w io.Writer, pending []apiPending) {
	if len(pending) == 0 {
		return
	}
	fmt.Fprintln(w)
	fmt.Fprintln(w, colorFor(w).head("pending:"))
	for _, pc := range pending {
		fmt.Fprintf(w, "  %s — %d/%d confirmed (id %s)\n", pc.Summary, pc.Confirmed, pc.Needed, pc.ID)
	}
}

// runPipelineShow is `carlos pipeline` and `carlos pipeline show` alike —
// see runPipeline's doc comment for why an unrecognized subcommand word also
// lands here rather than being refused outright.
func runPipelineShow(args []string) {
	fs, app, acctRaw, acctIDRaw, consoleFlag := pipelineFlagSet("pipeline show")
	fs.Parse(args)
	if fs.NArg() != 0 {
		log.Fatal(pipelineUsage)
	}

	sess := pipelineSignedInSession(*consoleFlag)
	printUsing(stdout, sess)
	acct := resolvedAccount(sess, acctRaw, acctIDRaw)
	app2 := resolvedApp(sess, acct, *app, pipelineUsage)

	p, err := sess.pipelineGet(context.Background(), acct, app2)
	if err != nil {
		log.Fatal(err)
	}
	channels := pipelineOrDefault(p)
	// A single-channel pipeline (the "no pipeline.json" default, or a real
	// one-channel pipeline someone composed down to that) is not shown as a
	// one-row ladder table — there is no order or rule to tabulate yet, and
	// a table with one row reads as ceremony around nothing (Task 10
	// controller ruling 5). The hint names the one command that grows it.
	if len(channels) == 1 {
		fmt.Fprintf(stdout, "%s — one channel, no pipeline set (carlos pipeline init --template edge-production|full-ladder adds more)\n",
			channels[0].Name)
	} else {
		printPipelineChannels(stdout, channels)
	}

	pending, err := sess.pendingList(context.Background(), acct, app2)
	if err != nil {
		log.Fatal(err)
	}
	printPipelinePending(stdout, pending)
}

// runPipelineInit replaces the whole pipeline with one of the two starter
// templates spec §5 names — the console-side equivalent of clicking a
// template button on the settings page, over the API.
func runPipelineInit(args []string) {
	fs, app, acctRaw, acctIDRaw, consoleFlag := pipelineFlagSet("pipeline init")
	template := fs.String("template", "", "starter pipeline: edge-production | full-ladder")
	fs.Parse(args)

	channels, ok := pipelineTemplate(*template)
	if !ok {
		log.Fatal("usage: carlos pipeline init --template edge-production|full-ladder [--app <a>] [--account <sqid-or-name>] [--account-id <sqid>] [--console <origin>]")
	}

	sess := pipelineSignedInSession(*consoleFlag)
	printUsing(stdout, sess)
	acct := resolvedAccount(sess, acctRaw, acctIDRaw)
	app2 := resolvedApp(sess, acct, *app, pipelineUsage)

	applyPipelinePut(sess, acct, app2, channels)
}

// pipelinePolicyFlags are the four rule-shaping flags set and add share.
// Registered once so their help text and names can never drift between the
// two subcommands.
func pipelinePolicyFlags(fs *flag.FlagSet) (bake *string, passkey *bool, promoteApprovals, changeApprovals *int) {
	bake = fs.String("bake", "", "bake window before this channel is eligible to adopt (Go duration, e.g. 24h; \"\" clears it)")
	passkey = fs.Bool("passkey", false, "require a console passkey to promote into or edit this channel; --passkey=false clears it")
	promoteApprovals = fs.Int("promote-approvals", 0, "promotions into this channel need this many console confirmations (0 clears the rule)")
	changeApprovals = fs.Int("change-approvals", 0, "pipeline edits that touch this channel need this many console confirmations (0 clears the rule)")
	return bake, passkey, promoteApprovals, changeApprovals
}

// runPipelineSet edits ONE existing channel's bake window or rules. It GETs
// the full current list, applies only the flags actually named on the
// command line (fs.Visit — the same tri-state pattern runRoute's --hibernate/
// --backing/--unit already use, cli.go) so an unmentioned flag never clobbers
// a rule someone else set, and PUTs the whole list back.
func runPipelineSet(args []string) {
	fs, app, acctRaw, acctIDRaw, consoleFlag := pipelineFlagSet("pipeline set")
	channel := channelFlag(fs, "channel to edit")
	bake, passkey, promoteApprovals, changeApprovals := pipelinePolicyFlags(fs)
	fs.Parse(args)
	usage := "usage: carlos pipeline set --channel <name> [--app <a>] [--bake <dur>] [--passkey[=false]] " +
		"[--promote-approvals N] [--change-approvals N] [--account <sqid-or-name>] [--account-id <sqid>] [--console <origin>]"
	if *channel == "" {
		log.Fatal(usage)
	}
	bakeSet, passkeySet, promoteSet, changeSet := false, false, false, false
	fs.Visit(func(f *flag.Flag) {
		switch f.Name {
		case "bake":
			bakeSet = true
		case "passkey":
			passkeySet = true
		case "promote-approvals":
			promoteSet = true
		case "change-approvals":
			changeSet = true
		}
	})

	sess := pipelineSignedInSession(*consoleFlag)
	printUsing(stdout, sess)
	acct := resolvedAccount(sess, acctRaw, acctIDRaw)
	app2 := resolvedApp(sess, acct, *app, usage)

	p, err := sess.pipelineGet(context.Background(), acct, app2)
	if err != nil {
		log.Fatal(err)
	}
	channels := pipelineOrDefault(p)
	idx := -1
	for i, c := range channels {
		if c.Name == *channel {
			idx = i
			break
		}
	}
	if idx == -1 {
		log.Fatalf("pipeline set: %q is not a channel of this pipeline — carlos pipeline add --channel %s to create it", *channel, *channel)
	}
	if bakeSet {
		channels[idx].Bake = *bake
	}
	if passkeySet {
		channels[idx].Passkey = *passkey
	}
	if promoteSet {
		channels[idx].PromoteApprovals = *promoteApprovals
	}
	if changeSet {
		channels[idx].ChangeApprovals = *changeApprovals
	}
	applyPipelinePut(sess, acct, app2, channels)
}

// runPipelineAdd inserts a new channel. --after names an existing channel to
// insert immediately behind; omitted, the new channel is appended at the
// end (entering the pipeline as its newest, most-downstream rung — never
// silently made the ENTRY channel, which --after edge would spell instead).
func runPipelineAdd(args []string) {
	fs, app, acctRaw, acctIDRaw, consoleFlag := pipelineFlagSet("pipeline add")
	channel := channelFlag(fs, "channel to add")
	after := fs.String("after", "", "insert immediately after this existing channel (default: append at the end)")
	bake, passkey, promoteApprovals, changeApprovals := pipelinePolicyFlags(fs)
	fs.Parse(args)
	usage := "usage: carlos pipeline add --channel <name> [--after <name>] [--app <a>] [--bake <dur>] [--passkey] " +
		"[--promote-approvals N] [--change-approvals N] [--account <sqid-or-name>] [--account-id <sqid>] [--console <origin>]"
	if *channel == "" {
		log.Fatal(usage)
	}

	sess := pipelineSignedInSession(*consoleFlag)
	printUsing(stdout, sess)
	acct := resolvedAccount(sess, acctRaw, acctIDRaw)
	app2 := resolvedApp(sess, acct, *app, usage)

	p, err := sess.pipelineGet(context.Background(), acct, app2)
	if err != nil {
		log.Fatal(err)
	}
	channels := pipelineOrDefault(p)
	for _, c := range channels {
		if c.Name == *channel {
			log.Fatalf("pipeline add: %q already exists in this pipeline — carlos pipeline set to edit it", *channel)
		}
	}
	entry := apiPipelineChannel{
		Name: *channel, Bake: *bake, Passkey: *passkey,
		PromoteApprovals: *promoteApprovals, ChangeApprovals: *changeApprovals,
	}
	pos := len(channels)
	if *after != "" {
		pos = -1
		for i, c := range channels {
			if c.Name == *after {
				pos = i + 1
				break
			}
		}
		if pos == -1 {
			log.Fatalf("pipeline add: --after %q does not name an existing channel of this pipeline", *after)
		}
	}
	next := make([]apiPipelineChannel, 0, len(channels)+1)
	next = append(next, channels[:pos]...)
	next = append(next, entry)
	next = append(next, channels[pos:]...)
	applyPipelinePut(sess, acct, app2, next)
}

// runPipelineRemove drops one channel from the pipeline. It never refuses on
// emptying the list to zero channels itself — SetPipeline's own validation
// (internal/release/pipeline.go) is where that shape check belongs, exactly
// as it is the one place every other pipeline shape rule is enforced.
func runPipelineRemove(args []string) {
	fs, app, acctRaw, acctIDRaw, consoleFlag := pipelineFlagSet("pipeline remove")
	channel := channelFlag(fs, "channel to remove")
	fs.Parse(args)
	usage := "usage: carlos pipeline remove --channel <name> [--app <a>] [--account <sqid-or-name>] [--account-id <sqid>] [--console <origin>]"
	if *channel == "" {
		log.Fatal(usage)
	}

	sess := pipelineSignedInSession(*consoleFlag)
	printUsing(stdout, sess)
	acct := resolvedAccount(sess, acctRaw, acctIDRaw)
	app2 := resolvedApp(sess, acct, *app, usage)

	p, err := sess.pipelineGet(context.Background(), acct, app2)
	if err != nil {
		log.Fatal(err)
	}
	channels := pipelineOrDefault(p)
	next := make([]apiPipelineChannel, 0, len(channels))
	found := false
	for _, c := range channels {
		if c.Name == *channel {
			found = true
			continue
		}
		next = append(next, c)
	}
	if !found {
		log.Fatalf("pipeline remove: %q is not a channel of this pipeline", *channel)
	}
	applyPipelinePut(sess, acct, app2, next)
}