PSA/ee/docs/plans/2026-03-16-cross-package-cleanup-p0-p2/SCRATCHPAD.md

Scratchpad: Cross-Package Cleanup P0-P2

Key Commands Reference

Build & TypeScript

# Full build (the definitive check)
npm run build

# TypeScript check on specific package (faster than full build)
cd packages/<pkg> && npx tsc --noEmit
cd server && npx tsc --noEmit
cd ee/server && npx tsc --noEmit
cd ee/packages/workflows && npx tsc --noEmit

Cross-Package Violations (Lint)

# Authoritative violation count (use this, NOT nx run-many which undercounts ~50%)
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | wc -l

# Per-source package breakdown
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | sed 's/.*Feature package "\([^"]*\)".*/\1/' | sort | uniq -c | sort -rn

# Per-target package breakdown
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | sed 's/.*feature package "\([^"]*\)".*/\1/' | sort | uniq -c | sort -rn

# Violations for a specific source package
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | grep 'Feature package "client-portal"'

# Violations for a specific target
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | grep 'feature package "documents"'

Circular Dependencies

# Generate Nx graph and check for new cycles
npx nx graph --file=/tmp/graph.json && node scripts/check-circular-deps.mjs /tmp/graph.json --baseline .github/known-cycles.json

# Update baseline after fixing cycles (include tightened baseline in commit)
npx nx graph --file=/tmp/graph.json && node scripts/check-circular-deps.mjs /tmp/graph.json --update-baseline .github/known-cycles.json

# As of 2026-03-17, the root `package.json` override `nx -> brace-expansion@^2.0.2`
# restores `npx nx graph --file=/tmp/graph.json` in this workspace.

Grep Patterns for Finding Violations

# Find all imports of a package from outside it
grep -r "@alga-psa/documents" --include="*.ts" --include="*.tsx" packages/ | grep -v "packages/documents/" | grep -v node_modules

# Find imports of auth-compat
grep -r "auth-compat" --include="*.ts" --include="*.tsx" -l | grep -v node_modules

# Find type-only cross-vertical imports
grep -rn "import type.*@alga-psa/" packages/ --include="*.ts" --include="*.tsx" | grep -v node_modules

# Check what shared/ imports from workflows
grep -r "@alga-psa/workflows" shared/ --include="*.ts" --include="*.tsx" -l | grep -v node_modules

Testing

# Run tests locally (requires .env.localtest)
npm run test:local

# Run affected tests only
npx vitest run --changed

# Run specific test file
cd server && npx vitest run path/to/test.test.ts

Decisions

• 2026-03-16: P0-1 test files moved to ee/packages/workflows/ (not packages/workflows/) because the tests reference EE-specific domain event builders
• 2026-03-16: @alga-psa/shared added as devDependency to ee/packages/workflows/package.json for moved test imports
• 2026-03-16: Removed 18 baseline cycles that all contained the resolved @alga-psa/shared -> @alga-psa/workflows edge; used manual baseline pruning because local Nx graph generation is still broken by the brace_expansion_1.default runtime error
• 2026-03-17: Added a root overrides.nx.brace-expansion = ^2.0.2 pin so nx's bundled minimatch@9 resolves a compatible brace-expansion version and npx nx graph works again locally.
• 2026-03-17: packages/storage now owns its document/media workflow-event payload builders and no longer depends on @alga-psa/auth, @alga-psa/shared, @alga-psa/workflow-streams, or @alga-psa/workflows; this removed the last unbaselined storage-driven cycles without changing emitted payload shapes.

Current State (2026-03-17)

• Branch: cleanup/circular_deps (rebased on origin/main)
• Feature checklist: complete through F039
• Known cycles baseline: 11 cycles after the restored Nx graph check and the storage dependency cleanup
• Authoritative lint count: 57 no-feature-to-feature-imports violations (down from the original 103 baseline)
• Build / graph status: npm run build, cd packages/storage && npx tsc --noEmit, cd packages/storage && npx vitest run tests/storageService.workflowEvents.test.ts, and npx nx graph --file=/tmp/graph.json && node scripts/check-circular-deps.mjs /tmp/graph.json --baseline .github/known-cycles.json all pass locally

2026-03-16 Progress Log

• Verified shared/ only references @alga-psa/workflows in a comment within shared/types/product-email-domains.d.ts.
• Verified moved workflow tests compile with cd ee/packages/workflows && npx tsc --noEmit; cd shared && npx tsc --noEmit also passes.
• npx nx graph --file=/tmp/graph.json still fails locally with brace_expansion_1.default is not a function, including under Node 20, so cycle-baseline verification currently relies on the removed import edge plus baseline pruning.
• npm run build passed from repo root after the workflow test moves and cycle-baseline update; build emitted existing Next.js webpack warnings only.
• Pending workflow-test file moves and the related ee/packages/workflows/package.json devDependency update are ready to commit as the final P0-1 code delta.
• Authoritative npm run lint baseline is 103 no-feature-to-feature-imports violations when run directly from repo root.

P0-2 Violation Breakdown (from /tmp/p0-lint.log)

By source package
38 client-portal
14 workflows
13 tickets
12 clients
10 projects
 9 billing
 3 assets
 2 users
 2 integrations

By target package
39 documents
13 tickets
 9 billing
 8 sla
 7 clients
 6 scheduling
 6 projects
 6 integrations
 5 workflows
 4 users

• Migrated ee/server/src/app/api/extensions/_auth.ts to call getSession() directly from @alga-psa/auth, removing its dependency on @/lib/auth-compat.
• Migrated ee/server/src/app/api/provisioning/tenants/route.ts to call getSession() directly from @alga-psa/auth, leaving server/src/lib/auth-compat.ts with no remaining callers.
• Deleted server/src/lib/auth-compat.ts; the compatibility wrapper is fully retired in favor of getSession() from @alga-psa/auth.
• npm run build still passes after deleting server/src/lib/auth-compat.ts; only pre-existing webpack warnings were emitted.
• Auth-compat retirement is now represented by the committed F008-F011 change series, so the P1-3 code path is fully checked in.
• Added export * from './assets' to packages/msp-composition/src/index.ts to expose the existing assets composition barrel from the package root.
• Added export * from './billing' to packages/msp-composition/src/index.ts so billing composition helpers are reachable from the main barrel.
• Added export * from './clients' to packages/msp-composition/src/index.ts; the root barrel now exposes assets, billing, clients, tickets, projects, and scheduling.
• npm run build passes with the expanded @alga-psa/msp-composition barrel; no new build regressions surfaced.
• The msp-composition export wiring is now fully committed via the F013-F016 change series.
• P2-5a inventory: packages/projects/src/actions/projectActions.ts is the active projects -> clients direct import (getContactByContactNameId); packages/scheduling/src currently has no direct @alga-psa/clients imports.
• Verified packages/clients/src/context/ClientCrossFeatureContext.tsx already exports the client cross-feature provider + hook surface needed for composition-layer injection.
• Verified packages/msp-composition/src/clients/MspClientCrossFeatureProvider.tsx already bridges tickets/surveys/assets callbacks into the clients context.
• Current lint baseline has 0 active projects -> clients and 0 active scheduling -> clients warnings; the lone remaining direct import in packages/projects/src/actions/projectActions.ts is an intentionally justified server-action exception.
• P2-5a is effectively green in the current tree: the most recent root npm run build passed, and the client-related pair counts are already reduced to zero warnings.
• P2-5a now closes as verification/bookkeeping only because the context/provider migration had already landed before this plan pass.
• P2-5b inventory from the authoritative lint log: documents is still the top target with 39 warnings sourced from projects (10), clients (10), client-portal (7), tickets (5), assets (3), users (2), workflows (1), and billing (1). Common import shapes are entity-image helpers, document utilities, Documents/DocumentUpload UI, and KB types.
• Moved the public uploadEntityImage / deleteEntityImage entrypoint to @alga-psa/storage and updated the client-portal, teams, users, tenancy, and clients callers to import from the horizontal package instead of @alga-psa/documents.
• Added a horizontal DocumentsCrossFeatureContext to @alga-psa/core so remaining document UI imports can be replaced without introducing new vertical-to-vertical dependencies.
• DocumentsCrossFeatureContext must stay off the root @alga-psa/core barrel because exporting a client-only React context there causes server imports of @alga-psa/core to fail Next.js builds.
• T001 verified that shared/ only mentions @alga-psa/workflows in the comment inside shared/types/product-email-domains.d.ts; there are no actual code imports left.
• T002 verified cd ee/packages/workflows && npx tsc --noEmit succeeds after the ten test-file moves.
• T003 verified a fresh repo-root npm run build succeeds after the workflow moves, auth cleanup, and storage entity-image extraction work.
• T004 hit the documented local skip condition: npx nx graph --file=/tmp/graph.json still fails with brace_expansion_1.default is not a function, so cycle verification continues to rely on the pruned baseline and removed import edge.
• T005 confirmed .github/known-cycles.json now contains 12 baselined cycles, down from the prior 30.
• T006 reconfirmed that the direct lint command remains the authoritative measurement path; after the later document cleanup it reports 98 current violations.
• T007 reconfirmed the per-source lint breakdown pipeline; the latest run is led by client-portal, workflows, tickets, clients, and projects.
• T008 reconfirmed the per-target lint breakdown pipeline; documents remains the top target even after the entity-image move, followed by tickets, billing, and sla.
• T009 verified there are no remaining auth-compat source references anywhere in the repo.
• T010 verified ee/server/src/app/api/extensions/_auth.ts now imports getSession directly from @alga-psa/auth.
• T011 verified ee/server/src/app/api/provisioning/tenants/route.ts now imports getSession directly from @alga-psa/auth.
• T012 confirmed server/src/lib/auth-compat.ts no longer exists on disk.
• T013 reuses the latest repo-root green build to validate the auth-compat removal end-to-end.
• T014 verified packages/msp-composition/src/index.ts exports ./assets from the root barrel.
• T015 verified packages/msp-composition/src/index.ts exports ./billing from the root barrel.
• T016 verified packages/msp-composition/src/index.ts exports ./clients from the root barrel.
• T017 reuses the latest repo-root green build to validate the expanded msp-composition barrel.
• T018 verified the current lint output has 0 active projects -> clients violations, which is below the historical non-zero starting point for P2-5a.
• T019 verified packages/clients/src/context/ClientCrossFeatureContext.tsx exists and exports the expected provider/hook pair.
• T020 reuses the latest repo-root green build to validate the current client-composition setup.
• T021 verified the latest lint run has 34 documents-target violations, which is below the <36 target in the plan.
• T022 verified no vertical package now imports uploadEntityImage or deleteEntityImage from @alga-psa/documents; those callers now resolve through @alga-psa/storage.
• T023 reuses the latest repo-root green build to validate the current document-cleanup changes.
• F028 conditions are met in the current tree: repo-root build passes and the documents target is down to 34 warnings from the earlier 39 baseline.
• The current document-cleanup series is committed through F025, F026, and the follow-up barrel fix, so the implemented P2-5b work is fully checked in.
• Rolled the DocumentsCrossFeatureContext out into composition providers for MSP and client-portal shells, then migrated the remaining client-side document UI/util callers in assets, tickets, and client-portal to consume the context instead of importing @alga-psa/documents directly.
• Moved the client-portal document provider out of packages/client-portal and into server/src/app/client-portal/ClientPortalDocumentsProvider.tsx after lint exposed that a local provider would itself create a new client-portal -> documents violation.
• Validation after the provider rollout: npm run lint now reports 91 total no-feature-to-feature-imports warnings and only 27 targeting documents (down from 98/34 before this pass); repo-root npm run build also passes.
• F030 categorization snapshot from /tmp/alga-lint-f030.log: client-portal now has 34 remaining warnings. 6 are clearly fixable (client-kb.ts, ClientKBArticleView.tsx, ClientKBPage.tsx via @alga-psa/types; ProjectDetailView.tsx via a composition facade). The other 28 are inherent composition edges across tickets, billing, clients, and users, where client-portal is intentionally orchestrating vertical feature APIs/components and is a reasonable candidate for justified eslint-disable comments in F031.
• Acceptable/inherent client-portal edges: client-billing.ts, client-tickets.ts, clientPaymentActions.ts, BillingOverview.tsx, ClientInvoicePreview.tsx, ClientProfile.tsx, ClientDetailsSettings.tsx, ClientPasswordChangeForm.tsx, UserManagementSettings.tsx, ClientAddTicket.tsx, TicketDetails.tsx, TicketDetails.originBadge.contract.test.ts, and TicketList.tsx.
• Fixable client-portal edges queued for later items: client-kb.ts, ClientKBArticleView.tsx, ClientKBPage.tsx (type-only documents imports for P2-6), plus ProjectDetailView.tsx (presentation imports from projects, a good client-portal composition-facade candidate for F032).
• Added file-level custom-rules/no-feature-to-feature-imports disables with explicit justification comments to the acceptable/inherent client-portal composition files; a fresh npm run lint now reports 63 total violations and only 6 remaining client-portal warnings, all in the previously identified fixable KB/project files.
• Created a new horizontal @alga-psa/client-portal-composition package and moved the project metrics card composition there via ClientPortalProjectMetrics; packages/client-portal/src/components/projects/ProjectDetailView.tsx no longer imports from @alga-psa/projects directly.
• Validation after F032: cd packages/client-portal && npx tsc --noEmit, cd server && npx tsc --noEmit, and npm run lint all pass; only 3 client-portal violations remain, all from the KB type-only imports targeted by P2-6.
• Re-ran the full repo-root npm run build after the new @alga-psa/client-portal-composition package landed; the build is green, so the client-portal cleanup track is now blocked only on the planned P2-6 type extraction.
• The client-portal cleanup series is now fully checkpointed through F030-F034: acceptable edges are documented and justified, the project-detail composition moved to a horizontal package, the build is green, and only the KB type-only imports remain for P2-6.
• F035 inventory: the meaningful remaining P2-6 candidates are the KB types IKBArticleWithDocument and ArticleType, imported type-only from @alga-psa/documents/actions in packages/client-portal/src/actions/client-portal-actions/client-kb.ts, packages/client-portal/src/components/kb/ClientKBArticleView.tsx, and packages/client-portal/src/components/kb/ClientKBPage.tsx. The broader grep also finds many same-package or horizontal-package type imports, but those are not cross-vertical cleanup targets.
• Moved the KB domain types into packages/types/src/lib/knowledgeBase.ts and exported them from @alga-psa/types; packages/documents/src/actions/kbArticleActions.ts now consumes those shared definitions instead of owning them locally.
• Validation after F036: cd packages/types && npx tsc --noEmit, cd packages/client-portal && npx tsc --noEmit, and cd packages/documents && npx tsc --noEmit all pass.
• Updated the three client-portal KB callers (client-kb.ts, ClientKBArticleView.tsx, ClientKBPage.tsx) to import the extracted KB types from @alga-psa/types; npm run lint now reports 0 remaining client-portal feature-import warnings and 57 total violations repo-wide.
• Re-ran the full repo-root npm run build after the KB type import swap; build stays green, and the lint baseline remains at 57, down from the original authoritative 103 count.
• The P2-6 type extraction series is now fully checkpointed through F035-F039: candidates identified, KB types moved into @alga-psa/types, callers updated, build re-verified, and the feature checklist is complete.
• Root-cause for the old nx graph failure: nx's bundled minimatch@9.0.3 was resolving the repo-level brace-expansion@5, which breaks braceExpand() at runtime. Pinning overrides.nx.brace-expansion to ^2.0.2 and refreshing node_modules restored npx nx graph.
• Removed stale packages/storage dependencies on auth/shared/workflows and replaced its @alga-psa/workflow-streams payload-builder imports with local equivalents in packages/storage/src/workflowEventPayloads.ts; this eliminated the remaining storage-driven graph cycles while preserving the same published event payload fields.
• Validation for the storage cleanup: cd packages/storage && npx tsc --noEmit, cd packages/storage && npx vitest run tests/storageService.workflowEvents.test.ts, npx nx graph --file=/tmp/graph.json && node scripts/check-circular-deps.mjs /tmp/graph.json --baseline .github/known-cycles.json, and repo-root npm run build all pass.
• T024 now passes end-to-end: the restored graph run reports 11 total cycles, .github/known-cycles.json has been tightened from 12 to 11, and the checker reports No new circular dependencies.
• T025 verified the client-portal cleanup end-to-end: npm run lint now reports 0 remaining Feature package "client-portal" violations, which means every prior client-portal edge was either removed via composition/type extraction or intentionally suppressed with a justification comment.
• T026 reuses the latest repo-root green npm run build after the client-portal composition package and KB type-extraction changes, confirming the client-portal cleanup series remains build-safe.
• T027 verified grep -rn "import type.*@alga-psa/documents" packages/client-portal/ --include='*.ts' --include='*.tsx' now returns 0 matches.
• T028 verified the new shared KB definitions live in packages/types/src/lib/knowledgeBase.ts and are exported through packages/types/src/index.ts.
• T029 reuses the latest repo-root green npm run build after the KB type extraction and caller migration.
• T030 confirmed the authoritative lint count is now 57, which is substantially below the P0-2 baseline of 103.

Remaining Open Work

• None. Feature and test checklists are complete.

Gotchas

• npm run lint is the correct command (not npx nx run-many --target=lint which misses ~50% of violations)
• The repo engine range is >=20 <25; under the current local Node v25.8.1, npm install emits EBADENGINE warnings even though the verified commands above still pass.
• Never create re-export shims when migrating — update all callers directly
• client-portal is inherently a composition layer — some violations may be acceptable with eslint-disable
• When adding context facades, providers must go in DefaultLayout.tsx (not per-page) because DrawerOutlet renders at layout level
• msp-composition is a horizontal package so it's allowed to import from verticals — its internal violations are by design