// Copyright 2026 Alibaba Group
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package output

import (
	"bytes"
	"fmt"
	"io"
	"strings"

	"github.com/spf13/cobra"
)

// WriteEnvelope 是统一信封的出口函数（B0 dev 试点桥接，WS1 改动点2/4）。
// 它复用 envelope.go 的权威 Envelope 类型，把信封按当前 --format 分发写出。
// Phase B 的 Emitter 类型将在此之上泛化（渲染先进 buffer、exit code 映射等）；
// 本函数仅提供 Phase F dev 域迁移所需的「信封 → cmd 流」出口，不重复定义类型。
//
// format 分发（契约规范 §5.2，经 renderEnvelope 实现）：
//   - json（默认）：输出完整信封——唯一 JSON 契约（§5.2 首行）。
//   - table/pretty：业务数据人读视图 + meta 摘要（不输出信封外壳）。
//   - csv/ndjson：裸记录（无信封）；meta.pagination 走 stderr 诊断行。
//   - raw：数据载荷透传（与 Write 的 raw 语义一致）。
//
// 数据出口一律写 cmd.OutOrStdout()、诊断出口写 cmd.ErrOrStderr()（均可被
// 测试重定向），不硬编码 os.Stdout/os.Stderr。未知 --format 值按 §5.2/AC-09
// 降级 fallback 并在此向 stderr 写一条 warning（不崩不静默）。
func WriteEnvelope(cmd *cobra.Command, env *Envelope, fallback Format) error {
	w, errW := io.Writer(io.Discard), io.Writer(io.Discard)
	format := fallback
	fields, jq, warning := "", "", ""
	if cmd != nil {
		w = cmd.OutOrStdout()
		errW = cmd.ErrOrStderr()
		format, warning = resolveFormatWithWarning(cmd, fallback)
		fields = ResolveFields(cmd)
		jq = ResolveJQ(cmd)
	}
	if env == nil {
		env = nilFallbackEnvelope()
	}
	if err := renderEnvelope(w, errW, env, format, fields, jq); err != nil {
		return err
	}
	// AC-09「不静默」：warning 仅在信封成功写出后补写 stderr——
	// 写出失败时错误优先，不留半截通道。
	if warning != "" {
		if _, werr := fmt.Fprintln(errW, "[WARN] "+warning); werr != nil {
			return werr
		}
	}
	return nil
}

// WriteEnvelopeTo 是 WriteEnvelope 的 writer 级实现（签名自 B205 保持不变），
// 供不持有 *cobra.Command 的调用方与单测直接使用。B37 起收编到 renderEnvelope
// 统一分发：json/空 format 输出完整信封（唯一 JSON 契约）；table/pretty 输出
// 业务数据人读视图 + meta 摘要；csv/ndjson 输出裸记录（分页诊断行在本签名下
// 无 stderr 出口可走，按 io.Discard 处理——需要诊断行的调用方走 WriteEnvelope
// 的 cmd 路径或 Emitter）。nil 信封降级为 I3 合法的 failure 兜底信封（B208）：
// 携带 internal 类 ErrorInfo——框架最后的兜底不得产出被自身 Validate() 拒绝的形态。
func WriteEnvelopeTo(w io.Writer, env *Envelope, format Format, fields, jq string) error {
	if env == nil {
		env = nilFallbackEnvelope()
	}
	return renderEnvelope(w, io.Discard, env, format, fields, jq)
}

// EmitResult is the framework 2.0 CLI adapter. Unlike the legacy Emitter,
// machine-readable JSON/NDJSON always writes the primary result to stdout for
// every outcome; stderr is diagnostics-only. Human failure formats retain the
// conventional stderr path. The result is validated before any byte is
// rendered, and the returned exit code comes from the same immutable result.
func EmitResult(cmd *cobra.Command, result CommandResult) (int, error) {
	code, _, err := emitResult(cmd, result)
	return code, err
}

