@jwilleke/ngdpbase-types 5.35.0 → 5.37.0

package/lib/packages/ngdpbase-types/testing.js

@@ -48,7 +48,7 @@ export function openAddonTestDatabase(owner, options, declaredBy) {
     checkAddonDatabaseRequest(owner, options);
     if (declaredBy) {
         const { slug, defaults } = declaredBy;
-        const layer = addonDatabaseLayer([{ slug, dir: '', source: 'directory', enabled: true, defaults }], {});
+        const layer = addonDatabaseLayer([{ slug, dir: '', enabled: true, defaults }], {});
         const refused = layer.refused.get(slug);
         if (refused)
             throw new Error(`Add-on '${slug}' is not loaded: ${refused}`);

package/lib/src/ice/ledger.d.ts

@@ -1,5 +1,13 @@
 import type { IceLedger, LedgerFileEntry } from './types.js';
+/**
+ * The ledger file form (#2013). A scope is bound to its receiver and user
+ * (`boundScope`); a file without this form was written before that binding,
+ * under a scope any caller could name, so it belongs to nobody: it is read
+ * as empty, never as anyone's history, and its files are imported once more.
+ */
+export declare const LEDGER_FORM = 2;
 interface ScopeFile {
+    form?: number;
     scope: string;
     files: LedgerFileEntry[];
     items: string[];

package/lib/src/ice/runImport.d.ts

@@ -21,8 +21,24 @@ export interface IceRunDeps {
 }
 /** The id of the receiver that keeps an original when the chosen receiver does not keep its own (D11). */
 export declare const FILES_RECEIVER = "core.files";
-/** The scope a run's fingerprints are checked in, unless the caller names one. */
-export declare function defaultScope(receiverId: string, ctx: ActorContext): string;
+/**
+ * The engine's key for an item of a file it stored, so a retry of that file
+ * skips it (#2010): the file's fingerprint, the chain, and a hash of the
+ * item's content (kind, text, data, bytes). Never its position: a shim that
+ * changes or orders its output differently cannot make a retry skip the
+ * wrong item. `seen` is how many identical items came before it in this file.
+ */
+export declare function itemKeyOf(sha256: string, chain: string[], item: IceItem, seen: number): string;
+/** The form of a bound scope (#2013). Scopes written before it never match one. */
+export declare const SCOPE_FORM = "ice2";
+/**
+ * The scope a run's fingerprints, per-file status and item keys live in
+ * (#2013): bound to the receiver and to the user the run is for, by their
+ * identity `@id` (else their username, #2041). The engine works it out from
+ * the caller's context; a request cannot name another user's. A caller's own
+ * `sub` (phr's source id) narrows it within that user's scope, never outside.
+ */
+export declare function boundScope(receiverId: string, owner: string, sub?: string): string;
 export interface ChainLeaf {
     item: IceItem;
     chain: string[];

package/lib/src/ice/types.d.ts

@@ -201,7 +201,13 @@ export interface IceReceiver {
     label?: string;
     /** The kinds it takes, e.g. `['ncm']`, `['file']`, `['phr.health-record']`. */
     accepts: IceKind[];
-    /** May this context use this receiver? Its existing permission — the import screen shows only these (D5). */
+    /**
+     * May this context use this receiver? Its existing permission (D5). The
+     * import screen shows only these, and the engine asks it before any work
+     * of a run (#2012): a no refuses every file before anything is unpacked,
+     * read by a shim, kept or fetched. Answer no whenever `receive` would
+     * refuse this context outright; `receive` still checks each item.
+     */
     mayUse(ctx: ActorContext): Promise<boolean>;
     /** Hand one item to the receiver's own door. */
     receive(item: IceItem, ctx: ActorContext, info: ReceiveInfo): Promise<ReceiveOutcome>;
@@ -252,10 +258,13 @@ export interface IceRunRequest {
     /** D11. Default `ngdpbase.import.engine.default-original`. */
     original?: OriginalChoice;
     /**
-     * Whose fingerprints and item keys this run is checked against. Default
-     * `<receiver>/<username>`: the same file imported again by the same person
-     * into the same receiver is skipped. A caller with its own notion of a
-     * source (phr's source id) passes it.
+     * A narrower ledger scope within the caller's own (#2013). The engine binds
+     * every run's scope to the receiver and to the user it runs as (their
+     * identity `@id`, else their username): the same file imported again by
+     * the same user into the same receiver is skipped. A caller with its own
+     * notion of a source (phr's source id) passes it to keep those apart; it
+     * can never reach another user's or another receiver's scope. Never pass a
+     * value a client sent.
      */
     scope?: string;
 }

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

@@ -12,6 +12,7 @@
  */
 import { type ActorContext } from '../context/ActorContext.js';
 import type { BackupFolder } from './BaseManager.js';
+import { type UpdateCheck, type UpdateOutcome } from '../utils/addonInstaller.js';
 import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
@@ -302,6 +303,9 @@ export interface AddonDashboardCard {
     /** URL of the add-on's admin page */
     adminUrl: string;
 }
+/** #2100: the PDP refused an administrator's add-on Update or Check. */
+export declare class AddonUpdateForbiddenError extends Error {
+}
 /**
  * Status information returned by getStatus()
  */
@@ -338,12 +342,14 @@ declare class AddonsManager extends BaseManager {
     private addonsPaths;
     /** Resolved absolute paths to addons directories */
     private resolvedAddonsPaths;
-    /** #673: npm package globs (from `node_modules:` addons-path entries) to discover from node_modules. */
-    private npmAddonPatterns;
     /** #1830: `<data>/addons`, where installed add-ons live; null when there is no data folder. */
     private installedDir;
     /** #1830: the installed add-ons verified this boot — the only ones loaded from `installedDir`. */
     private verifiedInstalled;
+    /** #2100: installed add-ons this start switched to an Update's release; settled after the load pass. */
+    private updatedThisStart;
+    /** #2100: Updates run one at a time, so two never write the lock file at once. */
+    private updateQueue;
     /** Stylesheets registered by add-ons via registerStylesheet() */
     private registeredStylesheets;
     /** Dashboard cards registered by add-ons via registerDashboardCard() */
@@ -374,6 +380,14 @@ declare class AddonsManager extends BaseManager {
      * this boot, not the next.
      */
     private installConfiguredAddons;
+    /**
+     * The installer's options for this site (#1830, #2100): the registry and the
+     * limits from configuration, and every request — registry, attestations, the
+     * Sigstore TUF repository — through the guarded client and the egress policy
+     * (#1139). `timeoutKey` is the `…install.<key>` that bounds each request: the
+     * boot install's, or the shorter one an admin page waits on.
+     */
+    private installerOptions;
     /**
      * `addon-install` (#1830): written after every check passed and before
      * anything is written to disk. on-failure: refuse — code does not join the
@@ -381,6 +395,47 @@ declare class AddonsManager extends BaseManager {
      * (recordSystemAction throws, and the installer writes nothing).
      */
     private recordAddonInstall;
+    /**
+     * #2100: after the load pass, settle each add-on this start switched to an
+     * Update's release. Loaded (or switched off, so there was nothing to try):
+     * the previous release's folder and tarball go. Not loaded: the previous
+     * release is restored on disk and in the lock, so the next start runs it.
+     * Core cannot unload an add-on that failed half-way (its modules, routes and
+     * jobs stay), so the restored release is not loaded in this process.
+     */
+    private settleUpdatedAddons;
+    /**
+     * `addon-update` (#2100) for a fall-back: core moved an installed add-on back
+     * from `from` to `to` because `from` did not load. on-failure: continue for
+     * this record — the fall-back has already happened on disk, and a lost
+     * record must not undo it.
+     */
+    private recordFallback;
+    /** #2100: the door for the admin's add-on questions. Throws when the PDP refuses. */
+    private requireAddonPermission;
+    /**
+     * #2100: for each add-on in `ngdpbase.addons.install`, the pinned release,
+     * the configured range, and the newest release in it that is newer — asked
+     * of the registry now. Called when an administrator opens the add-ons page
+     * or presses Check; never at start. Registry unreachable is an answer
+     * (`registryUnreachable`), not an error.
+     */
+    checkInstalledUpdates(ctx: ActorContext): Promise<UpdateCheck[]>;
+    /**
+     * #2100: an administrator's Update. Downloads `version` of the installed
+     * add-on `slug`, checks it exactly as a first install is checked (sha512,
+     * provenance, contents, `ngdpbase.minVersion`) and stages it: it runs from
+     * the next start. Asks the PDP for `config-manage`. Recorded as
+     * `addon-update` (who, the add-on, from and to) before anything is written;
+     * a record that cannot be written stops the Update.
+     */
+    updateInstalledAddon(ctx: ActorContext, slug: string, version: string): Promise<UpdateOutcome>;
+    /**
+     * `addon-update` (#2100): an administrator's Update, written after every
+     * check passed and before anything is written to disk. on-failure: refuse —
+     * a record that cannot be written stops the Update.
+     */
+    private recordAddonUpdate;
     /**
      * `addon-verify-failed` (#1830): an integrity, provenance, tarball, manifest,
      * lock or folder check refused (or, for a repaired folder, found it changed).
@@ -404,25 +459,10 @@ declare class AddonsManager extends BaseManager {
      * Scan a single addons directory and register any add-ons found.
      */
     private scanAddonsDirectory;
-    /**
-     * #673 (packaged model): discover addons published as npm packages, matching a
-     * `node_modules:<glob>` addons-path entry (e.g. `node_modules:@jwilleke/*-addon`).
-     * Each matching package is loaded through the same slug/module/register()
-     * contract as bundled and drop-in addons — only discovery differs.
-     */
-    private scanNpmAddons;
-    /** Locate the node_modules directory (app root / cwd). */
-    private findNodeModules;
-    /** Expand a `@scope/glob` (or bare `glob`) pattern to package directories. */
-    private resolveNpmAddonDirs;
     /**
      * Load a single addon from its directory (index.js/ts + optional package.json
-     * `ngdpbase` manifest) and register it. Shared by directory scans and npm
-     * (#673) discovery; `sourceLabel` is for logging only. `source` selects the
-     * no-slug identity fallback (#927): a directory addon's folder name is its
-     * identity verbatim, while an npm package strips the conventional `-addon`
-     * suffix. Duplicate ids are skipped — since npm discovery runs last, a
-     * bundled/drop-in addon wins.
+     * `ngdpbase` manifest) and register it. `sourceLabel` is for logging only.
+     * Duplicate ids are skipped, so the first directory scanned wins.
      */
     private registerAddonFromDir;
     /**

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

@@ -141,16 +141,15 @@ declare class ConfigurationManager extends BaseManager {
     /**
      * #672: refuse to start if any `ngdpbase.addons.<id>.enabled = true` key
      * references an `<id>` that has no matching addon in any configured
-     * `addons-path` entry — either a directory (bundled/drop-in) or, per
-     * #673/#924, an npm package matched by a `node_modules:<glob>` entry.
+     * `addons-path` directory (bundled/drop-in) and is not named in
+     * `ngdpbase.addons.install`. A retired `node_modules:` entry is ignored (#2102).
      * The discovery logic mirrors what `AddonsManager` does at runtime —
      * directory/package present with `index.js` or `index.ts` — but without
      * importing the modules (boot-time speed; `ConfigurationManager.initialize()`
-     * runs before any managers). The directory-vs-npm-pattern split, npm glob
-     * matching, AND the canonical-identity resolution are all shared with
+     * runs before any managers). The addons-path parsing AND the
+     * canonical-identity resolution are shared with
      * `AddonsManager` via `utils/addonsPathResolver.ts` so the two can no
-     * longer drift out of sync (#924: they had, and packaged addons could
-     * never boot as a result).
+     * longer drift out of sync (#924).
      *
      * Catches the failure mode that caused the 2026-05-10 geohazardwatch.com
      * outage: the deploy configmap had `ngdpbase.addons.ve-geology.enabled =

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

@@ -382,6 +382,18 @@ declare class ImportManager extends BaseManager {
     importRunsFor(ctx: ActorContext): IceRunReport[];
     /** Use this ledger instead of the file one: a test's, or a database table's. */
     setImportLedger(ledger: IceLedger): void;
+    /**
+     * The ledger scope a run uses (#2013): bound to the receiver and to the user
+     * `ctx` names, by their identity `@id`; their username only when the
+     * identity store answers that there is no record for them (#2041). Never a
+     * scope the caller names: a request's `scope` only narrows within this
+     * user's own.
+     *
+     * @throws IdentityStoreUnavailableError when the identity store cannot
+     *   answer: the run does not start, and nothing is recorded, rather than
+     *   land in a scope the user's other runs do not use
+     */
+    private importScope;
     private newRunReport;
     private executeRun;
     /** What a run, or keeping at upload, works with. */

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

@@ -18,8 +18,8 @@
  * shipped entry. The operator's file still wins over everything.
  *
  * Discovery follows `ngdpbase.managers.addons-manager.addons-path` exactly as
- * AddonsManager does — directories and `node_modules:` patterns — so bundled
- * and external addons are treated alike. Only an addon whose
+ * AddonsManager does — directory entries — so bundled
+ * and drop-in addons are treated alike. Only an addon whose
  * `ngdpbase.addons.<slug>.enabled` is true in the shipped+custom view
  * contributes; a disabled addon's opinions do not reach the catalog.
  *
@@ -63,7 +63,6 @@ export declare const ADDONS_MANAGER_ENABLED_KEY = "ngdpbase.managers.addons-mana
 export interface AddonDefaults {
     slug: string;
     dir: string;
-    source: 'directory' | 'npm';
     /**
      * Whether the addon is switched on. A turned-off addon's file is read for its
      * system-categories alone (#1559); none of its other keys reach the merge.
@@ -83,7 +82,6 @@ export declare function isAddonEnabled(base: Record<string, unknown>, slug: stri
  */
 export declare function discoverAddonDirs(base: Record<string, unknown>, cwd?: string, dataFolder?: string): Array<{
     dir: string;
-    source: 'directory' | 'npm';
 }>;
 /**
  * The defaults of every installed addon, enabled or not, in discovery order,

package/lib/src/utils/addonConfigLayer.js

@@ -18,8 +18,8 @@
  * shipped entry. The operator's file still wins over everything.
  *
  * Discovery follows `ngdpbase.managers.addons-manager.addons-path` exactly as
- * AddonsManager does — directories and `node_modules:` patterns — so bundled
- * and external addons are treated alike. Only an addon whose
+ * AddonsManager does — directory entries — so bundled
+ * and drop-in addons are treated alike. Only an addon whose
  * `ngdpbase.addons.<slug>.enabled` is true in the shipped+custom view
  * contributes; a disabled addon's opinions do not reach the catalog.
  *
@@ -61,7 +61,7 @@ import fs from 'fs';
 import path from 'path';
 import { isDeepStrictEqual } from 'util';
 import { configFilePaths, deepMergeConfigs, deepMergeObjects, instanceDataFolder, isPlainObject, readConfigFilesSync } from './configFiles.js';
-import { configuredInstallSlugs, findNodeModulesDir, installedAddonsDir, matchNpmPackageDirs, resolveAddonSlug, splitAddonsPath } from './addonsPathResolver.js';
+import { configuredInstallSlugs, installedAddonsDir, resolveAddonSlug, splitAddonsPath } from './addonsPathResolver.js';
 import { lockedAddonDirsSync } from './addonLock.js';
 import { LEGACY_SECRET_KEYS_KEY, SENSITIVE_VALUES_KEY } from './sensitiveValues.js';
 import { parsePrivatestore } from './privateStorePath.js';
@@ -81,7 +81,7 @@ export function isAddonEnabled(base, slug) {
 export function discoverAddonDirs(base, cwd = process.cwd(), dataFolder = instanceDataFolder()) {
     if (base[ADDONS_MANAGER_ENABLED_KEY] === false)
         return [];
-    const { directories, npmPatterns } = splitAddonsPath(base[ADDONS_PATH_KEY] ?? './addons');
+    const { directories } = splitAddonsPath(base[ADDONS_PATH_KEY] ?? './addons');
     const found = [];
     for (const raw of directories) {
         const root = path.resolve(cwd, raw);
@@ -95,20 +95,13 @@ export function discoverAddonDirs(base, cwd = process.cwd(), dataFolder = instan
         for (const entry of entries) {
             if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'shared')
                 continue;
-            found.push({ dir: path.join(root, entry.name), source: 'directory' });
+            found.push({ dir: path.join(root, entry.name) });
         }
     }
     const installed = installedAddonsDir(dataFolder, cwd);
     if (!found.some((f) => path.dirname(f.dir) === installed)) {
         for (const dir of lockedAddonDirsSync(installed, configuredInstallSlugs(base)))
-            found.push({ dir, source: 'directory' });
-    }
-    const nmRoot = npmPatterns.length > 0 ? findNodeModulesDir(cwd) : null;
-    if (nmRoot) {
-        for (const pattern of npmPatterns) {
-            for (const dir of matchNpmPackageDirs(nmRoot, pattern))
-                found.push({ dir, source: 'npm' });
-        }
+            found.push({ dir });
     }
     return found;
 }
@@ -122,8 +115,8 @@ export function discoverAddonDirs(base, cwd = process.cwd(), dataFolder = instan
  */
 export function discoverAddonDefaults(base, cwd = process.cwd(), dataFolder = instanceDataFolder()) {
     const out = [];
-    for (const { dir, source } of discoverAddonDirs(base, cwd, dataFolder)) {
-        const slug = resolveAddonSlug(dir, source);
+    for (const { dir } of discoverAddonDirs(base, cwd, dataFolder)) {
+        const slug = resolveAddonSlug(dir);
         const enabled = isAddonEnabled(base, slug);
         const file = path.join(dir, 'config', 'default-config.json');
         if (!fs.existsSync(file))
@@ -136,10 +129,10 @@ export function discoverAddonDefaults(base, cwd = process.cwd(), dataFolder = in
             for (const [key, value] of Object.entries(raw))
                 if (!key.startsWith('_'))
                     defaults[key] = value;
-            out.push({ slug, dir, source, enabled, defaults });
+            out.push({ slug, dir, enabled, defaults });
         }
         catch (err) {
-            out.push({ slug, dir, source, enabled, defaults: {}, error: err instanceof Error ? err.message : String(err) });
+            out.push({ slug, dir, enabled, defaults: {}, error: err instanceof Error ? err.message : String(err) });
         }
     }
     return out;

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

@@ -85,6 +85,12 @@ export type InstallStatus =
  | 'verified'
 /** Already installed; the folder differed from its verified tarball and was rewritten. */
  | 'repaired'
+/**
+ * #2100: switched to the release an administrator's Update staged; the
+ * previous release is kept until AddonsManager confirms this one loaded
+ * ({@link confirmUpdate}) or falls back to it ({@link rollBackUpdate}).
+ */
+ | 'updated'
 /** Not installed (and not loaded); `reason` says why. */
  | 'skipped';
 /** Which verification refused, for `addon-verify-failed`. */
@@ -99,6 +105,20 @@ export interface InstallOutcome {
     registryUnreachable?: boolean;
     /** Set when a verification refused, or (for `repaired`) found the folder changed. */
     failedCheck?: FailedCheck;
+    /** For `updated`: the release it replaced. */
+    previousVersion?: string;
+    /**
+     * #2100: a switch an earlier start made and never confirmed (the new release
+     * did not load, or the process stopped before it could) was undone at this
+     * start, before anything loaded: `from` is the release given up, `to` the
+     * one restored.
+     */
+    rolledBack?: {
+        from: string;
+        to: string;
+    };
+    /** #2100: something admins should hear about a staged Update, such as one discarded. */
+    notice?: string;
 }
 /** `sha512-<base64>` of `data`. */
 export declare function sha512Integrity(data: Buffer): string;
@@ -107,3 +127,73 @@ export declare function sha512Integrity(data: Buffer): string;
  * Never throws for one add-on's problem: each outcome says what happened.
  */
 export declare function installConfiguredAddons(specs: Record<string, unknown>, opts: InstallerOptions): Promise<InstallOutcome[]>;
+/**
+ * The switched-to release loaded (or the add-on is off, so there is nothing to
+ * try): the previous release's folder and tarball go. No-op when nothing waits.
+ */
+export declare function confirmUpdate(addonsDir: string, slug: string): Promise<void>;
+/**
+ * The switched-to release did not load: restore the previous release on disk
+ * and in the lock, so the next start runs it. The new folder is set aside
+ * (`.rejected-…`) for inspection. Undefined when there is nothing to undo.
+ */
+export declare function rollBackUpdate(addonsDir: string, slug: string, now?: Date): Promise<{
+    from: string;
+    to: string;
+} | undefined>;
+/** Why an Update is refused while the last one is not settled (`previous` still in the lock). */
+export declare const FINISH_LAST_UPDATE = "finish the last update first: restart the site";
+/** What the admin page shows for one add-on in `ngdpbase.addons.install`. */
+export interface UpdateCheck {
+    slug: string;
+    package?: string;
+    /** The configured range (`version` in the entry). */
+    range?: string;
+    /** The release the lock pins: what runs. Absent when not installed. */
+    pinned?: string;
+    /** A release an Update downloaded, used from the next start. */
+    pending?: string;
+    /** The newest release in the range, whether or not this core can run it. */
+    newest?: string;
+    /** The newest release in the range, newer than what is pinned or staged, that this core can run: what Update installs. */
+    available?: string;
+    /** The newest release in the range, newer than what is pinned or staged, when it needs a newer ngdpbase. */
+    needsCore?: {
+        version: string;
+        minVersion: string;
+    };
+    registryUnreachable?: boolean;
+    /** Why there is nothing to compare: not installed, or a configuration problem. */
+    problem?: string;
+    /** The last update is not settled (the lock still names the release it replaced): no Update until a restart. */
+    blocked?: string;
+}
+/**
+ * Ask the registry, for every installed add-on, which releases in its range
+ * are newer than the one pinned. Reads the packument only; writes nothing.
+ * Called only when an administrator opens the add-ons page or presses Check,
+ * never at start.
+ */
+export declare function checkForUpdates(specs: Record<string, unknown>, opts: InstallerOptions): Promise<UpdateCheck[]>;
+/** What an Update did. */
+export interface UpdateOutcome {
+    slug: string;
+    /** `staged`: verified and downloaded; it runs from the next start. `refused`: nothing changed; `reason` says why. */
+    status: 'staged' | 'refused';
+    package?: string;
+    version?: string;
+    /** The release that runs until the next start. */
+    previousVersion?: string;
+    reason?: string;
+    registryUnreachable?: boolean;
+    failedCheck?: FailedCheck;
+}
+/**
+ * Download `version` of an installed add-on and stage it for the next start
+ * (#2100). It must be a release in the configured range, newer than the
+ * pinned one, that this core can run, and it passes the same checks as a
+ * first install ({@link fetchVerified}): sha512, provenance, contents,
+ * package.json. `beforeInstall` (the audit record) runs after the checks and
+ * before anything is written. The running add-on's folder is not touched.
+ */
+export declare function stageUpdate(slug: string, rawSpec: unknown, version: string, opts: InstallerOptions): Promise<UpdateOutcome>;

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

@@ -7,9 +7,8 @@
  * folders in `<data>/addons` are installed add-ons at all: a folder the lock
  * does not name is never an add-on, whatever it contains.
  */
-/** What the lock records for one installed add-on. */
-export interface LockEntry {
-    package: string;
+/** One verified release of an add-on: what it is and what it was accepted on. */
+export interface PinnedVersion {
     version: string;
     integrity: string;
     installedAt: string;
@@ -19,6 +18,23 @@ export interface LockEntry {
         verifiedAt: string;
     };
 }
+/** What the lock records for one installed add-on. */
+export interface LockEntry extends PinnedVersion {
+    package: string;
+    /**
+     * #2100: a newer release an administrator's Update downloaded and verified.
+     * Its tarball waits in `.packages/`; the next start switches to it. Nothing
+     * else reads it, so until then the site runs `version`.
+     */
+    pending?: PinnedVersion;
+    /**
+     * #2100: the release this one replaced at the start that switched to it,
+     * kept (its folder as `.previous-<slug>`, its tarball in `.packages/`) until
+     * this one has loaded. Present at a later start only when that start never
+     * confirmed the switch, so the installer falls back to it.
+     */
+    previous?: PinnedVersion;
+}
 export interface LockFile {
     lockfileVersion: 1;
     addons: Record<string, LockEntry>;
@@ -26,6 +42,8 @@ export interface LockFile {
 export declare const LOCK_FILE_NAME = "addons-lock.json";
 /** Verified tarballs, kept so a restart needs no registry. Dot-named: discovery skips it. */
 export declare const PACKAGES_DIR_NAME = ".packages";
+/** #2100: the folder a switched-from release waits in until the new one has loaded. Dot-named: discovery skips it. */
+export declare const PREVIOUS_DIR_PREFIX = ".previous-";
 export declare function lockFilePath(addonsDir: string): string;
 /** The lock file, or an empty one when there is none. Throws when it exists and is not JSON. */
 export declare function readLockSync(addonsDir: string): LockFile;

package/lib/src/utils/addonLock.js

@@ -12,6 +12,8 @@ import path from 'path';
 export const LOCK_FILE_NAME = 'addons-lock.json';
 /** Verified tarballs, kept so a restart needs no registry. Dot-named: discovery skips it. */
 export const PACKAGES_DIR_NAME = '.packages';
+/** #2100: the folder a switched-from release waits in until the new one has loaded. Dot-named: discovery skips it. */
+export const PREVIOUS_DIR_PREFIX = '.previous-';
 export function lockFilePath(addonsDir) {
     return path.join(addonsDir, LOCK_FILE_NAME);
 }

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

@@ -1,30 +1,26 @@
 /**
  * Shared parsing/discovery for the `ngdpbase.managers.addons-manager.addons-path`
- * config value.
+ * config value, used by `AddonsManager` (runtime discovery), `ConfigurationManager`
+ * (the #672 boot-time "does this enabled addon exist" check) and the add-on
+ * config layer, so the three cannot drift (#924).
  *
- * #924: `AddonsManager` (real runtime discovery) and `ConfigurationManager`
- * (the #672 boot-time "does this enabled addon exist" safety check) used to
- * each carry their own copy of this logic. They drifted: `AddonsManager` was
- * updated for #673's `node_modules:<glob>` packaged-addon syntax, but the
- * validator's copy was not, so it resolved a `node_modules:` entry as a
- * literal (non-existent) directory and treated every packaged addon as
- * "unknown" — crashing boot the moment one was enabled. Consolidating the
- * parsing/matching into one module removes the class of bug, not just this
- * instance of it.
+ * #2102: the packaged model (`node_modules:<glob>` entries) is gone. A site
+ * config may still hold such an entry; it is ignored, never treated as a
+ * directory, and never stops the boot.
  */
-/** Prefix marking an addons-path entry as an npm-package glob rather than a directory. */
-export declare const NPM_ADDON_PREFIX = "node_modules:";
 export interface SplitAddonsPath {
     /** Plain directory entries (bundled/drop-in), not yet resolved to absolute. */
     directories: string[];
-    /** npm package name globs (the part after `node_modules:`), e.g. `@jwilleke/*-addon`. */
-    npmPatterns: string[];
+    /** Retired `node_modules:` entries (#2102): ignored; AddonsManager warns about them once at start. */
+    retired: string[];
 }
 /**
  * Coerce the raw config value (string or string[]) and split it into
- * filesystem directory entries vs. `node_modules:<glob>` npm patterns.
+ * filesystem directory entries and retired `node_modules:` entries.
  */
 export declare function splitAddonsPath(raw: unknown): SplitAddonsPath;
+/** The warning for one retired `node_modules:` entry (#2102). */
+export declare function retiredAddonsPathWarning(entry: string): string;
 /** The config key naming the add-ons to install (#1830). */
 export declare const ADDONS_INSTALL_KEY = "ngdpbase.addons.install";
 /**
@@ -35,42 +31,15 @@ export declare const ADDONS_INSTALL_KEY = "ngdpbase.addons.install";
 export declare function installedAddonsDir(dataFolder: string, cwd?: string): string;
 /** The slugs `ngdpbase.addons.install` names, from a merged or shipped+custom view. */
 export declare function configuredInstallSlugs(config: Record<string, unknown>): string[];
-/** Locate the `node_modules` directory to search for packaged addons (resolved from cwd). */
-export declare function findNodeModulesDir(cwd?: string): string | null;
-/**
- * Expand a `@scope/glob` (or bare `glob`) npm pattern to matching package
- * directories under `nmRoot`.
- */
-export declare function matchNpmPackageDirs(nmRoot: string, pattern: string): string[];
-/**
- * Best-effort addon identity for a packaged (npm) addon directory, derived
- * from its package-directory name alone — no module import, matching the
- * same boot-time-speed, no-module-loading design already accepted for the
- * directory-scan case (see `ConfigurationManager.assertConfiguredAddonsExist`).
- *
- * Follows the documented packaged-addon naming convention
- * (`@scope/<slug>-addon`, see docs/platform/deployment/addon-packaged.md):
- * strips a trailing `-addon` suffix if present, else returns the folder name
- * as-is.
- *
- * Caveat (same class as the existing directory-name heuristic): the addon's
- * *real* identity is whatever its module exports as `name` at runtime. A
- * package that doesn't follow the `-addon` naming convention, or whose
- * module exports a different `name`, won't be matched precisely here — this
- * is a validation-time approximation, not the source of truth.
- */
-export declare function deriveAddonSlugFromPackageDirName(dirName: string): string;
 /**
  * Canonical identity for an addon directory (#927), resolved the SAME
  * import-free way in every layer (discovery, `isEnabled`, the boot-time
- * validator) so the four historical identities (folder name, module `name`,
- * config key, manifest slug) can no longer drift:
+ * validator):
  *
- *   canonicalId = package.json `ngdpbase.slug`  ??  deriveAddonSlugFromPackageDirName(folder)
+ *   canonicalId = package.json `ngdpbase.slug`  ??  the folder name verbatim
  *
- * Reads `package.json` statically — never imports the module — which is what
- * lets the boot validator compute the exact id the runtime will register
- * under, instead of guessing. The module's exported `name` is a display
- * label validated against this at load time, not a source of identity.
+ * Reads `package.json` statically — never imports the module. The module's
+ * exported `name` is a display label validated against this at load time,
+ * not a source of identity.
  */
-export declare function resolveAddonSlug(addonDir: string, source: 'directory' | 'npm'): string;
+export declare function resolveAddonSlug(addonDir: string): string;

package/lib/src/utils/addonsPathResolver.js

@@ -1,36 +1,32 @@
 /**
  * Shared parsing/discovery for the `ngdpbase.managers.addons-manager.addons-path`
- * config value.
+ * config value, used by `AddonsManager` (runtime discovery), `ConfigurationManager`
+ * (the #672 boot-time "does this enabled addon exist" check) and the add-on
+ * config layer, so the three cannot drift (#924).
  *
- * #924: `AddonsManager` (real runtime discovery) and `ConfigurationManager`
- * (the #672 boot-time "does this enabled addon exist" safety check) used to
- * each carry their own copy of this logic. They drifted: `AddonsManager` was
- * updated for #673's `node_modules:<glob>` packaged-addon syntax, but the
- * validator's copy was not, so it resolved a `node_modules:` entry as a
- * literal (non-existent) directory and treated every packaged addon as
- * "unknown" — crashing boot the moment one was enabled. Consolidating the
- * parsing/matching into one module removes the class of bug, not just this
- * instance of it.
+ * #2102: the packaged model (`node_modules:<glob>` entries) is gone. A site
+ * config may still hold such an entry; it is ignored, never treated as a
+ * directory, and never stops the boot.
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { minimatch } from 'minimatch';
-/** Prefix marking an addons-path entry as an npm-package glob rather than a directory. */
-export const NPM_ADDON_PREFIX = 'node_modules:';
+/** The retired packaged-model prefix, recognised only so the entry can be ignored with a warning. */
+const RETIRED_PACKAGED_PREFIX = 'node_modules:';
 /**
  * Coerce the raw config value (string or string[]) and split it into
- * filesystem directory entries vs. `node_modules:<glob>` npm patterns.
+ * filesystem directory entries and retired `node_modules:` entries.
  */
 export function splitAddonsPath(raw) {
     const entries = Array.isArray(raw) ? raw.map(String) : [String(raw)];
     return {
-        directories: entries.filter(p => !p.startsWith(NPM_ADDON_PREFIX)),
-        npmPatterns: entries
-            .filter(p => p.startsWith(NPM_ADDON_PREFIX))
-            .map(p => p.slice(NPM_ADDON_PREFIX.length).trim())
-            .filter(Boolean)
+        directories: entries.filter(p => !p.trim().startsWith(RETIRED_PACKAGED_PREFIX)),
+        retired: entries.filter(p => p.trim().startsWith(RETIRED_PACKAGED_PREFIX))
     };
 }
+/** The warning for one retired `node_modules:` entry (#2102). */
+export function retiredAddonsPathWarning(entry) {
+    return `addons-path entry '${entry}' is no longer supported and is ignored; install add-ons with ngdpbase.addons.install`;
+}
 /** The config key naming the add-ons to install (#1830). */
 export const ADDONS_INSTALL_KEY = 'ngdpbase.addons.install';
 /**
@@ -46,69 +42,18 @@ export function configuredInstallSlugs(config) {
     const map = config[ADDONS_INSTALL_KEY];
     return map && typeof map === 'object' && !Array.isArray(map) ? Object.keys(map) : [];
 }
-/** Locate the `node_modules` directory to search for packaged addons (resolved from cwd). */
-export function findNodeModulesDir(cwd = process.cwd()) {
-    const nm = path.resolve(cwd, 'node_modules');
-    return fs.existsSync(nm) && fs.statSync(nm).isDirectory() ? nm : null;
-}
-/**
- * Expand a `@scope/glob` (or bare `glob`) npm pattern to matching package
- * directories under `nmRoot`.
- */
-export function matchNpmPackageDirs(nmRoot, pattern) {
-    let baseDir = nmRoot;
-    let nameGlob = pattern;
-    if (pattern.startsWith('@')) {
-        const slash = pattern.indexOf('/');
-        const scope = slash > 0 ? pattern.slice(0, slash) : pattern;
-        nameGlob = slash > 0 ? pattern.slice(slash + 1) : '*';
-        baseDir = path.join(nmRoot, scope);
-    }
-    if (!fs.existsSync(baseDir))
-        return [];
-    const out = [];
-    for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
-        if (entry.isDirectory() && !entry.name.startsWith('.') && minimatch(entry.name, nameGlob)) {
-            out.push(path.join(baseDir, entry.name));
-        }
-    }
-    return out;
-}
-/**
- * Best-effort addon identity for a packaged (npm) addon directory, derived
- * from its package-directory name alone — no module import, matching the
- * same boot-time-speed, no-module-loading design already accepted for the
- * directory-scan case (see `ConfigurationManager.assertConfiguredAddonsExist`).
- *
- * Follows the documented packaged-addon naming convention
- * (`@scope/<slug>-addon`, see docs/platform/deployment/addon-packaged.md):
- * strips a trailing `-addon` suffix if present, else returns the folder name
- * as-is.
- *
- * Caveat (same class as the existing directory-name heuristic): the addon's
- * *real* identity is whatever its module exports as `name` at runtime. A
- * package that doesn't follow the `-addon` naming convention, or whose
- * module exports a different `name`, won't be matched precisely here — this
- * is a validation-time approximation, not the source of truth.
- */
-export function deriveAddonSlugFromPackageDirName(dirName) {
-    const suffix = '-addon';
-    return dirName.endsWith(suffix) ? dirName.slice(0, -suffix.length) : dirName;
-}
 /**
  * Canonical identity for an addon directory (#927), resolved the SAME
  * import-free way in every layer (discovery, `isEnabled`, the boot-time
- * validator) so the four historical identities (folder name, module `name`,
- * config key, manifest slug) can no longer drift:
+ * validator):
  *
- *   canonicalId = package.json `ngdpbase.slug`  ??  deriveAddonSlugFromPackageDirName(folder)
+ *   canonicalId = package.json `ngdpbase.slug`  ??  the folder name verbatim
  *
- * Reads `package.json` statically — never imports the module — which is what
- * lets the boot validator compute the exact id the runtime will register
- * under, instead of guessing. The module's exported `name` is a display
- * label validated against this at load time, not a source of identity.
+ * Reads `package.json` statically — never imports the module. The module's
+ * exported `name` is a display label validated against this at load time,
+ * not a source of identity.
  */
-export function resolveAddonSlug(addonDir, source) {
+export function resolveAddonSlug(addonDir) {
     const dirName = path.basename(addonDir);
     const pkgPath = path.join(addonDir, 'package.json');
     try {
@@ -118,12 +63,7 @@ export function resolveAddonSlug(addonDir, source) {
             return slug.trim();
     }
     catch {
-        /* no/invalid package.json — fall back to the folder-derived id */
+        /* no/invalid package.json — fall back to the folder name */
     }
-    // Fallback when no slug is declared. npm packages follow the
-    // `@scope/<slug>-addon` publishing convention, so strip the conventional
-    // trailing `-addon`. A plain directory (bundled/drop-in) addon's folder
-    // name IS its identity verbatim — an addon may legitimately be named
-    // `something-addon` on disk — so never strip there.
-    return source === 'npm' ? deriveAddonSlugFromPackageDirName(dirName) : dirName;
+    return dirName;
 }

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -4,7 +4,7 @@ export declare const AUDIT_EVENT_NAME_PATTERN: RegExp;
 export declare const AUDIT_EVENT: {
     /** An add-on named in ngdpbase.addons.install installed into the data folder: package, version, sha512 and the repository its provenance names; recorded before it is written, which cannot proceed without it (#1830) */
     readonly ADDON_INSTALL: "addon-install";
-    /** An installed add-on moved to another version by an administrator's Update: who, and from which version to which (#1830; the Update action is not built yet) */
+    /** The release an installed add-on runs changed: an administrator's Update (who, the add-on, from and to version), recorded before the release is written, which cannot proceed without it; or core falling back to the previous release because the new one did not load (#2100) */
     readonly ADDON_UPDATE: "addon-update";
     /** An add-on refused or set aside by a check: its sha512, provenance, tarball contents, package.json, the lock file, or a changed installed folder (#1830) */
     readonly ADDON_VERIFY_FAILED: "addon-verify-failed";

package/lib/src/utils/auditEventNames.generated.js

@@ -11,7 +11,7 @@ export const AUDIT_EVENT_NAME_PATTERN = /^[a-z]+(-[a-z]+)+$/;
 export const AUDIT_EVENT = {
     /** An add-on named in ngdpbase.addons.install installed into the data folder: package, version, sha512 and the repository its provenance names; recorded before it is written, which cannot proceed without it (#1830) */
     ADDON_INSTALL: 'addon-install',
-    /** An installed add-on moved to another version by an administrator's Update: who, and from which version to which (#1830; the Update action is not built yet) */
+    /** The release an installed add-on runs changed: an administrator's Update (who, the add-on, from and to version), recorded before the release is written, which cannot proceed without it; or core falling back to the previous release because the new one did not load (#2100) */
     ADDON_UPDATE: 'addon-update',
     /** An add-on refused or set aside by a check: its sha512, provenance, tarball contents, package.json, the lock file, or a changed installed folder (#1830) */
     ADDON_VERIFY_FAILED: 'addon-verify-failed',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.35.0",
+  "version": "5.37.0",
   "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",
@@ -41,15 +41,14 @@
     "@types/multer": "^2.3.0",
     "@types/node": "^24.19.2",
     "better-sqlite3-multiple-ciphers": "^13.0.3",
-    "dotenv": "^18.0.8",
+    "dotenv": "^18.0.9",
     "express": "^5.3.0",
     "express-session": "^1.19.0",
     "fs-extra": "^11.4.1",
     "ipaddr.js": "^2.5.0",
-    "jose": "^6.2.12",
-    "linkedom": "^0.18.13",
+    "jose": "^6.2.13",
+    "linkedom": "^0.18.14",
     "markdown-it": "^14.3.3",
-    "minimatch": "^10.2.6",
     "minisearch": "7.2.0",
     "multer": "^2.4.0",
     "rrule-temporal": "2.2.8",