@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,51 @@
+/**
+ * A secret that must be defined in the instance `.env`, generated once when
+ * nothing supplies it (#1194, generalised for #1524).
+ *
+ * The session secret was the first; the credentials-store key is the second.
+ * Both follow one rule, so it is written once:
+ *
+ * 1. Set in the environment — use it, write nothing.
+ * 2. Blank in the environment, but the instance `.env` has a usable line — use
+ *    that (a launcher passing `NAME=` empty would otherwise regenerate on every
+ *    boot).
+ * 3. Otherwise generate, append one commented line to `<instanceDataDir>/.env`
+ *    (created `0600` when new), and use it.
+ *
+ * The repo-root `.env` is never written: it is shared by every instance that
+ * launches from the checkout.
+ */
+/** Filesystem seams, injected so the backfill is testable in a scratch dir. */
+export interface InstanceEnvFs {
+    readFile: (path: string) => string | null;
+    appendFile: (path: string, line: string, createMode: number) => void;
+    randomSecret: () => string;
+}
+/** Where the value the process is using came from. */
+export type InstanceEnvSecretOrigin = {
+    kind: 'env';
+} | {
+    kind: 'instance-env-file';
+    path: string;
+} | {
+    kind: 'generated';
+    path: string;
+};
+export interface InstanceEnvSecretSpec {
+    /** The variable, e.g. `NGDPBASE_SESSION_SECRET`. */
+    name: string;
+    /** The comment line written above a generated value (without `# `). */
+    comment: string;
+    /** Checks a found value and returns it, or throws (a placeholder, say). */
+    accept?: (value: string) => string;
+    /** The error thrown when the generated line cannot be written. */
+    refusal: (envPath: string, cause: Error) => Error;
+}
+export declare function ensureInstanceEnvSecret(spec: InstanceEnvSecretSpec, env: Readonly<Record<string, string | undefined>>, instanceDataDir: string, fs: InstanceEnvFs): {
+    secret: string;
+    origin: InstanceEnvSecretOrigin;
+};
+/** The last `NAME=` line in a dotenv file, unquoted; null when absent or blank. */
+export declare function readEnvLine(content: string, name: string): string | null;
+/** The real filesystem behind every generated `.env` secret. */
+export declare const nodeInstanceEnvFs: InstanceEnvFs;

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

@@ -0,0 +1,43 @@
+/**
+ * Which due slots of a scheduled job run, and which are skipped (#1715, epic
+ * #1611). Pure: the scheduler in `BackgroundJobManager` hands it the slots
+ * that are due and when the job was last busy, and records what it returns.
+ *
+ * A slot is due when its time has come and it has not been handled. Due slots
+ * come in two kinds, and each has its own rule:
+ *
+ *   - **came due while the job was running** (before `busyUntil`): the job's
+ *     `overlap` rule. `queue` keeps one waiting slot, the newest; `skip` keeps
+ *     none. One job never runs twice at once.
+ *   - **came due while the job was idle, or the server was down**: the job's
+ *     `catchUp` rule. A slot that came due within `onTimeMs` is on time, not
+ *     missed: `none` runs only on-time slots, `latest` runs the newest due slot,
+ *     `all` runs the newest {@link CATCH_UP_ALL_CAP}, oldest first.
+ *
+ * Every due slot not run is skipped, so the caller records it: a slot is
+ * never dropped without a trace (operator, 2026-10-08).
+ *
+ * @module utils/jobSlots
+ */
+export type CatchUp = 'none' | 'latest' | 'all';
+export type Overlap = 'queue' | 'skip';
+/** `catchUp: 'all'` runs at most this many missed slots; older ones are skipped. */
+export declare const CATCH_UP_ALL_CAP = 12;
+export interface SlotSelectionInput {
+    /** The due slots, oldest first. */
+    due: Date[];
+    now: Date;
+    /** When this job's last run in this process ended; null when it has not run since start. */
+    busyUntil: Date | null;
+    /** A slot that came due at most this long ago is on time, not missed. */
+    onTimeMs: number;
+    catchUp: CatchUp;
+    overlap: Overlap;
+}
+export interface SlotSelection {
+    /** Slots to run, oldest first, one at a time. */
+    run: Date[];
+    /** Slots passed over, oldest first. */
+    skip: Date[];
+}
+export declare function selectSlots(input: SlotSelectionInput): SlotSelection;

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

@@ -0,0 +1,127 @@
+/**
+ * Keyword normalizer (#869) — the title↔value canonical form for the unified
+ * keyword vocabulary.
+ *
+ * Per the epic's design principle #2, every keyword is `{ value, title }`:
+ *   - `title` (CatalogTerm.label) — display form, kept verbatim, written to files.
+ *   - `value` (CatalogTerm.term) — ngdpbase-internal canonical form: lowercase,
+ *     spaces/punctuation → single hyphens, diacritics transliterated, ≤ 64 chars
+ *     (IPTC IIM 2:25 limit), comma-free (comma is a list delimiter in many tools).
+ *
+ * `value` is what the media index, search, page metadata and URLs key on, so two
+ * titles that differ only by case/spacing/accent collapse to ONE value — the
+ * mechanism that makes `Dining` and `dining` impossible to hold as distinct
+ * keywords. This module is pure (no I/O); enforcement (routing all keyword input
+ * through it) is wired by its consumers.
+ *
+ * Differs deliberately from `simpleSlug` (pluginFormatters): that DROPS accented
+ * characters (`José` → `jos`), which would silently corrupt personal-name
+ * keywords; this TRANSLITERATES them (`José` → `jose`) and enforces the length
+ * cap.
+ */
+/** Max length of a keyword value (IPTC IIM 2:25 keyword field limit). */
+export declare const KEYWORD_VALUE_MAX = 64;
+/**
+ * Canonical value for a keyword title. Idempotent: `normalizeKeywordValue(v)`
+ * equals `v` for any already-valid value. Returns '' when the title has no
+ * usable alphanumeric content.
+ */
+export declare function normalizeKeywordValue(title: string): string;
+/**
+ * True when `value` is already a canonical keyword value: non-empty, ≤ 64 chars,
+ * comma-free, lowercase alphanumeric segments joined by single hyphens.
+ */
+export declare function isValidKeywordValue(value: string): boolean;
+/**
+ * True when two titles normalize to the same (non-empty) value — i.e. they are
+ * case/space/accent variants of one keyword.
+ */
+export declare function keywordsCollide(a: string, b: string): boolean;
+/** Build a `{ term, label }` pair (CatalogTerm shape) from a display title. */
+export declare function toKeywordTerm(title: string): {
+    term: string;
+    label: string;
+};
+/**
+ * Parse hierarchical tag values (#917) into `/`-joined canonical-value paths.
+ * digiKam/Lightroom store the tag tree two ways; both are unioned + deduped:
+ *   - `XMP-lr:HierarchicalSubject` — `|`-separated (`Places|USA|Colorado|Denver`)
+ *   - `XMP-digiKam:TagsList`       — `/`-separated (`Places/USA/Colorado/Denver`)
+ * Each segment is run through `normalizeKeywordValue`, so a path becomes
+ * `places/usa/colorado/denver` (leaf = last segment). Empty segments are
+ * dropped; a value that is a scalar string is treated as a single-entry list.
+ */
+export declare function parseHierarchicalTags(hierarchicalSubject: unknown, tagsList: unknown): string[];
+/**
+ * Reconcile a file's hierarchical tag tree against an edited flat keyword list
+ * (#918). Preserves the operator's digiKam hierarchy through an ngdpbase edit —
+ * paths are kept in their original DISPLAY form (never rewritten to slugs, which
+ * would corrupt the tree on re-read).
+ *
+ * Rules (only when the file already carries hierarchy — a flat-only file gets
+ * `null`, i.e. leave it flat):
+ *   - a KEPT keyword keeps its existing path (`~WHO/Crotty/Lyman …` stays);
+ *   - a REMOVED keyword's path is dropped;
+ *   - `auto/*` machine-tag paths are always preserved untouched (principle #5);
+ *   - a NEW keyword lands at the ROOT as a single-segment path in its display
+ *     form. (Cross-library placement at a known leaf path — via #917's leaf map
+ *     in display form — is a later refinement; root is the safe default.)
+ *
+ * `hierarchicalSubject`/`tagsList` are the file's current raw tag values (string
+ * or string[]). Returns the new values for BOTH encodings, or null to leave the
+ * file's hierarchy untouched.
+ */
+export declare function reconcileHierarchicalTags(keywords: readonly string[], hierarchicalSubject: unknown, tagsList: unknown): {
+    hierarchicalSubject: string[];
+    tagsList: string[];
+} | null;
+/**
+ * Build a leaf→path map from many hierarchical paths (#917) — the library-wide
+ * "where does this leaf keyword live" lookup #918 uses to place a newly-added
+ * keyword at its known hierarchical home. Leaf = last path segment; on conflict
+ * the most frequently-seen path wins (ties broken by longest, then first).
+ */
+export declare function buildLeafPathMap(paths: Iterable<string>): Map<string, string>;
+/** One keyword display form seen somewhere, with where it was seen (#919). */
+export interface KeywordFormStat {
+    form: string;
+    pageCount?: number;
+    mediaCount?: number;
+    catalogued?: boolean;
+    catalogId?: string;
+}
+/** A cluster of display forms that share one canonical value (#919). */
+export interface KeywordVariantGroup {
+    value: string;
+    canonicalForm: string;
+    canonicalId?: string;
+    forms: Array<{
+        form: string;
+        pageCount: number;
+        mediaCount: number;
+        catalogued: boolean;
+        catalogId?: string;
+    }>;
+    total: number;
+    mergeable: boolean;
+}
+/**
+ * Group keyword display forms into variant clusters (#919, #869 Slice 4).
+ * Forms are deduped by exact string (summing counts), grouped by
+ * `normalizeKeywordValue` (folds case/space/accent/punctuation — stronger than
+ * a lowercase match), and only values carried by **2+ distinct forms** are
+ * returned. Canonical form = the catalogued form if any, else the most-used.
+ * `mergeable` is true when the canonical and at least one other form are both
+ * catalog terms (the page-retag merge keys on catalog ids). Pure.
+ */
+export declare function groupKeywordVariants(forms: readonly KeywordFormStat[]): KeywordVariantGroup[];
+/**
+ * Collapse a keyword list to one entry per canonical value (#869 dedup
+ * enforcement): case/space/accent variants of the same keyword are merged,
+ * first occurrence wins ordering, empties dropped. When `canonicalByValue`
+ * (value → registry title) is supplied, a kept keyword is snapped to the
+ * registry's display title so `dining` converges on catalogued `Dining`;
+ * otherwise the first-seen form is kept trimmed. Pure — the registry lookup
+ * is passed in, not fetched here.
+ */
+export declare function dedupeKeywords(keywords: readonly string[], canonicalByValue?: ReadonlyMap<string, string>): string[];

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

