Skip to content

[ext-api 2/4] pkg: @comfyorg/extension-api npm package - #12143

Closed
christian-byrne wants to merge 18 commits into
ext-api/i-foundation-v2from
ext-api/i-pkg-v2
Closed

christian-byrne wants to merge 18 commits into
ext-api/i-foundation-v2from
ext-api/i-pkg-v2

Conversation

@christian-byrne

@christian-byrne christian-byrne commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Publishable npm package for the Extension API v2. Generates .d.ts type declarations and documentation for extension authors.

Stacked on #12142.

What's Included

Package (packages/extension-api/)

  • package.json — @comfyorg/extension-api package config
  • vite.config.mts — builds .d.ts + .js bundle via vite-plugin-dts
  • tsconfig.build.json — TypeScript config for declaration emit
  • typedoc.json + scripts/build-docs.ts — API documentation generator

CI Workflows (.github/workflows/)

  • extension-api-typecheck.yml — validates types on PR
  • extension-api-publish.yml — publishes to npm on release
  • ci-tests-extension-api.yaml — runs extension-api specific tests

Build Output

build/extension-api/
├── index.d.ts      # main entry
├── node.d.ts       # NodeHandle types
├── widget.d.ts     # WidgetHandle types
├── lifecycle.d.ts  # onNodeMounted, onNodeRemoved
├── types.d.ts      # ExtensionOptions, NodeExtensionOptions
├── events.d.ts     # Handler, Unsubscribe
├── shell.d.ts      # SidebarTabExtension, CommandManager
└── identifiers.d.ts # NodeLocatorId, NodeExecutionId

Test Plan

  • pnpm typecheck passes
  • pnpm --filter @comfyorg/extension-api build generates declarations

@coderabbitai

coderabbitai Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

Next included review available in 31 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: cb7cfa73-6009-47ca-8570-550374c98fc3

📥 Commits

Reviewing files that changed from the base of the PR and between 24d893d and 528d014.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (22)
  • .github/workflows/ci-tests-extension-api.yaml
  • .github/workflows/extension-api-publish.yml
  • .github/workflows/extension-api-typecheck.yml
  • .oxfmtrc.json
  • eslint.config.ts
  • knip.config.ts
  • lint-staged.config.ts
  • packages/extension-api/.gitignore
  • packages/extension-api/.npmignore
  • packages/extension-api/README.md
  • packages/extension-api/build/.gitignore
  • packages/extension-api/build/index.d.ts
  • packages/extension-api/package.json
  • packages/extension-api/scripts/build-docs.ts
  • packages/extension-api/src/index.ts
  • packages/extension-api/tsconfig.build.json
  • packages/extension-api/tsconfig.docs.json
  • packages/extension-api/tsconfig.json
  • packages/extension-api/typedoc.json
  • packages/extension-api/vite.config.mts
  • scripts/generate-docs.sh
  • src/types/extensionV2.ts
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch ext-api/i-pkg-v2

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

🌐 Website E2E

Tip

All tests passed.

Status ✅ Passed
Report View Report

@github-actions

github-actions Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 05/21/2026, 09:03:20 PM UTC

Links

@github-actions

github-actions Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

🎭 Playwright: 🕵🏻 0 passed, 0 failed

📊 Browser Reports
  • chromium: ❌ Deployment failed
  • chromium-2x: ❌ Deployment failed
  • chromium-0.5x: ❌ Deployment failed
  • mobile-chrome: ❌ Deployment failed

@socket-security

socket-security Bot commented May 11, 2026 •

Copy link
Copy Markdown

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

@codecov

codecov Bot commented May 11, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@                     Coverage Diff                     @@
##           ext-api/i-foundation-v2   #12143      +/-   ##
===========================================================
- Coverage                    59.49%   58.69%   -0.81%     
===========================================================
  Files                         1423     1418       -5     
  Lines                        72910    72358     -552     
  Branches                     20210    20038     -172     
