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

Cross-Package Cleanup: P0-P2 Priorities

Date: 2026-03-16 Status: In Progress Branch: cleanup/circular_deps (rebased on origin/main)

Problem Statement

The Alga PSA monorepo has accumulated cross-package violations (vertical packages importing from other vertical packages), circular dependency cycles (30 baselined), and stale re-export shims. This degrades build reliability, makes refactoring harder, and increases cognitive overhead.

Goals

1. Eliminate the shared → workflows circular dependency edge (responsible for 18 of 30 baselined cycles)
2. Establish an authoritative cross-package violation count baseline
3. Delete remaining stale shims (auth-compat)
4. Wire missing msp-composition re-exports
5. Reduce cross-package violations through composition layer and type extraction

Non-Goals

• Deleting server/src/lib/db/db.tsx shim (56 callers, deferred)
• Creating new ESLint rules or enforcement (P3)
• Splitting large files (P4)
• Extension infrastructure consolidation (P4)

Implementation Items

P0-1: Verify & Commit Shared Workflow Test Moves (DONE - needs commit)

10 test files already moved from shared/workflow/ to ee/packages/workflows/src/. The shared → workflows import edge is eliminated (verified: only 1 file in shared references @alga-psa/workflows, and it's a comment).

Files moved:

• 4 runtime tests → ee/packages/workflows/src/runtime/__tests__/
• 6 domain event builder tests → ee/packages/workflows/src/runtime/schemas/__tests__/

Verification commands:

# Verify no shared/ files import @alga-psa/workflows (should return 0 actual imports)
grep -r "@alga-psa/workflows" shared/ --include="*.ts" --include="*.tsx" -l | grep -v node_modules | grep -v ".d.ts"

# TypeScript check on affected packages
cd ee/packages/workflows && npx tsc --noEmit
cd shared && npx tsc --noEmit

# Update circular dep baseline
npx nx graph --file=/tmp/graph.json && node scripts/check-circular-deps.mjs /tmp/graph.json --baseline .github/known-cycles.json

# Full build
npm run build

P0-2: Authoritative Cross-Package Violation Count

Run ESLint directly (not via nx run-many, which undercounts ~50%).

Commands:

# Full lint run (authoritative count)
npx eslint "{packages}/**/*.{ts,tsx}" --no-error-on-unmatched-pattern 2>&1 | grep "no-feature-to-feature-imports" | wc -l

# Or use root lint script
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | wc -l

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

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

P1-3: Delete auth-compat.ts Shim

File: server/src/lib/auth-compat.ts What it does: Wraps getSession() from @alga-psa/auth as getServerSession() and auth for NextAuth v5 compatibility.

Callers (2 EE files):

• ee/server/src/app/api/extensions/_auth.ts — imports auth
• ee/server/src/app/api/provisioning/tenants/route.ts — imports getServerSession

Migration: Replace imports with import { getSession } from '@alga-psa/auth' and rename usage accordingly.

Verification commands:

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

# TypeScript check
cd server && npx tsc --noEmit
cd ee/server && npx tsc --noEmit

# Build
npm run build

P1-4: Wire Missing msp-composition Exports

File: packages/msp-composition/src/index.ts Current re-exports: tickets, projects, scheduling Missing re-exports: assets, billing, clients

These subdirectories have index.ts files with exports but aren't re-exported from the main barrel.

Verification commands:

# Check which packages import from msp-composition subpaths vs main
grep -r "@alga-psa/msp-composition" --include="*.ts" --include="*.tsx" -l | grep -v node_modules | grep -v "msp-composition/src"

# TypeScript check
cd packages/msp-composition && npx tsc --noEmit

# Build
npm run build

P2-5: Composition Layer Work (Task 3-7)

The largest remaining violation source. documents is #1 target (~36 violations), client-portal is #1 source (~36 violations).

P2-5a: Task 3-7b — Client Component Violations

Violations: clients → scheduling, projects → clients

Pattern: Create ClientCrossFeatureContext in clients package (if not already exists), create MspClientCrossFeatureProvider in msp-composition, update violating files to use context.

Files to check/modify:

• packages/projects/src/ files importing from @alga-psa/clients
• packages/scheduling/src/ files importing from @alga-psa/clients (already partially done via WorkItemDrawer)

P2-5b: Task 3-7c — Document Component Violations

Violations: projects → documents, tickets → documents, assets → documents, clients → documents, client-portal → documents, users → documents, billing → documents

This is the #1 target. Many imports are for:

• uploadEntityImage, deleteEntityImage (entity image management)
• downloadDocument, getDocumentDownloadUrl (document utilities)
• Documents component, DocumentUpload, FolderSelectorModal
• Type imports: IKBArticleWithDocument, ArticleType

Strategy: Move entity image actions to @alga-psa/storage or create context facades for UI components.

P2-5c: Task 3-7d — Client-Portal Violations

client-portal imports from: tickets (9), billing (6), clients (5), documents (6), projects (3), users (5) = ~34 violations.

Strategy: May need client-portal-composition package, or accept some violations with eslint-disable (client-portal is inherently a composition layer).

Verification commands for all P2-5 sub-tasks:

# Count violations after each change
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | wc -l

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

# TypeScript check on modified packages
npx tsc --noEmit -p packages/<package>/tsconfig.json

# Full build
npm run build

# Check circular deps didn't regress
npx nx graph --file=/tmp/graph.json && node scripts/check-circular-deps.mjs /tmp/graph.json --baseline .github/known-cycles.json

P2-6: Move Shared Types to @alga-psa/types (Task 3-6)

Move type-only cross-package imports to @alga-psa/types. Current candidates are limited — most type imports already use @alga-psa/types. The main candidates:

• IKBArticleWithDocument, ArticleType from @alga-psa/documents (used by client-portal KB pages)
• Any ticket/client/project types imported across verticals

Verification commands:

# Find type-only cross-vertical imports
grep -rn "import type.*@alga-psa/" packages/ --include="*.ts" --include="*.tsx" | grep -v node_modules | grep -v "from '@alga-psa/\(core\|db\|types\|ui\|shared\|auth\|event-bus\|event-schemas\|validation\|storage\|formatting\|workflow-streams\|user-composition\|tenancy\|msp-composition\)'"

# TypeScript check after moves
cd packages/types && npx tsc --noEmit

# Full build
npm run build

Acceptance Criteria

• P0-1: No files in shared/ import @alga-psa/workflows. Circular dep baseline reduced.
• P0-2: Authoritative violation count documented.
• P1-3: auth-compat.ts deleted, 2 EE callers migrated, build green.
• P1-4: msp-composition/src/index.ts re-exports all subdirectories, build green.
• P2-5: Cross-package violations reduced (target: <30 from current ~84).
• P2-6: Type-only imports moved to @alga-psa/types where applicable.

Verification Runbook (use after every commit)

# 1. TypeScript check (fast, catches import errors)
cd server && npx tsc --noEmit

# 2. Full build (catches Next.js + bundling issues)
npm run build

# 3. Cross-package violation count
npm run lint 2>&1 | grep "no-feature-to-feature-imports" | wc -l

# 4. Circular dependency check (if nx graph works)
npx nx graph --file=/tmp/graph.json 2>/dev/null && node scripts/check-circular-deps.mjs /tmp/graph.json --baseline .github/known-cycles.json

# 5. Run affected tests
npx vitest run --changed