[kklimuk]

🤖 docx-cli triage

What was wrong

There was no way to change how an existing image sits on the page. edit --at pN --width 2 → Unknown option, and read flagged <!-- docx:image img0 size="9x6in" overflow="yes" --> with no way to fix it. Alt text could only be set at images add time.

What changed (first slice of #47)

• New docx images set FILE --at imgN:
  • --width L / --height L keep the frame's current aspect ratio.
  • --size WxH takes the docx:image size="…" hint verbatim.
  • --fit shrinks the image to the text width and never enlarges it, which cures overflow="yes".
  • --alt TEXT sets the alt text (--alt "" clears it).
  • --batch FILE.jsonl takes {"at":"imgN",…} per line; a duplicate target is rejected.
  • --dry-run / -o work as on other mutators.
• In-place XML (core/image/frame.ts, Images.find / Images.set):
  • Writes <wp:extent> and <pic:spPr><a:xfrm><a:ext> together, plus descr on wp:docPr and pic:cNvPr.
  • Works on both inline and floating (wp:anchor) frames and leaves wrap and position untouched.
  • Refuses group/shape drawings rather than scale only their outer box.
• Write-read loop:
  • The ack echoes img0 size="2x1.33in" alt="…", and the next read shows it.
  • A markdown edit that restates [alt](sha256.ext) now keeps the displayed size (Body.findImageSizeByHash). Before, it snapped back to the native pixel size, which would silently undo any resize. This is a behaviour change.
• No-op exits MATCH_NOT_FOUND (e.g. --fit on an image that already fits).
• Under track-changes it applies untracked with a [docx-cli] audit comment, following the images replace precedent (see Decisions).
• images delete now uses the shared Images.find. Length parsing is shared with images add (cli/images/length.ts). formatImageSize is a single helper for the hint, the ack and the audit text.
• Docs, fixture, scenario:
  • Docs: REFERENCE, src/cli / core/image / core/markdown CLAUDE.md, images --help (which also mentions centering via edit --alignment), top-level help, skill commands.md.
  • Fixture: tests/fixtures/setup/images.ts dogfoods images set --fit --alt and --height.
  • Scenario: the invoice weak-agent scenario now asks for the logo at about 1.25in with alt text.

Verification

• Before: docx edit doc.docx --at p1 --width 2 → Unknown option.
• After:

  $ docx images set doc.docx --at img0 --fit
  images.set img0
  img0 size="6.5x4.33in" alt="Old"
  $ docx images set doc.docx --at img0 --fit   → MATCH_NOT_FOUND, exit 3
  $ docx images set doc.docx --at img0 --width 2in --alt "New logo"
  img0 size="2x1.33in" alt="New logo"
  

• On large-mixed.docx, a 15-entry --alt batch landed each alt on the matching imgN in read, and validate passes. Floating img1 resized with float, wrap and align kept.
• bun run check ✅ bun run test:unit ✅ (2107 tests; 16 new in tests/cli/images-set.test.ts)
• /simplify: single pass without the Agent tool. It pulled out a shared formatImageSize.
• /code-review xhigh: the forked skill reviewed the wrong checkout (see the PR comment). I did the xhigh pass on this diff by hand instead. It added the duplicate-target guard for --batch and checked that the imgN order matches read.
• Not run here: LibreOffice round-trip and the Word redline oracle (neither is available in the sandbox). The fixture was rebuilt and validates clean.

Decisions for you

• Tracking: is untracked + audit comment right for resize/alt? Word may record picture-size changes as run formatting changes. scripts/word-redlines.sh couldn't run here (no Word).
• Restated-image size: a markdown edit/insert of [alt](sha256.ext) now uses the size the image is shown at (the first drawing with that hash) instead of its native pixels. OK to keep?
• --fit width: it uses the page text width from the trailing sectPr, the same width images add fits to. It doesn't use the containing section's or table cell's width. Cell-aware fit can follow.
• No-op = nonzero: --fit on an image that already fits, or the same alt again, exits 3. In a batch, only a batch that changes nothing at all fails.
• Remaining scope of feat(images): images set — resize, wrap/float, alt text and captions on an existing image #47 (left for later PRs, so this PR says "Refs" and the issue stays open):
  • --wrap inline|square|… / --float left|right (inline↔anchor conversion)
  • --caption add/replace (blocked on feat(bookmarks): bookmarks as addressable targets, authored cross-references (REF/PAGEREF/NOTEREF), and internal links #40/feat(fields): model complex fields — parse, AST, read tokens, offset widths #41 for SEQ numbering)
  • images add --at CELL bare-cell fill
  • --fit --all
• fix(images): replace keeps the old frame, so a differently-shaped image is distorted #46 (images replace aspect refit, in progress separately) could share writeFrameSize/setImageFrame in src/core/image/frame.ts. Until fix(images): replace keeps the old frame, so a differently-shaped image is distorted #46 lands, --width after a replace keeps the old placeholder's ratio. The invoice criteria note this.

Refs #47 (first slice of #47)

---

Generated by Claude Code

[kklimuk]

🤖 docx-cli triage

This PR is the first slice of #47: images set --at imgN with --width/--height (aspect kept), --size WxH (the read hint verbatim), --fit (cures overflow="yes"), --alt, and --batch. The next read shows each change. A markdown restate of the image no longer undoes a resize.

What I verified:

• bun run check and bun run test:unit pass: 2107 tests, 16 of them new.
• The imgN order matches read on large-mixed.docx, and a resized floating image keeps its anchor, wrap and align.
• The rebuilt images.docx fixture passes validate.

Wrap/float, captions, images add --at CELL and --fit --all are not in this PR. They're listed under "Decisions for you" in the description, so #47 stays open ("Refs").

Process note: I ran /code-review xhigh --fix as a forked skill, and it ran in the primary checkout /home/user/docx-cli instead of this branch's worktree. It reviewed and edited an unrelated main...HEAD diff there: equations, track-changes apply and validate --fix. Those edits are uncommitted in that checkout, mixed with another agent's work. I didn't touch or revert them, and none of them are in this PR. I did the xhigh review of this diff by hand instead, which added the duplicate-target guard for --batch.

Action needed: approve/merge — PR #53 is ready once you've answered the checklist in the description (main questions: is untracked + audit comment right under tracking, and should a restated image keep its displayed size). Also inspect the uncommitted edits the misdirected review left in /home/user/docx-cli and keep or discard them.

---

Generated by Claude Code