Skip to content

fix(create-chapter): render each chapter's Web Banner from its deck - #65

Merged
rparundekar merged 3 commits into
mainfrom
fix/web-banner-render
Nov 3, 2026
Merged

rparundekar merged 3 commits into
mainfrom
fix/web-banner-render

Conversation

@rparundekar

@rparundekar rparundekar commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Web Banner.png (the square "AAIF Community Events / " image in every chapter folder) has the city drawn into the pixels. create_chapter.py rebrands OOXML text, so it copied TemplateCity's PNG byte for byte. Measured 2026-11-03: 37 chapters' banners were byte-identical to the template and said "San Francisco", including the two created this week. Renamed chapters (Japan, New Zealand, Edinburgh, and others) still showed their old names.

Fix

  • render_web_banner.py makes the banner from the fourth slide of the chapter's own Banners (…)/Square Logo.pptx. That slide is the same 2000x2000 composition, already rebranded, in the design system. It renders through slides_export.render_slide_png (Google's renderer, no LibreOffice).
  • Guards
    • The slide must say exactly "AAIF Community Events" plus the chapter's name. This is checked on the deck (slide resolved by presentation order) and again on the page the renderer draws.
    • The banner is stamped with the deck's md5Checksum plus the chapter name in appProperties, so a re-run skips current banners and re-checks after any deck change or rename.
    • The stamp is written after the upload. A temp Slides copy that can't be trashed fails the chapter.
    • A sweep never creates a banner and skips TemplateCity unless it is named. --chapter X --create creates one. It is the follow-up create_chapter prints when its render failed before the file existed.
    • A folder with no banner counts as absent, not failed, even when it has no Banners folder or deck.
  • slides_export.render_slide_png gains check_text and strict_cleanup, a PNG signature check and clearer errors. strict_cleanup puts a stray copy's id in the error even when the render also failed. Existing callers are unchanged.
  • create_chapter calls it after a clean write (exit 2 if the banner failed). It does not render a dirty existing deck under --resume. rename_chapter calls it after a verified write (exit 1 if it failed, and it never creates a banner).
  • Docs: the SKILL.md verify step and gotcha. references/rename-chapter.md lists what a text rename misses.

Verification

  • New test_render_web_banner.py (45 tests), new renderer guard tests in the library suite (604 passed), and new hook tests in test_create_chapter.py (79) and test_rename_chapter.py, including main() wiring. The NO_RETRY create is counted at the subprocess. Two mutants confirmed the new tests catch a dropped NO_RETRY and a report run that writes. Pre-commit is clean.
  • A live report over 120 folders found 119 to render and 0 refused. Tatooine has no banner and is listed.
  • A live --write on Aarhus rendered the right name at 2000x2000, left no temp copy, and re-runs as current.
  • The estate-wide --write ran on 2026-11-03: 118 rendered, 1 already current (Aarhus), 0 failed. Tatooine has no banner and was left alone.

🤖 Generated with Claude Code

Generated using wayfare.

Web Banner.png has the city drawn into the image, so the text rebrand never
reached it and every clone kept TemplateCity's "San Francisco" banner; renamed
chapters kept their old names. render_web_banner.py renders slide 4 of the
chapter's own Square Logo deck through Google's renderer instead, refuses a
slide that does not name the chapter, and stamps the banner with the deck's
checksum so a re-run skips current banners and picks up renamed decks.

