@syncular/cli 0.0.0

package/templates/demo/src/client/App.tsx.tpl

@@ -0,0 +1,137 @@
+import { useEffect, useState } from 'react';
+import type { TasksTable } from '../shared/db';
+import {
+  addTask,
+  initializeDemoSync,
+  listTasks,
+  removeTask,
+  subscribeToTaskChanges,
+  toggleTask,
+} from './syncular';
+
+export default function App() {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [tasks, setTasks] = useState<TasksTable[]>([]);
+  const [title, setTitle] = useState('');
+  const [saving, setSaving] = useState(false);
+
+  useEffect(() => {
+    let disposed = false;
+    let unsubscribe: (() => void) | null = null;
+
+    async function refresh() {
+      const rows = await listTasks();
+      if (!disposed) {
+        setTasks(rows);
+      }
+    }
+
+    async function boot() {
+      try {
+        await initializeDemoSync();
+        await refresh();
+        unsubscribe = await subscribeToTaskChanges(() => {
+          void refresh();
+        });
+      } catch (nextError) {
+        if (!disposed) {
+          setError(nextError instanceof Error ? nextError.message : String(nextError));
+        }
+      } finally {
+        if (!disposed) {
+          setLoading(false);
+        }
+      }
+    }
+
+    void boot();
+
+    return () => {
+      disposed = true;
+      unsubscribe?.();
+    };
+  }, []);
+
+  const onAdd = async () => {
+    const value = title.trim();
+    if (value.length === 0) return;
+
+    setSaving(true);
+    setError(null);
+    try {
+      await addTask(value);
+      setTitle('');
+    } catch (nextError) {
+      setError(nextError instanceof Error ? nextError.message : String(nextError));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const onToggle = async (task: TasksTable) => {
+    try {
+      await toggleTask(task);
+    } catch (nextError) {
+      setError(nextError instanceof Error ? nextError.message : String(nextError));
+    }
+  };
+
+  const onRemove = async (taskId: string) => {
+    try {
+      await removeTask(taskId);
+    } catch (nextError) {
+      setError(nextError instanceof Error ? nextError.message : String(nextError));
+    }
+  };
+
+  return (
+    <main className="page">
+      <header>
+        <h1>Syncular Demo</h1>
+        <p>Hono + Vite React + WA-SQLite</p>
+      </header>
+
+      <section className="card">
+        <h2>Tasks</h2>
+
+        <div className="input-row">
+          <input
+            value={title}
+            onChange={(event) => setTitle(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                void onAdd();
+              }
+            }}
+            placeholder="What should be synced?"
+          />
+          <button type="button" onClick={() => void onAdd()} disabled={saving}>
+            {saving ? 'Saving...' : 'Add'}
+          </button>
+        </div>
+
+        {loading ? <p>Connecting local DB + sync engine...</p> : null}
+        {error ? <p className="error">{error}</p> : null}
+
+        <ul className="task-list">
+          {tasks.map((task) => (
+            <li key={task.id}>
+              <label>
+                <input
+                  type="checkbox"
+                  checked={task.completed === 1}
+                  onChange={() => void onToggle(task)}
+                />
+                <span>{task.title}</span>
+              </label>
+              <button type="button" onClick={() => void onRemove(task.id)}>
+                Delete
+              </button>
+            </li>
+          ))}
+        </ul>
+      </section>
+    </main>
+  );
+}

package/templates/demo/src/client/main.tsx.tpl

@@ -0,0 +1,15 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import './styles.css';
+
+const root = document.getElementById('root');
+if (!root) {
+  throw new Error('Missing #root element');
+}
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/templates/demo/src/client/styles.css.tpl

@@ -0,0 +1,93 @@
+:root {
+  font-family: 'SF Pro Text', 'Segoe UI', Helvetica, Arial, sans-serif;
+  color: #0f172a;
+  background: linear-gradient(180deg, #f8fafc 0%, #eef2ff 100%);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+}
+
+.page {
+  max-width: 760px;
+  margin: 0 auto;
+  padding: 48px 20px;
+}
+
+header h1 {
+  margin: 0;
+  font-size: 2rem;
+}
+
+header p {
+  margin: 6px 0 0;
+  color: #334155;
+}
+
+.card {
+  margin-top: 24px;
+  padding: 20px;
+  border-radius: 14px;
+  background: #ffffff;
+  box-shadow: 0 12px 30px rgba(15, 23, 42, 0.08);
+}
+
+.input-row {
+  display: flex;
+  gap: 10px;
+}
+
+.input-row input {
+  flex: 1;
+  padding: 10px 12px;
+  border: 1px solid #cbd5e1;
+  border-radius: 8px;
+}
+
+button {
+  padding: 10px 14px;
+  border: 0;
+  border-radius: 8px;
+  background: #2563eb;
+  color: #ffffff;
+  cursor: pointer;
+}
+
+button:disabled {
+  opacity: 0.7;
+  cursor: default;
+}
+
+.task-list {
+  margin: 16px 0 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.task-list li {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 10px 12px;
+  border-radius: 8px;
+  border: 1px solid #e2e8f0;
+}
+
+.task-list label {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.error {
+  margin: 12px 0;
+  color: #dc2626;
+}

package/templates/demo/src/client/syncular.ts.tpl

@@ -0,0 +1,109 @@
+import { createClient, type Client } from '@syncular/client';
+import { createWaSqliteDb } from '@syncular/dialect-wa-sqlite';
+import { createHttpTransport } from '@syncular/transport-http';
+import type { Kysely } from 'kysely';
+import type { AppClientDb, TasksTable } from '../shared/db';
+
+const ACTOR_ID = 'demo-user';
+const CLIENT_DATABASE_FILE = 'syncular-demo-client.sqlite';
+
+interface DemoRuntime {
+  db: Kysely<AppClientDb>;
+  client: Client<AppClientDb>;
+}
+
+let runtimePromise: Promise<DemoRuntime> | null = null;
+
+async function ensureClientAppTables(db: Kysely<AppClientDb>): Promise<void> {
+  await db.schema
+    .createTable('tasks')
+    .ifNotExists()
+    .addColumn('id', 'text', (col) => col.primaryKey())
+    .addColumn('title', 'text', (col) => col.notNull())
+    .addColumn('completed', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('user_id', 'text', (col) => col.notNull())
+    .addColumn('server_version', 'integer', (col) => col.notNull().defaultTo(0))
+    .execute();
+}
+
+async function createRuntime(): Promise<DemoRuntime> {
+  const db = createWaSqliteDb<AppClientDb>({ fileName: CLIENT_DATABASE_FILE });
+  await ensureClientAppTables(db);
+
+  const { client } = await createClient<AppClientDb>({
+    db,
+    actorId: ACTOR_ID,
+    transport: createHttpTransport({
+      baseUrl: '/api/sync',
+      getHeaders: () => ({ 'x-user-id': ACTOR_ID }),
+    }),
+    tables: ['tasks'],
+    scopes: ['user:{user_id}'],
+    sync: {
+      realtime: false,
+      pollIntervalMs: 3000,
+    },
+  });
+
+  await client.sync();
+  return { db, client };
+}
+
+async function getRuntime(): Promise<DemoRuntime> {
+  if (!runtimePromise) {
+    runtimePromise = createRuntime();
+  }
+  return runtimePromise;
+}
+
+export async function initializeDemoSync(): Promise<void> {
+  await getRuntime();
+}
+
+export async function listTasks(): Promise<TasksTable[]> {
+  const runtime = await getRuntime();
+  return runtime.db
+    .selectFrom('tasks')
+    .selectAll()
+    .orderBy('server_version desc')
+    .execute();
+}
+
+export async function addTask(title: string): Promise<void> {
+  const runtime = await getRuntime();
+  await runtime.client.mutations.tasks.insert({
+    id: crypto.randomUUID(),
+    title,
+    completed: 0,
+    user_id: ACTOR_ID,
+    server_version: 0,
+  });
+  await runtime.client.sync();
+}
+
+export async function toggleTask(task: TasksTable): Promise<void> {
+  const runtime = await getRuntime();
+  await runtime.client.mutations.tasks.update(task.id, {
+    completed: task.completed === 1 ? 0 : 1,
+  });
+  await runtime.client.sync();
+}
+
+export async function removeTask(taskId: string): Promise<void> {
+  const runtime = await getRuntime();
+  await runtime.client.mutations.tasks.delete(taskId);
+  await runtime.client.sync();
+}
+
+export async function subscribeToTaskChanges(
+  callback: () => void
+): Promise<() => void> {
+  const runtime = await getRuntime();
+  const unsubscribeData = runtime.client.on('data:change', callback);
+  const unsubscribeSync = runtime.client.on('sync:complete', callback);
+
+  return () => {
+    unsubscribeData();
+    unsubscribeSync();
+  };
+}

package/templates/demo/src/server/index.ts.tpl

@@ -0,0 +1,58 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createBunSqliteDb } from '@syncular/dialect-bun-sqlite';
+import { runMigrations } from '@syncular/migrations';
+import { createServerHandler, ensureSyncSchema } from '@syncular/server';
+import { createSqliteServerDialect } from '@syncular/server-dialect-sqlite';
+import { createSyncServer } from '@syncular/server-hono';
+import { Hono } from 'hono';
+import { demoMigrations, type AppServerDb } from '../shared/db';
+
+const DATABASE_PATH = './data/server.sqlite';
+const PORT = Number(process.env.PORT ?? 8787);
+
+async function ensureDemoSchema() {
+  await mkdir(dirname(DATABASE_PATH), { recursive: true });
+
+  const db = createBunSqliteDb<AppServerDb>({ path: DATABASE_PATH });
+  const dialect = createSqliteServerDialect();
+  await ensureSyncSchema(db, dialect);
+  await runMigrations({
+    db,
+    migrations: demoMigrations,
+    trackingTable: 'sync_server_migration_state',
+  });
+
+  const tasksHandler = createServerHandler({
+    table: 'tasks',
+    scopes: ['user:{user_id}'],
+    resolveScopes: async (ctx) => ({ user_id: [ctx.actorId] }),
+  });
+
+  const { syncRoutes } = createSyncServer({
+    db,
+    dialect,
+    handlers: [tasksHandler],
+    authenticate: async (c) => {
+      const actorId = c.req.header('x-user-id') ?? 'demo-user';
+      return { actorId };
+    },
+  });
+
+  const app = new Hono();
+  app.get('/api/health', (c) =>
+    c.json({ ok: true, message: 'Syncular demo server running' })
+  );
+  app.route('/api/sync', syncRoutes);
+
+  return app;
+}
+
+const app = await ensureDemoSchema();
+
+Bun.serve({
+  port: PORT,
+  fetch: app.fetch,
+});
+
+console.log(`Syncular demo server listening on http://localhost:${PORT}`);

package/templates/demo/src/shared/db.ts.tpl

@@ -0,0 +1,40 @@
+import type { SyncClientDb } from '@syncular/client';
+import { defineMigrations } from '@syncular/migrations';
+import type { SyncCoreDb } from '@syncular/server';
+
+export interface TasksTable {
+  id: string;
+  title: string;
+  completed: number;
+  user_id: string;
+  server_version: number;
+}
+
+export interface AppClientDb extends SyncClientDb {
+  tasks: TasksTable;
+}
+
+export interface AppServerDb extends SyncCoreDb {
+  tasks: TasksTable;
+}
+
+export const demoMigrations = defineMigrations<AppServerDb>({
+  v1: async (db) => {
+    await db.schema
+      .createTable('tasks')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .addColumn('completed', 'integer', (col) => col.notNull().defaultTo(0))
+      .addColumn('user_id', 'text', (col) => col.notNull())
+      .addColumn('server_version', 'integer', (col) => col.notNull().defaultTo(1))
+      .execute();
+
+    await db.schema
+      .createIndex('idx_tasks_user_id')
+      .ifNotExists()
+      .on('tasks')
+      .columns(['user_id'])
+      .execute();
+  },
+});

package/templates/demo/syncular-migrate.ts.tpl

@@ -0,0 +1,79 @@
+/**
+ * Migration adapter for the generated Syncular demo.
+ */
+
+import { createBunSqliteDb } from '@syncular/dialect-bun-sqlite';
+import { getSchemaVersion, runMigrations } from '@syncular/migrations';
+import type { Kysely } from 'kysely';
+import { demoMigrations, type AppServerDb } from '../src/shared/db';
+
+function createDb(): Kysely<AppServerDb> {
+  return createBunSqliteDb<AppServerDb>({ path: './data/server.sqlite' });
+}
+
+export const <%= it.ADAPTER_EXPORT %> = {
+  async status() {
+    const db = createDb();
+    try {
+      const currentVersion = await getSchemaVersion(
+        db,
+        'sync_server_migration_state'
+      );
+      const targetVersion = demoMigrations.currentVersion;
+      const pendingVersions = demoMigrations.migrations
+        .map((migration) => migration.version)
+        .filter((version) => version > currentVersion);
+
+      return {
+        currentVersion,
+        targetVersion,
+        pendingVersions,
+        trackingTable: 'sync_server_migration_state',
+      };
+    } finally {
+      await db.destroy();
+    }
+  },
+
+  async up(options: {
+    onChecksumMismatch: 'error' | 'reset';
+    dryRun: boolean;
+  }) {
+    const db = createDb();
+    try {
+      const currentVersion = await getSchemaVersion(
+        db,
+        'sync_server_migration_state'
+      );
+
+      if (options.dryRun) {
+        const pendingVersions = demoMigrations.migrations
+          .map((migration) => migration.version)
+          .filter((version) => version > currentVersion);
+
+        return {
+          appliedVersions: pendingVersions,
+          currentVersion,
+          wasReset: false,
+          dryRun: true,
+        };
+      }
+
+      const result = await runMigrations({
+        db,
+        migrations: demoMigrations,
+        trackingTable: 'sync_server_migration_state',
+        onChecksumMismatch: options.onChecksumMismatch,
+      });
+
+      return {
+        appliedVersions: result.applied,
+        currentVersion: result.currentVersion,
+        wasReset: result.wasReset,
+        dryRun: false,
+      };
+    } finally {
+      await db.destroy();
+    }
+  },
+};

package/templates/demo/syncular-typegen.ts.tpl

@@ -0,0 +1,23 @@
+/**
+ * Generate database types from demo migrations.
+ */
+
+import { generateTypes } from '@syncular/typegen';
+import { demoMigrations } from '../src/shared/db';
+
+async function main() {
+  const result = await generateTypes({
+    migrations: demoMigrations,
+    output: './src/shared/types.generated.ts',
+    extendsSyncClientDb: true,
+  });
+
+  console.log(`Generated ${result.outputPath}`);
+  console.log(`Schema version: ${result.currentVersion}`);
+  console.log(`Tables: ${result.tableCount}`);
+}
+
+main().catch((error) => {
+  console.error('Type generation failed:', error);
+  process.exit(1);
+});

package/templates/demo/syncular.config.json.tpl

@@ -0,0 +1,7 @@
+{
+  "mode": "demo",
+  "migrate": {
+    "adapter": "<%= it.ADAPTER_PATH %>",
+    "export": "<%= it.ADAPTER_EXPORT %>"
+  }
+}

package/templates/demo/tsconfig.json.tpl

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["bun", "vite/client"]
+  },
+  "include": ["src", "scripts", "vite.config.ts"]
+}

package/templates/demo/vite.config.ts.tpl

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  worker: {
+    format: 'es',
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': 'http://localhost:8787',
+    },
+  },
+});

package/templates/libraries/syncular-electron.ts.tpl

@@ -0,0 +1,36 @@
+/**
+ * Syncular Electron module scaffold.
+ *
+ * Dialect: <%= it.ELECTRON_DIALECT_LABEL %>
+ */
+
+import { createClient } from '@syncular/client';
+import type { SyncClientDb } from '@syncular/client';
+<%= it.ELECTRON_DIALECT_IMPORT %>
+import { createHttpTransport } from '@syncular/transport-http';
+
+export const clientDialect = '<%= it.ELECTRON_DIALECT %>';
+
+export function createClientDb<DB extends SyncClientDb>() {
+  <%= it.ELECTRON_DB_FACTORY_LINE %>
+}
+
+export async function createSyncularElectronClient<DB extends SyncClientDb>(args: {
+  actorId: string;
+  token: string;
+  baseUrl: string;
+  tables: string[];
+  scopes: string[];
+}) {
+  const db = createClientDb<DB>();
+  return createClient({
+    db,
+    actorId: args.actorId,
+    transport: createHttpTransport({
+      baseUrl: args.baseUrl,
+      getHeaders: () => ({ Authorization: `Bearer ${args.token}` }),
+    }),
+    tables: args.tables,
+    scopes: args.scopes,
+  });
+}

package/templates/libraries/syncular-expo.ts.tpl

@@ -0,0 +1,32 @@
+/**
+ * Syncular Expo module scaffold.
+ */
+
+import { createClient } from '@syncular/client';
+import type { SyncClientDb } from '@syncular/client';
+import { createExpoSqliteDb } from '@syncular/dialect-expo-sqlite';
+import { createHttpTransport } from '@syncular/transport-http';
+
+export function createClientDb<DB extends SyncClientDb>() {
+  return createExpoSqliteDb<DB>({ databaseName: 'app.sqlite' });
+}
+
+export async function createSyncularExpoClient<DB extends SyncClientDb>(args: {
+  actorId: string;
+  token: string;
+  baseUrl: string;
+  tables: string[];
+  scopes: string[];
+}) {
+  const db = createClientDb<DB>();
+  return createClient({
+    db,
+    actorId: args.actorId,
+    transport: createHttpTransport({
+      baseUrl: args.baseUrl,
+      getHeaders: () => ({ Authorization: `Bearer ${args.token}` }),
+    }),
+    tables: args.tables,
+    scopes: args.scopes,
+  });
+}