@rool-dev/app 0.3.0

package/README.md

@@ -0,0 +1,306 @@
+# Rool App
+
+Build sandboxed apps that run inside Rool Spaces. An app is a Svelte 5 component hosted in an iframe, communicating with the host via a postMessage bridge.
+
+Apps are small, standardized, and easy to generate. An app project is just two files:
+
+- **`App.svelte`** — Your UI component (receives a reactive channel as a prop)
+- **`rool-app.json`** — Manifest with id, name, and collection access
+
+Everything else (Vite config, entry point, HTML, Tailwind CSS) is provided by the CLI.
+
+## Quick Start
+
+```bash
+npx rool-app init my-app
+cd my-app
+pnpm install
+npx rool-app dev
+```
+
+This opens a dev host at `/__rool-host/` that loads your app in a sandboxed iframe, connected to a real Rool Space.
+
+## Manifest
+
+`rool-app.json` declares your app's identity and collection access:
+
+```json
+{
+  "id": "my-app",
+  "name": "My App",
+  "description": "What this app does",
+  "collections": {
+    "write": {
+      "task": [
+        { "name": "title", "type": { "kind": "string" } },
+        { "name": "done", "type": { "kind": "boolean" } }
+      ]
+    },
+    "read": "*"
+  },
+  "systemInstruction": "Optional system instruction for the AI"
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Unique identifier (lowercase, hyphens) |
+| `name` | Yes | Display name |
+| `description` | No | Short description |
+| `collections` | No | Collection access declarations (see below) |
+| `systemInstruction` | No | Default system instruction for the AI channel |
+
+### Collection Access
+
+The `collections` field declares what collections the app works with, grouped by access level:
+
+- **`write`** — Collections the app can create, update, and delete objects in. An object with field definitions creates the collection in the space. `"*"` grants write access to all collections.
+- **`read`** — Collections the app can read from. An object with field definitions declares the expected shape. `"*"` grants read access to all collections.
+
+`write` implies `read` — no need to list a collection under both.
+
+```json
+// App with its own collections + read access to everything else
+"collections": {
+  "write": {
+    "card": [
+      { "name": "front", "type": { "kind": "string" } },
+      { "name": "back", "type": { "kind": "string" } }
+    ]
+  },
+  "read": "*"
+}
+
+// Full access to all collections (chat, SQL interface, etc.)
+"collections": {
+  "write": "*"
+}
+
+// Read-only access to all collections
+"collections": {
+  "read": "*"
+}
+```
+
+## App Component
+
+`App.svelte` receives a single prop — a `ReactiveAppChannel`:
+
+```svelte
+<script lang="ts">
+  import type { ReactiveAppChannel } from '@rool-dev/app';
+
+  interface Props {
+    channel: ReactiveAppChannel;
+  }
+
+  let { channel }: Props = $props();
+</script>
+
+<div>
+  <p>Connected to: {channel.spaceName}</p>
+  <p>Objects: {channel.objectIds.length}</p>
+  <button onclick={() => channel.prompt('Hello')}>Send</button>
+</div>
+```
+
+The component can import other `.svelte` components and `.ts` files — standard Svelte/TypeScript conventions apply. Tailwind CSS v4 is available out of the box. Add an `app.css` file to include custom styles.
+
+## ReactiveAppChannel
+
+The channel is the app's interface to the host Space. It mirrors the `@rool-dev/svelte` ReactiveChannel API over a postMessage bridge.
+
+### Reactive State
+
+These are Svelte 5 `$state` properties — use them directly in templates or `$effect` blocks:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `interactions` | `Interaction[]` | Channel interaction history (auto-updates) |
+| `objectIds` | `string[]` | All object IDs in the space (auto-updates on create/delete) |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `channelId` | `string` | Channel ID |
+| `spaceId` | `string` | Space ID |
+| `spaceName` | `string` | Space name |
+| `role` | `RoolUserRole` | User's role (`owner`, `admin`, `editor`, `viewer`) |
+| `linkAccess` | `LinkAccess` | URL sharing level |
+| `userId` | `string` | Current user's ID |
+| `isReadOnly` | `boolean` | True if viewer role |
+
+### Object Operations
+
+```typescript
+await channel.getObject(id)
+await channel.findObjects({ where: { type: 'note' } })
+await channel.createObject({ data: { type: 'note', text: '{{expand this}}' } })
+await channel.updateObject(id, { data: { text: 'Updated' } })
+await channel.updateObject(id, { prompt: 'Make it shorter' })
+await channel.deleteObjects([id])
+channel.getObjectIds({ limit: 10, order: 'desc' })
+```
+
+See the [SDK docs](../sdk/README.md) for full details on object operations, `{{placeholder}}` syntax, and `findObjects` options.
+
+### AI
+
+```typescript
+const { message, objects } = await channel.prompt('Create three tasks');
+const { message } = await channel.prompt('Summarize', { readOnly: true, effort: 'QUICK' });
+```
+
+| Option | Description |
+|--------|-------------|
+| `objectIds` | Focus on specific objects |
+| `responseSchema` | Request structured JSON response |
+| `effort` | `'QUICK'`, `'STANDARD'`, `'REASONING'`, or `'RESEARCH'` |
+| `ephemeral` | Don't record in interaction history |
+| `readOnly` | Disable mutation tools |
+
+### Schema
+
+```typescript
+channel.getSchema()
+await channel.createCollection('task', [
+  { name: 'title', type: { kind: 'string' } },
+  { name: 'done', type: { kind: 'boolean' } },
+])
+await channel.alterCollection('task', [...updatedFields])
+await channel.dropCollection('task')
+```
+
+### Undo/Redo
+
+```typescript
+await channel.checkpoint('Before delete')
+await channel.deleteObjects([id])
+await channel.undo()   // restores deleted object
+await channel.redo()   // deletes again
+```
+
+### Metadata
+
+Arbitrary key-value storage on the Space (not visible to AI):
+
+```typescript
+channel.setMetadata('viewport', { zoom: 1.5 })
+channel.getMetadata('viewport')
+channel.getAllMetadata()
+```
+
+### Interaction History
+
+```typescript
+channel.getInteractions()
+channel.getSystemInstruction()
+await channel.setSystemInstruction('Respond in haiku')
+```
+
+### Events
+
+```typescript
+channel.on('objectCreated', ({ objectId, object, source }) => { ... })
+channel.on('objectUpdated', ({ objectId, object, source }) => { ... })
+channel.on('objectDeleted', ({ objectId, source }) => { ... })
+channel.on('metadataUpdated', ({ metadata, source }) => { ... })
+channel.on('channelUpdated', ({ channelId, source }) => { ... })
+channel.on('reset', ({ source }) => { ... })
+```
+
+`source` is `'local_user'`, `'remote_user'`, `'remote_agent'`, or `'system'`.
+
+### Reactive Primitives
+
+#### `channel.watch(options)`
+
+Auto-updating filtered object list:
+
+```svelte
+<script>
+  const tasks = channel.watch({ where: { type: 'task' } });
+</script>
+
+{#each tasks.objects as task}
+  <div>{task.title}</div>
+{/each}
+```
+
+| State | Description |
+|-------|-------------|
+| `watch.objects` | `$state<RoolObject[]>` — matching objects |
+| `watch.loading` | `$state<boolean>` — loading state |
+
+Methods: `watch.refresh()`, `watch.close()`.
+
+#### `channel.object(id)`
+
+Single reactive object subscription:
+
+```svelte
+<script>
+  const item = channel.object('abc123');
+</script>
+
+{#if item.data}
+  <div>{item.data.title}</div>
+{/if}
+```
+
+| State | Description |
+|-------|-------------|
+| `object.data` | `$state<RoolObject | undefined>` — object data |
+| `object.loading` | `$state<boolean>` — loading state |
+
+Methods: `object.refresh()`, `object.close()`.
+
+## Hosting
+
+Apps run in a sandboxed iframe (`allow-scripts allow-same-origin`). The host creates the iframe, establishes a postMessage bridge, and proxies all channel operations to a real Rool Space. The app never authenticates directly — the host handles auth and forwards operations.
+
+The bridge protocol:
+1. App sends `rool:ready`
+2. Host responds with `rool:init` (channel metadata, schema, space info)
+3. App calls channel methods → `rool:request` → host executes → `rool:response`
+4. Host pushes real-time events → `rool:event` → app updates reactive state
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `rool-app init [name]` | Scaffold a new app project |
+| `rool-app dev` | Start the dev server with host shell |
+
+## Exported Types
+
+```typescript
+import type {
+  ReactiveAppChannel,
+  ReactiveObject,
+  ReactiveWatch,
+  WatchOptions,
+  RoolObject,
+  RoolObjectStat,
+  SpaceSchema,
+  CollectionDef,
+  FieldDef,
+  FieldType,
+  Interaction,
+  ToolCall,
+  PromptOptions,
+  PromptEffort,
+  FindObjectsOptions,
+  CreateObjectOptions,
+  UpdateObjectOptions,
+  ChangeSource,
+  RoolUserRole,
+  LinkAccess,
+  AppChannelEvents,
+} from '@rool-dev/app';
+```
+
+## License
+
+MIT - see [LICENSE](../../LICENSE) for details.

package/dist/cli/dev.d.ts

@@ -0,0 +1,10 @@
+/**
+ * rool-app dev
+ *
+ * Starts the app's Vite dev server with the dev host shell injected.
+ * The host shell is served at /__rool-host/ and the app at /.
+ *
+ * Usage: npx rool-app dev
+ */
+export {};
+//# sourceMappingURL=dev.d.ts.map

package/dist/cli/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/cli/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/cli/dev.js

@@ -0,0 +1,241 @@
+/**
+ * rool-app dev
+ *
+ * Starts the app's Vite dev server with the dev host shell injected.
+ * The host shell is served at /__rool-host/ and the app at /.
+ *
+ * Usage: npx rool-app dev
+ */
+import { createServer } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import tailwindcss from '@tailwindcss/vite';
+import { readFileSync, existsSync, watch } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { readManifest, getSvelteAliases } from './vite-utils.js';
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HOST_SHELL_JS_PATH = resolve(__dirname, '../dev/host-shell.js');
+// ---------------------------------------------------------------------------
+// HTML generation
+// ---------------------------------------------------------------------------
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function generateHostHtml(result) {
+    const { manifest, error } = result;
+    const channelId = manifest?.id ?? 'app-dev';
+    const dataAttrs = {
+        'data-channel-id': channelId,
+        'data-app-url': '/',
+    };
+    if (manifest)
+        dataAttrs['data-manifest'] = escapeHtml(JSON.stringify(manifest));
+    if (error)
+        dataAttrs['data-manifest-error'] = escapeHtml(error);
+    const attrs = Object.entries(dataAttrs).map(([k, v]) => `${k}="${v}"`).join('\n    ');
+    return `<!DOCTYPE html>
+<html lang="en" style="height:100%">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${manifest?.name ? escapeHtml(manifest.name) + ' \u2014 ' : ''}App Dev Host</title>
+  <script type="module" src="/@vite/client"></script>
+</head>
+<body style="height:100%;margin:0">
+  <div id="rool-host"
+    style="display:flex;height:100%;background:#f8fafc"
+    ${attrs}
+  ></div>
+  <script type="module" src="/__rool-host/host-shell.js"></script>
+</body>
+</html>`;
+}
+// ---------------------------------------------------------------------------
+// Vite plugins (internal — injected by the CLI, not user-facing)
+// ---------------------------------------------------------------------------
+/**
+ * Synthesizes index.html and the app entry module so app projects
+ * only need App.svelte + rool-app.json.
+ */
+function roolAppPlugin(root, tailwindCssPath) {
+    const VIRTUAL_ENTRY = 'virtual:rool-app-entry';
+    const RESOLVED_ENTRY = '\0' + VIRTUAL_ENTRY;
+    const VIRTUAL_CSS = 'virtual:rool-app-tailwind.css';
+    const RESOLVED_CSS = '\0' + VIRTUAL_CSS;
+    const appPath = resolve(root, 'App.svelte');
+    const cssPath = resolve(root, 'app.css');
+    const hasCss = existsSync(cssPath);
+    return {
+        name: 'rool-app-entry',
+        resolveId(id) {
+            if (id === VIRTUAL_ENTRY)
+                return RESOLVED_ENTRY;
+            if (id === VIRTUAL_CSS)
+                return RESOLVED_CSS;
+            return undefined;
+        },
+        load(id) {
+            if (id === RESOLVED_CSS)
+                return `@import "${tailwindCssPath}";`;
+            if (id !== RESOLVED_ENTRY)
+                return;
+            return [
+                `import { initApp } from '@rool-dev/app';`,
+                `import { mount } from 'svelte';`,
+                `import App from '${appPath}';`,
+                `import '${VIRTUAL_CSS}';`,
+                hasCss ? `import '${cssPath}';` : ``,
+                ``,
+                `async function main() {`,
+                `  const channel = await initApp();`,
+                `  mount(App, {`,
+                `    target: document.getElementById('app'),`,
+                `    props: { channel },`,
+                `  });`,
+                `}`,
+                ``,
+                `main().catch((err) => {`,
+                `  document.getElementById('app').innerHTML =`,
+                `    '<div style="padding:2rem;color:red"><h2>Failed to initialize app</h2><p>' + err.message + '</p></div>';`,
+                `});`,
+            ].filter(Boolean).join('\n');
+        },
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                // Serve synthesized index.html at /
+                if (req.url === '/' || req.url === '/index.html') {
+                    const html = `<!DOCTYPE html>
+<html lang="en" style="height:100%">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>App</title>
+</head>
+<body style="height:100%;margin:0">
+  <div id="app" style="height:100%"></div>
+  <script type="module" src="/@id/${VIRTUAL_ENTRY}"></script>
+</body>
+</html>`;
+                    server.transformIndexHtml(req.url, html).then((transformed) => {
+                        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                        res.end(transformed);
+                    }).catch(next);
+                    return;
+                }
+                next();
+            });
+        },
+    };
+}
+function roolHostPlugin(state, hostShellJs) {
+    return {
+        name: 'rool-app-host',
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (!req.url?.startsWith('/__rool-host'))
+                    return next();
+                if (req.url === '/__rool-host/host-shell.js') {
+                    res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+                    res.end(hostShellJs);
+                    return;
+                }
+                const html = generateHostHtml(state.current);
+                res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                res.end(html);
+            });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Manifest file watcher
+// ---------------------------------------------------------------------------
+function watchManifest(root, state, server) {
+    const manifestPath = resolve(root, 'rool-app.json');
+    let debounce = null;
+    const onChange = () => {
+        if (debounce)
+            clearTimeout(debounce);
+        debounce = setTimeout(() => {
+            const prev = state.current;
+            state.current = readManifest(root);
+            if (JSON.stringify(prev) === JSON.stringify(state.current))
+                return;
+            if (state.current.error) {
+                console.warn(`\n  \u26a0  Manifest: ${state.current.error}\n`);
+            }
+            else {
+                console.log(`\n  \u2713  Manifest updated \u2014 ${state.current.manifest.name}\n`);
+            }
+            server.ws.send({ type: 'full-reload', path: '*' });
+        }, 100);
+    };
+    // Watch the file (and parent dir so we catch creation/deletion)
+    try {
+        watch(manifestPath, onChange);
+    }
+    catch {
+        // File may not exist yet — watch the directory instead
+    }
+    watch(root, (_, filename) => {
+        if (filename === 'rool-app.json')
+            onChange();
+    });
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    const cwd = process.cwd();
+    const state = { current: readManifest(cwd) };
+    if (state.current.error) {
+        console.warn(`\n  \u26a0  Manifest: ${state.current.error}\n`);
+    }
+    // Load pre-built host shell bundle
+    let hostShellJs;
+    try {
+        hostShellJs = readFileSync(HOST_SHELL_JS_PATH, 'utf-8');
+    }
+    catch {
+        console.error(`Could not find host-shell.js at ${HOST_SHELL_JS_PATH}.\n` +
+            `Run "pnpm build" in the @rool-dev/app package first.`);
+        process.exit(1);
+    }
+    // Resolve packages from the CLI's own node_modules so apps don't need them
+    // and to ensure a single copy of svelte (compiler + runtime must match)
+    const tailwindPkgDir = dirname(fileURLToPath(import.meta.resolve('tailwindcss/package.json')));
+    const tailwindCssPath = resolve(tailwindPkgDir, 'index.css');
+    const appPkgPath = resolve(__dirname, '..');
+    const server = await createServer({
+        configFile: false,
+        root: cwd,
+        server: {
+            open: '/__rool-host/',
+        },
+        resolve: {
+            alias: [
+                { find: '@rool-dev/app', replacement: appPkgPath },
+                { find: /^tailwindcss$/, replacement: tailwindCssPath },
+                ...getSvelteAliases(),
+            ],
+        },
+        plugins: [
+            tailwindcss(),
+            svelte(),
+            roolAppPlugin(cwd, tailwindCssPath),
+            roolHostPlugin(state, hostShellJs),
+        ],
+    });
+    await server.listen();
+    server.printUrls();
+    const name = state.current.manifest?.name ?? 'app';
+    console.log(`\n  Dev host ready \u2014 serving ${name} via bridge\n`);
+    // Start watching the manifest for changes
+    watchManifest(cwd, state, server);
+}
+main().catch((err) => {
+    console.error('Failed to start dev server:', err);
+    process.exit(1);
+});

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+const command = process.argv[2];
+switch (command) {
+    case 'dev':
+        await import('./dev.js');
+        break;
+    case 'init':
+        await import('./init.js');
+        break;
+    case 'publish':
+        await import('./publish.js');
+        break;
+    default:
+        console.log(`Usage: rool-app <command>
+
+Commands:
+  init      Create a new app project
+  dev       Start the dev server
+  publish   Build and publish the app`);
+        process.exit(command ? 1 : 0);
+}
+export {};

package/dist/cli/init.d.ts

@@ -0,0 +1,7 @@
+/**
+ * rool-app init [name]
+ *
+ * Scaffolds a new app project in the current directory or a named subdirectory.
+ */
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}