func emitResult(cmd *cobra.Command, result CommandResult) (int, bool, error) {
	if err := ValidateResult(result); err != nil {
		return exitCodeInternal, false, err
	}
	env := result.envelope()
	env = redactEnvelope(env)
	format, warning := resolveFormatWithWarning(cmd, FormatJSON)
	fields, jq := ResolveFields(cmd), ResolveJQ(cmd)
	stdout, stderr := io.Writer(io.Discard), io.Writer(io.Discard)
	if cmd != nil {
		stdout, stderr = cmd.OutOrStdout(), cmd.ErrOrStderr()
	}

	if env.Outcome == OutcomeFailure && format != FormatJSON && format != FormatNDJSON {
		message := "command failed"
		if env.Error != nil && strings.TrimSpace(env.Error.Message) != "" {
			message = env.Error.Message
		}
		var buf bytes.Buffer
		_, _ = fmt.Fprintln(&buf, "Error: "+message)
		n, err := writeAllCount(stderr, buf.Bytes())
		if err != nil {
			return exitCodeInternal, n > 0, err
		}
		return result.ExitCode(), n > 0, nil
	}

	// Failure bypasses jq/fields so a filter cannot erase the typed error.
	if env.Outcome == OutcomeFailure {
		fields, jq = "", ""
	}
	var buf bytes.Buffer
	if err := renderEnvelope(&buf, stderr, env, format, fields, jq); err != nil {
		return exitCodeInternal, false, err
	}
	n, err := writeAllCount(stdout, buf.Bytes())
	if err != nil {
		return exitCodeInternal, n > 0, err
	}
	if warning != "" {
		// The primary result is already complete. Diagnostics are best-effort
		// and must not reverse its outcome when stderr is unavailable.
		_, _ = fmt.Fprintln(stderr, "[WARN] "+warning)
	}
	return result.ExitCode(), n > 0, nil
}

// nilFallbackEnvelope 构造 nil 信封的兜底信封（B208，轮6裁决⑨）。保留
// 「不 panic、必产合法 failure」的既有语义，且自身满足不变量 I3
// （error 非空 ⇔ outcome==failure）、通过 Envelope.Validate()——框架出口
// 兜底不得被自己的校验器判非法。Type 取 "internal"：这是框架内部缺陷而非
// 业务错误（§4 internal=5），Agent 可据 wire-stable 字段分支处置。
func nilFallbackEnvelope() *Envelope {
	return &Envelope{
		OK:      false,
		Outcome: OutcomeFailure,
		Error: &ErrorInfo{
			Type:    "internal",
			Message: "nil envelope: framework fallback",
		},
	}
}

// ---------------------------------------------------------------------------
// format 分发（B35~B40）：信封 → format 矩阵的统一分发点
// （契约规范 §5.2；适用域仅 stdout 数据通道——轮8裁决⑪）
// ---------------------------------------------------------------------------

