Issue #99 Phase 2: add editing CLI

[harumiWeb]

Summary

• Add the Phase 2 editing CLI commands (patch, make, ops list, ops describe, validate) from the existing exstruct console script.
• Keep the legacy extraction entrypoint exstruct INPUT.xlsx ... unchanged via first-token dispatch in src/exstruct/cli/main.py.
• Add edit CLI regression coverage and update ADR/spec/public docs for the Phase 2 contract.
• refs Promote Excel editing to first-class Python API and CLI, and reposition MCP as an integration layer #99

Acceptance Criteria (Issue #99 Phase 2)

• AC-01: Editing is available as first-class CLI commands from exstruct.
• AC-02: Legacy extraction CLI compatibility is preserved.
• AC-03: patch / make / ops / validate follow the JSON-first output and exit-code contract.
• AC-04: CLI regression tests cover the new edit surface and extraction dispatch boundary.
• AC-05: ADR, internal spec, and public docs are updated for the Phase 2 boundary.

Validation

• uv run pytest tests/cli/test_edit_cli.py tests/cli/test_cli.py tests/cli/test_cli_alpha_col.py tests/edit/test_api.py tests/mcp/test_validate_input.py -q
• uv run task precommit-run
• Added/updated tests for changed behavior.
• Updated docs (docs/cli.md, docs/api.md, README.md, README.ja.md, dev-docs/).

---

Summary by CodeRabbit

• New Features

  • Editing CLI added: JSON-first commands—patch, make, ops list/describe, validate—with non-interactive workflows and clear exit/output semantics.

• Documentation

  • Quick Start and detailed Phase 2 Editing CLI docs, API/CLI notes, and ADR describing the public editing CLI contract.

• Tests

  • End-to-end tests covering all editing CLI commands and behaviors.

[coderabbitai]

Warning

Rate limit exceeded

@harumiWeb has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 32 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 695eb324-6a98-4c90-bbc2-92b1d424930f

📥 Commits

Reviewing files that changed from the base of the PR and between dff6126 and 6db6b16.

📒 Files selected for processing (2)

• src/exstruct/cli/edit.py
• tests/cli/test_edit_cli.py

📝 Walkthrough

Walkthrough

Introduces a Phase‑2 Editing CLI: new CLI module and dispatcher wiring, formal ADR/spec/docs describing commands (patch, make, ops, validate), comprehensive tests, and task/tracking updates. No public API surface changes beyond CLI wrappers.

Changes

Cohort / File(s)	Summary
CLI Implementation src/exstruct/cli/edit.py, src/exstruct/cli/main.py	Adds a new editing CLI module with subcommands (patch, make, ops list/describe, validate), arg parsing, JSON I/O and exit semantics; main.py routes edit subcommands to the new module before legacy extraction flow.
Architectural Documentation dev-docs/adr/ADR-0007-editing-cli-as-public-operational-interface.md, dev-docs/adr/README.md, dev-docs/adr/index.yaml, dev-docs/adr/decision-map.md	New ADR and index/decision‑map entries documenting the editing CLI decision, status, scope, and related specs.
API & Architecture Specs dev-docs/specs/editing-cli.md, dev-docs/specs/editing-api.md, dev-docs/architecture/overview.md	Adds Phase‑2 CLI contract and notes that a CLI wrapper will expose the editing contract; documents dispatch rules and CLI‑specific surfaces.
Public Documentation README.md, README.ja.md, docs/cli.md, docs/api.md	Adds Quick Start and usage examples for the Editing CLI; documents flags, outputs, and behavior for patch/make/ops/validate.
Testing & Tracking tests/cli/test_edit_cli.py, tasks/feature_spec.md, tasks/todo.md	Extensive in‑process CLI test suite for editing commands; task and feature spec updates outlining implementation checklist and next actions.

Sequence Diagram(s)

sequenceDiagram
  participant User as "User (shell)"
  participant CLI as "exstruct CLI\n(src/exstruct/cli/edit.py)"
  participant EditLib as "exstruct.edit\n(patch/make)"
  participant Validator as "exstruct.mcp.validate_input"
  participant FS as "Filesystem / Workbook"

  User->>CLI: run `exstruct patch|make|ops|validate` + args
  CLI->>CLI: parse args, load --ops JSON (file/stdin)
  CLI->>EditLib: call patch_workbook / make_workbook / ops helpers
  EditLib->>FS: read/write workbook files
  EditLib-->>CLI: return PatchResult / ops list / schema
  CLI->>Validator: (validate command) validate_input(file)
  Validator-->>CLI: validation result (is_readable, warnings, errors)
  CLI->>User: write JSON to stdout, write errors to stderr, exit code

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Issue #99: Implements the Phase‑2 editing CLI feature discussed in the issue — adds subcommands, CLI routing, docs, and tests.

Possibly related PRs

• PR #102: The CLI wraps and dispatches to the exstruct.edit API introduced in PR #102.
• PR #91: Shares ADR and dev‑docs modifications around CLI/architecture documentation.
• PR #57: Both PRs touch CLI entrypoint dispatch logic and related CLI behavior.

Suggested labels

enhancement

Poem

🐰
A tiny rabbit taps the keys at night,
Patching workbooks with a hop and light,
Ops streamed as JSON, tidy and bright,
Validate, make, and list — all just right,
Hooray for edits that land in flight! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly describes the main change: adding the Phase 2 editing CLI commands to the exstruct project.
Description check	✅ Passed	The PR description provides comprehensive coverage with summary, custom acceptance criteria for Phase 2, validation evidence, and references the related issue, though it deviates from the repository's template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch issue-99-phase2

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

[Copilot]

Pull request overview

Adds the Phase 2 “editing CLI” surface to exstruct while preserving the legacy extraction entrypoint via first-token dispatch, and updates specs/ADRs/public docs plus regression tests to codify the new contract.

Changes:

• Introduce editing subcommands (patch, make, ops list/describe, validate) implemented in src/exstruct/cli/edit.py with JSON-first output + exit-code rules.
• Add first-token dispatch in src/exstruct/cli/main.py so legacy exstruct INPUT.xlsx ... continues to use the extraction parser.
• Add CLI regression tests and update ADR/spec/public docs/README parity for the Phase 2 boundary.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/cli/test_edit_cli.py	New end-to-end-ish in-process tests covering edit subcommands + dispatch boundary.
tasks/todo.md	Project log entry for Phase 2 CLI work and verification commands.
tasks/feature_spec.md	Captures Phase 2 goal/contract/boundaries and permanent references.
src/exstruct/cli/main.py	Adds first-token dispatch to route edit subcommands to the new edit parser; updates help epilog.
src/exstruct/cli/edit.py	Implements the editing subcommand parser, JSON I/O helpers, and wrappers over exstruct.edit + validate helper.
docs/cli.md	Documents the dual extraction-vs-editing CLI surface and edit command flags.
docs/api.md	Notes the matching operational CLI for the editing API.
dev-docs/specs/editing-cli.md	New internal spec defining the Phase 2 editing CLI contract.
dev-docs/specs/editing-api.md	Notes Phase 2 CLI wrapper exists and links to the CLI spec.
dev-docs/architecture/overview.md	Adds cli/edit.py and describes the dispatch layering.
dev-docs/adr/index.yaml	Registers ADR-0007 in the ADR index.
dev-docs/adr/decision-map.md	Adds ADR-0007 to the decision map domains.
dev-docs/adr/README.md	Adds ADR-0007 to the ADR README table.
dev-docs/adr/ADR-0007-editing-cli-as-public-operational-interface.md	New ADR recording the policy/compatibility decision for the editing CLI.
README.md	Adds Quick Start section for the editing CLI.
README.ja.md	Adds Japanese Quick Start parity for the editing CLI.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.