@korajs/cli 0.5.0 → 1.0.0-beta.0

package/templates/vue-sync/src/index.css

@@ -0,0 +1,339 @@
+*,
+*::before,
+*::after {
+	box-sizing: border-box;
+	margin: 0;
+	padding: 0;
+}
+
+:root {
+	--color-bg: #0a0a0f;
+	--color-surface: #111118;
+	--color-border: #1e1e2a;
+	--color-border-hover: #2a2a3a;
+	--color-text: #e4e4e7;
+	--color-text-muted: #71717a;
+	--color-text-dim: #3f3f46;
+	--color-primary: #6366f1;
+	--color-primary-hover: #818cf8;
+	--color-success: #34d399;
+	--color-warning: #fbbf24;
+	--color-danger: #f87171;
+	--font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+	--radius: 8px;
+}
+
+body {
+	font-family: var(--font-sans);
+	background: var(--color-bg);
+	color: var(--color-text);
+	line-height: 1.6;
+	-webkit-font-smoothing: antialiased;
+}
+
+.app {
+	max-width: 640px;
+	margin: 0 auto;
+	padding: 48px 16px;
+}
+
+.header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	margin-bottom: 32px;
+}
+
+.header h1 {
+	font-size: 1.5rem;
+	font-weight: 700;
+}
+
+.header-actions {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+}
+
+.sync-badge {
+	display: inline-flex;
+	align-items: center;
+	gap: 6px;
+	padding: 4px 12px;
+	border-radius: 999px;
+	background: var(--color-surface);
+	font-size: 0.8rem;
+}
+
+.sync-dot {
+	width: 8px;
+	height: 8px;
+	border-radius: 50%;
+}
+
+.sync-dot.connected,
+.sync-dot.synced {
+	background: var(--color-success);
+}
+.sync-dot.syncing {
+	background: var(--color-warning);
+}
+.sync-dot.offline {
+	background: var(--color-text-muted);
+}
+.sync-dot.error {
+	background: var(--color-danger);
+}
+
+.auth-button {
+	border: 1px solid var(--color-border);
+	border-radius: 999px;
+	background: var(--color-surface);
+	color: var(--color-text);
+	cursor: pointer;
+	font-size: 0.8rem;
+	max-width: 180px;
+	overflow: hidden;
+	padding: 4px 12px;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.auth-button:hover {
+	border-color: var(--color-border-hover);
+}
+
+.auth-error {
+	border: 1px solid rgba(248, 113, 113, 0.35);
+	border-radius: var(--radius);
+	color: var(--color-danger);
+	font-size: 0.85rem;
+	margin-bottom: 16px;
+	padding: 10px 12px;
+}
+
+.stats {
+	display: grid;
+	grid-template-columns: repeat(3, 1fr);
+	gap: 12px;
+	margin-bottom: 32px;
+}
+
+.stat-card {
+	background: var(--color-surface);
+	border: 1px solid var(--color-border);
+	border-radius: var(--radius);
+	padding: 16px;
+}
+
+.stat-card .label {
+	font-size: 0.8rem;
+	color: var(--color-text-muted);
+}
+
+.stat-card .value {
+	font-size: 1.5rem;
+	font-weight: 700;
+}
+
+.stat-card .value.muted {
+	color: var(--color-text-muted);
+}
+.stat-card .value.warning {
+	color: var(--color-warning);
+}
+.stat-card .value.success {
+	color: var(--color-success);
+}
+
+.add-form {
+	display: flex;
+	gap: 12px;
+	margin-bottom: 32px;
+}
+
+.add-form input {
+	flex: 1;
+	padding: 10px 16px;
+	border: 1px solid var(--color-border);
+	border-radius: var(--radius);
+	background: var(--color-surface);
+	color: var(--color-text);
+	font-size: 0.95rem;
+	outline: none;
+}
+
+.add-form input:focus {
+	border-color: var(--color-primary);
+}
+
+.add-form input::placeholder {
+	color: var(--color-text-muted);
+}
+
+.add-form button {
+	padding: 10px 20px;
+	border: none;
+	border-radius: var(--radius);
+	background: var(--color-primary);
+	color: white;
+	font-size: 0.95rem;
+	font-weight: 500;
+	cursor: pointer;
+}
+
+.add-form button:hover {
+	background: var(--color-primary-hover);
+}
+
+.add-form button:disabled {
+	opacity: 0.5;
+	cursor: not-allowed;
+}
+
+.filters {
+	display: flex;
+	gap: 8px;
+	margin-bottom: 24px;
+}
+
+.filter-btn {
+	padding: 6px 16px;
+	border: none;
+	border-radius: var(--radius);
+	background: var(--color-surface);
+	color: var(--color-text-muted);
+	font-size: 0.85rem;
+	font-weight: 500;
+	cursor: pointer;
+}
+
+.filter-btn:hover {
+	background: var(--color-border-hover);
+	color: var(--color-text);
+}
+
+.filter-btn.active {
+	background: var(--color-primary);
+	color: white;
+}
+
+.filter-btn .badge {
+	display: inline-block;
+	margin-left: 6px;
+	padding: 1px 6px;
+	border-radius: 999px;
+	font-size: 0.75rem;
+	background: rgba(255, 255, 255, 0.15);
+}
+
+.filter-btn:not(.active) .badge {
+	background: var(--color-border);
+}
+
+.todo-list {
+	display: flex;
+	flex-direction: column;
+	gap: 8px;
+}
+
+.todo-item {
+	display: flex;
+	align-items: center;
+	gap: 12px;
+	padding: 12px 16px;
+	border: 1px solid var(--color-border);
+	border-radius: var(--radius);
+	background: var(--color-surface);
+}
+
+.todo-item:hover {
+	border-color: var(--color-border-hover);
+}
+
+.todo-item .toggle {
+	background: none;
+	border: 2px solid var(--color-text-muted);
+	width: 20px;
+	height: 20px;
+	border-radius: 50%;
+	cursor: pointer;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	color: transparent;
+	font-size: 0.7rem;
+	flex-shrink: 0;
+}
+
+.todo-item .toggle.checked {
+	border-color: var(--color-success);
+	background: var(--color-success);
+	color: white;
+}
+
+.todo-item .title {
+	flex: 1;
+}
+
+.todo-item .title.done {
+	text-decoration: line-through;
+	color: var(--color-text-muted);
+}
+
+.todo-item .time {
+	font-size: 0.75rem;
+	color: var(--color-text-dim);
+}
+
+.todo-item .delete-btn {
+	background: none;
+	border: none;
+	color: var(--color-text-dim);
+	cursor: pointer;
+	padding: 4px;
+	opacity: 0;
+	transition: opacity 0.15s;
+}
+
+.todo-item:hover .delete-btn {
+	opacity: 1;
+}
+
+.todo-item .delete-btn:hover {
+	color: var(--color-danger);
+}
+
+.empty-state {
+	padding: 48px 0;
+	text-align: center;
+	color: var(--color-text-dim);
+	border: 1px dashed var(--color-border);
+	border-radius: var(--radius);
+}
+
+.footer {
+	display: flex;
+	justify-content: space-between;
+	margin-top: 24px;
+	font-size: 0.85rem;
+	color: var(--color-text-muted);
+}
+
+.footer button {
+	background: none;
+	border: none;
+	color: var(--color-text-muted);
+	cursor: pointer;
+}
+
+.footer button:hover {
+	color: var(--color-text);
+}
+
+.branding {
+	margin-top: 48px;
+	text-align: center;
+	font-size: 0.75rem;
+	color: var(--color-text-dim);
+}

package/templates/vue-sync/src/kora-worker.ts

@@ -0,0 +1,9 @@
+// Web Worker entry point for SQLite WASM.
+// Loaded automatically by the Kora store to run SQLite in a background thread.
+
+// Import the WASM binary URL so Vite resolves it with the correct content hash.
+// Without this, production builds fail because sqlite3 looks for the unhashed filename.
+import sqliteWasmUrl from '@sqlite.org/sqlite-wasm/sqlite3.wasm?url'
+;(globalThis as Record<string, unknown>).__KORA_SQLITE_WASM_URL = sqliteWasmUrl
+
+import '@korajs/store/sqlite-wasm/worker'

package/templates/vue-sync/src/main.ts

@@ -0,0 +1,47 @@
+import { createKoraAuthSync } from '@korajs/auth'
+import { AuthProvider } from '@korajs/auth/vue'
+import { KoraProvider } from '@korajs/vue'
+import { createApp as createKoraApp } from 'korajs'
+import { createApp, h } from 'vue'
+import App from './App.vue'
+import { authClient, completeOAuthCallbackFromLocation } from './auth'
+import schema from './schema'
+import './index.css'
+import koraWorkerUrl from './kora-worker.ts?worker&url'
+
+const syncUrl =
+	import.meta.env.VITE_SYNC_URL ||
+	`${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/kora-sync`
+
+const kora = createKoraApp({
+	schema,
+	sync: {
+		url: syncUrl,
+		authClient: createKoraAuthSync({ authClient, schema }),
+	},
+	store: {
+		workerUrl: koraWorkerUrl,
+	},
+	devtools: true,
+})
+
+kora.ready.then(() => kora.sync?.connect())
+void completeOAuthCallbackFromLocation().catch((error) => {
+	console.error('[Kora Auth] OAuth callback failed:', error)
+})
+
+createApp({
+	render: () =>
+		h(
+			AuthProvider,
+			{ client: authClient, fallback: h('div', 'Restoring session...') },
+			{
+				default: () =>
+					h(
+						KoraProvider,
+						{ app: kora, fallback: h('div', 'Loading...') },
+						{ default: () => h(App) },
+					),
+			},
+		),
+}).mount('#app')

package/templates/vue-sync/src/modules/todos/todo.mutations.ts

@@ -0,0 +1,25 @@
+import type { CollectionAccessor } from 'korajs'
+
+export interface CreateTodoInput {
+	title: string
+}
+
+export interface UpdateTodoStatusInput {
+	completed: boolean
+}
+
+export function createTodo(todos: CollectionAccessor, data: CreateTodoInput) {
+	return todos.insert({ title: data.title })
+}
+
+export function updateTodoStatus(
+	todos: CollectionAccessor,
+	id: string,
+	data: UpdateTodoStatusInput,
+) {
+	return todos.update(id, { completed: data.completed })
+}
+
+export function deleteTodo(todos: CollectionAccessor, id: string) {
+	return todos.delete(id)
+}

package/templates/vue-sync/src/modules/todos/todo.queries.ts

@@ -0,0 +1,5 @@
+import type { CollectionAccessor } from 'korajs'
+
+export function orderedTodos(todos: CollectionAccessor) {
+	return todos.where({}).orderBy('createdAt', 'desc')
+}

package/templates/vue-sync/src/modules/todos/todo.schema.ts

@@ -0,0 +1,10 @@
+import { t } from 'korajs'
+
+export const todos = {
+	fields: {
+		title: t.string(),
+		completed: t.boolean().default(false),
+		createdAt: t.timestamp().auto(),
+	},
+	indexes: ['completed', 'createdAt'],
+}

package/templates/vue-sync/src/modules/todos/useTodos.ts

@@ -0,0 +1,32 @@
+import { useCollection, useMutation, useQuery } from '@korajs/vue'
+import { computed } from 'vue'
+import {
+	type CreateTodoInput,
+	type UpdateTodoStatusInput,
+	createTodo,
+	deleteTodo,
+	updateTodoStatus,
+} from './todo.mutations'
+import { orderedTodos } from './todo.queries'
+
+export function useTodos() {
+	const todos = useCollection('todos')
+	const allTodos = useQuery(orderedTodos(todos))
+	const addTodo = useMutation((data: CreateTodoInput) => createTodo(todos, data))
+	const toggleTodo = useMutation((id: string, data: UpdateTodoStatusInput) =>
+		updateTodoStatus(todos, id, data),
+	)
+	const removeTodo = useMutation((id: string) => deleteTodo(todos, id))
+
+	const activeTodos = computed(() => allTodos.value.filter((todo) => !todo.completed))
+	const completedTodos = computed(() => allTodos.value.filter((todo) => !!todo.completed))
+
+	return {
+		allTodos,
+		activeTodos,
+		completedTodos,
+		addTodo,
+		toggleTodo,
+		deleteTodo: removeTodo,
+	}
+}

package/templates/vue-sync/src/schema.ts

@@ -0,0 +1,9 @@
+import { defineSchema } from 'korajs'
+import { todos } from './modules/todos/todo.schema'
+
+export default defineSchema({
+	version: 1,
+	collections: {
+		todos,
+	},
+})

package/templates/vue-sync/src/vite-env.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+	import type { DefineComponent } from 'vue'
+	const component: DefineComponent<object, object, unknown>
+	export default component
+}
+
+interface ImportMetaEnv {
+	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/vue-sync/tsconfig.json.hbs

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "jsx": "preserve",
+    "lib": ["ES2022", "DOM"],
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}

