@korajs/cli 0.0.0-canary-20261008174129

package/templates/tauri-react/src/updater.ts

@@ -0,0 +1,38 @@
+/**
+ * Auto-updater integration via tauri-plugin-updater.
+ *
+ * Checks for updates on app launch and periodically. When an update is
+ * available, the user is notified and can install it with a restart.
+ *
+ * Configure the update endpoint in src-tauri/tauri.conf.json under
+ * plugins.updater.endpoints. For GitHub Releases, use:
+ *   "endpoints": ["https://github.com/YOUR_ORG/YOUR_REPO/releases/latest/download/latest.json"]
+ *
+ * To generate signing keys: `pnpm tauri signer generate -w ~/.tauri/myapp.key`
+ * Set the pubkey in tauri.conf.json and TAURI_SIGNING_PRIVATE_KEY in CI.
+ */
+
+let updateChecked = false
+
+/**
+ * Check for updates once on app startup.
+ * Silently skips if the updater is not configured (empty endpoints/pubkey).
+ */
+export async function checkForUpdates(): Promise<void> {
+	if (updateChecked) return
+	updateChecked = true
+
+	try {
+		const { check } = await import('@tauri-apps/plugin-updater')
+		const update = await check()
+		if (update) {
+			console.log(`Update available: v${update.version}`)
+			// Download and install — the app will restart automatically
+			await update.downloadAndInstall()
+		}
+	} catch (err) {
+		// Updater not configured or network unavailable — this is fine.
+		// The app works fully offline; updates are best-effort.
+		console.debug('Update check skipped:', err)
+	}
+}

package/templates/tauri-react/src/vite-env.d.ts

@@ -0,0 +1,19 @@
+interface ImportMetaEnv {
+	readonly DEV: boolean
+	readonly VITE_SYNC_URL?: string
+	readonly VITE_AUTH_URL?: string
+}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv
+}
+
+declare module '*?worker&url' {
+	const url: string
+	export default url
+}
+
+declare module '*?url' {
+	const url: string
+	export default url
+}

package/templates/tauri-react/src-tauri/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "app"
+version = "0.0.1"
+edition = "2021"
+
+[lib]
+name = "app_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+tauri-plugin-opener = "2"
+tauri-plugin-updater = "2"
+tauri-plugin-kora-sqlite = { version = "0.1", path = "../node_modules/@korajs/tauri/plugin" }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

package/templates/tauri-react/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build();
+}

package/templates/tauri-react/src-tauri/capabilities/default.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "Capability for the main window",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "opener:default",
+    "kora-sqlite:default",
+    "updater:default"
+  ]
+}

package/templates/tauri-react/src-tauri/src/lib.rs

@@ -0,0 +1,8 @@
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_opener::init())
+        .plugin(tauri_plugin_updater::Builder::new().build())
+        .plugin(tauri_plugin_kora_sqlite::init())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}

package/templates/tauri-react/src-tauri/src/main.rs

@@ -0,0 +1,6 @@
+// Prevents additional console window on Windows in release
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    app_lib::run();
+}

package/templates/tauri-react/src-tauri/tauri.conf.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://raw.githubusercontent.com/tauri-apps/tauri/dev/crates/tauri-config-schema/schema.json",
+  "productName": "kora-app",
+  "version": "0.0.1",
+  "identifier": "com.kora.app",
+  "build": {
+    "frontendDist": "../dist",
+    "devUrl": "http://localhost:5173",
+    "beforeDevCommand": "vite",
+    "beforeBuildCommand": "vite build"
+  },
+  "app": {
+    "windows": [
+      {
+        "title": "Kora Desktop App",
+        "width": 900,
+        "height": 700,
+        "resizable": true,
+        "fullscreen": false
+      }
+    ],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ],
+    "createUpdaterArtifacts": false
+  },
+  "plugins": {
+    "updater": {
+      "pubkey": "",
+      "endpoints": []
+    }
+  }
+}

package/templates/tauri-react/tsconfig.json.hbs

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/templates/tauri-react/vite.config.ts

@@ -0,0 +1,15 @@
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+// Tauri apps use native SQLite — no WASM, no OPFS, no cross-origin isolation needed.
+export default defineConfig({
+	plugins: [react()],
+	// Prevent Vite from obscuring Rust compilation errors
+	clearScreen: false,
+	server: {
+		// Tauri expects a fixed port; fail if it's not available
+		strictPort: true,
+	},
+	// Environment variables with this prefix are exposed to the app
+	envPrefix: ['VITE_', 'TAURI_'],
+})

