velora-plugin 0.9.0

package/dist/checks/audit.js

@@ -0,0 +1,50 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export function checkNpmAudit(pluginDir) {
+    const name = "npm audit";
+    // In-monorepo reference plugins (plugins/google-maps) rely on the root
+    // pnpm-lock.yaml and have no lockfile of their own — audit is only
+    // meaningful against a real npm-managed project (a scaffolded,
+    // `npm install`ed external plugin), the actual target of this check.
+    if (!existsSync(join(pluginDir, "package-lock.json"))) {
+        return { name, passed: true, message: "skipped — no package-lock.json (not an npm-managed project)" };
+    }
+    let stdout;
+    try {
+        // shell: true is required so this resolves npm.cmd on Windows (npm is a
+        // .cmd shim there, and execFileSync cannot exec .cmd files without a
+        // shell — it fails immediately with ENOENT otherwise). Safe here: both
+        // the command ("npm") and args (["audit", "--json"]) are static
+        // literals, never user input, so there's no shell-injection risk from
+        // enabling this. This matches the shell: true convention already used
+        // for spawnSync calls in packages/velora-dev/src/{docker,sandbox}.ts.
+        stdout = execFileSync("npm", ["audit", "--json"], { cwd: pluginDir, encoding: "utf8", shell: true });
+    }
+    catch (error) {
+        // npm audit exits non-zero when it FINDS vulnerabilities — that's a
+        // normal result carried on stdout, not a crash.
+        stdout = error.stdout ?? "";
+    }
+    let report;
+    try {
+        report = JSON.parse(stdout);
+    }
+    catch {
+        return { name, passed: true, message: "skipped — npm audit did not return parseable JSON" };
+    }
+    const high = report.metadata?.vulnerabilities?.high ?? 0;
+    const critical = report.metadata?.vulnerabilities?.critical ?? 0;
+    if (high + critical === 0) {
+        return { name, passed: true, message: "0 high/critical advisories" };
+    }
+    const offenders = Object.entries(report.vulnerabilities ?? {})
+        .filter(([, advisory]) => advisory.severity === "high" || advisory.severity === "critical")
+        .map(([pkgName, advisory]) => `${pkgName} (${advisory.severity})`);
+    return {
+        name,
+        passed: false,
+        message: `${high + critical} high/critical advisor${high + critical === 1 ? "y" : "ies"}`,
+        details: offenders.join("\n"),
+    };
+}

package/dist/checks/bundle-size.d.ts

@@ -0,0 +1,3 @@
+import type { FederationBuildResult } from "../build-federation-bundle.js";
+import type { CheckResult } from "../types.js";
+export declare function checkBundleSize(build: FederationBuildResult): CheckResult;

package/dist/checks/bundle-size.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { gzipSync } from "node:zlib";
+const LIMIT_BYTES = 250 * 1024;
+function formatKb(bytes) {
+    return `${Math.ceil(bytes / 1024)} KB`;
+}
+export function checkBundleSize(build) {
+    const name = "bundle size";
+    if (!build.remoteEntryPath) {
+        return {
+            name,
+            passed: false,
+            message: build.buildError ? `federation build failed: ${build.buildError}` : "no remoteEntry.js produced by the build",
+        };
+    }
+    const gzipped = gzipSync(readFileSync(build.remoteEntryPath)).length;
+    if (gzipped > LIMIT_BYTES) {
+        return { name, passed: false, message: `${formatKb(gzipped)} gzipped exceeds the ${formatKb(LIMIT_BYTES)} limit` };
+    }
+    return { name, passed: true, message: `${formatKb(gzipped)} gzipped (limit ${formatKb(LIMIT_BYTES)})` };
+}

package/dist/checks/db-compat.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatePluginManifestResult } from "@velora-cms/plugin-sdk/manifest";
+import type { CheckResult } from "../types.js";
+export declare function checkDatabaseCompatibility(result: ValidatePluginManifestResult): CheckResult;

package/dist/checks/db-compat.js