package/templates/vue-sync/vite.config.ts

@@ -0,0 +1,79 @@
+import { copyFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import vue from '@vitejs/plugin-vue'
+import type { Plugin } from 'vite'
+import { defineConfig } from 'vite'
+
+function crossOriginIsolation(): Plugin {
+	return {
+		name: 'cross-origin-isolation',
+		configureServer(server) {
+			server.middlewares.use((_req, res, next) => {
+				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				next()
+			})
+		},
+		configurePreviewServer(server) {
+			server.middlewares.use((_req, res, next) => {
+				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				next()
+			})
+		},
+	}
+}
+
+function sqliteWasmHotfix(): Plugin {
+	return {
+		name: 'sqlite-wasm-hotfix',
+		apply: 'build',
+		closeBundle() {
+			const assetsDir = resolve('dist', 'assets')
+			if (!existsSync(assetsDir)) return
+
+			for (const file of readdirSync(assetsDir)) {
+				if (/^sqlite3-.+\.wasm$/.test(file)) {
+					copyFileSync(join(assetsDir, file), join(assetsDir, 'sqlite3.wasm'))
+					break
+				}
+			}
+
+			const proxyFile = resolve(
+				'node_modules',
+				'@sqlite.org',
+				'sqlite-wasm',
+				'sqlite-wasm',
+				'jswasm',
+				'sqlite3-opfs-async-proxy.js',
+			)
+			if (existsSync(proxyFile)) {
+				copyFileSync(proxyFile, join(assetsDir, 'sqlite3-opfs-async-proxy.js'))
+			}
+		},
+	}
+}
+
+export default defineConfig({
+	plugins: [vue(), crossOriginIsolation(), sqliteWasmHotfix()],
+	worker: {
+		format: 'es',
+	},
+	optimizeDeps: {
+		exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
+		include: ['yjs'],
+	},
+	resolve: {
+		dedupe: ['yjs'],
+	},
+	server: {
+		allowedHosts: true,
+		proxy: {
+			'/kora-sync': {
+				target: 'ws://localhost:3001',
+				ws: true,
+				rewriteWsOrigin: true,
+			},
+		},
+	},
+})

package/templates/vue-tailwind/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 swallow 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 bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+
+## 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, add-wins for arrays). 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 synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.