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>
89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# 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) |
|
||
|
||
```bash
|
||
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
|
||
|
||
1. Edit `web/koolook_sidebar.js` or any module under `web/sidebar/` (or related JSON) in the worktree.
|
||
2. `python scripts/sync_to_dev.py` — copies runtime files into your live
|
||
ComfyUI `custom_nodes/<koolook>/`. Reads `KOLOOK_COMFYUI_DEV_PATH` from `.env`.
|
||
3. Restart ComfyUI; verify visually.
|
||
4. 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.toml` changes and the push lands on
|
||
`main`. Full procedure: [`releasing.md`](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_frontend`
|
||
source before guessing.** E.g. the `loadGraphData(graph, true, true, wfName, {})`
|
||
4th-arg trick that names the workflow tab was pulled from upstream
|
||
`src/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 `pathStates` Map in `web/sidebar/tree.js`).
|
||
|
||
## Files this loop touches most
|
||
|
||
- [`web/koolook_sidebar.js`](../../web/koolook_sidebar.js) — sidebar entry (boots the extension; module bodies live in [`web/sidebar/`](../../web/sidebar/))
|
||
- [`web/starter_preset.json`](../../web/starter_preset.json) — bundled starter preset (replaces the legacy `curated_defaults.json` pick-only seed)
|
||
- [`web/workflow_defaults.json`](../../web/workflow_defaults.json) — workflow defaults
|
||
- [`scripts/sync_to_dev.py`](../../scripts/sync_to_dev.py) — dev sync helper
|
||
- [`docs/maintainers/curated-sidebar.md`](curated-sidebar.md) — starter-preset round-trip detail
|