// renderEnvelope 是信封渲染的统一分发点（B37，WS1 改动点4；契约规范 §5.2
// format 矩阵）。渲染先进 buffer 再一次性写出：数据通道任何一步失败都不向
// w 泄漏半截输出（§5.2 末条；与 B25 buffer-first 同口径）。
//
// 矩阵各行（适用域仅 stdout 数据通道——失败信封在 Emitter 流路由层恒以
// 完整 JSON 写 stderr，从不进入本矩阵，轮8裁决⑪）：
//
//   - json / 空：完整信封——唯一 JSON 契约（§5.2 首行，B38）；
//   - table / pretty：业务数据人读视图 + meta 层人读摘要（count/pagination），
//     不输出信封外壳（§5.2 矩阵行，B39）；
//   - csv / ndjson：裸记录（无信封外壳）；meta.pagination 走 errW 的 stderr
//     诊断行，不污染裸记录机器可读流（§5.2 矩阵行，B40）；
//   - raw：数据载荷透传（writeRaw 语义）。
//
// --jq 优先于 format：对**完整信封**求值后直接输出结果（§5.2 矩阵行，B42）。
// --fields 先投影数据载荷再按 format 分发（成功通道联动）。errW 为 nil 时按
// io.Discard 处理（csv/ndjson 诊断行无出口即丢弃）。
//
// buffer-first 纪律：全部分发路径（含 json/jq）先渲染进内存 buffer，成功后
// 才一次性写出到 w（§5.2 末条对分发点整体成立）——渲染失败零泄漏、写出
// 失败原子中止、短写报 io.ErrShortWrite。csv/ndjson 的 stderr 诊断行不经
// buffer，且在数据渲染成功后才写（渲染失败不留诊断噪声）。
func renderEnvelope(w io.Writer, errW io.Writer, env *Envelope, format Format, fields, jq string) error {
	if errW == nil {
		errW = io.Discard
	}
	if env == nil {
		env = nilFallbackEnvelope()
	}
	env = redactEnvelope(env)
	var buf bytes.Buffer
	if err := renderEnvelopeInto(&buf, errW, env, format, fields, jq); err != nil {
		return err
	}
	return writeAll(w, buf.Bytes())
}

// renderEnvelopeInto 按 format 矩阵把信封渲染进 buf（renderEnvelope 的渲染段）。
func renderEnvelopeInto(buf *bytes.Buffer, errW io.Writer, env *Envelope, format Format, fields, jq string) error {
	// 失败信封不参与 format/fields/jq 分发（轮8裁决⑪；契约规范 §5.1 v1.1
	// 回写条款）：恒输出完整 JSON 信封。§5.2 矩阵适用域仅 stdout 数据通道，
	// 失败信封无 data 载荷（I3），若按矩阵分发或经 jq/fields 过滤，§2.4
	// wire-stable 字段组将从错误通道消失。
	if env.Outcome == OutcomeFailure {
		if format == FormatNDJSON {
			return Write(buf, FormatNDJSON, env)
		}
		return WriteFiltered(buf, FormatJSON, env, "", "")
	}
	if strings.TrimSpace(jq) != "" {
		// jq 优先于 format：对完整信封求值后直接输出（§5.2 矩阵行）。
		return ApplyJQ(buf, env, strings.TrimSpace(jq))
	}

	switch format {
	case FormatJSON, "":
		// json（默认）始终保留完整信封。--fields 只投影业务载荷，
		// ok/outcome/meta 等稳定契约字段仍必须可供 Agent 分支和续页。
		if trimmed := strings.TrimSpace(fields); trimmed != "" {
			projected := *env
			projected.Data = SelectFields(env.Data, strings.Split(trimmed, ","))
			return WriteFiltered(buf, FormatJSON, &projected, "", "")
		}
		return WriteFiltered(buf, FormatJSON, env, "", "")
	default:
	}

	payload := env.Data
	if trimmed := strings.TrimSpace(fields); trimmed != "" {
		payload = SelectFields(payload, strings.Split(trimmed, ","))
	}

	switch format {
	case FormatTable, FormatPretty:
		if err := Write(buf, format, payload); err != nil {
			return err
		}
		if summary := renderMetaSummary(env.Meta); summary != "" {
			_, _ = fmt.Fprintf(buf, "\n%s\n", summary)
		}
		return nil
	case FormatCSV, FormatNDJSON:
		if err := Write(buf, format, payload); err != nil {
			return err
		}
		// 分页元数据走 stderr 诊断行（§5.2 csv/ndjson 行）。partial_failure
		// 例外：§2.3 明确「stderr 零输出」，特例优先于 §5.2 诊断行通则。
		if env.Outcome != OutcomePartialFailure {
			return writePaginationDiagnostic(errW, env.Meta)
		}
		return nil
	case FormatRaw:
		return Write(buf, FormatRaw, payload)
	default:
		// 未知 Format 常量（归一化/ParseFormat 后理论不可达）：按 json
		// 数据通道语义兜底，绝不静默丢弃载荷。--fields 同样投影业务载荷。
		if trimmed := strings.TrimSpace(fields); trimmed != "" {
			return WriteFiltered(buf, FormatJSON, env.Data, trimmed, "")
		}
		return WriteFiltered(buf, FormatJSON, env, "", "")
	}
}