create_chapter and rename_chapter call it after a write. The rename reference
now lists the other surfaces a text rename misses (badges, Luma links, the
feed's Summary prose).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rparundekar

Copy link
Copy Markdown
Collaborator Author

Self-Review

Six passes ran: code, silent failures, tests, comments, types and security. The diff is 494 lines and writes to every chapter folder, so it got the full set.

Important (9)

  • [silent-failure, types] render_web_banner.py:128: a matching stamp returns "current" before the name check runs. The stamp holds only the deck md5, so a chapter renamed without a deck rewrite keeps an old-name banner and reports clean.
  • [comments, silent-failure, code] render_web_banner.py:77: the name check reads the slide4.xml part, but the render uses the fourth slide in presentation order. A reordered deck gets one slide checked and another published.
  • [silent-failure, comments] create_chapter.py:812 and rename_chapter.py:450: sync_one returns only the error, so a no-op "current" prints "Rendered".
  • [silent-failure, types] create_chapter.py:812: a failed banner exits 0 on create but 1 on rename. The hook also runs before the residual check, so a dirty deck can be rendered first.
  • [silent-failure, code] slides_export.py:85 via render_web_banner.py:149: a failed trash of the temp Slides copy still counts as rendered. A sweep includes TemplateCity, where an orphan copy would be cloned into every new chapter.
  • [silent-failure] slides_export.py:40: the downloaded thumbnail is only size-checked. An HTML error page would be uploaded as the banner and stamped current.
  • [tests] test_render_web_banner.py: nothing asserts which file id gets the upload or the stamp, so a swap that overwrote the deck would stay green. The missing-checksum guard, _find duplicates and main() exit codes are untested.
  • [code, tests] rename_chapter.py:447: the rename hook has no test, though it changes the exit code.
  • [silent-failure, tests] render_web_banner.py:82: names_chapter is a substring check. "Portland" passes on "Portland, OR", and a slide still carrying a leftover city passes too.

Suggestions (8)

  • [types] render_web_banner.py:203: the final else counts any unknown action as current.
  • [code] render_web_banner.py:78: XML entities aren't unescaped, so a name with & is refused forever.
  • [code] rename_chapter.py:450: the rename hook creates a missing banner, against the sweep rule. A failed verify never mentions the banner.
  • [silent-failure] render_web_banner.py:155: a create followed by a failed upload leaves an empty banner, and the error doesn't say a file was made.
  • [silent-failure] render_web_banner.py:97: the duplicate error gives no ids. The wrong-name error doesn't point at DECK_NAME.
  • [comments] SKILL.md:197: it doesn't mention exit codes, that a sweep never creates banners, or that rename renders only after verify. Some docstring wording is off.
  • [comments] create_chapter.py:814: the fallback command is a bare filename, which doesn't resolve from an installed plugin.
  • [comments] test_create_chapter.py:14: a noqa moved to the wrong line.

Strengths

  • Security: no findings. Temp paths come from Drive ids, not names, and organizers gain nothing they couldn't already edit.
  • The stamp is written after the upload, files.create is NO_RETRY with a counted test, and report mode writes nothing.

Generated using wayfare.

- Stamp the deck checksum and the chapter name, so a renamed folder with an
  unchanged deck is checked again instead of reported current.
- Check the slide the renderer draws: resolve slide 4 by presentation order
  in the deck, and re-check the rendered page's own text in render_slide_png.
- Match the slide text exactly (headline plus name), unescape XML entities.
- render_slide_png: refuse a non-PNG download, name a short deck, and with
  strict_cleanup fail on an untrashed temp copy. A sweep skips TemplateCity
  unless it is named.
- The hooks get the Result: "already current" is no longer printed as
  "Rendered". Create exits 2 on a banner failure and skips a dirty deck.
  Rename never creates a banner, warns on stderr, and says so on a failed
  verify. Fallback commands print the script's absolute path.
- Tests: upload and stamp land on the banner, missing checksum, duplicate ids,
  main() exit codes, the rename hook, slide order and the renderer guards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rparundekar

Copy link
Copy Markdown
Collaborator Author

Self-Review: Improvements

Important (9 / 9 fixed):

  • render_web_banner.py: the stamp skipped the name check. Fixed: the stamp is now the deck md5 plus the chapter name, and a test covers a renamed folder with an unchanged deck.
  • render_web_banner.py: the slide checked might not be the slide rendered. Fixed: slide 4 is resolved by presentation order in the deck, and render_slide_png(check_text=...) re-checks the text of the page it actually draws.
  • create_chapter.py / rename_chapter.py: "current" printed as "Rendered". Fixed: sync_one returns the Result, and both hooks say "already current".
  • create_chapter.py: a banner failure exited 0, and a dirty deck could be rendered. Fixed: exit 2, and the banner is skipped when fresh files carry residuals.
  • slides_export.py: a failed temp-copy trash counted as success. Fixed: strict_cleanup=True fails the chapter and names the copy's id, and a sweep skips TemplateCity unless it is named.
  • slides_export.py: size-only download check. Fixed: a PNG signature check. A short deck and a missing thumbnail URL now give clear errors.
  • tests: upload and stamp targets were not pinned. Fixed: the fake Drive raises if either lands anywhere but the banner. Missing checksum, duplicates and main() exit codes are covered too.
  • rename_chapter.py: the hook was untested. Fixed: it moved into rerender_banner(), with tests for the name passed, never creating, and exit codes 0 and 1.
  • render_web_banner.py: substring name match. Fixed: an exact match (headline plus name, trailing punctuation ignored), with tests for "Portland, OR" and a leftover template city.

Suggestions (8 / 8 fixed):

  • Unknown outcomes now fail instead of counting as current.
  • XML entities are unescaped.
  • Rename leaves a folder with no banner as it is, and a failed verify names the banner command.
  • A create followed by a failed upload names the empty file.
  • Duplicate errors list the ids, and the wrong-name error points at DECK_NAME.
  • SKILL.md and the docstrings now match the code.
  • Fallback commands print the absolute script path.
  • The noqa is back on the right line.

Verification: library suite 598 passed, all aaif-create-chapter tests pass, pre-commit is clean. A live report over 120 folders found 119 to render and 0 refused. A live --write on one chapter rendered the right name at 2000x2000, left no temp copy, and re-runs as current.

Commits: 6b85073


Generated using wayfare.

@rparundekar rparundekar changed the title fix(create-chapter): render each chapter's Web Banner from its own deck fix(create-chapter): render each chapter's Web Banner from its deck Nov 3, 2026
@rparundekar

Copy link
Copy Markdown
Collaborator Author

Self-Review

Second pass, on head 6b85073, which includes the fixes from the first review. Six agents ran on the full diff (967 lines, 10 files).

Important (7)

  • [silent-failure-hunter] skills/aaif-create-chapter/scripts/render_web_banner.py:188: a folder with no banner and no Banners folder (or no deck) fails instead of reporting absent. The banner lookup runs after the deck lookup. A sweep would exit 1 on that folder forever, and a clean rename would warn about a banner that does not exist.
  • [silent-failure-hunter] skills/aaif-create-chapter/scripts/create_chapter.py:818: the fallback command printed when the create hook fails runs with create=False. If no banner file existed yet, the operator runs it, sees "left alone", gets exit 0, and the chapter never gets a banner.
  • [type-design, silent-failure-hunter, code-reviewer, comment-analyzer] lib/aaif_events/slides_export.py:131: with strict_cleanup, if the render fails AND the temp copy cannot be trashed, the copy's id goes only to a stderr warning. It never reaches the chapter's FAILED line.
  • [type-design] skills/aaif-create-chapter/scripts/create_chapter.py:825: any result that is not an error and not CURRENT prints "Rendered", including ABSENT. rename_chapter.py:472 raises KeyError on an unknown outcome after a rename has already landed.
  • [code-reviewer] skills/aaif-create-chapter/scripts/test_render_web_banner.py:274: the new NO_RETRY create site is tested by recording the keyword on a fake. AGENTS.md asks for a counted subprocess.
  • [pr-test-analyzer] tests mock one layer too high. Mutation testing (29 mutants, 13 survived) found:
    • main passing write=True in report mode survives, because the fake drops write.
    • sync_one running report-only, or without create, survives.
    • rename_chapter.main returning 0 instead of re-rendering survives.
    • No test covers a missing Banners folder, a missing deck, duplicate decks, or the renderer's fields mask.
  • [silent-failure-hunter] skills/aaif-create-chapter/scripts/create_chapter.py:813: under --resume, a Square Logo deck that is left dirty on purpose still gets a render attempt. The printed fallback can't work until --repair-existing runs.

Suggestions (9)

  • [code-reviewer] render_web_banner.py:156 and slides_export.py:44: text runs are joined with spaces, so a city split across runs ("Amster" + "dam") is refused. Runs within a paragraph should join with nothing.
  • [code-reviewer, comment-analyzer] render_web_banner.py:124: punctuation is stripped from the slide text but not from the expected name, so "Washington D.C." can never match.
  • [code-reviewer] render_web_banner.py:102: the fallback command quotes with %r, not shell quoting. An install path with spaces breaks it.
  • [type-design] slides_export.py:73: check_text returns an error or None. A caller passing a boolean predicate gets the opposite, and wrong slides pass.
  • [type-design] render_web_banner.py:110: the stamp does not say which slide or size was rendered, so changing SLIDE_INDEX would leave every banner marked current.
  • [silent-failure-hunter] render_web_banner.py:269: --jobs 0 crashes with a traceback.
  • [comment-analyzer] docstrings and docs claim more than the code does:
    • the strict_cleanup wording
    • the name_mismatch normalisation
    • the _page_text table text
    • exit 0 covering absent banners
    • why rename misses badges (it never opens SVG/PNG)
    • the Summary bullet
    • the SKILL.md checklist missing the "already current" and dirty-file outcomes
  • [pr-test-analyzer] the "never called" stubs reject keyword arguments, so they fail for the wrong reason. The dirty-clone test does not check its exit code. Tests build results from literal strings instead of the constants.
  • [pr-test-analyzer] untested: a package-absolute slide target, a missing contentUrl, and the slide-count boundary.

Strengths

  • Security found nothing exploitable. Untrusted decks are read with regexes inside the zip, never extracted, and argv is built without a shell.
  • The stamp is written last and carries both the md5 and the name. A missing md5 is an error, and non-PNG downloads are refused.
  • Every failure in this review is loud or fails closed. None publishes a wrong banner.

Generated using wayfare.

- A folder with no banner is absent before the Banners folder or deck is
  looked up, so it never fails a sweep or a rename.
- New --create flag (with --chapter only). The create hook's fallback
  command uses it, so a render that failed before the file existed can be
  finished.
- strict_cleanup puts the stray copy's id in the raised error even when the
  render also failed.
- create_chapter prints "Rendered" only for a render. rename_chapter treats an
  unknown outcome as exit 1, not a KeyError.
- A dirty existing Square Logo deck under --resume is not rendered. The
  advice now comes after --repair-existing.
- Runs within a paragraph or shape are joined with nothing, so a split word
  still matches. Punctuation at the ends of the expected name is stripped too.
- check_text rejects a non-string return. The fallback command is
  shell-quoted. --jobs must be at least 1. The stamp key notes when to
  rename it.
- Tests:
  - the NO_RETRY create counted at the subprocess;
  - write passed through main;
  - sync_one end to end;
  - rename main wiring;
  - missing folder, deck and duplicate decks;
  - the fields mask, the strict cleanup combo, and boundary cases.
- Docs now match the code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rparundekar

Copy link
Copy Markdown
Collaborator Author

Self-Review: Improvements

Important (7 / 7 fixed):

  • render_web_banner.py:188: a folder with no banner and no Banners folder failed the sweep. Fixed: the banner is checked first, and with no banner and no create, the result is absent before anything else is looked up.
  • create_chapter.py:818: the fallback command could not create the banner. Fixed: new --create flag, allowed only with --chapter. The create hook prints a command that uses it.
  • slides_export.py:131: the stray copy's id was lost when the render also failed. Fixed: with strict_cleanup, the raised error carries the render error and the copy's id together.
  • create_chapter.py:825, rename_chapter.py:472: "Rendered" was printed for any non-error result, and an unknown outcome raised KeyError. Fixed: create_chapter prints "Rendered" only for a render and warns with exit 2 otherwise. An unknown outcome in rename_chapter returns 1 with a warning.
  • test_render_web_banner.py: the NO_RETRY create is now tested at a counted subprocess. Fixed. Dropping the keyword fails the test (checked by mutation).
  • tests: added coverage for:
    • write passed through main, plus a mutation check that hard-coding True fails;
    • sync_one end to end;
    • rename_chapter.main wiring (verified write, failed verify, report);
    • missing Banners folder, missing deck and duplicate decks;
    • the fields mask, and the strict-cleanup case where the render also failed;
    • the slide-count boundary, a missing contentUrl, and package-absolute targets.
  • create_chapter.py:813: under --resume, a dirty existing deck got a render attempt. Fixed: it is skipped, and the command to run after --repair-existing is printed.

Suggestions (8 / 9 fixed):

  • Runs inside a paragraph (OOXML) or a shape (Slides API) are now joined with nothing, so "Amster" + "dam" reads as one word. Fixed.
  • Punctuation is now stripped from both ends of the expected name too. Fixed.
  • The fallback command uses shlex.quote for the path and the name. Fixed.
  • check_text raises TypeError on anything but None or a string. Fixed.
  • --jobs must be at least 1. Fixed.
  • Docstrings, SKILL.md and rename-chapter.md now say what the code does. Fixed.
  • Test hygiene: the "never called" stubs accept keyword arguments, the dirty-clone test checks its exit, and tests use the outcome constants. Fixed.
  • RENDER meaning "would render" in report mode is now in the Result docstring. Fixed.

Skipped:

  • render_web_banner.py:110: not adding the slide index to the stamp. Skipped: the estate sweep just stamped 118 banners, and changing the stamp format would re-render all of them for no visible change. A comment on STAMP now says to rename the key if SLIDE_INDEX or the size changes.

Commits: 37a7515


Generated using wayfare.

@rparundekar
rparundekar marked this pull request as ready for review November 3, 2026 21:49
@rparundekar
rparundekar merged commit bc79577 into main Nov 3, 2026
3 checks passed
@rparundekar
rparundekar deleted the fix/web-banner-render branch November 3, 2026 21:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant