@velora-cms/server 0.11.0

package/dist/media/media-service.js

@@ -0,0 +1,162 @@
+import { randomUUID } from "node:crypto";
+import { CreateBucketCommand, DeleteObjectCommand, GetObjectCommand, HeadBucketCommand, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+// Defaults match the minio service in docker-compose.yml (same treatment as
+// POSTGRES_TEST_URL), so local dev works with zero required config. Point
+// these at real S3/R2 via .env — see .env.example.
+export function mediaStorageConfigFromEnv() {
+    return {
+        endpoint: process.env.S3_ENDPOINT ?? "http://localhost:9000",
+        region: process.env.S3_REGION ?? "us-east-1",
+        accessKeyId: process.env.S3_ACCESS_KEY_ID ?? "velora",
+        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY ?? "velora-secret",
+        bucket: process.env.S3_BUCKET ?? "velora-media",
+    };
+}
+export class MediaService {
+    prisma;
+    config;
+    dialect;
+    s3;
+    constructor(prisma, config, 
+    // Which Prisma provider the injected client is actually querying against
+    // (postgresql | mysql | sqlite) — needed by list()'s search filter,
+    // see buildFilenameSearchFilter below. Passed in rather than
+    // rediscovered here so this class stays agnostic of how the caller
+    // resolved it (db/prisma.ts's VELORA_PRISMA_CLIENT_DIR-derived value in
+    // the real app, a literal in tests).
+    dialect) {
+        this.prisma = prisma;
+        this.config = config;
+        this.dialect = dialect;
+        this.s3 = new S3Client({
+            endpoint: config.endpoint,
+            region: config.region,
+            credentials: {
+                accessKeyId: config.accessKeyId,
+                secretAccessKey: config.secretAccessKey,
+            },
+            // MinIO and R2 route by path, not by bucket subdomain — and a
+            // localhost endpoint can't do virtual-hosted buckets at all.
+            forcePathStyle: true,
+        });
+    }
+    // Idempotent; safe to call on startup or from tests. Only creates the
+    // bucket when it doesn't exist yet.
+    async ensureBucket() {
+        try {
+            await this.s3.send(new HeadBucketCommand({ Bucket: this.config.bucket }));
+        }
+        catch {
+            await this.s3.send(new CreateBucketCommand({ Bucket: this.config.bucket }));
+        }
+    }
+    async upload(input) {
+        const id = randomUUID();
+        const storageKey = `${id}/${sanitizeForKey(input.filename)}`;
+        await this.s3.send(new PutObjectCommand({
+            Bucket: this.config.bucket,
+            Key: storageKey,
+            Body: input.data,
+            ContentType: input.mimeType,
+            ContentLength: input.data.length,
+        }));
+        try {
+            const row = await this.prisma.mediaFile.create({
+                data: {
+                    id,
+                    filename: input.filename,
+                    mimeType: input.mimeType,
+                    size: input.data.length,
+                    storageKey,
+                    url: this.canonicalUrl(storageKey),
+                    uploadedBy: input.uploadedBy,
+                },
+            });
+            return toMediaFile(row);
+        }
+        catch (error) {
+            // Metadata is the source of truth — don't leave an object around that
+            // no metadata row points to.
+            await this.s3
+                .send(new DeleteObjectCommand({ Bucket: this.config.bucket, Key: storageKey }))
+                .catch(() => undefined);
+            throw error;
+        }
+    }
+    async getById(id) {
+        const row = await this.prisma.mediaFile.findUnique({ where: { id } });
+        return row ? toMediaFile(row) : null;
+    }
+    // Newest-first, cursor-paginated (cursor = previous page's last id,
+    // same semantics as the content list endpoints). Prisma positions the
+    // cursor row within the compound order and skips it.
+    async list(options) {
+        const rows = await this.prisma.mediaFile.findMany({
+            where: options.search
+                ? { filename: buildFilenameSearchFilter(options.search, this.dialect) }
+                : undefined,
+            orderBy: [{ uploadedAt: "desc" }, { id: "desc" }],
+            take: options.limit,
+            ...(options.cursor ? { cursor: { id: options.cursor }, skip: 1 } : {}),
+        });
+        return rows.map(toMediaFile);
+    }
+    // Time-limited presigned GET — works against private buckets, which is
+    // why downloads go through this rather than the stored canonical url.
+    async getDownloadUrl(id, expiresInSeconds = 900) {
+        const row = await this.prisma.mediaFile.findUnique({ where: { id } });
+        if (!row) {
+            throw new Error(`Media file not found: ${id}`);
+        }
+        return getSignedUrl(this.s3, new GetObjectCommand({ Bucket: this.config.bucket, Key: row.storageKey }), { expiresIn: expiresInSeconds });
+    }
+    async delete(id) {
+        const row = await this.prisma.mediaFile.findUnique({ where: { id } });
+        if (!row) {
+            throw new Error(`Media file not found: ${id}`);
+        }
+        await this.s3.send(new DeleteObjectCommand({ Bucket: this.config.bucket, Key: row.storageKey }));
+        await this.prisma.mediaFile.delete({ where: { id } });
+    }
+    canonicalUrl(storageKey) {
+        const encodedKey = storageKey.split("/").map(encodeURIComponent).join("/");
+        return `${this.config.endpoint.replace(/\/$/, "")}/${this.config.bucket}/${encodedKey}`;
+    }
+}
+// Case-insensitive filename search, built per the active Prisma provider's
+// verified capabilities (Session 131 walkthrough, task-4-report.md step 13
+// — SQLite 500'd here because `mode: "insensitive"` isn't a real argument
+// outside the postgresql provider):
+//  - postgresql: bare `contains` compiles to a case-SENSITIVE LIKE, so
+//    Prisma's `mode: "insensitive"` is genuinely required there.
+//  - mysql: the generated client rejects `mode` (Prisma only accepts it
+//    for postgresql). Dropping `mode` assumes MySQL 8's default collation
+//    (utf8mb4_0900_ai_ci); case-sensitive collations silently degrade to
+//    case-sensitive search. Velora does not pin collation; the
+//    collation-independent fix (S104 LOWER()-both-sides) is backlogged.
+//  - sqlite: same rejection as mysql, and dropping `mode` is safe for the
+//    same reason — `contains` compiles to `LIKE`, which SQLite evaluates
+//    ASCII-case-insensitively by default.
+// Verified empirically against real postgres/mysql/sqlite instances before
+// writing this — don't "simplify" this back to one shape for every
+// dialect; that's exactly what caused the SQLite 500.
+export function buildFilenameSearchFilter(search, dialect) {
+    return dialect === "postgresql" ? { contains: search, mode: "insensitive" } : { contains: search };
+}
+// Original filename lives untouched in metadata; the object key only keeps
+// characters that are safe in S3 keys and URLs.
+function sanitizeForKey(filename) {
+    return filename.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function toMediaFile(row) {
+    return {
+        id: row.id,
+        filename: row.filename,
+        mimeType: row.mimeType,
+        size: row.size,
+        url: row.url,
+        uploadedBy: row.uploadedBy,
+        uploadedAt: row.uploadedAt.toISOString(),
+    };
+}

package/dist/plugins/boot-plugin-loader.d.ts

@@ -0,0 +1,32 @@
+import type { PrismaClient } from "@prisma/client";
+import type { PluginRegistryService } from "./plugin-registry-service.js";
+export interface BootLog {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+export interface BootPluginsReport {
+    attached: string[];
+    skipped: {
+        pluginId: string;
+        reason: string;
+    }[];
+    failed: {
+        pluginId: string;
+        reason: string;
+    }[];
+}
+/**
+ * The registry-driven boot loader (Session 122) — the caller of the
+ * attachManifest() bridge Sessions 62-63 designed for exactly this.
+ * Runs once at boot, AFTER the registry exists and BEFORE the server
+ * answers requests: for every installed plugin row (enabled or not —
+ * attaching a disabled plugin's manifest is what lets activate() work
+ * after a restart without a reinstall), import the stored package's
+ * self-contained server/plugin.js (Session 121), re-validate, attach.
+ *
+ * Failure posture (the Session 91 precedent): one plugin failing NEVER
+ * blocks boot or any other plugin. A failed/missing package logs a
+ * warning and its routes keep the existing 503-with-clear-cause
+ * behavior until reinstall.
+ */
+export declare function bootInstalledPlugins(prisma: PrismaClient, registry: PluginRegistryService, log: BootLog): Promise<BootPluginsReport>;

package/dist/plugins/boot-plugin-loader.js

@@ -0,0 +1,57 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { validatePluginManifest } from "@velora-cms/plugin-sdk/manifest";
+/**
+ * The registry-driven boot loader (Session 122) — the caller of the
+ * attachManifest() bridge Sessions 62-63 designed for exactly this.
+ * Runs once at boot, AFTER the registry exists and BEFORE the server
+ * answers requests: for every installed plugin row (enabled or not —
+ * attaching a disabled plugin's manifest is what lets activate() work
+ * after a restart without a reinstall), import the stored package's
+ * self-contained server/plugin.js (Session 121), re-validate, attach.
+ *
+ * Failure posture (the Session 91 precedent): one plugin failing NEVER
+ * blocks boot or any other plugin. A failed/missing package logs a
+ * warning and its routes keep the existing 503-with-clear-cause
+ * behavior until reinstall.
+ */
+export async function bootInstalledPlugins(prisma, registry, log) {
+    const report = { attached: [], skipped: [], failed: [] };
+    const rows = await prisma.pluginRegistry.findMany();
+    for (const row of rows) {
+        if (!row.packagePath) {
+            report.skipped.push({
+                pluginId: row.pluginId,
+                reason: "no stored package recorded (live-source plugin, or an install that never recorded its package)",
+            });
+            continue;
+        }
+        try {
+            const entryPath = join(row.packagePath, "server", "plugin.js");
+            if (!existsSync(entryPath)) {
+                report.failed.push({ pluginId: row.pluginId, reason: `package missing at ${entryPath}` });
+                log.warn(`[plugin-boot] ${row.pluginId}: package missing at ${entryPath} — routes will 503 until reinstall`);
+                continue;
+            }
+            const mod = (await import(pathToFileURL(entryPath).href));
+            if (!mod.default) {
+                throw new Error("server/plugin.js has no default export");
+            }
+            const validated = validatePluginManifest(mod.default);
+            if (!validated.ok) {
+                throw new Error(`manifest failed validation: ${validated.errors.join("; ")}`);
+            }
+            await registry.attachManifest(validated.manifest);
+            report.attached.push(row.pluginId);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            report.failed.push({ pluginId: row.pluginId, reason });
+            log.warn(`[plugin-boot] ${row.pluginId}: failed to load — ${reason}`);
+        }
+    }
+    log.info(`[plugin-boot] attached ${report.attached.length}, skipped ${report.skipped.length}, failed ${report.failed.length}` +
+        (report.attached.length ? ` (attached: ${report.attached.join(", ")})` : ""));
+    return report;
+}

package/dist/plugins/hook-dispatcher.d.ts

@@ -0,0 +1,13 @@
+import type { ContentLifecycleEvent, ContentService } from "@velora-cms/content-service";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { PluginRegistryService } from "./plugin-registry-service.js";
+import type { StructuredStorageAPI } from "./structured-storage-api.js";
+export declare function createHookDispatcher(deps: {
+    registry: PluginRegistryService;
+    structuredStorageAPI: StructuredStorageAPI;
+    contentService: ContentService;
+    adapter: DatabaseAdapter;
+    log: {
+        error: (obj: unknown, msg: string) => void;
+    };
+}): (event: ContentLifecycleEvent) => void;

package/dist/plugins/hook-dispatcher.js

@@ -0,0 +1,68 @@
+import { buildContext } from "./plugin-context.js";
+// S159: the hook engine's host half. Resolves every ACTIVE plugin's
+// handler for the event and invokes each fire-and-forget with the same
+// containment posture as plugin API routes: one plugin throwing is a log
+// line, never a failed publish. The returned function is synchronous and
+// void — ContentService's editorial path never awaits hook work.
+export function createHookDispatcher(deps) {
+    return (event) => {
+        // listActiveHookContributions reads manifest.contributions off objects
+        // supplied by dynamically-imported plugin code, same as buildContext
+        // below — a throwing getter here is just as untrusted, and sits above
+        // the loop, so it needs its own boundary or it would silently abort
+        // dispatch for every plugin on every event.
+        let contributions;
+        try {
+            contributions = deps.registry.listActiveHookContributions(event.event);
+        }
+        catch (err) {
+            try {
+                deps.log.error({ err, event: event.event }, "plugin hook lookup failed");
+            }
+            catch {
+                // Same untrusted-boundary swallow as below.
+            }
+            return;
+        }
+        for (const { pluginId, handler } of contributions) {
+            // The loop body itself — not just the deferred handler call below —
+            // must be per-plugin contained. buildContext and the synchronous
+            // prelude around it run on THIS plugin's turn through the loop; a
+            // throwing getter or similar from dynamically-imported plugin code
+            // here would otherwise abort dispatch for every plugin after this
+            // one, silently (nothing would log it).
+            try {
+                const context = buildContext(pluginId, deps.structuredStorageAPI, deps.contentService, deps.adapter);
+                // Each handler gets its own shallow copy of the event payload —
+                // every invocation below is a deferred microtask sharing what
+                // would otherwise be one object, so one plugin mutating its
+                // payload could otherwise leak that mutation into another
+                // plugin's handler.
+                const payload = { ...event };
+                void Promise.resolve()
+                    .then(() => handler(payload, context))
+                    .catch((err) => {
+                    try {
+                        deps.log.error({ err, pluginId, event: event.event }, "plugin hook handler threw");
+                    }
+                    catch {
+                        // A plugin can influence the logged `err` value at this
+                        // untrusted boundary (its own thrown error) — if that value
+                        // makes the logger itself throw (e.g. a hostile toJSON/
+                        // getter), swallow it rather than leave an unhandled
+                        // rejection from this .catch.
+                    }
+                });
+            }
+            catch (err) {
+                try {
+                    deps.log.error({ err, pluginId, event: event.event }, "plugin hook dispatch failed");
+                }
+                catch {
+                    // Same untrusted-boundary swallow as above, for the synchronous
+                    // path.
+                }
+            }
+        }
+    };
+}

package/dist/plugins/install-built-package.d.ts

@@ -0,0 +1,36 @@
+import type { PrismaClient } from "@prisma/client";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import { type ManifestRowFields, type RegisterLocalPluginResult } from "../sandbox/register-local-plugin.js";
+import { PluginRegistryService } from "./plugin-registry-service.js";
+import type { TrustTier } from "./verify-package.js";
+/** Resolves the server-importable manifest entry a `velora-plugin
+ * build` package always produces at this fixed path. */
+export declare function resolveBuiltManifestPath(packageDir: string): string;
+export declare function installBuiltPackage(service: PluginRegistryService, packageDir: string, remoteUrl: string, setRemoteUrl: (pluginId: string, remoteUrl: string) => Promise<void>, syncManifestFields: (pluginId: string, fields: ManifestRowFields) => Promise<void>, setPackagePath?: (pluginId: string, packagePath: string) => Promise<void>, opts?: {
+    trustTier?: TrustTier;
+    seed?: {
+        prisma: PrismaClient;
+        adapter: DatabaseAdapter;
+        createdBy?: string;
+    };
+}): Promise<RegisterLocalPluginResult>;
+export interface InstallBuiltPackageCliArgs {
+    target: string;
+    remoteUrl: string;
+    sidecarPath?: string;
+}
+/** Validates `main()`'s argv shape only — NOT whether "" is the right
+ * value for this particular plugin. A view-less plugin type (theme/
+ * template/bundle) has no remoteEntry.js at all — install-from-
+ * marketplace.ts computes remoteUrl as `""` for exactly that case ("Empty
+ * string = the loader's existing 'nothing to load' contract"), so an
+ * explicitly-passed empty string here is a legitimate value, not a missing
+ * argument, and this parser accepts it unconditionally. Only an actually
+ * omitted argv slot (undefined — the caller never supplied a second
+ * positional at all) is a usage error; `target` has no such legitimate-
+ * empty case, so it keeps the plain falsy check. This parser runs before
+ * any manifest is read, so it CANNOT tell a view-less "" apart from a
+ * view-bearing type's "" typo'd in by mistake — that type-aware check
+ * happens later, inside installBuiltPackage, once the manifest's real
+ * type is known. */
+export declare function parseInstallBuiltPackageCliArgs(argv: string[]): InstallBuiltPackageCliArgs;

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

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { hasClientBundle } from "@velora-cms/plugin-sdk/manifest";
+import { registerLocalPlugin } from "../sandbox/register-local-plugin.js";
+import { storePackage } from "./plugin-package-store.js";
+import { PluginRegistryService } from "./plugin-registry-service.js";
+import { seedTemplateSampleContent } from "./seed-template-content.js";
+// The counterpart to ../sandbox/register-local-plugin.ts: that one loads
+// a manifest from LIVE SOURCE (src/plugin.ts(x)) for velora-dev's
+// same-filesystem dev sandbox; this one loads from a BUILT, distributable
+// package's server/plugin.js (produced by `velora-plugin build`,
+// Session 81) — proving a plugin installs from a package with no source
+// tree alongside it at all. Both funnel into the same, unmodified
+// registerLocalPlugin() — the manifest's origin doesn't matter to it.
+//
+// Since Session 121, server/plugin.js is a self-contained Vite SSR bundle
+// (react, react/jsx-runtime, and @velora-cms/plugin-sdk all inlined; zero bare
+// import specifiers) rather than a tsc-emitted file with live import
+// specifiers — which is why no node_modules needs to exist anywhere near
+// the extraction point for this to resolve.
+//
+// Since Session 122, install COPIES the package into the managed plugin
+// store (plugin-package-store.ts) before importing anything, and imports
+// from that STORED copy rather than the caller's (often tmpdir) extraction
+// directory — the same copy a later boot loader will import on restart.
+/** Resolves the server-importable manifest entry a `velora-plugin
+ * build` package always produces at this fixed path. */
+export function resolveBuiltManifestPath(packageDir) {
+    const entryPath = join(packageDir, "server", "plugin.js");
+    if (!existsSync(entryPath)) {
+        throw new Error(`No built manifest found at ${packageDir} — expected server/plugin.js`);
+    }
+    return entryPath;
+}
+export async function installBuiltPackage(service, packageDir, remoteUrl, setRemoteUrl, syncManifestFields, setPackagePath, opts) {
+    resolveBuiltManifestPath(packageDir); // fail fast on a non-package before any copying
+    // manifest.json (written by `velora-plugin build`) supplies id+version
+    // WITHOUT importing code — the store path must be known before the
+    // import so the import runs against the STORED copy (what the boot
+    // loader will import later is byte-identical to what installs now).
+    const manifestJsonPath = join(packageDir, "manifest.json");
+    if (!existsSync(manifestJsonPath)) {
+        throw new Error(`No manifest.json found in ${packageDir} — not a velora-plugin built package`);
+    }
+    const summary = JSON.parse(readFileSync(manifestJsonPath, "utf8"));
+    if (!summary.id || !summary.version) {
+        throw new Error(`${manifestJsonPath} is missing id/version`);
+    }
+    // Path-safety gate: these two values become directory names BEFORE the
+    // manifest's own validation runs (validatePluginManifest fires later,
+    // inside registerLocalPlugin). Mirror the SDK manifest schema's id rule
+    // and a path-safe version shape so a hostile manifest.json can't
+    // traverse out of the store root.
+    if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(summary.id)) {
+        throw new Error(`manifest.json id "${summary.id}" is not a valid reverse-domain plugin id`);
+    }
+    // Must start and end with an alphanumeric — otherwise a version of "."
+    // or ".." (both match the bare character-class check on their own)
+    // resolves as a filesystem self-reference/parent-reference segment once
+    // joined into a path, not a literal directory name.
+    if (!/^[0-9a-z](?:[0-9a-z.+-]*[0-9a-z])?$/i.test(summary.version) ||
+        summary.version.includes("..")) {
+        throw new Error(`manifest.json version "${summary.version}" is not a path-safe version string`);
+    }
+    const storedDir = storePackage(packageDir, summary.id, summary.version);
+    const entryPath = resolveBuiltManifestPath(storedDir);
+    const mod = (await import(pathToFileURL(entryPath).href));
+    if (!mod.default) {
+        throw new Error(`${entryPath} has no default export`);
+    }
+    const manifestId = mod.default.id;
+    if (manifestId !== summary.id) {
+        throw new Error(`manifest.json id "${summary.id}" does not match server/plugin.js id "${manifestId}"`);
+    }
+    const manifestVersion = mod.default.version;
+    if (manifestVersion !== summary.version) {
+        throw new Error(`manifest.json version "${summary.version}" does not match server/plugin.js version "${manifestVersion}"`);
+    }
+    // SEC-2 (S172 audit): the declared type in manifest.json — the value the
+    // marketplace catalogs as `listing.type` and the human reviewer approves
+    // against — must equal the plugin's ACTUAL runtime type in server/plugin.js.
+    // The marketplace never inspects the (opaque, minified) server bundle, so a
+    // package could be listed/reviewed as a benign `datatype`/`theme` while its
+    // code runs as a `section` with public apiRoutes/hooks/scheduledTasks.
+    // Enforcing declared === runtime here makes any such spoof uninstallable
+    // everywhere, so the runtime type a plugin ships can never diverge from the
+    // type it was reviewed and listed as. (When manifest.json carries no type —
+    // an older sideload shape — there is nothing to contradict, so skip.)
+    const manifestType = mod.default.type;
+    if (summary.type && manifestType && summary.type !== manifestType) {
+        throw new Error(`manifest.json type "${summary.type}" does not match server/plugin.js type "${manifestType}" — the listed type must match the plugin's actual runtime type`);
+    }
+    // Type-aware remoteUrl gate. parseInstallBuiltPackageCliArgs (below)
+    // only enforces that the argv slot was supplied at all — it runs before
+    // any manifest is read, so it has no way to know the plugin's type and
+    // deliberately accepts an explicit "" unconditionally. install-from-
+    // marketplace.ts's own remoteUrl computation is the authority on when
+    // "" is actually correct: only for a view-less type (theme/template/
+    // bundle — see hasClientBundle), which ships no remoteEntry.js at all.
+    // A view-BEARING type (datatype/section/integration/utility) installed
+    // with an empty remoteUrl would register successfully but silently skip
+    // loading its views forever — boot-remote-plugins.ts's `if
+    // (!plugin.remoteUrl) continue` treats "" exactly like "nothing to
+    // load," with no error anywhere. Catch that here, now that the
+    // manifest's real type is known, rather than letting it install broken.
+    if (remoteUrl === "" && manifestType && hasClientBundle(manifestType)) {
+        throw new Error(`"${summary.id}" is type "${manifestType}", which ships a client bundle (remoteEntry.js) — an empty remoteUrl is only valid for view-less plugin types (theme/template/bundle). Pass the plugin's actual remoteUrl.`);
+    }
+    const outcome = await registerLocalPlugin(service, mod.default, remoteUrl, setRemoteUrl, syncManifestFields, opts);
+    await setPackagePath?.(summary.id, storedDir);
+    // D1: invoked AFTER registerLocalPlugin returns, never from inside
+    // PluginRegistryService.install() — the S88 documentTypes path stays
+    // untouched. Only a genuinely fresh install seeds — "activated"/
+    // "already-active" mean this call didn't create anything new, so
+    // there's nothing to seed against (and, for the already-active case,
+    // any real sample content would already exist anyway). storedDir is
+    // exactly the STORED package dir seedTemplateSampleContent reads
+    // sample-content.json from — the same copy the boot loader will import
+    // on restart. Wrapped in its own try/catch as a belt-and-braces guard
+    // on top of the seeder's own internal non-fatal handling — D2 requires
+    // this install to stand no matter what happens here.
+    if (outcome === "installed" && opts?.seed) {
+        try {
+            const seedResult = await seedTemplateSampleContent({ prisma: opts.seed.prisma, adapter: opts.seed.adapter }, summary.id, storedDir, opts.seed.createdBy);
+            if (typeof seedResult === "object") {
+                console.log(`[install-built-package] seeded ${seedResult.created} sample content node(s) for "${summary.id}"`);
+            }
+            else if (seedResult !== "none") {
+                console.log(`[install-built-package] sample content seeding for "${summary.id}": ${seedResult}`);
+            }
+        }
+        catch (error) {
+            console.error(`[install-built-package] sample content seeding for "${summary.id}" failed — the install stands`, error);
+        }
+    }
+    return outcome;
+}
+/** Validates `main()`'s argv shape only — NOT whether "" is the right
+ * value for this particular plugin. A view-less plugin type (theme/
+ * template/bundle) has no remoteEntry.js at all — install-from-
+ * marketplace.ts computes remoteUrl as `""` for exactly that case ("Empty
+ * string = the loader's existing 'nothing to load' contract"), so an
+ * explicitly-passed empty string here is a legitimate value, not a missing
+ * argument, and this parser accepts it unconditionally. Only an actually
+ * omitted argv slot (undefined — the caller never supplied a second
+ * positional at all) is a usage error; `target` has no such legitimate-
+ * empty case, so it keeps the plain falsy check. This parser runs before
+ * any manifest is read, so it CANNOT tell a view-less "" apart from a
+ * view-bearing type's "" typo'd in by mistake — that type-aware check
+ * happens later, inside installBuiltPackage, once the manifest's real
+ * type is known. */
+export function parseInstallBuiltPackageCliArgs(argv) {
+    const [target, remoteUrl, sidecarPath] = argv;
+    if (!target || remoteUrl === undefined) {
+        throw new Error("Usage: tsx install-built-package.ts <packageDir|package.tar.gz> <remoteUrl> [sidecarPath]");
+    }
+    return { target, remoteUrl, sidecarPath };
+}
+async function main() {
+    const { target, remoteUrl, sidecarPath: sidecarFlag } = parseInstallBuiltPackageCliArgs(process.argv.slice(2));
+    // Since Session 122, the CLI connects through connectContentDb() rather
+    // than hardcoding a PostgreSQLAdapter — this makes the sqlite sandbox a
+    // first-class CLI target (Session 121's live proof needed a throwaway
+    // driver precisely because of the old hardcoded adapter).
+    const { prisma } = await import("../db/prisma.js");
+    const { connectContentDb } = await import("../db/content-db.js");
+    const contentDb = await connectContentDb();
+    const activeDialect = process.env.VELORA_PLUGIN_ACTIVE_DIALECT ?? contentDb.dialect;
+    const service = new PluginRegistryService(prisma, contentDb.adapter, { activeDialect });
+    const setRemoteUrl = async (pluginId, url) => {
+        await prisma.pluginRegistry.update({ where: { pluginId }, data: { remoteUrl: url } });
+    };
+    const syncManifestFields = async (pluginId, fields) => {
+        await prisma.pluginRegistry.update({ where: { pluginId }, data: fields });
+    };
+    const setPackagePath = async (pluginId, packagePath) => {
+        await prisma.pluginRegistry.update({ where: { pluginId }, data: { packagePath } });
+    };
+    // Session 127: a .tar.gz takes the verifying path; a directory takes the
+    // original one, unchanged — velora-dev and in-monorepo development have
+    // no tarball.
+    if (target.endsWith(".tar.gz")) {
+        const { installPackageTarball } = await import("./install-package-tarball.js");
+        const { outcome, verification } = await installPackageTarball(service, target, remoteUrl, setRemoteUrl, syncManifestFields, setPackagePath, sidecarFlag ? { sidecarPath: sidecarFlag } : {});
+        console.log(`[install-built-package] ${outcome} (${verification.status})`);
+    }
+    else {
+        const outcome = await installBuiltPackage(service, target, remoteUrl, setRemoteUrl, syncManifestFields, setPackagePath);
+        console.log(`[install-built-package] ${outcome}`);
+    }
+    await prisma.$disconnect();
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((error) => {
+        console.error("[install-built-package] failed:", error);
+        process.exit(1);
+    });
+}

package/dist/plugins/install-package-tarball.d.ts

@@ -0,0 +1,25 @@
+import type { PrismaClient } from "@prisma/client";
+import type { TrustedKey, VerifyResult } from "@velora-cms/plugin-package";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { ManifestRowFields, RegisterLocalPluginResult } from "../sandbox/register-local-plugin.js";
+import type { PluginRegistryService } from "./plugin-registry-service.js";
+export interface InstallPackageTarballOptions {
+    /** Defaults to `<tarballPath>.sig` when present; pass null to force the
+     * unsigned path. */
+    sidecarPath?: string | null;
+    /** Defaults to loadTrustedKeys(). */
+    trustedKeys?: TrustedKey[];
+    /** Forwarded verbatim to installBuiltPackage (Session 151): when
+     * supplied, a template plugin's sample-content.json is seeded after a
+     * fresh install — see installBuiltPackage's own opts.seed doc. Purely
+     * additive: every pre-existing caller omits it and behaves unchanged. */
+    seed?: {
+        prisma: PrismaClient;
+        adapter: DatabaseAdapter;
+        createdBy?: string;
+    };
+}
+export declare function installPackageTarball(service: PluginRegistryService, tarballPath: string, remoteUrl: string, setRemoteUrl: (pluginId: string, remoteUrl: string) => Promise<void>, syncManifestFields: (pluginId: string, fields: ManifestRowFields) => Promise<void>, setPackagePath?: (pluginId: string, packagePath: string) => Promise<void>, options?: InstallPackageTarballOptions): Promise<{
+    outcome: RegisterLocalPluginResult;
+    verification: VerifyResult;
+}>;