@@ -0,0 +1,70 @@
+/**
+ * Simple logging framework using winston
+ *
+ * Provides centralized logging for the entire ngdpbase application with
+ * file rotation, console output, and configurable log levels.
+ *
+ * Issue #169: transport + format construction is delegated to a
+ * {@link BaseLoggingProvider} (default {@link FileLoggingProvider}) so the
+ * storage backend is swappable. The exported `logger` API is unchanged —
+ * call sites need no edits. The provider is deliberately engine-free: the
+ * logger bootstraps before WikiEngine/ConfigurationManager exist and is
+ * imported by nearly every module, so provider *selection* happens later in
+ * `WikiEngine.initialize()` via {@link setLoggingProvider}.
+ *
+ * @module logger
+ *
+ * @example
+ * import logger from './utils/logger';
+ * logger.info('Application started');
+ * logger.error('Error occurred', { error });
+ */
+import { Logger } from 'winston';
+import BaseLoggingProvider from '../providers/BaseLoggingProvider.js';
+/**
+ * Logger configuration options
+ */
+export interface LoggerConfig {
+    /** Log level (error, warn, info, debug) */
+    level?: string;
+    /** Log directory path */
+    dir?: string;
+    /** Max log file size in bytes or string format (e.g., '1MB') */
+    maxSize?: number | string;
+    /** Max number of rotated log files */
+    maxFiles?: number;
+}
+/**
+ * Resolve a provider name (e.g. `'fileloggingprovider'`) to an instance.
+ * Unknown names fall back to FileLoggingProvider — logging must never fail
+ * to initialize because of a misconfigured provider key.
+ *
+ * @param name - Lowercase provider name from `ngdpbase.logging.provider`
+ * @returns A logging provider instance
+ */
+export declare function resolveLoggingProvider(name: string | undefined): BaseLoggingProvider;
+/**
+ * Set the active logging provider. Called by WikiEngine after
+ * ConfigurationManager resolves `ngdpbase.logging.provider`. Does not rebuild
+ * the running logger on its own — {@link reconfigureLogger} does that.
+ *
+ * @param provider - The provider instance to activate
+ */
+export declare function setLoggingProvider(provider: BaseLoggingProvider): void;
+/**
+ * Creates a winston logger instance with the specified configuration.
+ * Transports and format are produced by the active logging provider.
+ *
+ * @param config - Logger configuration
+ * @returns Winston logger instance
+ */
+export declare function createLoggerWithConfig(config?: LoggerConfig): Logger;
+/**
+ * Reconfigures the global logger instance with new settings
+ *
+ * @param config - New logger configuration
+ * @returns Updated logger instance
+ */
+export declare function reconfigureLogger(config: LoggerConfig): Logger;
+declare const loggerInstance: Logger;
+export default loggerInstance;

