Files

T

malkuthroandClaude Opus 4.7 0d4c81295b chore(sync): --init flag for first-run dev-sync setup + Mac path docs (#61 )

Background
----------
Setting up `scripts/sync_to_dev.py` on a fresh machine required two
pre-steps the script didn't help with: (1) editing `.env` to point at
a path that didn't exist yet, then (2) `mkdir -p` on that path before
the first sync would work. The script errored out cleanly with
"target does not exist" but didn't tell the user the obvious next
move was to create it. This was particularly silent on Mac where the
ComfyUI install path differs from the Windows examples in `.env.example`.

Changes
-------
- **`--init` flag** on `scripts/sync_to_dev.py`. When the target
  directory doesn't exist and `--init` is passed, the script creates
  it and proceeds with the sync. Without `--init`, it errors out with
  the same "first time on this machine?" hint pointing at the new flag.
- **Safety guards** on `--init`. Refuses (exit 3) if:
  - the parent directory doesn't exist, OR
  - the parent doesn't look like a ComfyUI `custom_nodes/` folder
    (heuristic: parent is named `custom_nodes` OR sits inside a
    directory named `ComfyUI`).
  This prevents a typo in `KOLOOK_COMFYUI_DEV_PATH` from quietly
  creating a `ComfyUI-Koolook/` somewhere unexpected on disk. The
  refusal message includes a manual escape hatch (`mkdir -p` + retry
  without `--init`) for the case where the parent really IS the
  ComfyUI install but doesn't match the heuristic.
- **Drop stale `k_easy_version.py`** from `RUNTIME_PATHS`. The file
  was deleted in v0.1.10 (PR #41); the script's `if not src.exists()`
  guard meant it was a no-op every run, but the entry was misleading.
- **`.env.example`** gains explicit macOS / Linux / Windows path
  examples for `KOLOOK_COMFYUI_DEV_PATH` and a 3-step first-run
  recipe (cp .env.example → edit → `--init`).
- **`docs/maintainers/dev-iteration-loop.md`** gains a "First-time
  setup on a new machine" section with the per-OS path table and the
  same 3-step recipe.

Verification
------------
- `python scripts/sync_to_dev.py --dry-run` against a missing target
  → exit 2, hint at `--init`.
- `python scripts/sync_to_dev.py --init` against a real ComfyUI
  `custom_nodes/` parent → creates the leaf, copies 9 entries, exits 0.
- `python scripts/sync_to_dev.py` (no flag) re-run after `--init` →
  re-syncs cleanly, idempotent.
- `python scripts/sync_to_dev.py --init` against `/tmp/not-custom-nodes`
  → exit 3, "parent does not exist".
- `python scripts/sync_to_dev.py --init` against an existing
  `/tmp/wrong-parent` (not custom_nodes) → exit 3, "doesn't look like
  a ComfyUI custom_nodes/ folder", manual escape hatch in the message.
- `python -c "import ast; ast.parse(open('scripts/sync_to_dev.py').read())"`
  → syntax OK.
- `python tools/preflight_release.py --skip manager-meta -v` → PASS.

No CHANGELOG entry — dev-tooling under `scripts/` doesn't ship to
users of the published package. Avoiding noise on the [Unreleased]
section that PRs #59 / #60 also touch.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-05 08:58:24 +02:00

4.3 KiB

Raw Permalink Blame History

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.js or any module under web/sidebar/ (or related JSON) in the worktree.
python scripts/sync_to_dev.py — copies runtime files into your live ComfyUI custom_nodes/<koolook>/. Reads KOLOOK_COMFYUI_DEV_PATH from .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 — nodes	`web/curated_defaults.json` (in repo)	seeded once into user `localStorage` on first ComfyUI load
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.

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 — sidebar entry (boots the extension; module bodies live in web/sidebar/)
web/curated_defaults.json — node defaults
web/workflow_defaults.json — workflow defaults
scripts/sync_to_dev.py — dev sync helper
docs/maintainers/curated-sidebar.md — node-defaults round-trip detail

4.3 KiB Raw Permalink Blame History Unescape Escape