===========================================================
- Hits                         43381    42470     -911     
- Misses                       29056    29413     +357     
- Partials                       473      475       +2     
Flag Coverage Δ
unit 58.69% <ø> (-0.81%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 113 files with indirect coverage changes

🚀 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 commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle Size

⏳ Size data collection in progress…

⚡ Performance

⚠️ Performance tests failed. Check the CI workflow logs.

christian-byrne pushed a commit that referenced this pull request May 12, 2026
…ODO (review #12143.A6)

The widget name returned by createWidgetHandle (used by addWidget()) parses
the trailing segment of the entity id ("widget:graphId:nodeId:name") via
lastIndexOf(':') and an 'as unknown as string' cast. Make the temporary
nature of this parse explicit (TODO #11939, real WidgetNameComponent), and
document the missing-colon fallback (returns the full id rather than an
empty string) as the defensive default.
christian-byrne pushed a commit that referenced this pull request May 12, 2026
…port (review #12143.M1+A9)

The package barrel at packages/extension-api/src/index.ts duplicated the
canonical surface in src/extension-api/index.ts. Two hand-maintained
exports lists drift out of sync — Architect #4's removal of
startExtensionSystem from the public surface, for example, only landed in
the canonical barrel.

Collapse the package barrel to a single 'export * from
@/extension-api/index' re-export so the canonical file is the one source of
truth. Future surface additions/removals flow through automatically; no
risk of asymmetric export sets between the in-tree consumer
(@/extension-api) and the npm package consumer
(@comfyorg/extension-api).
christian-byrne pushed a commit that referenced this pull request May 12, 2026
knip flagged the new src/extension-api/* files and exports as unused
because nothing internal consumes them — by design. They are the public
API surface published by PKG2 (#12143).

Changes:
- knip.config.ts: add src/extension-api/index.ts as entry point (per
  AGENTS.md, this barrel is the explicit exception to the
  no-barrel-files-in-src rule because it IS the package entry).
- knip.config.ts: ignore src/types/extensionV2.ts (deprecated stub,
  removed once PKG2 ships).
- knip.config.ts: register `-publicAPI` tag.
- Tag externally-consumed exports with @publicapi:
  - lifecycle.ts: defineNodeExtension/Extension/WidgetExtension declares
    + back-compat type re-exports
  - extension-api-service.ts: _setDispatchImplForTesting, NodeInstanceScope
  - worldInstance.ts: World

Verifies the full lint-format CI matrix locally:
  pnpm lint        ✅
  pnpm stylelint   (unaffected, CSS-only)
  pnpm format:check ✅
  pnpm knip        ✅
christian-byrne pushed a commit that referenced this pull request May 12, 2026
…ODO (review #12143.A6)

The widget name returned by createWidgetHandle (used by addWidget()) parses
the trailing segment of the entity id ("widget:graphId:nodeId:name") via
lastIndexOf(':') and an 'as unknown as string' cast. Make the temporary
nature of this parse explicit (TODO #11939, real WidgetNameComponent), and
document the missing-colon fallback (returns the full id rather than an
empty string) as the defensive default.
christian-byrne pushed a commit that referenced this pull request May 12, 2026
…port (review #12143.M1+A9)

The package barrel at packages/extension-api/src/index.ts duplicated the
canonical surface in src/extension-api/index.ts. Two hand-maintained
exports lists drift out of sync — Architect #4's removal of
startExtensionSystem from the public surface, for example, only landed in
the canonical barrel.

Collapse the package barrel to a single 'export * from
@/extension-api/index' re-export so the canonical file is the one source of
truth. Future surface additions/removals flow through automatically; no
risk of asymmetric export sets between the in-tree consumer
(@/extension-api) and the npm package consumer
(@comfyorg/extension-api).
christian-byrne pushed a commit that referenced this pull request May 12, 2026
…port (review #12143.M1+A9)

The package barrel at packages/extension-api/src/index.ts duplicated the
canonical surface in src/extension-api/index.ts. Two hand-maintained
exports lists drift out of sync — Architect #4's removal of
startExtensionSystem from the public surface, for example, only landed in
the canonical barrel.

Collapse the package barrel to a single 'export * from
@/extension-api/index' re-export so the canonical file is the one source of
truth. Future surface additions/removals flow through automatically; no
risk of asymmetric export sets between the in-tree consumer
(@/extension-api) and the npm package consumer
(@comfyorg/extension-api).
christian-byrne pushed a commit that referenced this pull request May 12, 2026
oxlint flags console.log in packages/extension-api/scripts/build-docs.ts
(intentional CLI progress output). The pre-commit lint-staged hook in
ci-lint-format then aborts before the [automated] format commit can be
pushed back, blocking the entire lint-and-format job.

- Add file-level eslint-disable for no-console (CLI build script)
- Whitelist build-docs.ts in eslint.config.ts allowDefaultProject so
  typed-lint does not error on the file outside the tsconfig project graph

Discovered while rebasing #12143 onto the foundation-v2 knip fix
(5b05f2b).
christian-byrne pushed a commit that referenced this pull request May 12, 2026
Resolves CodeRabbit findings F-12143-1, F-12143-3, F-12143-7.

Per D17-pkg2-build-strategy ADR: package now builds via Vite library
mode + vite-plugin-dts, dropping the inconsistent rootDir restriction
and the --emitDeclarationOnly flag. Vite resolves @/* aliases against
the canonical surface in main app src/extension-api/, externalizes vue
as a peer dep, and bundles to a single 3.95 kB build/index.js.
vite-plugin-dts emits the per-file .d.ts closure under build/ with
@/* imports rewritten to relative paths.

The original tsc-only plan in #12143 was unworkable because tsc does
not rewrite path aliases — emitted JS would have unresolvable @/...
imports at runtime. Vite library mode is the smallest deviation that
satisfies PKG3 acceptance ('emits BOTH .d.ts + .js') while preserving
'the barrel is the source of truth in main app src/extension-api/'
intent in packages/extension-api/AGENTS.md.

Verified:
  pnpm build emits build/index.js (3.95 kB) + build/.../*.d.ts tree
  node -e "import('./build/index.js')" returns real functions for
    defineNodeExtension, defineExtension, onNodeMounted, onNodeRemoved
  synthetic downstream consumer importing NodeHandle/WidgetHandle
    types and runtime fns type-checks under tsc --noEmit
  pnpm lint && pnpm format:check && pnpm knip pass

Also adds packages/extension-api/vite.config.mts to the eslint
allowDefaultProject list so the typed lint rules can resolve it.

See decisions/D17-pkg2-build-strategy.md in the cross-repo workspace
for the full options analysis (A: types-only — rejected; B: vendor
sources — deferred to post-#11939; C: build from main app sources —
chosen).
christian-byrne pushed a commit that referenced this pull request May 12, 2026
Resolves CodeRabbit findings F-12143-1, F-12143-3, F-12143-7.

Per D17-pkg2-build-strategy ADR: package now builds via Vite library
mode + vite-plugin-dts, dropping the inconsistent rootDir restriction
and the --emitDeclarationOnly flag. Vite resolves @/* aliases against
the canonical surface in main app src/extension-api/, externalizes vue
as a peer dep, and bundles to a single 3.95 kB build/index.js.
vite-plugin-dts emits the per-file .d.ts closure under build/ with
@/* imports rewritten to relative paths.

The original tsc-only plan in #12143 was unworkable because tsc does
not rewrite path aliases — emitted JS would have unresolvable @/...
imports at runtime. Vite library mode is the smallest deviation that
satisfies PKG3 acceptance ('emits BOTH .d.ts + .js') while preserving
'the barrel is the source of truth in main app src/extension-api/'
intent in packages/extension-api/AGENTS.md.

Verified:
  pnpm build emits build/index.js (3.95 kB) + build/.../*.d.ts tree
  node -e "import('./build/index.js')" returns real functions for
    defineNodeExtension, defineExtension, onNodeMounted, onNodeRemoved
  synthetic downstream consumer importing NodeHandle/WidgetHandle
    types and runtime fns type-checks under tsc --noEmit
  pnpm lint && pnpm format:check && pnpm knip pass

Also adds packages/extension-api/vite.config.mts to the eslint
allowDefaultProject list so the typed lint rules can resolve it.

See decisions/D17-pkg2-build-strategy.md in the cross-repo workspace
for the full options analysis (A: types-only — rejected; B: vendor
sources — deferred to post-#11939; C: build from main app sources —
chosen).
christian-byrne pushed a commit that referenced this pull request May 13, 2026
Folds the foundation-file edits that were previously living in PRs #12143
and #12144 into the foundation PR (#12142) so each downstream PR's diff
contains only its own concerns.

From #12143 (pkg):
  - src/extension-api/index.ts: drop startExtensionSystem from public barrel
    (it is the internal boot fn; app.ts imports directly from the service)
  - src/extension-api/types.ts: fix bad escape in widgetCreated JSDoc example
  - src/services/extension-api-service.ts: add @internal tag to
    startExtensionSystem; widen widget.on() Phase-A stub warnings; harden
    addWidget name parse with explanatory TODO
  - src/services/__tests__/scope-registry.test.ts: drop unused removedCb in
    no-dispose-on-subgraph-promotion test

From #12144 (ext):
  - src/extension-api/lifecycle.ts: add JSDoc @example to defineWidgetExtension
  - src/extension-api/node.ts: hoist DOMWidgetOptions interface above NodeHandle
  - src/extension-api/shell.ts: clarify shell.ts is a re-export, not a move
  - src/services/extension-api-service.ts: more informative Phase-A stub
    warning text on node.on() (replaces pkg's terser version per ext review)

These are pure refinements (JSDoc, dev-only warnings, structural tidying);
no runtime behavior change. After this commit, rebasing pkg/ext onto the
new foundation will drop the corresponding source-touching commits as
empty no-ops and leave each PR scoped to its own concerns.
christian-byrne pushed a commit that referenced this pull request May 13, 2026
…port (review #12143.M1+A9)

The package barrel at packages/extension-api/src/index.ts duplicated the
canonical surface in src/extension-api/index.ts. Two hand-maintained
exports lists drift out of sync — Architect #4's removal of
startExtensionSystem from the public surface, for example, only landed in
the canonical barrel.

Collapse the package barrel to a single 'export * from
@/extension-api/index' re-export so the canonical file is the one source of
truth. Future surface additions/removals flow through automatically; no
risk of asymmetric export sets between the in-tree consumer
(@/extension-api) and the npm package consumer
(@comfyorg/extension-api).
christian-byrne pushed a commit that referenced this pull request May 13, 2026
oxlint flags console.log in packages/extension-api/scripts/build-docs.ts
(intentional CLI progress output). The pre-commit lint-staged hook in
ci-lint-format then aborts before the [automated] format commit can be
pushed back, blocking the entire lint-and-format job.

- Add file-level eslint-disable for no-console (CLI build script)
- Whitelist build-docs.ts in eslint.config.ts allowDefaultProject so
  typed-lint does not error on the file outside the tsconfig project graph

Discovered while rebasing #12143 onto the foundation-v2 knip fix
(5b05f2b).
christian-byrne pushed a commit that referenced this pull request May 13, 2026
Resolves CodeRabbit findings F-12143-1, F-12143-3, F-12143-7.

Per D17-pkg2-build-strategy ADR: package now builds via Vite library
mode + vite-plugin-dts, dropping the inconsistent rootDir restriction
and the --emitDeclarationOnly flag. Vite resolves @/* aliases against
the canonical surface in main app src/extension-api/, externalizes vue
as a peer dep, and bundles to a single 3.95 kB build/index.js.
vite-plugin-dts emits the per-file .d.ts closure under build/ with
@/* imports rewritten to relative paths.

The original tsc-only plan in #12143 was unworkable because tsc does
not rewrite path aliases — emitted JS would have unresolvable @/...
imports at runtime. Vite library mode is the smallest deviation that
satisfies PKG3 acceptance ('emits BOTH .d.ts + .js') while preserving
'the barrel is the source of truth in main app src/extension-api/'
intent in packages/extension-api/AGENTS.md.

Verified:
  pnpm build emits build/index.js (3.95 kB) + build/.../*.d.ts tree
  node -e "import('./build/index.js')" returns real functions for
    defineNodeExtension, defineExtension, onNodeMounted, onNodeRemoved
  synthetic downstream consumer importing NodeHandle/WidgetHandle
    types and runtime fns type-checks under tsc --noEmit
  pnpm lint && pnpm format:check && pnpm knip pass

Also adds packages/extension-api/vite.config.mts to the eslint
allowDefaultProject list so the typed lint rules can resolve it.

See decisions/D17-pkg2-build-strategy.md in the cross-repo workspace
for the full options analysis (A: types-only — rejected; B: vendor
sources — deferred to post-#11939; C: build from main app sources —
chosen).
christian-byrne pushed a commit that referenced this pull request May 13, 2026
…port (review #12143.M1+A9)

The package barrel at packages/extension-api/src/index.ts duplicated the
canonical surface in src/extension-api/index.ts. Two hand-maintained
exports lists drift out of sync — Architect #4's removal of
startExtensionSystem from the public surface, for example, only landed in
the canonical barrel.

Collapse the package barrel to a single 'export * from
@/extension-api/index' re-export so the canonical file is the one source of
truth. Future surface additions/removals flow through automatically; no
risk of asymmetric export sets between the in-tree consumer
(@/extension-api) and the npm package consumer
(@comfyorg/extension-api).
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Wave-9 cascade — pkg .d.ts rebuild for D-widget-serialization-simplification

Foundation e56187adf3 → pkg 166953175c (clean 15-step rebase; 7 wave-8 cleanups skipped as "previously applied").

Hand-patched packages/extension-api/build/index.d.ts (Node 20 vs vite blocks pnpm build per AGENTS.md Rule 8). Surface diff vs foundation:

  • WidgetHandle.isSerializeEnabled / setSerializeEnabled — removed
  • WidgetBeforeSerializeEvent.context 4-way discriminator — removed
  • WidgetBeforeSerializeEvent.skip() — removed
  • WidgetHandle.on('propertyChange', handler) overload — removed
  • WidgetPropertyChangeEvent interface + JSDoc — removed entirely
  • WidgetOptions.serialize?: boolean key — removed
  • JSDoc on WidgetBeforeSerializeEvent / options / serializeValue — updated to reference A16; transport-discriminator examples stripped

NodeBeforeSerializeEvent.context intentionally retained — node-level surface stays @deprecated + runtime-warned per ADR-0010 (not banned by this ADR per user direction 2026-05-20).

Verified: grep -nE '(set|is)SerializeEnabled|WidgetPropertyChangeEvent|skip\(\)|context.*workflow.*subgraph' returns only the node-level NodeBeforeSerializeEvent.context (line 115).

Restratify mirror at drift = 0 (166953175c).

@christian-byrne

Copy link
Copy Markdown
Contributor Author

🧊 Phase A surface frozen — foundation ee0537fdb5 (wave-11)

The public API surface for this stack is now locked at foundation commit ee0537fdb5 per D-api-surface-finalization. All four PRs in the stack (#12142 / #12143 / #12144 / #12145) will be rebased onto the ECS branch (PR #11939) before merge — codecov, e2e, perf, and Playwright failures on this stack are intentionally divergent from current main and not a merge blocker until that rebase point.

What's frozen

  • 7 shell-UI defineX entry points (sidebar / bottom panel / command / hotkey / setting / about-badge / toolbar) + toast / notify inline carve-out
  • defineNode / defineWidget with reduced surfaces (NodeHandle.getWidget(s) removed per A1 bilateral; WidgetHandle.setSerializeEnabled removed per A16; runtime addWidget banned per A15)
  • Event surface: widget.on('valueChange' | 'beforeSerialize'), node.on(...) lifecycle
  • Bootstrap: defineExtension + setup / mount hooks

Re-open criteria

Either (1) a new ACCEPTED ADR with axiom-compliance verification, or (2) Phase B trigger (#11939 merges).

Next up — Phase B

Kickoff tracking: #12394.
First Phase B work: defineWidgetAugmenter (PROPOSED ADR D-define-widget-augmenter — unblocks dynamicPrompts.v2 stub + Pattern 3 cross-node sync).

Live frozen-surface dashboard

https://comfyui-frontend-ecosystem.vercel.app (marker commit cf0cf88 on the ecosystem repo surfaces this checkpoint in the Vercel deploy log).

Connor Byrne and others added 18 commits May 21, 2026 14:01
Restratified i-pkg. Adds the @comfyorg/extension-api npm package
(packages/extension-api/) — package.json, tsconfig.{json,build,docs},
typedoc.json, scripts/build-docs.ts, README, .npmignore — plus three
CI workflows (extension-api-typecheck.yml, extension-api-publish.yml,
ci-tests-extension-api.yaml) and the docgen helper script.

Modifies foundation's src/extension-api/index.ts and
src/services/extension-api-service.ts with the package-aware tweaks
required for npm consumption.

Lockfile regenerated to include packages/extension-api workspace deps.

Original (pre-restratify) branch tip backed up at
refs/backup/restratify-20260511/ext-api-i-pkg.
…port (review #12143.M1+A9)

The package barrel at packages/extension-api/src/index.ts duplicated the
canonical surface in src/extension-api/index.ts. Two hand-maintained
exports lists drift out of sync — Architect #4's removal of
startExtensionSystem from the public surface, for example, only landed in
the canonical barrel.

Collapse the package barrel to a single 'export * from
@/extension-api/index' re-export so the canonical file is the one source of
truth. Future surface additions/removals flow through automatically; no
risk of asymmetric export sets between the in-tree consumer
(@/extension-api) and the npm package consumer
(@comfyorg/extension-api).
oxlint flags console.log in packages/extension-api/scripts/build-docs.ts
(intentional CLI progress output). The pre-commit lint-staged hook in
ci-lint-format then aborts before the [automated] format commit can be
pushed back, blocking the entire lint-and-format job.

- Add file-level eslint-disable for no-console (CLI build script)
- Whitelist build-docs.ts in eslint.config.ts allowDefaultProject so
  typed-lint does not error on the file outside the tsconfig project graph

Discovered while rebasing #12143 onto the foundation-v2 knip fix
(5b05f2b).
…review F-12143-8/9/10)

The dry_run input was declared as type: boolean but the default was the
string 'true' and the conditional comparisons used '== "true"' / '== "false"'.
GitHub Actions coerces typed boolean inputs to actual booleans, so the
string comparisons would never match a workflow_dispatch invocation.

- default: 'true' → default: true (match declared type)
- inputs.dry_run == 'false' → !inputs.dry_run
- inputs.dry_run == 'true' → inputs.dry_run

Validated locally with actionlint (clean).

Refs CodeRabbit findings F-12143-8, F-12143-9, F-12143-10 in
research/reviews/coderabbit-batch-2026-05-12.md.
Resolves CodeRabbit findings F-12143-1, F-12143-3, F-12143-7.

Per D17-pkg2-build-strategy ADR: package now builds via Vite library
mode + vite-plugin-dts, dropping the inconsistent rootDir restriction
and the --emitDeclarationOnly flag. Vite resolves @/* aliases against
the canonical surface in main app src/extension-api/, externalizes vue
as a peer dep, and bundles to a single 3.95 kB build/index.js.
vite-plugin-dts emits the per-file .d.ts closure under build/ with
@/* imports rewritten to relative paths.

The original tsc-only plan in #12143 was unworkable because tsc does
not rewrite path aliases — emitted JS would have unresolvable @/...
imports at runtime. Vite library mode is the smallest deviation that
satisfies PKG3 acceptance ('emits BOTH .d.ts + .js') while preserving
'the barrel is the source of truth in main app src/extension-api/'
intent in packages/extension-api/AGENTS.md.

Verified:
  pnpm build emits build/index.js (3.95 kB) + build/.../*.d.ts tree
  node -e "import('./build/index.js')" returns real functions for
    defineNodeExtension, defineExtension, onNodeMounted, onNodeRemoved
  synthetic downstream consumer importing NodeHandle/WidgetHandle
    types and runtime fns type-checks under tsc --noEmit
  pnpm lint && pnpm format:check && pnpm knip pass

Also adds packages/extension-api/vite.config.mts to the eslint
allowDefaultProject list so the typed lint rules can resolve it.

See decisions/D17-pkg2-build-strategy.md in the cross-repo workspace
for the full options analysis (A: types-only — rejected; B: vendor
sources — deferred to post-#11939; C: build from main app sources —
chosen).
- Remove build/ from .gitignore so types are visible in PR
- Update vite config to use rollupTypes for bundled declarations
- Update package.json types path to ./build/index.d.ts
- Exclude packages/*/build/ from lint-staged
- Include index.d.ts (37KB bundled types), index.js (2MB), index.js.map

The bundled index.d.ts contains all public API types inline.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove index.js and index.js.map from git tracking. The .d.ts file is
committed for npm package visibility and reviewer inspection, while JS
files are generated at build time and don't need to be in version control.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updates bundled types after foundation renamed widgets() → getWidgets().

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update workflow actions to versions allowed in .pinact.yaml:
- actions/setup-node@v4 → v6
- actions/github-script@v7 → v8

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The packages/extension-api/build/ directory contains TypeDoc/tsc-generated
.d.ts snapshots committed for reviewability (per D17). These should not
be format-checked since they're machine-generated.

Adds packages/extension-api/build/** to oxfmt ignorePatterns so that
'pnpm format:check' passes cleanly post-restratify reconciliation.

Part of RECONCILE-PKG (PR #12143).
…drop *EntityId from extensionV2 stub

Cascade of D20 (decisions/D20-id-type-convergence.md) from foundation:

- Rebuild packages/extension-api/build/index.d.ts via vite build so the
  published .d.ts ships the new id/equals surface and drops the three
  demoted brand re-exports.
- src/types/extensionV2.ts: stop re-exporting NodeEntityId, WidgetEntityId,
  SlotEntityId — they are no longer in the @/extension-api barrel per D20.
  Use node.id/widget.id (string) and equals(other) for the public surface.
…P8.C) + D-widget-converge (W6.P3.C) cascade

Regenerates packages/extension-api/build/index.d.ts to ship the merged
foundation surface from the two cherry-picked commits:
  - df921f3 / a22682b — Hybrid C Readonly typing per
    D-immutability-enforcement (8 mutation-family accessors now readonly,
    getInputs/getOutputs renamed, widget.options + widget.serializeValue
    accessor-only).
  - 2f10235 / d76592e — DOMWidget ↔ Widget convergence via mount
    lifecycle per D-widget-converge / Axiom A12. New WidgetCleanup /
    WidgetMountContext / WidgetMountFn exports; DOMWidgetOptions and
    NodeHandle.addDOMWidget() removed.

Verification:
  $ grep -c 'WidgetMountContext\|WidgetCleanup\|WidgetMountFn' build/index.d.ts
  8
  $ grep -c 'DOMWidgetOptions\|addDOMWidget' build/index.d.ts
  0

+222/-53 lines net (build/index.d.ts).
…ascade

Picks up the canvas-units / escape-hatch / A13 JSDoc on NodeHandle.{getPosition,setPosition,getSize,setSize} from foundation fa3229b so the published .d.ts and the docgen pipeline see the policy text. No symbol changes.
…cation (wave-9)

Hand-patched packages/extension-api/build/index.d.ts to match the
foundation surface after A16 closure:

- Drop `isSerializeEnabled` / `setSerializeEnabled` from WidgetHandle
- Drop `WidgetBeforeSerializeEvent.context` 4-way discriminator
- Drop `WidgetBeforeSerializeEvent.skip()`
- Drop `on('propertyChange', handler)` overload
- Drop entire `WidgetPropertyChangeEvent` interface
- Drop `WidgetOptions.serialize?: boolean` key
- Update JSDoc on `WidgetBeforeSerializeEvent` / `options` / `serializeValue`
  to reference A16 / drop transport-discriminator examples

`NodeBeforeSerializeEvent.context` is intentionally retained — the
node-level surface stays `@deprecated` + runtime-warned per ADR-0010
(not banned by D-widget-serialization-simplification).

Hand-edit pattern because pnpm build is blocked by Node 20 vs vite
requirement per AGENTS.md Rule 8. Surface verified to match foundation
HEAD e56187a.

Refs: decisions/D-widget-serialization-simplification.md, AXIOMS.md §A15+A16
…ave-10)

Hand-patched mirror of foundation surface changes per AGENTS.md Rule 8
(Node 20 vs vite blocks `pnpm build` in this worktree):

- Remove `NodeHandle.addWidget(...)` method declaration (A15 closure)
- Scrub 5 JSDoc references to `node.addWidget(...)` across NodeHandle
  getWidgets doc, NodeBeforeSerialize migration example, defineWidget
  options doc, WidgetHandle name doc, WidgetHandle label doc,
  WidgetOptions doc
- Add A15 / D-ban-runtime-addwidget cross-references

Mirrors foundation commit `d5d5692928`.
Hand-patched mirror of foundation hygiene cleanup per AGENTS.md Rule 8
(Node 20 vs vite blocks `pnpm build` in this worktree):

- Strip HR-style section dividers
- Strip parenthetical decision archaeology
  ((per D5), (D-immutability-enforcement, Hybrid C),
  D-bootstrap-hooks (W6.P6.C), D-shell-ui-entrypoints (W6.P5.C), etc.)
  from per-export JSDoc — preserve AXIOMS.md §A1/A14/A15/A16/A12 refs
  and PHASE_A_EXCLUDED axiom blocks (functional content).
- Strip "W6.P8.UNMIGRATABLE / D-input-output-shape" todo refs.
- One stale `defineWidgetExtension` JSDoc example fixed (was already
  on foundation; rebase carried the fix through).

Mirrors foundation commit `ee0537fdb5`.

ADR: decisions/D-design-review-hygiene-cleanup.md
Zero published-surface change (no types added/removed/renamed).
@artokun

artokun commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Drive-by from a downstream consumer (comfyui-mcp) tracking this PR — flagging two concrete items I'd want sorted before the first extension-api-v* tag, both unrelated to the in-flight foundation review:

1. peerDependencies uses the pnpm catalog: protocol, but the publish step is npm publish — not pnpm publish — so the resolved version won't be substituted in the published manifest.

In packages/extension-api/package.json:

"peerDependencies": {
  "vue": "catalog:"
}

And in .github/workflows/extension-api-publish.yml:

cd packages/extension-api
npm publish --provenance --access public

npm doesn't understand pnpm's catalog protocol; it'll publish the manifest verbatim with "catalog:" as the peer-dep range. Anyone who consumes @comfyorg/extension-api via npm or yarn will hit EUNSUPPORTEDPROTOCOL (or a silently broken peer-dep resolution). I tested this on a pnpm 10 / npm 11 host to confirm the install error shape.

Two easy fixes:

  • Switch the publish step to pnpm publish --filter @comfyorg/extension-api ..., which resolves catalog: to the concrete pinned version at pack time. (Cleanest.)
  • Or, add a publishConfig.peerDependencies override (or a pre-publish script that rewrites the manifest in-place) so the published artifact has a concrete range like ^3.5.0 regardless of which tool publishes.

2. packages/extension-api/package.json is missing license, repository, homepage, bugs.

These are non-load-bearing today but become annoying once published — npm shows "Unknown license" on the package page, GitHub doesn't show the license badge, and downstream tooling (Renovate, Dependabot, SCA scanners) starts to nag. Concretely:

"license": "<the license you intend — see below>",
"repository": {
  "type": "git",
  "url": "https://github.com/Comfy-Org/ComfyUI_frontend.git",
  "directory": "packages/extension-api"
},
"homepage": "https://docs.comfy.org/extension-api",  // or similar
"bugs": "https://github.com/Comfy-Org/ComfyUI_frontend/issues"

Worth being explicit about license here — the parent repo is GPL-3.0, but extension-API consumers generally need a permissive license to integrate. If the intent is to publish this scoped subpackage under a different license than the parent, declaring it here (and adding a LICENSE file alongside README.md in the files array) closes a real ambiguity for everyone downstream. Happy to defer if this is on a separate track.

Thanks for the careful work on the stack — looking forward to consuming this.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Retarget to main attempted and reverted — this PR is the second layer of a four-deep stack ([ext-api 2/4]) and cannot be retargeted to main until the foundation layer merges.

Stack: main ← #12142 [ext-api 1/4] (ext-api/i-foundation-v2, 44 commits, 25 unresolved review threads) ← this PR [ext-api 2/4] (ext-api/i-pkg-v2, 18 commits, 23 files) ← #12144 ext-api/i-ext-v2 ← #12145 ext-api/i-tf-v2.

What I did: retargeted base ext-api/i-foundation-v2 → main via REST PATCH /pulls/12143. Result: mergeable: false, mergeable_state: dirty, diff grew 23 → 70 files (62 commits ahead of main, 1411 behind). The 18 pkg-specific commits depend on the foundation's 44 commits (e.g. packages/extension-api/ scaffolding from #12142), so they cannot stand alone on main without the foundation layer.

Reverted base back to ext-api/i-foundation-v2 — PR restored to mergeable: true, mergeable_state: unstable, 23 changed files, head 528d014e15 unchanged.

Unblock: merge #12142 first, then retarget this PR to main (it will rebase cleanly since the foundation commits will be in main). No force-push to the head branch was performed.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor
⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@DrJKL DrJKL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The package cannot build or ship from this head. The library entry traverses application modules and raw Vue SFCs without the Vue plugin, the advertised test job exits successfully after skipping its missing configuration, and the published export map names a JavaScript file absent from the packed artifact.

I fully reviewed the package boundary, export/build/typecheck/doc configs, and workflows against its stacked base, and sampled the generated declaration and API imports. Current main contains no packages/extension-api or src/extension-api; this package must also be reconciled with the dedicated-store and widget compatibility direction now recorded in ADRs 0008, 0016, and 0023.

Checks: install and changed-file format passed. pnpm --filter @comfyorg/extension-api build failed after reaching 46 .vue files; pnpm test:extension-api exited 0 with SKIP: vitest.extension-api.config.mts not found; typecheck failed with 16 extension-API errors; changed-file ESLint failed on the package entry; Knip failed on an inherited unused export. npm pack --dry-run contained build/index.d.ts but no build/index.js.

I concur with the existing downstream comment about publishing catalog: through npm and the missing package metadata; those findings are not duplicated inline.

// package's own `src/index.ts` exists only as a documented entry
// point that re-exports the same surface, but we point Vite at the
// canonical file so dts paths line up cleanly with the JS bundle.
entry: resolve(surfaceRoot, 'index.ts'),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This entry imports the app-owned API tree rather than a package-owned leaf boundary. pnpm --filter @comfyorg/extension-api build follows that tree into 46 raw .vue files and fails because this library config has no Vue plugin. More importantly, the public package is coupled to application registrations. Give the package a buildable leaf entry that depends only on the intended public contract.

"exports": {
".": {
"types": "./build/index.d.ts",
"import": "./build/index.js",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The packed artifact has no build/index.js; npm pack --dry-run includes only the declaration, README, and manifest. This runtime export is therefore broken even before publication. The build must produce and pack the file named here.

uses: ./.github/actions/setup-frontend

- name: Run extension-api test suite
run: pnpm test:extension-api

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This job is green without running a test. On this head, pnpm test:extension-api prints SKIP: vitest.extension-api.config.mts not found and exits 0 because neither the config nor the stated test directory exists in this stack layer. A required test command must fail when its suite is absent.

*
* @packageDocumentation
*/
export * from '@/extension-api/index'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Changed-file ESLint rejects this entry because it is outside the configured TypeScript project service. Include the package source in the lint/typecheck project instead of shipping an entry point the repository checks cannot analyze.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Superseded by benjcooley's #16691 ("feat(nodeApi): publish the custom-node API"), which republishes the node/widget/graph API surface this stack targeted (src/platform/nodeApi/{nodeHandle,widgetHandle,graphHandle,slotHandle}.ts) under the current architecture. Per Christian's rulings on bbc #237 and bbc #290, closing.

Full context for agent readers

This PR is part of the [ext-api] stack (packages/extension-api/ npm package publishing), stacked on #12142. #16691 is the currently-active, open direction for the same problem — publishing a node/custom-node API surface — under src/platform/nodeApi/ rather than a separate npm package. #16691 has not yet merged, but Christian's ruling names it as the superseding direction, so this branch is closed rather than carried forward.

Author verified: christian-byrne. #12142 (the foundation PR this stacks on) is left open per the ruling; only #12143/#12145/#11251 are closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants