Skip to content

docs(api-types): make the refresh steps runnable and describe the real consumer - #23041

Merged
christian-byrne merged 1 commit into
mainfrom
cbyrne/api-types-readme-pnpm-exec
Nov 5, 2026
Merged

christian-byrne merged 1 commit into
mainfrom
cbyrne/api-types-readme-pnpm-exec

Conversation

@christian-byrne

Copy link
Copy Markdown
Contributor

Follow-up to #22426 and #22013, both merged. Documentation only — no code, no spec, no generated output.

Why

Two problems with packages/comfyui-api-types/README.md.

The refresh steps were not runnable. The copy-pasteable block ended with bare oxfmt --write src/generated. That resolves inside the check:generated script, where pnpm puts node_modules/.bin on PATH, but not in the shell someone pastes it into:

$ cd packages/comfyui-api-types && command -v oxfmt
(not found)

Reported by @dante01yoon on #22426; the thread was still open when that PR merged.

The scope section described a state that no longer exists. It said nothing imported the package and that QueuePromptRequestBody was still hand-written. #22013 made both false.

What changed

  • pnpm exec oxfmt --write src/generated, verified to run from the package directory in a clean environment (env -i with only node on PATH).
  • The scope section now describes the two members that derive from PromptWorkflowMetadata, and why they use different operators: the request narrows the map by key, the frame takes the map's value type, because core echoes the map's contents onto the frame rather than the map itself.
  • Records why tsconfig.types.json bundles this package — the frame types are re-exported from @comfyorg/comfyui-frontend-types and this package is private, so without the bundle entry the published declarations carry an import no external consumer can resolve and check:types-consumer fails. That is easy to remove by accident.

Verification Evidence

$ env -i … bash -lc 'cd packages/comfyui-api-types && command -v oxfmt'
NOT ON PATH            # the reported bug, reproduced
$ env -i … bash -lc 'cd packages/comfyui-api-types && pnpm exec oxfmt --write src/generated'
WORKS                  # the replacement

$ pnpm --filter @comfyorg/comfyui-api-types check:generated   # 0 — pin untouched
$ npx oxfmt --check packages/comfyui-api-types/README.md      # clean

The pnpm typecheck:workspaces claim already in the file was also checked rather than assumed: the script exists and runs in ci-lint-format.yaml and ci-lint-format-queue.yaml.

The pin is unchanged at 8f0da854…, so no regeneration is involved.

…l consumer

Two corrections to this README, one reported and one made stale by #22013.

The copy-pasteable refresh block ended with bare `oxfmt --write src/generated`.
That resolves inside the `check:generated` script, where pnpm puts
`node_modules/.bin` on PATH, but not in the shell a human pastes it into:

    $ cd packages/comfyui-api-types && command -v oxfmt
    (not found)

Now `pnpm exec oxfmt --write src/generated`, verified to run from that
directory in a clean environment.

The scope section still said nothing imported the package and that
`QueuePromptRequestBody` was hand-written, which stopped being true when #22013
merged. It now describes the two members that derive from
`PromptWorkflowMetadata` and why they use different operators — the request
narrows the map by key, the frame takes the map's value type, because core
echoes the map's contents onto the frame rather than the map itself.

Also records why `tsconfig.types.json` bundles this package: the frame types are
re-exported from `@comfyorg/comfyui-frontend-types` and this package is private,
so without the bundle entry the published declarations carry an unresolvable
import and `check:types-consumer` fails. That is easy to undo by accident.
@christian-byrne
christian-byrne requested a review from a team November 5, 2026 17:46
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 11/05/2026, 05:48:44 PM UTC

Links

🧩 Custom Nodes Ecosystem Matrix: 🟡 Withheld — could not measure

No verdict is available. Open the workflow run to confirm the check was intentionally skipped, or fix the collection failure and re-run it.

Findings and check details

