Skip to content

feat(docs): add direct table operations#729

Merged
steipete merged 1 commit into
mainfrom
feat/docs-table-ops-686
Jun 10, 2026
Merged

feat(docs): add direct table operations#729
steipete merged 1 commit into
mainfrom
feat/docs-table-ops-686

Conversation

@steipete

Copy link
Copy Markdown
Collaborator

Summary

  • add direct Docs table row/column insert/delete and merge/unmerge commands
  • support index, negative index, exact first-cell text, text: disambiguation, *, and tab selection
  • share request builders with docs sed, remove duplicate mutation paths, and preserve revision control across capped batches
  • reject unsafe merged/non-rectangular references before mutation

Proof

  • DEVELOPER_DIR=/Library/Developer/CommandLineTools make ci
  • autoreview clean: no accepted/actionable findings
  • disposable live Docs proof on [email protected]:
    • exact-header and all-table row/column mutations
    • row values with raw readback and revision binding
    • merge/unmerge provider span readback
    • safe horizontal/vertical merged-cell anchors
    • destructive merged-cell and valued vertical-boundary rejection
    • tab-local mutation
    • whitespace, numeric, and ambiguous header selection
    • all test Docs moved to trash

Closes #686

@clawsweeper

clawsweeper Bot commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 10, 2026, 6:53 AM ET / 10:53 UTC.

Summary
The branch adds direct gog docs table-row, table-column, table-merge, and table-unmerge commands, refactors sed table mutations through shared helpers, and updates generated docs, tests, changelog, and safety profiles.

Reproducibility: not applicable. as a bug reproduction: this is a feature PR. Current main inspection shows the top-level table commands are absent, while the PR diff adds them and reports live Google Docs proof.

Review metrics: 3 noteworthy metrics.

  • Changed surface: 20 files, +1987/-251. This is a broad Docs feature PR, so maintainers should review command registration, shared mutation helpers, docs, tests, and safety profiles together.
  • Generated command docs: 8 added command pages. The CLI surface is user-facing and the generated docs need to stay in sync with the new schema.
  • Safety profile coverage: 2 profiles updated. The new mutating table commands are explicitly denied in both readonly and agent-safe profiles.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Confirm the intentional fail-closed behavior for existing docs sed merged/non-rectangular table references before merge.

Risk before merge

  • [P1] The shared helper intentionally tightens existing docs sed table mutation behavior by rejecting unsafe merged or non-rectangular references before sending the request, so maintainers should accept that fail-closed compatibility change before merge.
  • [P1] The branch edits CHANGELOG.md; this review workflow treats changelog entries as release-owned, so maintainers may want to keep or drop that line during landing rather than make it a contributor-side blocker.

Maintainer options:

  1. Accept the fail-closed sed behavior (recommended)
    Maintainers can land this as-is if they agree unsafe merged or non-rectangular docs sed table mutations should now fail before API mutation.
  2. Preserve old sed compatibility
    If existing scripts must keep the older permissive sed behavior, keep the new direct commands but avoid changing docs sed semantics or add explicit compatibility coverage before merge.

Next step before merge

  • [P2] This needs normal maintainer merge judgment on the new destructive Docs command surface and the intentional docs sed compatibility tightening; there is no narrow autofix task from this review.

Security
Cleared: No concrete security or supply-chain concern was found; the diff adds mutating Docs commands but keeps them disabled in readonly and agent-safe profiles and does not touch dependencies, workflows, secrets, or installers.

Review details

Best possible solution:

Land after maintainers accept the direct command contract and the fail-closed docs sed compatibility change, keeping the generated docs, tests, safety-profile denies, and live Docs proof together.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a feature PR. Current main inspection shows the top-level table commands are absent, while the PR diff adds them and reports live Google Docs proof.

Is this the best way to solve the issue?

