@vfarcic/dot-ai 1.22.0 → 1.23.0

package/dist/core/user-prompts-loader.js

@@ -46,6 +46,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPromptsOverrideError = exports.IngestedSourceNotFoundError = exports.PromptsSourceValidationError = exports.MAX_INGESTED_SOURCES = void 0;
+exports.sanitizeIngestFileMode = sanitizeIngestFileMode;
+exports.ingestPromptsSource = ingestPromptsSource;
 exports.getUserPromptsConfig = getUserPromptsConfig;
 exports.computePromptsSource = computePromptsSource;
 exports.getUserPromptsConfigFromOverride = getUserPromptsConfigFromOverride;
@@ -54,6 +57,8 @@ exports.sanitizeUrlForLogging = sanitizeUrlForLogging;
 exports.scrubSourceUrl = scrubSourceUrl;
 exports.loadUserPrompts = loadUserPrompts;
 exports.clearUserPromptsCache = clearUserPromptsCache;
+exports.clearIngestedPromptsSources = clearIngestedPromptsSources;
+exports.getIngestedPromptsSources = getIngestedPromptsSources;
 exports.getUserPromptsCacheState = getUserPromptsCacheState;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -63,6 +68,393 @@ const git_utils_1 = require("./git-utils");
 const prompts_1 = require("../tools/prompts");
 // In-memory cache state (persists across requests within same process)
 let cacheState = null;
