create-ekka-desktop-app 0.2.2

package/README.md

@@ -0,0 +1,137 @@
+# create-ekka-desktop-app
+
+Scaffold a new EKKA desktop app with one command. Zero config, batteries included.
+
+## Quick Start
+
+```bash
+npx create-ekka-desktop-app my-app
+cd my-app
+npm install
+npm run tauri:dev
+```
+
+That's it. You now have a native desktop app running.
+
+## What You Get
+
+```
+my-app/
+├── src/
+│   ├── app/App.tsx        # Your app (start here)
+│   ├── demo/              # Demo UI (delete when ready)
+│   └── ekka/              # EKKA SDK (do not modify)
+├── src-tauri/             # Tauri (Rust) shell
+├── branding/              # App name, icon, bundle ID
+├── package.json
+└── vite.config.ts
+```
+
+## Development
+
+```bash
+# Web browser (fast reload)
+npm start
+
+# Desktop window (native)
+npm run tauri:dev
+```
+
+## Build
+
+```bash
+# Create distributable .app
+npm run tauri:build
+```
+
+Output: `src-tauri/target/release/bundle/macos/<AppName>.app`
+
+## Customize Branding
+
+Edit `branding/app.json`:
+
+```json
+{
+  "name": "My App",
+  "bundleId": "com.mycompany.myapp",
+  "version": "1.0.0"
+}
+```
+
+Replace `branding/icon.icns` with your app icon.
+
+## Project Structure
+
+| Path | Purpose |
+|------|---------|
+| `src/app/App.tsx` | **Your app code starts here** |
+| `src/demo/` | Demo UI - delete when you're ready to build your own |
+| `src/ekka/` | EKKA SDK - provides secure APIs (do not modify) |
+| `src-tauri/` | Tauri shell - handles native window, builds .app |
+| `branding/` | App name, icon, bundle ID |
+
+## EKKA SDK
+
+The app includes the EKKA SDK at `src/ekka/`. It provides:
+
+- **Secure key-value storage** - Data persists across sessions
+- **Background work queues** - Run async tasks reliably
+- **Policy enforcement** - All operations are auditable
+
+```tsx
+import { ekka } from './ekka';
+
+// Store data
+await ekka.store.set('key', 'value');
+
+// Retrieve data
+const value = await ekka.store.get('key');
+
+// Queue background work
+await ekka.work.enqueue({ task: 'process', data: {...} });
+```
+
+## Demo Mode
+
+The app runs in **demo mode** by default - all data is stored in memory. This lets you develop and test without any backend setup.
+
+When you're ready for production:
+1. Build with the EKKA engine sidecar (via `ekka-desktop-build`)
+2. The SDK automatically connects to the real backend
+
+## Requirements
+
+- Node.js 18+
+- Rust (for Tauri builds)
+- Xcode Command Line Tools (macOS)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Start dev server (web) |
+| `npm run tauri:dev` | Start dev server (desktop) |
+| `npm run tauri:build` | Build distributable app |
+| `npm run lint` | Run ESLint |
+| `npm run build` | Build frontend only |
+
+## FAQ
+
+**Q: How do I change the app name?**
+Edit `branding/app.json` and set the `name` field.
+
+**Q: How do I change the app icon?**
+Replace `branding/icon.icns` with your icon file.
+
+**Q: How do I remove the demo UI?**
+Delete `src/demo/` and update `src/main.tsx` to render your own component.
+
+**Q: Where is my data stored in demo mode?**
+In memory. It resets when you restart the app.
+
+**Q: How do I connect to a real backend?**
+Build with `ekka-desktop-build` which injects the EKKA engine sidecar.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templateDir = resolve(__dirname, '..', 'template');
+
+const projectName = process.argv[2];
+
+if (!projectName) {
+  console.error('Usage: npx create-ekka-desktop-app <project-name>');
+  process.exit(1);
+}
+
+const targetDir = resolve(process.cwd(), projectName);
+
+if (existsSync(targetDir)) {
+  console.error(`Error: Directory "${projectName}" already exists.`);
+  process.exit(1);
+}
+
+console.log(`Creating EKKA desktop app in ${targetDir}...`);
+
+// Copy template
+mkdirSync(targetDir, { recursive: true });
+cpSync(templateDir, targetDir, { recursive: true });
+
+// Update package.json with project name
+const pkgPath = join(targetDir, 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+pkg.name = projectName;
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+// Update branding/app.json with project name
+const brandingPath = join(targetDir, 'branding', 'app.json');
+const branding = JSON.parse(readFileSync(brandingPath, 'utf8'));
+// Convert project-name to "Project Name" for display
+const displayName = projectName
+  .split('-')
+  .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+  .join(' ');
+// Convert project-name to ai.ekka.projectname for bundleId
+const bundleId = `ai.ekka.${projectName.replace(/-/g, '')}`;
+branding.name = displayName;
+branding.bundleId = bundleId;
+writeFileSync(brandingPath, JSON.stringify(branding, null, 2) + '\n');
+
+// Update src-tauri/Cargo.toml crate name
+const cargoPath = join(targetDir, 'src-tauri', 'Cargo.toml');
+let cargoContent = readFileSync(cargoPath, 'utf8');
+cargoContent = cargoContent.replace(/^name = ".*"$/m, `name = "${projectName}"`);
+cargoContent = cargoContent.replace(/^description = ".*"$/m, `description = "${displayName}"`);
+writeFileSync(cargoPath, cargoContent);
+
+console.log(`
+Done! To get started:
+
+  cd ${projectName}
+  npm install
+
+Development:
+  npm start            # Web (browser)
+  npm run tauri:dev    # Desktop (native window)
+
+Build:
+  npm run tauri:build  # Create distributable app
+
+Edit src/app/App.tsx to build your UI.
+Delete src/demo/ when ready.
+`);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "create-ekka-desktop-app",
+  "version": "0.2.2",
+  "description": "Create an EKKA desktop app with built-in demo backend. No setup required.",
+  "type": "module",
+  "bin": {
+    "create-ekka-desktop-app": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+    "ekka",
+    "desktop",
+    "scaffold",
+    "generator"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/branding/app.json

@@ -0,0 +1,6 @@
+{
+  "name": "EKKA Desktop",
+  "bundleId": "ai.ekka.desktop",
+  "version": "0.2.0",
+  "iconIcns": "branding/icon.icns"
+}

package/template/eslint.config.js

@@ -0,0 +1,98 @@
+/**
+ * EKKA Desktop App ESLint Configuration
+ *
+ * GUARDRAILS ENFORCED:
+ * - No fs, https, axios, child_process imports (TS is sandboxed)
+ * - No process.env access (TS MUST NOT decide config)
+ * - No direct fetch() calls outside src/ekka/client.ts
+ * - All network MUST go through the ekka client
+ *
+ * These rules enforce the EKKA security model:
+ * TS communicates ONLY through the ekka client to EKKA's servers.
+ */
+
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist', 'node_modules', 'src-tauri', 'vite.config.ts', 'eslint.config.js']),
+
+  // Base config for all TypeScript files
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactRefresh.configs.vite,
+    ],
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    rules: {
+      // React hooks rules
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+
+      // ========================================
+      // EKKA GUARDRAILS - FORBIDDEN IMPORTS
+      // ========================================
+      'no-restricted-imports': ['error', {
+        paths: [
+          // Node.js modules - TS MUST NOT access filesystem or spawn processes
+          { name: 'fs', message: 'EKKA: TS is sandboxed. TS MUST NOT read files.' },
+          { name: 'fs/promises', message: 'EKKA: TS is sandboxed. TS MUST NOT read files.' },
+          { name: 'node:fs', message: 'EKKA: TS is sandboxed. TS MUST NOT read files.' },
+          { name: 'node:fs/promises', message: 'EKKA: TS is sandboxed. TS MUST NOT read files.' },
+          { name: 'path', message: 'EKKA: TS is sandboxed. Use ekka client for all operations.' },
+          { name: 'node:path', message: 'EKKA: TS is sandboxed. Use ekka client for all operations.' },
+          { name: 'child_process', message: 'EKKA: TS is sandboxed. TS MUST NOT spawn processes.' },
+          { name: 'node:child_process', message: 'EKKA: TS is sandboxed. TS MUST NOT spawn processes.' },
+
+          // Network libraries - TS MUST NOT make direct network calls
+          { name: 'https', message: 'EKKA: TS MUST NOT make direct network calls. Use ekka client only.' },
+          { name: 'node:https', message: 'EKKA: TS MUST NOT make direct network calls. Use ekka client only.' },
+          { name: 'http', message: 'EKKA: TS MUST NOT make direct network calls. Use ekka client only.' },
+          { name: 'node:http', message: 'EKKA: TS MUST NOT make direct network calls. Use ekka client only.' },
+          { name: 'axios', message: 'EKKA: TS MUST NOT use axios. Use ekka client only.' },
+          { name: 'node-fetch', message: 'EKKA: TS MUST NOT use node-fetch. Use ekka client only.' },
+
+          // Crypto - TS MUST NOT do crypto
+          { name: 'crypto', message: 'EKKA: TS MUST NOT do crypto. Server handles all crypto.' },
+          { name: 'node:crypto', message: 'EKKA: TS MUST NOT do crypto. Server handles all crypto.' },
+        ],
+        patterns: [
+          { group: ['axios/*'], message: 'EKKA: TS MUST NOT use axios. Use ekka client only.' },
+        ],
+      }],
+
+      // ========================================
+      // EKKA GUARDRAILS - NO PROCESS.ENV
+      // ========================================
+      'no-restricted-globals': ['error',
+        { name: 'process', message: 'EKKA: TS MUST NOT access process.env. Config is managed by EKKA.' },
+      ],
+    },
+  },
+
+  // ========================================
+  // EKKA GUARDRAILS - NO FETCH() ANYWHERE
+  // ALL HTTP must go through Tauri/Rust via engine_request
+  // ========================================
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-globals': ['error',
+        { name: 'process', message: 'EKKA: TS MUST NOT access process.env. Config is managed by EKKA.' },
+        { name: 'fetch', message: 'EKKA: Direct fetch() is FORBIDDEN. All HTTP must go through Tauri via engine_request. See RULEBOOK_ARCHITECTURE_AI.md.' },
+      ],
+    },
+  },
+])

package/template/index.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>EKKA Desktop App</title>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html, body, #root {
+        height: 100%;
+        width: 100%;
+        overflow: hidden;
+      }
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ekka-desktop-app",
+  "private": true,
+  "version": "0.2.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "start": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "preview": "vite preview",
+    "tauri": "tauri",
+    "tauri:dev": "tauri dev",
+    "tauri:build": "tauri build"
+  },
+  "dependencies": {
+    "@tauri-apps/api": "^2.0.0",
+    "@tauri-apps/plugin-dialog": "^2.6.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@tauri-apps/cli": "^2.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint": "^9.17.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.16",
+    "globals": "^15.14.0",
+    "typescript": "~5.6.2",
+    "typescript-eslint": "^8.18.2",
+    "vite": "^6.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/template/src/app/App.tsx

@@ -0,0 +1,24 @@
+/**
+ * Your App - Edit this file!
+ *
+ * This is where you build your UI.
+ * Use the ekka client for all data operations.
+ */
+
+import { ekka } from '../ekka';
+
+export function App() {
+  // Example: Initialize on button click
+  async function handleStart() {
+    await ekka.connect();
+    // Now you can use ekka.db and ekka.queue
+  }
+
+  return (
+    <div style={{ padding: '2rem', fontFamily: 'system-ui, sans-serif' }}>
+      <h1>My EKKA App</h1>
+      <p>Edit <code>src/app/App.tsx</code> to get started.</p>
+      <button onClick={handleStart}>Start</button>
+    </div>
+  );
+}