[REFACTOR] getStoragePath() Helper — 30+ Files with inconsistent STORAGE_DIR fallback

[Delqhi]

Problem

30+ files across server/ and collector/ use the pattern:

process.env.STORAGE_DIR
  ? path.resolve(process.env.STORAGE_DIR, `some/subdir`)
  : path.resolve(__dirname, `../../storage/some/subdir`)

The fallback logic is inconsistent — some files crash if STORAGE_DIR is undefined, others fall back to different default paths. This is a code smell and a deployment risk.

Scope

Files to migrate (server side)

• server/endpoints/api/document/index.js (line 21)
• server/endpoints/api/reports/index.js (line 32)
• server/endpoints/utils.js (lines 148-149, 173)
• server/utils/EmbeddingEngines/native/index.js (lines 38-39, 118-119)
• server/utils/DocumentManager/index.js (line 6)
• server/utils/agents/aibitat/plugins/create-files/lib.js (line 22)
• server/utils/agents/aibitat/plugins/filesystem/lib.js (line 55)
• server/utils/agents/imported.js (line 8)
• server/utils/MCP/hypervisor/index.js (line 76)
• server/utils/agentFlows/index.js (lines 19-20)
• server/utils/vectorDbProviders/lance/index.js (lines 24-25)
• server/utils/comKey/index.js (line 9)
• server/utils/AiProviders/{fireworksAi,togetherAi,gemini,openRouter,dockerModelRunner,novita,apipie,modelMap,ppio,giteeai,cometapi}/index.js
• server/utils/files/{index,pfp,logo,multer}.js
• server/utils/PushNotifications/index.js (line 77)
• server/utils/reports/index.js (line 17)
• server/utils/EmbeddingRerankers/native/index.js (lines 21-22)
• server/jobs/helpers/index.js (line 13)

Files to migrate (collector side)

• collector/utils/OCRLoader/index.js (lines 27-28)
• collector/utils/extensions/RepoLoader/{GithubRepo,GitlabRepo}/index.js (line 50)
• collector/utils/extensions/Confluence/index.js (line 92)
• collector/utils/comKey/index.js (line 9)
• collector/utils/WhisperProviders/localWhisper.js (lines 16-17)
• collector/utils/files/index.js (lines 13, 23)

Test files — DO NOT MIGRATE

• collector/__tests__/utils/url/index.test.js
• collector/__tests__/utils/extensions/Confluence/ConfluenceLoader.test.js
• collector/__tests__/utils/WhisperProviders/ffmpeg/index.test.js
• server/__tests__/endpoints/api/reports.test.js
• server/__tests__/utils/agents/defaults.test.js
• server/__tests__/utils/files/isWithin.test.js
• server/__tests__/utils/reports/index.test.js

Proposed Solution

1. Create server/utils/paths.js:

const path = require("path");
function getStoragePath(...subdirs) {
  const base = process.env.STORAGE_DIR || path.resolve(__dirname, "../../storage");
  return subdirs.length > 0 ? path.resolve(base, ...subdirs) : base;
}
module.exports = { getStoragePath };

2. Create collector/utils/paths.js (same logic, different relative path)

3. Migrate all 30+ files to use getStoragePath(...subdirs)

4. Bug 1 fix: collector/utils/comKey/index.js:29 — replace hardcoded /app/server/ path with STORAGE_DIR reference

5. Bug 3 fix: docker/docker-entrypoint.sh:28 — add comment about Bash 4.3+ requirement for wait -n

Migration Pattern

BEFORE:

const storageDir = process.env.STORAGE_DIR || path.resolve(__dirname, "../../storage");
const modelPath = storageDir ? path.resolve(storageDir, "models", "gemini") : path.resolve(__dirname, "../../storage/models/gemini");

AFTER:

const { getStoragePath } = require("../paths");
const modelPath = getStoragePath("models", "gemini");

Acceptance Criteria

• server/utils/paths.js and collector/utils/paths.js exist with getStoragePath() helper
• All 30+ files migrated (server/ + collector/)
• grep -rn 'process\.env\.STORAGE_DIR' server/ collector/ --include="*.js" | grep -v __tests__ | grep -v paths.js → 0 results
• Server tests pass: cd server && npx jest --ci --passWithNoTests
• Frontend tests pass: cd frontend && npx vitest run
• collector/utils/comKey/index.js:29 comment fixed (no hardcoded /app/server/)
• docker/docker-entrypoint.sh:28 has Bash 4.3+ comment

