Workflow improvement
Plan and apply revision-bound document text patches.
Proposed implementation
Add an executable companion under examples/docs-review/ with README and unittest suite, invoked via python3 and existing gws (no separate auth implementation). Provide plan and apply subcommands. Plan reads one live document with all tabs, selects a tab unambiguously, loads UTF-8 find/replacement files, verifies exactly one occurrence within supported text (reject ambiguous, table-crossing, image-crossing or suggested text targets), records exact source revision/document/tab, before/after diff, expected match count and a deterministic SHA-256 payload digest in a reviewable versioned JSON plan. Apply reconstructs and validates the plan, re-reads current source, refuses revision/source mismatch, submits exactly the planned replacement with writeControl.requiredRevisionId and tabsCriteria.tabIds, checks occurrencesChanged==1, then re-reads and verifies targeted text while checking untouched structural/style metadata where meaningful. Use replaceAllText rather than deleting/rebuilding document blocks to preserve untouched formatting, tables and images; document formatting inheritance inside newly replaced text. Never blindly retry mutations. On ambiguous write outcome retain plan and report possible application, no success. No in-place full-document reupload, no arbitrary command execution from plan, no private fields persisted unnecessarily. Scope first version explicitly to reviewed text replacements; unsupported structural moves fail before writing. Use a no-write local preview mode. Plan/apply API uses argument lists for subprocess, timeouts, checked return codes, redacted actionable errors, relative safe input/output paths confined to CWD with symlink/traversal checks. Examples use synthetic documents only. Public API Docs indices and revision behavior reference official docs.
Acceptance criteria and tests
Plan stable deterministic digest; unique/zero/multiple matches; Unicode/UTF-16 and tab scoping; zero writes during plan; source revision mismatch refuses; tampered/malformed/oversized plan refuses; unsupported structures reject; concurrent API 400 fails; reply count 0 fails; missing revision fails; post-write verification mismatch is not success; timeout after submission marks ambiguous outcome; actual CLI subprocess integration through a temporary stub gws using fixtures (not tests only of mocked methods); path traversal and symlink escape blocked; original plan unchanged after failures.
Upstream coordination
Related: New companion workflow; related upstream googleworkspace#901/googleworkspace#726.
This fork issue tracks one independent contribution from our document-workflow improvement effort. Existing upstream issues remain the canonical reports; the resulting PR will target googleworkspace/cli and reference them.
Delivery
- Separate branch:
feat/docs-review-patches.
- Tests first, independent code review, required checks and changeset.
- Synthetic fixtures only; no personal documents or credentials in public artifacts.
Implementation PR: googleworkspace#933
Workflow improvement
Plan and apply revision-bound document text patches.
Proposed implementation
Add an executable companion under examples/docs-review/ with README and unittest suite, invoked via python3 and existing gws (no separate auth implementation). Provide plan and apply subcommands. Plan reads one live document with all tabs, selects a tab unambiguously, loads UTF-8 find/replacement files, verifies exactly one occurrence within supported text (reject ambiguous, table-crossing, image-crossing or suggested text targets), records exact source revision/document/tab, before/after diff, expected match count and a deterministic SHA-256 payload digest in a reviewable versioned JSON plan. Apply reconstructs and validates the plan, re-reads current source, refuses revision/source mismatch, submits exactly the planned replacement with writeControl.requiredRevisionId and tabsCriteria.tabIds, checks occurrencesChanged==1, then re-reads and verifies targeted text while checking untouched structural/style metadata where meaningful. Use replaceAllText rather than deleting/rebuilding document blocks to preserve untouched formatting, tables and images; document formatting inheritance inside newly replaced text. Never blindly retry mutations. On ambiguous write outcome retain plan and report possible application, no success. No in-place full-document reupload, no arbitrary command execution from plan, no private fields persisted unnecessarily. Scope first version explicitly to reviewed text replacements; unsupported structural moves fail before writing. Use a no-write local preview mode. Plan/apply API uses argument lists for subprocess, timeouts, checked return codes, redacted actionable errors, relative safe input/output paths confined to CWD with symlink/traversal checks. Examples use synthetic documents only. Public API Docs indices and revision behavior reference official docs.
Acceptance criteria and tests
Plan stable deterministic digest; unique/zero/multiple matches; Unicode/UTF-16 and tab scoping; zero writes during plan; source revision mismatch refuses; tampered/malformed/oversized plan refuses; unsupported structures reject; concurrent API 400 fails; reply count 0 fails; missing revision fails; post-write verification mismatch is not success; timeout after submission marks ambiguous outcome; actual CLI subprocess integration through a temporary stub gws using fixtures (not tests only of mocked methods); path traversal and symlink escape blocked; original plan unchanged after failures.
Upstream coordination
Related: New companion workflow; related upstream googleworkspace#901/googleworkspace#726.
This fork issue tracks one independent contribution from our document-workflow improvement effort. Existing upstream issues remain the canonical reports; the resulting PR will target googleworkspace/cli and reference them.
Delivery
feat/docs-review-patches.Implementation PR: googleworkspace#933