@velora-cms/server 0.11.0

package/dist/plugins/install-package-tarball.js

@@ -0,0 +1,73 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { extractArtifact } from "@velora-cms/plugin-package";
+import { installBuiltPackage } from "./install-built-package.js";
+import { loadTrustedKeys } from "./trusted-keys.js";
+import { checkPackageIdentity, describeVerifyResult, resolveSidecarPath, trustTierFor, verifyPackage } from "./verify-package.js";
+/** Best-effort cleanup shared by both extraction-temp-dir removal sites
+ * below. Cleanup is housekeeping, never the operation that matters — a
+ * failure here must never mask a real error already propagating out of
+ * the caller, so it only ever warns. */
+function removeTempDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
+    }
+    catch (cleanupError) {
+        console.warn(`[install-package-tarball] failed to remove temp extraction directory ${dir} — leaving it behind`, cleanupError);
+    }
+}
+export async function installPackageTarball(service, tarballPath, remoteUrl, setRemoteUrl, syncManifestFields, setPackagePath, options = {}) {
+    const defaultSidecar = resolveSidecarPath(tarballPath);
+    const sidecarPath = options.sidecarPath === undefined ? (existsSync(defaultSidecar) ? defaultSidecar : null) : options.sidecarPath;
+    const trustedKeys = options.trustedKeys ?? loadTrustedKeys();
+    const verification = await verifyPackage(tarballPath, sidecarPath, trustedKeys);
+    const extractDir = mkdtempSync(join(tmpdir(), "velora-install-"));
+    const extracted = await extractArtifact(tarballPath, extractDir);
+    if (!extracted.ok) {
+        // extractArtifact writes entries incrementally and does NOT roll back a
+        // partial extraction — deleting the directory is the caller's job.
+        // maxRetries/retryDelay: on Windows, files the extractor just finished
+        // writing (e.g. a corrupt-trailer archive that still decoded some real
+        // entries before its gzip integrity check failed at the end — observed
+        // directly while developing this module's own tests, by flipping the
+        // last byte of a real .tar.gz) can have their handles released
+        // asynchronously a moment after extraction settles, making an
+        // immediate recursive rmSync race an ENOTEMPTY — the same reality
+        // documented at every other rmSync of a just-written temp tree in this
+        // codebase (e.g. build-and-sideload.integration.test.ts's TMP_ROOT
+        // cleanup).
+        //
+        // Even with those retries, rmSync can still throw. Cleanup is
+        // best-effort housekeeping; the extraction failure below is the real,
+        // diagnosable problem. A cleanup failure must never mask it — leaving
+        // the temp directory behind is a far smaller cost than surfacing a
+        // filesystem error that names neither the real cause nor the package.
+        removeTempDir(extractDir);
+        throw new Error(`Package could not be extracted: ${extracted.reason}`);
+    }
+    try {
+        // The identity cross-check can only happen now: manifest.json does not
+        // exist until extraction. It DOWNGRADES a verified verdict, never
+        // upgrades one. The envelope it checks against comes off `verification`
+        // itself (the authenticated result from verifyPackage) — never from a
+        // second, unauthenticated read of the sidecar file.
+        const manifestPath = join(extractDir, "manifest.json");
+        if (!existsSync(manifestPath)) {
+            throw new Error(`No manifest.json found in ${tarballPath} — not a velora-plugin built package`);
+        }
+        const summary = JSON.parse(readFileSync(manifestPath, "utf8"));
+        const finalVerdict = checkPackageIdentity(verification, summary.id ?? "", summary.version ?? "");
+        describeVerifyResult(finalVerdict, tarballPath);
+        const outcome = await installBuiltPackage(service, extractDir, remoteUrl, setRemoteUrl, syncManifestFields, setPackagePath, { trustTier: trustTierFor(finalVerdict), seed: options.seed });
+        return { outcome, verification: finalVerdict };
+    }
+    finally {
+        // installBuiltPackage copies the package into the managed store
+        // (S122) before importing, so the temp extraction is disposable.
+        // Same cleanup as the extraction-failure branch above: a failure here
+        // must not mask a successful install, nor replace a genuine error
+        // already propagating out of installBuiltPackage.
+        removeTempDir(extractDir);
+    }
+}

