feat: Enhance local project support and artifact handling

- Updated ROADMAP.md to reflect completion of local project environment paths and Drift fixes.
- Modified objectstack.config.ts to support local mode with specific environment variables and artifact compilation.
- Added new Project Artifact documentation to clarify the response shape of the artifact API.
- Removed outdated plugin-bi example and its associated files.
- Improved metadata plugin to load from local artifact files and handle metadata registration.
- Updated dev command to compile objectstack.config.ts when necessary and streamline local development setup.

Author: hotlong

ROADMAP.md

@@ -160,9 +160,9 @@ Ordered by dependency. Items higher in the list unblock those below them.
 明确 ObjectOS 启动输入 = **Artifact**（不可变、可缓存的元数据信封）+ **Deployment Config**（业务 DB 坐标、凭据、项目身份、密钥；不进 artifact）。详见 [north-star.mdx §6.3](content/docs/concepts/north-star.mdx)。
 
 - [x] north-star.mdx §6.3 增补 Runtime Inputs 节（含本地单 project env 表 + 反模式说明）
-- [ ] 实现本地单 project env 路径：`OBJECTSTACK_PROJECT_ID` / `OBJECTSTACK_DATABASE_URL` / `OBJECTSTACK_DATABASE_DRIVER` / `OBJECTSTACK_ARTIFACT_PATH`（默认 `./dist/objectstack.json`）/ `OBJECTSTACK_CLOUD_URL`（可选，留空即离线）/ `AUTH_SECRET`
-- [ ] 修复 Drift：`ProjectKernelFactory` 不再直连控制面 DB 读 `sys_project` / `sys_project_credential`，改走 Artifact API + Deployment Config 注入
-- [ ] [apps/server/objectstack.config.ts](apps/server/objectstack.config.ts) 的 env 命名收敛到 `OBJECTSTACK_*` 前缀
+- [x] 实现本地单 project env 路径：`OBJECTSTACK_PROJECT_ID` / `OBJECTSTACK_DATABASE_URL` / `OBJECTSTACK_DATABASE_DRIVER` / `OBJECTSTACK_ARTIFACT_PATH`（默认 `./dist/objectstack.json`）/ `OBJECTSTACK_CLOUD_URL`（可选，留空即离线）/ `AUTH_SECRET`
+- [x] 修复 Drift：`ProjectKernelFactory` 不再直连控制面 DB 读 `sys_project` / `sys_project_credential`，改走 Artifact API + Deployment Config 注入（`localProject` 分支）
+- [x] [apps/server/objectstack.config.ts](apps/server/objectstack.config.ts) 的 env 命名收敛到 `OBJECTSTACK_*` 前缀，`isLocalMode` 分流本地/云端路径
 
 **Resolves:** Open Question §9.2（已解决）+ 新增 Drift（`ProjectKernelFactory` 绕过 Artifact API）。
 

apps/server/objectstack.config.ts

@@ -5,27 +5,30 @@
  *
  * Booted by `objectstack dev` / `objectstack serve` (see `package.json`).
  *
- * The CLI loads this file, registers the plugins below on a fresh
- * `ObjectKernel`, then auto-mounts the standard HTTP stack
- * (HonoServerPlugin, Setup, RestAPI, Dispatcher, I18nService).
+ * ## Boot modes
  *
- * Our plugin list:
- *  1. `createControlPlanePlugins(...)` — ObjectQL + driver + tenant +
- *     system-project + auth/security/audit + metadata for `sys_*`.
- *  2. `MultiProjectPlugin` — registers `env-registry`, `kernel-manager`
- *     and `template-seeder` on the control kernel so HttpDispatcher can
- *     route requests to per-project kernels via hostname / X-Project-Id.
+ * ### Local mode  (`OBJECTSTACK_CLOUD_URL` is unset)
  *
