Skip to content

feat!: move flows, integrations and utilities out of the package root (A1) - #387

Merged
LinuxDevil merged 1 commit into
mainfrom
lou-a1-subpaths
Oct 4, 2026
Merged

LinuxDevil merged 1 commit into
mainfrom
lou-a1-subpaths

Conversation

@LinuxDevil

Copy link
Copy Markdown
Owner

Closes #236

What

Moves flows, the credentialed Jira/GitHub/Slack/email tools, encryption, StorageService and the validators out of the package root into subpaths. Nothing is removed.

  • ./flows now also re-exports src/types/flow (the flow types leave the root and ./types).
  • New ./integrations re-exports tools/built-in/{email,jira,github,slack}; tools/built-in/index.ts drops them, so they leave the root and ./tools.
  • New ./utils (src/utils/index.ts becomes the subpath barrel) exports security/crypto, the three security/types types, storage/StorageService, storage/types, StorageServiceApprovalStore, LocalStorageCheckpointStore and ./validators; it no longer re-exports ./errors/./errorCodes (the root exports those two modules directly instead).
  • src/storage/index.ts is deleted; ApprovalGate.ts/checkpoint.ts import ../storage/StorageService directly. src/execution/index.ts exports explicit named lists from ApprovalGate/checkpoint minus the two moved stores.
  • package.json exports + tsup.config.ts entries added for ./integrations and ./utils.
  • specToAgent()'s credentials error now names createGitHubTools(config)/createJiraTools(config) from @lousho/build-ai-agent/integrations (code LOUSHO_TOOL_NEEDS_CREDENTIALS unchanged).
  • importGraph.test.ts ENTRY_POINTS gains both entries; verify-docs-snippets.ts's storage placeholder is now typed from /utils.
  • Agent Forge (5 files) imports flow names from @lousho/build-ai-agent/flows.
  • Docs: all listed pages updated; docs/installation.md gains the entry-point table at the end of the "Entry points share code" section (no new heading).
  • New src/publicSurface.test.ts / src/publicSurface.test-d.ts pin the split (value names absent from root + present on the subpath; type names via @ts-expect-error/expectTypeOf). A2a/A2b/A2c/A3/A5 will append their names.
  • CHANGELOG ### Breaking entry with the ticket's migration note.

Export counts (TypeScript checker over src/index.ts)

  • Before: 825 exports. After: 727 exports — 98 fewer names.
  • Spec said 97: the flow barrel now holds 19 engine exports, one more than the audit's 18 — isCreateAgentResult (LOU-R14, LOU-R14: reject createAgent() agents passed to flows #364) was added after the ticket's cc5ddb8 measurement. Subpath counts: ./flows 52, ./integrations 24, ./utils 22. ./types lost the 33 flow types (65→32); ./tools lost the 24 integration names (136→112).

Spec decisions exercised / ambiguities resolved

  • ./integrations and ./utils names kept as decided in the ticket.
  • src/flows/index.ts re-exports ../types/flow after its own barrels — no collision (FlowDefinitionNode stays distinct).
  • G7 already merged: docs/api-overview.md was split since the ticket's line numbers were written; the moved prose lives at api-overview.md:50 (stores row), :317 (flows bullet), :343 (utilities bullet) and was updated in place. docs/sessions.md no longer mentions the two stores (G-wave rewrite removed the snippet), so nothing to change there.
  • docs/streaming.md/docs/errors.md mention createGitHubTools(config); errors.md now names the /integrations specifier.
  • apps/agent-forge/server/runRegistry.ts:599 used an inline import('@lousho/build-ai-agent').AgentFlow; switched to the new /flows type import (the ticket's grep only covered import { } statements).
  • scripts/.tmp/ helper script kept uncommitted via info/exclude.

Verification

  • npm run build (ESM+CJS+DTS) ✓ — dist/integrations/index.* and dist/utils/index.* emitted.
  • npx tsc --noEmit ✓ · npm run typecheck:tests ✓ · npm run test:types ✓ (82 typecheck tests incl. publicSurface.test-d.ts) · npm run lint zero warnings.
  • npx vitest run src/publicSurface.test.ts src/providers/importGraph.test.ts src/providers/sharedChunks.test.ts src/spec/specToAgent.test.ts src/flows src/tools/built-in src/execution/ApprovalGate.test.ts src/execution/checkpoint.test.ts src/execution/checkpointHistory.contract.test.ts — 540 tests pass; importGraph covers the two new entries in ESM and CJS.
  • npm run docs:verify-snippets -- --skip-build ✓ (258 snippets type-check, 8 run).
  • Agent Forge: typecheck ✓, typecheck:server ✓, test -- --run (119) ✓, test:server (133) ✓.
  • npm run docs:llms re-run, llms.txt/llms-full.txt committed.
  • npm run pack-smoke: every exports entry loads from the packed tarball in ESM and CJS (19/19), createAgent + mockModel turn ok in both — but the tarball-size guards fail: 924 entries (cap 900), 16,996,312 B unpacked (cap 16 MiB), 4,625,773 B packed (cap 4.5 MiB). Pre-existing on main: measured ~898 entries / ~16.99 MB / ~4.6 MB there too — alpha.9 growth already breaches all three caps; the in-flight fix/lou-s1-tarball PR slims the tarball (test-d.ts/testkit/cassettes exclusions, MAX_ENTRIES 1050) and is the designated fix. This PR adds ~26 entries legitimately (two new dist subpath entries + src/integrations/index.ts).

… (A1)

The root exported 825 names; flows, the credentialed Jira/GitHub/Slack/email
tools, encryption, StorageService and the validators were not agent
functionality a new user needs there. They move to subpaths, nothing is
removed:

- './flows' now also re-exports the flow types (they leave './types')
- new './integrations' re-exports email/jira/github/slack built-ins
  (they leave the root and './tools')
- new './utils' holds crypto, security option types, StorageService,
  StorageServiceApprovalStore, LocalStorageCheckpointStore and the
  validators; the root keeps only utils/errors and utils/errorCodes
- root exports drop './flows', './storage' (barrel deleted) and the two
  StorageService stores move with it

Root exports: 825 -> 727 (98 fewer; isCreateAgentResult was added to the
flows barrel after the audit's count of 97).

New src/publicSurface.test.ts / .test-d.ts pin the split; later wave-4
tickets extend them.

Closes #236
@LinuxDevil
LinuxDevil merged commit 33f0939 into main Oct 4, 2026
1 of 9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[A1] Move flows, integrations and utilities out of the package root into subpaths

1 participant