@vfarcic/dot-ai 1.22.0 → 1.23.0

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

@@ -41,6 +41,15 @@ export interface UserPromptsOverride {
      * 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.
@@ -54,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
@@ -116,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;AAMH,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;IACjB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;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,CAqDnB;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;AA6VD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,OAAe,EAC7B,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CA0JnB;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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"}