@jwilleke/ngdpbase-types 5.41.0 → 5.41.1

package/lib/packages/media-date/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Filename → capture-date parser, the one implementation of it.
+ *
+ * ngdpbase uses it when a media file carries no usable EXIF/QuickTime date, and
+ * mjs-media-handling uses a built copy of it to place and stamp files. Both must read a name the same way, which is why it is one package.
+ *
+ * It is a pure function of the name: no filesystem, no network, no server.
+ *
+ * Missing parts are filled with fixed, documented values — see FAKE_MONTH below
+ * and README.md. Callers that must know what was real read `parseFilenameDate`,
+ * whose `month`/`day`/`time` are null where the name did not carry them.
+ */
+/** Written when the name gives a year but no month. */
+export declare const FAKE_MONTH = 6;
+/** Written when the name gives no day of the month. */
+export declare const FAKE_DAY = 15;
+/** Written when the name gives no time of day. */
+export declare const FAKE_TIME = "11:59:00";
+/** What a filename said, with null for each part it did not say. */
+export interface FilenameDate {
+    year: number;
+    month: number | null;
+    day: number | null;
+    /** `HH:MM:SS`, only when the name carried a valid time. */
+    time: string | null;
+    /** Which rule matched, e.g. `filename:YYYY-MM-DD`. */
+    source: string;
+}
+/** What the name itself says, nothing filled in. Null when it says nothing. */
+export declare function parseFilenameDate(filename: string): FilenameDate | null;
+/** `YYYY-MM-DD HH:MM:SS`, with FAKE_MONTH, FAKE_DAY and FAKE_TIME where missing. */
+export declare function fillFilenameDate(date: FilenameDate): string;
+/** The capture date a filename gives, filled in; null when it gives none. */
+export declare function parseDateFromFilename(filename: string): string | null;

package/lib/src/managers/ConfigurationManager.d.ts

