velora-plugin 0.9.0

package/dist/pack-starter.js

@@ -0,0 +1,118 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { create } from "tar";
+// Only 'section' and 'bundle' manifests can carry a bundledTemplate
+// contribution (SectionPluginContributions / BundlePluginContributions in
+// manifest.ts) — 'template' plugins don't declare this key at all (see
+// isStarterBearing below for how 'template' is still legally starter-
+// bearing, just not through this specific structural check).
+const BUNDLED_TEMPLATE_TYPES = ["section", "bundle"];
+/**
+ * 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 function hasBundledTemplateContribution(manifest) {
+    return (BUNDLED_TEMPLATE_TYPES.includes(manifest.type) &&
+        "bundledTemplate" in manifest.contributions &&
+        manifest.contributions.bundledTemplate !== undefined);
+}
+/**
+ * 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 function isStarterBearing(manifest) {
+    return hasBundledTemplateContribution(manifest) || manifest.type === "template";
+}
+export class UndeclaredStarterError extends Error {
+    constructor(pluginDir) {
+        super(`${pluginDir} has a starter/ directory but its manifest does not declare a bundledTemplate contribution ` +
+            `and is not a 'template'-type plugin. An undeclared starter/ is treated as a mistake, not a choice — ` +
+            `either add contributions.bundledTemplate (only 'section' and 'bundle' plugin types may), make the ` +
+            `plugin type 'template' (implicitly starter-bearing), or remove the starter/ directory.`);
+        this.name = "UndeclaredStarterError";
+    }
+}
+// Directory names excluded from the packed archive by name, at ANY depth —
+// starter/ packs SOURCE only (the 20MB artifact cap and the "never ship
+// node_modules" rule both depend on this). A vendored dir doesn't only
+// appear at the starter/ root — e.g. a monorepo-shaped starter can have
+// `apps/site/node_modules/...` — so every path segment is checked, not just
+// the first. `.astro` is Astro's generated dir (content types, dev logs) —
+// build output, never source.
+const EXCLUDED_DIRS = new Set(["node_modules", "dist", ".git", ".next", ".astro"]);
+// Env files are excluded by segment at any depth — `.env`, `.env.local`,
+// `.env.production`, etc. can hold live secrets and must never ship inside
+// a served archive. The one deliberate exception is `.env.example`: it is
+// starter documentation (placeholder values a user copies to a real .env),
+// so it keeps packing.
+const ENV_FILE_PATTERN = /^\.env(\..*)?$/;
+function isEnvFileSegment(segment) {
+    return ENV_FILE_PATTERN.test(segment) && segment !== ".env.example";
+}
+function isExcluded(entryPath) {
+    // node-tar's create() filter receives archive-relative entry paths,
+    // posix-normalized (forward slashes) regardless of host OS, and
+    // "./"-prefixed for entries directly under cwd (e.g. "./node_modules",
+    // "./node_modules/some-dep/index.js") — strip that prefix before splitting
+    // into segments, and split on either separator defensively rather than
+    // depend on posix-only output. Excluded if ANY segment matches, so a
+    // FILE merely named e.g. "dist" (no extension) is also excluded — that's
+    // an accepted ambiguity, same as npm-pack-style ignore matching, not a
+    // bug: the archive is source-only and a bare `dist`/`node_modules`/`.git`/
+    // `.next` file is not a plausible legitimate source file in a starter.
+    const normalized = entryPath.replace(/^\.\/?/, "");
+    const segments = normalized.split(/[\\/]/);
+    return segments.some((segment) => EXCLUDED_DIRS.has(segment) || isEnvFileSegment(segment));
+}
+/**
+ * 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 async function packStarterIfPresent(pluginDir, outDir, manifest) {
+    const starterDir = join(pluginDir, "starter");
+    if (!existsSync(starterDir))
+        return null;
+    if (!isStarterBearing(manifest)) {
+        throw new UndeclaredStarterError(pluginDir);
+    }
+    const archivePath = join(outDir, "starter.tar.gz");
+    await create({
+        gzip: true,
+        file: archivePath,
+        cwd: starterDir,
+        filter: (entryPath) => !isExcluded(entryPath),
+    }, 
+    // Same convention as pack.ts: "." packs everything directly under
+    // starter/ at the archive root, not nested under a "starter/" folder.
+    ["."]);
+    return archivePath;
+}

package/dist/pack.d.ts

@@ -0,0 +1,12 @@
+import { type BuildResult } from "./build.js";
+export interface PackResult {
+    pluginDir: string;
+    archivePath: string;
+    buildResult: BuildResult;
+}
+/**
+ * Always runs buildPlugin() first (never packs a stale package), then
+ * tars the resulting velora-package/ directory into
+ * <pluginDir>/<id>-<version>.tar.gz.
+ */
+export declare function packPlugin(pluginDir: string, outFile?: string): Promise<PackResult>;

package/dist/pack.js

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+import { create } from "tar";
+import { buildPlugin } from "./build.js";
+import { loadManifest } from "./load-manifest.js";
+/**
+ * Always runs buildPlugin() first (never packs a stale package), then
+ * tars the resulting velora-package/ directory into
+ * <pluginDir>/<id>-<version>.tar.gz.
+ */
+export async function packPlugin(pluginDir, outFile) {
+    const buildResult = await buildPlugin(pluginDir);
+    const manifestResult = await loadManifest(pluginDir);
+    if (!manifestResult.ok) {
+        throw new Error(`manifest became invalid between build and pack for ${pluginDir}`);
+    }
+    const { id, version } = manifestResult.manifest;
+    const archivePath = outFile ?? join(pluginDir, `${id}-${version}.tar.gz`);
+    await create({ gzip: true, file: archivePath, cwd: buildResult.outDir }, 
+    // tar's `create` lists entries relative to `cwd` — "." packs
+    // everything directly under velora-package/ at the archive root
+    // (not nested under a "velora-package/" folder), so extracting the
+    // archive lands manifest.json/remoteEntry.js/server/ directly in
+    // the target directory.
+    ["."]);
+    return { pluginDir, archivePath, buildResult };
+}

package/dist/publish.d.ts

@@ -0,0 +1,24 @@
+export interface PublishOptions {
+    registryUrl: string;
+    token: string;
+}
+export type PublishResult = {
+    ok: true;
+    submissionId: string;
+    state: string;
+    failedChecks?: string[];
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
+/** Upload an already-packed archive. Split from publishPlugin so tests
+ * can exercise the HTTP contract without a 90-second validate+build. */
+export declare function uploadArchive(archivePath: string, opts: PublishOptions): Promise<PublishResult>;
+/** pack (which validates once, first, and fails fast — never uploads a
+ * package that can't pass its own local floor) → upload. validatePlugin
+ * is deliberately NOT called again here: buildPlugin (invoked by
+ * packPlugin) already runs the full validation suite, including a real
+ * federation build, and doing that twice per publish would double an
+ * already expensive step for no benefit. */
+export declare function publishPlugin(pluginDir: string, opts: PublishOptions): Promise<PublishResult>;

package/dist/publish.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { BuildValidationError } from "./build.js";
+import { packPlugin } from "./pack.js";
+/** Upload an already-packed archive. Split from publishPlugin so tests
+ * can exercise the HTTP contract without a 90-second validate+build. */
+export async function uploadArchive(archivePath, opts) {
+    const body = new FormData();
+    body.set("file", new Blob([readFileSync(archivePath)], { type: "application/gzip" }), basename(archivePath));
+    let response;
+    try {
+        response = await fetch(new URL("/api/v1/submissions", opts.registryUrl), {
+            method: "POST",
+            headers: { authorization: `Bearer ${opts.token}` },
+            body,
+        });
+    }
+    catch (error) {
+        return { ok: false, status: 0, message: `could not reach the registry at ${opts.registryUrl}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        return { ok: false, status: response.status, message: payload.message ?? `registry replied ${response.status}` };
+    }
+    return {
+        ok: true, submissionId: payload.submissionId ?? "", state: payload.state ?? "submitted",
+        ...(payload.failedChecks ? { failedChecks: payload.failedChecks } : {}),
+    };
+}
+/** pack (which validates once, first, and fails fast — never uploads a
+ * package that can't pass its own local floor) → upload. validatePlugin
+ * is deliberately NOT called again here: buildPlugin (invoked by
+ * packPlugin) already runs the full validation suite, including a real
+ * federation build, and doing that twice per publish would double an
+ * already expensive step for no benefit. */
+export async function publishPlugin(pluginDir, opts) {
+    try {
+        const packed = await packPlugin(pluginDir);
+        return uploadArchive(packed.archivePath, opts);
+    }
+    catch (error) {
+        if (error instanceof BuildValidationError) {
+            const failed = error.validation.checks.filter((c) => !c.passed).map((c) => c.name).join(", ");
+            return { ok: false, status: 0, message: `local validate failed (${failed}) — fix these before publishing` };
+        }
+        throw error;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export interface CheckResult {
+    name: string;
+    passed: boolean;
+    message: string;
+    details?: string;
+}
+export interface ValidationResult {
+    pluginDir: string;
+    checks: CheckResult[];
+    passed: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,5 @@
+import type { ValidationResult } from "./types.js";
+export type { CheckResult, ValidationResult } from "./types.js";
+export { loadManifest } from "./load-manifest.js";
+export { CLIENT_BUNDLE_TYPES, hasClientBundle } from "@velora-cms/plugin-sdk/manifest";
+export declare function validatePlugin(pluginDir: string): Promise<ValidationResult>;

package/dist/validate.js

@@ -0,0 +1,49 @@
+import { buildFederationBundle, cleanupFederationBuild } from "./build-federation-bundle.js";
+import { checkNpmAudit } from "./checks/audit.js";
+import { checkBundleSize } from "./checks/bundle-size.js";
+import { checkDatabaseCompatibility } from "./checks/db-compat.js";
+import { checkManifest } from "./checks/manifest.js";
+import { checkSharedDeps } from "./checks/shared-deps.js";
+import { checkTypeScript } from "./checks/typescript.js";
+import { checkRequiredViews } from "./checks/views.js";
+import { loadManifest } from "./load-manifest.js";
+import { hasClientBundle } from "@velora-cms/plugin-sdk/manifest";
+// Re-exported from the package root so consumers that only need manifest
+// loading (e.g. the marketplace seed script) don't need a new subpath —
+// validate.js is already the package's "." export.
+export { loadManifest } from "./load-manifest.js";
+// Same reasoning as loadManifest above: consumers of the artifact-shape
+// contract (S144) get it from the package root without a new subpath.
+export { CLIENT_BUNDLE_TYPES, hasClientBundle } from "@velora-cms/plugin-sdk/manifest";
+export async function validatePlugin(pluginDir) {
+    const manifestResult = await loadManifest(pluginDir);
+    const checks = [
+        checkManifest(manifestResult),
+        checkRequiredViews(manifestResult),
+        checkTypeScript(pluginDir),
+    ];
+    // S144: only client-bearing types ship a federation bundle — for
+    // theme/template/bundle there is nothing to size-check and no shared
+    // singletons to verify, and running Vite for them is pure waste. The
+    // checks stay in the report (passed, "not applicable") so a report
+    // always has the same shape regardless of type.
+    const clientBundle = manifestResult.ok ? hasClientBundle(manifestResult.manifest.type) : true;
+    if (clientBundle) {
+        const build = await buildFederationBundle(pluginDir);
+        try {
+            checks.push(checkBundleSize(build));
+            checks.push(checkSharedDeps(pluginDir, build));
+        }
+        finally {
+            cleanupFederationBuild(build);
+        }
+    }
+    else {
+        const message = `not applicable — ${manifestResult.ok ? manifestResult.manifest.type : ""} plugins ship no client bundle`;
+        checks.push({ name: "bundle size", passed: true, message });
+        checks.push({ name: "react/react-dom not bundled", passed: true, message });
+    }
+    checks.push(checkDatabaseCompatibility(manifestResult));
+    checks.push(checkNpmAudit(pluginDir));
+    return { pluginDir, checks, passed: checks.every((check) => check.passed) };
+}

package/dist/write-manifest-json.d.ts

@@ -0,0 +1,7 @@
+import type { CMSPlugin } from "@velora-cms/plugin-sdk/manifest";
+/** Writes `<outDir>/manifest.json` — a redacted, JSON-safe summary of a
+ * validated plugin manifest for marketplace listing/review without
+ * executing any code. Never the source of truth for install() (which
+ * needs the live manifest from server/plugin.js, see
+ * bundle-server-manifest.ts) — this file is display-only. */
+export declare function writeManifestJson(manifest: CMSPlugin, outDir: string): void;

package/dist/write-manifest-json.js

@@ -0,0 +1,72 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+const CONTRIBUTION_ENTRY_FIELDS = ["id", "name", "label", "icon", "version", "method", "path", "cron"];
+/**
+ * Redacts one contribution-array entry (e.g. one DataTypePlugin, one
+ * AdminSectionContribution) down to its plain string identifying fields
+ * — never the functions (views, serialize, onSelect, handler, ...) or
+ * raw JSON schemas a real contribution object also carries. A bare
+ * string entry (bundledPlugins' plugin ids) passes through unchanged.
+ */
+function summarizeContributionEntry(entry) {
+    if (entry === null || typeof entry !== "object")
+        return entry;
+    const record = entry;
+    const summary = {};
+    for (const field of CONTRIBUTION_ENTRY_FIELDS) {
+        if (typeof record[field] === "string")
+            summary[field] = record[field];
+    }
+    return summary;
+}
+/**
+ * Redacts a manifest's full `contributions` object to a JSON-safe
+ * summary suitable for marketplace listing/review without executing
+ * any code: array-valued contributions become arrays of
+ * summarizeContributionEntry results; `hooks` (a Record<event, handler
+ * function>) becomes just its event-name keys; `bundledTemplate` and
+ * `themeTokens` are already plain-string-valued objects, kept as-is;
+ * anything else present is recorded as `true` (contributed, no further
+ * detail available to redact safely).
+ */
+function summarizeContributions(contributions) {
+    const summary = {};
+    for (const [key, value] of Object.entries(contributions)) {
+        if (value == null)
+            continue;
+        if (Array.isArray(value)) {
+            summary[key] = value.map(summarizeContributionEntry);
+        }
+        else if (key === "hooks" && typeof value === "object") {
+            summary[key] = Object.keys(value);
+        }
+        else if (key === "bundledTemplate" || key === "themeTokens") {
+            summary[key] = value;
+        }
+        else {
+            summary[key] = true;
+        }
+    }
+    return summary;
+}
+/** Writes `<outDir>/manifest.json` — a redacted, JSON-safe summary of a
+ * validated plugin manifest for marketplace listing/review without
+ * executing any code. Never the source of truth for install() (which
+ * needs the live manifest from server/plugin.js, see
+ * bundle-server-manifest.ts) — this file is display-only. */
+export function writeManifestJson(manifest, outDir) {
+    const summary = {
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        type: manifest.type,
+        description: manifest.description,
+        author: manifest.author,
+        license: manifest.license,
+        cmsVersion: manifest.cmsVersion,
+        databaseCompatibility: manifest.databaseCompatibility,
+        permissions: manifest.permissions,
+        contributions: summarizeContributions(manifest.contributions),
+    };
+    writeFileSync(join(outDir, "manifest.json"), JSON.stringify(summary, null, 2));
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "velora-plugin",
+  "version": "0.9.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "velora-plugin": "dist/index.js"
+  },
+  "main": "dist/validate.js",
+  "types": "dist/validate.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velora-cms/velora.git",
+    "directory": "packages/velora-plugin"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/validate.d.ts",
+      "import": "./dist/validate.js",
+      "default": "./dist/validate.js"
+    },
+    "./pack": {
+      "types": "./dist/pack.d.ts",
+      "import": "./dist/pack.js",
+      "default": "./dist/pack.js"
+    }
+  },
+  "dependencies": {
+    "@module-federation/vite": "1.16.12",
+    "@vitejs/plugin-react": "4.7.0",
+    "tar": "^7.5.19",
+    "tsx": "4.22.4",
+    "typescript": "6.0.3",
+    "vite": "6.4.3",
+    "@velora-cms/plugin-sdk": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "@types/react": "19.2.17",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "create-velora-plugin": "0.9.0"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run"
+  }
+}