Toilville/toilville-design
Watch
5
1
Fork
You've already forked toilville-design
 0
Code Issues 21 Pull requests Projects Releases Packages Wiki Activity Actions

feat(tools): just doctor + designer quickstart #194

Merged
peterswimm merged 1 commit from feat/designer-doctor into main 2026-10-07 23:02:49 +00:00
Conversation 0 Commits 1 Files changed 7 +293 -2
peterswimm commented 2026-10-07 23:01:10 +00:00
Owner
Copy link

Scope

Step 2 of the designer-tooling roadmap: the local path for building, plus one page that ties the
whole flow together.

  • tools/doctor.py (stdlib), also runnable as just doctor. It checks a machine for local
    builds. Each missing item prints the brew or pip command that installs it.
    • Required: python ≥ 3.10 and git.
    • Recommended: just, pre-commit and its installed hook, and jsonschema. just check imports
      jsonschema, so the full gate is not stdlib-only.
    • Optional, each named with the command that needs it: ghostscript and poppler (just plates),
      pandoc (just doc), resvg (just assets-raster) and pytest.
    • It exits 1 only when a required tool is missing, so it runs on a fresh machine before just is
      installed. It also prints the repoRoot to set for the Affinity scripts.
  • docs/DESIGNER_QUICKSTART.md: one page from Affinity export to merged PR. It includes a
    no-terminal path (Forgejo web upload plus the build-dist label from #193) and a table of
    common errors. Linked from README.md and the affinity-scripts README.
  • Pre-commit hook names now give the fix: "run just build, or add the build-dist label to
    your PR".

Testing

  • generator/tests/unit/test_doctor.py (4 tests). A missing git fails with exit 1 and prints
    the fix; this is the control that must fail. Missing recommended or optional tools still exit 0.
  • Full suite: PYTHONPATH=. pytest generator/tests: 284 passed. just check: exit 0.
  • Ran on Peter's Mac: it correctly flags pre-commit (the hook file exists but the binary isn't on
    PATH), plus pandoc and resvg as optional.

Impact Statement

  • Existing features: no expected impact. A new script and recipe; the hooks behave the same, only
    their names changed.
  • Public APIs / contracts: none.
  • Schemas: none.
  • Data / artifacts: none. No dist/ change.
  • Integrations: none.
  • Mappings: none.
  • Backward compatibility: fully compatible.

Docs

New docs/DESIGNER_QUICKSTART.md, with links from README.md and the affinity-scripts README.
The no-terminal path assumes #193 (build bot) is merged and its label and secret are set up.

## Scope Step 2 of the designer-tooling roadmap: the local path for building, plus one page that ties the whole flow together. - **`tools/doctor.py`** (stdlib), also runnable as `just doctor`. It checks a machine for local builds. Each missing item prints the `brew` or `pip` command that installs it. - Required: python ≥ 3.10 and git. - Recommended: `just`, `pre-commit` and its installed hook, and `jsonschema`. `just check` imports `jsonschema`, so the full gate is not stdlib-only. - Optional, each named with the command that needs it: ghostscript and poppler (`just plates`), pandoc (`just doc`), resvg (`just assets-raster`) and pytest. - It exits 1 only when a required tool is missing, so it runs on a fresh machine before `just` is installed. It also prints the `repoRoot` to set for the Affinity scripts. - **`docs/DESIGNER_QUICKSTART.md`**: one page from Affinity export to merged PR. It includes a no-terminal path (Forgejo web upload plus the `build-dist` label from #193) and a table of common errors. Linked from `README.md` and the affinity-scripts README. - **Pre-commit hook names** now give the fix: "run `just build`, or add the build-dist label to your PR". ## Testing - `generator/tests/unit/test_doctor.py` (4 tests). A missing **git** fails with exit 1 and prints the fix; this is the control that must fail. Missing recommended or optional tools still exit 0. - Full suite: `PYTHONPATH=. pytest generator/tests`: 284 passed. `just check`: exit 0. - Ran on Peter's Mac: it correctly flags `pre-commit` (the hook file exists but the binary isn't on PATH), plus pandoc and resvg as optional. ## Impact Statement - Existing features: no expected impact. A new script and recipe; the hooks behave the same, only their names changed. - Public APIs / contracts: none. - Schemas: none. - Data / artifacts: none. No `dist/` change. - Integrations: none. - Mappings: none. - Backward compatibility: fully compatible. ## Docs New `docs/DESIGNER_QUICKSTART.md`, with links from `README.md` and the affinity-scripts README. The no-terminal path assumes #193 (build bot) is merged and its label and secret are set up.
feat(tools): just doctor + designer quickstart
Some checks failed
PR policy check / policy-gate (pull_request) Successful in 1s
Details
Block Validation / validate (pull_request) Successful in 54s
Details
Security Scans / Gitleaks secret scan (pull_request) Successful in 24s
Details
Security Scans / Trivy filesystem scan (pull_request) Failing after 30s
Details
Test Generator / lint-workflows (pull_request) Successful in 14s
Details
UDG dist drift gate / dist/ matches dtcg + udg sources (pull_request) Successful in 13s
Details
Test Generator / lint-prose (pull_request) Successful in 18s
Details
Copy coverage / Design copy reaching rendered HTML (pull_request) Successful in 25s
Details
Test Generator / test (pull_request) Successful in 3m41s
Details
ee587ed964 
tools/doctor.py (stdlib) checks a machine for local builds: python >= 3.10
and git are required; just, pre-commit (+ installed hook) and jsonschema
(which `just check` imports) are recommended; ghostscript, poppler, pandoc,
resvg and pytest are optional and named with the command that needs them.
Each miss prints the brew/pip command that fixes it. Exits 1 only for a
missing required tool, so it runs on a fresh machine before `just` exists
(`python3 tools/doctor.py`, or `just doctor`).

docs/DESIGNER_QUICKSTART.md is one page from Affinity export to merged PR,
with a no-terminal path (Forgejo web UI + the build-dist label from #193)
and an error table. Linked from README.md and the affinity-scripts README.
The pre-commit drift-gate hook names now say how to fix a failure.
peterswimm deleted branch feat/designer-doctor 2026-10-07 23:02:49 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
build-dist
Ask the UDG build bot to run just build and commit generated files to this PR

  
priority
P1
 Urgent — no working icon yet (custom art pending) or a shipping asset

  
priority
P2
 High — has an accessible stand-in; bespoke art wanted

  
priority
P3
 Medium — stage visual headers

  
priority
P4
 Low — behavioral dimension family

  
bug
Something is not working

  
duplicate
This issue or pull request already exists

  
enhancement
New feature

  
help wanted
Need some help

  
invalid
Something is wrong

  
question
More information is needed

  
wontfix
This won't be fixed

No labels
build-dist
priority
P1
priority
P2
priority
P3
priority
P4
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Toilville/toilville-design!194
No description provided.