package/lib/src/utils/logger.js

@@ -0,0 +1,106 @@
+/**
+ * Simple logging framework using winston
+ *
+ * Provides centralized logging for the entire ngdpbase application with
+ * file rotation, console output, and configurable log levels.
+ *
+ * Issue #169: transport + format construction is delegated to a
+ * {@link BaseLoggingProvider} (default {@link FileLoggingProvider}) so the
+ * storage backend is swappable. The exported `logger` API is unchanged —
+ * call sites need no edits. The provider is deliberately engine-free: the
+ * logger bootstraps before WikiEngine/ConfigurationManager exist and is
+ * imported by nearly every module, so provider *selection* happens later in
+ * `WikiEngine.initialize()` via {@link setLoggingProvider}.
+ *
+ * @module logger
+ *
+ * @example
+ * import logger from './utils/logger';
+ * logger.info('Application started');
+ * logger.error('Error occurred', { error });
+ */
+import { createLogger } from 'winston';
+import FileLoggingProvider from '../providers/FileLoggingProvider.js';
+// Default config (can be overridden)
+// Note: File transport is only added when 'dir' is explicitly provided
+// (e.g., during reconfiguration from WikiEngine after ConfigurationManager resolves paths)
+const defaultConfig = {
+    level: 'info',
+    maxSize: 1048576, // 1MB
+    maxFiles: 5
+};
+/**
+ * The active logging provider. Defaults to FileLoggingProvider (the pre-#169
+ * behaviour). Swapped via {@link setLoggingProvider} once config is resolved.
+ */
+let activeProvider = new FileLoggingProvider();
+/**
+ * Resolve a provider name (e.g. `'fileloggingprovider'`) to an instance.
+ * Unknown names fall back to FileLoggingProvider — logging must never fail
+ * to initialize because of a misconfigured provider key.
+ *
+ * @param name - Lowercase provider name from `ngdpbase.logging.provider`
+ * @returns A logging provider instance
+ */
+export function resolveLoggingProvider(name) {
+    switch ((name ?? '').toLowerCase()) {
+        case 'fileloggingprovider':
+        case '':
+            return new FileLoggingProvider();
+        default:
+            // No logger guarantees available here yet; fall back silently to the
+            // default rather than throwing during bootstrap.
+            return new FileLoggingProvider();
+    }
+}
+/**
+ * Set the active logging provider. Called by WikiEngine after
+ * ConfigurationManager resolves `ngdpbase.logging.provider`. Does not rebuild
+ * the running logger on its own — {@link reconfigureLogger} does that.
+ *
+ * @param provider - The provider instance to activate
+ */
+export function setLoggingProvider(provider) {
+    activeProvider = provider;
+}
+/**
+ * Creates a winston logger instance with the specified configuration.
+ * Transports and format are produced by the active logging provider.
+ *
+ * @param config - Logger configuration
+ * @returns Winston logger instance
+ */
+export function createLoggerWithConfig(config = {}) {
+    const logConfig = { ...defaultConfig, ...config };
+    return createLogger({
+        level: logConfig.level,
+        format: activeProvider.createFormat(),
+        transports: activeProvider.createTransports(logConfig)
+    });
+}
+/**
+ * Reconfigures the global logger instance with new settings
+ *
+ * @param config - New logger configuration
+ * @returns Updated logger instance
+ */
+export function reconfigureLogger(config) {
+    if (!loggerInstance) {
+        throw new Error('Logger instance not initialized');
+    }
+    const currentLogger = loggerInstance; // Capture for closure
+    const newLogger = createLoggerWithConfig(config);
+    // Clear existing transports
+    currentLogger.clear();
+    // Add new transports from the reconfigured logger
+    newLogger.transports.forEach(transport => {
+        currentLogger.add(transport);
+    });
+    // Update logger level
+    currentLogger.level = newLogger.level;
+    return currentLogger;
+}
+// Create default logger instance - always initialized before export
+const loggerInstance = createLoggerWithConfig();
+// Export the logger instance as default
+export default loggerInstance;

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