// writeAll 把 p 一次性写入 w；短写（接受了部分字节却未写全）报
// io.ErrShortWrite——与 Emitter.writeOnce 同一短写纪律，绝不把截断输出当成功。
func writeAll(w io.Writer, p []byte) error {
	_, err := writeAllCount(w, p)
	return err
}

func writeAllCount(w io.Writer, p []byte) (int, error) {
	n, err := w.Write(p)
	if err != nil {
		return n, err
	}
	if n < len(p) {
		return n, io.ErrShortWrite
	}
	return n, nil
}

// renderMetaSummary 把信封 meta 层渲染为人读摘要行（§5.2：table/pretty 输出
// 「业务数据 + 人读分页摘要」）。无 meta 内容返回空串。count 单独成行；
// pagination 摘要复用 renderPaginationSummary。
func renderMetaSummary(meta *Meta) string {
	if meta == nil {
		return ""
	}
	var lines []string
	if meta.Count != nil {
		lines = append(lines, fmt.Sprintf("count: %d", *meta.Count))
	}
	if meta.Pagination != nil {
		lines = append(lines, "pagination: "+renderPaginationSummary(meta.Pagination))
	}
	return strings.Join(lines, "\n")
}

// renderPaginationSummary 按 wire 字段名输出分页摘要：
// endpoint_exhausted/pages/items/next_token（snake_case 与 wire 一致，Agent
// 可交叉核对；§3 两态显式语义保留——false 也输出，因为它是「可续跑」的
// 有意义状态）。
func renderPaginationSummary(p *Pagination) string {
	parts := []string{fmt.Sprintf("endpoint_exhausted: %t", p.EndpointExhausted)}
	if p.Pages > 0 {
		parts = append(parts, fmt.Sprintf("pages: %d", p.Pages))
	}
	if p.Items > 0 {
		parts = append(parts, fmt.Sprintf("items: %d", p.Items))
	}
	if p.NextToken != "" {
		parts = append(parts, fmt.Sprintf("next_token: %s", p.NextToken))
	}
	return strings.Join(parts, ", ")
}

// writePaginationDiagnostic 把分页诊断行写到 errW（§5.2：csv/ndjson 裸记录
// 格式下分页元数据走 stderr 诊断行）。无 meta/pagination 时零输出——
// 不给无分页场景制造噪声。
func writePaginationDiagnostic(errW io.Writer, meta *Meta) error {
	if meta == nil || meta.Pagination == nil {
		return nil
	}
	_, err := fmt.Fprintln(errW, "[pagination] "+renderPaginationSummary(meta.Pagination))
	return err
}

// ---------------------------------------------------------------------------
// Phase B 泛化（B24~B29）：Emitter 类型——success/pending/partial 走 stdout、
// failure 走 stderr 的双向出口；渲染先进 buffer 再一次性写出。
// ---------------------------------------------------------------------------

// Emitter 是统一信封的双向出口（B24，WS1 改动点2）。它持有 stdout/stderr 两个
// 写入目标与当前 format/fields/jq 配置，按契约规范 §5.1 流向纪律把信封分发到
// 正确的流：
//
//   - success / pending / partial_failure → stdout（数据通道）；
//   - failure（含 nil 信封降级）→ stderr，stdout 严格零字节（AC-11）。
//
// 每次写出都经过「先渲染进内存 buffer、再一次性写出」（B25，契约规范 §5.2
// 末条），写一半失败不产生残缺 JSON。渲染复用 WriteEnvelopeTo（B205），
// Emitter 不重新定义信封类型或 wire 键。
type Emitter struct {
	stdout io.Writer
	stderr io.Writer
	format Format
	fields string
	jq     string
}