package/dist/plugins/plugin-context.d.ts

@@ -0,0 +1,5 @@
+import type { ContentService } from "@velora-cms/content-service";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { PluginApiRouteContext } from "@velora-cms/plugin-sdk/manifest";
+import type { StructuredStorageAPI } from "./structured-storage-api.js";
+export declare function buildContext(pluginId: string, structuredStorageAPI: StructuredStorageAPI, contentService: ContentService, adapter: DatabaseAdapter): PluginApiRouteContext;

package/dist/plugins/plugin-context.js

@@ -0,0 +1,26 @@
+// Shared by plugin-api-routes.ts and hook-dispatcher.ts (S159) — both need
+// to build the exact same plugin-scoped capabilities object (structured
+// storage bound to the calling plugin's id, plus getPublishedContent), so
+// there is exactly ONE definition of that shape rather than two that could
+// drift. PluginApiRouteContext and the SDK's PluginHookContext are
+// structurally identical (manifest.ts), so this single builder satisfies
+// both call sites without a cast.
+export function buildContext(pluginId, structuredStorageAPI, contentService, adapter) {
+    return {
+        structuredStorage: {
+            defineTable: (schema) => structuredStorageAPI.defineTable(pluginId, schema),
+            insert: (tableName, data) => structuredStorageAPI.insert(pluginId, tableName, data),
+            update: (tableName, where, data) => structuredStorageAPI.update(pluginId, tableName, where, data),
+            delete: (tableName, where) => structuredStorageAPI.delete(pluginId, tableName, where),
+            query: (tableName) => structuredStorageAPI.query(pluginId, tableName),
+            transaction: (fn) => structuredStorageAPI.transaction(pluginId, fn),
+        },
+        getPublishedContent: async (contentId) => {
+            const node = await adapter.getContentNode(contentId);
+            if (!node || node.publishedAt === null)
+                return null;
+            const version = await contentService.getCurrentVersion(contentId);
+            return { id: node.id, documentTypeId: node.documentTypeId, data: version.data };
+        },
+    };
+}

package/dist/plugins/plugin-package-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Server-owned store for installed plugin packages (Session 122). A
+ * built package is COPIED here at install time and imported from here —
+ * both immediately and by the boot loader on every later restart — so
+ * the caller's extraction directory (usually an OS tmpdir) can vanish
+ * without breaking the installation.
+ *
+ * Layout: <root>/<pluginId>/<version>/ holding the ENTIRE extracted
+ * package. Copying the whole tree is load-bearing: server/package.json
+ * (Session 121's ESM marker) must ride along or plain-Node imports of
+ * server/plugin.js regress to CJS misparsing. Version-keyed paths are
+ * the ESM-cache answer: a future plugin UPDATE lands at a new path and
+ * therefore a new module URL. Re-installing the SAME version into a
+ * running process keeps serving the already-imported module for hooks
+ * (Node caches by URL) — accepted: install() attaches the manifest it
+ * just imported, so the running process is internally consistent, and
+ * the fresh files take over at next boot.
+ *
+ * pluginId and version become directory names here, so they must already
+ * be path-safe by the time they reach this module. The actual gate lives
+ * in install-built-package.ts's regexes (id: reverse-domain shape;
+ * version: path-safe characters with no ".."), run BEFORE storePackage()
+ * is called — validatePluginManifest itself only requires version to be
+ * a non-empty string (`z.string().min(1)`), so it is NOT what makes this
+ * safe. Any other caller of storePackage() must pre-vet its own id and
+ * version the same way; this module does no validation of its own.
+ */
+export declare function resolvePluginsDir(): string;
+export declare function packageStorePath(pluginId: string, version: string): string;
+export declare function storePackage(sourceDir: string, pluginId: string, version: string): string;
+export declare function removePluginPackages(pluginId: string): void;

