feat: add setup route for first-run user creation and organization provisioning

Author: hotlong

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **`OBJECTSTACK_MODE` replaces `OBJECTSTACK_MULTI_PROJECT`** — Boot-mode selection is now driven by a single `OBJECTSTACK_MODE` variable accepting `standalone` (default) or `cloud`. The legacy `OBJECTSTACK_MULTI_PROJECT=true` flag remains as a deprecated alias (with a one-shot console warning at boot) and will be removed in the next major release. Root `pnpm dev` now starts in standalone mode; use `pnpm dev:cloud` for the multi-project / control-plane shape. Updated `apps/server/objectstack.config.ts`, `apps/studio/server/index.ts`, `.env.example`, the cloud-deployment guide, and the north-star env table.
+
 ### Added
 - **Studio: cascade-delete projects and organizations** — The previously-disabled "Archive project" button on `/projects/$projectId` is now an enabled "Delete project" action with typed-name confirmation. New "Danger zone" section on `/orgs/$orgId` lets owners delete an organization, which cascades to every project the org owns (including each project's physical database). Server side adds `DELETE /api/v1/cloud/projects/:id[?force=1]` and `DELETE /api/v1/cloud/organizations/:id` to `HttpDispatcher`, both routed via `dispatcher-plugin`. The org-delete path uses better-auth's `auth.api.deleteOrganization` (which removes members + invitations + teams) and falls back to a direct `sys_organization` row delete when the plugin isn't loaded. Client SDK gains `client.projects.delete(id, { force })` and `client.organizations.delete(id)`. New Studio hooks `useDeleteProject` and `useDeleteOrganization` (the latter refreshes the session + org list so the active-org pointer is cleared automatically).
 - **`os auth login` — browser-based device flow (Vercel CLI style)** — Running `os auth login` in an interactive TTY no longer requires typing a password into the terminal. The CLI now calls `POST /api/v1/auth/device/request` to obtain a one-time device code, prints the verification URL, auto-opens the browser, and polls `GET /api/v1/auth/device/token` every 2 s until the user approves. A new Studio page at `/_studio/auth/device?code=…` lets authenticated users (or users who sign in inline) approve the request with one click. The old `--email`/`--password` path is preserved for non-interactive / CI use; `--no-browser` skips auto-open. Server-side: two new endpoints (`/device/request`, `/device/token`) and an approval endpoint (`/device/approve`) added to `plugin-auth`; device codes expire after 5 min and are stored in-memory.

ROADMAP.md

@@ -171,7 +171,7 @@ Tests: [packages/spec/src/system/project-artifact.test.ts](packages/spec/src/sys
 明确 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 表 + 反模式说明）
-- [x] 实现本地 single / multi-project env 路径：`OBJECTSTACK_MULTI_PROJECT` / `OBJECTSTACK_PROJECT_ID` / `OBJECTSTACK_DATABASE_URL` / `OBJECTSTACK_DATABASE_DRIVER` / `OBJECTSTACK_ARTIFACT_PATH`（默认 `./dist/objectstack.json`）/ `AUTH_SECRET`
+- [x] 实现本地 standalone / cloud env 路径：`OBJECTSTACK_MODE` (旧 `OBJECTSTACK_MULTI_PROJECT`) / `OBJECTSTACK_PROJECT_ID` / `OBJECTSTACK_DATABASE_URL` / `OBJECTSTACK_DATABASE_DRIVER` / `OBJECTSTACK_ARTIFACT_PATH`（默认 `./dist/objectstack.json`）/ `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` 分流本地/云端路径
 

apps/account/src/routeTree.gen.ts

@@ -10,6 +10,7 @@
 
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as VerifyEmailRouteImport } from './routes/verify-email'
+import { Route as SetupRouteImport } from './routes/setup'
 import { Route as ResetPasswordRouteImport } from './routes/reset-password'
 import { Route as RegisterRouteImport } from './routes/register'
 import { Route as LoginRouteImport } from './routes/login'
@@ -39,6 +40,11 @@ const VerifyEmailRoute = VerifyEmailRouteImport.update({
   path: '/verify-email',
   getParentRoute: () => rootRouteImport,
 } as any)
+const SetupRoute = SetupRouteImport.update({
+  id: '/setup',
+  path: '/setup',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ResetPasswordRoute = ResetPasswordRouteImport.update({
   id: '/reset-password',
   path: '/reset-password',
@@ -168,6 +174,7 @@ export interface FileRoutesByFullPath {
   '/login': typeof LoginRoute
   '/register': typeof RegisterRoute
   '/reset-password': typeof ResetPasswordRoute
+  '/setup': typeof SetupRoute
   '/verify-email': typeof VerifyEmailRoute
   '/accept-invitation/$invitationId': typeof AcceptInvitationInvitationIdRoute
   '/account/profile': typeof AccountProfileRoute
@@ -193,6 +200,7 @@ export interface FileRoutesByTo {
   '/login': typeof LoginRoute
   '/register': typeof RegisterRoute
   '/reset-password': typeof ResetPasswordRoute
+  '/setup': typeof SetupRoute
   '/verify-email': typeof VerifyEmailRoute
   '/accept-invitation/$invitationId': typeof AcceptInvitationInvitationIdRoute
   '/account/profile': typeof AccountProfileRoute
@@ -219,6 +227,7 @@ export interface FileRoutesById {
   '/login': typeof LoginRoute
   '/register': typeof RegisterRoute
   '/reset-password': typeof ResetPasswordRoute
+  '/setup': typeof SetupRoute
   '/verify-email': typeof VerifyEmailRoute
   '/accept-invitation/$invitationId': typeof AcceptInvitationInvitationIdRoute
   '/account/profile': typeof AccountProfileRoute
@@ -247,6 +256,7 @@ export interface FileRouteTypes {
     | '/login'
     | '/register'
     | '/reset-password'
+    | '/setup'
     | '/verify-email'
     | '/accept-invitation/$invitationId'
     | '/account/profile'
@@ -272,6 +282,7 @@ export interface FileRouteTypes {
     | '/login'
     | '/register'
     | '/reset-password'
+    | '/setup'
     | '/verify-email'
     | '/accept-invitation/$invitationId'
     | '/account/profile'
@@ -297,6 +308,7 @@ export interface FileRouteTypes {
     | '/login'
     | '/register'
     | '/reset-password'
+    | '/setup'
     | '/verify-email'
     | '/accept-invitation/$invitationId'
     | '/account/profile'
@@ -324,6 +336,7 @@ export interface RootRouteChildren {
   LoginRoute: typeof LoginRoute
   RegisterRoute: typeof RegisterRoute
   ResetPasswordRoute: typeof ResetPasswordRoute
+  SetupRoute: typeof SetupRoute
   VerifyEmailRoute: typeof VerifyEmailRoute
   AcceptInvitationInvitationIdRoute: typeof AcceptInvitationInvitationIdRoute
   AuthDeviceRoute: typeof AuthDeviceRoute
@@ -342,6 +355,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof VerifyEmailRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/setup': {
+      id: '/setup'
+      path: '/setup'
+      fullPath: '/setup'
+      preLoaderRoute: typeof SetupRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/reset-password': {
       id: '/reset-password'
       path: '/reset-password'
@@ -553,6 +573,7 @@ const rootRouteChildren: RootRouteChildren = {
   LoginRoute: LoginRoute,
   RegisterRoute: RegisterRoute,
   ResetPasswordRoute: ResetPasswordRoute,
+  SetupRoute: SetupRoute,
   VerifyEmailRoute: VerifyEmailRoute,
   AcceptInvitationInvitationIdRoute: AcceptInvitationInvitationIdRoute,
   AuthDeviceRoute: AuthDeviceRoute,

apps/account/src/routes/__root.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { createRootRoute, Outlet, useLocation, useNavigate } from '@tanstack/react-router';
-import { useEffect, useMemo } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { ObjectStackProvider } from '@objectstack/client-react';
 import { ObjectStackClient } from '@objectstack/client';
 import { Toaster } from '@/components/ui/toaster';
@@ -19,41 +19,87 @@ const PUBLIC_ROUTES = new Set([
   '/reset-password',
   '/verify-email',
   '/auth/device',
+  '/setup',
 ]);
 
 function isPublic(pathname: string): boolean {
   return PUBLIC_ROUTES.has(pathname) || pathname.startsWith('/accept-invitation/');
 }
 
+/**
+ * Probes `/api/v1/auth/bootstrap-status` once per app load. Returns:
+ * - `null` while loading
+ * - `true` if at least one user exists (normal mode)
+ * - `false` if the database is empty (first-run setup required)
+ *
+ * On any error we assume `true` so the SPA falls through to its normal
+ * login flow rather than hijacking the user with a setup screen.
+ */
+function useBootstrapStatus(): boolean | null {
+  const [hasOwner, setHasOwner] = useState<boolean | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const res = await fetch('/api/v1/auth/bootstrap-status');
+        if (!res.ok) {
+          if (!cancelled) setHasOwner(true);
+          return;
+        }
+        const data = await res.json() as { hasOwner?: boolean };
+        if (!cancelled) setHasOwner(data.hasOwner !== false);
+      } catch {
+        if (!cancelled) setHasOwner(true);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+  return hasOwner;
+}
+
 function RequireAuth({ children }: { children: React.ReactNode }) {
   const { user, loading } = useSession();
   const navigate = useNavigate();
   const location = useLocation();
   const pub = isPublic(location.pathname);
-  // OAuth consent screen renders fullscreen without sidebar/topbar chrome
-  // — it's a flow page, not part of the account portal proper. Still
-  // requires authentication.
   const fullscreenAuthed = location.pathname.startsWith('/oauth/');
+  const hasOwner = useBootstrapStatus();
+  const onSetup = location.pathname === '/setup';
 
+  // First-run redirect: if there's no owner yet, force /setup. This runs
+  // before the auth check below so the user isn't bounced to /login first.
+  useEffect(() => {
+    if (hasOwner === false && !onSetup && !user) {
+      navigate({ to: '/setup', replace: true });
+    }
+  }, [hasOwner, onSetup, user, navigate]);
+
+  // If the database has been bootstrapped, the /setup page should redirect
+  // unauthenticated visitors back to /login (handled inside the page itself).
   useEffect(() => {
     if (loading) return;
+    if (hasOwner === false) return; // setup flow takes precedence
     if (!user && !pub) {
       navigate({
         to: '/login',
         search: { redirect: location.pathname + location.searchStr },
         replace: true,
       });
     }
-  }, [user, loading, pub, navigate, location.pathname, location.searchStr]);
+  }, [user, loading, pub, navigate, location.pathname, location.searchStr, hasOwner]);
 
-  if (loading && !user) {
+  if (hasOwner === null || (loading && !user)) {
     return (
       <div className="flex min-h-screen w-full flex-1 items-center justify-center bg-background">
         <div className="h-8 w-8 animate-spin rounded-full border-4 border-muted border-t-primary" />
       </div>
     );
   }
 
+  if (hasOwner === false && !onSetup) {
+    return null;
+  }
+
   if (!user && !pub) {
     return null;
   }