diff --git a/README.md b/README.md index b011aec..b006fa0 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ A workflow of about 25 nodes takes around 10 minutes. A large workflow can take ## What you get - +ba_04_allinone_dark - **The rebuilt workflow**: a `.json` file with `_readable` appended to the original name. The original file is not overwritten. - **report.html**: open it in a browser to watch the AI rebuild the workflow and read an explanation of the result. diff --git a/skills/comfyui-readable-node/SKILL.md b/skills/comfyui-readable-node/SKILL.md index 46e770f..603439e 100644 --- a/skills/comfyui-readable-node/SKILL.md +++ b/skills/comfyui-readable-node/SKILL.md @@ -60,12 +60,23 @@ The rules in the references serve these principles and goals; how to read a rule ## Steps -`S` is the path of scripts/. Choose one working folder `W` inside the folder where the results go (the one the user named; otherwise next to the original), and type every canvas move as `python3 $S/canvas.py --dir $W `. Below, this is written `canvas`. The list of moves, their syntax and the detailed behavior (undo, placements calculated only once, block, and so on) are at the top of canvas.py (`python3 $S/canvas.py` prints them): read it once before step 4. +`S` is the path of scripts/. The results go in the folder the user named; otherwise next to the original, or the current folder when there is no original. Make one working folder `W` there for this job, named after the workflow it builds with `_work` after it (`image_flux2_klein_text_to_image_work`, `flux_text_to_image_work`), and type every canvas move as `python3 $S/canvas.py --dir $W `. Below, this is written `canvas`. The list of moves, their syntax and the detailed behavior (undo, placements calculated only once, block, and so on) are at the top of canvas.py (`python3 $S/canvas.py` prints them): read it once before step 4. - Put every file you make while working inside `W`: plan files (build.txt for building, layout.txt for arranging: "the plan" is layout.txt), Note files, workflows or object_info you fetch to read, notes. Only the exported workflows and the report page go outside `W`. `canvas finish` deletes the files of `W` it knows (what it wrote, the plan and Note files, understanding.md) and names the others it left: delete only those, one by one. Do not delete `W` with a recursive delete. -Moves marked "(when there is an original)" are only for rebuilding a given workflow. When building a new one, skip them. - -When the user asks for it fast, skip steps 9 and 10 (the review and the report page), finish with `canvas finish fast`. +Which steps apply. Moves marked "(when there is an original)" in the steps are only for rebuilding a given workflow. "Fast" is when the user asks for it fast; it applies to both. + +| Step | Rebuilding a given workflow | Building a new one | Fast | Done before the next step | +|---|---|---|---|---| +| 1 Read | `open `, `src all` | `open new ` (only the node definitions) | same | the working folder is open | +| 2 Understanding | A to E of references/understanding.md | what was asked: what it makes, what the user puts in and gets out | same | understanding.md | +| 3 Split | yes | yes | same | the canvases | +| 4 Build | `copy` and `add`, then `diff` | `add` only | same | the wires are connected | +| 5–6 Arrange, look and fix | yes | yes | same | what the check names is fixed | +| 7 Notes | yes | yes | same | the Notes | +| 8 Export | the original's name with `_readable`, `diff` | a few English words for what it does | same | the exported workflows | +| 9 Review | yes | yes | skipped | the review registered | +| 10 Report page | with Original | without Original | skipped | report.html | +| 11 Report and finish | `finish` | `finish` | `finish fast` | the working folder is gone | 1. **Read the original (when there is an original)** `canvas open ` @@ -77,6 +88,7 @@ When the user asks for it fast, skip steps 9 and 10 (the review and the report p The understanding of the workflow, written before building. Write the first version after reading, and revise it while building. Keep what you revised as well. - Read references/content.md, references/techniques.md, and the "Content" and "Notes" parts of references/examples.md before writing (its "Layout" part comes in step 5). readable-form.md, notes.md and review.md are read in steps 5, 7 and 9, not now. - What to write is in references/understanding.md. For every node, write what it does with its values here. + - When building a new one, write only what was asked: what the workflow makes, what the user puts in and gets out. 3. **Split** Following the split in the understanding document, make one canvas per workflow (`canvas new `, `canvas use `). How they are named is in step 8. One canvas becomes one workflow JSON. @@ -123,13 +135,13 @@ When the user asks for it fast, skip steps 9 and 10 (the review and the report p - One Note at a time, check that the node on the 🔗 line and the topics are about the same node; a topic about another node moves to that node's Note. 8. **Export and compare** - For each canvas, `canvas export .json`. The name is the original's file name with `_readable` after it (`image_flux2_klein_text_to_image_readable.json`), so it stands beside the original without overwriting it; when the workflow was split, a few English words after that say what each one does (`…_readable_upscale.json`). (When there is an original) run `canvas diff` again on every canvas, take the differences one by one against the four items of step 4 and content.md, "What becomes of each part", fix what they say, and export again. + For each canvas, `canvas export .json`. The name is the original's file name with `_readable` after it (`image_flux2_klein_text_to_image_readable.json`), so it stands beside the original without overwriting it; when the workflow was split, a few English words after that say what each one does (`…_readable_upscale.json`). When there is no original, the name is a few English words for what it does (`flux_text_to_image.json`). (When there is an original) run `canvas diff` again on every canvas, take the differences one by one against the four items of step 4 and content.md, "What becomes of each part", fix what they say, and export again. 9. **Review (another agent)** Read references/review.md and follow it: draw the picture for each canvas (not for one that differs from another only in values), give the brief to a new agent, fix the rows one at a time, answer every row, export again and register the review with `canvas review`. 10. **Write the report page (`report.html`)** - Write the page where the user checks the result, as one HTML file. The page has three views. The canvas makes Original (the original workflow) and Rebuilt (what was done on the canvases, one move at a time). You write only the Walkthrough. + Write the page where the user checks the result, as one HTML file. The page has three views. The canvas makes Original (the original workflow; only when there is an original) and Rebuilt (what was done on the canvases, one move at a time). You write only the Walkthrough. - For each canvas, write `$W/walk_.md`, select the canvas with `canvas use `, and register it with `canvas walk $W/walk_.md` (the file's form is at the top of canvas.py). How to write it is in references/notes.md, "Walkthrough". - Set the order of the canvases on the page with `canvas order …`: the basic workflow on the left, then those that add to it (t2i before i2i and edit, the normal version before its fast version), parts last. Workflows of the same form that differ only in values (one per model) share one tab: write them next to each other as `/`. - Finally, write the page with `canvas report report.html ` (`ja`, `en`, `zh` and so on). diff --git a/skills/comfyui-readable-node/references/report.md b/skills/comfyui-readable-node/references/report.md index 489f674..66081a9 100644 --- a/skills/comfyui-readable-node/references/report.md +++ b/skills/comfyui-readable-node/references/report.md @@ -8,8 +8,8 @@ 2. The folder of the files, once. Under it, each file name as a bullet, with nested lines: - What the workflow makes, from what. From the second workflow on, with how it differs ("The same video, with Turbo LoRA in 4 steps."). - Only when split: how it differs from the others (a LoRA, the steps). - - For `report.html`: "Open it to compare with the original workflow and to read how the rebuilt workflow works." -3. **Changed from the original workflow**: each change that makes the result differ, one bullet each. Nested under it: the reason, when the change alone does not explain itself; what takes the place of something lost. Of what the references say to report, only these are said. + - For `report.html`: "Open it to compare with the original workflow and to read how the rebuilt workflow works." When there is no original: "Open it to read how the workflow works." +3. **Changed from the original workflow** (when there is an original): each change that makes the result differ, one bullet each. Nested under it: the reason, when the change alone does not explain itself; what takes the place of something lost. Of what the references say to report, only these are said. 4. **What else could be changed**, only when there is something: another build with core only (also when a Caution Note already says it); a step that makes in core an input the user would make elsewhere (a depth map from a photo with Depth Anything 3), not added. Write it as "there is also a form that …", not as what you can do ("I can …", "… can also be made"). 5. **Other**, only when there is something: a model whose download link was not found; a custom node not installed, whose values were matched from its source. diff --git a/skills/comfyui-readable-node/scripts/canvas.py b/skills/comfyui-readable-node/scripts/canvas.py index 7c46df8..dd2eb4d 100644 --- a/skills/comfyui-readable-node/scripts/canvas.py +++ b/skills/comfyui-readable-node/scripts/canvas.py @@ -14,6 +14,8 @@ with the core Compare Images (ImageCompare), returns value nodes into their targets or turns them into typed ones, and merges identical loaders. Removes Preview Image nodes that only show what was loaded. Reports everything it did. Discards positions, sizes, colors, titles and groups (the author's words are returned separately). + open new + A new workflow (no original): only the node definitions are read. src, copy and diff are not used. src outputs output nodes and the size of each one's upstream src list [part of type] list of source nodes src all inputs/outputs, values and mode of every source node at once (instead of many `src node`) @@ -355,7 +357,7 @@ def oi(self): if self._oi is None: p = self.dir / "object_info.json" if not p.exists(): - raise Stop("not opened yet (run open first)") + raise Stop("not opened yet (run open first; for a new workflow, open new )") self._oi = jload(p) return self._oi @@ -374,9 +376,16 @@ def consume(self, path): def src(self): p = self.dir / "src.flat.json" if not p.exists(): - raise Stop("not opened yet (run open first)") + raise Stop("not opened yet (run open first; for a new workflow, open new )") return jload(p) + def original(self): + """The source, for a move that reads an original: stops when the work was opened with `open new`.""" + flat = self.src() + if not self.cfg.get("source"): + raise Stop("no original (opened with `open new`): add nodes with `add `") + return flat + def canvas_path(self, name): return self.dir / "canvas" / f"{name}.json" @@ -3694,10 +3703,18 @@ def do_finish(work, args=()): if missing: raise Stop("not finished. Nothing is deleted:\n " + "\n ".join(missing)) root = os.path.abspath(work.dir) + real_root = os.path.realpath(root) def inside(p): + # the folder that holds the file, with every link followed, must be the working folder or inside it: + # a path spelled inside it can go out through a folder link (W/alias -> elsewhere). The file itself is not + # followed: a file link is deleted as a link, and its target stays + p = os.path.abspath(p) + if p == root: + return False try: - return os.path.commonpath([root, os.path.abspath(p)]) == root and os.path.abspath(p) != root + parent = os.path.realpath(os.path.dirname(p)) + return os.path.commonpath([real_root, parent]) == real_root except ValueError: # another drive (Windows): outside return False @@ -3727,7 +3744,9 @@ def inside(p): except OSError: pass if os.path.exists(root): - left = sorted(os.path.relpath(os.path.join(dp, f), root) for dp, _, fs in os.walk(root) for f in fs) + # a folder link is named too (os.walk lists it with the folders and does not go into it) + left = sorted(os.path.relpath(os.path.join(dp, f), root) for dp, ds, fs in os.walk(root) + for f in fs + [d for d in ds if os.path.islink(os.path.join(dp, d))]) if not left: return [f"deleted {len(files)} files. The working folder {root} is empty but could not be removed " f"(it is the current directory?): remove it from outside"] + note_outside @@ -3739,12 +3758,26 @@ def inside(p): def do_open(work, args): if len(args) < 2: - raise Stop("open ") + raise Stop("open , or for a new workflow (no original): " + "open new ") wf_path, oi_src = args[0], args[1] + if work.names(): + # one working folder is one job: the export, review and report records of the canvases here would be taken + # for the new job + raise Stop(f"this working folder already holds canvases ({', '.join(work.names())}): open the workflow in " + f"another working folder, named after what it builds (_work). Nothing changed") oi = CS.load_object_info(oi_src) work.dir.mkdir(parents=True, exist_ok=True) jdump(work.dir / "object_info.json", oi) work._oi = oi + if wf_path == "new": + # a new workflow: only the node definitions; the source is empty and no original is remembered + jdump(work.dir / "src.flat.json", FL.flatten(RW.load({"nodes": [], "links": []}), oi)) + work.cfg.pop("source", None) + work.cfg["object_info"] = oi_src + work.save_cfg() + return [f"no original: a new workflow, built with the node definitions of {oi_src} ({len(oi)} node types). " + f"Moves that read an original (src, copy, diff) are not used"] out = [] raw = jload(wf_path) if AF.is_api(raw): @@ -3973,7 +4006,7 @@ def src_node_lines(flat, oi, nid): def do_src(work, args): - flat, oi = work.src(), work.oi + flat, oi = work.original(), work.oi if not args: raise Stop("src ") sub = args[0] @@ -4871,8 +4904,7 @@ def _run_cmd(work, line): work.save_cfg() return [f"current canvas: {args[0]}"] if cmd == "diff": - if not work.cfg.get("source"): - raise Stop("not opened yet (run open first)") + work.original() src, _ = load_source(need_file(work.cfg["source"], "source workflow"), work.oi) outs = [] for name in work.names(): @@ -5014,7 +5046,7 @@ def change(cv, work, cmd, args): def _op_copy(cv, work, args): nodes = cv.nodes - src = work.src() + src = work.original() sn = {n["id"]: n for n in src["nodes"]} for sid in args: if sid not in sn: diff --git a/tests/test_finish.py b/tests/test_finish.py index 2883d90..7f37169 100644 --- a/tests/test_finish.py +++ b/tests/test_finish.py @@ -242,6 +242,48 @@ def test_unknown_files_and_the_folder_are_left(self): self.assertFalse((self.w / "src.flat.json").exists()) self.assertFalse((self.w / "canvas").exists()) + def outside_dir_with_sentinel(self): + outside = self.out / "outside_dir" + outside.mkdir() + sentinel = outside / "sentinel.md" + sentinel.write_text("# S\ntext", encoding="utf-8") + return outside, sentinel + + def test_a_note_through_a_folder_link_to_outside_is_kept(self): + outside, sentinel = self.outside_dir_with_sentinel() + (self.w / "alias").symlink_to(outside, target_is_directory=True) + self.do(f"note {self.w / 'alias' / 'sentinel.md'} below 12") + self.export_and_report() + out = self.do("finish") + self.assertTrue(sentinel.exists()) + self.assertEqual(sentinel.read_text(encoding="utf-8"), "# S\ntext") + self.assertTrue(any("outside the working folder" in x and "sentinel.md" in x for x in out), out) + # the link itself is left and named: the folder is not called empty + self.assertIn("alias", out[0]); self.assertNotIn("is empty", out[0]) + self.assertFalse((self.w / "src.flat.json").exists()) + + def test_a_canvas_folder_turned_into_a_link_to_outside_is_not_followed(self): + outside, sentinel = self.outside_dir_with_sentinel() + self.export_and_report() + shutil.copy(self.w / "canvas" / "t.json", outside / "t.json") + real = self.w / "canvas" + shutil.move(str(real), str(self.out / "canvas_moved")) + real.symlink_to(outside, target_is_directory=True) + os.environ["CANVAS_KEEP_WORK"] = "1" + listed = self.do("finish") + os.environ.pop("CANVAS_KEEP_WORK") + self.assertFalse(any(x.strip() == "canvas/t.json" for x in listed), listed) + self.assertTrue(any(x.strip() == "src.flat.json" for x in listed), listed) + + def test_a_file_link_inside_removes_only_the_link(self): + outside, sentinel = self.outside_dir_with_sentinel() + (self.w / "link.md").symlink_to(sentinel) + self.do(f"note {self.w / 'link.md'} below 12") + self.export_and_report() + self.do("finish") + self.assertTrue(sentinel.exists()) + self.assertFalse(self.w.exists()) + def test_keep_work_deletes_nothing(self): self.export_and_report() os.environ["CANVAS_KEEP_WORK"] = "1" diff --git a/tests/test_new_workflow.py b/tests/test_new_workflow.py new file mode 100644 index 0000000..9b650f8 --- /dev/null +++ b/tests/test_new_workflow.py @@ -0,0 +1,95 @@ +"""Tests for building a new workflow, with no original (`open new `). Python standard library only. + +What is checked: the steps SKILL.md gives for a new workflow run to the end (build, layout, export, models, review, +report, finish), and the moves that only work on an original say so instead of failing on a missing file. + +Usage: python3 -m unittest discover -s tests +""" +import shutil +import sys +import tempfile +import unittest +from pathlib import Path + +HERE = Path(__file__).resolve().parent +SCRIPTS = next(p for p in (HERE.parent / "skills" / "comfyui-readable-node" / "scripts", HERE.parent / "skill" / "scripts") + if p.is_dir()) +sys.path.insert(0, str(SCRIPTS)) +import canvas as C # noqa: E402 + +FIX = HERE / "fixtures" + + +class NewWorkflowTest(unittest.TestCase): + def setUp(self): + self.out = Path(tempfile.mkdtemp()) + self.w = self.out / "w" + + def tearDown(self): + shutil.rmtree(self.out) + + def do(self, line): + return C.run_cmd(C.Work(self.w), line) + + def build(self): + self.do(f"open new {FIX / 'object_info.json'}") + self.do("new t") + self.do("add UNETLoader unet") + self.do("add ModelSamplingFlux msf") + self.do("link unet.MODEL msf.model") + + def test_open_new_starts_without_an_original(self): + out = self.do(f"open new {FIX / 'object_info.json'}") + self.assertTrue(any("no original" in x for x in out), out) + self.assertEqual(self.do("new t"), ["made canvas t"]) + + def test_a_new_workflow_runs_to_finish(self): + self.build() + plan = self.w / "layout.txt" + plan.write_text("put unet origin\nput msf right unet wire\n", encoding="utf-8") + self.do(f"layout {plan}") + self.do(f"export {self.out / 't.json'}") + models = self.do("models") + self.assertTrue(any("draft of the model Note text" in x for x in models), models) + _, ids = C.Work(self.w).current().workflow() + review = self.w / "review_t.md" + review.write_text("# Review: t\n\n| rule | nodes | what to change | answer |\n|---|---|---|---|\n" + f"| Rails: a single value is wired directly | {min(ids.values())} | wire it directly | fixed |\n", + encoding="utf-8") + self.do(f"review {review}") + self.do(f"report {self.out / 'report.html'} en") + self.do("finish") + self.assertFalse(self.w.exists()) + self.assertTrue((self.out / "t.json").exists() and (self.out / "report.html").exists()) + + def test_moves_for_an_original_say_there_is_none(self): + self.build() + for line in ("copy 12", "src all", "diff"): + with self.assertRaises(C.Stop) as e: + self.do(line) + self.assertIn("no original", str(e.exception), line) + + def test_open_stops_in_a_working_folder_already_used(self): + # one working folder is one job: opening another workflow over canvases (and their export, review and report + # records) would let finish take the old records for the new job + self.build() + for line in (f"open new {FIX / 'object_info.json'}", f"open {FIX / 'flux_t2i.json'} {FIX / 'object_info.json'}"): + with self.assertRaises(C.Stop) as e: + self.do(line) + self.assertIn("another working folder", str(e.exception), line) + self.assertEqual(C.Work(self.w).names(), ["t"]) + + def test_open_again_before_any_canvas(self): + # nothing built yet: opening again (another object_info, the original after all) is fine + self.do(f"open new {FIX / 'object_info.json'}") + out = self.do(f"open {FIX / 'flux_t2i.json'} {FIX / 'object_info.json'}") + self.assertTrue(any(x.startswith("read:") for x in out), out) + + def test_open_still_needs_both_files_for_an_original(self): + with self.assertRaises(C.Stop) as e: + self.do(f"open {FIX / 'flux_t2i.json'}") + self.assertIn("open new", str(e.exception)) + + +if __name__ == "__main__": + unittest.main()