@@ -0,0 +1,15 @@
+export function checkDatabaseCompatibility(result) {
+    const name = "database compatibility declared";
+    if (!result.ok) {
+        return { name, passed: false, message: "cannot check — manifest schema invalid" };
+    }
+    // Zod's databaseCompatibility.supported.min(1) already guarantees this
+    // is non-empty whenever result.ok is true — this check exists as its
+    // own named, reported gate per the Session 80 checklist, not because
+    // new logic is needed beyond what manifest validity already enforces.
+    const supported = result.manifest.databaseCompatibility.supported;
+    if (supported.length === 0) {
+        return { name, passed: false, message: "databaseCompatibility.supported is empty" };
+    }
+    return { name, passed: true, message: `declared: ${supported.join(", ")}` };
+}

package/dist/checks/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatePluginManifestResult } from "@velora-cms/plugin-sdk/manifest";
+import type { CheckResult } from "../types.js";
+export declare function checkManifest(result: ValidatePluginManifestResult): CheckResult;

package/dist/checks/manifest.js

@@ -0,0 +1,12 @@
+export function checkManifest(result) {
+    const name = "manifest schema valid";
+    if (result.ok) {
+        return { name, passed: true, message: "manifest schema valid" };
+    }
+    return {
+        name,
+        passed: false,
+        message: `manifest schema invalid (${result.errors.length} issue${result.errors.length === 1 ? "" : "s"})`,
+        details: result.errors.join("\n"),
+    };
+}

package/dist/checks/shared-deps.d.ts

@@ -0,0 +1,3 @@
+import type { FederationBuildResult } from "../build-federation-bundle.js";
+import type { CheckResult } from "../types.js";
+export declare function checkSharedDeps(pluginDir: string, build: FederationBuildResult): CheckResult;

package/dist/checks/shared-deps.js

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+// Symbol.for('react.element') is a literal string in React's own source
+// (react-is/react internals) that survives minification — its presence
+// in a built federation bundle means react's actual runtime code was
+// inlined rather than shared, even if package.json superficially
+// declares it correctly.
+const REACT_TELLTALE = "react.element";
+export function checkSharedDeps(pluginDir, build) {
+    const name = "react/react-dom not bundled";
+    const pkg = JSON.parse(readFileSync(join(pluginDir, "package.json"), "utf8"));
+    const misplaced = ["react", "react-dom"].filter((dep) => pkg.dependencies?.[dep]);
+    if (misplaced.length > 0) {
+        return {
+            name,
+            passed: false,
+            message: `${misplaced.join(", ")} declared under "dependencies" — must be "peerDependencies" (or absent) so the host's shared singleton is used`,
+        };
+    }
+    if (build.remoteEntryPath) {
+        const bundleSource = readFileSync(build.remoteEntryPath, "utf8");
+        if (bundleSource.includes(REACT_TELLTALE)) {
+            return {
+                name,
+                passed: false,
+                message: "the built bundle contains React's own source — react is being bundled instead of shared",
+            };
+        }
+    }
+    return { name, passed: true, message: "react/react-dom are peer/shared, not bundled" };
+}

package/dist/checks/typescript.d.ts

@@ -0,0 +1,2 @@
+import type { CheckResult } from "../types.js";
+export declare function checkTypeScript(pluginDir: string): CheckResult;

package/dist/checks/typescript.js

@@ -0,0 +1,34 @@
+import ts from "typescript";
+export function checkTypeScript(pluginDir) {
+    const name = "typescript compiles";
+    const configPath = ts.findConfigFile(pluginDir, ts.sys.fileExists, "tsconfig.json");
+    if (!configPath) {
+        return { name, passed: false, message: `no tsconfig.json found in ${pluginDir}` };
+    }
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (configFile.error) {
+        return { name, passed: false, message: ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n") };
+    }
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, pluginDir);
+    const program = ts.createProgram({
+        rootNames: parsed.fileNames,
+        options: { ...parsed.options, noEmit: true },
+    });
+    const diagnostics = [...parsed.errors, ...ts.getPreEmitDiagnostics(program)];
+    if (diagnostics.length === 0) {
+        return { name, passed: true, message: "no type errors" };
+    }
+    const details = diagnostics
+        .map((diagnostic) => ts.formatDiagnostic(diagnostic, {
+        getCurrentDirectory: () => pluginDir,
+        getCanonicalFileName: (file) => file,
+        getNewLine: () => "\n",
+    }))
+        .join("");
+    return {
+        name,
+        passed: false,
+        message: `${diagnostics.length} type error${diagnostics.length === 1 ? "" : "s"}`,
+        details,
+    };
+}

