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).
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 e56187adf3.
Refs: decisions/D-widget-serialization-simplification.md, AXIOMS.md §A15+A16
Picks up the canvas-units / escape-hatch / A13 JSDoc on NodeHandle.{getPosition,setPosition,getSize,setSize} from foundation fa3229b402 so the published .d.ts and the docgen pipeline see the policy text. No symbol changes.
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.
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>
- 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>
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).
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
(5b05f2b793).
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).
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.