Yes, with a maintainer acceptance caveat: sharing request builders between sed and direct commands is the narrow maintainable direction, but the stricter sed behavior is a product/compatibility choice before merge.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against e1be268f70a6.

Label changes

Label changes:

  • add P2: This is a bounded but meaningful Docs command-surface feature with live mutation behavior, not an urgent regression or security issue.
  • add merge-risk: 🚨 compatibility: The PR refactors existing docs sed table mutations through stricter helpers that can fail existing scripts on unsafe merged or non-rectangular table references.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator-authored PR, and the body nevertheless reports make ci plus disposable live Google Docs proof across the new table operations.

Label justifications:

  • P2: This is a bounded but meaningful Docs command-surface feature with live mutation behavior, not an urgent regression or security issue.
  • merge-risk: 🚨 compatibility: The PR refactors existing docs sed table mutations through stricter helpers that can fail existing scripts on unsafe merged or non-rectangular table references.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator-authored PR, and the body nevertheless reports make ci plus disposable live Google Docs proof across the new table operations.
Evidence reviewed

What I checked:

  • Repository policy read: AGENTS.md was read fully; its PR review flow, parseable output guidance, and safety/config guidance shaped this review. (AGENTS.md:1, e1be268f70a6)
  • Current main lacks direct table commands: Current main registers existing Docs commands such as table-column-width, but not the requested table-row, table-column, table-merge, or table-unmerge command surface. (internal/cmd/docs.go:35, e1be268f70a6)
  • PR adds the direct command implementation: The PR head defines the new table row/column command structs and execution path, including table selection, row values, tab targeting, and mutation result output. (internal/cmd/docs_table_ops.go:82, b263c73c9b3a)
  • PR shares sed table request builders: The PR head routes existing docs sed row/column and merge operations through the new shared table request builders instead of keeping duplicate mutation code. (internal/cmd/docs_sed_table_ops.go:43, b263c73c9b3a)
  • Safety profiles deny new mutating commands: The diff adds the new destructive Docs table commands to both agent-safe and readonly profiles with false values, matching the repository safety posture for write operations. (safety-profiles/agent-safe.yaml:152, b263c73c9b3a)
  • Related issue context: The linked feature request remains open and asked for top-level table-row/table-column/table-merge commands because current main only exposed this through docs sed; the PR body uses closing syntax for that request.

Likely related people:

  • steipete: Recent local and GitHub history ties the Docs command registry, table-column-width command, table target fixes, and the current PR branch to Peter Steinberger. (role: recent area contributor and merger; confidence: high; commits: b34e3033913a, e51f6be9dc38, 0a7e6425384b; files: internal/cmd/docs.go, internal/cmd/docs_table_column_width.go, internal/cmd/docs_sed_table_ops.go)
  • Vinston: GitHub path history shows the original sed formatting DSL commit created the sed table operation path that this PR now refactors into shared helpers. (role: introduced behavior; confidence: medium; commits: e2d41ad87c56; files: internal/cmd/docs_sed_table_ops.go)
  • chrischall: Merged PR metadata shows chrischall introduced the adjacent direct docs insert-table primitive, which is closely related to this direct Docs table command surface. (role: adjacent feature contributor; confidence: medium; commits: 3a1b15592f47; files: internal/cmd/docs.go, internal/cmd/docs_insert_table.go, internal/cmd/docs_table_inserter.go)
  • sebsnyk: The linked feature request came from sebsnyk, and recent Docs command history includes a merged adjacent Docs command credited to that handle, making them useful context for the desired CLI ergonomics. (role: related workflow contributor; confidence: medium; commits: 1b8a750026df; files: internal/cmd/docs.go, docs/docs-editing.md)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. labels Jun 10, 2026
@steipete
steipete merged commit 31fb2e5 into main Jun 10, 2026
12 of 13 checks passed
@steipete
steipete deleted the feat/docs-table-ops-686 branch June 10, 2026 11:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(docs): top-level table-row / table-column / table-merge commands

1 participant