@lumerahq/cli 0.7.0

package/dist/status-BEVUV6RY.js

@@ -0,0 +1,131 @@
+import {
+  getToken,
+  getTokenSource
+} from "./chunk-NDLYGKS6.js";
+import {
+  detectProjectVersion,
+  findProjectRoot,
+  getAppName,
+  getAppTitle,
+  getBaseUrl,
+  readPackageJson
+} from "./chunk-D2BLSEGR.js";
+
+// src/commands/status.ts
+import pc from "picocolors";
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+async function validateToken(token) {
+  const baseUrl = getBaseUrl();
+  try {
+    const response = await fetch(`${baseUrl}/api/me`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!response.ok) {
+      return { valid: false, error: `${response.status} ${response.statusText}` };
+    }
+    const data = await response.json();
+    return {
+      valid: true,
+      user: data.user?.email,
+      company: data.user?.company?.name
+    };
+  } catch (err) {
+    return { valid: false, error: err instanceof Error ? err.message : "Unknown error" };
+  }
+}
+function countItems(dir) {
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile() || d.isDirectory()).length;
+}
+async function status(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`
+${pc.dim("Usage:")}
+  lumera status
+
+${pc.dim("Description:")}
+  Show project information and status.
+`);
+    return;
+  }
+  let projectRoot;
+  try {
+    projectRoot = findProjectRoot();
+  } catch {
+    console.error(pc.red("Not in a Lumera project directory."));
+    console.error(pc.dim("Run this command from a project with a package.json."));
+    process.exit(1);
+  }
+  const pkg = readPackageJson(projectRoot);
+  const version = detectProjectVersion(projectRoot);
+  const appName = getAppName(projectRoot);
+  const appTitle = getAppTitle(projectRoot);
+  const tokenSource = getTokenSource(projectRoot);
+  console.log();
+  console.log(pc.bold(`Project: ${appTitle}`));
+  console.log(pc.dim(`  Name: ${appName}`));
+  console.log(pc.dim(`  Version: ${pkg.version || "0.0.0"}`));
+  console.log(pc.dim(`  Structure: v${version}${version === 0 ? " (legacy)" : ""}`));
+  console.log();
+  const platformDir = version === 0 ? "lumera_platform" : "platform";
+  const collectionsDir = join(projectRoot, platformDir, "collections");
+  const automationsDir = join(projectRoot, platformDir, "automations");
+  const hooksDir = join(projectRoot, platformDir, "hooks");
+  const scriptsDir = version === 0 ? join(projectRoot, platformDir, "scripts") : join(projectRoot, "scripts");
+  const collections = countItems(collectionsDir);
+  const automations = countItems(automationsDir);
+  const hooks = countItems(hooksDir);
+  const scripts = countItems(scriptsDir);
+  console.log(pc.bold("Platform:"));
+  console.log(`  ${collections} collection${collections !== 1 ? "s" : ""}`);
+  console.log(`  ${automations} automation${automations !== 1 ? "s" : ""}`);
+  console.log(`  ${hooks} hook${hooks !== 1 ? "s" : ""}`);
+  console.log();
+  if (scripts > 0) {
+    console.log(pc.bold("Scripts:"));
+    console.log(`  ${scripts} script${scripts !== 1 ? "s" : ""}`);
+    console.log();
+  }
+  console.log(pc.bold("Auth:"));
+  const baseUrl = getBaseUrl();
+  console.log(pc.dim(`  API: ${baseUrl}`));
+  if (tokenSource) {
+    let token;
+    try {
+      token = getToken(projectRoot);
+    } catch {
+      console.log(pc.yellow(`  \u26A0 Token source found but could not read token`));
+      console.log(pc.dim(`    Run \`lumera login\` to re-authenticate`));
+      console.log();
+      return;
+    }
+    const validation = await validateToken(token);
+    if (validation.valid) {
+      console.log(pc.green(`  \u2713 Authenticated (${tokenSource})`));
+      if (validation.user) console.log(pc.dim(`    User: ${validation.user}`));
+      if (validation.company) console.log(pc.dim(`    Company: ${validation.company}`));
+    } else {
+      console.log(pc.red(`  \u2717 Token invalid (${tokenSource})`));
+      console.log(pc.dim(`    Error: ${validation.error}`));
+      console.log(pc.dim(`    Run \`lumera login\` to re-authenticate`));
+    }
+  } else {
+    console.log(pc.yellow(`  \u26A0 Not logged in`));
+    console.log(pc.dim(`    Run \`lumera login\` to authenticate`));
+  }
+  console.log();
+  if (version === 0) {
+    console.log(pc.yellow("\u26A0 This project uses legacy structure (v0)."));
+    console.log(pc.dim("  Run `lumera project migrate` to upgrade to v1."));
+    console.log();
+    console.log(pc.dim("  Limited functionality in v0:"));
+    console.log(pc.dim("  - lumera app deploy: \u2713 supported"));
+    console.log(pc.dim("  - lumera platform apply: \u2717 requires v1"));
+    console.log(pc.dim("  - lumera run: \u2717 requires v1"));
+    console.log();
+  }
+}
+export {
+  status
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@lumerahq/cli",
+  "version": "0.7.0",
+  "description": "CLI for building and deploying Lumera apps",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "lumera": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "archiver": "^7.0.1",
+    "dotenv": "^16.4.7",
+    "open": "^10.1.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/archiver": "^6.0.3",
+    "@types/node": "^22.10.2",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "dev": "tsup src/index.ts --format esm --watch"
+  }
+}

package/templates/default/CLAUDE.md

@@ -0,0 +1,245 @@
+# {{projectTitle}} - Claude Code Instructions
+
+**Full Architecture**: See `ARCHITECTURE.md`
+
+---
+
+## AI Agent Skills
+
+This project includes Lumera skills for AI coding agents. Skills provide detailed documentation for building on the Lumera platform.
+
+**Installed skills** (in `.claude/skills/`):
+- **lumera-collections** - Collections and Records API
+- **lumera-automations** - Python automation scripts
+- **lumera-webhooks** - Receiving external webhooks
+- **write-hooks** - Server-side JavaScript hooks
+- **lumera-sdk** - Python SDK reference
+- **using-lumera** - Platform overview and patterns
+
+### Installing/Updating Skills
+
+Skills are auto-installed when creating the app. To manually install or update:
+
+```bash
+npx skills add git@github.com:lumerahq/lumera-skills.git
+```
+
+> **Note:** Requires SSH access to the lumerahq GitHub organization.
+
+---
+
+## Quick Reference
+
+### Lumera CLI
+
+All `lumera` commands are run via `pnpm dlx`:
+
+```bash
+# Shortcuts
+pnpm dev              # Start dev server
+pnpm deploy           # Deploy frontend
+
+# All other commands
+pnpm dlx @lumerahq/cli platform plan
+pnpm dlx @lumerahq/cli platform apply
+pnpm dlx @lumerahq/cli platform destroy
+pnpm dlx @lumerahq/cli run scripts/seed-demo.py
+pnpm dlx @lumerahq/cli status
+```
+
+### Running the Frontend
+
+```bash
+# Login first (stores credentials in .lumera/credentials.json)
+lumera login
+
+# Start dev server
+pnpm dev
+
+# With custom port
+lumera app dev --port 3000
+
+# With ngrok tunnel
+lumera app dev --url https://my-tunnel.ngrok.io
+
+# Plain vite (no Lumera registration)
+pnpm dev:vite
+```
+
+### Linting & Formatting
+
+```bash
+# Type check without emitting
+pnpm typecheck
+
+# Lint and auto-fix
+pnpm lint
+
+# Format code
+pnpm format
+
+# Run all checks (lint + typecheck) - use in CI
+pnpm check:ci
+```
+
+### Deploying
+
+```bash
+# Deploy frontend to S3
+lumera app deploy
+
+# Apply platform resources (collections, automations, hooks)
+lumera platform apply
+
+# Preview platform changes first
+lumera platform plan
+```
+
+### Running Scripts
+
+All scripts are **idempotent** - safe to run multiple times during iterative development.
+
+```bash
+# Run a script locally
+lumera run scripts/seed-demo.py
+
+# Dependencies can be declared inline (PEP 723)
+```
+
+### Running Automations via External ID
+
+Always run automations using their `external_id` (not the internal Lumera ID which changes per tenant).
+
+```python
+uv run python << 'EOF'
+from lumera import automations
+
+# Run automation by external_id (returns Run object immediately)
+run = automations.run_by_external_id(
+    "{{projectName}}:my_automation",
+    inputs={"param": "value"}
+)
+print(f"Run ID: {run.id}")
+print(f"Status: {run.status}")
+
+# Wait for completion (blocks until done or timeout)
+result = run.wait(timeout=600)  # 10 min timeout
+print(f"Result: {result}")
+EOF
+```
+
+**Run object properties**: `id`, `status`, `result`, `error`, `inputs`, `is_terminal`
+**Run object methods**: `wait(timeout)`, `refresh()`, `cancel()`
+**Status values**: `queued`, `running`, `succeeded`, `failed`, `cancelled`, `timeout`
+
+---
+
+## Important Rules
+
+1. **Authenticate first** - Before running any CLI or SDK commands, ensure the user has run `lumera login --local`. This stores credentials in `.lumera/credentials.json` which the SDK reads automatically.
+
+2. **Source of truth is code** - `platform/` contains all schemas, automations, hooks. Update local code first, then deploy.
+
+3. **Never edit Lumera directly** - Don't change data/schema in Lumera UI without explicit user approval.
+
+4. **Offer to deploy** - When schemas, hooks, or automations change, offer to deploy to Lumera.
+
+5. **Use lumera-sdk skill for Python** - When writing scripts or automations, refer to the **lumera-sdk** skill (`.claude/skills/lumera-sdk.md`) for available SDK functions and usage patterns. The SDK source code is also available in `.venv/lib/python*/site-packages/lumera/` for detailed implementation reference. Key modules:
+   - `lumera.pb` - Record and collection operations (search, get, create, update, delete)
+   - `lumera.storage` - File uploads and downloads
+   - `lumera.llm` - LLM completions
+   - `lumera.automations` - Running and managing automations
+   - `lumera.integrations` - Third-party integrations (Google, Slack, etc.)
+
+6. **Use Python SDK for ad-hoc investigation** - When you need to quickly query data, inspect records, or debug issues, use the Python SDK with `uv run python` (uses `.venv` automatically via `pyproject.toml`):
+   ```bash
+   uv run python -c "from lumera import pb; print(pb.search('collection_name'))"
+   ```
+
+---
+
+## Key Directories
+
+```
+platform/
+├── automations/    # Automation scripts (Python)
+├── collections/    # Collection schemas (JSON)
+└── hooks/          # Server-side JavaScript hooks
+
+scripts/            # Local scripts (seed, migrate, etc.)
+
+src/                # React frontend
+├── routes/         # TanStack Router pages
+├── lib/            # queries.ts, api helpers
+└── components/     # React components
+
+.venv/              # Python venv with lumera SDK (for IDE autocomplete)
+```
+
+### Python Environment
+
+A Python virtual environment is created at `.venv/` with the `lumera` SDK pre-installed. This provides IDE autocomplete when writing automations and scripts.
+
+```bash
+# Activate venv (optional - for IDE integration)
+source .venv/bin/activate
+
+# SDK is available for import
+python -c "from lumera import pb; print(pb)"
+```
+
+> **Note:** You don't need to activate the venv to run scripts - `lumera run` handles this automatically.
+
+---
+
+## Frontend Patterns
+
+### Fetching Data
+
+```typescript
+import { pbSql, pbList } from '@lumerahq/ui/lib';
+
+const result = await pbSql<{ id: string; name: string }>({
+  sql: 'SELECT id, name FROM users WHERE active = true'
+});
+
+const items = await pbList<User>('users', {
+  filter: 'active = true',
+  sort: '-created',
+  perPage: 50,
+});
+```
+
+### Running Automations from Frontend
+
+```typescript
+import { createRun, pollRun } from '@lumerahq/ui/lib';
+
+const run = await createRun({
+  automationId: '{{projectName}}:process_data',
+  inputs: { file_id: 'abc123' },
+});
+
+const result = await pollRun(run.id);
+```
+
+---
+
+## Debugging with Lumera SDK
+
+```python
+uv run python << 'EOF'
+from lumera import pb
+
+# List collections
+print(pb.list_collections())
+
+# Search records
+result = pb.search("my_collection", per_page=10)
+print(result)
+
+# Get single record
+record = pb.get("my_collection", "record_id")
+print(record)
+EOF
+```

package/templates/default/README.md

@@ -0,0 +1,59 @@
+# {{projectTitle}}
+
+Lumera custom embedded app.
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Login to Lumera:
+   ```bash
+   lumera login
+   ```
+
+3. Start development server:
+   ```bash
+   pnpm dev
+   ```
+
+## CLI Commands
+
+```bash
+# Development
+lumera app dev                    # Start dev server
+lumera app dev --port 3000        # Custom port
+
+# Deployment
+lumera app deploy                 # Build and deploy frontend
+lumera platform apply             # Apply collections, automations, hooks
+lumera platform plan              # Preview platform changes
+
+# Scripts
+lumera run scripts/seed-demo.py   # Run seed script
+
+# Project info
+lumera status                     # Show project info
+```
+
+## Project Structure
+
+```
+├── src/                # Frontend (React + TanStack)
+│   ├── routes/         # TanStack Router pages
+│   ├── components/     # React components
+│   └── lib/            # API utilities
+├── platform/           # Backend resources
+│   ├── collections/    # Collection schemas (JSON)
+│   ├── automations/    # Automation scripts (Python)
+│   └── hooks/          # Server-side hooks (JS)
+├── scripts/            # Local scripts
+└── CLAUDE.md           # AI assistant instructions
+```
+
+## Documentation
+
+- `CLAUDE.md` - AI coding assistant instructions
+- `ARCHITECTURE.md` - System architecture (customize for your app)

package/templates/default/biome.json

@@ -0,0 +1,33 @@
+{
+  "$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"
+    }
+  }
+}

package/templates/default/index.html

@@ -0,0 +1,13 @@
+<!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" />
+    <title>{{projectTitle}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/default/package.json.hbs

@@ -0,0 +1,46 @@
+{
+  "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 app dev",
+    "deploy": "pnpm dlx @lumerahq/cli app deploy",
+    "dev:vite": "vite",
+    "build": "vite build && tsc",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint --write .",
+    "format": "biome format --write .",
+    "check": "biome check --write .",
+    "check:ci": "biome check . && tsc --noEmit"
+  },
+  "dependencies": {
+    "@lumerahq/ui": "^0.3.0",
+    "@tanstack/react-query": "^5.90.11",
+    "@tanstack/react-router": "1.155.0",
+    "@tanstack/router-plugin": "1.155.0",
+    "lucide-react": "^0.469.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "sonner": "^2.0.7",
+    "tailwindcss": "^4.0.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@tailwindcss/vite": "^4.0.6",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.0.4",
+    "typescript": "^5.7.2",
+    "vite": "^7.1.7"
+  }
+}

package/templates/default/platform/collections/example_items.json

@@ -0,0 +1,28 @@
+{
+  "id": "example_items",
+  "name": "example_items",
+  "fields": [
+    {
+      "name": "name",
+      "type": "text",
+      "required": true
+    },
+    {
+      "name": "status",
+      "type": "select",
+      "values": ["pending", "processing", "completed"],
+      "default": "pending"
+    },
+    {
+      "name": "description",
+      "type": "text"
+    },
+    {
+      "name": "source_id",
+      "type": "text"
+    }
+  ],
+  "indexes": [
+    { "fields": ["source_id"], "unique": true }
+  ]
+}

package/templates/default/pyproject.toml.hbs

@@ -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/scripts/seed-demo.py

@@ -0,0 +1,35 @@
+# /// script
+# dependencies = ["lumera-sdk"]
+# ///
+"""
+Seed demo data into Lumera (idempotent - safe to run multiple times).
+
+Usage:
+    lumera run scripts/seed-demo.py
+"""
+
+from lumera import pb
+
+# Seed demo items
+demo_items = [
+    {
+        "external_id": "demo:item_1",
+        "name": "Example Item 1",
+        "status": "pending",
+        "description": "This is an example item",
+    },
+    {
+        "external_id": "demo:item_2",
+        "name": "Example Item 2",
+        "status": "pending",
+        "description": "Another example item",
+    },
+]
+
+print("Seeding demo data...")
+
+for item in demo_items:
+    pb.upsert("example_items", item)
+    print(f"  ✓ {item['name']}")
+
+print(f"\nSeeded {len(demo_items)} items")