package/dist/checks/views.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatePluginManifestResult } from "@velora-cms/plugin-sdk/manifest";
+import type { CheckResult } from "../types.js";
+export declare function checkRequiredViews(result: ValidatePluginManifestResult): CheckResult;

package/dist/checks/views.js

@@ -0,0 +1,63 @@
+// Mirrors the contribution matrix (docs/PROJECT_CONTEXT.md → Plugin
+// System). A schema-valid manifest can still declare an empty
+// contributions object for its type (every key in the matrix is
+// .optional()) — that's a useless plugin, and this check is the one
+// place that catches it. datatype's per-view requirement
+// (input/readOnly/settings) is ALREADY structurally enforced by
+// DataTypePluginSchema (only "preview" is optional there), so a
+// schema-valid datatype manifest can never be missing one — reaching
+// "passed: true" below already proves it.
+const REQUIRED_ONE_OF = {
+    datatype: ["dataTypes", "mediaProcessors", "settingsPages"],
+    section: [
+        "dataTypes",
+        "adminSections",
+        "apiRoutes",
+        "dashboardWidgets",
+        "hooks",
+        "scheduledTasks",
+        "settingsPages",
+        "documentTypes",
+        "bundledTemplate",
+    ],
+    template: ["documentTypes"],
+    theme: ["themeTokens"],
+    integration: ["hooks", "settingsPages", "exposedServices"],
+    utility: [
+        "dashboardWidgets",
+        "hooks",
+        "scheduledTasks",
+        "mediaProcessors",
+        "settingsPages",
+        "contentTreeActions",
+        "editorToolbar",
+    ],
+    bundle: ["bundledPlugins", "bundledTemplate"],
+};
+function hasContent(value) {
+    if (value == null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === "object")
+        return Object.keys(value).length > 0;
+    return Boolean(value);
+}
+export function checkRequiredViews(result) {
+    const name = "required views/contributions present";
+    if (!result.ok) {
+        return { name, passed: false, message: "cannot check — manifest schema invalid" };
+    }
+    const manifest = result.manifest;
+    const requiredKeys = REQUIRED_ONE_OF[manifest.type];
+    const contributions = manifest.contributions;
+    const present = requiredKeys.filter((key) => hasContent(contributions[key]));
+    if (present.length === 0) {
+        return {
+            name,
+            passed: false,
+            message: `${manifest.type} plugin declares no contributions (expected at least one of: ${requiredKeys.join(", ")})`,
+        };
+    }
+    return { name, passed: true, message: `contributes: ${present.join(", ")}` };
+}

package/dist/copy-sample-content.d.ts

