malkuthroandClaude Opus 4.7
413b153702
Audit triggered while debugging the v0.2.0 release surfaced drift in the maintainer docs vs current code: dead curated_defaults.json references (file replaced by starter_preset.json in PR #72), the v1_0_1 fork example (removed in v0.1.5), and a "tooling we don't have yet" entry that's now covered by tools/preflight_release.py. Adds a new conventions.md for cross-cutting rules — currently the Mermaid-for-diagrams convention. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4.5 KiB
4.5 KiB
Iterative dev loop — sidebar work
How the Curated Nodes / Workflows sidebar was built, in case you come back to it after a break. Optimized for fast iteration without the publish round-trip.
First-time setup on a new machine
KOLOOK_COMFYUI_DEV_PATH should point at the eventual Koolook subdirectory
inside your live ComfyUI custom_nodes/ folder — not the custom_nodes/
parent itself.
| Platform | Typical path |
|---|---|
| macOS | /Volumes/Data/ComfyUI/custom_nodes/ComfyUI-Koolook |
| Linux | /home/<user>/ComfyUI/custom_nodes/ComfyUI-Koolook |
| Windows | C:/ComfyUI_portable/ComfyUI/custom_nodes/ComfyUI-Koolook (forward slashes work fine) |
cp .env.example .env # if you don't have one yet
$EDITOR .env # set KOLOOK_COMFYUI_DEV_PATH
python scripts/sync_to_dev.py --init # creates the leaf folder + first sync
# restart ComfyUI to pick up the new install
After that first run, drop the --init — plain python scripts/sync_to_dev.py
is enough for every subsequent edit. The --init flag is a one-shot guard
against typos: it refuses to create a Koolook folder unless the parent looks
like a ComfyUI custom_nodes/ directory (named custom_nodes or sitting
inside a ComfyUI parent).
The loop
- Edit
web/koolook_sidebar.jsor any module underweb/sidebar/(or related JSON) in the worktree. python scripts/sync_to_dev.py— copies runtime files into your live ComfyUIcustom_nodes/<koolook>/. ReadsKOLOOK_COMFYUI_DEV_PATHfrom.env.- Restart ComfyUI; verify visually.
- Iterate.
End-to-end: ~10–30 seconds. No tag/publish round-trip.
Trigger phrases when working with the agent
| You say | Agent does |
|---|---|
dev-sync (or "sync to dev", "copy those files") |
runs scripts/sync_to_dev.py |
go |
implements the most-recently proposed plan as code |
| paste exported JSON from the ↓ button | replaces the matching web/<feature>_defaults.json |
What survives across re-syncs and ComfyUI restarts
| Data | Lives in | Persistence |
|---|---|---|
| Node favorites (per user) | localStorage["koolook.curated.userPicks.v1"] |
survives JS updates, ComfyUI restarts, browser refreshes |
| Saved workflows incl. archive (per install) | ComfyUI /userdata/koolook_workflows.json |
survives JS updates and ComfyUI restarts |
| Distributed defaults — starter preset | web/starter_preset.json (in repo) |
copied once into the user's snapshot library as starter.json on first ComfyUI load (replaces the legacy curated_defaults.json localStorage seed) |
| Distributed defaults — workflows | web/workflow_defaults.json (in repo) |
seeded once into /userdata on first ComfyUI load |
dev-sync + restart never wipes user state. Only localStorage.clear(),
deleting /userdata/koolook_workflows.json, or wiping browser data does.
Commit / push / publish gates
- Commit after a stable batch of working changes — not after every edit.
- Pushing a feature/PR branch never triggers a Comfy Registry publish.
- Publish fires only when
pyproject.tomlchanges and the push lands onmain. Full procedure:releasing.md.
Tips that paid off in this build
- Annotated screenshots (a red arrow on the spot you're talking about) beat text descriptions for UI feedback every time.
- Verify uncertain frontend APIs against
Comfy-Org/ComfyUI_frontendsource before guessing. E.g. theloadGraphData(graph, true, true, wfName, {})4th-arg trick that names the workflow tab was pulled from upstreamsrc/scripts/app.ts, not guessed. - Defensive fallbacks when calling a newer ComfyUI API surface — multiple property paths inside try/catch so older frontends still work.
- Persist folder expansion state across re-renders so saving doesn't
collapse the user's view (the
pathStatesMap inweb/sidebar/tree.js).
Files this loop touches most
web/koolook_sidebar.js— sidebar entry (boots the extension; module bodies live inweb/sidebar/)web/starter_preset.json— bundled starter preset (replaces the legacycurated_defaults.jsonpick-only seed)web/workflow_defaults.json— workflow defaultsscripts/sync_to_dev.py— dev sync helperdocs/maintainers/curated-sidebar.md— starter-preset round-trip detail