package/dist/plugins/plugin-package-store.js

@@ -0,0 +1,64 @@
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/**
+ * Server-owned store for installed plugin packages (Session 122). A
+ * built package is COPIED here at install time and imported from here —
+ * both immediately and by the boot loader on every later restart — so
+ * the caller's extraction directory (usually an OS tmpdir) can vanish
+ * without breaking the installation.
+ *
+ * Layout: <root>/<pluginId>/<version>/ holding the ENTIRE extracted
+ * package. Copying the whole tree is load-bearing: server/package.json
+ * (Session 121's ESM marker) must ride along or plain-Node imports of
+ * server/plugin.js regress to CJS misparsing. Version-keyed paths are
+ * the ESM-cache answer: a future plugin UPDATE lands at a new path and
+ * therefore a new module URL. Re-installing the SAME version into a
+ * running process keeps serving the already-imported module for hooks
+ * (Node caches by URL) — accepted: install() attaches the manifest it
+ * just imported, so the running process is internally consistent, and
+ * the fresh files take over at next boot.
+ *
+ * pluginId and version become directory names here, so they must already
+ * be path-safe by the time they reach this module. The actual gate lives
+ * in install-built-package.ts's regexes (id: reverse-domain shape;
+ * version: path-safe characters with no ".."), run BEFORE storePackage()
+ * is called — validatePluginManifest itself only requires version to be
+ * a non-empty string (`z.string().min(1)`), so it is NOT what makes this
+ * safe. Any other caller of storePackage() must pre-vet its own id and
+ * version the same way; this module does no validation of its own.
+ */
+export function resolvePluginsDir() {
+    return resolve(process.env.VELORA_PLUGINS_DIR ?? join(process.cwd(), ".velora", "plugins"));
+}
+export function packageStorePath(pluginId, version) {
+    return join(resolvePluginsDir(), pluginId, version);
+}
+export function storePackage(sourceDir, pluginId, version) {
+    const target = packageStorePath(pluginId, version);
+    const resolvedSource = resolve(sourceDir);
+    // Self-destruction guard: if the caller passes the ALREADY-STORED copy
+    // back in as its own source (an operator re-running the install CLI
+    // against `.velora/plugins/<id>/<version>` itself, say), the rmSync
+    // below would delete the target and then try to copy from the very
+    // directory it just deleted — destroying the only copy of the package.
+    // Same-path is a no-op success; a source nested INSIDE the target is a
+    // hard error rather than a silent partial delete.
+    if (resolvedSource === target) {
+        return target;
+    }
+    if (resolvedSource.startsWith(target + sep)) {
+        throw new Error(`storePackage: source "${resolvedSource}" is inside the target directory "${target}" it would be copied into — refusing to delete the target first`);
+    }
+    // Replace, never merge — a leftover file from a previous copy of the
+    // same version must not survive into the new package's directory.
+    rmSync(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
+    mkdirSync(target, { recursive: true });
+    cpSync(resolvedSource, target, { recursive: true });
+    return target;
+}
+export function removePluginPackages(pluginId) {
+    const dir = join(resolvePluginsDir(), pluginId);
+    if (!existsSync(dir))
+        return;
+    rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
+}

package/dist/plugins/plugin-registry-service.d.ts

@@ -0,0 +1,227 @@
+import type { PluginRegistry, PrismaClient } from "@prisma/client";
+import { type CMSPlugin, type DatabaseDialect, type HookEvent, type HookHandler, type SerializerContribution } from "@velora-cms/plugin-sdk/manifest";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { TrustTier } from "./verify-package.js";
+/** A persisted plugin registry row (Prisma's shape, re-exported under a
+ * service-level name so route/consumer code doesn't couple to Prisma). */
+export type InstalledPlugin = PluginRegistry;
+/** Manifest failed Session 60's validation — carries the readable
+ * `path: message` errors for the future install route to surface. */
+export declare class PluginInstallError extends Error {
+    readonly errors: string[];
+    constructor(message: string, errors?: string[]);
+}
+/** 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 declare class PluginIncompatibleError extends PluginInstallError {
+    constructor(message: string);
+}
+export declare class PluginNotInstalledError extends Error {
+    constructor(pluginId: string);
+}
+/** 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 declare class PluginDependencyError extends PluginInstallError {
+    readonly missingDependencies: string[];
+    constructor(pluginId: string, missingDependencies: string[]);
+}
+/** 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 declare class PluginMigrationError extends PluginInstallError {
+    readonly migrationId: string;
+    readonly cause: unknown;
+    constructor(pluginId: string, migrationId: string, cause: unknown);
+}
+/** 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 declare class PluginNotActiveError extends Error {
+    constructor(pluginId: string);
+}
+/** 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 declare class PluginNotLoadedError extends Error {
+    constructor(pluginId: string);
+}
+/** 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 declare class StructuredDataCleanupRequiresConfirmationError extends Error {
+    readonly snapshotGroupId: string;
+    constructor(pluginId: string, snapshotGroupId: string);
+}
+/** One tracked document type that failed assertDocumentTypeDeletable(),
+ * resolved to a display name (not just the id uninstall() only tracks) so
+ * the caller — ultimately the admin uninstall dialog — can name it. */
+export interface PluginDocumentTypeBlocker {
+    documentTypeId: string;
+    documentType: string;
+    reason: "has-content" | "has-templates";
+    contentCount?: number;
+}
+/** 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 declare class PluginDocumentTypesInUseError extends Error {
+    readonly blockers: PluginDocumentTypeBlocker[];
+    constructor(pluginId: string, blockers: PluginDocumentTypeBlocker[]);
+}
+export interface PluginRegistryOptions {
+    activeDialect: DatabaseDialect;
+    structuredDataLifecycle?: {
+        snapshot: (pluginId: string) => Promise<string>;
+        cleanup: (pluginId: string) => Promise<void>;
+    };
+}
+export declare class PluginRegistryService {
+    private readonly prisma;
+    private readonly adapter;
+    private readonly manifests;
+    private readonly enabledIds;
+    private readonly activeDialect;
+    private readonly structuredDataLifecycle;
+    private readonly documentTypeService;
+    constructor(prisma: PrismaClient, adapter: DatabaseAdapter, options: PluginRegistryOptions);
+    /** 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. */
+    getInstalledPlugin(pluginId: string): Promise<InstalledPlugin | null>;
+    /** Installed AND enabled, or throw — the exact gate SimpleStorageAPI
+     * needs on every get()/set(). */
+    requireActivePlugin(pluginId: string): Promise<InstalledPlugin>;
+    /** 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: string): CMSPlugin | undefined;
+    /** Re-attach a loaded plugin's manifest to an existing installation
+     * (post-restart bridge for the boot-time plugin loader). */
+    attachManifest(manifest: CMSPlugin): Promise<void>;
+    /** 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: string): void;
+    /**
+     * 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.
+     */
+    install(manifest: unknown, opts?: {
+        trustTier?: TrustTier;
+    }): Promise<InstalledPlugin>;
+    /** 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). */
+    private rollbackMigrations;
+    /** 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. */
+    private rollbackDocumentTypes;
+    /**
+     * 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).
+     */
+    activate(pluginId: string): Promise<void>;
+    /**
+     * 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).
+     */
+    deactivate(pluginId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    uninstall(pluginId: string, options?: {
+        confirmStructuredDataCleanup?: boolean;
+    }): Promise<{
+        snapshotGroupId: string | null;
+    }>;
+    /** 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(): Array<{
+        pluginId: string;
+        serializers: SerializerContribution;
+    }>;
+    /** 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: HookEvent): Array<{
+        pluginId: string;
+        handler: HookHandler;
+    }>;
+}