flowstate-plugin-node Package Skill

Package: @epicdm/flowstate-plugin-node Repository: epic-flowstate-community Path: packages/flowstate-plugin-node Version: 1.1.6

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Plugin Node Dev Manifest Watcher

Purpose

Use this skill when working with DevManifestWatcher, the Node runtime that keeps a plugin registry synchronized with dev-manifest JSON files.

Read First

• packages/flowstate-plugin-node/src/DevManifestWatcher.ts
• packages/flowstate-plugin-node/tests/DevManifestWatcher.test.ts
• packages/flowstate-app-framework/src/plugins/DevManifest.ts
• packages/flowstate-app-framework/src/plugins/contracts.ts
• scripts/smoke/plugin-dev-hot-reload.ts

Watcher Lifecycle

1. Construct with watchDir, registry, and optional fetchImpl, polling, health, logger, and signal options.
2. start() creates watchDir recursively.
3. Chokidar watches top-level .json files with ignoreInitial: false.
4. Initial add loads are captured and awaited after ready, removing the startup race window.
5. change reloads and re-registers the manifest.
6. unlink unregisters the manifest.
7. A health timer polls dev app URLs.
8. stop() closes the watcher, clears health timer, removes SIGINT handler, and clears internal maps.

Registry Contract

The supplied registry must support:

• registerDevManifest(manifest)
• unregisterDevManifest(id)
• markStale(id)
• markHealthy(id)

Manifest Rules

• Only .json files are considered.
• JSON parse failures warn and skip.
• DevManifestSchema.safeParse failures warn and skip.
• Non-http URLs are rejected by schema validation.
• If a file's manifest id changes, unregister the old id before registering the new one.
• If filename and manifest id differ, unlink uses the tracked manifest id rather than the filename.

Health Rules

• Connector manifests are registered but excluded from health polling.
• App plugin dev URLs are checked with HEAD.
• Failures increment a per-plugin counter.
• staleAfterFailures marks the plugin stale once.
• A later successful HEAD resets failures and calls markHealthy when recovering from stale.
• isPolling prevents overlapping poll cycles.
• The timer is unref'ed when possible.

Polling Fallback

Use usePolling: true and pollingInterval for Docker, network drives, or environments where native file watching is unreliable.

Common Mistakes

• Do not register invalid manifests just because JSON parses.
• Do not trust the filename as the plugin id after registration.
• Do not let health polling continue after stop().
• Do not install signal handlers in tests unless the behavior is under test.

Verification

yarn workspace @epicdm/flowstate-plugin-node test --runInBand tests/DevManifestWatcher.test.ts

Package Skill Inventory

@epicdm/flowstate-plugin-node Skill Inventory

Skill Set

Design Notes

The feature inventory lists five features, but useful agent skills should be workflow-based. isNewerVersion and pickLatestVersion are included in the update-check workflow rather than taught as standalone product features.

Not Included

• No generated function-by-function skilllets.
• No instructions to import Node-only runtime classes from flowstate-app-framework.
• No Dojo publish step until generated Dojo content is rebuilt from these reviewed skills.

Review Gate

@epicdm/flowstate-plugin-node Skills Review

Verdict

Pass with tracked follow-ups.

The authored skills are source-backed and workflow-oriented. They cover Node-only plugin operations, dev manifest watching, plugin source loading, update checks, framework boundary, and maintenance drift.

Coverage

• Dev manifest watcher: covered from src/DevManifestWatcher.ts and tests.
• Plugin loader: covered from src/PluginLoader.ts and tests.
• Update checks: covered from src/UpdateCheckService.ts and tests.
• Framework boundary: covered from framework plugin type files and plugin-node source imports.
• Generated content drift: covered from README, feature inventory, and Dojo artifacts.

Verification Results

LC_ALL=C rg -n "[^\\x00-\\x7F]" packages/flowstate-plugin-node/.flowstate/skills
rg -n "^name:|^description:" packages/flowstate-plugin-node/.flowstate/skills
yarn workspace @epicdm/flowstate-plugin-node test
yarn workspace @epicdm/flowstate-plugin-node typecheck
yarn workspace @epicdm/flowstate-plugin-node build
yarn nx build @epicdm/flowstate-plugin-node

Results:

• ASCII scan passed with no non-ASCII matches.
• Frontmatter scan found name and description on all six skills.
• typecheck passed.
• build passed and emitted CJS, ESM, sourcemaps, and DTS outputs.
• test passed: 3 suites, 58 tests. Expected console warnings came from invalid manifest/invalid JSON test cases.
• yarn nx build @epicdm/flowstate-plugin-node passed and built/cached 11 dependency tasks plus plugin-node. Nx Cloud reported the existing unconnected-workspace 401 warning.
• There is no package lint script.

Follow-Ups

• Replace README placeholder usage and include UpdateCheckService.
• Rebuild package-local Dojo content from these reviewed workflow skills.
• Consider changing the smoke script source deep import to the package barrel when build/runtime constraints allow.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-plugin-node/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.