feat(base): require --fields on +table-create

[CarolSum]

Summary

+table-create without --fields creates a table with the platform default schema. Those default fields then coexist with every field the caller adds afterwards, and no field command removes them all — the only clean recovery is to delete the table and start over. This makes --fields required, so the schema is declared up front, matching what +base-create already recommends via --table-name + --fields.

Concretely, the failure this prevents: an agent runs +table-create --name X, gets a table carrying the default schema, adds its own N fields, and ends up with a table of N + default-schema fields — while reporting N to the user, because the extra columns were never part of its plan.

Changes

• Mark --fields Required on +table-create, so --help and the machine-readable schema both advertise it.
• Reject blank / non-array / empty-array --fields in Validate. Cobra's MarkFlagRequired only checks that the flag was set, so --fields "" and --fields "[]" would still reach the API with no fields body and silently fall back to the default schema. Both now return a typed *errs.ValidationError with param: --fields and a hint. This mirrors the two-layer pattern already used by sheets/+history-revert.
• Validate runs ahead of the dry-run branch, so --dry-run can no longer preview an invocation the real call would reject.
• Sharpen the flag description and add a worked example + a tip explaining why the flag is required.
• Update skills/lark-base/SKILL.md, tests/cli_e2e/base/coverage.md, and the live e2e helper (all three existing live-e2e callers already pass a schema, so no live coverage is lost).

Test Plan

• Unit tests pass — make unit-test clean; new contract tests in shortcuts/base/table_create_test.go cover the Required declaration, missing / blank / empty-array / non-object-item rejection, the dry-run gate, and the valid path. Each fails if the corresponding code change is reverted.
• Manual local verification confirms the lark-cli base +table-create flow works as expected:
  • missing --fields → {"type":"validation","subtype":"invalid_argument","message":"required flag(s) \"fields\" not set"}
  • --fields '[]' → {"type":"validation","subtype":"invalid_argument","message":"--fields must define at least one field","param":"--fields","hint":"An empty array is not a schema: ..."}
  • --fields '[{"name":"Title","type":"text"}]' → POST /open-apis/base/v3/bases/:base_token/tables with the schema inline, unchanged from before
• go vet ./..., gofmt -l ., go mod tidy (no change), golangci-lint run --new-from-rev=origin/main (0 issues)

Notes for reviewers

This is a breaking change: +table-create --base-token <t> --name <n> without --fields now fails instead of creating a default-schema table. Callers that relied on create-empty-then-add-fields must pass the schema to --fields. If you would rather stage it, the same validation could first ship as a deprecation warning on the fieldless path — happy to rework it that way.

One thing I deliberately left alone: the missing-flag case still surfaces cobra's terse required flag(s) "fields" not set, without param or hint, because enriching that path touches the shared dispatcher in cmd/root.go and belongs in its own PR. The flag description and tips carry the guidance in --help meanwhile.

Related Issues

• None

Summary by CodeRabbit

• New Features

  • Table creation now requires a non-empty field schema provided through --fields.
  • Updated help and guidance clarify field requirements and field schema formatting.

• Bug Fixes

  • Invalid, blank, empty, non-object, or malformed field definitions now receive descriptive validation errors.
  • Dry-run validation consistently enforces required field schemas.

• Tests

  • Expanded coverage for required fields, invalid schemas, dry runs, valid schemas, and CLI validation metadata.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 74008703-69aa-431e-a5a6-c98392515c2e

📥 Commits

Reviewing files that changed from the base of the PR and between 1d3bedc and c7b76a7.

📒 Files selected for processing (1)

• shortcuts/base/table_create.go

🚧 Files skipped from review as they are similar to previous changes (1)

• shortcuts/base/table_create.go

---

📝 Walkthrough

Walkthrough

The +table-create command now requires a non-empty JSON field schema. Validation rejects invalid schemas before request execution. Tests, CLI coverage, helper functions, and Lark Base guidance now reflect this requirement.

Changes

Explicit table schema creation

Layer / File(s)	Summary
Table-create CLI contract shortcuts/base/table_create.go, shortcuts/base/base_shortcuts_test.go, shortcuts/base/base_dryrun_ops_test.go, shortcuts/base/table_create_test.go	--fields is required. Help text, descriptions, examples, and dry-run coverage define the explicit non-empty schema requirement.
Field schema validation shortcuts/base/table_ops.go, shortcuts/base/table_create_test.go, shortcuts/base/base_shortcuts_test.go	Validation rejects blank, malformed, empty, and non-object field schemas. Valid schemas pass validation, and JSON syntax errors remain available in validation metadata.
Workflow and documentation alignment tests/cli_e2e/base/helpers_test.go, tests/cli_e2e/base/coverage.md, skills/lark-base/SKILL.md	Helpers always pass --fields. Coverage documentation and Lark Base guidance describe the required schema.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant validateTableCreate
  participant TableCreateRequest
  CLI->>validateTableCreate: validate --fields JSON
  validateTableCreate-->>CLI: return validation error or valid schema
  validateTableCreate->>TableCreateRequest: pass validated fields

