nodes/malkuthro-ComfyUI-Koolook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
b5b46d7fccf0111292e059d4d4bc47782d2fd70f
malkuthro-ComfyUI-Koolook/docs/maintainers/dev-iteration-loop.md
T
malkuthro 1d9d40ab70 Add audio transcript timeline node (#189) 
* Add audio transcript timeline node

* Hook audio transcripts into Koolook Director

* Add modular timeline audio timing workflow

* fix(frontend): guard Comfy workflow draft cache

* fix(audio): compose transcript timeline prompts

* fix(audio): address transcript review findings

* fix(ci): keep transcript tests lightweight

* fix(timeline): restore image previews from saved paths

* fix(timeline): scrub restored preview blobs
2026-05-30 18:31:41 +02:00

134 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. **If a design mockup exists** for what you just implemented (look
under [`docs/designs/`](../designs/)), screenshot the running result
and diff against the mockup. Don't request review until visual parity
is reached or each deviation is documented. See the [project
CLAUDE.md](../../CLAUDE.md) *"Visual verification for design-driven
implementation"* section for the full rule.
5. 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 and manual ComfyUI restarts never wipe 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`).
- **For frontend preview buttons, inspect the virtual-node implementation
before guessing.** ComfyUI custom nodes such as EasyUse GET/SET can be
frontend-only tunnels: render-time Python receives the resolved value, but
a JS preview button may only see the visible GET key unless it follows the
tunnel itself. Read the installed custom node JS, then simulate the relevant
LiteGraph shape locally before asking the maintainer to test.
## Debugging frontend preview buttons
Frontend preview buttons, such as Easy AI Pipeline's `Get output file path`,
are not the same execution path as the node's Python outputs. The button code
runs in browser JS and often peeks at connected widgets; the real render path
runs through ComfyUI execution and may resolve virtual or dynamic nodes that
the preview cannot see by default.
When a preview disagrees with render-time output:
1. Confirm whether the fix is Python, JS, or both. Python changes need a
ComfyUI restart; JS changes need the browser tab to reload the extension
module. Restarting ComfyUI alone does not guarantee an already-open tab has
re-imported `web/*.js`.
2. Verify the served extension file directly, e.g.
`http://127.0.0.1:8188/extensions/koolook/ai_pipeline.js`, and add a
short temporary marker when needed so the loaded frontend version is
provable.
3. Inspect the connected custom node's frontend source in the live
`custom_nodes/` install. EasyUse GET/SET nodes live in
`comfyui-easy-use/web_version/v1/js/getset.js`.
4. If the connected node is a virtual tunnel, follow its graph semantics
manually. EasyUse `easy getNode` stores the visible key in its `Constant`
widget; the actual value lives upstream of the matching `easy setNode`
input link.
5. Build a small local JS simulation of the LiteGraph shape
(`GET -> SET -> source`) before dev-syncing another guess.
Do not assume the in-browser automation can always read `app.graph` from the
modern ComfyUI frontend. If the graph object is not exposed, use source
inspection, served-file checks, and small simulations instead.
## 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
Reference in New Issue View Git Blame Copy Permalink