malkuthroandClaude Opus 4.7
a0a8469448
Five user-visible changes to the Kforge Labs sidebar that complete the
dev-sync verification loop and fix theme-mode discovery:
- Build-tag footer at the bottom of the sidebar: `dev <sha> · <time>`
on line 1 (SHA at 13px monospace, the at-a-glance identifier),
italic <scope> on line 2. Reads `web/_dev_build.json` written by
`scripts/sync_to_dev.py --scope "<short scope>"`. Visible-in-app
companion to PR #95's chat-report convention — closes the gap when
the maintainer is juggling parallel sessions and can't tell whether
the browser tab is showing the latest sync. Absent on registry
installs; footer renders empty there.
- Theme/category mode now mirrors repo-mode population: REPOS auto-
pull union user-picks, deduped, with the new auto-pull-hidden set
filtered out. The earlier picks-only design dropped the entire
Koolook pack from theme mode on a stock install, even though those
same nodes appeared in repo mode — silently violating the "my
favorites in two views" mental model. `gatherNodesByTheme` rewritten
to seed from REPOS first, then user picks, with the same
autoCategoryRoots + hidden filtering repo mode uses.
- `×` works on every favorite, including auto-pulled REPOS nodes.
Adds `koolook.autoPullHidden.v1` localStorage Set; `×` on an auto-
pulled row calls `hideAutoPullType(type)` so the next render skips
it. `addToMyPicks` calls `unhideAutoPullType` as a side effect so
re-adding via `+` automatically restores visibility. Same uniform
"remove / bring back" UX whether the node was a user pick or REPOS
auto-pull.
- Pack-name badges restored on theme-mode leaves only. Small dim
`Koolook` / `KJNodes` text on the right of each row, same opacity
as the search-flatten breadcrumb. Memory aid for "where did this
node come from?" Repo mode and search-flatten still skip the badge
(origin is conveyed by tree nesting / breadcrumb prefix).
- `scripts/sync_to_dev.py --scope` flag: extends PR #95's brief-
output design with a JSON artifact (`<target>/web/_dev_build.json`)
carrying commit + timestamp + worktree + scope, which the sidebar
footer fetches on render. Doesn't change the existing one-line
chat-report contract or the `_build_line()` shape.
Tested via dev-sync against the live ComfyUI install:
- Footer renders correctly (`dev afe539e · 2026-05-06 15:38` + scope)
- Image bucket in theme mode now contains Koolook image nodes
- Pack badges visible on theme leaves
- × hides auto-pulled Koolook nodes; toolbar + restores them
CHANGELOG entries added; the prior conflicting [Unreleased] notes
about picks-only theme + pack-badge removal are flagged as superseded
in the new entries (release prep can squash).
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
136 lines
6.5 KiB
Markdown
136 lines
6.5 KiB
Markdown
# ComfyUI-Koolook Agent Workflow
|
||
|
||
## Source-of-truth model
|
||
|
||
- MAIN repo: `ComfyUI-Koolook`
|
||
- External forks root (default): `../ComfyUI-Forks` (relative to MAIN)
|
||
- External third-party code must remain outside MAIN.
|
||
- Sibling projects (read-only references that live outside MAIN) are referenced via `KOLOOK_*` env vars only. Never hardcode absolute paths with usernames in committed files. Real paths live in `.env` (gitignored); the committed `.env.example` is the public template. See README "Sibling Projects" and `docs/reference/glossary.md`.
|
||
|
||
## Hard rules
|
||
|
||
- Do not vendor/copy full third-party repositories into MAIN.
|
||
- Keep MAIN limited to:
|
||
- custom Koolook nodes
|
||
- wrapper loaders under `forks/`
|
||
- fork tracking docs under `forks/`
|
||
- For third-party integrations, update:
|
||
- `forks/forks_manifest.yaml`
|
||
- `forks/THIRD_PARTY.md`
|
||
- `forks/README.md` (if workflow conventions change)
|
||
|
||
## Radiance fork policy (v2_3_3)
|
||
|
||
- Package entrypoint: `forks/radiance_koolook/__init__.py`
|
||
- Modified nodes live in MAIN and are GitHub-tracked:
|
||
- `forks/radiance_koolook/versions/v2_3_3/nodes_vae.py`
|
||
- External sibling checkout (`../ComfyUI-Forks/radiance-v2.3.3-koolook`) is raw reference only.
|
||
- Current baseline pin for raw comparison: `f262f47ddfda01ece154bf80c22769b1e4cef795` (the v2.3.3 release commit; the cleanest tag pointing at it is the typo'd `radinace2.3.3`, so we pin by SHA).
|
||
- Koolook-original node IDs (`Easy_hdr_VAE_encode`, `Easy_hdr_VAE_decode`) are exposed verbatim via the `SKIP_VERSION_SUFFIX` set in `versions/v2_3_3/__init__.py`. Future Koolook nodes in this fork can opt out the same way; future ports of upstream-named classes should keep the `__koolook_v2_3_3` suffix to avoid colliding with installed copies of upstream Radiance.
|
||
- `forks/forks_manifest.yaml` must include `source_ref` + `pinned_commit` + `license` + `license_verified_at`.
|
||
- The historical `v1_0_1` fork was removed in v0.1.5 — see `forks/THIRD_PARTY.md` for the rationale and recovery instructions.
|
||
|
||
## Change management
|
||
|
||
- When upgrading external forks (v2, v3, etc.), add a new wrapper/version namespace.
|
||
- Never rename existing namespaced node IDs that already appear in saved workflows.
|
||
|
||
## `dev-sync` — copy runtime files into a live ComfyUI install
|
||
|
||
Fast iteration without cutting a release. Copies runtime files to
|
||
`KOLOOK_COMFYUI_DEV_PATH` (set in `.env`; see `.env.example`).
|
||
|
||
- `python scripts/sync_to_dev.py --scope "<short scope>"` — brief two-line summary; use `-v` for per-file output
|
||
- `--dry-run` — preview without touching the target
|
||
|
||
**Always pass `--scope`** with the same ≤10-word scope summary you'll
|
||
put on chat-report line 2. The flag persists the scope to
|
||
`<target>/web/_dev_build.json`, which the Kforge Labs sidebar reads on
|
||
load and renders as a discreet two-line footer (`dev <sha> · <time>` +
|
||
italic `<scope>` underneath). Same identifier the chat report quotes,
|
||
but visible in the running ComfyUI itself — closes the gap when the
|
||
maintainer can't tell at a glance whether the browser tab is showing
|
||
the latest sync.
|
||
|
||
**Trigger phrase: `dev-sync`** (or "copy those files", "sync dev", "push to dev").
|
||
The agent runs the script and reports completion. The script errors
|
||
cleanly when the env var is unset; never guess a path.
|
||
|
||
**User-initiated ONLY — never automatic.** Dev-sync overwrites the
|
||
maintainer's live ComfyUI install. Do NOT trigger it as part of any
|
||
automated flow:
|
||
|
||
• after a commit
|
||
• after a PR merge or `/ship-pr`
|
||
• at session end / wrap-up
|
||
• on hook completion or "task complete" cleanup
|
||
• from any agent skill that doesn't explicitly require it
|
||
|
||
The maintainer typically runs multiple parallel sessions across worktrees;
|
||
an unsolicited sync from one session silently overwrites what another is
|
||
reviewing in ComfyUI, and the wrong code gets reviewed. Wait for the
|
||
explicit trigger phrase. If unsure whether the user wants a sync, ASK —
|
||
don't sync.
|
||
|
||
**Chat report format** — two lines, copied verbatim from the script's
|
||
own header line:
|
||
|
||
```
|
||
<short-sha> - <worktree-name>
|
||
<≤10 word summary of the PR / change scope to review>
|
||
```
|
||
|
||
Line 1 is the script's first output line — never invent it, just relay.
|
||
Line 2 is the *scope of what to review* — the change in this build, ≤10
|
||
words, no list of all files. Examples:
|
||
|
||
```
|
||
8dfb966 - dreamy-jones-40655e
|
||
Quick Save + status dot + recovery section
|
||
|
||
a1b2c3d - feat-install-missing
|
||
install-missing button on Nodes row
|
||
```
|
||
|
||
Broader iteration pattern (push/publish gates, what survives re-syncs)
|
||
is in [`docs/maintainers/dev-iteration-loop.md`](docs/maintainers/dev-iteration-loop.md).
|
||
|
||
## Kforge Labs sidebar — starter preset distribution
|
||
|
||
The "Kforge Labs" ComfyUI sidebar tab (implemented in
|
||
`web/koolook_sidebar.js`) ships a single bundled snapshot file at
|
||
`web/starter_preset.json`. On first launch the seeder copies it into
|
||
the user's snapshot library directory (the same dir the Snapshot
|
||
Save/Load dialog reads) as `starter.json`. The user opens Snapshot →
|
||
Load, picks `starter`, clicks → picks + workflows + tags + archive
|
||
populated in one go.
|
||
|
||
To update the distributed starter preset:
|
||
|
||
1. Inside ComfyUI's Kforge Labs tab, dial in the state you want fresh
|
||
users to see — picks via `+` / `×` / right-click; workflows via the
|
||
Workflows section; tags via right-click → Tags…
|
||
2. In the **Tools** row (between Snapshot and the search field), click
|
||
the ↓ button → full snapshot JSON copied to clipboard.
|
||
3. Paste into `web/starter_preset.json`, replacing the file contents.
|
||
4. Commit + push (does **not** trigger publish — only `pyproject.toml`
|
||
changes merged to `main` do).
|
||
|
||
Full workflow including reset / verification steps:
|
||
[`docs/maintainers/curated-sidebar.md`](docs/maintainers/curated-sidebar.md).
|
||
The seeder runs exactly once per browser AND skips users with non-empty
|
||
existing picks (legacy curated_defaults.json users), so changing the
|
||
shipped starter doesn't disturb anyone's existing state — the new
|
||
starter only reaches fresh installs and users who clear browser data.
|
||
|
||
## Releasing
|
||
|
||
- The canonical release procedure is `docs/maintainers/releasing.md`. Follow it for every
|
||
`vX.Y.Z` cut — do not invent a one-off flow.
|
||
- The per-release tickbox mirror is `.github/ISSUE_TEMPLATE/release_checklist.md`.
|
||
Open one as a tracking issue when starting a release.
|
||
- Always validate the Comfy Registry publish against the PR branch
|
||
(`gh workflow run publish.yml --ref release/vX.Y.Z-prep`) before merging.
|
||
A `Failed to validate token` error is almost always a `[tool.comfy] PublisherId`
|
||
mismatch, not a token problem.
|