prismcast 1.13.0 → 1.14.0

package/dist/config/consistencyProbe.js

@@ -7,46 +7,19 @@
  *
  *   - Variant entries with a canonicalKey (in channels.json) reference a canonical that exists in PREDEFINED_CHANNELS or the user's stored channels.
  *   - User domain mappings (in profiles.json) reference profiles that exist as builtin or user-defined.
- *   - The service tag filter (in config.json's channels.enabledServices) contains only recognized service tags.
  *
- * Each issue is logged loudly and, when an auto-fix is provided, applied immediately. Auto-fixes that need to mutate persistent state go through the same
- * mutate* functions as user code so the integrity validators and snapshot machinery cover them too.
+ * The probe reports what an operator must act on and changes nothing: each issue is logged, because the right repair depends on what the operator intended. A
+ * rule the running process can enforce on its own belongs where the process applies it - an unknown service tag never reaches the running filter because the
+ * services module restricts the filter itself - rather than here.
  *
  * Adding a new check is a single function returning ConsistencyIssue[]; collectConsistencyIssues calls each registered check function and aggregates the
  * results into one array.
  */
-import { LOG, formatError } from "../utils/index.js";
-import { getAllServiceTags, mutateEnabledServices } from "./services.js";
 import { getUserDomains, getUserProfiles } from "./userProfiles.js";
-import { CONFIG } from "./index.js";
+import { LOG } from "../utils/index.js";
 import { PREDEFINED_CHANNELS } from "../channels/index.js";
 import { getBuiltinProfile } from "./sites.js";
 import { getStoredUserChannels } from "./userChannels.js";
-/**
- * Validates that every service tag in CONFIG.channels.enabledServices is recognized, and when unknown tags remain its auto-fix persists the cleaned list through
- * mutateEnabledServices. In practice initializeUserChannels already strips unrecognized tags from the in-memory CONFIG.channels.enabledServices before the probe
- * runs - a memory-only cleanup that does not rewrite config.json - so the probe usually sees a clean list and the persisting auto-fix does not fire.
- */
-function checkServiceTagFilter() {
-    if (CONFIG.channels.enabledServices.length === 0) {
-        return [];
-    }
-    const knownTags = new Set(getAllServiceTags().map((tag) => tag.tag));
-    const enabledSet = new Set(CONFIG.channels.enabledServices);
-    const invalid = [...enabledSet.difference(knownTags)];
-    if (invalid.length === 0) {
-        return [];
-    }
-    return [{
-            autoFix: async () => {
-                // mutateEnabledServices persists the cleaned list to config.json and updates the in-memory cache atomically.
-                await mutateEnabledServices([...enabledSet.intersection(knownTags)]);
-            },
-            category: "unknown-service-tag",
-            description: "Service filter contains unrecognized tag(s): " + invalid.join(", "),
-            severity: "warning"
-        }];
-}
 /**
  * Validates that every variant entry's canonicalKey points at a channel that exists either in the predefined catalog or the user's stored channels. Dangling
  * canonical references usually mean the user deleted the canonical without cleaning the variants up; we surface for operator action rather than auto-fixing
@@ -101,16 +74,13 @@ function checkDomainProfiles() {
  */
 function collectConsistencyIssues() {
     return [
-        ...checkServiceTagFilter(),
         ...checkVariantCanonicals(),
         ...checkDomainProfiles()
     ];
 }
 /**
- * Runs the consistency probe at startup. Logs every issue, runs auto-fixes for warnings, and surfaces errors for operator review. Errors do not block startup
- * - a consistency error is recoverable runtime state, not an unbootable system. Operators see them in the log and can act before the next restart.
- *
- * Auto-fix failures are themselves logged but do not propagate. The probe is best-effort hygiene; a failure here must not bring down the server.
+ * Runs the consistency probe at startup. Logs every issue at its severity and changes nothing, so an operator sees in the log what needs their action before the
+ * next restart. Errors do not block startup - a consistency error is recoverable runtime state, not an unbootable system.
  */
 export async function runConsistencyProbeAtStartup() {
     const issues = collectConsistencyIssues();
@@ -119,8 +89,7 @@ export async function runConsistencyProbeAtStartup() {
     }
     for (const issue of issues) {
         const message = "Consistency probe (" + issue.category + ", " + issue.severity + "): " + issue.description;
-        // Defensive: no current checker emits severity:"error" - every check returns "warning" issues. The branch exists so a future check that needs operator
-        // attention rather than auto-cleanup can mark itself error and surface accordingly. Add a test to assert this behavior once an error-severity check exists.
+        // An error-severity issue is logged at error, so a check whose issue needs the operator before the next restart surfaces accordingly.
         if (issue.severity === "error") {
             LOG.error(message);
         }
@@ -128,19 +97,7 @@ export async function runConsistencyProbeAtStartup() {
             LOG.warn(message);
         }
     }
-    // Run auto-fixes in parallel via Promise.allSettled - each fix is independent and a failure on one must not block the others. We iterate the eligible issues
-    // and look up each settlement by index (length-paired by construction; Promise.allSettled preserves input order and arity), logging rejected reasons as
-    // warnings while leaving successful fixes intact.
-    const eligible = issues.filter((issue) => (issue.severity === "warning") && issue.autoFix);
-    const results = await Promise.allSettled(eligible.map(async (issue) => issue.autoFix?.()));
-    for (const [index, issue] of eligible.entries()) {
-        const result = results[index];
-        if (result?.status === "rejected") {
-            LOG.warn("Consistency probe auto-fix failed for %s: %s.", issue.category, formatError(result.reason));
-        }
-    }
-    // Defensive: paired with the per-issue severity dispatch above. No checker currently emits severity:"error", so this aggregate report is unreachable today;
-    // it remains in place so a future error-severity check produces the operator-visible summary line without any further wiring.
+    // Paired with the per-issue severity dispatch above: any error-severity issue also produces one operator-visible summary line counting them.
     const errors = issues.filter((issue) => issue.severity === "error").length;
     if (errors > 0) {
         LOG.error("Consistency probe found %d error(s) requiring operator review.", errors);

package/dist/config/consistencyProbe.js.map

@@ -1 +1 @@
-{"version":3,"file":"consistencyProbe.js","sourceRoot":"","sources":["../../src/config/consistencyProbe.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"consistencyProbe.js","sourceRoot":"","sources":["../../src/config/consistencyProbe.ts"],"names":[],"mappings":"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"}

package/dist/config/index.d.ts

@@ -1,16 +1,25 @@
-import type { ApplyResult, ChangeOutcome, ConfigChange } from "./reactivity.ts";
+import type { ApplyResult, ChangeRejection, ConfigChange, ConfigChangePartition } from "./reactivity.ts";
+import { mutateConfigThen, readConfig } from "./userConfig.ts";
+import type { ProcessFieldPath, UserConfig } from "./userConfig.ts";
 import type { Config, Nullable } from "../types/index.ts";
-import { mutateConfig, readConfig } from "./userConfig.ts";
 /**
  * CLI override map. Keys are dot-separated CONFIG_METADATA paths (e.g., "server.port", "paths.chromeDataDir"). Values are the parsed CLI flag values. Applied as the
  * highest-priority merge pass in mergeConfiguration().
  */
 export type CliOverrides = Record<string, unknown>;
 export interface ConfigStore {
-    readonly mutateConfig: typeof mutateConfig;
+    readonly mutateConfigThen: typeof mutateConfigThen;
     readonly readConfig: typeof readConfig;
 }
 export declare let CONFIG: Config;
+/**
+ * The error a save throws when the configuration it would write fails validation. The store writes nothing when its mutation throws, so the file, the running
+ * configuration and the loaded snapshot all stay as they were. Its message is the validation reason alone, complete sentences an operator can act on, so a
+ * route answers it as the validation error it is.
+ */
+export declare class ConfigurationRejectedError extends Error {
+    name: string;
+}
 /**
  * Indicates whether a user config file parse error occurred during initialization. The web UI displays a warning when this is true.
  */
@@ -21,69 +30,121 @@ export declare let configParseError: boolean;
 export declare let configParseErrorMessage: string | undefined;
 /**
  * Initializes the configuration by loading the user config file, merging with defaults, applying environment variable overrides, and applying CLI overrides. This
- * must be called at startup before any code accesses CONFIG. After initialization, the CONFIG object contains the final merged values.
+ * must be called at startup before any code accesses CONFIG. After initialization, the CONFIG object contains the final merged values. A file whose stored
+ * capture values need a correction, or whose HDHomeRun DeviceID the boot corrected, is written once through the store, the one write storing every correction
+ * the file needs, unless the store could not read the file or the configuration carries a hard error.
  * @param cliOverrides - Optional CLI flag overrides, applied at the highest priority level.
+ * @param io - The config store the boot reads from and makes its one correcting write through.
  */
 export declare function initializeConfiguration(cliOverrides?: CliOverrides, io?: ConfigStore): Promise<void>;
 /**
- * Re-reads the user config file, re-merges with the original CLI overrides, applies post-merge normalizations, commits the result to the in-memory CONFIG
- * binding, and dispatches the resulting diff to registered config-change handlers. This is the single entry point for "config changed - tell subsystems"; both
- * the /config save handler and /config/import handler call it after writing to disk. The returned ApplyResult partitions the diff into changes that were
- * applied live, deferred (requiring restart), or rejected (refused by a handler). Callers use the deferred count to decide whether to schedule a restart.
- *
- * Atomicity contract: failures during the read, merge, or normalize steps leave CONFIG completely untouched - the function builds the new shape in isolation
- * and only reassigns the live binding after all of those steps succeed. Failures DURING handler dispatch, however, occur after the CONFIG reassignment: CONFIG
- * already reflects the new on-disk state, but the handler chain may have run partway. The conservative answer is that handlers must not throw; they should
- * report outcomes (including "rejected") instead. That atomicity-on-read behavior is exercised by index.reload.test.ts.
+ * Returns the loaded snapshot: the configuration file as last loaded, merged and normalized exactly as the next boot would read it. Where it differs from CONFIG,
+ * the running process does not yet reflect the file. The settings form renders from it, so a page loaded after a save shows what is saved rather than what is
+ * running, and submitting that page cannot post the running value back over a change waiting for a restart.
+ * @returns The loaded snapshot. Callers read it and never mutate it.
+ */
+export declare function getLoadedConfiguration(): Readonly<Config>;
+/**
+ * Answers which saved settings the running process does not yet reflect: the gap between CONFIG and the loaded snapshot, partitioned by reactivity class. Its
+ * held members are the settings pending a restart, and its live and next-stream members are the settings a handler could not realize. The view covers the
+ * settings surface alone, the paths CONFIG_METADATA declares, because a leaf the process wrote and the loaded snapshot does not hold, which only a process
+ * write the file refused leaves, is the process ahead of the file rather than a save the user is waiting on. Derived on every call from CONFIG and the loaded
+ * snapshot, so it holds no state of its own. A reconcile publishes the snapshot only once it has committed what its handlers realized, so a caller that does
+ * not wait on the store's queue reads CONFIG and the snapshot as the last completed reconcile left them, and a change a save introduces is never listed as
+ * unrealized while its handlers are still running.
+ * @returns The settings-surface gap, partitioned into held, live, and next-stream changes, each carrying the running value as previous and the saved value as
+ *   current.
+ */
+export declare function getConfigurationGap(): ConfigChangePartition;
+/**
+ * The one entry for a write to the settings surface - the settings save, the import, and the debug page all go through it. Inside the store's own mutation it
+ * applies the caller's mutator to the current file, builds the candidate exactly as the next boot would read that file, and refuses an invalid candidate by
+ * throwing ConfigurationRejectedError with the validation reason, so the store writes nothing. A file the store cannot parse or cannot read refuses the
+ * mutation inside the store the same way. Once the file is written, the save reconciles that candidate as the write's follow-up and answers with its result.
  *
- * Validation contract: before committing, the merged shape is re-checked against the same hard-error and capture-coercion checks the startup path enforces.
- * A configuration that carries a hard error (out-of-range numeric, non-absolute path, conflicting HDHR port) or would need a capture coercion (native mode, a
- * captureCodecs list missing the h264 baseline) is rejected rather than silently coerced: CONFIG stays on the previous valid state and every diffed change is
- * reported as rejected so the operator sees why nothing took effect. This closes the window where a live save could commit an un-normalized capture
- * configuration into the live binding without passing through validateConfiguration. The reject-on-invalid path is exercised by index.reload.test.ts.
+ * One queue: the store's chain serializes each write's read-modify-write together with its follow-up, a save's reconcile or a process write's commit, which
+ * runs while the store's queue is held, so no write reads the file while another write's reconcile or commit is running, and overlapping saves commit in the
+ * order their writes landed. A config-change handler never writes the configuration, because the reconcile or the process write's commit it runs inside holds
+ * the store's queue, and a write it awaited would wait on that queue and never settle.
+ * @param mutator - Applies the caller's change to the current file in place. A throw inside it writes nothing.
+ * @param io - The config store the save writes through.
+ * @returns What the reconcile realized, the restart-class changes this save holds for a restart, and the changes of this save a handler refused.
+ * @throws ConfigurationRejectedError when the candidate fails validation, and the store's own error when the file cannot be parsed, read, or written.
+ */
+export declare function saveConfiguration(mutator: (current: UserConfig) => void, io?: ConfigStore): Promise<ApplyResult>;
+/**
+ * The leaves a process write answers, keyed by the dot path of a field the process owns, so a path PROCESS_FIELDS does not declare as a state field is a
+ * compile error.
+ */
+export type ProcessFieldValues = Readonly<Partial<Record<ProcessFieldPath, unknown>>>;
+/**
+ * What a process write answers: whether the file took the write. The running configuration holds the leaves whatever the file did, so persisted false means
+ * the change is in effect but reverts when the process restarts, which a caller acting for the user reports to them.
+ */
+export interface ProcessWriteResult {
+    readonly persisted: boolean;
+}
+/**
+ * The operation for every field the process owns, the leaves the settings form never writes: the setup flag, the disabled predefined channels, the display
+ * preferences, the service list, and the discovered DVR host. Inside the store's own mutation it answers the leaves from the file the store just read and sets
+ * each on that file, and once the write has landed its follow-up commits exactly those leaves: their handlers are dispatched whatever CONFIG held before, and
+ * each leaf is set on CONFIG and then on the loaded snapshot. It builds no candidate and validates nothing beyond the store's own write normalization, because
+ * the process already holds the values it writes, and every other difference between CONFIG and the file, a hand edit or a refused setting among them, stays
+ * for the next settings save to reconcile and report.
  *
- * Serialization contract: calls are serialized on a module-level queue, so overlapping reloads read and commit in call order and the last reload to run always
- * reads a snapshot at least as fresh as every write that preceded its call. A failed reload rejects to its own caller without breaking the chain for later
- * ones. This extends the handler contract: a registered config-change handler must never call reloadConfiguration, because a queued reload awaiting a nested
- * reload would deadlock the chain.
- * @returns The aggregate result of dispatching the diff.
- */
-export declare function reloadConfiguration(io?: ConfigStore): Promise<ApplyResult>;
-/**
- * Live-applies the "logging." subset of a config diff. The debug filter is applied live by commitDebugFilter during reloadConfiguration - the runtime filter is
- * updated right after CONFIG is committed and before the diff dispatches - so it reports applied with no restart, which is what lets a debug-filter change take
- * effect immediately instead of waiting for one. The remaining logging fields (httpLogLevel, maxSize) are consumed when the logger and HTTP middleware are wired
- * at startup, so they defer to a restart.
+ * When the store refuses the write - it could not read or parse the file, or the callback, the write, or its readback failed - the leaves are answered again
+ * from the running configuration, one warning names them with the store's error, and they are committed to CONFIG alone; the operation resolves with persisted
+ * false, because the process owns the value and the file is only its record. The warning comes before the commit so a commit that throws propagates with the
+ * store's error already on record. A readback that fails is such a refusal though the file may hold the leaves, and the loaded snapshot takes them at the
+ * next settings save that lands. A rejection that arrives once the follow-up has begun is rethrown instead, because that write has landed: committing and
+ * dispatching the leaves a second time would log a refusal the file never made.
  *
- * Exported so tests can invoke the dispatch directly with a synthetic diff. Registered with the reactivity primitive at module load (side effect below).
- * @param changes - The subset of the diff whose path begins with "logging.".
- * @returns Per-change outcomes.
+ * A caller's fields answers from its argument alone and changes nothing it reaches, because it may run twice, once on the file the store read and once on the
+ * clone of CONFIG the refused path hands it, and Readonly holds only its argument's top level. A handler for a process field never writes the configuration,
+ * because the commit it runs inside holds the store's queue; a handler that refuses a process leaf leaves it committed regardless.
+ * @param fields - Answers the leaves to write, keyed by path, from the stored configuration it is handed.
+ * @param io - The config store the write goes through.
+ * @returns Whether the file took the write: persisted is true once the write has landed and false when the store refused it.
+ * @throws Whatever a follow-up that has begun rejects with, such as the class resolver's error for a leaf no setting or state entry classifies, and whatever
+ *   the refused path's commit throws once its warning is logged.
  */
-export declare function applyLoggingConfigChanges(changes: readonly ConfigChange[]): Promise<readonly ChangeOutcome[]>;
+export declare function writeProcessFields(fields: (stored: Readonly<UserConfig>) => ProcessFieldValues, io?: ConfigStore): Promise<ProcessWriteResult>;
+/**
+ * Realizes a change to the persisted debug filter: the candidate's filter becomes the runtime filter unless an env or CLI source owns it. Applying a filter
+ * cannot fail, so the handler refuses nothing. It is exported, as every module-registered handler is, so a suite that resets the registry re-registers it.
+ * @param _changes - The change under the handler's path; the candidate carries the filter, so the handler reads it there instead.
+ * @param next - The candidate running configuration.
+ * @returns No rejections.
+ */
+export declare function applyDebugFilterChange(_changes: readonly ConfigChange[], next: Readonly<Config>): Promise<readonly ChangeRejection[]>;
 /**
  * Returns a deep copy of the default configuration. Used by the web UI to display default values and handle reset operations.
  * @returns A copy of the default configuration.
  */
 export declare function getDefaults(): Config;
 /**
- * Validates that a configuration value is a positive integer within an optional range. This helper performs the common validation pattern of checking for valid
- * integers and enforcing minimum/maximum bounds. It returns an error message if validation fails, allowing the caller to collect all errors before reporting them.
- * @param name - The configuration name for error messages, typically the environment variable name.
- * @param value - The value to validate, typically parsed from an environment variable.
- * @param min - Optional minimum allowed value (inclusive).
+ * Validates that a configuration value is an integer at or above its floor and at or below an optional ceiling. The floor is the minimum the setting's metadata
+ * declares, and 1 when none is declared, so a setting whose metadata allows zero accepts it and an integer setting with no declared minimum stays positive. It
+ * returns an error message rather than throwing, so the caller can collect every error before reporting them. Every message is a complete sentence naming the
+ * value it refused, and a value below the floor draws a message naming the floor it applied, because a save joins the messages into the reason it answers with.
+ * @param name - The configuration name for error messages, typically the environment variable name or the setting's label.
+ * @param value - The value to validate.
+ * @param min - The declared minimum (inclusive). When it is omitted, the floor is 1.
  * @param max - Optional maximum allowed value (inclusive).
  * @returns Error message if invalid, null if valid.
  */
-export declare function validatePositiveInt(name: string, value: number, min?: number, max?: number): Nullable<string>;
+export declare function validateInteger(name: string, value: number, min?: number, max?: number): Nullable<string>;
 /**
- * Validates that a configuration value is a positive number (including floats) within an optional range.
+ * Validates that a configuration value is a number, fractional or whole, at or above its floor and at or below an optional ceiling. The floor is the minimum the
+ * setting's metadata declares, and when none is declared the value must be positive, so zero is accepted only where the metadata says it is. Every message is a
+ * complete sentence naming the value it refused and, for a value below the floor, the floor it applied.
  * @param name - The configuration name for error messages.
  * @param value - The value to validate.
- * @param min - Optional minimum allowed value (inclusive).
+ * @param min - The declared minimum (inclusive). When it is omitted, the value must be greater than zero.
  * @param max - Optional maximum allowed value (inclusive).
  * @returns Error message if invalid, null if valid.
  */
-export declare function validatePositiveNumber(name: string, value: number, min?: number, max?: number): Nullable<string>;
+export declare function validateNumber(name: string, value: number, min?: number, max?: number): Nullable<string>;
 /** The settings whose value the server refuses to start with out of range. Each entry is a CONFIG_METADATA path, and the floor, the ceiling, and the name the
  * error reports all come from that path's metadata - the same metadata the settings form validates a save against. One declaration of a bound means a value
  * the form accepts is a value the boot accepts, and there is no second copy to fall out of step with the first.
@@ -97,21 +158,12 @@ export declare function validatePositiveNumber(name: string, value: number, min?
  */
 export declare const STARTUP_BOUNDED_SETTINGS: readonly string[];
 /**
- * Validates all configuration values and throws an error if any are invalid. This function runs at startup after configuration initialization. It first applies
- * the capture coercions in place (filtering captureCodecs, forcing FFmpeg mode, with the same operator-visible warning as before), then collects every hard
- * error against the coerced CONFIG and throws once with the complete list. Splitting the pure collectors (collectCoercions, collectHardErrors) from the in-place
- * application lets reloadConfiguration reuse the same hard-error and capture-coercion checks without silently coercing a live save.
+ * Validates the running configuration and throws if it carries any hard error. It runs at startup once the configuration is initialized, collects every hard
+ * error, and throws once with the complete list, so the operator can fix every issue in one pass. A correctable value never reaches here uncorrected, because
+ * the configuration is corrected as it is built.
  * @throws If any configuration value is invalid. The error message lists all invalid values.
  */
 export declare function validateConfiguration(): void;
-/**
- * Persists the capture configuration that validateConfiguration coerced at startup back to disk so the on-disk state matches the live CONFIG. A no-op unless a
- * coercion actually occurred. Without this, a config file holding an unsupported capture value (native mode, or a captureCodecs list missing the h264 baseline)
- * stays divergent from the coerced live CONFIG forever, and the reload-validation path would then reject every later save on the resulting phantom capture diff.
- * filterDefaults strips any value equal to its default on write, so a config coerced back to the FFmpeg/h264 defaults leaves a clean file with no capture override.
- * Failures degrade gracefully: the live CONFIG is already coerced, so a write failure only means the divergence persists until the next successful save or boot.
- */
-export declare function persistCoercedConfig(io?: ConfigStore): Promise<void>;
 /**
  * Displays the active configuration at startup. This helps operators verify their settings and diagnose connection issues. We log only the most commonly adjusted
  * values to keep output concise while providing useful debugging information.