// NewEmitter 构造 Emitter（B24）。nil writer 按 io.Discard 处理（等价丢弃，
// 防 panic）。format 是解析后的当前 format（空值由 WriteEnvelopeTo 按 json
// 处理）；fields/jq 为命令解析出的 --fields/--jq 过滤条件。
func NewEmitter(stdout, stderr io.Writer, format Format, fields, jq string) *Emitter {
	if stdout == nil {
		stdout = io.Discard
	}
	if stderr == nil {
		stderr = io.Discard
	}
	return &Emitter{stdout: stdout, stderr: stderr, format: format, fields: fields, jq: jq}
}

// Emit 按 env 的 outcome 把信封写到对应流（B26/B27/B28，契约规范 §5.1）：
//
//   - success / pending：完整信封落 stdout（B26，ok:true，§2.1/§2.2）；
//   - partial_failure：三通道明细落 stdout、stderr 零输出（B28，§2.3）；
//   - failure：信封落 stderr、stdout 严格零字节（B27，AC-11）；
//   - nil 信封由 WriteEnvelopeTo 降级为 failure，同样落 stderr。
//
// exit 0 语义标注（B32 收口，契约规范 §4/I2）：Emit 的流路由与
// ExitCodeForEnvelope 的退出码语义一一对应——落 stdout 的信封
// （success/pending/partial_failure 中 ok:true 的前两者）对应 exit 0，
// 落 stderr 的 failure（含 nil 降级）对应非零退出码。Emitter 只负责写出，
// 不自行 os.Exit；进程退出码由 runner 出口按同一映射统一决定（§4 规则）。
//
// 失败信封恒以完整 JSON 信封渲染并绕过 format/fields/jq：失败信封没有数据
// 载荷（I3），§5.1 要求 stderr 上的失败信封恒为结构化信封；「非 json 只渲染
// data」的分发规则只适用于携带数据的信封。若 --jq 作用于失败信封会把错误
// 通道过滤为空，Agent 将丢失错误明细，故同样绕过。
func (em *Emitter) Emit(env *Envelope) error {
	if env == nil || env.Outcome == OutcomeFailure {
		return em.writeOnce(em.stderr, env, FormatJSON, "", "")
	}
	return em.writeOnce(em.stdout, env, em.format, em.fields, em.jq)
}

// writeOnce 先把信封完整渲染进内存 buffer，再一次性写出到 target（B25，
// 契约规范 §5.2 末条「渲染先进 buffer 再一次性写出」）：渲染失败不向 target
// 泄漏任何字节；写出失败原子中止——writer 报错即原样返回，短写（接受了部分
// 字节却未写全）报 io.ErrShortWrite，绝不把截断输出当成功。渲染统一走
// renderEnvelope 分发点（B37），csv/ndjson 的分页诊断行（B40）以 em.stderr
// 为诊断出口。
func (em *Emitter) writeOnce(target io.Writer, env *Envelope, format Format, fields, jq string) error {
	if env == nil {
		env = nilFallbackEnvelope()
	}
	var buf bytes.Buffer
	if err := renderEnvelope(&buf, em.stderr, env, format, fields, jq); err != nil {
		return err
	}
	p := buf.Bytes()
	n, err := target.Write(p)
	if err != nil {
		return err
	}
	if n < len(p) {
		return io.ErrShortWrite
	}
	return nil
}

// ParseFormat 把字符串形式的 format 值（来自 --format flag 或 caller 接口）
// 归一化为 Format 常量；大小写不敏感，未知/空值返回 fallback。它是不持有
// *cobra.Command 的调用方（如主漏斗 callMCPToolInternalOpts）的 ResolveFormat
// 等价物，二者共用同一归一化规则。
func ParseFormat(raw string, fallback Format) Format {
	return normalizeFormat(raw, fallback)
}

