@velora-cms/server 0.11.0

package/dist/plugins/plugin-registry-service.js

@@ -0,0 +1,636 @@
+import { validatePluginManifest, } from "@velora-cms/plugin-sdk/manifest";
+import { DocumentTypeInUseError, DocumentTypeService } from "@velora-cms/content-service";
+/** Manifest failed Session 60's validation — carries the readable
+ * `path: message` errors for the future install route to surface. */
+export class PluginInstallError extends Error {
+    errors;
+    constructor(message, errors = []) {
+        super(message);
+        this.errors = errors;
+        this.name = "PluginInstallError";
+    }
+}
+/** The manifest is valid but declares it doesn't support the site's
+ * active database — blocked with the declared reason, never a silent
+ * failure. Subclass of PluginInstallError so general install handling
+ * keeps working while the marketplace/UI can distinguish. */
+export class PluginIncompatibleError extends PluginInstallError {
+    constructor(message) {
+        super(message);
+        this.name = "PluginIncompatibleError";
+    }
+}
+export class PluginNotInstalledError extends Error {
+    constructor(pluginId) {
+        super(`No installed plugin with id "${pluginId}"`);
+        this.name = "PluginNotInstalledError";
+    }
+}
+/** The manifest declares pluginDependencies that aren't all installed AND
+ * active. Rejected with the full list, not just the first miss, so the
+ * installer can resolve everything in one pass rather than discovering
+ * missing dependencies one at a time. Subclass of PluginInstallError so
+ * existing catch sites keep working. */
+export class PluginDependencyError extends PluginInstallError {
+    missingDependencies;
+    constructor(pluginId, missingDependencies) {
+        super(`Plugin "${pluginId}" requires the following plugin(s), which must be installed and active first: ${missingDependencies.join(", ")}`);
+        this.missingDependencies = missingDependencies;
+        this.name = "PluginDependencyError";
+    }
+}
+/** A declared migration's up()/down() threw during install. Carries the
+ * plugin id, the specific migration id that failed, and the original
+ * cause — install() has already rolled back every migration that
+ * succeeded earlier in this same batch by the time this is thrown, so
+ * the plugin is left with no partial migration state and no registry
+ * row. Subclass of PluginInstallError so existing catch sites keep
+ * working. */
+export class PluginMigrationError extends PluginInstallError {
+    migrationId;
+    cause;
+    constructor(pluginId, migrationId, cause) {
+        super(`Plugin "${pluginId}"'s migration "${migrationId}" failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.migrationId = migrationId;
+        this.cause = cause;
+        this.name = "PluginMigrationError";
+    }
+}
+/** Installed but disabled — the gate SimpleStorageAPI needs before an
+ * HTTP request touches a plugin's stored values: a disabled plugin's
+ * views aren't mounted anywhere, so its storage shouldn't be live either. */
+export class PluginNotActiveError extends Error {
+    constructor(pluginId) {
+        super(`Plugin "${pluginId}" is installed but not active — enable it before using its storage`);
+        this.name = "PluginNotActiveError";
+    }
+}
+/** The plugin is installed but its manifest (the CODE — hooks are
+ * functions) isn't attached in this process, so it can't be activated:
+ * enabled:true for something that isn't running would be a lying state.
+ * Whatever loads plugin code at boot re-attaches via attachManifest. */
+export class PluginNotLoadedError extends Error {
+    constructor(pluginId) {
+        super(`Plugin "${pluginId}" is installed but its manifest is not loaded in this process — ` +
+            `attach it with attachManifest() before activating`);
+        this.name = "PluginNotLoadedError";
+    }
+}
+/** Thrown when uninstall() is called on a structured-storage plugin
+ * without confirmStructuredDataCleanup: true. The snapshot has ALREADY
+ * been taken by this point — nothing else has happened (no onUninstall,
+ * no migration rollback, no row deletion) — so retrying with
+ * confirmStructuredDataCleanup: true is always safe. */
+export class StructuredDataCleanupRequiresConfirmationError extends Error {
+    snapshotGroupId;
+    constructor(pluginId, snapshotGroupId) {
+        super(`Uninstalling structured-storage plugin "${pluginId}" requires confirmation to proceed — ` +
+            `its data was snapshotted as "${snapshotGroupId}". Call uninstall() again with ` +
+            `{ confirmStructuredDataCleanup: true } to actually delete its tables.`);
+        this.snapshotGroupId = snapshotGroupId;
+        this.name = "StructuredDataCleanupRequiresConfirmationError";
+    }
+}
+/** F1 QA fix wave: thrown by uninstall()'s document-type guard when one or
+ * MORE tracked document types are still in use — aggregated across EVERY
+ * tracked document type, not just the first to fail, so the operator sees
+ * the whole blocking set in one 409 instead of discovering it one retry at
+ * a time. Distinct from content-service's own DocumentTypeInUseError
+ * (which only ever describes a single document type, by id) — that class
+ * is still what assertDocumentTypeDeletable() throws per-call; this one is
+ * what uninstall() throws once it's walked every tracked document type and
+ * collected every failure. */
+export class PluginDocumentTypesInUseError extends Error {
+    blockers;
+    constructor(pluginId, blockers) {
+        super(`Cannot uninstall plugin "${pluginId}": the following document type(s) are still in use: ` +
+            blockers.map((blocker) => blocker.documentType).join(", "));
+        this.blockers = blockers;
+        this.name = "PluginDocumentTypesInUseError";
+    }
+}
+// install() runs a plugin's declared migrations and onInstall hook
+// before persisting the registry row (Session 72) — a failure at either
+// step leaves no partial state, matching activate()'s "hook before
+// state" philosophy. uninstall() checks every tracked document type is
+// safe to delete FIRST (before anything else, including the
+// structured-data snapshot), then runs onUninstall and rolls migrations
+// back before deleting the row, tolerating a missing manifest the same
+// way deactivate() does (destructive operations must never be blocked by
+// a missing manifest) — see both methods' own doc comments for the full
+// ordering rationale.
+export class PluginRegistryService {
+    prisma;
+    adapter;
+    // Attached manifests — the runtime half the DB row can't hold (hooks
+    // are functions). install() attaches automatically; after a server
+    // restart the loader (Session 66's federation loader, Month 6's local
+    // plugin loader) re-attaches via attachManifest().
+    manifests = new Map();
+    // In-memory mirror of the DB `enabled` flag (Session 112) — the public
+    // read path's per-request serializer lookup needs a sync, in-process
+    // answer and must not hit the DB on every content read. Kept in lockstep
+    // with every write to the flag below (install/activate/deactivate/
+    // uninstall/attachManifest); never read independently as a source of
+    // truth — requireActivePlugin() etc. still go through the DB row.
+    enabledIds = new Set();
+    activeDialect;
+    structuredDataLifecycle;
+    documentTypeService;
+    constructor(prisma, adapter, options) {
+        this.prisma = prisma;
+        this.adapter = adapter;
+        this.activeDialect = options.activeDialect;
+        this.structuredDataLifecycle = options.structuredDataLifecycle ?? {
+            snapshot: async () => "",
+            cleanup: async () => { },
+        };
+        this.documentTypeService = new DocumentTypeService(adapter);
+    }
+    /** Non-throwing lookup — the read every other method here already does
+     * privately, exposed for callers (SimpleStorageAPI) that need to check
+     * installation state without triggering a lifecycle transition. */
+    async getInstalledPlugin(pluginId) {
+        return this.prisma.pluginRegistry.findUnique({ where: { pluginId } });
+    }
+    /** Installed AND enabled, or throw — the exact gate SimpleStorageAPI
+     * needs on every get()/set(). */
+    async requireActivePlugin(pluginId) {
+        const row = await this.getInstalledPlugin(pluginId);
+        if (!row) {
+            throw new PluginNotInstalledError(pluginId);
+        }
+        if (!row.enabled) {
+            throw new PluginNotActiveError(pluginId);
+        }
+        return row;
+    }
+    /** Read-only exposure of the attached manifest for a plugin id — used
+     * by request-time dispatchers (plugin-api-routes.ts) that need a
+     * plugin's declared contributions without going through install()/
+     * activate() again. Returns undefined if the manifest isn't attached
+     * in this process (never installed, or a restart happened and
+     * attachManifest() hasn't re-attached it yet). */
+    getManifest(pluginId) {
+        return this.manifests.get(pluginId);
+    }
+    /** Re-attach a loaded plugin's manifest to an existing installation
+     * (post-restart bridge for the boot-time plugin loader). */
+    async attachManifest(manifest) {
+        const row = await this.prisma.pluginRegistry.findUnique({
+            where: { pluginId: manifest.id },
+        });
+        if (!row) {
+            throw new PluginNotInstalledError(manifest.id);
+        }
+        this.manifests.set(manifest.id, manifest);
+        // Post-restart bridge: the enabled mirror is process-local and empty
+        // on a fresh process, so re-attaching an already-active plugin must
+        // seed it from the row the lookup above already fetched.
+        if (row.enabled) {
+            this.enabledIds.add(manifest.id);
+        }
+        else {
+            this.enabledIds.delete(manifest.id);
+        }
+    }
+    /** The inverse of attachManifest: forget the in-process manifest so
+     * request-time consumers (the S89 apiRoutes dispatcher's
+     * requireActivePlugin/route lookup) stop answering for this plugin
+     * immediately — the uninstall route calls this so no restart is
+     * needed. A manifest that was never attached is a no-op. */
+    detachManifest(pluginId) {
+        this.manifests.delete(pluginId);
+    }
+    /**
+     * Validate a manifest (Session 60's validator — the contribution
+     * matrix included) and persist it. Session 127: the trust tier is now
+     * an optional caller-supplied value (`opts.trustTier`), defaulting to
+     * 'unverified' so every pre-S127 caller (which never supplied one)
+     * behaves identically. Local/dev plugins remain unsigned by
+     * definition and so always take the default.
+     * Installed ≠ active — rows start disabled; activate() is Session 63.
+     */
+    async install(manifest, opts) {
+        const result = validatePluginManifest(manifest);
+        if (!result.ok) {
+            throw new PluginInstallError(`Plugin manifest failed validation:\n${result.errors.map((e) => `  - ${e}`).join("\n")}`, result.errors);
+        }
+        const { manifest: plugin } = result;
+        // Database compatibility gate (Session 64): blocked with the
+        // declared reason, never a silent failure — the marketplace
+        // pre-filters by dialect, but sideloads land here too.
+        const { supported, unsupportedReason } = plugin.databaseCompatibility;
+        if (!supported.includes(this.activeDialect)) {
+            const reason = unsupportedReason?.[this.activeDialect];
+            throw new PluginIncompatibleError(`Plugin "${plugin.id}" does not support the active database (${this.activeDialect}). ` +
+                `Supported: ${supported.join(", ")}.${reason ? ` Reason: ${reason}` : ""}`);
+        }
+        const existing = await this.prisma.pluginRegistry.findUnique({
+            where: { pluginId: plugin.id },
+        });
+        if (existing) {
+            throw new PluginInstallError(`Plugin "${plugin.id}" is already installed (version ${existing.version})`);
+        }
+        // Dependency resolution (Session 71): every declared dependency must
+        // already be installed AND active — a merely-installed-but-disabled
+        // dependency's views/routes aren't actually running, so this plugin
+        // couldn't rely on it either. Collect every miss in one pass rather
+        // than failing on the first, so the installer sees the whole picture.
+        if (plugin.pluginDependencies && plugin.pluginDependencies.length > 0) {
+            const missing = [];
+            for (const dependencyId of plugin.pluginDependencies) {
+                const dependency = await this.prisma.pluginRegistry.findUnique({
+                    where: { pluginId: dependencyId },
+                });
+                if (!dependency || !dependency.enabled) {
+                    missing.push(dependencyId);
+                }
+            }
+            if (missing.length > 0) {
+                throw new PluginDependencyError(plugin.id, missing);
+            }
+        }
+        // Migrations + onInstall (Session 72): the last gate before the
+        // registry row exists, so a failure here leaves no partial state —
+        // same "hook before state" philosophy as activate(). ctx is
+        // deliberately {} today (PluginMigrationContext, manifest.ts) — this
+        // is the only sense in which migrations run "against whichever Tier
+        // 1 database is active": the activeDialect check above, not a live
+        // adapter connection plugins could use to write raw SQL.
+        const applied = [];
+        if (plugin.migrations && plugin.migrations.length > 0) {
+            for (const migration of plugin.migrations) {
+                try {
+                    await migration.up({});
+                    await this.prisma.pluginMigrationRecord.create({
+                        data: { pluginId: plugin.id, migrationId: migration.id },
+                    });
+                    applied.push(migration);
+                }
+                catch (cause) {
+                    await this.rollbackMigrations(plugin.id, applied);
+                    throw new PluginMigrationError(plugin.id, migration.id, cause);
+                }
+            }
+        }
+        // Document types the manifest provisions at install (Month 8, Session
+        // 88) — only section/template plugins carry this contribution. Runs
+        // AFTER migrations (mirrors why onInstall already runs after
+        // migrations) and BEFORE onInstall, so a plugin's own install hook can
+        // rely on its document types already existing.
+        //
+        // Two-phase (Session 149, Task 2 amendment): a manifest declares
+        // treeRules' allowedParentTypes/allowedChildTypes by document type
+        // NAME (there's no id to reference at manifest-authoring time — the
+        // server mints one per entry, right here), but
+        // ContentService.assertValidPlacement compares those arrays against
+        // the real minted ids. Before this fix the name strings rode straight
+        // through to storage and could never match, silently breaking any
+        // cross-referencing treeRules (plugins/commerce never hit this — both
+        // its document types declare empty treeRules arrays).
+        //
+        // Phase 1 creates every declared type with its name-bearing arrays
+        // stripped (allowedAtRoot needs no resolution and is preserved),
+        // recording declaredName -> mintedId as each row is created. Phase 2
+        // walks the ORIGINAL declared requests, resolves every name against
+        // that map, and applies the resolved treeRules via the same update
+        // surface the admin Document Type editor's PUT /api/document-types/:id
+        // route uses (apps/server/src/routes/document-types.ts) —
+        // adapter.updateDocumentType, a full replace of the mutable
+        // definition (kind/defaultTemplateId untouched). There's no
+        // DocumentTypeService wrapper for update (the route calls the adapter
+        // directly too), so this mirrors that rather than inventing one. A
+        // name that isn't one of THIS plugin's own declared types is an
+        // install failure — the single try/catch below rolls back every
+        // document type phase 1 created (plus migrations) exactly like a
+        // phase-1 failure already did.
+        const createdDocumentTypes = [];
+        if (plugin.type === "section" || plugin.type === "template") {
+            const declared = plugin.contributions.documentTypes ?? [];
+            try {
+                const mintedIdByName = new Map();
+                for (const request of declared) {
+                    // Fail before the side effect: a manifest declaring the same
+                    // document type name twice would otherwise let
+                    // mintedIdByName.set() below silently overwrite the first
+                    // minted id with the second (last-wins) — every name resolution
+                    // in phase 2 is load-bearing for tree-rule enforcement, so a
+                    // silently ambiguous name must never reach it.
+                    if (mintedIdByName.has(request.name)) {
+                        throw new PluginInstallError(`Plugin "${plugin.id}" declares document type "${request.name}" more than once — document type names must be unique within a single plugin`);
+                    }
+                    const phase1Request = request.kind === "page"
+                        ? {
+                            ...request,
+                            treeRules: {
+                                allowedAtRoot: request.treeRules.allowedAtRoot,
+                                allowedParentTypes: [],
+                                allowedChildTypes: [],
+                            },
+                        }
+                        : request;
+                    const created = await this.documentTypeService.createDocumentType(phase1Request);
+                    await this.prisma.pluginDocumentType.create({
+                        data: { pluginId: plugin.id, documentTypeId: created.id },
+                    });
+                    createdDocumentTypes.push(created);
+                    mintedIdByName.set(request.name, created.id);
+                }
+                for (const [index, request] of declared.entries()) {
+                    if (request.kind !== "page")
+                        continue;
+                    const { allowedParentTypes, allowedChildTypes } = request.treeRules;
+                    if (allowedParentTypes.length === 0 && allowedChildTypes.length === 0)
+                        continue;
+                    const resolveNames = (names) => names.map((name) => {
+                        const id = mintedIdByName.get(name);
+                        if (!id) {
+                            throw new PluginInstallError(`Plugin "${plugin.id}" document type "${request.name}" declares a treeRules reference to "${name}", ` +
+                                `which is not one of this plugin's own declared document types (${declared.map((d) => d.name).join(", ")})`);
+                        }
+                        return id;
+                    });
+                    const createdType = createdDocumentTypes[index];
+                    await this.adapter.updateDocumentType(createdType.id, {
+                        name: createdType.name,
+                        icon: createdType.icon,
+                        fields: createdType.fields,
+                        tabs: createdType.tabs,
+                        treeRules: {
+                            allowedAtRoot: request.treeRules.allowedAtRoot,
+                            allowedParentTypes: resolveNames(allowedParentTypes),
+                            allowedChildTypes: resolveNames(allowedChildTypes),
+                        },
+                    });
+                }
+            }
+            catch (cause) {
+                await this.rollbackDocumentTypes(plugin.id, createdDocumentTypes);
+                await this.rollbackMigrations(plugin.id, applied);
+                throw cause;
+            }
+        }
+        try {
+            await plugin.onInstall?.();
+        }
+        catch (cause) {
+            await this.rollbackDocumentTypes(plugin.id, createdDocumentTypes);
+            await this.rollbackMigrations(plugin.id, applied);
+            throw cause;
+        }
+        const row = await this.prisma.pluginRegistry.create({
+            data: {
+                pluginId: plugin.id,
+                name: plugin.name,
+                type: plugin.type,
+                version: plugin.version,
+                // Session 127: the tier a verified install earned, defaulting to
+                // the pre-S127 literal so every existing caller is unchanged.
+                trustTier: opts?.trustTier ?? "unverified",
+                storageType: plugin.databaseCompatibility.storageType,
+                enabled: false,
+            },
+        });
+        this.manifests.set(plugin.id, plugin);
+        // Mirror the row just persisted — install() always writes enabled:
+        // false today, so this is a no-op in practice, but it's written
+        // against row.enabled (not a hardcoded false) so a future
+        // auto-activate-on-install path can't silently desync the mirror.
+        if (row.enabled) {
+            this.enabledIds.add(plugin.id);
+        }
+        return row;
+    }
+    /** Roll back a batch of already-applied migrations in reverse order,
+     * removing each tracking row as it rolls back. Shared by install()'s
+     * two failure paths (a later migration failing, or onInstall failing
+     * after all migrations succeeded). */
+    async rollbackMigrations(pluginId, migrations) {
+        for (const migration of [...migrations].reverse()) {
+            await migration.down({});
+            await this.prisma.pluginMigrationRecord.deleteMany({
+                where: { pluginId, migrationId: migration.id },
+            });
+        }
+    }
+    /** Delete every document type created so far in THIS install() call, in
+     * reverse order, plus its PluginDocumentType tracking row — always safe
+     * to hard-delete without assertDocumentTypeDeletable first, since these
+     * were just created inside this same call and cannot yet have any
+     * content or template referencing them. Shared by install()'s two
+     * documentTypes-era failure paths (a later entry failing, or onInstall
+     * failing after all entries succeeded) — same shape as
+     * rollbackMigrations. */
+    async rollbackDocumentTypes(pluginId, documentTypes) {
+        for (const documentType of [...documentTypes].reverse()) {
+            await this.documentTypeService.deleteDocumentType(documentType.id);
+            await this.prisma.pluginDocumentType.deleteMany({
+                where: { pluginId, documentTypeId: documentType.id },
+            });
+        }
+    }
+    /**
+     * Enable an installed plugin. Hooks fire on TRANSITIONS only —
+     * activating an already-active plugin is a no-op. onActivate runs
+     * BEFORE enabled:true is persisted: a plugin that fails to start
+     * stays disabled. Requires the manifest to be attached (installed
+     * but unloaded code can't be "active" — that would be a lying state).
+     */
+    async activate(pluginId) {
+        const row = await this.prisma.pluginRegistry.findUnique({ where: { pluginId } });
+        if (!row) {
+            throw new PluginNotInstalledError(pluginId);
+        }
+        if (row.enabled) {
+            return;
+        }
+        const manifest = this.manifests.get(pluginId);
+        if (!manifest) {
+            throw new PluginNotLoadedError(pluginId);
+        }
+        await manifest.onActivate?.();
+        await this.prisma.pluginRegistry.update({
+            where: { pluginId },
+            data: { enabled: true },
+        });
+        this.enabledIds.add(pluginId);
+    }
+    /**
+     * Disable an installed plugin without losing its configuration or
+     * data. Deliberately asymmetric with activate(): enabled:false is
+     * persisted FIRST and onDeactivate runs after (a hook error
+     * propagates, but the plugin is already off — you deactivate things
+     * BECAUSE they're broken, so disabling must never be blocked), and a
+     * missing manifest is fine (post-restart you can still switch a
+     * plugin off; the hook is skipped).
+     */
+    async deactivate(pluginId) {
+        const row = await this.prisma.pluginRegistry.findUnique({ where: { pluginId } });
+        if (!row) {
+            throw new PluginNotInstalledError(pluginId);
+        }
+        if (!row.enabled) {
+            return;
+        }
+        await this.prisma.pluginRegistry.update({
+            where: { pluginId },
+            data: { enabled: false },
+        });
+        this.enabledIds.delete(pluginId);
+        await this.manifests.get(pluginId)?.onDeactivate?.();
+    }
+    /**
+     * Remove an installed plugin. For structured-storage plugins, the
+     * confirmation gate is checked FIRST — before onUninstall, before
+     * migration rollback, before anything else destructive (Month 8,
+     * Session 87): a snapshot is always taken, and if the caller hasn't
+     * passed confirmStructuredDataCleanup: true, uninstall() throws
+     * StructuredDataCleanupRequiresConfirmationError right there, having
+     * changed nothing else — the row, migrations, and manifest are all
+     * untouched, so retrying with confirmation is always safe. Only once
+     * past that gate does the rest of teardown proceed: fallible cleanup
+     * (onUninstall, migration rollback) runs BEFORE the irreversible row
+     * delete (Session 72) — a failure there leaves the plugin
+     * still-installed and retryable rather than orphaned. Order is
+     * stack-shaped, inverse of install(): onUninstall (the last thing
+     * installed) runs first, migrations (the first thing installed) roll
+     * back last, in LIFO order — reversing manifest.migrations' own
+     * declared array, the same source of truth install() walked forward
+     * through, rather than sorting the tracked rows by appliedAt. Two
+     * migrations applied back-to-back inside the same install() call can
+     * land the exact same DateTime (Postgres' now() has finite, and on
+     * some platforms coarse, resolution — reproduced on real CI: two
+     * inserts a few microseconds apart still tied, and ORDER BY gives no
+     * guarantee which tied row sorts first), which silently rolled
+     * migrations back out of order. The manifest array has no such
+     * ambiguity: array position is exact. If the manifest isn't attached
+     * (no server restart re-attached it), both are silently skipped —
+     * can't call functions that don't exist in this process — matching
+     * deactivate()'s "destructive operations must never be blocked by a
+     * missing manifest," applied more strongly here since uninstall is far
+     * less reversible than deactivate. The actual structured-data cleanup
+     * (dropping the plugin's tables) runs only after confirmation, right
+     * before the registry row is deleted.
+     */
+    async uninstall(pluginId, options) {
+        const row = await this.prisma.pluginRegistry.findUnique({ where: { pluginId } });
+        if (!row) {
+            throw new PluginNotInstalledError(pluginId);
+        }
+        // Document-type deletion guard, checked FIRST — cheaper and
+        // unconditional (never confirmable, unlike structured-data cleanup
+        // below), so it fails fast before any other side effect. A blocked
+        // document type is not a "confirm to proceed" situation: the caller
+        // must resolve the underlying content/template references themselves.
+        // F1 QA fix wave: walks every tracked document type and aggregates
+        // ALL failures (not just the first) into one PluginDocumentTypesInUseError
+        // — an admin with three content-bearing document types used to learn
+        // about them one at a time, each retry surfacing the next. The name
+        // comes from adapter.getDocumentType() (an existing, already-
+        // implemented-for-all-three-dialects read — not a new adapter method)
+        // since the tracking row itself only has the id.
+        const trackedDocumentTypes = await this.prisma.pluginDocumentType.findMany({ where: { pluginId } });
+        const blockers = [];
+        for (const tracked of trackedDocumentTypes) {
+            try {
+                await this.documentTypeService.assertDocumentTypeDeletable(tracked.documentTypeId);
+            }
+            catch (error) {
+                if (!(error instanceof DocumentTypeInUseError))
+                    throw error;
+                const documentType = await this.adapter.getDocumentType(tracked.documentTypeId);
+                blockers.push({
+                    documentTypeId: tracked.documentTypeId,
+                    documentType: documentType?.name ?? tracked.documentTypeId,
+                    reason: error.reason,
+                    contentCount: error.contentCount,
+                });
+            }
+        }
+        if (blockers.length > 0) {
+            throw new PluginDocumentTypesInUseError(pluginId, blockers);
+        }
+        // Checked next, before onUninstall/migration rollback/anything else
+        // — a rejected call must be safe to retry, which means nothing else
+        // can have happened yet when this throws. simple-storage plugins never
+        // take this branch, so snapshotGroupId stays null for them (Task 6:
+        // the CONFIRMED pass's minted id is threaded through to the return
+        // below — the unconfirmed pass still throws with its id on the error,
+        // as before).
+        let snapshotGroupId = null;
+        if (row.storageType === "structured") {
+            snapshotGroupId = await this.structuredDataLifecycle.snapshot(pluginId);
+            if (!options?.confirmStructuredDataCleanup) {
+                throw new StructuredDataCleanupRequiresConfirmationError(pluginId, snapshotGroupId);
+            }
+        }
+        const manifest = this.manifests.get(pluginId);
+        if (manifest) {
+            await manifest.onUninstall?.();
+            const records = await this.prisma.pluginMigrationRecord.findMany({ where: { pluginId } });
+            const trackedByMigrationId = new Map(records.map((record) => [record.migrationId, record]));
+            // Reversing manifest.migrations for rollback order (rather than
+            // trusting the tracked rows' appliedAt) assumes that array is
+            // APPEND-ONLY for an already-installed plugin: a plugin update may
+            // only add new entries after the existing ones, never reorder or
+            // remove entries an earlier install already applied. Violate that
+            // and this reversal silently rolls back in the wrong order --
+            // there is no other signal here to detect or correct for it.
+            for (const migration of [...(manifest.migrations ?? [])].reverse()) {
+                const record = trackedByMigrationId.get(migration.id);
+                if (!record)
+                    continue;
+                await migration.down({});
+                await this.prisma.pluginMigrationRecord.delete({ where: { id: record.id } });
+            }
+        }
+        if (row.storageType === "structured") {
+            await this.structuredDataLifecycle.cleanup(pluginId);
+        }
+        for (const tracked of trackedDocumentTypes) {
+            await this.documentTypeService.deleteDocumentType(tracked.documentTypeId);
+        }
+        await this.prisma.pluginDocumentType.deleteMany({ where: { pluginId } });
+        await this.prisma.pluginRegistry.delete({ where: { pluginId } });
+        // Sweeps any tracking rows the unattached-manifest path above
+        // couldn't roll back individually (down() needs the manifest's
+        // function reference, which doesn't exist without it).
+        await this.prisma.pluginMigrationRecord.deleteMany({ where: { pluginId } });
+        this.manifests.delete(pluginId);
+        this.enabledIds.delete(pluginId);
+        return { snapshotGroupId };
+    }
+    /** Active plugins with an attached manifest declaring serializers —
+     * the public read path's per-request lookup (Session 112). Sync and
+     * in-memory: an active-but-unattached plugin (the standing S89
+     * no-boot-loader gap) is skipped exactly like its apiRoutes are. */
+    listActiveSerializerContributions() {
+        const out = [];
+        for (const [pluginId, manifest] of this.manifests) {
+            if (!this.enabledIds.has(pluginId))
+                continue;
+            const serializers = manifest.contributions.serializers;
+            if (serializers)
+                out.push({ pluginId, serializers });
+        }
+        return out;
+    }
+    /** Active plugins with an attached manifest declaring a handler for
+     * this specific event — the hook dispatcher's per-event lookup (S159).
+     * Sync and in-memory, same shape as listActiveSerializerContributions:
+     * an active-but-unattached plugin is skipped exactly like its apiRoutes
+     * and serializers are. */
+    listActiveHookContributions(event) {
+        const out = [];
+        for (const [pluginId, manifest] of this.manifests) {
+            if (!this.enabledIds.has(pluginId))
+                continue;
+            const hooks = manifest.contributions.hooks;
+            const handler = hooks?.[event];
+            if (handler)
+                out.push({ pluginId, handler });
+        }
+        return out;
+    }
+}

package/dist/plugins/seed-template-content.d.ts

@@ -0,0 +1,23 @@
+import type { PrismaClient } from "@prisma/client";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+export interface SeedTemplateContentDeps {
+    prisma: PrismaClient;
+    adapter: DatabaseAdapter;
+}
+export type SeedTemplateContentResult = "none" | "invalid" | "skipped" | {
+    created: number;
+};
+/**
+ * Seeds a template plugin's sample-content.json as real, published
+ * content — creation order in the file IS the seed order (parents
+ * precede children per D1's documented contract), and every node is
+ * created THEN published, so it lands as version 1, currently published,
+ * matching the immutable-versioning path exactly the way a human editor
+ * publishing through the admin UI would produce.
+ *
+ * D2 governs every early return here: idempotent-by-skip (no duplicates
+ * on a second install/second call) and non-fatal (a seeding problem never
+ * unwinds an otherwise-successful plugin install — the caller's install
+ * stands regardless of what this function returns).
+ */
+export declare function seedTemplateSampleContent(deps: SeedTemplateContentDeps, pluginId: string, storedPackageDir: string, createdBy?: string): Promise<SeedTemplateContentResult>;