pedwfrontend/memory-bank/refactor-plan-actions-index.md

Refactor Plan — Priority 1 (actions/index.js split)

Last updated: 2026-03-13

Handover note (2026-03-13)

• Import-migration wave from actions barrel to focused modules has been checked in and completed via PR.
• Next chunk will be delivered from a new branch and should start at legacy decomposition.

Next branch kickoff scope (Phase 5)

Primary objective: split actions/services/legacyActionsService.js into smaller direct implementations while preserving function signatures.

Recommended first slice:

1. Extract reference/search internals from legacyActionsService.js into dedicated modules.
2. Keep actions/services/* exports stable and route through new direct implementations.
3. Add focused parity checks per extracted function group (inputs, headers, hash behavior, return shapes).

Then continue with:

4. Portal/document extraction in small batches.
5. Remove dead wrappers from legacyActionsService.js once call paths are fully migrated.

Phase 5 slice roadmap (completed)

Status key: [x] done, [ ] pending

1. [x] Search + reference direct extraction
   • searchDirectService.js, referenceDataDirectService.js
   • searchService.js / referenceDataService.js re-pointed
2. [x] Document direct extraction
   • create documentDirectService.js
   • re-point documentService.js
   • parity checks: blob paths/hash behavior/return shapes
3. [x] Portal direct extraction
   • create portalDirectService.js
   • re-point portalService.js
   • parity checks: watched-case and completion-message flows
4. [x] Account + case direct extraction
   • create accountDirectService.js, caseDirectService.js
   • re-point grouped services
5. [x] Notify + integration + admin direct extraction
   • create notifyDirectService.js, integrationDirectService.js, adminDirectService.js
6. [x] Legacy slim-down pass
   • remove dead wrappers from legacyActionsService.js
   • keep only temporary compatibility exports still required
7. [x] Final cleanup + validation pass
   • grep checks for remaining ./legacyActionsService imports
   • lint/manual smoke checks

Phase 5 completion snapshot (2026-03-13)

• All grouped service modules now route through focused direct modules under actions/services/*DirectService.js.
• actions/services/legacyActionsService.js has been removed.
• Verification completed:
  • actions/services scan returns zero ./legacyActionsService imports.
  • npm run lint completes with warnings only.
  • npm run build completes successfully.

Next phase kickoff recommendation

Focus on post-split hardening and cleanup:

1. Add parity-focused tests for extracted direct services and actions/services/index.js export stability.
2. Consolidate repeated axios/error-handling patterns into shared clients/utilities where safe.
3. Reduce verbose debug logging in direct services (especially account/case/document paths) with redaction discipline.
4. Run targeted manual smoke matrix for search/case/myportal/document/notify with EN/CY parity checks.

Phase 6 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Add parity-focused tests for extracted services and barrel stability
   • tests/phase6/service-parity.test.cjs
   • validates grouped/direct service export parity
   • validates actions/services/index.js export stability
2. [x] Reduce repeated axios/error-handling patterns safely
   • added shared helper: actions/services/httpServiceUtils.js
   • adopted in selected direct modules without signature/return-shape changes
3. [x] Logging cleanup in sensitive direct-service flows
   • removed noisy debug logs from search/document/portal/case/admin direct services
4. [x] Add focused behavioural contract tests in current phase
   • tests/phase6/service-behaviour.test.cjs
   • success/error contract checks with mocked axios/logger (8/8 passing)
5. [x] Run targeted validation/smoke checks
   • parity test: pass
   • behavioural test: pass
   • manual smoke matrix executed (search/case/myportal/document/notify, EN/CY + negative paths)

Notes:

• Known pre-existing caveat during smoke checks:
  • /searchresults and /cy/searchresults return 500 in local dev due SSR serialization issue (initialState.search.searchString undefined).
  • treated as existing issue, not introduced by this refactor phase.

Future requirements / next-phase backlog (post-Phase-6)

1. Investigate and fix /searchresults SSR serialization issue (EN/CY parity).
2. Expand behavioural service tests to remaining domains:
   • document
   • portal
   • account
   • notify
   • integration
3. Add focused negative-path tests for token/hash/relay-sensitive handlers.
4. Continue small-batch hardening with reversible commits and parity checks per batch.
5. Prepare PR evidence bundle for each increment:
   • lint + test commands
   • behavioural/parity test outputs
   • manual EN/CY + negative-path smoke matrix

Phase 7 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Create new branch from origin/SIPS-Development with required work item prefix
   • branch: TASK21988a-phase7-postphase6-hardening
2. [x] Fix pre-existing /searchresults SSR serialization issue with EN/CY parity
   • updated pages/searchresults.js:
     • setSearch(query.q) -> setSearch(query?.q || "")
3. [x] Expand behavioural tests to remaining service domains
   • added tests/phase7/service-behaviour.test.cjs
   • coverage includes: document, portal, account, notify, integration
4. [x] Add feasible negative-path tests for token/hash/relay-sensitive flows
   • validated hashed path composition (e.g., hashAPIPath usage)
   • validated existing function error contracts (undefined/error string/rethrow)
5. [x] Execute validation bundle
   • node tests/phase6/service-parity.test.cjs -> pass
   • node tests/phase6/service-behaviour.test.cjs -> pass (8/8)
   • node tests/phase7/service-behaviour.test.cjs -> pass (10/10)
   • npm run lint -> warnings only (no new errors)
6. [x] Execute targeted manual smoke matrix (EN/CY + negative paths)
   • local server on localhost:3001 (3000 occupied)
   • /searchresults, /cy/searchresults -> 200
   • /case, /cy/case -> 200
   • /myportal, /cy/myportal -> 307 -> /auth/signin
   • /api/file/getbloblistproxy?container=test&casefolderID=test -> 400
   • POST /api/email/notify with {} -> 400

Phase 7 rollback notes

• Revert pages/searchresults.js fallback change if search behaviour regresses unexpectedly.
• Remove tests/phase7/service-behaviour.test.cjs if test scope needs to be rolled back.
• Reset branch to pre-Phase-7 commit if full rollback required.

Phase 8 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Create new branch from origin/SIPS-Development with required work item prefix
   • branch: TASK22017-phase8-hardening-slice
2. [x] Re-enable/enforce hash validation in 4 sensitive target handlers
   • pages/api/file/deleteblobcase.js
   • pages/api/file/deleteblobrep.js
   • pages/api/file/createappealcompletemessage_api.js
   • pages/api/endpoint/getportallogin_api.js
3. [x] Standardize negative-path behavior for invalid/missing hash and required keys
   • added early 400 guards for missing required query params where applicable
   • preserved response-shape contracts/signatures
4. [x] Improve logging discipline in sensitive flow
   • removed noisy direct console output in createappealcompletemessage_api
   • routed updated error path logging via consoleLogger
5. [x] Keep caller behavior compatible after hash re-enforcement
   • actions/services/documentDirectService.js now appends hash for:
     • deleteblobcase
     • deleteblobrep
   • actions/services/portalDirectService.js now appends hash for:
     • createappealcompletemessage_api (existing hash-path contract retained)
6. [x] Add focused Phase 8 tests
   • added tests/phase8/service-behaviour.test.cjs
   • includes negative-path coverage for all 4 target handlers
   • includes one valid-hash happy-path contract check (getportallogin_api) via mocks
7. [x] Execute validation bundle
   • node tests/phase6/service-parity.test.cjs -> pass
   • node tests/phase6/service-behaviour.test.cjs -> pass (8/8)
   • node tests/phase7/service-behaviour.test.cjs -> pass (10/10)
   • node tests/phase8/service-behaviour.test.cjs -> pass (5/5)
   • npm run lint -> warnings only (pre-existing react-hooks dependency warnings)
8. [x] Execute manual HTTP negative-path matrix + feasible happy-path spot-check
   • invalid/missing hash across 4 target handlers -> 400
   • missing required params where tested -> 400
   • valid-hash getportallogin_api spot-check returned 400 in local env due upstream relay/CRM dependency

Phase 8 rollback notes

• Revert these files to rollback the full hardening slice:
  • pages/api/file/deleteblobcase.js
  • pages/api/file/deleteblobrep.js
  • pages/api/file/createappealcompletemessage_api.js
  • pages/api/endpoint/getportallogin_api.js
  • actions/services/documentDirectService.js
  • actions/services/portalDirectService.js
  • tests/phase8/service-behaviour.test.cjs
• Re-run phase6/phase7 baseline tests and lint after rollback to confirm parity.

Phase 9 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Create new branch from origin/SIPS-Development with required work item prefix
   • branch: TASK22019-phase-9-hardening
2. [x] Re-enable/enforce hash validation in 4 additional sensitive file handlers
   • pages/api/file/createrepcompletemessage_api.js
   • pages/api/file/upload.js
   • pages/api/file/uploadsinglefile.js
   • pages/api/file/setupcontainer.js
3. [x] Standardize negative-path behavior for invalid/missing hash and key params
   • added early 400 handling for missing required query/body values where applicable
4. [x] Improve logging discipline in sensitive paths
   • removed noisy direct console logging in touched handlers
5. [x] Keep caller behavior compatible after hash re-enforcement
   • actions/services/portalDirectService.js
     • sendRepCompleteMessage now appends hash
   • actions/services/documentDirectService.js
     • upload-related calls now append hash
6. [x] Add focused Phase 9 tests
   • added tests/phase9/service-behaviour.test.cjs
   • negative-path tests for all 4 selected handlers
7. [x] Execute validation bundle
   • node tests/phase6/service-parity.test.cjs -> pass
   • node tests/phase6/service-behaviour.test.cjs -> pass (8/8)
   • node tests/phase7/service-behaviour.test.cjs -> pass (10/10)
   • node tests/phase8/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase9/service-behaviour.test.cjs -> pass (5/5)
   • npm run lint -> warnings only (no new lint errors)
8. [x] Execute manual HTTP negative-path matrix
   • missing/invalid hash checks across selected handlers -> 400
   • missing key params where tested -> 400
9. [x] Valid-hash HTTP happy-path spot-check
   • POST /api/file/uploadsinglefile?hash=<valid> -> 200 (hash generated from .env.local key)

Phase 9 rollback notes

• Revert these files to rollback the full hardening slice:
  • pages/api/file/createrepcompletemessage_api.js
  • pages/api/file/upload.js
  • pages/api/file/uploadsinglefile.js
  • pages/api/file/setupcontainer.js
  • actions/services/portalDirectService.js
  • actions/services/documentDirectService.js
  • tests/phase9/service-behaviour.test.cjs
• Re-run phase6/phase7/phase8/phase9 baseline tests and lint after rollback to confirm parity.

Phase 10 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Continue connected hardening slices on same branch
   • branch: TASK22019-phase-9-hardening
2. [x] Re-enable/standardize hash + param guard handling in 4 additional file retrieval handlers
   • pages/api/file/getawaitingsubmissionfromblob.js
   • pages/api/file/getprogressobjblob.js
   • pages/api/file/getbloblist.js
   • pages/api/file/getrepsblob.js
3. [x] Standardize negative-path behavior
   • added explicit early 400 for missing required query/hash values
   • standardized early 400 for hash mismatch
4. [x] Improve logging discipline in touched handlers
   • removed old commented debug traces
5. [x] Add focused Phase 10 tests
   • added tests/phase10/service-behaviour.test.cjs
   • includes negative-path tests for all 4 handlers
6. [x] Execute validation bundle
   • node tests/phase6/service-parity.test.cjs -> pass
   • node tests/phase6/service-behaviour.test.cjs -> pass (8/8)
   • node tests/phase7/service-behaviour.test.cjs -> pass (10/10)
   • node tests/phase8/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase9/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase10/service-behaviour.test.cjs -> pass (5/5)
   • npm run lint -> warnings only (no new lint errors)
7. [x] Execute manual HTTP negative-path matrix + valid-hash spot-check
   • missing hash across selected handlers -> 400
   • valid hash getbloblist spot-check -> 500 (downstream/local dependency)

Phase 10 rollback notes

• Revert these files to rollback the full hardening slice:
  • pages/api/file/getawaitingsubmissionfromblob.js
  • pages/api/file/getprogressobjblob.js
  • pages/api/file/getbloblist.js
  • pages/api/file/getrepsblob.js
  • tests/phase10/service-behaviour.test.cjs
• Re-run phase6/phase7/phase8/phase9/phase10 baseline tests and lint after rollback to confirm parity.

Phase 11 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Continue connected hardening slices on same branch
   • branch: TASK22019-phase-9-hardening
2. [x] Re-enable/standardize hash + param guard handling in additional sensitive handlers
   • pages/api/file/getbloblist.js
   • pages/api/file/deleteblob.js
   • pages/api/file/deleteawaitingsubmissionfromblob.js
3. [x] Standardize negative-path behavior
   • added explicit early 400 for missing required query/hash values
   • standardized early 400 for hash mismatch
4. [x] Improve logging discipline in touched handlers
   • removed old commented debug traces
5. [x] Add focused Phase 11 tests
   • added tests/phase11/service-behaviour.test.cjs
   • includes negative-path tests for selected handlers
6. [x] Execute validation bundle
   • node tests/phase6/service-parity.test.cjs -> pass
   • node tests/phase6/service-behaviour.test.cjs -> pass (8/8)
   • node tests/phase7/service-behaviour.test.cjs -> pass (10/10)
   • node tests/phase8/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase9/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase10/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase11/service-behaviour.test.cjs -> pass (4/4)
   • npm run lint -> warnings only (no new lint errors)
7. [x] Execute manual HTTP negative-path matrix + valid-hash spot-check
   • missing/invalid hash across selected handlers -> 400
   • valid hash getbloblist spot-check -> 500 (downstream/local dependency)

Phase 11 rollback notes

• Revert these files to rollback the full hardening slice:
  • pages/api/file/getbloblist.js
  • pages/api/file/deleteblob.js
  • pages/api/file/deleteawaitingsubmissionfromblob.js
  • tests/phase11/service-behaviour.test.cjs
• Re-run phase6/phase7/phase8/phase9/phase10/phase11 baseline tests and lint after rollback to confirm parity.

Phase 12 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Continue connected hardening slices on same branch
   • branch: TASK22019-phase-9-hardening
2. [x] Re-enable/standardize hash + param guard handling in additional sensitive handlers
   • pages/api/file/downloadblob.js
   • pages/api/file/getbloblistproxy.js
   • pages/api/file/getrepsblobproxy.js
   • pages/api/file/getawaitingsubmissionfromblobproxy.js
3. [x] Standardize negative-path behavior
   • added explicit early 400 for missing required query/hash values
   • standardized early 400 for hash mismatch in downloadblob
4. [x] Add focused Phase 12 tests
   • added tests/phase12/service-behaviour.test.cjs
   • includes negative-path tests for selected handlers
5. [x] Execute validation bundle
   • node tests/phase6/service-parity.test.cjs -> pass
   • node tests/phase6/service-behaviour.test.cjs -> pass (8/8)
   • node tests/phase7/service-behaviour.test.cjs -> pass (10/10)
   • node tests/phase8/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase9/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase10/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase11/service-behaviour.test.cjs -> pass (4/4)
   • node tests/phase12/service-behaviour.test.cjs -> pass (4/4)
   • npm run lint -> warnings only (no new lint errors)
6. [x] Execute manual HTTP negative-path matrix + valid-hash spot-check
   • missing/invalid inputs across selected handlers -> 400
   • valid hash downloadblob spot-check -> 500 (downstream/local dependency)

Phase 12 rollback notes

• Revert these files to rollback the full hardening slice:
  • pages/api/file/downloadblob.js
  • pages/api/file/getbloblistproxy.js
  • pages/api/file/getrepsblobproxy.js
  • pages/api/file/getawaitingsubmissionfromblobproxy.js
  • tests/phase12/service-behaviour.test.cjs
• Re-run phase6/phase7/phase8/phase9/phase10/phase11/phase12 baseline tests and lint after rollback to confirm parity.

Phase 13 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Continue connected hardening slices on same branch
   • branch: TASK22019-phase-9-hardening
2. [x] Re-enable/standardize hash + param guard handling in additional sensitive handlers
   • pages/api/file/deleteblobcase.js
   • pages/api/file/deleteblobrep.js
   • pages/api/file/createcaseinvolvement_api.js
   • pages/api/file/createrepinvolvement_api.js
3. [x] Standardize negative-path behavior
   • added explicit early 400 for missing required query/hash/body values
   • standardized early 400 for hash mismatch in delete handlers
4. [x] Improve logging discipline in touched handlers
   • removed noisy body/query logging in involvement handlers
5. [x] Add focused Phase 13 tests
   • added tests/phase13/service-behaviour.test.cjs
   • includes negative-path tests and valid-input mocked happy paths
6. [x] Execute validation bundle
   • node tests/phase6/service-parity.test.cjs -> pass
   • node tests/phase6/service-behaviour.test.cjs -> pass (8/8)
   • node tests/phase7/service-behaviour.test.cjs -> pass (10/10)
   • node tests/phase8/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase9/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase10/service-behaviour.test.cjs -> pass (5/5)
   • node tests/phase11/service-behaviour.test.cjs -> pass (4/4)
   • node tests/phase12/service-behaviour.test.cjs -> pass (4/4)
   • node tests/phase13/service-behaviour.test.cjs -> pass (7/7)
   • npm run lint -> warnings only (no new lint errors)
7. [x] Execute manual HTTP negative-path matrix + valid-hash spot-check
   • missing/invalid inputs across selected handlers -> 400
   • valid hash deleteblobcase spot-check -> 500 (downstream/local dependency)

Phase 13 rollback notes

• Revert these files to rollback the full hardening slice:
  • pages/api/file/deleteblobcase.js
  • pages/api/file/deleteblobrep.js
  • pages/api/file/createcaseinvolvement_api.js
  • pages/api/file/createrepinvolvement_api.js
  • tests/phase13/service-behaviour.test.cjs
• Re-run phase6/phase7/phase8/phase9/phase10/phase11/phase12/phase13 baseline tests and lint after rollback to confirm parity.

Phase 14 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Diagnose authenticated browser journey runtime error
   • traced to client-side hashAPIPath usage reading server-only HASHKEY
2. [x] Implement minimal reversible signing bridge
   • added pages/api/endpoint/gethash_api.js
   • session-gated with allow-listed API path prefixes
3. [x] Keep client/service contracts stable
   • updated documentDirectService and portalDirectService to request hash from signer endpoint
   • kept server-side fallback hashing only when env key exists
4. [x] Add focused phase-14 tests
   • added tests/phase14/service-behaviour.test.cjs
   • covers 400/401 negative paths and authenticated happy path
5. [x] Execute validation bundle
   • phase6–phase14 test set all pass
   • lint warnings only (pre-existing)

Phase 14 rollback notes

• Revert these files to rollback the fix slice:
  • pages/api/endpoint/gethash_api.js
  • actions/services/documentDirectService.js
  • actions/services/portalDirectService.js
  • tests/phase14/service-behaviour.test.cjs
• Re-run phase6–phase14 tests + lint after rollback.

Phase 14 closeout follow-up snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Expand signer usage to remaining browser-sensitive hashed call in account domain
   • actions/services/accountDirectService.js
   • getPortalLogin now requests hash from authenticated signer endpoint
2. [x] Extend signer allow-list minimally for required route
   • pages/api/endpoint/gethash_api.js
   • added /api/endpoint/getportallogin_api only
3. [x] Preserve and verify behavioural contract coverage
   • tests/phase7/service-behaviour.test.cjs updated for signer flow
   • tests/phase14/service-behaviour.test.cjs extended with allow-list path test
4. [x] Apply runtime-discovered contract alignment fixes (minimal/reversible)
   • pages/api/file/getrepsblob.js
     • removed unnecessary casefolderID requirement to match endpoint contract
   • components/elements/index.js
     • restored missing updateLinks import for Quill path
5. [x] Re-run required validation
   • phase6 parity + behaviour -> pass
   • phase7/8/9/10/11/12/13/14 behaviour -> pass
   • lint -> warnings only (pre-existing)
6. [x] Push branch for review continuity
   • TASK22019-phase-9-hardening pushed to origin

Phase 14 closeout follow-up rollback notes

• Revert 6094874 to remove portal-login signer migration and tests.
• Revert b8fa514 to remove getrepsblob contract-alignment + Quill import fix.
• Re-run phase6–phase14 tests and lint after rollback.

Phase 15 completion snapshot (2026-03-13)

Status key: [x] done, [ ] pending

1. [x] Create new branch from origin/SIPS-Development with required work item prefix
   • branch: TASK22028-phase15-hardening-slice
2. [x] Apply minimal consistency-only hardening in 4 additional sensitive handlers
   • pages/api/file/upload.js
   • pages/api/file/uploadsinglefile.js
   • pages/api/file/createappealcompletemessage_api.js
   • pages/api/file/setupcontainer.js
3. [x] Standardize negative-path behavior
   • explicit early 400 for missing/invalid hash in selected handlers
   • explicit missing required-input checks where route contract requires them
   • preserved response-shape contracts and function signatures
4. [x] Add focused Phase 15 tests
   • added tests/phase15/service-behaviour.test.cjs
   • includes negative-path tests for missing/invalid hash + required-input checks
   • includes one valid-hash mocked happy-path response-shape check
5. [x] Execute required validation bundle
   • phase6 parity + phase6–phase14 behaviour tests -> pass
   • phase15 behaviour tests -> pass
   • lint -> warnings only (pre-existing)
6. [x] Execute targeted manual checks
   • missing/invalid hash across selected handlers -> 400
   • missing required params where applicable -> 400
   • valid-hash setupcontainer spot-check -> 200

Phase 15 rollback notes

• Revert these files to rollback the full hardening slice:
  • pages/api/file/upload.js
  • pages/api/file/uploadsinglefile.js
  • pages/api/file/createappealcompletemessage_api.js
  • pages/api/file/setupcontainer.js
  • tests/phase15/service-behaviour.test.cjs
• Re-run phase6–phase15 baseline tests and lint after rollback to confirm parity.

Safe execution mode for migration chunks (required)

To reduce terminal hangs during bulk migration work, run refactor chunks in safe stepwise mode instead of long chained commands.

Required command pattern:

1. Read/inspect target files.
2. Apply edits only.
3. Verify with targeted grep for remaining broad imports.
4. Check git status.
5. Stage files.
6. Commit.
7. Re-run verification and then continue to the next chunk.

Rules:

• Do not combine edit + verify + add + commit + log in one long chained command.
• Keep each terminal call short and single-purpose.
• If a command is interrupted, re-check git status and resume from the next incomplete step.
• Preserve smallest viable diff and behavior parity.

Implementation status snapshot (2026-03-12)

• Phase 1 completed:
  • Extracted core helpers into actions/core/{env,logger,hash,token,headers}.js.
  • Moved wrapper functions into actions/services/legacyActionsService.js.
  • Reduced actions/index.js to compatibility barrel re-exports.
  • Added actions/clients/README.md scaffold for upcoming client extraction.
• Validation status:
  • npm run lint currently fails at framework/tooling option level (legacy ESLint options), not due to this refactor logic.
  • Manual test matrix is required next (search/case/myportal/auth/notify/file).

Implementation status snapshot (Phase 2 update — 2026-03-12)

• Phase 2 completed:
  • Added grouped service modules under actions/services/:
    • searchService.js
    • caseService.js
    • accountService.js
    • portalService.js
    • documentService.js
    • referenceDataService.js
    • notifyService.js
    • adminService.js
    • integrationService.js
  • Added actions/services/index.js barrel.
  • Updated actions/index.js to export from ./services and ./core/*.
  • Verified export parity: all legacyActionsService exports are represented by grouped service modules.
• Current compatibility model:
  • Consumers can continue importing from ../actions with unchanged function names/signatures.
  • legacyActionsService remains an internal compatibility implementation module until Phase 3 consumer migration.

Implementation status snapshot (Phase 3 update — 2026-03-12)

• Phase 3 started with targeted consumer migration to focused imports.
• Updated high-churn consumers:
  • components/case/summary.js
    • createWatchedCases, deleteWatchedCases, getWatchedCasesProxy, setCaseInvolvment -> actions/services/portalService
    • getLinkedCases -> actions/services/searchService
    • getPortalModuleDetailsProxy -> actions/services/caseService
  • pages/api/email/notify.js
    • consoleLogger -> actions/core/logger
    • getPreferredLanguage -> actions/services/accountService
• Updated selected endpoint handlers to core imports:
  • pages/api/endpoint/getwatchedcases_api.js
  • pages/api/endpoint/getadvancedsearchpaged_api.js
  • pages/api/endpoint/getpreferredlanguage_api.js
  • pages/api/endpoint/createcrmtask_api.js
• Compatibility remains preserved via actions/index.js barrel while migration proceeds incrementally.

Implementation status snapshot (Phase 4 update — 2026-03-12)

• Phase 4 started with targeted hardening helpers and sensitive-path adoption.
• Added actions/core/guards.js with:
  • isNonEmptyString
  • sanitizeString
  • escapeODataString
• Expanded actions/core/logger.js with redaction support:
  • redactSensitive
  • masking for likely email/token/secret patterns in logged content
• Updated actions/index.js compatibility barrel to export ./core/guards.
• Applied hardening in selected sensitive/high-churn handlers:
  • pages/api/email/notify.js
    • email input sanitization + required-field guard
    • redacted logging for outbound payload diagnostics
  • pages/api/endpoint/getpreferredlanguage_api.js
    • sanitized/validated emailAddress
    • OData string escaping for query construction
    • redacted query logging
  • pages/api/endpoint/createcrmtask_api.js
    • sanitized/validated request inputs for subject/email/body
    • centralized structured error logging via consoleLogger

Implementation status snapshot (Priority 1 execution pass — 2026-03-12)

• Completed another targeted consumer migration pass from broad actions barrel imports to focused service/core imports in these files:
  • components/admin/tabs/documents.js
  • components/admin/tabs/storage.js
  • components/admin/utils/serverside.js
  • components/case/documents.js
  • components/case/representation/representationComplete.js
  • components/case/representation/representationElements.js
  • components/elements/index.js
  • components/myportal/awaitingsubmissionfromblob.js
  • components/myportal/topthree.js
  • components/myportal/topthree_reps.js
  • components/utils/index.js
  • lib/myportal/loadMyPortalAppealPage.js
  • lib/newappeal/loadNewAppealPage.js
• Kept compatibility behavior via existing actions/index.js barrel.
• Validation note: npm run lint remains blocked by repository ESLint/Next option incompatibility (pre-existing tooling configuration).

Goal

Reduce coupling and regression risk by splitting actions/index.js into focused modules while preserving existing behavior and call signatures during migration.

Why this is first

actions/index.js is currently a high-risk hotspot: API wrappers, relay/hash helpers, token acquisition, logging, file helpers, and notification helpers are mixed in one module. This increases blast radius for every change.

Scope (planned)

• In scope:
  • Module extraction and internal architecture cleanup.
  • Backward-compatible export strategy.
  • Migration plan for consumers under components/**, pages/**, and pages/api/**.
• Out of scope (for this refactor phase):
  • Functional changes to business logic.
  • Contract changes to API handlers.
  • Dependency swaps.

Proposed target structure

actions/
  index.js                  # compatibility barrel (temporary)
  core/
    env.js                  # BASE_URL/API_ROOT/relay roots
    logger.js               # consoleLogger/conLog with redaction helpers
    hash.js                 # hashAPIPath/hashString/dehashString
    token.js                # getToken + token request config
    headers.js              # azureHeaders* helpers
  clients/
    relayClient.js          # signed relay calls + shared axios behavior
    endpointClient.js       # endpoint route wrappers
    fileClient.js           # file route wrappers
    notifyClient.js         # email/notify wrappers
  services/
    caseService.js
    searchService.js
    portalService.js
    accountService.js
    documentService.js

Notes:

• Keep actions/index.js as a façade initially to avoid breaking imports.
• Move internals first, then update call sites incrementally.

Migration strategy (phased)

Phase 1 — Safe extraction with no consumer changes

1. Create new modules under actions/core/** and actions/clients/**.
2. Move utility functions (hash, headers, token, logger, env helpers).
3. Re-export all existing functions from actions/index.js unchanged.
4. Verify parity with lint + smoke checks.

Phase 2 — Service grouping

1. Group route wrapper functions into service modules by domain (case/search/portal/account/document).
2. Keep identical function names/signatures.
3. Add thin unit tests for pure helpers first (hash, env, route builder helpers).

Phase 3 — Consumer migration

1. Replace broad imports from actions/index.js with targeted imports from new modules.
2. Migrate high-churn areas first:
   • components/breadcrumbs.js
   • components/case/summary.js
   • pages/api/email/notify.js
   • selected pages/api/endpoint/** handlers
3. Keep index barrel until migration completion.

Phase 4 — Harden + slim

1. Introduce typed/validated request helper boundaries (JS doc + runtime guard checks).
2. Remove dead exports and duplicate wrappers.
3. Finalize redacted logging policy in sensitive flows.

Backward compatibility rules

• Do not change public function names/signatures during Phases 1–2.
• Keep return shapes identical unless explicitly planned and validated.
• Preserve existing hash and relay behavior contract.
• Preserve EN/CY behavior where helper functions influence locale-sensitive flows.

Validation plan

• npm run lint
• Manual smoke paths:
  • search -> results -> case summary -> back nav
  • myportal viewall -> case summary -> breadcrumb return path
  • auth email sign-in flow
  • notify new case reference language selection path
  • file/document fetch paths touched by moved wrappers
• Negative-path checks:
  • invalid hash or malformed query for sensitive handlers
  • token acquisition failures and relay timeout handling

Regression tests and coverage plan (to add during implementation)

Test tooling recommendation

Current repo has no active automated test runner configured in package.json. For this refactor, introduce a minimal unit test setup (recommended: Jest) focused on pure logic first.

Suggested scripts:

• test: run all unit tests
• test:watch: local watch mode
• test:coverage: coverage output for CI and PR evidence

Minimum tests for Priority 1

1. actions/core/hash.js
   • deterministic hash for known input
   • query string handling (?hash= vs &hash=)
   • malformed/edge inputs
2. actions/core/headers.js
   • expected OData/auth headers produced for each helper
3. actions/core/token.js
   • token request config generation
   • success and error mapping behavior (mock axios)
4. actions/core/env.js
   • server vs browser base URL resolution
5. compatibility barrel (actions/index.js)
   • exports parity test to ensure existing function names remain available during migration

Integration-style safeguards (mocked external calls)

• Relay client request assembly test:
  • signed URL includes hash
  • token is attached
  • timeout/error behavior is consistent
• Notify client wrapper test:
  • language/template routing remains unchanged for PEDW-NEW-CASEREF path

Coverage targets for this refactor

• actions/core/**: >= 90% lines/functions
• actions/clients/**: >= 80% lines/functions
• Global coverage gate for this phase: >= 70% (new tests only; avoid blocking unrelated legacy code)

Regression gate in PR

Required evidence for each phase:

1. npm run lint
2. npm run test
3. npm run test:coverage (attach summary)
4. Manual smoke matrix from this plan (search/case/myportal/auth/notify/file)

Risks and mitigations

• Risk: import breakage due to broad existing usage.
  • Mitigation: keep compatibility barrel and migrate in small batches.
• Risk: hidden behavior differences from refactor-only moves.
  • Mitigation: freeze signatures + add helper tests + run route smoke matrix each phase.
• Risk: sensitive logging leakage while touching shared helpers.
  • Mitigation: centralize logger early and enforce redaction helper.

Definition of done (for this priority)

1. actions/index.js reduced to compatibility exports only (minimal logic).
2. Core helper modules and service modules exist and are used by migrated consumers.
3. Lint and manual validation matrix pass.
4. Memory docs updated (activeContext, progress, change-log).