+const ingestedSources = new Map();
+/**
+ * PRD #647 D5 — upload-input hardening caps. These are the EXACT values the
+ * frozen contract (.dot-agent-deck/647-contract.md) and the integration suite
+ * pin, chosen to trip the app-level cap before the ~1 MiB nginx ingress limit.
+ */
+const MAX_INGEST_FILES = 100;
+const MAX_INGEST_TOTAL_BYTES = 256 * 1024; // 256 KiB
+/**
+ * PRD #647 F5 / D2-M4 — max number of distinct ingested sources held in memory.
+ * The cache is push-populated by authenticated uploads, so without a bound it
+ * grows unbounded across distinct identifiers (a memory-growth vector). This
+ * is a simple access-ordered LRU cap: on overflow the least-recently-used entry
+ * (oldest `uploadedAt`, refreshed on every successful render) is evicted, and a
+ * later `?source=` render of an evicted identifier hits the existing D2
+ * render-miss guidance (re-upload required). Correctness over tuning per the
+ * frozen contract — 50 distinct sources is ample for the CLI's per-host usage.
+ */
+exports.MAX_INGESTED_SOURCES = 50;
+/**
+ * Thrown by ingestPromptsSource on a malformed/unsafe upload so the REST handler
+ * can map it to a 400 (vs. a 500 for unexpected IO failures).
+ */
+class PromptsSourceValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptsSourceValidationError';
+    }
+}
+exports.PromptsSourceValidationError = PromptsSourceValidationError;
+/**
+ * PRD #647 D2 — thrown when a render names an ingested `?source=<identifier>`
+ * that is not (or no longer) cached. It carries actionable re-upload guidance
+ * and is mapped to a 400 VALIDATION_ERROR by the REST handler. Deliberately
+ * distinct from the generic "Prompt not found" so the caller knows to re-upload
+ * the source rather than wonder why a known skill name is missing — and it never
+ * triggers (nor mentions) a git clone, since ingested identifiers are never
+ * cloned.
+ */
+class IngestedSourceNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IngestedSourceNotFoundError';
+    }
+}
+exports.IngestedSourceNotFoundError = IngestedSourceNotFoundError;
+/**
+ * PRD #647 D5 — sanitize an untrusted POSIX `mode` string from an uploaded
+ * manifest into a safe numeric file mode. Strips the special bits
+ * (setuid 04000, setgid 02000, sticky 01000) so an uploaded skill file can never
+ * carry an exec-escalation surprise, and keeps only the standard rwx permission
+ * bits (07777 → 0777). Anything unparseable falls back to a sane 0644.
+ */
+function sanitizeIngestFileMode(mode) {
+    const DEFAULT_MODE = 0o644;
+    if (typeof mode !== 'string' || mode.trim() === '') {
+        return DEFAULT_MODE;
+    }
+    // Manifests send octal strings (e.g. "0644", "755"); parse base 8.
+    const parsed = parseInt(mode.trim(), 8);
+    if (Number.isNaN(parsed) || parsed < 0) {
+        return DEFAULT_MODE;
+    }
+    // Mask off setuid/setgid/sticky and any bits above the 0777 permission range.
+    return parsed & 0o777;
+}
+/**
+ * PRD #647 C5 (CodeRabbit) — strict canonical-base64 matcher. `Buffer.from(s,
+ * 'base64')` silently DROPS any out-of-alphabet character and tolerates missing
+ * padding, so a malformed `content` would otherwise decode to corrupt bytes and
+ * be cached. The CLI always uploads canonical, padded standard base64
+ * (Buffer#toString('base64')), so we require exactly that: only the standard
+ * alphabet (A–Z a–z 0–9 + /), `=` padding allowed only at the end, and a length
+ * that is a multiple of 4. The empty string (an empty file) is accepted.
+ */
+const CANONICAL_BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+function isCanonicalBase64(content) {
+    return content.length % 4 === 0 && CANONICAL_BASE64_RE.test(content);
+}
+/**
+ * Root directory holding decoded ingested sources, a sibling of the git-clone
+ * cache directory so both live under the same writable tmp space.
+ */
+function getIngestedCacheRoot() {
+    return path.join(path.dirname(getCacheDirectory()), 'ingested-prompts');
+}
+/**
+ * PRD #647 F6 — create a fresh, unpredictable 0700 staging directory under the
+ * ingested-cache root for an in-progress upload.
+ *
+ * Decoded files are written here FIRST and only promoted into the predictable
+ * per-identifier slot once every file is on disk (see F3 atomic re-ingest).
+ * Because the name is CSPRNG-random (crypto.randomUUID via mkdtempSync) and the
+ * directory is 0700, a local attacker can't pre-plant a symlink for the
+ * writeFileSync calls to follow (TOCTOU) — the same hardening the token-bearing
+ * clone path uses in createIsolatedCloneRoot.
+ */
+function createIngestedStagingDir() {
+    const root = getIngestedCacheRoot();
+    fs.mkdirSync(root, { recursive: true });
+    const dir = fs.mkdtempSync(path.join(root, `staging-${crypto.randomUUID()}-`));
+    try {
+        fs.chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best-effort hardening (mkdtempSync already creates with 0700) */
+    }
+    return dir;
+}
+/**
+ * PRD #647 F5 — enforce the LRU cap on the ingested-source registry. Evicts the
+ * least-recently-used entries (oldest `uploadedAt`) until the registry is within
+ * MAX_INGESTED_SOURCES, removing each evicted entry's on-disk directory too so
+ * memory AND disk stay bounded. An evicted identifier's next render falls into
+ * the D2 render-miss path (the registry entry is gone), instructing the caller
+ * to re-upload — it is never silently cloned.
+ */
+function evictIngestedIfNeeded(logger) {
+    while (ingestedSources.size > exports.MAX_INGESTED_SOURCES) {
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of ingestedSources) {
+            if (entry.uploadedAt < oldestTime) {
+                oldestTime = entry.uploadedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey === undefined)
+            break;
+        const evicted = ingestedSources.get(oldestKey);
+        ingestedSources.delete(oldestKey);
+        if (evicted) {
+            try {
+                fs.rmSync(evicted.localPath, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort disk cleanup; the registry entry is already gone */
+            }
+            logger.debug('Evicted ingested prompts source (LRU cap reached)', {
+                source: evicted.source,
+            });
+        }
+    }
+}
+/**
+ * PRD #647 M2/M4/D5 — validate, base64-decode, harden, and cache an uploaded
+ * skill source.
+ *
+ * The decoded files are written to a fresh 0700 staging directory, then
+ * atomically promoted into the per-identifier slot (a hash of the identifier)
+ * and registered in the in-memory ingested cache so the existing render path
+ * (loadUserPrompts → loadPromptsFromDir) resolves them with no git operation.
+ * The atomic promote (F3) means a failed/invalid re-upload never destroys the
+ * prior cached entry.
+ *
+ * Hardening, all applied BEFORE the prior slot is touched so a rejected upload
+ * is never partially cached:
+ *   - D3 dedup: an identical `contentHash` already cached for this identifier
+ *     short-circuits with status 'unchanged' — nothing is re-decoded or rewritten.
+ *   - D5 file-count cap: more than MAX_INGEST_FILES files is rejected up front.
+ *   - D5 total-size cap: summed DECODED bytes over MAX_INGEST_TOTAL_BYTES is rejected.
+ *   - D5 zip-slip: every file path goes through sanitizeRelativePath (reused
+ *     from git-utils) to reject traversal/absolute paths.
+ *   - F3 NUL byte: a `\0` in a file path is rejected with a 400 BEFORE any fs
+ *     call (sanitizeRelativePath does not catch it).
+ *   - D5 mode bits: each file's POSIX `mode` is sanitized (setuid/setgid/sticky
+ *     stripped) via sanitizeIngestFileMode before the file is written.
+ */
+function ingestPromptsSource(input, logger) {
+    // Identifier (cache key) must be a non-empty string.
+    if (typeof input.source !== 'string' || input.source.trim() === '') {
+        throw new PromptsSourceValidationError('source is required and must be a non-empty string');
+    }
+    const identifier = input.source.trim();
+    const contentHash = typeof input.contentHash === 'string' ? input.contentHash : undefined;
+    // PRD #647 D3 — content-hash dedup. If the caller sent a contentHash that is
+    // already cached for this identifier, the upload is byte-for-byte unchanged:
+    // short-circuit WITHOUT re-decoding or rewriting any files and report the
+    // cached file count. A different or absent hash falls through to a normal
+    // (re)ingest below.
+    if (contentHash) {
+        const cached = ingestedSources.get(identifier);
+        if (cached && cached.contentHash === contentHash) {
+            logger.info('Ingested prompts source unchanged (dedup short-circuit)', {
+                source: cached.source,
+                fileCount: cached.fileCount,
+            });
+            return {
+                source: cached.source,
+                contentHash,
+                fileCount: cached.fileCount,
+                status: 'unchanged',
+            };
+        }
+    }
+    // Manifest must carry at least one file.
+    if (!Array.isArray(input.files) || input.files.length === 0) {
+        throw new PromptsSourceValidationError('files is required and must be a non-empty array');
+    }
+    // PRD #647 D5 — file-count cap, enforced before any decode/write.
+    if (input.files.length > MAX_INGEST_FILES) {
+        throw new PromptsSourceValidationError(`Too many files: ${input.files.length} exceeds the limit of ${MAX_INGEST_FILES}`);
+    }
+    // Decode + path-validate EVERY file (and tally decoded bytes) before writing.
+    const decoded = [];
+    let totalBytes = 0;
+    for (const raw of input.files) {
+        if (!raw || typeof raw !== 'object') {
+            throw new PromptsSourceValidationError('each file must be an object with a path and base64 content');
+        }
+        const file = raw;
+        if (typeof file.path !== 'string' || file.path.trim() === '') {
+            throw new PromptsSourceValidationError('each file must have a non-empty string path');
+        }
+        if (typeof file.content !== 'string') {
+            throw new PromptsSourceValidationError(`file content must be a base64-encoded string: ${file.path}`);
+        }
+        // PRD #647 F3 — reject a NUL byte BEFORE any fs call. git-utils'
+        // sanitizeRelativePath does not catch `\0`, so without this an embedded NUL
+        // would slip through to fs.mkdirSync/writeFileSync and throw a raw
+        // TypeError → a generic 500 plus a partial write. Map it to a clean 400
+        // here, up front, so a rejected upload never touches disk. (Backslashes are
+        // left as ordinary POSIX path characters — they cannot escape the root —
+        // keeping parity with the mock's sanitizeRelativePath.)
+        if (file.path.includes('\0')) {
+            throw new PromptsSourceValidationError(`Invalid file path "${file.path}": contains null byte`);
+        }
+        let relPath;
+        try {
+            // Reuse the folder-write traversal/zip-slip guard.
+            relPath = (0, git_utils_1.sanitizeRelativePath)(file.path);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'invalid path';
+            throw new PromptsSourceValidationError(`Invalid file path "${file.path}": ${message}`);
+        }
+        // PRD #647 C5 — reject malformed base64 with a 400 BEFORE decoding, so a
+        // corrupt upload is never silently decoded (Buffer.from drops bad chars)
+        // and cached. Checked after the path guards so a rejected upload never
+        // touches disk.
+        if (!isCanonicalBase64(file.content)) {
+            throw new PromptsSourceValidationError(`Invalid base64 content for file "${file.path}"`);
+        }
+        const bytes = Buffer.from(file.content, 'base64');
+        totalBytes += bytes.length;
+        // PRD #647 D5 — total decoded payload cap, checked before any write so an
+        // oversized manifest is never partially cached.
+        if (totalBytes > MAX_INGEST_TOTAL_BYTES) {
+            throw new PromptsSourceValidationError(`Total decoded payload exceeds the limit of ${MAX_INGEST_TOTAL_BYTES} bytes`);
+        }
+        decoded.push({
+            relPath,
+            bytes,
+            // PRD #647 D5 — sanitize the untrusted mode (strip setuid/setgid/sticky).
+            mode: sanitizeIngestFileMode(file.mode),
+        });
+    }
+    // PRD #647 F3 — atomic re-ingest. Each identifier maps to a predictable
+    // per-identifier slot keyed by its hash, but we never write INTO that slot
+    // directly: write the decoded files into a fresh, unpredictable 0700 staging
+    // directory FIRST, then promote it into place only after every file is on
+    // disk. This guarantees a write-time failure (the NUL byte rejected above,
+    // EISDIR, disk full, …) NEVER destroys the previously-cached entry — the old
+    // slot is removed only on the success path, and the in-memory registry is
+    // updated last.
+    const finalDir = path.join(getIngestedCacheRoot(), crypto.createHash('sha256').update(identifier).digest('hex'));
+    const stagingDir = createIngestedStagingDir();
+    // PRD #647 N3 — count DISTINCT written paths: two manifest entries that
+    // sanitize to the same path collapse to one file on disk, so fileCount must
+    // not double-count them.
+    const writtenPaths = new Set();
+    // PRD #647 F3 (CodeRabbit C1) — failure-ATOMIC promote. The earlier version
+    // `rmSync(finalDir)`'d the prior slot BEFORE the rename, so a rename failure
+    // destroyed the last known-good entry (the map still pointed at finalDir).
+    // Instead: move the old slot aside to an unpredictable backup, rename staging
+    // into place, then delete the backup. If the promote throws, the backup is
+    // moved back so the prior cached entry is always recoverable. rename does not
+    // follow a symlink at the source or target, so a pre-planted finalDir symlink
+    // is moved/replaced, not written through.
+    const backupDir = `${finalDir}.bak-${crypto.randomUUID()}`;
+    let hadPrevious = false;
+    try {
+        for (const { relPath, bytes, mode } of decoded) {
+            const fullPath = path.join(stagingDir, relPath);
+            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+            fs.writeFileSync(fullPath, bytes, { mode });
+            writtenPaths.add(relPath);
+        }
+        // Move any prior slot aside FIRST (so it can be restored on failure), then
+        // promote the fully-written staging dir into place.
+        if (fs.existsSync(finalDir)) {
+            fs.renameSync(finalDir, backupDir);
+            hadPrevious = true;
+        }
+        fs.renameSync(stagingDir, finalDir);
+    }
+    catch (error) {
+        // Roll back the partial staging dir; never leave it behind.
+        try {
+            fs.rmSync(stagingDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort cleanup of the abandoned staging dir */
+        }
+        // Restore the prior cached entry if it was moved aside but the promote
+        // never completed, so a failed re-upload truly never destroys it.
+        if (hadPrevious && fs.existsSync(backupDir) && !fs.existsSync(finalDir)) {
+            try {
+                fs.renameSync(backupDir, finalDir);
+            }
+            catch {
+                /* best-effort restore; backup remains on disk for manual recovery */
+            }
+        }
+        throw error;
+    }
+    // Promote succeeded — discard the prior good copy. Best-effort: a cleanup
+    // failure here must NOT fail an already-successful re-ingest (the new content
+    // is in place), at worst leaving a stale backup dir for the tmp sweep.
+    if (hadPrevious) {
+        try {
+            fs.rmSync(backupDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort cleanup of the superseded prior copy */
+        }
+    }
+    const fileCount = writtenPaths.size;
+    const scrubbedSource = scrubSourceUrl(identifier);
+    // PRD #647 F5 — re-insert so a re-upload counts as most-recently-used in the
+    // access-ordered LRU, then evict if the registry now exceeds the cap.
+    ingestedSources.delete(identifier);
+    ingestedSources.set(identifier, {
+        identifier,
+        source: scrubbedSource,
+        contentHash,
+        localPath: finalDir,
+        fileCount,
+        uploadedAt: Date.now(),
+    });
+    evictIngestedIfNeeded(logger);
+    logger.info('Ingested prompts source', {
+        source: scrubbedSource,
+        fileCount,
+    });
+    return {
+        source: scrubbedSource,
+        contentHash,
+        fileCount,
+        status: 'ingested',
+    };
+}
+/**
+ * Load prompts from a previously-ingested source (PRD #647 M3 + D2).
+ *
+ * Resolves the identifier from the in-memory ingested cache and reads the
+ * decoded upload directly — NO git operation. A miss (evicted/never-uploaded)
+ * throws IngestedSourceNotFoundError with re-upload guidance rather than
+ * silently falling back to a clone (D2: ingested identifiers are never cloned).
+ * The thrown message deliberately avoids the generic "Prompt not found" wording
+ * AND any git/clone/scheme vocabulary so the caller learns to re-upload and the
+ * "no clone attempted" guarantee is observable.
+ *
+ * Note the distinction the contract requires: a MISSING identifier (no cache
+ * entry) yields this guidance, whereas a CACHED identifier that simply does not
+ * contain the requested skill name returns the loaded prompts and lets the
+ * caller surface the normal "Prompt not found".
+ */
+function loadIngestedPrompts(identifier, logger) {
+    const entry = ingestedSources.get(identifier);
+    if (!entry || !fs.existsSync(entry.localPath)) {
+        const scrubbed = scrubSourceUrl(identifier);
+        logger.warn('Ingested prompts source not found; (re)upload required', {
+            source: scrubbed,
+        });
+        throw new IngestedSourceNotFoundError(`Ingested source not found: ${scrubbed}. (Re)upload it via POST /api/v1/prompts/sources before rendering.`);
+    }
+    // PRD #647 F5 — mark this entry most-recently-used so a frequently-rendered
+    // source survives the LRU eviction in evictIngestedIfNeeded.
+    entry.uploadedAt = Date.now();
+    const prompts = loadPromptsFromDir(entry.localPath, logger);
+    logger.info('Loaded user prompts from ingested source', {
+        total: prompts.length,
+        source: entry.source,
+    });
+    return prompts;
+}
 /**
  * Read user prompts configuration from environment variables
  * Returns null if DOT_AI_USER_PROMPTS_REPO is not set
@@ -525,14 +917,112 @@ function loadSkillFolder(dirPath, dirName, logger) {
     }
     return prompt;
 }
+/**
+ * Read flat `.md` prompt files and skill folders (directories with SKILL.md)
+ * from a prompts directory into Prompt objects.
+ *
+ * Shared by the git-clone loader path and the PRD #647 ingested (uploaded)
+ * source path so both resolve through ONE identical loader — the only
+ * difference between a `?repo=` clone and an uploaded `?source=` is how the
+ * directory was populated. The caller is responsible for ensuring the directory
+ * exists.
+ */
+function loadPromptsFromDir(promptsDir, logger) {
+    const entries = fs.readdirSync(promptsDir, { withFileTypes: true });
+    const prompts = [];
+    const loadedNames = new Set();
+    // 1. Load flat .md files (existing behavior)
+    const mdFiles = entries.filter(e => e.isFile() && e.name.endsWith('.md'));
+    for (const entry of mdFiles) {
+        try {
+            const filePath = path.join(promptsDir, entry.name);
+            const prompt = (0, prompts_1.loadPromptFile)(filePath, 'user');
+            prompts.push(prompt);
+            loadedNames.add(prompt.name);
+            logger.debug('Loaded user prompt', {
+                name: prompt.name,
+                file: entry.name,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.warn('Failed to load user prompt file, skipping', {
+                file: entry.name,
+                error: errorMessage,
+            });
+        }
+    }
+    // 2. Load skill folders (directories containing SKILL.md)
+    const directories = entries.filter(e => e.isDirectory() && !e.name.startsWith('.'));
+    for (const dir of directories) {
+        try {
+            const dirPath = path.join(promptsDir, dir.name);
+            const prompt = loadSkillFolder(dirPath, dir.name, logger);
+            if (prompt) {
+                if (loadedNames.has(prompt.name)) {
+                    logger.warn('Skill folder name collision with existing prompt, skipping', {
+                        name: prompt.name,
+                        dir: dir.name,
+                    });
+                    continue;
+                }
+                prompts.push(prompt);
+                loadedNames.add(prompt.name);
+                logger.debug('Loaded user skill folder', {
+                    name: prompt.name,
+                    dir: dir.name,
+                    filesCount: prompt.files?.length ?? 0,
+                });
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.warn('Failed to load skill folder, skipping', {
+                dir: dir.name,
+                error: errorMessage,
+            });
+        }
+    }
+    return prompts;
+}
+/**
+ * Raised when a PER-REQUEST prompts-repo override (PRD #581/#621) fails to load —
+ * e.g. the clone is rejected (missing/wrong forwarded credential) or the source is
+ * unreachable. An env-var-configured repo failure falls back to built-in prompts,
+ * but an override is an explicit caller request, so its failure must surface as an
+ * error instead of silently returning fewer skills ("fail open" — issue #575).
+ *
+ * The `message` is already credential-scrubbed by the thrower, so callers may
+ * surface it to clients directly.
+ */
+class UserPromptsOverrideError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UserPromptsOverrideError';
+    }
+}
+exports.UserPromptsOverrideError = UserPromptsOverrideError;
 /**
  * Load user prompts from a git repository.
  *
  * When `override` is supplied, fetches from that repository for this call only,
  * ignoring DOT_AI_USER_PROMPTS_REPO env vars. Otherwise, uses env-var configuration.
- * Returns empty array if not configured or on error.
+ *
+ * Returns an empty array when not configured, or when an ENV-VAR-configured repo
+ * fails to load (graceful fallback to built-in prompts). When a per-request
+ * `override` fails to load, throws {@link UserPromptsOverrideError} instead — the
+ * caller asked for that specific source, so the failure must not be swallowed.
  */
 async function loadUserPrompts(logger, forceRefresh = false, override) {
+    // PRD #647 D1/M3: an ingested-source override resolves from the in-memory
+    // uploaded-source cache and is NEVER cloned. Short-circuit BEFORE
+    // getUserPromptsConfigFromOverride, which would reject a non-http identifier
+    // such as `local:<label>`. The render handler only sets this when the request
+    // carries an explicit `?source=` signal, so the env-var and `?repo=` clone
+    // paths below are untouched.
+    if (override?.ingestedSource) {
+        return loadIngestedPrompts(override.ingestedSource, logger);
+    }
     let config;
     try {
         // Override validation can throw on bad scheme / traversal / branch — keep
@@ -545,6 +1035,12 @@ async function loadUserPrompts(logger, forceRefresh = false, override) {
     catch (error) {
         const rawMessage = error instanceof Error ? error.message : 'Unknown error';
         const safeMessage = (0, git_utils_1.scrubCredentials)(rawMessage);
+        // A per-request override that fails validation is an explicit caller request
+        // gone wrong — surface it (issue #575). Env-var config failures fall back.
+        if (override) {
+            logger.error('Per-request prompts override is invalid', new Error(safeMessage));
+            throw new UserPromptsOverrideError(safeMessage);
+        }
         logger.error('Failed to load user prompts, falling back to built-in only', new Error(safeMessage));
         return [];
     }
@@ -569,62 +1065,8 @@ async function loadUserPrompts(logger, forceRefresh = false, override) {
             });
             return [];
         }
-        // Load flat .md files and skill folders from the prompts directory
-        const entries = fs.readdirSync(promptsDir, { withFileTypes: true });
-        const prompts = [];
-        const loadedNames = new Set();
-        // 1. Load flat .md files (existing behavior)
-        const mdFiles = entries.filter(e => e.isFile() && e.name.endsWith('.md'));
-        for (const entry of mdFiles) {
-            try {
-                const filePath = path.join(promptsDir, entry.name);
-                const prompt = (0, prompts_1.loadPromptFile)(filePath, 'user');
-                prompts.push(prompt);
-                loadedNames.add(prompt.name);
-                logger.debug('Loaded user prompt', {
-                    name: prompt.name,
-                    file: entry.name,
-                });
-            }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-                logger.warn('Failed to load user prompt file, skipping', {
-                    file: entry.name,
-                    error: errorMessage,
-                });
-            }
-        }
-        // 2. Load skill folders (directories containing SKILL.md)
-        const directories = entries.filter(e => e.isDirectory() && !e.name.startsWith('.'));
-        for (const dir of directories) {
-            try {
-                const dirPath = path.join(promptsDir, dir.name);
-                const prompt = loadSkillFolder(dirPath, dir.name, logger);
-                if (prompt) {
-                    if (loadedNames.has(prompt.name)) {
-                        logger.warn('Skill folder name collision with existing prompt, skipping', {
-                            name: prompt.name,
-                            dir: dir.name,
-                        });
-                        continue;
-                    }
-                    prompts.push(prompt);
-                    loadedNames.add(prompt.name);
-                    logger.debug('Loaded user skill folder', {
-                        name: prompt.name,
-                        dir: dir.name,
-                        filesCount: prompt.files?.length ?? 0,
-                    });
-                }
-            }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-                logger.warn('Failed to load skill folder, skipping', {
-                    dir: dir.name,
-                    error: errorMessage,
-                });
-            }
-        }
+        // Load flat .md files and skill folders from the prompts directory.
+        const prompts = loadPromptsFromDir(promptsDir, logger);
         logger.info('Loaded user prompts from repository', {
             total: prompts.length,
             url: sanitizeUrlForLogging(config.repoUrl),
@@ -638,6 +1080,14 @@ async function loadUserPrompts(logger, forceRefresh = false, override) {
         const safeMessage = (0, git_utils_1.scrubCredentials)(config.gitToken
             ? rawMessage.replaceAll(config.gitToken, '***')
             : rawMessage);
+        // A per-request override clone failure (bad/missing forwarded credential,
+        // unreachable host, missing branch/subdir) must NOT silently fall back to
+        // built-in prompts — the caller explicitly requested this source, so surface
+        // the failure (issue #575). Env-var-configured repo failures still fall back.
+        if (override) {
+            logger.error('Failed to load per-request prompts override', new Error(safeMessage));
+            throw new UserPromptsOverrideError(safeMessage);
+        }
         logger.error('Failed to load user prompts, falling back to built-in only', new Error(safeMessage));
         return [];
     }
@@ -667,6 +1117,21 @@ async function loadUserPrompts(logger, forceRefresh = false, override) {
 function clearUserPromptsCache() {
     cacheState = null;
 }
+/**
+ * Clear the ingested-source cache (PRD #647, useful for testing).
+ * Only drops the in-memory registry; on-disk directories are left to be
+ * overwritten by the next upload or cleaned with the tmp directory.
+ */
+function clearIngestedPromptsSources() {
+    ingestedSources.clear();
+}
+/**
+ * Inspect the ingested-source cache (PRD #647, for testing/debugging).
+ * Returns the scrubbed identifiers currently cached.
+ */
+function getIngestedPromptsSources() {
+    return [...ingestedSources.values()].map(entry => entry.source);
+}
 /**
  * Get current cache state (for testing/debugging)
  */

package/dist/interfaces/mcp.d.ts

@@ -73,7 +73,29 @@ export declare class MCPServer {
     private generateRequestId;
     start(): Promise<void>;
     private startHttpTransport;
+    /**
+     * Buffer and JSON-parse the request body.
+     *
+     * PRD #647 F1: when `maxBytes` is supplied (the untrusted ingest route), the
+     * body is rejected with RequestBodyTooLargeError as soon as the declared
+     * Content-Length OR the accumulated bytes exceed the ceiling — so an
+     * authenticated multi-GB POST can't buffer unbounded and OOM the shared
+     * process. When `maxBytes` is omitted (every other endpoint), behavior is
+     * exactly as before: no cap.
+     */
     private parseRequestBody;
+    /**
+     * PRD #647 F1: true only for the prompts source ingest endpoint, the one
+     * untrusted route the raw-body cap is scoped to. Parses the pathname so a
+     * query string can't bypass (or wrongly trip) the cap.
+     *
+     * PRD #647 C2 (CodeRabbit): the cap check runs BEFORE route dispatch, so a
+     * non-canonical pathname must be normalized here or it slips past the cap and
+     * buffers an uncapped body (DoS). A strict `===` let `POST /api/v1/prompts/
+     * sources/` (trailing slash) — the same ingest surface — skip `maxBytes`.
+     * Collapse trailing slashes (keeping a bare "/" intact) before comparing.
+     */
+    private isPromptsIngestRequest;
     stop(): Promise<void>;
     isReady(): boolean;
 }

package/dist/interfaces/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/interfaces/mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAgFtC,OAAO,EAAgB,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAcvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAmBD,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAkC;IACrD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,cAAc,CAAC,CAAiC;IACxD,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAA6B;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAqB;IAC3C,OAAO,CAAC,SAAS,CAAC,CAAM;gBAEZ,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe;IA6BjD;;;OAGG;IACH,gBAAgB,IAAI,aAAa,GAAG,SAAS;IAQ7C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IA2CvB;;OAEG;IACH,OAAO,CAAC,WAAW;IA8KnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;OAIG;YACW,mBAAmB;IA6CjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkCzB,OAAO,CAAC,qBAAqB;IAS7B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,iBAAiB;IAInB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAed,kBAAkB;YAgSlB,gBAAgB;IAexB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B,OAAO,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/interfaces/mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAgFtC,OAAO,EAAgB,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAcvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAqDD,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAkC;IACrD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,cAAc,CAAC,CAAiC;IACxD,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAA6B;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAqB;IAC3C,OAAO,CAAC,SAAS,CAAC,CAAM;gBAEZ,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe;IA6BjD;;;OAGG;IACH,gBAAgB,IAAI,aAAa,GAAG,SAAS;IAQ7C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IA2CvB;;OAEG;IACH,OAAO,CAAC,WAAW;IA8KnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;OAIG;YACW,mBAAmB;IA6CjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkCzB,OAAO,CAAC,qBAAqB;IAS7B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,iBAAiB;IAInB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAed,kBAAkB;IA0ThC;;;;;;;;;OASG;YACW,gBAAgB;IAgD9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,sBAAsB;IAWxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B,OAAO,IAAI,OAAO;CAGnB"}