Skip to content

Commit 1909884

Browse files
Copilothotlong
Copilot
and
hotlong
committed
docs: update examples and documentation with preview mode
- Add PreviewHostExample to app-host/objectstack.config.ts with full preview mode KernelContext usage documentation - Update app-host README with preview mode section, config table, and OS_MODE=preview quick start - Update content/docs/references/kernel/context.mdx with preview mode enum value and PreviewModeConfig schema reference - Update examples/README.md with preview mode in protocol coverage Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 8e5aa99 commit 1909884

4 files changed

Lines changed: 179 additions & 9 deletions

File tree

‎content/docs/references/kernel/context.mdx‎

Lines changed: 53 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ Defines the operating mode of the kernel
1414
## TypeScript Usage
1515

1616
```typescript
17-
import { KernelContext, RuntimeMode } from '@objectstack/spec/kernel';
18-
import type { KernelContext, RuntimeMode } from '@objectstack/spec/kernel';
17+
import { KernelContext, RuntimeMode, PreviewModeConfig } from '@objectstack/spec/kernel';
18+
import type { KernelContext, RuntimeMode, PreviewModeConfig } from '@objectstack/spec/kernel';
1919

2020
// Validate data
2121
const result = KernelContext.parse(data);
@@ -30,13 +30,14 @@ const result = KernelContext.parse(data);
3030
| Property | Type | Required | Description |
3131
| :--- | :--- | :--- | :--- |
3232
| **instanceId** | `string` | ✅ | Unique UUID for this running kernel process |
33-
| **mode** | `Enum<'development' \| 'production' \| 'test' \| 'provisioning'>` | ✅ | Kernel operating mode |
33+
| **mode** | `Enum<'development' \| 'production' \| 'test' \| 'provisioning' \| 'preview'>` | ✅ | Kernel operating mode |
3434
| **version** | `string` | ✅ | Kernel version |
3535
| **appName** | `string` | optional | Host application name |
3636
| **cwd** | `string` | ✅ | Current working directory |
3737
| **workspaceRoot** | `string` | optional | Workspace root if different from cwd |
3838
| **startTime** | `integer` | ✅ | Boot timestamp (ms) |
3939
| **features** | `Record<string, boolean>` | ✅ | Global feature toggles |
40+
| **previewMode** | `PreviewModeConfig` | optional | Preview/demo mode configuration (used when mode is `'preview'`) |
4041

4142

4243
---
@@ -47,11 +48,56 @@ Kernel operating mode
4748

4849
### Allowed Values
4950

50-
* `development`
51-
* `production`
52-
* `test`
53-
* `provisioning`
51+
* `development` — Hot-reload, verbose logging
52+
* `production` — Optimized, strict security
53+
* `test` — Mocked interfaces
54+
* `provisioning` — Setup/Migration mode
55+
* `preview` — Demo/preview mode — bypass auth, simulate admin identity
5456

5557

5658
---
5759

60+
## PreviewModeConfig
61+
62+
Configures the kernel's preview/demo mode behaviour. When `mode` is set to `'preview'`, the platform
63+
skips authentication screens and simulates an admin identity so visitors can explore the system without
64+
registering or logging in.
65+
66+
<Callout type="warn">
67+
**Security:** Preview mode should **never** be used in production environments.
68+
</Callout>
69+
70+
### Properties
71+
72+
| Property | Type | Default | Description |
73+
| :--- | :--- | :--- | :--- |
74+
| **autoLogin** | `boolean` | `true` | Auto-login as simulated user, skipping login/registration pages |
75+
| **simulatedRole** | `Enum<'admin' \| 'user' \| 'viewer'>` | `'admin'` | Permission role for the simulated preview user |
76+
| **simulatedUserName** | `string` | `'Preview User'` | Display name for the simulated preview user |
77+
| **readOnly** | `boolean` | `false` | Restrict the preview session to read-only operations |
78+
| **expiresInSeconds** | `integer` | `0` | Preview session duration in seconds (0 = no expiration) |
79+
| **bannerMessage** | `string` | — | Banner message displayed in the UI during preview mode |
80+
81+
### Example
82+
83+
```typescript
84+
import { KernelContextSchema } from '@objectstack/spec/kernel';
85+
86+
const ctx = KernelContextSchema.parse({
87+
instanceId: '550e8400-e29b-41d4-a716-446655440000',
88+
mode: 'preview',
89+
version: '1.0.0',
90+
cwd: '/app',
91+
startTime: Date.now(),
92+
previewMode: {
93+
autoLogin: true,
94+
simulatedRole: 'admin',
95+
simulatedUserName: 'Demo Admin',
96+
readOnly: false,
97+
bannerMessage: 'You are exploring a demo — data will be reset periodically.',
98+
},
99+
});
100+
```
101+
102+
---
103+

‎examples/README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,14 +152,18 @@ pnpm build
152152
**Level:** 🔴 Advanced
153153
**Protocols:** System, API, Data
154154

155-
**Complete server implementation** showing how to build a metadata-driven backend. Features dynamic schema loading from plugins, auto-generated REST APIs, unified metadata API, and plugin orchestration.
155+
**Complete server implementation** showing how to build a metadata-driven backend. Features dynamic schema loading from plugins, auto-generated REST APIs, unified metadata API, plugin orchestration, and **preview/demo mode**.
156+
157+
**Preview Mode:** Run with `OS_MODE=preview` to bypass login/registration and simulate an admin identity — ideal for marketplace demos and app showcases.
156158

157159
**Quick Start:**
158160
```bash
159161
cd examples/app-host
160162
pnpm install
161163
pnpm dev
162-
# API available at http://localhost:3000
164+
165+
# Preview mode (no login required)
166+
OS_MODE=preview pnpm dev
163167
```
164168

165169
---
@@ -225,6 +229,7 @@ pnpm typecheck
225229
|----------|---------|----------|
226230
| Manifest | ✅ Complete | All examples with `objectstack.config.ts` |
227231
| Plugin System | ✅ Complete | [App Host](./app-host/) |
232+
| Preview Mode | ✅ Complete | [App Host](./app-host/) — `OS_MODE=preview` |
228233
| Datasources | 🟡 Partial | [App Host](./app-host/) |
229234
| I18n / Translations | ✅ Complete | [Todo Translations](./app-todo/src/translations/), [CRM Translations](./app-crm/src/translations/) |
230235
| Job Scheduling | 🔴 Missing | _Planned_ |

‎examples/app-host/README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ It demonstrates how to build a metadata-driven backend that dynamically loads ob
99
- **Unified Metadata API**: `/api/v1/meta/objects`
1010
- **Unified Data API**: `/api/v1/data/:object` (CRUD)
1111
- **Zero-Code Backend**: No creating routes or controllers per object.
12+
- **Preview Mode**: Run in demo mode — bypass login, auto-simulate admin identity.
1213

1314
## Setup
1415

@@ -28,6 +29,62 @@ It demonstrates how to build a metadata-driven backend that dynamically loads ob
2829
# Expected: Server starts at http://localhost:3000
2930
```
3031