- * The control-plane driver is selected from a single URL-style env var
- * (Turso/Prisma convention):
+ * Single-project, offline-first.  No control-plane DB is required.
+ * Required env vars:
+ *   OBJECTSTACK_PROJECT_ID        — project identity (e.g. "proj_local")
+ *   OBJECTSTACK_DATABASE_URL      — project business DB (file:./app.db, memory://mydb, libsql://…)
+ *   OBJECTSTACK_DATABASE_DRIVER   — driver name: sqlite | memory | turso | postgres
+ *   OBJECTSTACK_ARTIFACT_PATH     — path to compiled artifact (default: ./dist/objectstack.json)
+ *   AUTH_SECRET                   — JWT signing secret (≥32 chars)
  *
- *   OBJECTSTACK_DATABASE_URL
- *     - unset                 → `file:./.objectstack/data/control.db`
- *     - `file:<path>` / path  → SQLite at that path (better-sqlite3)
- *     - `libsql://…`          → libSQL/Turso
- *     - `http(s)://…`         → libSQL/sqld over HTTP
+ * ### Cloud mode  (`OBJECTSTACK_CLOUD_URL` is set)
  *
- *   OBJECTSTACK_DATABASE_AUTH_TOKEN — optional, for libSQL/HTTP URLs.
+ * Multi-project, control-plane connected.
+ * Required env vars:
+ *   OBJECTSTACK_DATABASE_URL      — control-plane DB URL
+ *   OBJECTSTACK_DATABASE_AUTH_TOKEN — optional, for libSQL/Turso URLs
+ *   AUTH_SECRET / NEXT_PUBLIC_BASE_URL — same as local
+ *
+ * The control-plane driver URL accepts:
+ *   - unset / `file:<path>`  → SQLite (better-sqlite3)  [default: .objectstack/data/control.db]
+ *   - `libsql://…`           → libSQL / Turso
+ *   - `http(s)://…`          → libSQL / sqld over HTTP
  */
 
 import { resolve as resolvePath } from 'node:path';
@@ -39,11 +42,58 @@ import { templateRegistry } from './server/templates/registry.js';
 
 type IDataDriver = Contracts.IDataDriver;
 
-/**
- * Resolve the control-plane driver from `OBJECTSTACK_DATABASE_URL`.
- * Drivers are loaded via dynamic import() so esbuild does not bundle
- * the database libraries (better-sqlite3, libsql) at parse time.
- */
+// ── Discriminator ─────────────────────────────────────────────────────────────
+const isLocalMode = !process.env.OBJECTSTACK_CLOUD_URL;
+
+const authSecret = process.env.AUTH_SECRET
+    ?? 'dev-secret-please-change-in-production-min-32-chars';
+const baseUrl = process.env.NEXT_PUBLIC_BASE_URL
+    ?? (process.env.VERCEL_PROJECT_PRODUCTION_URL
+        ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
+        : undefined)
+    ?? (process.env.VERCEL_URL
+        ? `https://${process.env.VERCEL_URL}`
+        : undefined)
+    ?? `http://localhost:${process.env.PORT ?? 3000}`;
+
+// ── LOCAL MODE ────────────────────────────────────────────────────────────────
+
+const localProjectId = process.env.OBJECTSTACK_PROJECT_ID ?? 'proj_local';
+const localDatabaseUrl = process.env.OBJECTSTACK_DATABASE_URL
+    ?? `file:${resolvePath(process.cwd(), '.objectstack/data/local.db')}`;
+const localDatabaseDriver = process.env.OBJECTSTACK_DATABASE_DRIVER ?? 'sqlite';
+const localArtifactPath = process.env.OBJECTSTACK_ARTIFACT_PATH
+    ?? resolvePath(process.cwd(), 'dist/objectstack.json');
+
+// Lazy-loading proxy for local boot: registers ObjectQL + MetadataPlugin(local-file) + Auth
+// on the kernel. No control-plane, no MultiProjectPlugin.
+const localBootPluginProxy: any = {
+    name: 'com.objectstack.local-boot',
+    version: '0.0.0',
+    async init(ctx: any) {
+        const { ObjectQLPlugin } = await import('@objectstack/objectql');
+        const { MetadataPlugin } = await import('@objectstack/metadata');
+        const { AuthPlugin } = await import('@objectstack/plugin-auth');
+
+        await ctx.kernel.use(new ObjectQLPlugin({ environmentId: localProjectId }));
+        await ctx.kernel.use(new MetadataPlugin({
+            watch: false,
+            environmentId: localProjectId,
+            artifactSource: { mode: 'local-file', path: localArtifactPath },
+        }));
+        await ctx.kernel.use(new AuthPlugin({ secret: authSecret, baseUrl }));
+
+        ctx.logger?.info?.('[LocalBoot] plugins registered', {
+            projectId: localProjectId,
+            databaseUrl: localDatabaseUrl,
+            databaseDriver: localDatabaseDriver,
+            artifactPath: localArtifactPath,
+        });
+    },
+};
+
+// ── CLOUD MODE ────────────────────────────────────────────────────────────────
+
 async function buildControlDriver(): Promise<{
     driver: IDataDriver;
     driverName: 'sqlite' | 'turso';
@@ -66,22 +116,7 @@ async function buildControlDriver(): Promise<{
     return { driver: driver as unknown as IDataDriver, driverName: 'sqlite', databaseUrl: `file:${filename}` };
 }
 
-const authSecret = process.env.AUTH_SECRET
-    ?? 'dev-secret-please-change-in-production-min-32-chars';
-const baseUrl = process.env.NEXT_PUBLIC_BASE_URL
-    ?? (process.env.VERCEL_PROJECT_PRODUCTION_URL
-        ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
-        : undefined)
-    ?? (process.env.VERCEL_URL
-        ? `https://${process.env.VERCEL_URL}`
-        : undefined)
-    ?? `http://localhost:${process.env.PORT ?? 3000}`;
-
 // Per-project kernels share a minimal base. Loaded lazily on project provisioning.
-// System plugins (Tenant, Auth, Security, Audit) are included so that sys_*
-// objects are visible at project API endpoints. They declare
-// `defaultDatasource: 'cloud'` so their queries route through the
-// ControlPlaneProxyDriver (org-scoped) mounted by ProjectKernelFactory.
 const basePlugins: BasePluginsFactory = async ({ projectId, project }) => {
     const { ObjectQLPlugin } = await import('@objectstack/objectql');
     const { MetadataPlugin } = await import('@objectstack/metadata');
@@ -100,18 +135,14 @@ const basePlugins: BasePluginsFactory = async ({ projectId, project }) => {
     ];
 };
 
-// Example bundles are seeded into a project at provisioning time via
-// the template-seeder — not pre-installed into every project kernel.
 const appBundles: AppBundleResolver = {
     async resolve() { return []; },
 };
 
 // Single shared promise — both control-plane plugins and MultiProjectPlugin
-// use the same DB connection. buildControlDriver() is called only once.
+// use the same DB connection.
 const controlDriverPromise = buildControlDriver();
 
-// Lazy-loading wrapper for MultiProjectPlugin — the control driver is built
-// asynchronously so it is not imported at module evaluation time.
 const multiProjectPluginProxy: any = {
     name: 'com.objectstack.multi-project',
     version: '0.0.0',
@@ -138,19 +169,27 @@ const multiProjectPluginProxy: any = {
     },
 };
 
-export default {
-    plugins: [
-        ...createControlPlanePlugins({
-            controlDriverPromise,
-            authSecret,
-            baseUrl,
-        }),
-        multiProjectPluginProxy,
-    ],
-    // Project-scoping config consumed by `createRestApiPlugin` and
-    // `createDispatcherPlugin` (auto-registered by `objectstack serve`).
-    api: {
-        enableProjectScoping: true,
-        projectResolution: 'auto' as const,
-    },
-};
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export default isLocalMode
+    ? {
+        plugins: [localBootPluginProxy],
+        api: {
+            enableProjectScoping: false,
+            projectResolution: 'none' as const,
+        },
+    }
+    : {
+        plugins: [
+            ...createControlPlanePlugins({
+                controlDriverPromise,
+                authSecret,
+                baseUrl,
+            }),
+            multiProjectPluginProxy,
+        ],
+        api: {
+            enableProjectScoping: true,
+            projectResolution: 'auto' as const,
+        },
+    };

content/docs/references/cloud/index.mdx

@@ -13,6 +13,7 @@ This section contains all protocol schemas for the cloud layer of ObjectStack.
   <Card href="/docs/references/cloud/package" title="Package" description="Source: packages/spec/src/cloud/package.zod.ts" />
   <Card href="/docs/references/cloud/package-version" title="Package Version" description="Source: packages/spec/src/cloud/package-version.zod.ts" />
   <Card href="/docs/references/cloud/project" title="Project" description="Source: packages/spec/src/cloud/project.zod.ts" />
+  <Card href="/docs/references/cloud/project-artifact" title="Project Artifact" description="Source: packages/spec/src/cloud/project-artifact.zod.ts" />
   <Card href="/docs/references/cloud/project-package" title="Project Package" description="Source: packages/spec/src/cloud/project-package.zod.ts" />
   <Card href="/docs/references/cloud/tenant" title="Tenant" description="Source: packages/spec/src/cloud/tenant.zod.ts" />
 </Cards>

content/docs/references/cloud/meta.json

@@ -9,6 +9,7 @@
     "package-version",
     "plugin-security",
     "project",
+    "project-artifact",
     "project-package",
     "provisioning",
     "tenant"

content/docs/references/cloud/project-artifact.mdx

@@ -0,0 +1,40 @@
+---
+title: Project Artifact
+description: Project Artifact protocol schemas
+---
+
+{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}
+
+# Project Artifact Envelope (M1)
+
+Describes the response shape of `GET /api/v1/cloud/projects/:projectId/artifact`
+
+— the assembled artifact ObjectOS pulls from the control plane.
+
+Distinct from the marketplace `PackageArtifactSchema` (a .tgz file listing).
+
+This envelope wraps the compiled `ObjectStackDefinitionSchema` produced by
+
+`objectstack compile` together with control-plane assigned identity
+
+(`commitId`, `checksum`).
+
+<Callout type="info">
+**Source:** `packages/spec/src/cloud/project-artifact.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { Sha256Digest } from '@objectstack/spec/cloud';
+import type { Sha256Digest } from '@objectstack/spec/cloud';
+
+// Validate data
+const result = Sha256Digest.parse(data);
+```
+
+---
+
+
+---
+