@@ -0,0 +1,95 @@
+/**
+ * Magic-link device binding (#1022).
+ *
+ * A magic link is bearer-only: whoever holds the URL can sign in. A forwarded
+ * email, a link pasted into a chat, or a mailbox a second person can read is a
+ * complete account takeover — no second factor, and nothing in the log saying
+ * the redemption came from somewhere unexpected.
+ *
+ * The mitigation is to remember which browser asked for the link (an opaque
+ * value in an HTTP-only cookie, stored alongside the token) and check it at
+ * redemption.
+ *
+ * ## Why this is two features, not one
+ *
+ * Strict binding breaks the most common real flow: request the link on a
+ * laptop, open the mail on a phone. That is not an edge case, and silently
+ * breaking it would be worse than the risk being mitigated. So:
+ *
+ * - **Observability is always on.** Every redemption records whether the
+ *   browser matched, plus IP and User-Agent, through `AuditManager` so it is
+ *   queryable rather than buried in the app log. Costs nothing in UX.
+ * - **Enforcement is opt-in**, behind
+ *   `ngdpbase.auth.magic-link.bind-to-requesting-device` (default `false`).
+ *
+ * ## The direction that must not be got wrong
+ *
+ * An absent cookie is `absent`, never `match`. A forwarded link arrives with no
+ * cookie at all, so treating "no cookie" as a pass would make the enforcement
+ * setting do nothing against the exact attacker it exists to stop.
+ *
+ * A token carrying no stored state is a separate case (`unknown`) and is always
+ * allowed: tokens live in memory for ~15 minutes, so on the deploy that ships
+ * this there are live tokens issued before the feature existed. Refusing those
+ * would sign people out mid-flow for no security gain.
+ */
+/** Cookie carrying the opaque per-request state value. */
+export declare const DEVICE_STATE_COOKIE = "ngdp_ml_state";
+/**
+ * The same binding for an OAuth sign-in (#1630): the browser that started the
+ * flow is the one the callback must come back to. Its own cookie, so a
+ * magic-link request and a Google sign-in in flight together do not overwrite
+ * each other. Unlike the magic link there is no cross-device flow here — the
+ * provider redirects the same browser back — so it is always enforced.
+ */
+export declare const OAUTH_STATE_COOKIE = "ngdp_oauth_state";
+export type DeviceBindingOutcome = 
+/** Cookie present and equal to the value stored with the token. */
+'match'
+/** Cookie present but different — a different browser is redeeming. */
+ | 'mismatch'
+/** No cookie presented. The cross-device flow, and also the forwarded-link attack. */
+ | 'absent'
+/** Token predates this feature, or was issued without state. Not evidence either way. */
+ | 'unknown';
+export interface DeviceBindingResult {
+    outcome: DeviceBindingOutcome;
+    /** Whether the sign-in may proceed, given the enforcement setting. */
+    allowed: boolean;
+}
+export interface DeviceBindingInput {
+    /** State stored with the token when the link was requested. */
+    stored: string | null | undefined;
+    /** State presented by the redeeming browser's cookie. */
+    presented: string | null | undefined;
+    /** Whether `bind-to-requesting-device` is enabled. */
+    enforce: boolean;
+}
+/** A fresh opaque state value. 32 bytes of CSPRNG, hex-encoded. */
+export declare function newDeviceState(): string;
+/**
+ * Cookie options for the state cookie.
+ *
+ * `SameSite=Lax` rather than `Strict` is deliberate: the redemption arrives as
+ * a top-level navigation from a mail client or webmail tab, and `Strict` would
+ * withhold the cookie on that cross-site click — making every ordinary
+ * redemption look like a mismatch, which is the failure mode most likely to get
+ * this feature switched off.
+ *
+ * `httpOnly` keeps page scripts from reading or forging it. `maxAge` tracks the
+ * token TTL so the cookie does not outlive what it describes.
+ */
+export declare function deviceStateCookieOptions(ttlMs: number, secure?: boolean): {
+    httpOnly: true;
+    sameSite: 'lax';
+    maxAge: number;
+    path: '/';
+    secure: boolean;
+};
+/**
+ * Decide what the presented cookie says about the redeeming browser.
+ *
+ * Never throws: this runs on the sign-in path, and an exception here would turn
+ * a legitimate login into a 500.
+ */
+export declare function evaluateDeviceBinding(input: DeviceBindingInput): DeviceBindingResult;

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