32+
3. Run in **preview mode** (skip login, simulate admin):
33+
```bash
34+
OS_MODE=preview pnpm dev
35+
# Expected: Server starts in preview mode — no login required
36+
```
37+
38+
## Preview / Demo Mode
39+
40+
Preview mode allows visitors (e.g. marketplace customers) to explore the platform
41+
without registering or logging in. The kernel boots with `mode: 'preview'` and the
42+
frontend skips authentication screens, automatically simulating an admin session.
43+
44+
### How It Works
45+
46+
1. The runtime reads `OS_MODE=preview` from the environment (or the stack config).
47+
2. The `KernelContext` is created with `mode: 'preview'` and a `previewMode` config.
48+
3. The frontend detects `mode === 'preview'` and:
49+
- Hides the login / registration pages.
50+
- Automatically creates a simulated admin session.
51+
- Shows a preview banner to indicate demo mode.
52+
53+
### Configuration
54+
55+
```typescript
56+
import { KernelContextSchema } from '@objectstack/spec/kernel';
57+
58+
const ctx = KernelContextSchema.parse({
59+
instanceId: '550e8400-e29b-41d4-a716-446655440000',
60+
mode: 'preview',
61+
version: '1.0.0',
62+
cwd: process.cwd(),
63+
startTime: Date.now(),
64+
previewMode: {
65+
autoLogin: true, // Skip login/registration pages
66+
simulatedRole: 'admin', // Simulated user role (admin | user | viewer)
67+
simulatedUserName: 'Demo Admin',
68+
readOnly: false, // Allow writes (set true for read-only demos)
69+
expiresInSeconds: 3600, // Session expires after 1 hour (0 = no expiration)
70+
bannerMessage: 'You are exploring a demo — data will be reset periodically.',
71+
},
72+
});
73+
```
74+
75+
### PreviewModeConfig Properties
76+
77+
| Property | Type | Default | Description |
78+
|:---|:---|:---|:---|
79+
| **autoLogin** | `boolean` | `true` | Auto-login as simulated user, skip login/registration |
80+
| **simulatedRole** | `'admin' \| 'user' \| 'viewer'` | `'admin'` | Permission role for the simulated user |
81+
| **simulatedUserName** | `string` | `'Preview User'` | Display name shown in the UI |
82+
| **readOnly** | `boolean` | `false` | Block all write operations |
83+
| **expiresInSeconds** | `integer` | `0` | Session duration (0 = no expiration) |
84+
| **bannerMessage** | `string` | — | Banner message displayed in the UI |
85+
86+
> **⚠️ Security:** Preview mode should NEVER be used in production environments.
87+
3188
## API Usage Examples
3289