@@ -0,0 +1,39 @@
+import type { CMSPlugin } from "@velora-cms/plugin-sdk/manifest";
+/**
+ * Same legality product as packStarterIfPresent's UndeclaredStarterError
+ * (pack-starter.ts): an undeclared package data file is treated as a
+ * mistake, not a choice. sample-content.json only means something to a
+ * starter-bearing plugin — it's the seed tree
+ * apps/server/src/plugins/seed-template-content.ts (S149 Task 2) creates
+ * host-side after install, keyed to the SAME plugin's own documentTypes
+ * contribution. A sample-content.json sitting next to a non-starter-
+ * bearing manifest can never be consumed by anything.
+ */
+export declare class UndeclaredSampleContentError extends Error {
+    constructor(pluginDir: string);
+}
+/**
+ * Copies <pluginDir>/sample-content.json into <outDir>/sample-content.json
+ * when present — the S149 delivery mechanism for a template's seed
+ * content. Host-side seeding (D1 of the S149 plan) needs the file to
+ * survive INSIDE the packed artifact: onInstall runs with no minted ids
+ * and no content API, so the actual node-creation walk has to happen
+ * AFTER install(), reading this file back out of the STORED package
+ * directory (apps/server/src/plugins/seed-template-content.ts, Task 2) —
+ * plain readFileSync, no separate tar entry extraction. packPlugin tars
+ * the whole outDir as-is (pack.ts), so once the file lands in outDir it
+ * rides into the artifact for free, exactly like starter.tar.gz.
+ *
+ * Rules (mirrors packStarterIfPresent's structure exactly):
+ *  - sample-content.json absent → no-op, regardless of starter-bearing
+ *    status (a starter-bearing plugin with no sample content stays legal
+ *    — not every template ships seed data).
+ *  - sample-content.json present, NOT starter-bearing → throws
+ *    UndeclaredSampleContentError.
+ *  - sample-content.json present and starter-bearing → copied verbatim
+ *    (no parsing/validation here — Task 2's seeder owns shape validation
+ *    against the STORED copy; build-time is a pure file carry).
+ *
+ * Returns the copied file's path, or null when nothing was copied.
+ */
+export declare function copySampleContentIfPresent(pluginDir: string, outDir: string, manifest: CMSPlugin): string | null;

package/dist/copy-sample-content.js

@@ -0,0 +1,57 @@
+import { copyFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { isStarterBearing } from "./pack-starter.js";
+/**
+ * Same legality product as packStarterIfPresent's UndeclaredStarterError
+ * (pack-starter.ts): an undeclared package data file is treated as a
+ * mistake, not a choice. sample-content.json only means something to a
+ * starter-bearing plugin — it's the seed tree
+ * apps/server/src/plugins/seed-template-content.ts (S149 Task 2) creates
+ * host-side after install, keyed to the SAME plugin's own documentTypes
+ * contribution. A sample-content.json sitting next to a non-starter-
+ * bearing manifest can never be consumed by anything.
+ */
+export class UndeclaredSampleContentError extends Error {
+    constructor(pluginDir) {
+        super(`${pluginDir} has a sample-content.json but its manifest is not starter-bearing (see ` +
+            `pack-starter.ts's isStarterBearing — a 'template'-type plugin, or a section/bundle plugin ` +
+            `declaring contributions.bundledTemplate). An undeclared sample-content.json is treated as a ` +
+            `mistake, not a choice — either make the plugin starter-bearing or remove the file.`);
+        this.name = "UndeclaredSampleContentError";
+    }
+}
+/**
+ * Copies <pluginDir>/sample-content.json into <outDir>/sample-content.json
+ * when present — the S149 delivery mechanism for a template's seed
+ * content. Host-side seeding (D1 of the S149 plan) needs the file to
+ * survive INSIDE the packed artifact: onInstall runs with no minted ids
+ * and no content API, so the actual node-creation walk has to happen
+ * AFTER install(), reading this file back out of the STORED package
+ * directory (apps/server/src/plugins/seed-template-content.ts, Task 2) —
+ * plain readFileSync, no separate tar entry extraction. packPlugin tars
+ * the whole outDir as-is (pack.ts), so once the file lands in outDir it
+ * rides into the artifact for free, exactly like starter.tar.gz.
+ *
+ * Rules (mirrors packStarterIfPresent's structure exactly):
+ *  - sample-content.json absent → no-op, regardless of starter-bearing
+ *    status (a starter-bearing plugin with no sample content stays legal
+ *    — not every template ships seed data).
+ *  - sample-content.json present, NOT starter-bearing → throws
+ *    UndeclaredSampleContentError.
+ *  - sample-content.json present and starter-bearing → copied verbatim
+ *    (no parsing/validation here — Task 2's seeder owns shape validation
+ *    against the STORED copy; build-time is a pure file carry).
+ *
+ * Returns the copied file's path, or null when nothing was copied.
+ */
+export function copySampleContentIfPresent(pluginDir, outDir, manifest) {
+    const sourcePath = join(pluginDir, "sample-content.json");
+    if (!existsSync(sourcePath))
+        return null;
+    if (!isStarterBearing(manifest)) {
+        throw new UndeclaredSampleContentError(pluginDir);
+    }
+    const destPath = join(outDir, "sample-content.json");
+    copyFileSync(sourcePath, destPath);
+    return destPath;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import type { ValidationResult } from "./types.js";
+import { type PublishResult } from "./publish.js";
+export declare function formatResult(result: ValidationResult): string;
+/** Pure rendering for `publishPlugin`'s ok branch — split out so the CLI's
+ * console/exitCode wiring is the only untested shell. */
+export declare function formatPublishOutcome(result: Extract<PublishResult, {
+    ok: true;
+}>): {
+    text: string;
+    failed: boolean;
+};

package/dist/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { validatePlugin } from "./validate.js";
+import { buildPlugin, BuildValidationError } from "./build.js";
+import { packPlugin } from "./pack.js";
+import { publishPlugin } from "./publish.js";
+export function formatResult(result) {
+    const lines = [];
+    for (const check of result.checks) {
+        const mark = check.passed ? "✓" : "✗";
+        lines.push(`${mark} ${check.name} (${check.message})`);
+        if (!check.passed && check.details) {
+            lines.push(check.details
+                .split("\n")
+                .map((line) => `  ${line}`)
+                .join("\n"));
+        }
+    }
+    const failed = result.checks.filter((check) => !check.passed).length;
+    lines.push("");
+    lines.push(failed === 0
+        ? `All ${result.checks.length} check${result.checks.length === 1 ? "" : "s"} passed.`
+        : `${failed} check${failed === 1 ? "" : "s"} failed.`);
+    return lines.join("\n");
+}
+/** Pure rendering for `publishPlugin`'s ok branch — split out so the CLI's
+ * console/exitCode wiring is the only untested shell. */
+export function formatPublishOutcome(result) {
+    if (result.state === "validation_failed") {
+        const lines = [`Published: submission ${result.submissionId} — validation failed`];
+        for (const name of result.failedChecks ?? [])
+            lines.push(`  ✗ ${name}`);
+        return { text: lines.join("\n"), failed: true };
+    }
+    if (result.state === "awaiting_review") {
+        return { text: `Published: submission ${result.submissionId} — validation passed, awaiting review`, failed: false };
+    }
+    return { text: `Published: submission ${result.submissionId} (state: ${result.state})`, failed: false };
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean", default: false },
+            out: { type: "string" },
+            registry: { type: "string" },
+            token: { type: "string" },
+        },
+    });
+    const [, command, dirArg] = ["velora-plugin", ...positionals];
+    const pluginDir = dirArg ?? process.cwd();
+    switch (command) {
+        case "validate": {
+            const result = await validatePlugin(pluginDir);
+            if (values.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.log(formatResult(result));
+            }
+            process.exitCode = result.passed ? 0 : 1;
+            return;
+        }
+        case "build": {
+            try {
+                const result = await buildPlugin(pluginDir, values.out);
+                console.log(`Built ${result.outDir}`);
+                process.exitCode = 0;
+            }
+            catch (error) {
+                if (error instanceof BuildValidationError) {
+                    console.error(formatResult(error.validation));
+                    process.exitCode = 1;
+                    return;
+                }
+                throw error;
+            }
+            return;
+        }
+        case "pack": {
+            try {
+                const result = await packPlugin(pluginDir, values.out);
+                console.log(`Packed ${result.archivePath}`);
+                process.exitCode = 0;
+            }
+            catch (error) {
+                if (error instanceof BuildValidationError) {
+                    console.error(formatResult(error.validation));
+                    process.exitCode = 1;
+                    return;
+                }
+                throw error;
+            }
+            return;
+        }
+        case "publish": {
+            const registryUrl = values.registry ?? process.env.VELORA_REGISTRY_URL ?? "http://localhost:3200";
+            const token = values.token ?? process.env.VELORA_PUBLISH_TOKEN;
+            if (!token) {
+                console.error("set VELORA_PUBLISH_TOKEN or pass --token");
+                process.exitCode = 1;
+                return;
+            }
+            try {
+                const result = await publishPlugin(pluginDir, { registryUrl, token });
+                if (result.ok) {
+                    const outcome = formatPublishOutcome(result);
+                    if (outcome.failed) {
+                        console.error(outcome.text);
+                        process.exitCode = 1;
+                    }
+                    else {
+                        console.log(outcome.text);
+                        process.exitCode = 0;
+                    }
+                }
+                else {
+                    // publishPlugin maps a local validation failure into this
+                    // ok:false branch (a joined check-names message) rather than
+                    // throwing BuildValidationError, so this is the path a failed
+                    // validate actually takes today.
+                    console.error(result.message);
+                    process.exitCode = 1;
+                }
+            }
+            catch (error) {
+                // Kept for parity with the build/pack cases' check-by-check
+                // output and as a safety net — publishPlugin does not currently
+                // let BuildValidationError escape (it catches and maps it above),
+                // so this branch is not expected to be exercised in practice.
+                if (error instanceof BuildValidationError) {
+                    console.error(formatResult(error.validation));
+                    process.exitCode = 1;
+                    return;
+                }
+                throw error;
+            }
+            return;
+        }
+        default: {
+            console.error(`Unknown command "${command ?? ""}". Usage: velora-plugin <validate|build|pack|publish> [dir] [--json] [--out <path>] [--registry <url>] [--token <token>]`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+}
+// Only run the CLI when this file is executed directly (e.g. `node index.js`
+// or the `velora-plugin` bin), not when it's imported as a module — this file
+// is also imported by index.test.ts to reuse `formatResult`, and running
+// `main()` as an import side-effect would parse the test runner's real
+// process.argv, print a spurious "Unknown command" error, and set
+// process.exitCode as an unrelated side effect of importing a library export.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    main().catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });
+}

package/dist/load-manifest.d.ts

@@ -0,0 +1,18 @@
+import { type ValidatePluginManifestResult } from "@velora-cms/plugin-sdk/manifest";
+/**
+ * Every plugin template (create-velora-plugin) and the google-maps
+ * reference plugin expose their manifest from src/plugin.ts or
+ * src/plugin.tsx — the same file each vite.config.ts names under
+ * federation's exposes['./plugin'].
+ */
+export declare function resolveManifestEntry(pluginDir: string): string;
+/**
+ * Loads a plugin's manifest module IN-PROCESS via tsx's tsImport — not a
+ * subprocess — so the real manifest object (with live function references
+ * DataTypePluginSchema's z.custom() checks need) never has to cross a
+ * serialization boundary. Works uniformly whether the plugin's own
+ * tsconfig emits JS (plugins/google-maps) or is a type-check-only gate
+ * (create-velora-plugin's scaffolded projects, noEmit: true) — neither's
+ * dist/ layout matters, since this never touches dist/.
+ */
+export declare function loadManifest(pluginDir: string): Promise<ValidatePluginManifestResult>;

package/dist/load-manifest.js

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tsImport } from "tsx/esm/api";
+import { validatePluginManifest } from "@velora-cms/plugin-sdk/manifest";
+/**
+ * Every plugin template (create-velora-plugin) and the google-maps
+ * reference plugin expose their manifest from src/plugin.ts or
+ * src/plugin.tsx — the same file each vite.config.ts names under
+ * federation's exposes['./plugin'].
+ */
+export function resolveManifestEntry(pluginDir) {
+    const tsEntry = join(pluginDir, "src", "plugin.ts");
+    if (existsSync(tsEntry))
+        return tsEntry;
+    const tsxEntry = join(pluginDir, "src", "plugin.tsx");
+    if (existsSync(tsxEntry))
+        return tsxEntry;
+    throw new Error(`No plugin entry found at src/plugin.ts or src/plugin.tsx in ${pluginDir}`);
+}
+/**
+ * Loads a plugin's manifest module IN-PROCESS via tsx's tsImport — not a
+ * subprocess — so the real manifest object (with live function references
+ * DataTypePluginSchema's z.custom() checks need) never has to cross a
+ * serialization boundary. Works uniformly whether the plugin's own
+ * tsconfig emits JS (plugins/google-maps) or is a type-check-only gate
+ * (create-velora-plugin's scaffolded projects, noEmit: true) — neither's
+ * dist/ layout matters, since this never touches dist/.
+ */
+export async function loadManifest(pluginDir) {
+    let entryPath;
+    try {
+        entryPath = resolveManifestEntry(pluginDir);
+    }
+    catch (error) {
+        return { ok: false, errors: [error instanceof Error ? error.message : String(error)] };
+    }
+    let mod;
+    try {
+        mod = (await tsImport(pathToFileURL(entryPath).href, import.meta.url));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errors: [`failed to load plugin module ${entryPath}: ${error instanceof Error ? error.message : String(error)}`],
+        };
+    }
+    return validatePluginManifest(mod.default);
+}

package/dist/pack-starter.d.ts

@@ -0,0 +1,48 @@
+import type { CMSPlugin } from "@velora-cms/plugin-sdk/manifest";
+/**
+ * Structural check for "this manifest declares a bundledTemplate
+ * contribution" — mirrors the compile-time contribution matrix at
+ * runtime, the same way validate.ts's Zod schemas do, without importing
+ * any Zod schema here (loadManifest already validated the manifest before
+ * build.ts ever calls this).
+ */
+export declare function hasBundledTemplateContribution(manifest: CMSPlugin): boolean;
+/**
+ * Whether a starter/ directory is LEGAL for this manifest — the check
+ * packStarterIfPresent actually gates on. True in two cases:
+ *  - the manifest declares a bundledTemplate contribution (section/bundle,
+ *    hasBundledTemplateContribution above), or
+ *  - the manifest's type is 'template'. Per manifest.ts's
+ *    TemplatePluginContributions doc comment: "A template plugin IS a
+ *    bundled template (per the matrix), so there is no separate
+ *    bundledTemplate key — it contributes the document types its starter
+ *    needs." A template plugin is implicitly starter-bearing by design,
+ *    not by an explicit contribution flag, so it can never fail the
+ *    'declares bundledTemplate' structural check the way section/bundle
+ *    manifests do — it's legal unconditionally.
+ */
+export declare function isStarterBearing(manifest: CMSPlugin): boolean;
+export declare class UndeclaredStarterError extends Error {
+    constructor(pluginDir: string);
+}
+/**
+ * Packs <pluginDir>/starter/ into <outDir>/starter.tar.gz when present —
+ * the S148 delivery mechanism (the archive rides inside the plugin
+ * artifact; packPlugin tars the whole outDir, so nothing else has to
+ * change for it to reach the marketplace).
+ *
+ * Rules (S148 Global Constraints):
+ *  - starter/ absent → no-op, regardless of whether bundledTemplate is
+ *    declared (a bundledTemplate without an archive stays legal —
+ *    repository-only or metadata-only).
+ *  - starter/ present, NOT starter-bearing (see isStarterBearing) → throws
+ *    UndeclaredStarterError. An undeclared starter/ is a mistake, not a
+ *    choice.
+ *  - starter/ present and starter-bearing (bundledTemplate declared, OR
+ *    type 'template') → archive created, entries relative to starter/,
+ *    excluding node_modules/dist/.git/.next/.astro and env files
+ *    (.env, .env.* — except .env.example) at any depth.
+ *
+ * Returns the archive path, or null when no archive was created.
+ */
+export declare function packStarterIfPresent(pluginDir: string, outDir: string, manifest: CMSPlugin): Promise<string | null>;