@@ -0,0 +1,40 @@
+/**
+ * Shared utilities for manager-to-plugin content methods.
+ *
+ * Managers import from here to implement methods like toMarqueeText() or
+ * toSlideshowContent() in a consistent way. Plugin code never imports from
+ * this file — plugins only receive the formatted output string.
+ */
+/**
+ * Common options for manager methods that feed plugin content.
+ * Passed as a raw key=value object from the plugin's fetch= parameter.
+ * Domain-specific options (e.g. alertLevel, colorCode) are handled per-manager.
+ */
+export interface ManagerFetchOptions {
+    /** Max items to return. 0 = unlimited. */
+    limit?: number;
+    /** Field name to sort by — each manager defines valid values. */
+    sortBy?: string;
+    /** Sort direction. */
+    sortOrder?: 'asc' | 'desc';
+    /** ISO date string — include only items at or after this date. */
+    since?: string;
+    /** ISO date string — include only items before this date. */
+    before?: string;
+}
+/**
+ * Parse a raw key=value args object (from a plugin fetch= parameter) into
+ * a typed ManagerFetchOptions. Unknown keys are silently ignored — each
+ * manager is responsible for reading its own domain-specific keys from the
+ * same raw object.
+ *
+ * Convenience shorthand: `sort='date-desc'` expands to
+ * `{ sortBy: 'date', sortOrder: 'desc' }`.
+ *
+ * @example
+ * // fetch='HansDataManager.toMarqueeText(limit=3,sort=date-desc)'
+ * // raw = { limit: '3', sort: 'date-desc' }
+ * const opts = parseManagerFetchOptions(raw);
+ * // opts = { limit: 3, sortBy: 'date', sortOrder: 'desc' }
+ */
+export declare function parseManagerFetchOptions(raw?: Record<string, string>): ManagerFetchOptions;

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

