@lumerahq/cli 0.19.2 → 0.19.3

package/dist/{templates-M3RDNDDY.js → templates-LNUOTNLN.js}

@@ -1,7 +1,6 @@
 import {
   listAllTemplates
-} from "./chunk-OQW5E7UT.js";
-import "./chunk-FJFIWC7G.js";
+} from "./chunk-H357NP7T.js";
 import "./chunk-PNKVD2UK.js";
 
 // src/commands/templates.ts
@@ -25,7 +24,7 @@ ${pc.dim("Examples:")}
   lumera templates                              # List available templates
   lumera templates list -v                      # Show with descriptions
   lumera templates validate ./my-template       # Validate a template dir
-  lumera init my-app -t invoice-processing      # Use a template
+  lumera init my-app -t default                 # Use a template
 `);
 }
 async function list(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumerahq/cli",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "description": "CLI for building and deploying Lumera apps",
   "type": "module",
   "engines": {

package/templates/default/AGENTS.md

@@ -0,0 +1,151 @@
+# {{projectTitle}}
+
+A Lumera app built with collections, automations, hooks, and a React frontend.
+
+## Project Structure
+
+```
+platform/
+├── collections/       # Collection schemas (JSON) — deployed via lumera apply
+├── automations/       # Python automations (config.json + run.py per automation)
+├── hooks/             # JavaScript hooks on collection lifecycle events
+src/
+├── routes/index.tsx   # Home page
+├── lib/queries.ts     # Data fetching helpers
+├── components/        # Shared UI components
+├── components/ui/     # shadcn UI primitives (installed via MCP)
+scripts/               # Utility scripts (seed data, migrations, etc.)
+```
+
+## Lumera Concepts
+
+A Lumera app is built from these primitives — all defined as code in `platform/`:
+
+- **Collections** (`platform/collections/*.json`) — Data tables with typed fields. Deployed via `lumera apply`.
+- **Automations** (`platform/automations/*/`) — Python scripts that run on Lumera's servers. Each has a `config.json` and `run.py`.
+- **Hooks** (`platform/hooks/*.js`) — JavaScript on collection lifecycle events (`before_create`, `after_update`, etc.).
+- **Webhooks** — Receive events from external services (Stripe, GitHub, etc.). Events land in `lm_event_log`; process them with hooks or automations.
+- **Mailbox** — Each tenant gets an email address. Inbound emails are persisted to `lm_mailbox_messages` — use hooks to trigger automations on new mail.
+- **Email** — Send transactional emails from automations via `from lumera import email`. Logged to `lm_email_logs`.
+
+All resources use **external IDs** in the format `<app-name>:<resource-name>` (auto-derived from `package.json` name + directory/file name).
+
+## Project Namespacing
+
+**All collection names are automatically namespaced by project.** Always use bare names (e.g. `orders`, not `myproject__orders`) everywhere — in collection JSON files, Python SDK calls, JavaScript hooks, and frontend queries. The platform resolves bare names to the project-scoped version transparently.
+
+- `pb.ensure_collection("orders", ...)` → stored as `{project}__orders`
+- `pb.search("orders", ...)` → resolves to `{project}__orders`
+- `ctx.dao.find("orders", ...)` → resolves to `{project}__orders`
+- `pbList("orders", ...)` in frontend → resolves via `X-Lumera-Project` header
+
+**Never manually prefix collection names with `{project}__`.** Two projects can each have an `orders` collection — they are fully isolated.
+
+For detailed technical reference (data models, relationships, design decisions), see [architecture.md](architecture.md).
+
+## UI Components
+
+**Always use shadcn components for UI.** Never hand-code primitives like buttons, dialogs, cards, inputs, tables, etc.
+
+### Installing components
+
+Use `bunx` to install shadcn components (the sandbox has `bun`, not `npm`/`npx`):
+
+```bash
+bunx shadcn@latest add button card dialog      # Install specific components
+bunx shadcn@latest add table input label select  # Install more as needed
+```
+
+Components install into `src/components/ui/` and are fully editable.
+
+### shadcn MCP server
+
+A `shadcn` MCP server is available to browse and search the registry. Use `mcp({ server: "shadcn" })` to list available tools, then:
+
+```
+mcp({ search: "button" })        # Search across all MCP servers
+mcp({ server: "shadcn" })        # List shadcn tools
+```
+
+Useful MCP tools:
+- **search_items_in_registries** — fuzzy search components by name
+- **view_items_in_registries** — view component source code
+- **get_item_examples_from_registries** — find usage examples with full code
+- **get_add_command_for_items** — get the install command
+
+All tools use the `@shadcn` registry (e.g. `@shadcn/button`, `@shadcn/card`).
+
+### Project setup
+
+- `components.json` — configures shadcn paths, aliases, and theme
+- `src/styles.css` — shadcn neutral theme CSS variables
+- `src/lib/utils.ts` — `cn()` utility, import from `@/lib/utils`
+- `src/components/ui/` — installed shadcn components (editable)
+
+**Do not hand-code UI primitives.** If you need a button, card, dialog, table, form, select, tabs, tooltip, or any standard UI element — install it from shadcn first.
+
+## Frontend API Calls
+
+Custom apps run in an **iframe**. **Always use the `@lumerahq/ui` bridge for API calls.** Never use raw `fetch()` against Lumera API endpoints.
+
+```ts
+// ✅ Correct — uses postMessage bridge, no CORS issues
+import { pbSql, pbList, pbCreate, pbUpdate, pbDelete } from '@lumerahq/ui/lib';
+
+// CRUD
+const records = await pbList('orders', { filter: JSON.stringify({ status: "pending" }) });
+await pbCreate('orders', { amount: 100 });
+await pbUpdate('orders', recordId, { status: 'done' });
+await pbDelete('orders', recordId);
+
+// ❌ WRONG — direct fetch will fail with CORS errors
+fetch('/api/pb/sql', { method: 'POST', body: JSON.stringify({ sql: '...' }) });
+fetch('https://app.lumerahq.com/api/pb/sql', ...);
+```
+
+**Why:** The bridge sends requests to the parent window via `postMessage`. The parent makes the actual API call on its own origin — no CORS, and auth is handled automatically.
+
+**Rules:**
+- Always import from `@lumerahq/ui/lib` — never write a custom `apiFetch` with raw `fetch()`
+- Token is not needed — the bridge handles auth via the parent session
+- `X-Lumera-Project` header is not needed — the parent adds it automatically
+
+
+## Workflow
+
+Follow the user's lead. If they tell you exactly what to build, build it. The workflow below is the default when they describe a goal and leave the approach to you.
+
+### Step 1: Plan
+1. **Read skills first** — Read the matching skill files for API details and patterns.
+2. **Discuss the plan** — Start from the **simplest thing that works** — one collection, one screen, one feature. Propose incremental steps that layer on complexity but if the decisions are obvious, you can execute multiple steps in one go. Each step should be a complete horizontal slice (collection + backend logic + UI).
+3. **Stop and ask the user to approve.** Iterate until they're happy with the plan. They may reorder steps, drop features, or add ones you didn't think of.
+
+### Step 2: Build (one slice at a time)
+4. **Build horizontally** — Pick the first step. Build the full slice: collection schema → `lumera apply` → seed data → UI route/components → commit. Each slice should be deployable and usable on its own.
+5. **Stop and ask for feedback** — Tell the user to open the **Preview tab** to see the app. The dev server starts automatically — you do NOT need to run `pnpm dev` or start any server. Iterate on the slice until they're happy.
+6. **Repeat** — Move to the next step. Build, deploy, get feedback.
+
+### Rules
+7. **Code is source of truth** — Edit files in `platform/`, then deploy with `lumera apply`. Don't edit in the Lumera UI.
+8. **Keep docs current** — After each slice, update `architecture.md` with what was built (data models, relationships, hook logic, design decisions). Also update the project description at the top of this file (`AGENTS.md`) so it reflects what the project actually does now — not the original template description.
+9. **Commit and push** — After each slice or significant change: `git add -A && git commit -m "descriptive message" && git push`. The sandbox is ephemeral — uncommitted work is lost if recycled.
+10. **Deploy marker** — When your changes need `lumera apply`, include at the end of your response: `<!-- DEPLOY: short commit message -->`. Skip for frontend-only changes.
+
+## File Artifacts
+
+When you create a file the user should **see** in chat (HTML pages, SVG graphics, CSV exports, PDFs, images, charts, etc.), call `create_artifact` with the file path after writing it. This uploads the file and renders an inline preview or download card in the chat. Without this step, the file exists in the sandbox but the user cannot see it.
+
+Always call `create_artifact` for: `.html`, `.svg`, `.csv`, `.json`, `.xml`, `.md`, `.txt`, `.pdf`, `.png`, `.jpg`, `.gif`, `.xlsx`, `.docx`, `.pptx`, `.zip` — any file the user asked to see or download.
+
+## Python
+
+Python 3.14 is pre-installed with common data packages (pandas, numpy, matplotlib, pdfplumber, openpyxl, etc.). To install additional packages use `uv add <package>` (preferred) or `pip install <package>`.
+
+## Key Commands
+
+```bash
+lumera plan                            # Preview changes (dry run)
+lumera apply                           # Deploy everything
+lumera run scripts/seed.py             # Run a script remotely
+lumera status                          # Show sync status
+```

package/templates/default/README.md

@@ -0,0 +1,18 @@
+# {{projectTitle}}
+
+Blank Lumera starter — a minimal React app with platform scaffolding. No pre-built collections, automations, or agents. Start building from scratch.
+
+## Quick Start
+
+```bash
+lumera plan    # Preview changes
+lumera apply   # Deploy resources
+```
+
+## Structure
+
+- `platform/collections/` — Collection schemas (JSON)
+- `platform/automations/` — Python automations
+- `platform/hooks/` — JavaScript hooks
+- `src/` — React frontend (TanStack Router + Query)
+- `scripts/` — Utility scripts

package/templates/default/_gitignore

@@ -0,0 +1,14 @@
+node_modules
+dist
+pnpm-lock.yaml
+.env
+.env.local
+*.local
+__pycache__
+*.pyc
+.venv/
+.lumera/
+uv.lock
+src/routeTree.gen.ts
+.tanstack/
+.pi/sessions/

package/templates/default/architecture.md

@@ -0,0 +1,29 @@
+# Architecture
+
+> Update this file as you build — it should always reflect the current state of the project so any agent or developer can understand the system from this file alone.
+
+## Overview
+
+This is a blank starter. No collections, automations, or hooks are defined yet. Build your app by adding resources to `platform/` and deploying with `lumera apply`.
+
+## Collections
+
+_None yet — add collection schemas to `platform/collections/` as you build._
+
+## Automations
+
+_None yet — add automation configs to `platform/automations/` as you build._
+
+## Hooks
+
+_None yet — add hook scripts to `platform/hooks/` as you build._
+
+## Frontend Routes
+
+| Route | Purpose |
+|-------|---------|
+| `/` | Home page — blank canvas, ready to build |
+
+## Design Decisions
+
+_Document key decisions here as you make them._

package/templates/default/biome.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "includes": ["**", "!!**/node_modules", "!!**/dist", "!!**/*routeTree.gen.ts"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": { "noExplicitAny": "off" },
+      "style": { "noNonNullAssertion": "off" }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "always",
+      "trailingCommas": "es5"
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  }
+}

package/templates/default/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-luma",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}

package/templates/default/icon.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="80" y2="80" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#ecfdf5"/>
+      <stop offset="100%" stop-color="#d1fae5"/>
+    </linearGradient>
+    <linearGradient id="g1" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#34d399"/>
+      <stop offset="100%" stop-color="#059669"/>
+    </linearGradient>
+  </defs>
+  <rect width="80" height="80" rx="18" fill="url(#bg)"/>
+  <!-- Rocket body -->
+  <path d="M40 12 C40 12 28 28 28 44 C28 52 33 58 40 58 C47 58 52 52 52 44 C52 28 40 12 40 12Z" fill="url(#g1)" opacity="0.9"/>
+  <!-- Window -->
+  <circle cx="40" cy="34" r="5" fill="#ecfdf5"/>
+  <circle cx="40" cy="34" r="3" fill="#059669" opacity="0.3"/>
+  <!-- Fins -->
+  <path d="M28 44 L20 54 L28 50Z" fill="#34d399" opacity="0.7"/>
+  <path d="M52 44 L60 54 L52 50Z" fill="#34d399" opacity="0.7"/>
+  <!-- Flame -->
+  <path d="M36 58 Q38 68 40 72 Q42 68 44 58" fill="#fbbf24"/>
+  <path d="M38 58 Q39 65 40 68 Q41 65 42 58" fill="#f97316"/>
+  <!-- Stars -->
+  <circle cx="18" cy="18" r="1.5" fill="#059669" opacity="0.5"/>
+  <circle cx="62" cy="14" r="1" fill="#059669" opacity="0.4"/>
+  <circle cx="14" cy="38" r="1" fill="#059669" opacity="0.3"/>
+  <circle cx="66" cy="32" r="1.5" fill="#059669" opacity="0.4"/>
+</svg>

package/templates/default/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#000000" />
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+    <title>{{projectTitle}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/default/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "type": "module",
+  "pnpm": {
+    "overrides": {
+      "@tanstack/router-core": "1.155.0"
+    }
+  },
+  "lumera": {
+    "version": 1,
+    "name": "{{projectTitle}}"
+  },
+  "scripts": {
+    "dev": "pnpm dlx @lumerahq/cli dev",
+    "deploy": "pnpm dlx @lumerahq/cli apply app",
+    "dev:vite": "vite",
+    "build": "vite build && tsc",
+    "preview": "vite preview",
+    "typecheck": "tsr generate && tsc --noEmit",
+    "lint": "biome lint --write .",
+    "format": "biome format --write .",
+    "check": "biome check --write .",
+    "check:ci": "biome check . && tsr generate && tsc --noEmit"
+  },
+  "dependencies": {
+    "@lumerahq/ui": "^0.7.6",
+    "@tanstack/react-query": "^5.90.11",
+    "@tanstack/react-router": "1.155.0",
+    "@tanstack/router-plugin": "1.155.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.7.0",
+    "radix-ui": "^1.4.3",
+    "shadcn": "^4.1.2",
+    "tailwind-merge": "^3.4.0",
+    "tw-animate-css": "^1.4.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "sonner": "^2.0.7",
+    "tailwindcss": "^4.2.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@tailwindcss/vite": "^4.2.2",
+    "@tanstack/router-cli": "1.155.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3"
+  }
+}

package/templates/default/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "{{projectName}}"
+version = "0.1.0"
+description = "{{projectTitle}} - Lumera custom app"
+requires-python = ">=3.11"
+dependencies = [
+    "lumera",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "pytest",
+]

package/templates/default/src/components/layout.tsx

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+
+export function AppLayout({ children }: { children: ReactNode }) {
+  return (
+    <div className="min-h-screen bg-background overflow-hidden">
+      <main className="overflow-auto scroll-smooth">
+        <div className="p-8 max-w-5xl mx-auto">{children}</div>
+      </main>
+    </div>
+  );
+}

package/templates/default/src/lib/auth.ts

@@ -0,0 +1,9 @@
+import { createContext } from 'react';
+
+export type AuthContextValue = {
+  company?: { id: string; name?: string; apiName?: string };
+  user?: { id: string; name: string; email: string; role?: string };
+  sessionToken?: string;
+};
+
+export const AuthContext = createContext<AuthContextValue | null>(null);

package/templates/default/src/lib/queries.ts

@@ -0,0 +1,17 @@
+// import { type PbRecord, pbList, pbSql } from '@lumerahq/ui/lib';
+
+// Add your collection types and query functions here.
+//
+// Example:
+//
+//   export type Order = PbRecord & {
+//     title: string;
+//     amount: number;
+//     status: string;
+//   };
+//
+//   export async function listOrders(page = 1) {
+//     return pbList<Order>('orders', { page, perPage: 20, sort: '-created' });
+//   }
+//
+// Use bare collection names — namespacing is handled automatically.

package/templates/default/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/default/src/main.tsx

@@ -0,0 +1,130 @@
+import { type HostPayload, isEmbedded, onInitMessage, postReadyMessage } from '@lumerahq/ui/lib';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createHashHistory, createRouter, RouterProvider } from '@tanstack/react-router';
+import { StrictMode, useEffect, useRef, useState } from 'react';
+import ReactDOM from 'react-dom/client';
+import { Toaster } from 'sonner';
+
+import { AuthContext, type AuthContextValue } from './lib/auth';
+import { routeTree } from './routeTree.gen';
+import './styles.css';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 30_000, retry: 1 },
+  },
+});
+
+const hashHistory = createHashHistory();
+
+const router = createRouter({
+  routeTree,
+  history: hashHistory,
+  context: {},
+  defaultPreload: 'intent',
+  scrollRestoration: true,
+});
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}
+
+const ROUTE_STORAGE_KEY = '{{projectName}}-route';
+
+function RouteRestorer() {
+  const isFirstLoad = useRef(true);
+
+  useEffect(() => {
+    if (isFirstLoad.current) {
+      isFirstLoad.current = false;
+      const savedRoute = localStorage.getItem(ROUTE_STORAGE_KEY);
+      if (savedRoute && savedRoute !== '/' && router.state.location.pathname === '/') {
+        router.navigate({ to: savedRoute });
+      }
+    }
+
+    return router.subscribe('onResolved', ({ toLocation }) => {
+      localStorage.setItem(ROUTE_STORAGE_KEY, toLocation.href);
+    });
+  }, []);
+
+  return null;
+}
+
+const App = () => {
+  const [hostContext, setHostContext] = useState<AuthContextValue | null>(null);
+  const [status, setStatus] = useState<'pending' | 'ready' | 'denied'>('pending');
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const standaloneDevMode =
+      import.meta.env.DEV && !isEmbedded() && !!import.meta.env.VITE_DEV_API_BASE_URL;
+
+    if (!isEmbedded() && !standaloneDevMode) {
+      setStatus('denied');
+      return;
+    }
+
+    const cleanup = onInitMessage((payload?: HostPayload) => {
+      setHostContext({
+        company: payload?.company,
+        user: payload?.user,
+        sessionToken: payload?.session?.token,
+      });
+      setStatus('ready');
+    });
+
+    postReadyMessage();
+    return cleanup;
+  }, []);
+
+  if (status === 'pending') {
+    return (
+      <main className="flex min-h-screen items-center justify-center bg-background">
+        <div className="flex flex-col items-center gap-4">
+          <div className="size-10 rounded-xl bg-gradient-to-br from-[var(--accent-gradient-from)] to-[var(--accent-gradient-to)] flex items-center justify-center text-white font-semibold text-lg shadow-sm animate-pulse">
+            L
+          </div>
+          <p className="text-sm text-muted-foreground">Loading...</p>
+        </div>
+      </main>
+    );
+  }
+
+  if (status === 'denied' || !hostContext) {
+    return (
+      <main className="flex min-h-screen items-center justify-center bg-background">
+        <div className="text-center space-y-3">
+          <div className="inline-flex size-12 rounded-xl bg-muted items-center justify-center mb-2">
+            <span className="text-2xl font-semibold text-muted-foreground">403</span>
+          </div>
+          <p className="text-sm text-muted-foreground">
+            Access denied, this app can only be accessed from within Lumera.
+          </p>
+        </div>
+      </main>
+    );
+  }
+
+  return (
+    <AuthContext.Provider value={hostContext}>
+      <QueryClientProvider client={queryClient}>
+        <RouterProvider router={router} />
+        <RouteRestorer />
+        <Toaster position="top-right" richColors />
+      </QueryClientProvider>
+    </AuthContext.Provider>
+  );
+};
+
+const rootElement = document.getElementById('app');
+if (rootElement && !rootElement.innerHTML) {
+  ReactDOM.createRoot(rootElement).render(
+    <StrictMode>
+      <App />
+    </StrictMode>,
+  );
+}

package/templates/default/src/routes/__root.tsx

@@ -0,0 +1,10 @@
+import { createRootRoute, Outlet } from '@tanstack/react-router';
+import { AppLayout } from '../components/layout';
+
+export const Route = createRootRoute({
+  component: () => (
+    <AppLayout>
+      <Outlet />
+    </AppLayout>
+  ),
+});