// ---------------------------------------------------------------------------
// 退出码映射（B32/B33/B34）：outcome / error 类别 → exit code
// （契约规范 §4；不变量 I2 —— exit code == 0 ⇔ ok == true）
// ---------------------------------------------------------------------------

// 退出码表取值对齐：契约规范 §4 × 规划 v1.2 决策（OQ-1 已关闭——保留现行
// 码表 api=1 / auth=2 / validation=3 / PAT=4 / internal=5 / discovery=6，
// 仅新增 partial_failure 专用码 7；草案表中 validation→2 / confirmation→3
// 的拆分属 wire 破坏性重排，放弃）。confirmation_required 是 failure 的子类，
// 与 validation 共享 rc=3、以 subtype 区分（AC-13；runtime 同源于
// internal/errors 的 ExitCode 表）。
const (
	exitCodeOK         = 0
	exitCodeAPI        = 1
	exitCodeAuth       = 2
	exitCodeValidation = 3 // confirmation_required 子类共享此码（OQ-1 定案）
	exitCodePermission = 4 // PAT / permission failures
	exitCodeInternal   = 5
	exitCodeDiscovery  = 6
	exitCodePartial    = 7 // partial_failure 专用（契约 §4；规划 WS2 第4项；B142 将在 errors 侧补同源常量）
)

// subtypeConfirmationRequired 是门禁拦截的 failure 子类标记（契约规范 §2.4），
// 与 runtime apperrors.WithReason("confirmation_required") 形态同源。
const subtypeConfirmationRequired = "confirmation_required"

// ExitCodeForEnvelope 计算信封对应的进程退出码（B33，AC-10/I2；契约规范 §4）。
// 纯函数：只读信封字段、不做任何 I/O。映射规则：
//
//   - success / pending → 0（I2：exit 0 ⇔ ok；异步受理不是失败，§1/§4）；
//   - partial_failure → 7（部分成功专用码，区别于普通失败，§4）；
//   - failure → 按 Error.Type 类别映射，confirmation_required 子类恒 3；
//   - nil 信封 → 5（与 WriteEnvelopeTo 的 internal 类兜底信封同源）；
//   - 非法 outcome → 5（非法信封属框架缺陷，归 internal）。
//
// 判定只看 outcome / error 类别，不看可能被命令层篡改的 OK 字段（与 IsOK
// 同口径，I1）。退出码由 runner 出口统一决定、命令层禁止自行 os.Exit
// （§4 规则）；本函数为 Emitter 语义标注、runner 映射与测试提供同一依据。
func ExitCodeForEnvelope(env *Envelope) int {
	if env == nil {
		return exitCodeInternal
	}
	switch env.Outcome {
	case OutcomeSuccess, OutcomePending:
		return exitCodeOK
	case OutcomePartialFailure:
		return exitCodePartial
	case OutcomeFailure:
		return exitCodeForErrorInfo(env.Error)
	default:
		return exitCodeInternal
	}
}

// exitCodeForErrorInfo 把失败信封的 error 类别映射为退出码（契约规范 §4）。
// subtype=confirmation_required 优先于 type：门禁拦截无论挂在哪个 type 下
// 都恒为 3（AC-13）。error 缺席（违反 I3 的形态）按 internal 处理——
// 没有明细可分支的失败不得假装可恢复。未知 type 归 internal（不应发生）。
func exitCodeForErrorInfo(info *ErrorInfo) int {
	if info == nil {
		return exitCodeInternal
	}
	if info.Subtype == subtypeConfirmationRequired {
		return exitCodeValidation
	}
	switch info.Type {
	case "api":
		return exitCodeAPI
	case "auth":
		return exitCodeAuth
	case "validation":
		return exitCodeValidation
	case "permission":
		return exitCodePermission
	case "discovery":
		return exitCodeDiscovery
	default:
		return exitCodeInternal
	}
}