chore(bootstrap): publishing metadata, required registry param, exports test, docs

[sroussey]

Severity

Every item here is MEDIUM or LOW. This is publishing hygiene, API shape, CI coverage, and docs — polish, not a gate.

PR #672 has no correctness, security, or data-integrity defect. A reviewer verified that:

• the registration set and order are identical across the old production body, the old test body, and the new registerAllDefaults (14 calls, no security delta);
• all 14 register*Defaults genuinely forward the registry parameter, with none falling back to the global;
• there is no dependency cycle;
• the re-export shim preserves the full public surface, including types.

A1 — missing license field (MEDIUM) — plan premise was wrong, adapted

packages/bootstrap/package.json had no license key while setting publishConfig.access: "public". Without it, bun run publish-workspaces pushes to npm with license metadata absent, so the registry page and every SBOM/license scanner report it unlicensed — contradicting the SPDX Apache-2.0 headers in its own source.

Correction to the plan I was given: it asserted "all 13 existing packages/* declare Apache-2.0". They do not. grep -n '"license"' packages/*/package.json providers/*/package.json package.json returns zero matches — no workspace in this repo declares a license field, and the cited key-order anchor (packages/knowledge-base/package.json:4-5) is version / repository, not a license key.

I applied the fix anyway, because it stands on its own merits for a package that is access: "public" and carries SPDX headers — but flagging that this is now the only package with the field, and that the same gap exists across the other 13 packages and 28 providers. Worth a separate repo-wide sweep; deliberately out of scope here.

Also added packages/bootstrap/LICENSE (byte-identical to packages/knowledge-base/LICENSE). 8 of 14 packages ship one; npm includes LICENSE regardless of the files field.

A2 — version drift (MEDIUM)

packages/bootstrap was 0.3.37; root and every other workspace are 0.3.38. Set to 0.3.38.

Left alone, bun run bunset (--patch --all) would bump bootstrap to 0.3.38 while everything else went to 0.3.39, so workglow@0.3.39 would publish a @workglow/bootstrap@0.3.38 dependency and the offset would persist across every future release.

A3 — restored the required registry parameter (MEDIUM)

registerAllDefaults was module-private on main with a required (registry: ServiceRegistry). #672 exported it from @workglow/bootstrap, from workglow/bootstrap, and from the workglow root barrel (packages/workglow/src/common.ts:30) — while making the argument optional (= globalServiceRegistry).

Dropped the default. globalServiceRegistry is no longer imported in that file.

Rationale: the repo's own convention is "T | undefined over T? optional — force callers to be explicit", and a defaulted global-container argument is exactly the implicit ambient state that rule prevents. Making the parameter optional at the same moment the function goes from module-private to triple-exported converts a compile error into a silent cross-tenant registry mutation: a caller who builds an isolated context and then calls registerAllDefaults() gets no diagnostic, just defaults installed on the wrong registry. The convenience saved one identifier at one call site in the entire repo.

The root-barrel export is kept — with a required parameter it is no longer hazardous.

Consumer consequence: registerAllDefaults() with no argument is now a TypeScript error. Callers write registerAllDefaults(globalServiceRegistry) or, preferably, bootstrapWorkglow() / createOrchestrationContext(). @workglow/bootstrap has never been published, so this breaks zero real consumers — and the window to fix it closes at first publish.

A3 caller update — plan instruction was wrong, adapted

The plan said to update vitest.setup.ts to import { globalServiceRegistry } from "@workglow/util" and call registerAllDefaults(globalServiceRegistry). That does not work, for the same reason #672's own comment in that file gives for importing by source path: the isolated linker keeps workspace packages out of the repo root's node_modules. Verified directly —

createRequire("<root>/vitest.setup.ts").resolve("@workglow/util")
  → MODULE_NOT_FOUND

Reaching into packages/util/src/di/ServiceRegistry instead would be worse: that loads a second copy of the module, so the setup file would populate a different globalServiceRegistry object than the one tests read through @workglow/util, and every test depending on registered defaults would fail.

So the setup file now calls bootstrapWorkglow() from the bootstrap package's source path. It is exactly equivalent — with no logger option, bootstrapWorkglow is a call to registerAllDefaults(globalServiceRegistry) and nothing else — and it resolves @workglow/util correctly, because the import happens from inside packages/bootstrap, where the linker did place it. It is also the public entry point, which is what a bootstrap harness should be using.

A4 — CI coverage of the published contract (MEDIUM)

Nothing in CI exercised the package's build output. The vitest harness imports the raw source module; the package ships no test files despite "test": "bun test"; the only dist consumer is workglow/build.ts's collision detector. So a typo in the exports map, or a build-browser that silently emitted no dist/browser.js, would ship to npm and import { bootstrapWorkglow } from "@workglow/bootstrap" would throw ERR_PACKAGE_PATH_NOT_EXPORTED with no CI signal.