Loading

Possibly related PRs

• larksuite/cli#2153: Both changes modify validateTableCreate and strengthen --fields validation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely states the main change: requiring --fields for +table-create.
Description check	✅ Passed	The description includes the required Summary, Changes, Test Plan, and Related Issues sections with detailed scope and verification results.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/base/base_shortcuts_test.go`:
- Around line 1224-1226: Strengthen the invalid-fields rejection test in
shortcuts/base/base_shortcuts_test.go:1224-1226 by using errs.ProblemOf to
assert the validation category and subtype, errors.As to inspect
*errs.ValidationError and verify its Param, and an errors.Is or equivalent
assertion for the JSON parse cause. Apply the same typed-error assertions in
shortcuts/base/table_create_test.go:35-41, including Param == "--fields" and
preservation of the wrapped Cobra required-flag cause.

In `@shortcuts/base/table_create.go`:
- Line 34: Update the fieldless-create guidance in
shortcuts/base/table_create.go lines 34-34 and skills/lark-base/SKILL.md lines
84-84 to state that omitted, blank, or empty schemas are rejected before table
creation, rather than creating platform-default fields; keep both descriptions
consistent with the current validation behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0d1d98bd-f502-4032-8af9-7371cc8f301e

📥 Commits

Reviewing files that changed from the base of the PR and between f7d0326 and 2f4576b.

📒 Files selected for processing (8)

• shortcuts/base/base_dryrun_ops_test.go
• shortcuts/base/base_shortcuts_test.go
• shortcuts/base/table_create.go
• shortcuts/base/table_create_test.go
• shortcuts/base/table_ops.go
• skills/lark-base/SKILL.md
• tests/cli_e2e/base/coverage.md
• tests/cli_e2e/base/helpers_test.go

[CarolSum]

Thanks for the review — pushed 38677e1. Two of the three points were valid; one I'd like to push back on with evidence.

1. Typed metadata on the rejection tests — fixed for the invalid-schema case.

base_shortcuts_test.go now asserts category/subtype/param via assertInvalidArgumentValidation and the preserved *json.SyntaxError cause, rather than just "an error came back". Verified the shape it pins:

err type = *errs.ValidationError
category=validation subtype=invalid_argument param="--fields"
cause = unexpected end of JSON input

2. Same request for the missing-flag test — not applicable at that layer.

The suggestion was to assert Param == "--fields" and a wrapped cobra cause in table_create_test.go. That contract does not exist there. A missing flag fails inside cobra's ValidateRequiredFlags, which returns a plain error; the typed envelope is applied later by the dispatcher. Probed against this branch:

err type = *errors.errorString, err = required flag(s) "fields" not set
errs.ProblemOf        → not a typed problem
errors.As(*errs.ValidationError) → no

The envelope-level contract is already pinned where it actually holds, in cmd/root_test.go:388 ("usage error (missing required flag) is typed as invalid_argument with exit 2"), keyed off cobraUsageErrorMarkers in cmd/root.go. Rather than assert a promise this layer does not make, I kept the text assertion, documented why, and added a guard that fails if the boundary ever moves — so the weaker assertion cannot silently outlive its reason.

3. Stale fieldless-create guidance — fixed. Fair catch: both the tip and the skill note read as if the fieldless path were still reachable through +table-create. Both now lead with the rejection (omitted / blank / empty-array, before any table is created) while keeping why the schema has to be declared here.

Re-ran the full gate after the changes: make unit-test clean, go vet, gofmt -l ., go mod tidy (no change), golangci-lint --new-from-rev=origin/main → 0 issues.

---

Heads-up on an overlap: #2153 also rewrites validateTableCreate — it adds --view parsing there, while this PR adds --fields validation. The two are complementary in intent but will conflict textually in shortcuts/base/table_ops.go (and lightly in base_shortcuts_test.go / skills/lark-base/SKILL.md / coverage.md). Whichever lands first, I'm happy to rebase this one on top — just say the word.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@c7b76a7a521efb4a883c7b1f3453810f50b5a5a2

🧩 Skill update

npx skills add CarolSum/cli#feat/base-table-create-require-fields -y -g