feat(template-seeding): implement project template seeding and management

Author: hotlong

apps/server/objectstack.config.ts

@@ -14,7 +14,7 @@
  */
 
 import { defineStack } from '@objectstack/spec';
-import { AppPlugin, DriverPlugin } from '@objectstack/runtime';
+import { DriverPlugin } from '@objectstack/runtime';
 import { ObjectQLPlugin } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 import { TursoDriver } from '@objectstack/driver-turso';
@@ -27,9 +27,6 @@ import { MetadataPlugin } from '@objectstack/metadata';
 import { AIServicePlugin } from '@objectstack/service-ai';
 import { AutomationServicePlugin } from '@objectstack/service-automation';
 import { AnalyticsServicePlugin } from '@objectstack/service-analytics';
-import CrmApp from '../../examples/app-crm/objectstack.config';
-import TodoApp from '../../examples/app-todo/objectstack.config';
-import BiPluginManifest from '../../examples/plugin-bi/objectstack.config';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
@@ -70,7 +67,7 @@ export default defineStack({
     namespace: 'server',
     name: 'ObjectStack Server',
     version: '1.0.0',
-    description: 'Production server aggregating CRM, Todo and BI plugins',
+    description: 'Production server — multi-project control plane',
     type: 'app',
   },
   // Phase 3: enable project-scoped URLs (/api/v1/projects/:projectId/...)
@@ -91,9 +88,6 @@ export default defineStack({
     },
     new DriverPlugin(new InMemoryDriver(), 'memory'),
     new DriverPlugin(tursoDriver, 'turso'),
-    new AppPlugin(CrmApp),
-    new AppPlugin(TodoApp),
-    new AppPlugin(BiPluginManifest),
     new SetupPlugin(),
     new AuthPlugin({
       secret: process.env.AUTH_SECRET ?? 'dev-secret-please-change-in-production-min-32-chars',

apps/server/server/bootstrap.ts

@@ -41,6 +41,7 @@ import { TursoDriver } from '@objectstack/driver-turso';
 import { SqlDriver } from '@objectstack/driver-sql';
 import type { Contracts } from '@objectstack/spec';
 import { createControlPlanePlugins } from './control-plane-preset.js';
+import { createTemplateSeeder } from './template-seeder.js';
 
 type IDataDriver = Contracts.IDataDriver;
 
@@ -194,40 +195,10 @@ async function bootstrapMultiProject(
         ),
     });
 
-    // MVP app-bundle resolver.
-    //
-    // The example CRM / Todo / BI bundles are loaded lazily *and* gated on
-    // an env flag so that:
-    //   1. Test environments (E2E, unit tests) can skip them entirely —
-    //      the example `defineStack(...)` configs perform their own Zod
-    //      validation on import, so a single unrelated schema drift in
-    //      an example would otherwise crash bootstrap for everyone.
-    //   2. Production multi-project deployments that do not ship the
-    //      reference apps (the typical case) avoid paying the cost.
-    //
-    // Set `OBJECTSTACK_BUNDLE_EXAMPLES=true` to get the legacy behaviour —
-    // all three example bundles are attached to every project kernel.
-    // Swap this resolver for a registry-backed one once
-    // `sys_project_package` is consulted.
+    // Example bundles are no longer pre-installed into every project kernel.
+    // They are seeded once at provisioning time via `createTemplateSeeder`.
     const appBundles: AppBundleResolver = {
-        async resolve() {
-            if (process.env.OBJECTSTACK_BUNDLE_EXAMPLES !== 'true') {
-                return [];
-            }
-            // Dynamic `new Function('return import(...)')(…)` sidesteps
-            // TypeScript's static rootDir analysis — the example configs
-            // live outside apps/server's tsconfig rootDir but are still
-            // resolvable at runtime. Kept here intentionally so the tsc
-            // typecheck doesn't need a dedicated include for examples.
-            const dyn = (spec: string) =>
-                (new Function('s', 'return import(s)') as (s: string) => Promise<any>)(spec);
-            const [crm, todo, bi] = await Promise.all([
-                dyn('../../../examples/app-crm/objectstack.config.ts'),
-                dyn('../../../examples/app-todo/objectstack.config.ts'),
-                dyn('../../../examples/plugin-bi/objectstack.config.ts'),
-            ]);
-            return [crm.default, todo.default, bi.default];
-        },
+        async resolve() { return []; },
     };
 
     // Per-project kernels only need the minimal base — driver is injected
@@ -259,6 +230,11 @@ async function bootstrapMultiProject(
 
     const controlKernel = await bootstrapControlKernel(controlDriver, driverName);
 
+    // Register the template seeder so http-dispatcher can resolve it during
+    // provisioning via `kernel.getServiceAsync('template-seeder')`.
+    const seeder = createTemplateSeeder(kernelManager);
+    controlKernel.registerService('template-seeder', seeder);
+
     return {
         kernel: controlKernel,
         kernelManager,

apps/server/server/template-seeder.ts

@@ -0,0 +1,90 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { SeedLoaderService } from '@objectstack/runtime';
+import type { KernelManager } from '@objectstack/runtime';
+import { templateRegistry, listTemplates } from './templates/registry.js';
+import { extractMetadataItems } from './templates/extract.js';
+
+export interface TemplateSeeder {
+    seed(params: { projectId: string; templateId: string }): Promise<void>;
+    listTemplates(): Array<{ id: string; label: string; description: string; category?: string }>;
+}
+
+export function createTemplateSeeder(kernelManager: KernelManager): TemplateSeeder {
+    return {
+        listTemplates,
+
+        async seed({ projectId, templateId }) {
+            const template = templateRegistry[templateId];
+            if (!template) {
+                throw new Error(
+                    `Unknown template: '${templateId}'. Available: [${Object.keys(templateRegistry).join(', ')}]`,
+                );
+            }
+
+            // blank has no metadata to seed — skip early
+            if (templateId === 'blank') return;
+
+            const bundle = await template.load();
+            const items = extractMetadataItems(bundle);
+
+            if (items.length === 0) {
+                throw new Error(
+                    `template '${templateId}' produced 0 metadata items — bundle shape unexpected (keys=[${bundle ? Object.keys(bundle).join(',') : 'null'}])`,
+                );
+            }
+
+            const kernel = await kernelManager.getOrCreate(projectId);
+
+            let metadata: any;
+            try {
+                metadata = await kernel.getServiceAsync('metadata');
+            } catch (err: any) {
+                throw new Error(
+                    `metadata service unavailable for project ${projectId}: ${err?.message ?? err}`,
+                );
+            }
+            if (!metadata || typeof metadata.bulkRegister !== 'function') {
+                throw new Error(
+                    `metadata.bulkRegister unavailable for project ${projectId} (got ${metadata ? typeof metadata : 'null'})`,
+                );
+            }
+
+            const engine: any = await kernel
+                .getServiceAsync('objectql')
+                .catch(() => null);
+            if (!engine) {
+                throw new Error(
+                    `objectql engine unavailable for project ${projectId} — metadata persistence would be in-memory only`,
+                );
+            }
+            if (typeof metadata.setDataEngine === 'function') {
+                // Defensive: ensure DatabaseLoader is wired even if
+                // MetadataPlugin.start() missed it (e.g. plugin order race).
+                try { metadata.setDataEngine(engine, undefined, projectId); } catch { /* already set */ }
+            }
+
+            const result: any = await metadata.bulkRegister(items, { continueOnError: true });
+            const failed = result?.failed ?? 0;
+            if (failed > 0) {
+                const errs = (result?.errors ?? [])
+                    .slice(0, 5)
+                    .map((e: any) => `${e?.type}/${e?.name}: ${e?.error ?? 'unknown'}`)
+                    .join('; ');
+                throw new Error(
+                    `bulkRegister reported ${failed} failures for project ${projectId}: ${errs}`,
+                );
+            }
+
+            // Seed row data if the bundle ships datasets
+            if (Array.isArray(bundle.data) && bundle.data.length > 0) {
+                const seedLoader = new SeedLoaderService(
+                    engine,
+                    metadata,
+                    console as any,
+                );
+                await seedLoader.load({ datasets: bundle.data, config: {} });
+            }
+        },
+    };
+}

apps/server/server/templates/blank.ts

@@ -0,0 +1,13 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ProjectTemplate } from './types.js';
+
+export const blankTemplate: ProjectTemplate = {
+    id: 'blank',
+    label: 'Blank',
+    description: 'Empty project — start from scratch.',
+    category: 'starter',
+    async load() {
+        return { manifest: { id: 'blank', namespace: 'blank' }, objects: [] } as any;
+    },
+};

apps/server/server/templates/crm.ts

@@ -0,0 +1,32 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as path from 'node:path';
+import type { ProjectTemplate } from './types.js';
+
+// Resolve the CRM bundle relative to THIS file so the path survives any
+// compilation/build output layout. Using a file:// URL means we can hand
+// the path to a dynamic import() without TypeScript trying to type-check
+// the target (which lives outside apps/server's rootDir).
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATH = path.resolve(HERE, '../../../../examples/app-crm/objectstack.config.ts');
+const BUNDLE_URL = pathToFileURL(BUNDLE_PATH).href;
+
+// Lazy dynamic import — the bundle's Zod evaluation is deferred until the
+// template is actually selected, so a schema drift in the example cannot
+// crash control-plane bootstrap.
+const dyn = (spec: string): Promise<any> =>
+    (new Function('s', 'return import(s)') as (s: string) => Promise<any>)(spec);
+
+export const crmTemplate: ProjectTemplate = {
+    id: 'crm',
+    label: 'CRM Starter',
+    description: 'Accounts, Contacts, Opportunities — full CRM example.',
+    category: 'business',
+    async load() {
+        const mod = await dyn(BUNDLE_URL);
+        // ESM default can be nested under `.default.default` when the
+        // loader double-wraps (tsx + file:// URL). Unwrap defensively.
+        return mod?.default?.manifest ? mod.default : (mod?.default?.default ?? mod?.default ?? mod);
+    },
+};

apps/server/server/templates/extract.ts

@@ -0,0 +1,51 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Flatten an `ObjectStackDefinition` bundle into the `{type, name, data}`
+ * shape consumed by `MetadataPlugin.bulkRegister`.
+ *
+ * Object names are namespaced (`${ns}__${name}`) when the bundle declares
+ * a non-reserved namespace and the name is not already prefixed. Other
+ * metadata types (view/dashboard/flow/...) are preserved as-is to match
+ * the existing AppPlugin install path.
+ *
+ * Skipped on purpose:
+ *   - apis / actions   — handler refs require kernel code, not metadata only
+ *   - translations     — needs i18n plugin
+ *   - sharingRules / roles — needs security plugin
+ *   - onEnable hooks   — code, not metadata
+ */
+export interface ExtractedItem {
+    type: string;
+    name: string;
+    data: unknown;
+}
+
+const RESERVED_NS = new Set(['base', 'system']);
+
+export function extractMetadataItems(bundle: any): ExtractedItem[] {
+    const items: ExtractedItem[] = [];
+    const ns = bundle?.manifest?.namespace as string | undefined;
+
+    const toFQN = (name: string): string =>
+        name.includes('__') || !ns || RESERVED_NS.has(ns) ? name : `${ns}__${name}`;
+
+    const pushAll = (type: string, arr?: any[], rewriteName = false) => {
+        for (const item of arr ?? []) {
+            if (!item?.name) continue;
+            const name = rewriteName ? toFQN(item.name) : item.name;
+            const data = rewriteName ? { ...item, name } : item;
+            items.push({ type, name, data });
+        }
+    };
+
+    pushAll('object', bundle?.objects, true);
+    pushAll('view', bundle?.views);
+    pushAll('dashboard', bundle?.dashboards);
+    pushAll('report', bundle?.reports);
+    pushAll('flow', bundle?.flows);
+    pushAll('agent', bundle?.agents);
+    pushAll('app', bundle?.apps);
+
+    return items;
+}

apps/server/server/templates/registry.ts

@@ -0,0 +1,25 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { blankTemplate } from './blank.js';
+import { crmTemplate } from './crm.js';
+import { todoTemplate } from './todo.js';
+import type { ProjectTemplate } from './types.js';
+
+export const templateRegistry: Record<string, ProjectTemplate> = {
+    [blankTemplate.id]: blankTemplate,
+    [crmTemplate.id]: crmTemplate,
+    [todoTemplate.id]: todoTemplate,
+};
+
+export const DEFAULT_TEMPLATE_ID = 'blank';
+
+export function listTemplates(): Array<Pick<ProjectTemplate, 'id' | 'label' | 'description' | 'category'>> {
+    return Object.values(templateRegistry).map(({ id, label, description, category }) => ({
+        id,
+        label,
+        description,
+        category,
+    }));
+}
+
+export type { ProjectTemplate } from './types.js';

apps/server/server/templates/todo.ts

@@ -0,0 +1,17 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ProjectTemplate } from './types.js';
+
+const dyn = (spec: string) =>
+    (new Function('s', 'return import(s)') as (s: string) => Promise<any>)(spec);
+
+export const todoTemplate: ProjectTemplate = {
+    id: 'todo',
+    label: 'Todo List',
+    description: 'Lightweight task tracker — single-object example.',
+    category: 'starter',
+    async load() {
+        const mod = await dyn('../../../../examples/app-todo/objectstack.config.ts');
+        return mod.default;
+    },
+};

apps/server/server/templates/types.ts

@@ -0,0 +1,24 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Project Template — descriptor used by the provisioning seeder.
+ *
+ * A template's `load()` returns an `ObjectStackDefinition`-shaped bundle
+ * (objects/views/dashboards/flows/agents/apps/data) which is then fanned
+ * out into `bulkRegister` calls against the freshly-provisioned project
+ * kernel. Loading is async + lazy so example bundles are evaluated only
+ * when the template is actually selected — a Zod drift in one example
+ * cannot crash control-plane bootstrap.
+ */
+export interface ProjectTemplate {
+    /** Stable id used by the API / Studio selector. */
+    id: string;
+    /** Human-readable label shown in Studio. */
+    label: string;
+    /** Short description for the picker. */
+    description: string;
+    /** Optional category tag. */
+    category?: string;
+    /** Lazy bundle loader. Must be cheap to call repeatedly. */
+    load(): Promise<any>;
+}