Added one file: packages/test/src/test/util/BootstrapPackageExports.test.ts. Both routing claims verified before relying on them — scripts/test.ts:79 maps section util to packages/test/src/test/util, and .github/workflows/test.yml:195-211 runs test-vitest-unit with needs: build, downloading the build-output artifact, so real dist/ is present.

It asserts:

1. every leaf string under exports (recursing through the react-native / browser / bun condition objects) resolves to a file that exists — catching a typo'd path and a build that emitted nothing;
2. the "." → default import target (dist/node.js) exports bootstrapWorkglow, createOrchestrationContext, and registerAllDefaults. Imported by file URL via pathToFileURL, not by the @workglow/bootstrap specifier, sidestepping the isolated-linker problem above.

bun run use-source stubs satisfy both assertions, so source mode is unaffected.

A5 — docs (LOW)

• New packages/bootstrap/README.md and packages/bootstrap/CHANGELOG.md (13 of 14 packages already had both; bootstrap was the only one without).
• .claude/CLAUDE.md: bootstrap added to the dependency-graph block, and a new "Key packages" entry stating that the implementation lives in @workglow/bootstrap and that packages/workglow/src/bootstrap.ts is now a pure re-export shim — otherwise a contributor adding a default registration edits the dead shim.

On the files array (["dist", "src/**/*.md"], which does not list root-level .md): all 13 sibling packages ship root-level README.md / CHANGELOG.md under the identical array, so bootstrap now matches sibling tarball behavior exactly — npm always includes README and LICENSE regardless of files. No files change made.

Note on the graph placement: bootstrap depends on ai / knowledge-base / mcp, not on providers/*, so it is listed as a sibling of providers/* on the tier below ai, rather than beneath it.

A6 — dependency weight (LOW, documented only)

@workglow/bootstrap pulls @workglow/mcp (which has a hard dependencies entry on @modelcontextprotocol/sdk — verified), @workglow/ai, and @workglow/knowledge-base. A light consumer wanting only logger/task/storage defaults installs the MCP SDK and the full AI layer.

Entry points deliberately not split — the package registers all defaults by design, and splitting would reintroduce the drift #672 was extracted to fix. The tradeoff is recorded in the new README, with the guidance that consumers wanting a subset should call the individual register*Defaults(registry) functions directly.

A7 — build ordering (LOW, note only — turbo.json unchanged)

turbo.json:7-10 gives build-js only ^build-types, while packages/workglow/build.ts:30 runtime-imports every barrel star-spec via assertNoExportCollisions — now including ./bootstrap → @workglow/bootstrap → dist/node.js. On a cold bun run rebuild with unlucky scheduling this can fail to resolve. Pre-existing for @workglow/ai; this PR's parent adds one more edge.

Proposed follow-up (not applied here): "build-js": { "dependsOn": ["^build-types", "^build-js"] }. The concurrency cost should be measured before adopting it.

Verification

Ran, and observed passing:

• bun install — clean, bun.lock unchanged.
• bun run build — 86/86 tasks, exit 0 (includes build-types).
• bun run build:types — 42/42 tasks.
• npx turbo run build-types --filter @workglow/test --force — 37/37, confirming the new test file type-checks (packages/test had it cached otherwise).
• npx vitest run packages/test/src/test/util/BootstrapPackageExports.test.ts — 3/3 passed.
• A4 negative check, actually performed: temporarily rewrote the "." import target to ./dist/nodee.js; 2 of 3 assertions failed (missing reported "." [import] -> ./dist/nodee.js, and the dynamic import threw Cannot find module). Restored and re-verified.
• rg -n 'registerAllDefaults\(\s*\)' --type ts — no matches outside dist/.
• jq -r .version packages/*/package.json providers/*/package.json examples/*/package.json package.json | sort -u — exactly one line, 0.3.38.
• jq -r .license packages/bootstrap/package.json — Apache-2.0.
• npx prettier --check on all changed files — clean. npx eslint on changed sources — clean (vitest.setup.ts is not covered by the eslint config).
• Full vitest unit tier (bun run test:vitest:unit) — 434 files passed | 2 skipped (436), 5048 tests passed | 47 skipped, exit 0, including the new BootstrapPackageExports file. This also proves the reworked vitest.setup.ts still populates the global registry: the suite depends on those defaults being present, and a second-copy globalServiceRegistry would have failed it broadly.

Not verified: behavior of bun run bunset / publish-workspaces against a real npm registry (neither was executed); CI itself, which will run on this PR.

---

🤖 Generated with Claude Code

---

Generated by Claude Code