@@ -306,6 +306,12 @@ declare class ConfigurationManager extends BaseManager {
      * Empty for an addon that ships no file, is disabled, or is unknown.
      */
     getAddonDeclaredDefaults(slug: string): Record<string, unknown>;
+    /**
+     * `value` with its environment references resolved as `getProperty` would
+     * resolve it under `key`, for checking a value before it is saved (#2195).
+     * Throws, as `getProperty` would, on a bare `$VAR` that is not set.
+     */
+    resolveValueAs(key: string, value: unknown): unknown;
     /**
      * Resolve environment-variable references in a string config value.
      *

package/lib/src/managers/MediaManager.d.ts

@@ -37,6 +37,8 @@ declare class MediaManager extends BaseManager implements CatalogSource {
     readonly currentSchemaVersion = 1;
     /** Active media provider (null when not yet initialized) */
     private _provider;
+    /** Why configured folders were refused for overlapping private storage (#2195). */
+    private overlapReasons;
     /** The configured media folders, for the degraded-state reason (#1167). */
     private mediaFolders;
     /** Return the active media provider for use by AssetManager. */
@@ -105,6 +107,13 @@ declare class MediaManager extends BaseManager implements CatalogSource {
      * what degraded means (#1155) — configured, wanted, not working.
      */
     private recordFolderState;
+    /** Log and notify admins of each folder refused for overlapping private storage (#2195). */
+    private surfaceOverlaps;
+    /**
+     * Why each of `folders` may not be a media folder, empty when all may (#2195).
+     * The configuration screen asks before saving `ngdpbase.media.folders`.
+     */
+    checkFolders(folders: string[]): string[];
     /** One path per line, then "and N more" when the provider capped the list (#2191). */
     private formatFileList;
     /**

package/lib/src/providers/FileSystemMediaProvider.d.ts

@@ -37,6 +37,12 @@ export interface FileSystemMediaProviderConfig {
     readonly: boolean;
     /** Set of file extensions (lowercase, no dot) to index */
     extensions: Set<string>;
+    /**
+     * Private storage the scanner never walks under or keeps in the index (#2195):
+     * the roots `privateStorageRoots` lists. MediaManager already refuses a folder
+     * that overlaps them; this holds even if one gets past it.
+     */
+    excludedRoots?: string[];
 }
 /** Default supported media file extensions — used when no config override is provided */
 export declare const DEFAULT_MEDIA_EXTENSIONS: string[];
@@ -54,6 +60,8 @@ declare class FileSystemMediaProvider extends BaseMediaProvider {
     private readonly config;
     /** In-memory index: id → MediaIndexEntry */
     private index;
+    /** `config.excludedRoots` as real paths, resolved once (#2195). */
+    private readonly excludedReal;
     /** Single ExifTool worker process reused across all reads */
     private readonly exiftoolInstance;
     constructor(config: FileSystemMediaProviderConfig);
@@ -62,6 +70,17 @@ declare class FileSystemMediaProvider extends BaseMediaProvider {
      * (before the first background scan).
      */
     initialize(): Promise<void>;
+    /** The private storage root `p` is under, or undefined (#2195). */
+    private excludedRootOf;
+    /** Whether `p` is under private storage the scanner must not touch (#2195). */
+    private isExcluded;
+    /**
+     * Drop index entries under private storage (#2195): a site that had a media
+     * folder overlapping it before the check existed has those files indexed.
+     */
+    private dropExcludedEntries;
+    /** Delete every cached thumbnail (`{id}-*.webp`) of `ids`: they are copies of the files. */
+    private removeThumbnails;
     /**
      * Release the ExifTool worker process.
      */

package/lib/src/utils/mediaFolderOverlap.d.ts

@@ -0,0 +1,50 @@
+/** One place private files are kept, and what to call it in a message. */
+export interface PrivateStorageRoot {
+    label: string;
+    path: string;
+}
+/** How a media folder overlaps a root: it is the root, holds it, or is inside it. */
+export type OverlapRelation = 'equals' | 'contains' | 'is inside';
+export interface MediaFolderOverlap {
+    folder: string;
+    /** 1-based position of the folder in `ngdpbase.media.folders`. */
+    position: number;
+    root: PrivateStorageRoot;
+    relation: OverlapRelation;
+}
+/** Minimal configuration surface, so tests need no live engine. */
+export interface StorageRootConfig {
+    getProperty(key: string, defaultValue: unknown): unknown;
+    getResolvedDataPath(key: string, defaultValue: string): string;
+}
+/**
+ * Where private files live: the vaults (shared folders' pages and files are
+ * the `shared-folders` container's vault, so they are in here), the legacy
+ * `private/` root a site may not have moved yet, the shared folders' key
+ * storage, and two places in attachment storage: the old private attachments
+ * the migration leaves behind and reads as a fallback, and the thumbnail cache,
+ * which holds thumbnails of vault images. Attachment paths are the ones
+ * BasicAttachmentProvider resolves.
+ */
+export declare function privateStorageRoots(config: StorageRootConfig): PrivateStorageRoot[];
+/**
+ * The real path of `p`, or of its nearest existing ancestor with the rest
+ * appended. `p` is not normalized first: `link/..` is the parent of where
+ * `link` points, not the directory holding `link` (#2195).
+ */
+export declare function realPathOf(p: string): string;
+/** Whether `child` is `parent` or under it; both already real paths. */
+export declare function isSameOrUnder(child: string, parent: string): boolean;
+/** How `folder` overlaps `root`, or null for no overlap. */
+export declare function overlapRelation(folder: string, root: string): OverlapRelation | null;
+/** The first private storage root `folder` overlaps, or null. */
+export declare function findMediaFolderOverlap(folder: string, roots: PrivateStorageRoot[], position?: number): MediaFolderOverlap | null;
+/** Each of `folders` that overlaps a root, with its position in the list. */
+export declare function findMediaFolderOverlaps(folders: string[], roots: PrivateStorageRoot[]): MediaFolderOverlap[];
+/**
+ * The message for a refused folder. It names the folder by its position and
+ * the kind of storage. It never echoes the folder: one inside a vault would
+ * name the vault's owner and id, and the message reaches admin notices and
+ * their email.
+ */
+export declare function describeMediaFolderOverlap(o: MediaFolderOverlap): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.41.0",
+  "version": "5.41.1",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",

package/lib/src/providers/mediaFilenameDate.d.ts

@@ -1,22 +0,0 @@
-/**
- * Conservative filename → capture-date parser (#809, slice C of #807).
- *
- * Last-resort fallback used by media providers when a file carries no usable
- * EXIF/QuickTime capture date. Many devices encode the capture time in the
- * filename (e.g. `PXL_20260113_123414708.jpg`, `2026-04-03-IMG_4654.jpg`,
- * `Feb_20_2026_19_25_04.jpg`); without this, those files index with
- * `dateTimeOriginal: null` and sort only by file `mtime`.
- *
- * Design constraints (from the issue):
- *   - **Conservative** — only a small set of high-confidence, anchored patterns
- *     are accepted. Anything ambiguous returns `null`, and the caller then
- *     falls back to `mtime` and surfaces the file to admins.
- *   - **Distinguishable provenance** — the caller records that the resulting
- *     date came from the filename (`captureDateSource: 'filename'`), so a
- *     parsed date never masquerades as authoritative EXIF metadata.
- *
- * Returns a `"YYYY-MM-DD HH:MM:SS"` string (the exact shape produced by the
- * EXIF extractor, so it flows through sort/filter identically), or `null`.
- * A date-only match yields a `00:00:00` time.
- */
-export declare function parseDateFromFilename(filename: string): string | null;