@@ -0,0 +1,15 @@
+/**
+ * Move `{attachmentStoragedir}/{legacyprivateroot}/{user}/hash.ext` into
+ * `{pages}/{privateroot}/{user}/{defaultstoreid}/{attachmentsdir}/` (#1386).
+ *
+ * Destination is the page store. Leave sealed stores' leftover files alone.
+ * `legacyprivateroot` is migrate-FROM only — not a live write target.
+ */
+import { type PrivateStoreLayoutOverrides } from './privateStorePath.js';
+export declare function migrateLegacyPrivateAttachments(opts: {
+    attachmentsPrivateDir: string;
+    pagesDirectory: string;
+    layout?: PrivateStoreLayoutOverrides;
+}): Promise<{
+    moved: number;
+}>;

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

@@ -0,0 +1,22 @@
+/**
+ * URL-first filename derivation for organization JSON-LD files (#617,
+ * locked decision #9).
+ *
+ * Domain names are guaranteed unique by registry, so URL-derived slugs are
+ * the strongest uniqueness anchor for the on-disk filename. Falls back to
+ * the org name when no URL is available, then to a literal `organization`
+ * last-ditch default.
+ *
+ *   filenameFromOrg({ url: 'https://fairwayscondos.org/' })
+ *     → 'fairwayscondos-org.json'
+ *   filenameFromOrg({ url: 'www.fairwayscondos.org' })
+ *     → 'www-fairwayscondos-org.json'
+ *   filenameFromOrg({ name: 'The Fairways' })
+ *     → 'the-fairways.json'
+ *   filenameFromOrg({})
+ *     → 'organization.json'
+ */
+export declare function filenameFromOrg({ url, name }: {
+    url?: string;
+    name?: string;
+}): string;

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

@@ -0,0 +1,27 @@
+/**
+ * A page that belongs to a feature is not there while the feature is off (#1677).
+ *
+ * A shipped help page for capture still told readers to open `/capture/install`
+ * on a site where capture is off, and that route answered 404. A page names
+ * the switch it belongs to in frontmatter — `requires-setting:
+ * ngdpbase.capture.enabled` — and while that setting is not `true`, reading the
+ * page answers "not found" and listings leave it out, as profile already
+ * leaves out its Captures row (#1004).
+ *
+ * One predicate, asked by both doors that decide a page: PageManager's
+ * deciding read (so the reader gets the ordinary not-found) and the
+ * PolicyInformationPoint's page tiers (so listings and every other caller of
+ * the decider agree). Only `view` is affected; editing the page is unchanged.
+ */
+/** The frontmatter key naming the boolean setting a page belongs to. */
+export declare const REQUIRES_SETTING = "requires-setting";
+interface SettingReader {
+    getProperty(key: string, fallback: unknown): unknown;
+}
+/**
+ * True when the page names a setting and that setting is not `true`.
+ * A page naming no setting is never hidden. Without a configuration reader
+ * nothing is hidden: absence of configuration is not a switch turned off.
+ */
+export declare function hiddenByFeature(metadata: Record<string, unknown> | null | undefined, config: SettingReader | null | undefined): boolean;
+export {};

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

@@ -0,0 +1,21 @@
+export interface ParsedPageFile {
+    data: Record<string, unknown>;
+    content: string;
+}
+/**
+ * A name value as text, for values that no longer carry their written form
+ * (metadata already parsed elsewhere). A Date becomes its ISO string, which is
+ * what an imported timestamp title was written as.
+ */
+export declare function nameAsText(value: unknown): string | undefined;
+/**
+ * Make a metadata object's name fields text in place, and return it.
+ *
+ * For callers holding metadata that was parsed without
+ * `parsePageFrontmatter`; a save must never meet a boolean or Date title.
+ */
+export declare function namesAsText<T extends Record<string, unknown>>(data: T): T;
+/**
+ * Parse a page file. Name fields come back as the text written in the file.
+ */
+export declare function parsePageFrontmatter(raw: string): ParsedPageFile;