sheet

var ListSheets = shortcut.Shortcut{
	OutputRollout: output.RolloutUnifiedActive,
	Service:       "sheet",
	Command:       "+list-sheets",
	Product:       "sheet",
	Description:   "严格列出在线电子表格的工作表，并可按完整标题精确筛选",
	Intent:        "需要发现一个在线电子表格中的工作表与稳定 sheetId，或验证某个完整工作表标题是否存在时",
	Risk:          shortcut.RiskRead,
	Safety: contract.SafetySpec{
		Effect: "read", Risk: "low",
		Confirmation: "not_required", Idempotency: "idempotent",
	},
	Contract: corecmd.ContractDecl{
		Identity: contract.ToolIdentitySpec{
			ProductID:      "sheet",
			Name:           "shortcut_list_sheets",
			CanonicalPath:  "sheet.shortcut_list_sheets",
			CLIPath:        "sheet +list-sheets",
			PrimaryCLIPath: "sheet +list-sheets",
		},
		Description: "严格列出在线电子表格的工作表",
		Interface: &contract.InterfaceSpec{
			Mode:         "composite",
			Availability: "available",
			Reason:       "Reviewed built-in shortcut adapter: the executable CLI owns validation, optional multi-step orchestration, output projection, and confirmation; the complete command contract is not represented by one pinned MCP interface_ref.",
		},
		Selection: contract.SelectionSpec{
			AgentSummary: "严格列出在线电子表格的工作表，并可按完整标题精确筛选",
			UseWhen:      []string{"需要发现一个在线电子表格中的工作表与稳定 sheetId，或验证某个完整工作表标题是否存在时"},
			AvoidWhen:    []string{"需要管理 AITable/Base 的数据表或记录时改用 aitable；需要原始 get_all_sheets 响应时改用 sheet list"},
			Examples:     []string{"dws sheet +list-sheets --node NODE_ID"},
		},
		Parameters: []contract.ParamDecl{
			{Name: "node", Property: "node"},
			{Name: "title", Property: "title"},
		},
		Result: &contract.ResultSpec{
			Outcomes:       []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
			DataSchema:     json.RawMessage(`{"type":"object","description":"经过严格校验的工作表列表","properties":{"count":{"type":"integer","description":"精确筛选后的工作表数量"},"sheets":{"type":"array","description":"工作表条目；显式空数组表示合法零命中","items":{"type":"object","description":"带稳定身份的工作表","properties":{"sheetId":{"type":"string","description":"稳定工作表 ID"},"title":{"type":"string","description":"工作表完整标题"},"index":{"type":"integer","description":"可选工作表顺序"},"visibility":{"description":"可选工作表可见性"},"rowCount":{"type":"integer","description":"可选行数"},"columnCount":{"type":"integer","description":"可选列数"}},"required":["sheetId","title"],"additionalProperties":false}}},"required":["count","sheets"],"additionalProperties":false}`),
			SensitivePaths: []string{"sheets.sheetId", "sheets.title"},
		},
	},
	Flags: []shortcut.Flag{
		{Name: "node", Type: shortcut.FlagString, Desc: "表格文档 ID 或 URL；--node 去除空白后不能为空", Required: true},
		{Name: "title", Type: shortcut.FlagString, Desc: "按完整工作表标题精确筛选（区分大小写）；显式传入时去除空白后不能为空"},
	},
	Constraints: []shortcut.Constraint{
		{Kind: shortcut.ConstraintCustom, Flags: []string{"node"}, Description: "--node 去除空白后不能为空"},
		{Kind: shortcut.ConstraintCustom, Flags: []string{"title"}, Description: "--title 显式传入时去除空白后不能为空"},
	},
	Tips: []string{`dws sheet +list-sheets --node NODE_ID`},
	Validate: func(rt *shortcut.RuntimeContext) error {
		if err := validateSheetNode(rt); err != nil {
			return err
		}
		return validateOptionalSheetString(rt, "title")
	},
	Execute: func(rt *shortcut.RuntimeContext) error {
		data, err := rt.CallMCPData("sheet", "get_all_sheets", map[string]any{"nodeId": rt.Str("node")})
		if err != nil {
			return err
		}
		sheets, err := projectSheetList(data, rt.Str("title"))
		if err != nil {
			return err
		}
		return rt.Output(map[string]any{"count": len(sheets), "sheets": sheets})
	},
}

