@vfarcic/dot-ai 1.21.1 → 1.23.0

package/dist/core/git-utils.d.ts

@@ -11,6 +11,19 @@
  * - GITHUB_APP_ENABLED: Enable GitHub App authentication
  * - GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID: GitHub App config
  */
+/**
+ * Environment variable name through which a per-request override credential
+ * (PRD #621 M3) is handed to the GIT_ASKPASS helper. The token travels in the
+ * git child process's ENVIRONMENT — never on its argv (ps/proc) and never
+ * embedded in the clone URL written to `.git/config`.
+ */
+export declare const ASKPASS_TOKEN_ENV = "DOT_AI_GIT_ASKPASS_TOKEN";
+/**
+ * Environment variable naming the host the override token is bound to. The
+ * GIT_ASKPASS helper emits the token ONLY when git's credential prompt names
+ * this host, so a cross-host HTTP redirect can never obtain it (Decision 3).
+ */
+export declare const ASKPASS_HOST_ENV = "DOT_AI_GIT_ASKPASS_HOST";
 export interface GitAuthConfig {
     pat?: string;
     githubApp?: {
@@ -31,7 +44,40 @@ export declare function sanitizeRelativePath(relativePath: string): string;
 export interface CloneOptions {
     branch?: string;
     depth?: number;
+    /**
+     * Per-call git credential (PRD #621 M3). When supplied it OVERRIDES the
+     * env/GitHub-App auth (`getGitAuthConfigFromEnv`) for this clone only
+     * (Decision 4) and is scoped to the host in `repoUrl` with cross-host
+     * redirect forwarding disabled (Decision 3 — see buildOverrideCloneAuth).
+     * When omitted, the clone uses env auth exactly as before.
+     */
+    token?: string;
 }
+/**
+ * PRD #621 M3 / Decision 3: build the clone URL + intended host for a
+ * per-request override credential.
+ *
+ * The credential itself is NOT in the returned URL — it is the bare
+ * `x-access-token` username only (the token is passed via a HOST-BOUND
+ * GIT_ASKPASS helper, see cloneRepo / createAskpassScript). So the token never
+ * lands on the git argv or in the cloned `.git/config` remote URL (MEDIUM-2/3).
+ *
+ * No `-c` git config is returned: the earlier `-c credential.helper=` was
+ * REJECTED by simple-git's safety guard (allowUnsafeCredentialHelper), which
+ * aborted the clone entirely; and `-c http.followRedirects=false` is dropped
+ * per review finding R-1 (it blocked legitimate same-host redirects too). The
+ * host-bound askpass makes following redirects provably safe — the token is
+ * emitted ONLY for `host`, and libcurl already strips credentials on a
+ * cross-host redirect by default.
+ *
+ * Returned as plain data so the auth decision is unit-testable without spawning
+ * git. The token is intentionally NOT a parameter — it never influences this
+ * (URL/argv) surface.
+ */
+export declare function buildOverrideCloneAuth(repoUrl: string): {
+    cloneUrl: string;
+    host: string;
+};
 export declare function cloneRepo(repoUrl: string, targetDir: string, opts?: CloneOptions): Promise<{
     localPath: string;
     branch: string;

package/dist/core/git-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../../src/core/git-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AASD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1E;AA2ED,wBAAsB,YAAY,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAc7E;AAED,wBAAgB,uBAAuB,IAAI,aAAa,CAyBvD;AAeD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CASjE;AAID,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BhD;AAID,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B5E;AAID,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,CAAC,CA4ErB"}
+{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../../src/core/git-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAI1D,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AASD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1E;AA2ED,wBAAsB,YAAY,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAc7E;AAED,wBAAgB,uBAAuB,IAAI,aAAa,CAyBvD;AAeD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CASjE;AAID,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,CAMA;AAkJD,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAsChD;AAID,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B5E;AAID,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,CAAC,CA4ErB"}

package/dist/core/git-utils.js

@@ -49,20 +49,37 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASKPASS_HOST_ENV = exports.ASKPASS_TOKEN_ENV = void 0;
 exports.scrubCredentials = scrubCredentials;
 exports.getAuthenticatedUrl = getAuthenticatedUrl;
 exports.getAuthToken = getAuthToken;
 exports.getGitAuthConfigFromEnv = getGitAuthConfigFromEnv;
 exports.sanitizeRelativePath = sanitizeRelativePath;
+exports.buildOverrideCloneAuth = buildOverrideCloneAuth;
 exports.cloneRepo = cloneRepo;
 exports.pullRepo = pullRepo;
 exports.pushRepo = pushRepo;
 const simple_git_1 = __importDefault(require("simple-git"));
+const node_child_process_1 = require("node:child_process");
 const jwt = __importStar(require("jsonwebtoken"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
 const FETCH_TIMEOUT_MS = 30000;
 const GIT_TIMEOUT_MS = 120000; // 2 minutes for git operations
+/**
+ * Environment variable name through which a per-request override credential
+ * (PRD #621 M3) is handed to the GIT_ASKPASS helper. The token travels in the
+ * git child process's ENVIRONMENT — never on its argv (ps/proc) and never
+ * embedded in the clone URL written to `.git/config`.
+ */
+exports.ASKPASS_TOKEN_ENV = 'DOT_AI_GIT_ASKPASS_TOKEN';
+/**
+ * Environment variable naming the host the override token is bound to. The
+ * GIT_ASKPASS helper emits the token ONLY when git's credential prompt names
+ * this host, so a cross-host HTTP redirect can never obtain it (Decision 3).
+ */
+exports.ASKPASS_HOST_ENV = 'DOT_AI_GIT_ASKPASS_HOST';
 // ─── Auth helpers ───
 function scrubCredentials(message) {
     return message
@@ -177,10 +194,184 @@ function sanitizeRelativePath(relativePath) {
     }
     return normalized;
 }
+/**
+ * PRD #621 M3 / Decision 3: build the clone URL + intended host for a
+ * per-request override credential.
+ *
+ * The credential itself is NOT in the returned URL — it is the bare
+ * `x-access-token` username only (the token is passed via a HOST-BOUND
+ * GIT_ASKPASS helper, see cloneRepo / createAskpassScript). So the token never
+ * lands on the git argv or in the cloned `.git/config` remote URL (MEDIUM-2/3).
+ *
+ * No `-c` git config is returned: the earlier `-c credential.helper=` was
+ * REJECTED by simple-git's safety guard (allowUnsafeCredentialHelper), which
+ * aborted the clone entirely; and `-c http.followRedirects=false` is dropped
+ * per review finding R-1 (it blocked legitimate same-host redirects too). The
+ * host-bound askpass makes following redirects provably safe — the token is
+ * emitted ONLY for `host`, and libcurl already strips credentials on a
+ * cross-host redirect by default.
+ *
+ * Returned as plain data so the auth decision is unit-testable without spawning
+ * git. The token is intentionally NOT a parameter — it never influences this
+ * (URL/argv) surface.
+ */
+function buildOverrideCloneAuth(repoUrl) {
+    const url = new URL(repoUrl);
+    const host = url.host;
+    url.username = 'x-access-token';
+    url.password = '';
+    return { cloneUrl: url.toString(), host };
+}
+/**
+ * Create a throwaway, HOST-BOUND GIT_ASKPASS helper script. The script holds NO
+ * secret — it echoes the token from the environment (ASKPASS_TOKEN_ENV) ONLY
+ * when git's credential prompt (passed as $1) names the intended host
+ * (ASKPASS_HOST_ENV), delimited by `@`/`//` before and a closing quote after.
+ * For any other host — e.g. after an HTTP redirect, or a look-alike like
+ * `github.com.evil.test` — it emits nothing, so the token can never reach a
+ * different host (Decision 3). The token never touches disk. The script lives
+ * in its own 0700 temp dir; `cleanup` removes it.
+ */
+function createAskpassScript() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dot-ai-askpass-'));
+    try {
+        fs.chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best-effort hardening */
+    }
+    const scriptPath = path.join(dir, 'askpass.sh');
+    // Host-bound match: require the intended host immediately after `@` or `//`
+    // and immediately before the closing `'` git puts around the URL, so neither
+    // a different redirect host nor a look-alike suffix matches.
+    const script = [
+        '#!/bin/sh',
+        'case "$1" in',
+        `  *"@$${exports.ASKPASS_HOST_ENV}'"*|*"//$${exports.ASKPASS_HOST_ENV}'"*)`,
+        `    printf '%s\\n' "$${exports.ASKPASS_TOKEN_ENV}"`,
+        '    ;;',
+        'esac',
+        '',
+    ].join('\n');
+    fs.writeFileSync(scriptPath, script, { mode: 0o700 });
+    return {
+        scriptPath,
+        cleanup: () => {
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort cleanup; the script holds no secret */
+            }
+        },
+    };
+}
+/**
+ * PRD #621 M3: clone an OVERRIDE repo using a per-request token, via a
+ * HOST-BOUND GIT_ASKPASS helper.
+ *
+ * This deliberately spawns `git` DIRECTLY rather than going through simple-git:
+ * simple-git's safety scanner rejects the env vars this approach relies on
+ * (GIT_ASKPASS → allowUnsafeAskPass) and even flags inherited vars like EDITOR
+ * / PAGER, which aborts the clone before it starts. A direct spawn lets us pass
+ * the full process.env (PATH/HOME/proxy/TLS) plus the askpass wiring with no
+ * argument/env guard interference, while still keeping:
+ *   - the token OFF the argv (the URL carries only the `x-access-token`
+ *     username) and OUT of .git/config (MEDIUM-2/MEDIUM-3);
+ *   - the token bound to the source host so a cross-host redirect can't obtain
+ *     it (Decision 3 — host-bound askpass + libcurl's default cross-host
+ *     credential stripping). Redirects are NOT disabled (review finding R-1),
+ *     so legitimate same-host redirects still work.
+ */
+async function cloneWithOverrideToken(repoUrl, targetDir, opts) {
+    const { cloneUrl, host } = buildOverrideCloneAuth(repoUrl);
+    const askpass = createAskpassScript();
+    const args = ['clone'];
+    if (opts.branch) {
+        args.push('--branch', opts.branch);
+    }
+    if (opts.depth) {
+        args.push('--depth', String(opts.depth));
+    }
+    // `--` terminates option parsing so the URL/dir can never be read as flags.
+    args.push('--', cloneUrl, targetDir);
+    const env = {
+        ...process.env,
+        GIT_ASKPASS: askpass.scriptPath,
+        // Never fall back to an interactive terminal prompt if askpass yields nothing.
+        GIT_TERMINAL_PROMPT: '0',
+        [exports.ASKPASS_TOKEN_ENV]: opts.token,
+        [exports.ASKPASS_HOST_ENV]: host,
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)('git', args, {
+                env,
+                stdio: ['ignore', 'ignore', 'pipe'],
+            });
+            let stderr = '';
+            // The 'error', 'close', and timeout handlers can each race to settle this
+            // promise (e.g. 'close' still fires after a kill or a spawn 'error'). A
+            // promise only settles once, but the LATER handlers would still run their
+            // logic on an already-settled promise. Guard so the FIRST settle wins and
+            // every subsequent handler is a no-op, and clear the timeout on settle so
+            // no dangling timer fires afterwards.
+            let settled = false;
+            const timerRef = {};
+            const settle = (action) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timerRef.id)
+                    clearTimeout(timerRef.id);
+                action();
+            };
+            timerRef.id = setTimeout(() => {
+                settle(() => {
+                    child.kill('SIGKILL');
+                    reject(new Error(`git clone timed out after ${GIT_TIMEOUT_MS}ms`));
+                });
+            }, GIT_TIMEOUT_MS);
+            child.stderr?.on('data', chunk => {
+                stderr += chunk.toString();
+            });
+            child.on('error', err => {
+                settle(() => reject(err));
+            });
+            child.on('close', code => {
+                settle(() => {
+                    if (code === 0) {
+                        resolve();
+                    }
+                    else {
+                        // stderr carries only the username-only URL (no token), so it is
+                        // safe to surface; the caller scrubs it again as defense-in-depth.
+                        reject(new Error(`git clone exited with code ${code}: ${stderr.trim()}`));
+                    }
+                });
+            });
+        });
+    }
+    finally {
+        // Remove the askpass helper as soon as the clone finishes (success or
+        // failure). It holds no secret, but leaving temp files around is untidy.
+        askpass.cleanup();
+    }
+    return { localPath: targetDir, branch: opts.branch || 'main' };
+}
 async function cloneRepo(repoUrl, targetDir, opts) {
+    // PRD #621 M3 / Decision 4: a per-request override credential takes precedence
+    // over env auth for THIS clone only and uses the host-bound GIT_ASKPASS path.
+    if (opts?.token) {
+        return cloneWithOverrideToken(repoUrl, targetDir, {
+            ...opts,
+            token: opts.token,
+        });
+    }
+    // Env/GitHub-App auth path (unchanged): credentials come from
+    // getGitAuthConfigFromEnv and are embedded in the URL as before.
     const authConfig = getGitAuthConfigFromEnv();
     let cloneUrl;
-    // Use authenticated URL if credentials are available, otherwise clone unauthenticated (public repos)
     if (authConfig.pat || authConfig.githubApp) {
         const token = await getAuthToken(authConfig);
         cloneUrl = getAuthenticatedUrl(repoUrl, token);

package/dist/core/user-prompts-loader.d.ts

@@ -32,6 +32,24 @@ export interface UserPromptsOverride {
     repoUrl: string;
     branch?: string;
     subPath?: string;
+    /**
+     * Per-request git credential forwarded by the caller (PRD #621 M2/M3, via the
+     * X-Dot-AI-Git-Token header). When present it takes precedence over
+     * DOT_AI_GIT_TOKEN for THIS request only (Decision 4) and triggers per-request
+     * cache isolation so a private authenticated clone is never served to/from the
+     * shared unauthenticated cache slot (Decision 2). Never enters the cache key
+     * or any log/error/source surface.
+     */
+    gitToken?: string;
+    /**
+     * PRD #647 D1: when set, this override resolves to an already-ingested source
+     * (uploaded via POST /api/v1/prompts/sources) identified by this string —
+     * NOT a git clone. loadUserPrompts reads the cached uploaded files directly
+     * and NEVER calls cloneRepo, so a `local:<label>` or server-unreachable
+     * `?repo=` URL is served without any git operation. `repoUrl` carries the
+     * same identifier only for the scrubbed `source` echo (computePromptsSource).
+     */
+    ingestedSource?: string;
 }
 /**
  * Cache state for tracking repository freshness.
@@ -45,6 +63,88 @@ interface CacheState {
     branch: string;
     subPath: string;
 }
+/**
+ * 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.
+ */
+export declare const 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).
+ */
+export declare class PromptsSourceValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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.
+ */
+export declare class IngestedSourceNotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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.
+ */
+export declare function sanitizeIngestFileMode(mode: unknown): number;
+/** Shape of the uploaded manifest (validated at runtime; all fields untrusted). */
+export interface IngestPromptsSourceInput {
+    source: unknown;
+    contentHash?: unknown;
+    files: unknown;
+}
+/** Result echoed back to the caller after a successful ingest. */
+export interface IngestPromptsSourceResult {
+    /** Credential-scrubbed identifier the render path uses via ?source=. */
+    source: string;
+    contentHash?: string;
+    fileCount: number;
+    /**
+     * 'ingested' — the manifest was decoded, hardened, and (re)written.
+     * 'unchanged' — PRD #647 D3 short-circuit: an identical contentHash was
+     * already cached for this identifier, so nothing was re-decoded or rewritten.
+     */
+    status: 'ingested' | 'unchanged';
+}
+/**
+ * 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.
+ */
+export declare function ingestPromptsSource(input: IngestPromptsSourceInput, logger: Logger): IngestPromptsSourceResult;
 /**
  * Read user prompts configuration from environment variables
  * Returns null if DOT_AI_USER_PROMPTS_REPO is not set
@@ -107,18 +207,46 @@ export declare function sanitizeUrlForLogging(url: string): string;
  * helper was deferred per the M2 follow-up scope.
  */
 export declare function scrubSourceUrl(url: string): string;
+/**
+ * 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.
+ */
+export declare class UserPromptsOverrideError extends Error {
+    constructor(message: string);
+}
 /**
  * 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.
  */
 export declare function loadUserPrompts(logger: Logger, forceRefresh?: boolean, override?: UserPromptsOverride): Promise<Prompt[]>;
 /**
  * Clear the cache state (useful for testing)
  */
 export declare function clearUserPromptsCache(): void;
+/**
+ * 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.
+ */
+export declare function clearIngestedPromptsSources(): void;
+/**
+ * Inspect the ingested-source cache (PRD #647, for testing/debugging).
+ * Returns the scrubbed identifiers currently cached.
+ */
+export declare function getIngestedPromptsSources(): string[];
 /**
  * Get current cache state (for testing/debugging)
  */

package/dist/core/user-prompts-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-prompts-loader.d.ts","sourceRoot":"","sources":["../../src/core/user-prompts-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAO1C,OAAO,EAAE,MAAM,EAA8B,MAAM,kBAAkB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,UAAU,UAAU;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAsB/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAS3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,mBAAmB,GAC5B,iBAAiB,CAkDnB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAqB1C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUzD;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoBlD;AA2PD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,OAAe,EAC7B,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CA0HnB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,GAAG,IAAI,CAE5D"}
+{"version":3,"file":"user-prompts-loader.d.ts","sourceRoot":"","sources":["../../src/core/user-prompts-loader.ts"],"names":[],"mappings":"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"}