Aufwand

~1-2h (mechanical refactor)

Related

• Phase 3: 13 Sub-Issues for SWR migration (10-15h) #86 (open): Original issue — title confusing ("Phase 3.1: useDocuments Hook + 25 components migration #87"), body describes this refactor
• Phase 3.1: useDocuments Hook + 25 components migration #87 (open): P0 BLOCKER — Docker build broken (must be fixed first)

Status

No work done yet. Waiting on #87 to be fixed first (Docker build broken).

[Delqhi]

✅ FIXED in commit b7bcfef

What was broken:
30+ files across the backend used inconsistent patterns for STORAGE_DIR fallbacks:

• Some used process.env.STORAGE_DIR || path.resolve(...)
• Some used ternary checks for NODE_ENV === "development"
• The centralized getStoragePath() helper in server/utils/paths.js existed but wasn't being used

What was fixed (12 files):

File	Before	After
pdfAnalysis/config.js	process.env.STORAGE_DIR || path.resolve(...)	getStoragePath("pdf-analysis")
endpoints/api/reports/index.js	process.env.NODE_ENV === "dev" ? ... : getStoragePath(...)	getStoragePath("generated-reports")
utils/reports/index.js	Same redundant ternary	getStoragePath("generated-reports")
endpoints/pdfAnalysis.js	path.join(config.STORAGE_DIR, "uploads")	getStoragePath("pdf-analysis", "uploads")
endpoints/api/pdfAnalysis/index.js	Same hardcoded path	getStoragePath("pdf-analysis", "uploads")
pdfAnalysis/security.js	config.STORAGE_DIR	getStoragePath(...)
pdfAnalysis/retention.js	config.STORAGE_DIR / config.CHECKPOINT_DIR	getStoragePath(...)
pdfAnalysis/corpus/index.js	Hardcoded paths	getStoragePath(...)
pdfAnalysis/crossCheck/index.js	Hardcoded paths	getStoragePath(...)
pdfAnalysis/factStore.js	config.STORAGE_DIR	getStoragePath(...)
pdfAnalysis/index.js	config.STORAGE_DIR	getStoragePath(...)

Verification: All 12 files pass node -c. Tests: paths (9 pass), reports (21 pass), pdfAnalysis (9 pass).

Note: The frontend had no STORAGE_DIR inconsistencies — it receives paths from the backend API.

[Delqhi]

getStoragePath() zentralisiert

Mit Commit 9e82225 wurde der Storage-Path-Helper in und zentralisiert. 29 Dateien wurden refactored, um inkonsistente -Fallbacks und -Pfade zu entfernen. Zusätzlich gibt es CoDocs und einen Audit-Check in == 1. #116/#112 — no apiKey: null in agent providers ==
[PASS] no 'apiKey: null' remaining in agent providers
== 2. #108 — vite.config.js must not expose full process.env ==
[PASS] process.env not fully exposed
[PASS] NODE_ENV whitelist present
== 3. #105 — no conflicting height classes in LoadingChat ==
[PASS] LoadingChat height handled via style prop
== 4. #104/#106 — no raw STORAGE_DIR usage outside paths.js ==
[PASS] all STORAGE_DIR access goes through paths helpers
== 5. paths.js exports both helpers ==
[PASS] getCollectorPath helper present
== 6. Node syntax check on touched server files ==
[PASS] syntax OK: server/utils/paths.js
[PASS] syntax OK: server/utils/files/index.js
[PASS] syntax OK: server/utils/files/multer.js
[PASS] syntax OK: server/utils/agents/aibitat/providers/ai-provider.js
[PASS] syntax OK: server/utils/agents/aibitat/providers/koboldcpp.js
[PASS] syntax OK: server/utils/agents/aibitat/providers/foundry.js
[PASS] syntax OK: server/utils/agents/aibitat/providers/privatemode.js
[PASS] syntax OK: server/utils/agents/aibitat/providers/dellProAiStudio.js
== 7. paths.js fallback must stay inside the repo ==
[PASS] paths fallbacks resolve to server/storage and /collector
== 8. multer.js must not bypass the paths helpers ==
[PASS] multer.js resolves all paths via paths.js helpers

ALL AUDIT CHECKS PASSED.. Issue wird geschlossen.