var Read = shortcut.Shortcut{
	OutputRollout: output.RolloutUnifiedActive,
	Service:       "sheet",
	Command:       "+read",
	Product:       "sheet",
	Description:   "完整读取并严格校验在线电子表格范围；截断结果失败关闭",
	Intent:        "需要逐格读取在线电子表格的值、公式或格式化值，并要求结果未被服务端截断时",
	Risk:          shortcut.RiskRead,
	Safety: contract.SafetySpec{
		Effect: "read", Risk: "low",
		Confirmation: "not_required", Idempotency: "idempotent",
	},
	Contract: corecmd.ContractDecl{
		Identity: contract.ToolIdentitySpec{
			ProductID:      "sheet",
			Name:           "shortcut_read",
			CanonicalPath:  "sheet.shortcut_read",
			CLIPath:        "sheet +read",
			PrimaryCLIPath: "sheet +read",
		},
		Description: "完整读取并严格校验工作表范围",
		Interface: &contract.InterfaceSpec{
			Mode:         "composite",
			Availability: "available",
			Reason:       "Reviewed built-in shortcut adapter: the executable CLI owns validation, optional multi-step orchestration, output projection, and confirmation; the complete command contract is not represented by one pinned MCP interface_ref.",
		},
		Selection: contract.SelectionSpec{
			AgentSummary: "完整读取并严格校验在线电子表格范围；截断结果失败关闭",
			UseWhen:      []string{"需要逐格读取在线电子表格的值、公式或格式化值，并要求结果未被服务端截断时"},
			AvoidWhen:    []string{"需要纯 CSV 时用 sheet csv-get；需要 AITable/Base 结构化记录时用 aitable；超大范围应拆小后重试，不能把截断结果当完整成功"},
			Examples:     []string{"dws sheet +read --node NODE_ID --sheet-id SHEET_ID --range \"A1:D10\""},
		},
		Parameters: []contract.ParamDecl{
			{Name: "node", Property: "node"},
			{Name: "sheet-id", Property: "sheetId"},
			{Name: "range", Property: "range"},
			{Name: "value-render-option", Property: "valueRenderOption"},
		},
		DryRun: &contract.DryRunSpec{
			PreviewKind: contract.DryRunPreviewRequest,
			RemoteReads: false,
		},
		Result: &contract.ResultSpec{
			Outcomes:       []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
			DataSchema:     json.RawMessage(`{"type":"object","description":"完整且未截断的单元格范围","properties":{"cells":{"type":"array","description":"与行列坐标对齐的二维单元格对象数组","items":{"type":"array","description":"一行单元格对象","items":{"type":"object","description":"单元格结构化数据","additionalProperties":true}}},"colIndices":{"type":"array","description":"与 cells 列对齐的 A1 列标","items":{"type":"string"}},"rowIndices":{"type":"array","description":"与 cells 行对齐的一基行号","items":{"type":"integer"}},"complete":{"type":"boolean","description":"结果已证明完整；成功结果恒为 true"},"hasMore":{"type":"boolean","description":"服务端截断标记；成功结果恒为 false"},"truncationReasons":{"type":"array","description":"截断原因；成功结果恒为空数组","items":{"type":"string"}},"resolvedRange":{"type":"string","description":"服务解析后的请求范围"},"returnedRange":{"type":"string","description":"服务实际返回的范围"},"message":{"type":"string","description":"可选服务说明"}},"required":["cells","colIndices","rowIndices","complete","hasMore","truncationReasons"],"additionalProperties":false}`),
			SensitivePaths: []string{"cells"},
		},
	},
	Flags: []shortcut.Flag{
		{Name: "node", Type: shortcut.FlagString, Desc: "表格文档 ID 或 URL；--node 去除空白后不能为空", Required: true},
		{Name: "sheet-id", Type: shortcut.FlagString, Desc: "工作表 ID 或名称 (不传则第一个工作表)；显式传入时去除空白后不能为空"},
		{Name: "range", Type: shortcut.FlagString, Desc: "读取范围，A1 表示法 (不传则全部数据)；显式传入时去除空白后不能为空"},
		{Name: "value-render-option", Type: shortcut.FlagString, Desc: "取值模式", Enum: []string{"formatted_value", "raw_value", "formula"}},
	},
	Constraints: []shortcut.Constraint{
		{Kind: shortcut.ConstraintCustom, Flags: []string{"node"}, Description: "--node 去除空白后不能为空"},
		{Kind: shortcut.ConstraintCustom, Flags: []string{"sheet-id"}, Description: "--sheet-id 显式传入时去除空白后不能为空"},
		{Kind: shortcut.ConstraintCustom, Flags: []string{"range"}, Description: "--range 显式传入时去除空白后不能为空"},
	},
	Tips: []string{`dws sheet +read --node NODE_ID --sheet-id SHEET_ID --range "A1:D10"`},
	Validate: func(rt *shortcut.RuntimeContext) error {
		if err := validateSheetNode(rt); err != nil {
			return err
		}
		for _, name := range []string{"sheet-id", "range"} {
			if err := validateOptionalSheetString(rt, name); err != nil {
				return err
			}
		}
		return nil
	},
	Execute: func(rt *shortcut.RuntimeContext) error {
		params := map[string]any{"nodeId": rt.Str("node")}
		if rt.Changed("sheet-id") {
			params["sheetId"] = rt.Str("sheet-id")
		}
		if rt.Changed("range") {
			params["range"] = rt.Str("range")
		}
		if rt.Changed("value-render-option") {
			params["valueRenderOption"] = rt.Str("value-render-option")
		}
		if rt.DryRun() {
			return rt.CallMCP("get_cell_infos", params)
		}
		data, err := rt.CallMCPData("sheet", "get_cell_infos", params)
		if err != nil {
			return err
		}
		projected, err := projectSheetRead(data)
		if err != nil {
			return err
		}
		return rt.Output(projected)
	},
}