3390
### 1. Get All Objects

‎examples/app-host/objectstack.config.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,65 @@ export default defineStack({
3333
new AppPlugin(BiPluginManifest)
3434
]
3535
});
36+
37+
/**
38+
* Preview Mode Host Example
39+
*
40+
* Demonstrates how to run the platform in "preview" mode.
41+
* When `mode` is set to `'preview'`, the kernel signals the frontend to:
42+
* - Skip login/registration screens
43+
* - Automatically simulate an admin identity
44+
* - Display a preview-mode banner to the user
45+
*
46+
* Use this for marketplace demos, app showcases, or onboarding
47+
* tours where visitors should explore the system without signing up.
48+
*
49+
* ## Usage
50+
*
51+
* Set the `OS_MODE` environment variable to `preview` at boot:
52+
*
53+
* ```bash
54+
* OS_MODE=preview pnpm dev
55+
* ```
56+
*
57+
* Or use this stack definition directly as a starting point.
58+
*
59+
* ## KernelContext (created by the Runtime at boot)
60+
*
61+
* ```ts
62+
* import { KernelContextSchema } from '@objectstack/spec/kernel';
63+
*
64+
* const ctx = KernelContextSchema.parse({
65+
* instanceId: '550e8400-e29b-41d4-a716-446655440000',
66+
* mode: 'preview',
67+
* version: '1.0.0',
68+
* cwd: process.cwd(),
69+
* startTime: Date.now(),
70+
* previewMode: {
71+
* autoLogin: true,
72+
* simulatedRole: 'admin',
73+
* simulatedUserName: 'Demo Admin',
74+
* readOnly: false,
75+
* bannerMessage: 'You are exploring a demo — data will be reset periodically.',
76+
* },
77+
* });
78+
* ```
79+
*/
80+
export const PreviewHostExample = defineStack({
81+
manifest: {
82+
id: 'app-host-preview',
83+
name: 'app_host_preview',
84+
version: '1.0.0',
85+
description: 'Host application in preview/demo mode — bypasses login, simulates admin user',
86+
type: 'app',
87+
},
88+
89+
// Same plugins as the standard host
90+
plugins: [
91+
new ObjectQLPlugin(),
92+
new DriverPlugin(new InMemoryDriver()),
93+
new AppPlugin(CrmApp),
94+
new AppPlugin(TodoApp),
95+
new AppPlugin(BiPluginManifest)
96+
]
97+
});

0 commit comments

Comments
 (0)