comfy-preflight 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- comfy_preflight-1.0.0/LICENSE +21 -0
- comfy_preflight-1.0.0/PKG-INFO +225 -0
- comfy_preflight-1.0.0/README.md +179 -0
- comfy_preflight-1.0.0/pyproject.toml +57 -0
- comfy_preflight-1.0.0/setup.cfg +4 -0
- comfy_preflight-1.0.0/src/comfy_preflight/__init__.py +27 -0
- comfy_preflight-1.0.0/src/comfy_preflight/_assert_probe.py +47 -0
- comfy_preflight-1.0.0/src/comfy_preflight/aggregate.py +200 -0
- comfy_preflight-1.0.0/src/comfy_preflight/checks/__init__.py +45 -0
- comfy_preflight-1.0.0/src/comfy_preflight/checks/c1_link_topology.py +180 -0
- comfy_preflight-1.0.0/src/comfy_preflight/checks/c2_register.py +390 -0
- comfy_preflight-1.0.0/src/comfy_preflight/checks/c4_saved_is_submitted.py +186 -0
- comfy_preflight-1.0.0/src/comfy_preflight/checks/c5_frame.py +293 -0
- comfy_preflight-1.0.0/src/comfy_preflight/checks/c8_envelope.py +281 -0
- comfy_preflight-1.0.0/src/comfy_preflight/cli.py +360 -0
- comfy_preflight-1.0.0/src/comfy_preflight/envelope.py +377 -0
- comfy_preflight-1.0.0/src/comfy_preflight/errors.py +136 -0
- comfy_preflight-1.0.0/src/comfy_preflight/graph.py +179 -0
- comfy_preflight-1.0.0/src/comfy_preflight/mcp_server.py +195 -0
- comfy_preflight-1.0.0/src/comfy_preflight/register.py +184 -0
- comfy_preflight-1.0.0/src/comfy_preflight/registry.py +228 -0
- comfy_preflight-1.0.0/src/comfy_preflight.egg-info/PKG-INFO +225 -0
- comfy_preflight-1.0.0/src/comfy_preflight.egg-info/SOURCES.txt +38 -0
- comfy_preflight-1.0.0/src/comfy_preflight.egg-info/dependency_links.txt +1 -0
- comfy_preflight-1.0.0/src/comfy_preflight.egg-info/entry_points.txt +2 -0
- comfy_preflight-1.0.0/src/comfy_preflight.egg-info/requires.txt +7 -0
- comfy_preflight-1.0.0/src/comfy_preflight.egg-info/top_level.txt +1 -0
- comfy_preflight-1.0.0/tests/test_aggregate.py +441 -0
- comfy_preflight-1.0.0/tests/test_c1_link_topology.py +222 -0
- comfy_preflight-1.0.0/tests/test_c2_register.py +395 -0
- comfy_preflight-1.0.0/tests/test_c4_saved_is_submitted.py +234 -0
- comfy_preflight-1.0.0/tests/test_c5_frame.py +303 -0
- comfy_preflight-1.0.0/tests/test_c8_envelope.py +628 -0
- comfy_preflight-1.0.0/tests/test_cli.py +380 -0
- comfy_preflight-1.0.0/tests/test_errors.py +222 -0
- comfy_preflight-1.0.0/tests/test_fixtures_are_self_contained.py +165 -0
- comfy_preflight-1.0.0/tests/test_mcp_surface.py +251 -0
- comfy_preflight-1.0.0/tests/test_no_assert_in_library.py +125 -0
- comfy_preflight-1.0.0/tests/test_packaging.py +153 -0
- comfy_preflight-1.0.0/tests/test_registry.py +225 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 mcp-tool-shop
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: comfy-preflight
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A gate that runs on a ComfyUI workflow graph in the seconds before submission, and halts a submission that would spend credits producing a known-wrong result.
|
|
5
|
+
Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026 mcp-tool-shop
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://github.com/mcp-tool-shop-org/comfy-preflight
|
|
29
|
+
Project-URL: Issues, https://github.com/mcp-tool-shop-org/comfy-preflight/issues
|
|
30
|
+
Keywords: comfyui,workflow,preflight,validation,gate
|
|
31
|
+
Classifier: Development Status :: 4 - Beta
|
|
32
|
+
Classifier: Intended Audience :: Developers
|
|
33
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
34
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
35
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
36
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
37
|
+
Requires-Python: >=3.11
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
License-File: LICENSE
|
|
40
|
+
Provides-Extra: mcp
|
|
41
|
+
Requires-Dist: mcp>=2.0; extra == "mcp"
|
|
42
|
+
Provides-Extra: dev
|
|
43
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
44
|
+
Requires-Dist: mcp>=2.0; extra == "dev"
|
|
45
|
+
Dynamic: license-file
|
|
46
|
+
|
|
47
|
+
<p align="center">
|
|
48
|
+
<a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
|
|
49
|
+
</p>
|
|
50
|
+
|
|
51
|
+
<p align="center">
|
|
52
|
+
<img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/comfy-preflight/readme.png" alt="comfy-preflight" width="600">
|
|
53
|
+
</p>
|
|
54
|
+
|
|
55
|
+
<p align="center">
|
|
56
|
+
<a href="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
57
|
+
<a href="https://pypi.org/project/comfy-preflight/"><img src="https://img.shields.io/pypi/v/comfy-preflight?color=3775a9&label=pypi" alt="PyPI"></a>
|
|
58
|
+
<a href="https://www.npmjs.com/package/@mcptoolshop/comfy-preflight"><img src="https://img.shields.io/npm/v/@mcptoolshop/comfy-preflight?color=cb3837&label=npm" alt="npm"></a>
|
|
59
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
|
|
60
|
+
<a href="https://mcp-tool-shop-org.github.io/comfy-preflight/"><img src="https://img.shields.io/badge/landing%20page-live-2ea043" alt="Landing page"></a>
|
|
61
|
+
</p>
|
|
62
|
+
|
|
63
|
+
<p align="center">
|
|
64
|
+
<strong>A gate that runs on a ComfyUI workflow graph in the seconds before it is submitted,</strong><br>
|
|
65
|
+
and halts a submission that would spend credits producing a known-wrong result.<br>
|
|
66
|
+
It does not submit. It does not fix your graph.
|
|
67
|
+
</p>
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## The gap it lives in
|
|
72
|
+
|
|
73
|
+
> **A Comfy Cloud `dry_run` PASS does not prove link sanity.**
|
|
74
|
+
> A hand-retyped payload with a self-referencing node link — `VAEDecode.samples = ["14", 0]`,
|
|
75
|
+
> the node pointing at itself — returned `status: validated`.
|
|
76
|
+
|
|
77
|
+
The provider's validator answers *is this graph well-formed enough to run.* It does not answer
|
|
78
|
+
*is this the graph you meant.* Every check here lives in that gap, and each one was paid for by
|
|
79
|
+
a run that got past `dry_run`.
|
|
80
|
+
|
|
81
|
+
**Submission is the irreversible act with no real undo, and a preflight is a compensator you run
|
|
82
|
+
BEFORE instead of after.** A completed cloud job is billed; the only compensator afterwards is
|
|
83
|
+
*cancel it if it is still queued, otherwise none.* That is the whole argument for this package.
|
|
84
|
+
|
|
85
|
+
## Install
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npx @mcptoolshop/comfy-preflight check graph.json # no Python needed
|
|
89
|
+
pip install comfy-preflight # for the in-process gate
|
|
90
|
+
pip install "comfy-preflight[mcp]" # + the MCP stdio server
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The npx launcher downloads a binary from this repo's GitHub Release and **verifies its SHA256**
|
|
94
|
+
against the checksums in that same release before running it. Python ≥ 3.11; binaries for
|
|
95
|
+
linux-x64 and win-x64 (macOS installs via `pip`).
|
|
96
|
+
|
|
97
|
+
## Use it
|
|
98
|
+
|
|
99
|
+
**The production gate — in-process, on the submit path:**
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from comfy_preflight import preflight
|
|
103
|
+
|
|
104
|
+
# Inside the function that submits. Not in a shell step before it.
|
|
105
|
+
preflight(graph, register, input_dims=(width, height)) # raises PreflightHalt
|
|
106
|
+
submit(graph) # only reached if nothing raised
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**The development door:**
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
comfy-preflight check graph.json \
|
|
113
|
+
--input-dims 1072x1024 --register subject.json --saved sidecar.json --json
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
| exit | meaning |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `0` | nothing halted — PASS, ADVISORY or NOT_APPLICABLE, **each named in the output** |
|
|
119
|
+
| `1` | HALT |
|
|
120
|
+
| `2` | **nothing was examined** — bad arguments, unreadable file, or an internal error |
|
|
121
|
+
|
|
122
|
+
ADVISORY exits `0` on purpose: a nonzero status stops a `&&` chain, which would turn an advisory
|
|
123
|
+
into a halt in every shell that runs one.
|
|
124
|
+
|
|
125
|
+
## What it checks
|
|
126
|
+
|
|
127
|
+
| # | check | halts on |
|
|
128
|
+
|---|---|---|
|
|
129
|
+
| 1 | **Link topology** | a node input reading its own node; a link to a node id not in the graph |
|
|
130
|
+
| 2 | **The inverted register scan** | a declared register that does not match the graph's construction — **in both directions** |
|
|
131
|
+
| 4 | **Saved-is-submitted** | the saved sidecar and the submitted payload differing **as parsed graphs** |
|
|
132
|
+
| 5 | **Generator-legal frame** | a dimension the effective frame's VAE cannot decode at |
|
|
133
|
+
| 8 | **Declared envelope** | **nothing — it never halts.** Out-of-band is an ADVISORY |
|
|
134
|
+
|
|
135
|
+
Three checks from the original design are **not built**, and are named rather than quietly
|
|
136
|
+
missing: recipe-vs-profile agreement (no subject-profile fixture exists), estimate-before-submit
|
|
137
|
+
(transport-side — no graph-structural operand), and anchor reproduction (needs the graph
|
|
138
|
+
*builder*; the corpus holds outputs, not the scripts that made them).
|
|
139
|
+
|
|
140
|
+
### Check 2 — the one that names the method
|
|
141
|
+
|
|
142
|
+
When a subject's register declares **no style adapter**, the claim being asserted is *not* "the
|
|
143
|
+
weight is 0.0". It is that **no loader node and no adapter card reference exist anywhere in the
|
|
144
|
+
graph**.
|
|
145
|
+
|
|
146
|
+
> *A weight of 0.0 is not a weight of zero on a loaded card; it is no card.*
|
|
147
|
+
|
|
148
|
+
**And it asserts the mirror image.** A decided positive weight with **no loader node** is
|
|
149
|
+
*silently inert*: the run completes, costs money, and produces base-model output while every log
|
|
150
|
+
line says the adapter was requested. That direction produces no signal a human could notice —
|
|
151
|
+
which is exactly where a gate earns its place over a person looking.
|
|
152
|
+
|
|
153
|
+
### Check 5 — the effective frame, not the declared one
|
|
154
|
+
|
|
155
|
+
`1066 / 8 = 133.25` encodes to 133 latent columns and decodes to **1064**, putting every output
|
|
156
|
+
2 px off its control image and breaking every downstream pairing.
|
|
157
|
+
|
|
158
|
+
**The defect happened upstream of the graph.** The 1066 was derived correctly from a mesh, the
|
|
159
|
+
image was rendered at that width and uploaded, and the graph never declared it — so a check
|
|
160
|
+
reading graph literals could not have caught the incident that motivates it. The operand is the
|
|
161
|
+
frame the run will actually produce, which on an img2img graph is the input image's dimensions.
|
|
162
|
+
|
|
163
|
+
÷8 halts. ÷16 advises. A floor and a preference, not two floors.
|
|
164
|
+
|
|
165
|
+
### Check 8 — advisory, and honest about what it cannot say
|
|
166
|
+
|
|
167
|
+
For each checkpoint the graph loads, parameters are compared against a **cited** envelope table.
|
|
168
|
+
Every entry carries its band, source URL, retrieval date and a quote of the card's own words —
|
|
169
|
+
and the constructor refuses to build an entry that does not.
|
|
170
|
+
|
|
171
|
+
The day-one entry is `Qwen-Image-InstantX-ControlNet-Union`. It carries the
|
|
172
|
+
`controlnet_conditioning_scale` band its card documents, and a **declared absence** for denoise,
|
|
173
|
+
because that card publishes no denoise range at all — verified against the live card rather than
|
|
174
|
+
recalled. So a run on a graph at `denoise=0.92` reports the 0.92, names the parameter, and says
|
|
175
|
+
plainly that it cannot judge it and why.
|
|
176
|
+
|
|
177
|
+
Reporting the value it cannot judge is the honest half of the finding. Inventing a band to judge
|
|
178
|
+
it against would be the dishonest half.
|
|
179
|
+
|
|
180
|
+
## The adoption contract
|
|
181
|
+
|
|
182
|
+
**Call it in-process on the submit path. There is no skip flag.**
|
|
183
|
+
|
|
184
|
+
*The check lives inside the tool that performs the irreversible step.* A preflight in a shell
|
|
185
|
+
chain before a submit is a **transport, not a guard** — in the incident that produced this rule,
|
|
186
|
+
47,020 texels were committed after a gate had already fired, because a PowerShell chain walked
|
|
187
|
+
past a failing exit code. Nobody decided to proceed; the construction was incapable of stopping.
|
|
188
|
+
|
|
189
|
+
**The CLI and the MCP server are both transports, not gates.** Reading a HALT from either and
|
|
190
|
+
then submitting from somewhere else is that same chain with a nicer interface.
|
|
191
|
+
|
|
192
|
+
No function here takes a `skip`, `force`, `warn_only` or `enabled` parameter, and tests read each
|
|
193
|
+
signature rather than trusting the docs. **Every gate `raise`s; none is a bare `assert`** —
|
|
194
|
+
`python -O` deletes `assert` silently, and CI runs the whole suite under `-O` and
|
|
195
|
+
`PYTHONOPTIMIZE=1` to prove the gates survive it.
|
|
196
|
+
|
|
197
|
+
## Over MCP
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
python -m comfy_preflight.mcp_server # stdio
|
|
201
|
+
npx @mcptoolshop/comfy-preflight mcp # same server, no Python required
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
One tool, `preflight`, returning the same structured result the library returns — a test asserts
|
|
205
|
+
byte-identity. A HALT is a *successful* call returning `{"verdict": "halt", ...}`, because
|
|
206
|
+
reporting it as a protocol error would throw away the structure the caller needs.
|
|
207
|
+
|
|
208
|
+
## Security
|
|
209
|
+
|
|
210
|
+
No network calls, no credentials, no telemetry, and it writes nothing anywhere. It reads a graph
|
|
211
|
+
and a profile, and returns a verdict. Full threat model — data touched, data *not* touched, and
|
|
212
|
+
the permissions required — in [SECURITY.md](SECURITY.md).
|
|
213
|
+
|
|
214
|
+
## Documentation
|
|
215
|
+
|
|
216
|
+
📖 **[The handbook](https://mcp-tool-shop-org.github.io/comfy-preflight/handbook/)** — getting
|
|
217
|
+
started, every check in detail, the adoption contract, and the envelope table.
|
|
218
|
+
|
|
219
|
+
## License
|
|
220
|
+
|
|
221
|
+
MIT — see [LICENSE](LICENSE).
|
|
222
|
+
|
|
223
|
+
<p align="center">
|
|
224
|
+
Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
|
|
225
|
+
</p>
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/comfy-preflight/readme.png" alt="comfy-preflight" width="600">
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
+
<a href="https://pypi.org/project/comfy-preflight/"><img src="https://img.shields.io/pypi/v/comfy-preflight?color=3775a9&label=pypi" alt="PyPI"></a>
|
|
12
|
+
<a href="https://www.npmjs.com/package/@mcptoolshop/comfy-preflight"><img src="https://img.shields.io/npm/v/@mcptoolshop/comfy-preflight?color=cb3837&label=npm" alt="npm"></a>
|
|
13
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
|
|
14
|
+
<a href="https://mcp-tool-shop-org.github.io/comfy-preflight/"><img src="https://img.shields.io/badge/landing%20page-live-2ea043" alt="Landing page"></a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<strong>A gate that runs on a ComfyUI workflow graph in the seconds before it is submitted,</strong><br>
|
|
19
|
+
and halts a submission that would spend credits producing a known-wrong result.<br>
|
|
20
|
+
It does not submit. It does not fix your graph.
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## The gap it lives in
|
|
26
|
+
|
|
27
|
+
> **A Comfy Cloud `dry_run` PASS does not prove link sanity.**
|
|
28
|
+
> A hand-retyped payload with a self-referencing node link — `VAEDecode.samples = ["14", 0]`,
|
|
29
|
+
> the node pointing at itself — returned `status: validated`.
|
|
30
|
+
|
|
31
|
+
The provider's validator answers *is this graph well-formed enough to run.* It does not answer
|
|
32
|
+
*is this the graph you meant.* Every check here lives in that gap, and each one was paid for by
|
|
33
|
+
a run that got past `dry_run`.
|
|
34
|
+
|
|
35
|
+
**Submission is the irreversible act with no real undo, and a preflight is a compensator you run
|
|
36
|
+
BEFORE instead of after.** A completed cloud job is billed; the only compensator afterwards is
|
|
37
|
+
*cancel it if it is still queued, otherwise none.* That is the whole argument for this package.
|
|
38
|
+
|
|
39
|
+
## Install
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npx @mcptoolshop/comfy-preflight check graph.json # no Python needed
|
|
43
|
+
pip install comfy-preflight # for the in-process gate
|
|
44
|
+
pip install "comfy-preflight[mcp]" # + the MCP stdio server
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The npx launcher downloads a binary from this repo's GitHub Release and **verifies its SHA256**
|
|
48
|
+
against the checksums in that same release before running it. Python ≥ 3.11; binaries for
|
|
49
|
+
linux-x64 and win-x64 (macOS installs via `pip`).
|
|
50
|
+
|
|
51
|
+
## Use it
|
|
52
|
+
|
|
53
|
+
**The production gate — in-process, on the submit path:**
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
from comfy_preflight import preflight
|
|
57
|
+
|
|
58
|
+
# Inside the function that submits. Not in a shell step before it.
|
|
59
|
+
preflight(graph, register, input_dims=(width, height)) # raises PreflightHalt
|
|
60
|
+
submit(graph) # only reached if nothing raised
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**The development door:**
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
comfy-preflight check graph.json \
|
|
67
|
+
--input-dims 1072x1024 --register subject.json --saved sidecar.json --json
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
| exit | meaning |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `0` | nothing halted — PASS, ADVISORY or NOT_APPLICABLE, **each named in the output** |
|
|
73
|
+
| `1` | HALT |
|
|
74
|
+
| `2` | **nothing was examined** — bad arguments, unreadable file, or an internal error |
|
|
75
|
+
|
|
76
|
+
ADVISORY exits `0` on purpose: a nonzero status stops a `&&` chain, which would turn an advisory
|
|
77
|
+
into a halt in every shell that runs one.
|
|
78
|
+
|
|
79
|
+
## What it checks
|
|
80
|
+
|
|
81
|
+
| # | check | halts on |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| 1 | **Link topology** | a node input reading its own node; a link to a node id not in the graph |
|
|
84
|
+
| 2 | **The inverted register scan** | a declared register that does not match the graph's construction — **in both directions** |
|
|
85
|
+
| 4 | **Saved-is-submitted** | the saved sidecar and the submitted payload differing **as parsed graphs** |
|
|
86
|
+
| 5 | **Generator-legal frame** | a dimension the effective frame's VAE cannot decode at |
|
|
87
|
+
| 8 | **Declared envelope** | **nothing — it never halts.** Out-of-band is an ADVISORY |
|
|
88
|
+
|
|
89
|
+
Three checks from the original design are **not built**, and are named rather than quietly
|
|
90
|
+
missing: recipe-vs-profile agreement (no subject-profile fixture exists), estimate-before-submit
|
|
91
|
+
(transport-side — no graph-structural operand), and anchor reproduction (needs the graph
|
|
92
|
+
*builder*; the corpus holds outputs, not the scripts that made them).
|
|
93
|
+
|
|
94
|
+
### Check 2 — the one that names the method
|
|
95
|
+
|
|
96
|
+
When a subject's register declares **no style adapter**, the claim being asserted is *not* "the
|
|
97
|
+
weight is 0.0". It is that **no loader node and no adapter card reference exist anywhere in the
|
|
98
|
+
graph**.
|
|
99
|
+
|
|
100
|
+
> *A weight of 0.0 is not a weight of zero on a loaded card; it is no card.*
|
|
101
|
+
|
|
102
|
+
**And it asserts the mirror image.** A decided positive weight with **no loader node** is
|
|
103
|
+
*silently inert*: the run completes, costs money, and produces base-model output while every log
|
|
104
|
+
line says the adapter was requested. That direction produces no signal a human could notice —
|
|
105
|
+
which is exactly where a gate earns its place over a person looking.
|
|
106
|
+
|
|
107
|
+
### Check 5 — the effective frame, not the declared one
|
|
108
|
+
|
|
109
|
+
`1066 / 8 = 133.25` encodes to 133 latent columns and decodes to **1064**, putting every output
|
|
110
|
+
2 px off its control image and breaking every downstream pairing.
|
|
111
|
+
|
|
112
|
+
**The defect happened upstream of the graph.** The 1066 was derived correctly from a mesh, the
|
|
113
|
+
image was rendered at that width and uploaded, and the graph never declared it — so a check
|
|
114
|
+
reading graph literals could not have caught the incident that motivates it. The operand is the
|
|
115
|
+
frame the run will actually produce, which on an img2img graph is the input image's dimensions.
|
|
116
|
+
|
|
117
|
+
÷8 halts. ÷16 advises. A floor and a preference, not two floors.
|
|
118
|
+
|
|
119
|
+
### Check 8 — advisory, and honest about what it cannot say
|
|
120
|
+
|
|
121
|
+
For each checkpoint the graph loads, parameters are compared against a **cited** envelope table.
|
|
122
|
+
Every entry carries its band, source URL, retrieval date and a quote of the card's own words —
|
|
123
|
+
and the constructor refuses to build an entry that does not.
|
|
124
|
+
|
|
125
|
+
The day-one entry is `Qwen-Image-InstantX-ControlNet-Union`. It carries the
|
|
126
|
+
`controlnet_conditioning_scale` band its card documents, and a **declared absence** for denoise,
|
|
127
|
+
because that card publishes no denoise range at all — verified against the live card rather than
|
|
128
|
+
recalled. So a run on a graph at `denoise=0.92` reports the 0.92, names the parameter, and says
|
|
129
|
+
plainly that it cannot judge it and why.
|
|
130
|
+
|
|
131
|
+
Reporting the value it cannot judge is the honest half of the finding. Inventing a band to judge
|
|
132
|
+
it against would be the dishonest half.
|
|
133
|
+
|
|
134
|
+
## The adoption contract
|
|
135
|
+
|
|
136
|
+
**Call it in-process on the submit path. There is no skip flag.**
|
|
137
|
+
|
|
138
|
+
*The check lives inside the tool that performs the irreversible step.* A preflight in a shell
|
|
139
|
+
chain before a submit is a **transport, not a guard** — in the incident that produced this rule,
|
|
140
|
+
47,020 texels were committed after a gate had already fired, because a PowerShell chain walked
|
|
141
|
+
past a failing exit code. Nobody decided to proceed; the construction was incapable of stopping.
|
|
142
|
+
|
|
143
|
+
**The CLI and the MCP server are both transports, not gates.** Reading a HALT from either and
|
|
144
|
+
then submitting from somewhere else is that same chain with a nicer interface.
|
|
145
|
+
|
|
146
|
+
No function here takes a `skip`, `force`, `warn_only` or `enabled` parameter, and tests read each
|
|
147
|
+
signature rather than trusting the docs. **Every gate `raise`s; none is a bare `assert`** —
|
|
148
|
+
`python -O` deletes `assert` silently, and CI runs the whole suite under `-O` and
|
|
149
|
+
`PYTHONOPTIMIZE=1` to prove the gates survive it.
|
|
150
|
+
|
|
151
|
+
## Over MCP
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
python -m comfy_preflight.mcp_server # stdio
|
|
155
|
+
npx @mcptoolshop/comfy-preflight mcp # same server, no Python required
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
One tool, `preflight`, returning the same structured result the library returns — a test asserts
|
|
159
|
+
byte-identity. A HALT is a *successful* call returning `{"verdict": "halt", ...}`, because
|
|
160
|
+
reporting it as a protocol error would throw away the structure the caller needs.
|
|
161
|
+
|
|
162
|
+
## Security
|
|
163
|
+
|
|
164
|
+
No network calls, no credentials, no telemetry, and it writes nothing anywhere. It reads a graph
|
|
165
|
+
and a profile, and returns a verdict. Full threat model — data touched, data *not* touched, and
|
|
166
|
+
the permissions required — in [SECURITY.md](SECURITY.md).
|
|
167
|
+
|
|
168
|
+
## Documentation
|
|
169
|
+
|
|
170
|
+
📖 **[The handbook](https://mcp-tool-shop-org.github.io/comfy-preflight/handbook/)** — getting
|
|
171
|
+
started, every check in detail, the adoption contract, and the envelope table.
|
|
172
|
+
|
|
173
|
+
## License
|
|
174
|
+
|
|
175
|
+
MIT — see [LICENSE](LICENSE).
|
|
176
|
+
|
|
177
|
+
<p align="center">
|
|
178
|
+
Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
|
|
179
|
+
</p>
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "comfy-preflight"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "A gate that runs on a ComfyUI workflow graph in the seconds before submission, and halts a submission that would spend credits producing a known-wrong result."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { file = "LICENSE" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
authors = [{ name = "mcp-tool-shop", email = "64996768+mcp-tool-shop@users.noreply.github.com" }]
|
|
13
|
+
keywords = ["comfyui", "workflow", "preflight", "validation", "gate"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Topic :: Multimedia :: Graphics",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
# ZERO runtime dependencies, and this is load-bearing rather than tidy.
|
|
24
|
+
# The npm door (@mcptoolshop/npm-launcher -> a SHA256-pinned PyInstaller binary) is only
|
|
25
|
+
# open to packages whose dependencies are stdlib + sqlite3 + mcp. Adding a third-party
|
|
26
|
+
# runtime dep closes it. The checks operate on parsed JSON; nothing here needs numpy.
|
|
27
|
+
dependencies = []
|
|
28
|
+
|
|
29
|
+
[project.optional-dependencies]
|
|
30
|
+
# mcp>=2.0, not >=1.0: the server class the surface is built on is `mcp.server.MCPServer`,
|
|
31
|
+
# and 2.0 removed the 1.x `mcp.server.fastmcp.FastMCP`. The bound was verified against the
|
|
32
|
+
# installed SDK rather than recalled - a >=1.0 bound would resolve to a version that
|
|
33
|
+
# ImportErrors on first use, which is the same defect class as a console script pointing at an
|
|
34
|
+
# absent module.
|
|
35
|
+
mcp = ["mcp>=2.0"]
|
|
36
|
+
dev = ["pytest>=8.0", "mcp>=2.0"]
|
|
37
|
+
|
|
38
|
+
# The console script, restored now that the CLI it names exists. The scaffold declared this
|
|
39
|
+
# entry before any CLI module did, which installs a command that raises ImportError on first
|
|
40
|
+
# use — a defect that surfaces for the person who installs the package, not for the person who
|
|
41
|
+
# wrote the entry. tests/test_packaging.py imports every declared target and fails if one does
|
|
42
|
+
# not resolve, so the entry can never again outrun the module.
|
|
43
|
+
[project.scripts]
|
|
44
|
+
comfy-preflight = "comfy_preflight.cli:main"
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
Homepage = "https://github.com/mcp-tool-shop-org/comfy-preflight"
|
|
48
|
+
Issues = "https://github.com/mcp-tool-shop-org/comfy-preflight/issues"
|
|
49
|
+
|
|
50
|
+
[tool.setuptools.packages.find]
|
|
51
|
+
where = ["src"]
|
|
52
|
+
|
|
53
|
+
[tool.pytest.ini_options]
|
|
54
|
+
testpaths = ["tests"]
|
|
55
|
+
# -O / PYTHONOPTIMIZE strips `assert`. This project's gates `raise`; the test suite is
|
|
56
|
+
# also run under -O in CI to prove the gates survive it. See tests/test_gates_survive_O.py
|
|
57
|
+
addopts = "-q"
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""comfy-preflight — a gate on a ComfyUI workflow graph, run before submission.
|
|
2
|
+
|
|
3
|
+
Submitting a graph is the one irreversible act in a generation pipeline: a completed cloud
|
|
4
|
+
job is billed, and the only compensator is "cancel it if it is still queued, otherwise
|
|
5
|
+
none." This package is a compensator you run *before* instead of after.
|
|
6
|
+
|
|
7
|
+
It does not submit, does not repair a graph, and never sees an output.
|
|
8
|
+
|
|
9
|
+
`preflight()` is the function the adoption contract names: call it **in-process on the submit
|
|
10
|
+
path**, and let it raise. See the README's build-state table for which checks it composes; that
|
|
11
|
+
table is the honest state of this repo.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
__version__ = "1.0.0"
|
|
15
|
+
|
|
16
|
+
from comfy_preflight.aggregate import PreflightResult, preflight
|
|
17
|
+
from comfy_preflight.errors import Defect, PreflightHalt, Verdict, merge_verdicts
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"__version__",
|
|
21
|
+
"preflight",
|
|
22
|
+
"PreflightResult",
|
|
23
|
+
"Defect",
|
|
24
|
+
"PreflightHalt",
|
|
25
|
+
"Verdict",
|
|
26
|
+
"merge_verdicts",
|
|
27
|
+
]
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""A probe that measures whether a bare `assert` gates LIBRARY code in this interpreter.
|
|
2
|
+
|
|
3
|
+
Why this module exists, and why it is in `src/` rather than in `tests/`:
|
|
4
|
+
|
|
5
|
+
**pytest rewrites `assert` statements in test modules.** Its import hook transforms them into
|
|
6
|
+
explicit code that raises `AssertionError`, so a bare `assert False` written in a test file
|
|
7
|
+
still fires under `python -O` — not because the interpreter kept it, but because pytest
|
|
8
|
+
replaced it before the interpreter saw it. pytest says so itself when run under -O:
|
|
9
|
+
|
|
10
|
+
PytestConfigWarning: assertions not in test modules or plugins will be ignored because
|
|
11
|
+
assert statements are not executed by the underlying Python interpreter
|
|
12
|
+
|
|
13
|
+
Library code is **not** rewritten. So an assert in `comfy_preflight/*.py` really is deleted
|
|
14
|
+
under `-O`, while an assert in `tests/*.py` is not. A test that probes assert-stripping with
|
|
15
|
+
its own assert therefore measures a proxy — pytest's rewriting — instead of the property, and
|
|
16
|
+
reports the opposite of the truth. That mistake was made once here and caught by the -O CI
|
|
17
|
+
leg failing.
|
|
18
|
+
|
|
19
|
+
This module is the honest instrument: it lives where the gates live, so it is subject to the
|
|
20
|
+
same treatment they are.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def bare_assert_fires() -> bool:
|
|
27
|
+
"""True if a bare `assert` raises in library code under the running interpreter.
|
|
28
|
+
|
|
29
|
+
Returns False when assertions are stripped (`python -O`, `PYTHONOPTIMIZE`), which is
|
|
30
|
+
exactly the condition under which a gate written as an `assert` would silently vanish and
|
|
31
|
+
let execution continue past it.
|
|
32
|
+
"""
|
|
33
|
+
try:
|
|
34
|
+
assert False # noqa: B011 - deliberately bare; this is the measurement
|
|
35
|
+
return False
|
|
36
|
+
except AssertionError:
|
|
37
|
+
return True
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def asserts_are_stripped() -> bool:
|
|
41
|
+
"""True when this interpreter is discarding assertions.
|
|
42
|
+
|
|
43
|
+
Read from the interpreter rather than inferred, so it can be cross-checked against
|
|
44
|
+
`bare_assert_fires()`. If the two ever disagree, something is rewriting library code and
|
|
45
|
+
the gates' guarantee needs re-examining.
|
|
46
|
+
"""
|
|
47
|
+
return not __debug__
|