Executes the frontend JS of every registry pack that ships any, against this change, in both renderers. The eight ecosystem-matrix shard checks are a harness self-test; the pack verdict is matrix-verdict.

The matrix runs on same-repository version-bump PRs with relevant changes, main-branch pushes, and manual dispatches. This candidate does not qualify, so every expensive stage was skipped.

Full docs: scripts/registry-census/README.md

Reproduce locally
# build one shard's fixture, then run it
python3 scripts/registry-census/build_matrix.py --shard 1/4
MATRIX_RENDERER=vue MATRIX_VUE=1 \
  npx vitest run --config vitest.matrix.config.mts

🌾 Fallow: ✅ Passed

Findings and check details

Fallow audits the diff for duplication, complexity and dead code. It gates on new findings only, so when the audit completes, a red is something this PR introduced or moved — never inherited backlog. A red can also mean the audit itself did not finish; the details below say which happened.

No new findings in the changed files.

Full docs: ADR-DEVEX-LINT-0015

Reproduce locally
# the base the gate compared against
npx fallow audit --root . --quiet --format json \
  --changed-since df6dfd8f146df453738bb13bdcd3c061130353b5

🏛️ Architecture: ✅ Passed

Findings and check details

Warnings (368)

  • billing path matches no source files: src/platform/billing/composables/activateBillingScope.testUtils.ts. Remove or update it in docs/architecture/domains/records/billing.domain.json.
  • error-handling path matches no source files: src/utils/errorUtil.ts. Remove or update it in docs/architecture/domains/records/error-handling.domain.json.
  • graph-model path matches no source files: src/types/linkTopology.ts. Remove or update it in docs/architecture/domains/records/graph-model.domain.json.
  • graph-model path matches no source files: src/types/nodeState.ts. Remove or update it in docs/architecture/domains/records/graph-model.domain.json.
  • job-queue path matches no source files: src/platform/remote/comfyui/jobs/**. Remove or update it in docs/architecture/domains/records/job-queue.domain.json.
  • linear-mode path matches no source files: src/utils/appMode.ts. Remove or update it in docs/architecture/domains/records/linear-mode.domain.json.
  • link-connection path matches no source files: src/lib/litegraph/src/infrastructure/LinkConnectorEventMap.ts. Remove or update it in docs/architecture/domains/records/link-connection.domain.json.
  • node-widgets path matches no source files: src/types/widgetState.ts. Remove or update it in docs/architecture/domains/records/node-widgets.domain.json.
  • subgraphs path matches no source files: src/lib/litegraph/src/infrastructure/SubgraphEventMap.ts. Remove or update it in docs/architecture/domains/records/subgraphs.domain.json.
  • vue-node-widgets path matches no source files: src/types/positionConfig.ts. Remove or update it in docs/architecture/domains/records/vue-node-widgets.domain.json.
  • workspace path matches no source files: src/platform/workspace/fixtures/**. Remove or update it in docs/architecture/domains/records/workspace.domain.json.
  • packages/api-client/src/abortSignal.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/abortSignal.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/fetchRouteTemplate.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/fetchWithRetry.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/fetchWithRetry.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/retryPolicy.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/retryPolicy.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/statusRetryTelemetry.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/api-client/src/statusRetryTelemetry.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/comfyui-api-types/src/generated/index.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/comfyui-api-types/src/generated/types.gen.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/comfyui-api-types/src/index.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/formatUtil.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/formatUtil.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/geometry.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/loadExternalScript.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/networkUtil.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/telemetry.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/telemetry.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/urlSafety.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/shared-frontend-utils/src/urlSafety.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • packages/tailwind-utils/src/index.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/TopbarActions.vue is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/searchbox/v2/filterChip.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/VideoConcatClipStrip.vue is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/VideoConcatClipTile.vue is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/VideoConcatPanel.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/VideoConcatPanel.vue is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/VideoConcatPlaybackBar.vue is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/WidgetVideoConcat.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/WidgetVideoConcat.vue is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/videoConcat/__fixtures__/clipTiles.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/widgetHistory/WidgetHistoryButtons.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/components/widgetHistory/WidgetHistoryButtons.vue is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/composables/graph/menuOption.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/composables/useAgentExtensionActions.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/composables/useAgentExtensionActions.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/composables/useAgentExtensionNotices.test.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • src/composables/useAgentExtensionNotices.ts is not claimed by any domain. Add it to a module in docs/architecture/domains/records.
  • …and 318 more

Full docs: Frontend domain catalog

Reproduce locally
pnpm architecture:check

@coderabbitai

coderabbitai Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The README now documents packages/api-client as a consumer, describes workflow types derived from PromptWorkflowMetadata, explains declaration bundling for external consumers, and runs the formatter through pnpm exec.

Changes: API types documentation

Layer / File(s) Summary
Document package usage and refresh
packages/comfyui-api-types/README.md
The Scope section identifies packages/api-client as a consumer and describes the derived workflow types and bundled declarations. The refresh command now invokes oxfmt through pnpm exec.

Estimated code review effort: 1 (Trivial) | ~4 minutes

Change: Other

Possibly related issues

Possibly related PRs

Suggested labels: size:S

Suggested reviewers: drjkl

Merge Risk: Minimal · up to 2d1d4

The README updates package guidance and the formatter command. No merge-blocking issue is identified.

Pre-merge checks: Passed 6

Check name Status Explanation
Title check Passed The title clearly identifies the documentation change: it makes the API types refresh steps runnable and updates the description of the real consumer.
Description check Passed The description explains the problem, changes, design rationale, risks, and verification results. It does not use the template headings exactly, but it provides equivalent Summary and Verification con…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
End-To-End Test Suggestion For User-Facing Changes Passed The pull request changes only packages/comfyui-api-types/README.md. The diff documents refresh commands and package scope; it does not change frontend behavior, a feature, or a user-visible trigger.…
Adr Compliance For Entity/Litegraph Changes Passed The changed file is packages/comfyui-api-types/README.md. No changed file is under src/lib/litegraph/, src/ecs/, or a graph-entity-related path. The ADR compliance check does not apply.
Full details: Description check

Explanation

The description explains the problem, changes, design rationale, risks, and verification results. It does not use the template headings exactly, but it provides equivalent Summary and Verification content and is sufficiently complete.

Full details: End-To-End Test Suggestion For User-Facing Changes

Explanation

The pull request changes only packages/comfyui-api-types/README.md. The diff documents refresh commands and package scope; it does not change frontend behavior, a feature, or a user-visible trigger. This check is therefore inapplicable, and no Playwright spec is required.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between df6dfd8 and 2d1d4d3.

Files selected for processing: 1

  • packages/comfyui-api-types/README.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

@codecov

codecov Bot commented Nov 5, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main   #23041   +/-   ##
=======================================
  Coverage   87.62%   87.62%           
=======================================
  Files        3049     3049           
  Lines      163734   163734           
  Branches    41721    41721           
=======================================
  Hits       143471   143471           
  Misses      19372    19372           
  Partials      891      891           
Flag Coverage Δ
billing-web-unit 92.19% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions github-actions Bot added the risk:high PR risk grade (advisory shadow check; grader-owned) label Nov 5, 2026

@dante01yoon dante01yoon left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the README against the package dependency, generated workflow metadata consumers, declaration bundle configuration, and CI scripts. The pnpm exec refresh command and updated consumer description match the repository. No blocking findings. No tests run, as requested.

@christian-byrne
christian-byrne added this pull request to the merge queue Nov 5, 2026
Merged via the queue into main with commit f8fec15 Nov 5, 2026
82 checks passed
@christian-byrne
christian-byrne deleted the cbyrne/api-types-readme-pnpm-exec branch November 5, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:high PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants