feat: implement third-party artifact binding and app bundle resolver for multi-project support

Author: hotlong

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Third-party project binding via `metadata.artifact_path`** — Multi-project `POST /api/v1/cloud/projects` now accepts `metadata.artifact_path` to bind a locally-compiled bundle (e.g. `examples/app-crm/dist/objectstack.json`) into a fresh project. Provisioning loads the JSON, registers schemas in the per-project ObjectQL engine, and seeds the bundle's `data` arrays — same pipeline that built-in templates use. New `TemplateSeeder.seedBundle({ projectId, bundle })` method exposes the seeder for arbitrary bundles. Bind errors (read failure, malformed JSON) are recorded as non-fatal `metadata.artifactBindError` so the project still flips to `active`. Verified end-to-end: query `/api/v1/projects/{id}/data/account` returns the seeded CRM accounts.
+- **`AppBundleResolver` for live kernel binding** — `apps/server` now ships `createFsAppBundleResolver()` in `apps/server/server/fs-app-bundle-resolver.ts`. Reads `sys_project.metadata.artifact_path` (or `artifact_paths[]`) at per-project kernel boot, with optional `OBJECTSTACK_PROJECT_ARTIFACTS=projId:path,…` env override and `OBJECTSTACK_PROJECT_ARTIFACT_ROOT` for relative path resolution. Used wherever a project kernel is materialized (trigger / function / metadata API requests). Replaces the previous `return []` stub.
+
 ### Fixed
 - `apps/server`: `GET /api/v1/cloud/templates` now returns the full template registry (`blank`, `crm`, `todo`) on Vercel / play.objectstack.ai. Root cause: the dispatcher resolved templates through a `template-seeder` service registered by `MultiProjectPlugin`, and on Vercel cold starts that service registration could be missed by the request handler — the dispatcher then silently returned `{ templates: [], total: 0 }`. Added a `createTemplatesRoutePlugin` that registers `/cloud/templates` directly on `http.server` from a static, module-scope `listTemplates()` snapshot, registered before `DispatcherPlugin`. Local single-project mode is unchanged.
 - `packages/runtime/http-dispatcher.ts`: `/cloud/templates` fallback now logs the resolution error via `console.error` instead of swallowing it silently, so the underlying cause is visible in production logs.

apps/server/objectstack.config.ts

@@ -50,6 +50,7 @@ import { createSingleProjectPlugin } from './server/single-project-plugin.js';
 import { createStudioRuntimeConfigPlugin, createTemplatesRoutePlugin } from './server/multi-project-plugins.js';
 import { listTemplates } from './server/templates/registry.js';
 import { templateRegistry } from './server/templates/registry.js';
+import { createFsAppBundleResolver } from './server/fs-app-bundle-resolver.js';
 
 type IDataDriver = Contracts.IDataDriver;
 
@@ -197,9 +198,7 @@ const basePlugins: BasePluginsFactory = async ({ projectId, project }) => {
     ];
 };
 
-const appBundles: AppBundleResolver = {
-    async resolve() { return []; },
-};
+const appBundles: AppBundleResolver = createFsAppBundleResolver();
 
 // Single shared promise — both control-plane plugins and MultiProjectPlugin
 // use the same DB connection.

apps/server/server/fs-app-bundle-resolver.ts

@@ -0,0 +1,115 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * File-System AppBundleResolver
+ *
+ * Resolves the artifact bundles a project is bound to by reading the
+ * project's row from the control plane (`sys_project.metadata`) and
+ * loading any artifact files referenced there.
+ *
+ * Binding model — a project's metadata column may carry:
+ *   {
+ *     "artifact_path": "./examples/app-crm/dist/objectstack.json",
+ *     // -- OR --
+ *     "artifact_paths": ["./pkg-a/dist/objectstack.json", "./pkg-b/dist/objectstack.json"]
+ *   }
+ *
+ * Paths are resolved relative to `OBJECTSTACK_PROJECT_ARTIFACT_ROOT`
+ * (defaults to `process.cwd()`). Absolute paths are honored as-is.
+ *
+ * For pure dev convenience, an env-var override is also supported:
+ *   OBJECTSTACK_PROJECT_ARTIFACTS=proj_crm:/abs/path/crm.json,proj_todo:/abs/path/todo.json
+ * Entries listed there override `metadata.artifact_path` for that
+ * project id, so a developer can rebind without rewriting the DB row.
+ *
+ * On read errors (missing file, malformed JSON) the resolver logs a
+ * warning and returns `[]` for that path — the kernel still boots, just
+ * without that bundle, which is the same behaviour as the legacy stub.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve as resolvePath, isAbsolute } from 'node:path';
+import type { AppBundleResolver } from '@objectstack/runtime';
+
+const ENV_MAP_VAR = 'OBJECTSTACK_PROJECT_ARTIFACTS';
+const ARTIFACT_ROOT_VAR = 'OBJECTSTACK_PROJECT_ARTIFACT_ROOT';
+
+function parseEnvMap(raw: string | undefined): Map<string, string[]> {
+    const map = new Map<string, string[]>();
+    if (!raw) return map;
+    for (const segment of raw.split(',')) {
+        const trimmed = segment.trim();
+        if (!trimmed) continue;
+        const idx = trimmed.indexOf(':');
+        if (idx <= 0) continue;
+        const projectId = trimmed.slice(0, idx).trim();
+        const path = trimmed.slice(idx + 1).trim();
+        if (!projectId || !path) continue;
+        const list = map.get(projectId) ?? [];
+        list.push(path);
+        map.set(projectId, list);
+    }
+    return map;
+}
+
+function extractMetadataPaths(metadata: any): string[] {
+    if (!metadata || typeof metadata !== 'object') return [];
+    const out: string[] = [];
+    if (typeof metadata.artifact_path === 'string') out.push(metadata.artifact_path);
+    if (Array.isArray(metadata.artifact_paths)) {
+        for (const p of metadata.artifact_paths) {
+            if (typeof p === 'string') out.push(p);
+        }
+    }
+    return out;
+}
+
+export function createFsAppBundleResolver(): AppBundleResolver {
+    const envMap = parseEnvMap(process.env[ENV_MAP_VAR]);
+    const root = process.env[ARTIFACT_ROOT_VAR] ?? process.cwd();
+    const cache = new Map<string, any>();
+
+    async function loadOne(path: string): Promise<any | null> {
+        const abs = isAbsolute(path) ? path : resolvePath(root, path);
+        if (cache.has(abs)) return cache.get(abs);
+        try {
+            const raw = await readFile(abs, 'utf-8');
+            const parsed = JSON.parse(raw);
+            cache.set(abs, parsed);
+            return parsed;
+        } catch (err: any) {
+            // eslint-disable-next-line no-console
+            console.warn(
+                `[FsAppBundleResolver] Failed to load artifact '${abs}': ${err?.message ?? err}`,
+            );
+            cache.set(abs, null);
+            return null;
+        }
+    }
+
+    return {
+        async resolve(project) {
+            const projectId = (project as any)?.id;
+            // Env-var override wins so devs can hot-swap without a DB write.
+            const overridePaths = projectId ? envMap.get(projectId) : undefined;
+            // sys_project.metadata is stored as JSON text in some drivers; tolerate both.
+            let meta: any = (project as any)?.metadata;
+            if (typeof meta === 'string') {
+                try { meta = JSON.parse(meta); } catch { meta = undefined; }
+            }
+            const metadataPaths = extractMetadataPaths(meta);
+
+            const paths = overridePaths && overridePaths.length > 0
+                ? overridePaths
+                : metadataPaths;
+            if (paths.length === 0) return [];
+
+            const bundles: any[] = [];
+            for (const p of paths) {
+                const b = await loadOne(p);
+                if (b) bundles.push(b);
+            }
+            return bundles;
+        },
+    };
+}

packages/runtime/src/http-dispatcher.ts

@@ -1731,6 +1731,54 @@ export class HttpDispatcher {
                                 }
                             }
                         }
+
+                        // Bind a third-party developer's locally compiled artifact
+                        // into this project. The caller passes
+                        // `metadata.artifact_path` (path to a compiled
+                        // ObjectStack bundle JSON) and we delegate to the same
+                        // seeder pipeline that templates use. Resolved relative
+                        // to OBJECTSTACK_PROJECT_ARTIFACT_ROOT (or process.cwd
+                        // if unset).
+                        const artifactPathRaw = (baseMetadata as any).artifact_path;
+                        if (typeof artifactPathRaw === 'string' && artifactPathRaw.length > 0) {
+                            try {
+                                const fs = await import('node:fs/promises');
+                                const path = await import('node:path');
+                                const root = process.env.OBJECTSTACK_PROJECT_ARTIFACT_ROOT
+                                    ?? process.cwd();
+                                const resolved = path.isAbsolute(artifactPathRaw)
+                                    ? artifactPathRaw
+                                    : path.resolve(root, artifactPathRaw);
+                                const text = await fs.readFile(resolved, 'utf8');
+                                const bundle = JSON.parse(text);
+                                const seeder: any = await this.resolveService('template-seeder');
+                                if (seeder?.seedBundle) {
+                                    await seeder.seedBundle({ projectId, bundle });
+                                } else {
+                                    throw new Error('template-seeder.seedBundle is unavailable');
+                                }
+                            } catch (bindErr) {
+                                const bindMessage = bindErr instanceof Error ? bindErr.message : String(bindErr);
+                                try {
+                                    const existing = await findOne(ENV, { id: projectId });
+                                    const existingMeta = typeof existing?.metadata === 'string'
+                                        ? JSON.parse(existing.metadata)
+                                        : (existing?.metadata ?? {});
+                                    await ql.update(
+                                        ENV,
+                                        {
+                                            metadata: JSON.stringify({
+                                                ...existingMeta,
+                                                artifactBindError: { message: bindMessage, artifactPath: artifactPathRaw },
+                                            }),
+                                        },
+                                        { where: { id: projectId } } as any,
+                                    );
+                                } catch {
+                                    // Best-effort metadata update — ignore secondary failure.
+                                }
+                            }
+                        }
                     } catch (err) {
                         const message = err instanceof Error ? err.message : String(err);
                         const failedAt = new Date().toISOString();

packages/runtime/src/multi-project-plugin.ts

@@ -57,6 +57,13 @@ export interface ProjectTemplate {
 export interface TemplateSeeder {
     listTemplates(): Array<Pick<ProjectTemplate, 'id' | 'label' | 'description' | 'category'>>;
     seed(params: { projectId: string; templateId: string }): Promise<void>;
+    /**
+     * Seed an arbitrary `ObjectStackDefinition`-shaped bundle into the
+     * given project. Used for binding a third-party developer's locally
+     * compiled artifact (e.g. `examples/app-crm/dist/objectstack.json`)
+     * into a multi-project server at provisioning time.
+     */
+    seedBundle(params: { projectId: string; bundle: any }): Promise<void>;
 }
 
 export interface MultiProjectPluginConfig {
@@ -131,6 +138,87 @@ function createTemplateSeeder(
     templates: Record<string, ProjectTemplate>,
     envRegistry: EnvironmentDriverRegistry,
 ): TemplateSeeder {
+    const seedBundleForProject = async (projectId: string, bundle: any): Promise<void> => {
+        const items = bundle ? extractMetadataItems(bundle) : [];
+        const dataSets = bundle ? namespaceDatasets(bundle) : [];
+
+        // Empty bundle (e.g. the "blank" template) → nothing to seed.
+        if (items.length === 0 && dataSets.length === 0) return;
+
+        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') {
+            const cached = envRegistry.peekById(projectId);
+            const orgId = (cached?.project as any)?.organization_id as string | undefined;
+            try { metadata.setDataEngine(engine, orgId, projectId); } catch { /* already set */ }
+        }
+
+        if (items.length > 0) {
+            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}`,
+                );
+            }
+        }
+
+        // Register the bundle into the ObjectQL engine's SchemaRegistry so that
+        // syncSchemas() can create tables for the newly-registered objects.
+        // bulkRegister() only updates MetadataManager's registry, not the engine's
+        // internal _registry — without this, syncSchemas() has no objects to create.
+        if (items.length > 0 && typeof engine?.registerApp === 'function') {
+            try { (engine as any).registerApp(bundle); } catch { /* best effort */ }
+        }
+
+        // Sync schemas so tables exist before seeding.
+        if (items.length > 0 && typeof engine?.syncSchemas === 'function') {
+            try { await engine.syncSchemas(); } catch { /* best effort */ }
+        }
+
+        if (dataSets.length > 0) {
+            const seedLoader = new SeedLoaderService(engine, metadata, console as any);
+            const config = SeedLoaderConfigSchema.parse({});
+            await seedLoader.load({ datasets: dataSets, config });
+        }
+
+        // Force a persistence flush so the per-project JSON file is
+        // written before the provisioning handler returns; otherwise
+        // the memory driver's dirty flag only saves on a 2s timer and
+        // early HTTP responses may see an empty file on disk.
+        const driverWithFlush = (kernel as any).services?.driver ?? (kernel as any).getService?.('driver');
+        const flushable = typeof driverWithFlush?.flush === 'function'
+            ? driverWithFlush
+            : null;
+        if (flushable) {
+            try { await flushable.flush(); } catch { /* best effort */ }
+        }
+    };
+
     return {
         listTemplates() {
             return Object.values(templates).map(({ id, label, description, category }) => ({
@@ -150,84 +238,11 @@ function createTemplateSeeder(
             }
 
             const bundle = await template.load();
-            const items = bundle ? extractMetadataItems(bundle) : [];
-            const dataSets = bundle ? namespaceDatasets(bundle) : [];
-
-            // Empty bundle (e.g. the "blank" template) → nothing to seed.
-            if (items.length === 0 && dataSets.length === 0) return;
-
-            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') {
-                const cached = envRegistry.peekById(projectId);
-                const orgId = (cached?.project as any)?.organization_id as string | undefined;
-                try { metadata.setDataEngine(engine, orgId, projectId); } catch { /* already set */ }
-            }
-
-            if (items.length > 0) {
-                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}`,
-                    );
-                }
-            }
-
-            // Register the bundle into the ObjectQL engine's SchemaRegistry so that
-            // syncSchemas() can create tables for the newly-registered objects.
-            // bulkRegister() only updates MetadataManager's registry, not the engine's
-            // internal _registry — without this, syncSchemas() has no objects to create.
-            if (items.length > 0 && typeof engine?.registerApp === 'function') {
-                try { (engine as any).registerApp(bundle); } catch { /* best effort */ }
-            }
-
-            // Sync schemas so tables exist before seeding.
-            if (items.length > 0 && typeof engine?.syncSchemas === 'function') {
-                try { await engine.syncSchemas(); } catch { /* best effort */ }
-            }
-
-            if (dataSets.length > 0) {
-                const seedLoader = new SeedLoaderService(engine, metadata, console as any);
-                const config = SeedLoaderConfigSchema.parse({});
-                await seedLoader.load({ datasets: dataSets, config });
-            }
+            await seedBundleForProject(projectId, bundle);
+        },
 
-            // Force a persistence flush so the per-project JSON file is
-            // written before the provisioning handler returns; otherwise
-            // the memory driver's dirty flag only saves on a 2s timer and
-            // early HTTP responses may see an empty file on disk.
-            const driverWithFlush = (kernel as any).services?.driver ?? (kernel as any).getService?.('driver');
-            const flushable = typeof driverWithFlush?.flush === 'function'
-                ? driverWithFlush
-                : null;
-            if (flushable) {
-                try { await flushable.flush(); } catch { /* best effort */ }
-            }
+        async seedBundle({ projectId, bundle }) {
+            await seedBundleForProject(projectId, bundle);
         },
     };
 }