package/templates/vue-basic/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this project. Humans: this is useful for you too.
+
+## What this project is
+
+This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
+
+## Golden rules
+
+1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
+2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
+3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
+4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
+5. **Surface mutation errors.** Fire-and-forget mutate calls put errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
+7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
+
+## Data API cheat sheet
+
+```ts
+await app.ready
+const rec = await app.todos.insert({ title: 'x' })   // defaults and .auto() fields applied
+await app.todos.update(rec.id, { completed: true })  // partial update, changed fields only
+await app.todos.delete(rec.id)
+const one = await app.todos.findById(rec.id)
+const unsubscribe = app.todos
+  .where({ completed: false })
+  .orderBy('createdAt', 'desc')
+  .subscribe((rows) => {/* fires immediately, then on every change */})
+```
+
+Schema example (`src/schema.ts`):
+
+```ts
+import { defineSchema, t } from 'korajs'
+
+export default defineSchema({
+  version: 1,
+  collections: {
+    todos: {
+      fields: {
+        title: t.string(),
+        completed: t.boolean().default(false),
+        tags: t.array(t.string()).default([]),
+        priority: t.enum(['low', 'medium', 'high']).default('medium'),
+        createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
+      },
+      indexes: ['completed', 'createdAt'],
+    },
+  },
+})
+```
+
+If you change a collection's shape, increment `version` and add a `migrations` entry for it (`migrate().addField(...)`): each device migrates its local database on its next open. `npx kora migrate` generates the matching migration for server databases and a transform stub for clients still on the older version.
+
+## Project conventions
+
+- Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, arrays as multisets that keep every device's additions and removals, objects per top-level key). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
+
+## Commands
+
+- `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
+- `npm run build` type-checks and builds for production.
+- `npx kora doctor` diagnoses a broken setup.
+- DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
+
+## Sync and auth
+
+Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
+
+## Vue bindings
+
+```ts
+import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/vue'
+
+const todos = useCollection('todos')
+const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
+const addTodo = useMutation((data) => todos.insert(data))
+```
+
+Rules: always surface the mutation's error state in the UI. `useQuery` reads the local store (no network, no spinner); the ref holds `[]` until the first local result. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

package/templates/vue-basic/README.md.hbs

@@ -0,0 +1,62 @@
+# {{projectName}}
+
+An offline-first application built with [Kora.js](https://ehoneahobed.github.io/kora/).
+
+## Getting Started
+
+```bash
+npm run dev
+```
+
+- **App**: http://localhost:5173
+
+## Project Structure
+
+```
+src/
+  schema.ts        # Schema entry point
+  main.tsx         # App initialization and Kora setup
+  App.tsx          # Main application component
+  modules/
+    todos/
+      todo.schema.ts     # Todo collection definition
+      todo.queries.ts    # Reusable todo query builders
+      todo.mutations.ts  # Todo mutation helpers
+      useTodos.ts        # React hook connecting todos to the UI
+  kora-worker.ts   # SQLite WASM web worker
+  index.css        # Styles
+kora.config.ts     # Kora configuration
+```
+
+In a feature module, `schema` defines data shape, `queries` contain reads only, `mutations` contain
+writes, and `useTodos.ts` is the React binding that exposes todo data and actions to components.
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Start dev server |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build |
+
+## Adding Sync
+
+To enable real-time sync across devices, update `src/main.tsx`:
+
+```typescript
+const app = createApp({
+  schema,
+  sync: {
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001/kora-sync',
+  },
+  // ...
+})
+```
+
+Then create a `server.ts` and install `@korajs/server`. See the [Sync Configuration guide](https://ehoneahobed.github.io/kora/guide/sync-configuration).
+
+## Learn More
+
+- [Documentation](https://ehoneahobed.github.io/kora/)
+- [Storage Configuration](https://ehoneahobed.github.io/kora/guide/storage-configuration)
+- [Schema Design](https://ehoneahobed.github.io/kora/guide/schema-design)

package/templates/vue-basic/index.html.hbs

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/vue-basic/kora.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'korajs/config'
+
+export default defineConfig({
+	schema: './src/schema.ts',
+	dev: {
+		port: 5173,
+		watch: {
+			enabled: true,
+			debounceMs: 300,
+		},
+	},
+})

package/templates/vue-basic/package.json.hbs

@@ -0,0 +1,32 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "kora dev",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "korajs": "{{koraVersion}}",
+    "@korajs/vue": "{{koraVersion}}",
+    "@korajs/store": "{{koraVersion}}",
+    "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
+    "vue": "^3.5.0",
+    "yjs": "^13.6.30"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "devDependencies": {
+    "@korajs/cli": "{{koraVersion}}",
+    "@vitejs/plugin-vue": "^5.2.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vue-tsc": "^2.2.0"
+  }
+}

package/templates/vue-basic/src/App.vue

@@ -0,0 +1,117 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { useTodos } from './modules/todos/useTodos'
+
+type Filter = 'all' | 'active' | 'completed'
+
+const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } = useTodos()
+
+const filter = ref<Filter>('all')
+const input = ref('')
+
+const filteredTodos = computed(() => {
+	if (filter.value === 'active') return activeTodos.value
+	if (filter.value === 'completed') return completedTodos.value
+	return allTodos.value
+})
+
+function handleSubmit(): void {
+	const title = input.value.trim()
+	if (!title) return
+	addTodo.mutate({ title })
+	input.value = ''
+}
+
+function clearCompleted(): void {
+	for (const todo of completedTodos.value) {
+		deleteTodo.mutate(todo.id)
+	}
+}
+
+function formatTime(timestamp: number): string {
+	const date = new Date(timestamp)
+	const now = new Date()
+	if (date.toDateString() === now.toDateString()) {
+		return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+	}
+	return date.toLocaleDateString([], { month: 'short', day: 'numeric' })
+}
+</script>
+
+<template>
+	<div class="app">
+		<div class="header">
+			<h1>My Tasks</h1>
+		</div>
+
+		<div class="stats">
+			<div class="stat-card">
+				<div class="label">Total</div>
+				<div class="value muted">{{ allTodos.length }}</div>
+			</div>
+			<div class="stat-card">
+				<div class="label">Remaining</div>
+				<div class="value warning">{{ activeTodos.length }}</div>
+			</div>
+			<div class="stat-card">
+				<div class="label">Done</div>
+				<div class="value success">{{ completedTodos.length }}</div>
+			</div>
+		</div>
+
+		<form class="add-form" @submit.prevent="handleSubmit">
+			<input v-model="input" type="text" placeholder="What needs to be done?" />
+			<button type="submit" :disabled="!input.trim()">Add</button>
+		</form>
+
+		<div class="filters">
+			<button
+				v-for="f in (['all', 'active', 'completed'] as const)"
+				:key="f"
+				type="button"
+				:class="['filter-btn', { active: filter === f }]"
+				@click="filter = f"
+			>
+				{{ f.charAt(0).toUpperCase() + f.slice(1) }}
+				<span class="badge">
+					{{
+						f === 'all'
+							? allTodos.length
+							: f === 'active'
+								? activeTodos.length
+								: completedTodos.length
+					}}
+				</span>
+			</button>
+		</div>
+
+		<div class="todo-list">
+			<div v-if="filteredTodos.length === 0" class="empty-state">
+				<template v-if="filter === 'all'">No tasks yet. Add one above!</template>
+				<template v-else-if="filter === 'active'">All caught up! No active tasks.</template>
+				<template v-else>No completed tasks yet.</template>
+			</div>
+			<div v-for="todo in filteredTodos" v-else :key="todo.id" class="todo-item">
+				<button
+					type="button"
+					:class="['toggle', { checked: todo.completed }]"
+					@click="toggleTodo.mutate(todo.id, { completed: !todo.completed })"
+				>
+					{{ todo.completed ? '✓' : '' }}
+				</button>
+				<span :class="['title', { done: todo.completed }]">{{ String(todo.title) }}</span>
+				<span v-if="todo.createdAt" class="time">{{ formatTime(Number(todo.createdAt)) }}</span>
+				<button type="button" class="delete-btn" @click="deleteTodo.mutate(todo.id)">×</button>
+			</div>
+		</div>
+
+		<div v-if="allTodos.length > 0" class="footer">
+			<span>{{ activeTodos.length }} item{{ activeTodos.length !== 1 ? 's' : '' }} left</span>
+			<button v-if="completedTodos.length > 0" type="button" @click="clearCompleted">
+				Clear completed
+			</button>
+		</div>
+
+		<p class="branding">Powered by Kora — offline-first</p>
+	</div>
+</template>