create-syncular-app 0.1.3 → 0.2.1

package/template/minimal/src/clients.ts

@@ -0,0 +1,54 @@
+/**
+ * Two clients, one server, terminal-visible convergence.
+ *
+ * A writes a note; B — a completely independent client core with its own local
+ * database — bootstraps, syncs, and reads the same row back. This is the proof
+ * that sync works end to end, no browser required.
+ *
+ * Run the server first (`bun run server`), then this script (`bun run
+ * clients`). Both talk real HTTP to http://localhost:8787.
+ */
+import { makeClient } from './make-client';
+
+const BASE_URL = process.env.SERVER_URL ?? 'http://localhost:8787';
+const LIST_ID = 'welcome';
+
+const a = makeClient(BASE_URL, 'client-a');
+const b = makeClient(BASE_URL, 'client-b');
+await a.start();
+await b.start();
+
+// Both clients subscribe to the same list (the requested scope).
+const sub = { id: 'notes', table: 'notes', scopes: { list_id: [LIST_ID] } };
+a.subscribe(sub);
+b.subscribe(sub);
+
+// A writes a note. mutate() records it locally + queues it for the next push.
+const now = Date.now();
+a.mutate([
+  {
+    table: 'notes',
+    op: 'upsert',
+    values: {
+      id: 'note-1',
+      list_id: LIST_ID,
+      body: 'Hello from client A',
+      updated_at_ms: now,
+    },
+  },
+]);
+console.log('A: wrote note-1, pushing…');
+await a.syncUntilIdle(); // push A's outbox to the server
+
+console.log('B: syncing…');
+await b.syncUntilIdle(); // B bootstraps the list and applies A's note
+
+const rows = b.query('SELECT id, body FROM notes ORDER BY id');
+console.log('B sees:', rows);
+
+const converged = rows.length === 1 && rows[0]?.body === 'Hello from client A';
+console.log(converged ? '\n✓ converged' : '\n✗ did NOT converge');
+
+await a.close();
+await b.close();
+process.exit(converged ? 0 : 1);

package/template/minimal/src/make-client.ts

@@ -0,0 +1,26 @@
+/**
+ * Construct one SyncClient against the running server.
+ *
+ * The client core is plain library code — it runs on whatever database backend
+ * and transport you give it. In the browser that is sqlite-wasm on OPFS + a
+ * WebSocket; here it is bun:sqlite + fetch, so the whole thing runs in a
+ * terminal with no browser. Everything else is identical to a web build (see
+ * the `web` template for the browser story).
+ */
+import {
+  httpSegmentDownloader,
+  httpSyncTransport,
+  SyncClient,
+} from '@syncular/client';
+import { openBunDatabase } from '@syncular/client/bun';
+import { schema } from './syncular.generated';
+
+export function makeClient(baseUrl: string, clientId: string): SyncClient {
+  return new SyncClient({
+    database: openBunDatabase(), // in-memory; pass a path to persist
+    schema,
+    clientId,
+    transport: httpSyncTransport(`${baseUrl}/sync`),
+    segments: httpSegmentDownloader(`${baseUrl}/segments`),
+  });
+}

package/template/minimal/src/server.ts

@@ -0,0 +1,39 @@
+/**
+ * The whole sync backend in one Bun process.
+ *
+ * `createSyncularHono` mounts the protocol routes (POST /sync, GET
+ * /segments/:id, PUT|GET /blobs/:id) over the framework-free
+ * `@syncular/server` core. Storage is bun:sqlite; the server manages its
+ * own `sync_*` tables — the app migration (migrations/0001_initial) only feeds
+ * typegen the schema SHAPE, it is never run here.
+ *
+ * EDIT FIRST: `resolveScopes` is the whole authorization story. It runs in
+ * YOUR backend, next to YOUR auth, and decides which scope values an actor may
+ * see. Here the demo actor may see every list (`['*']`); a real backend
+ * returns the lists the authenticated user belongs to. `authenticate` is where
+ * you plug in your real session/token check.
+ */
+import {
+  MemorySegmentStore,
+  SqliteServerStorage,
+  type SyncServerConfig,
+} from '@syncular/server';
+import { createSyncularHono } from '@syncular/server-hono';
+import { schema } from './syncular.generated';
+
+const config: SyncServerConfig = {
+  schema,
+  storage: new SqliteServerStorage(process.env.DB_PATH ?? ':memory:'),
+  segments: new MemorySegmentStore(),
+  resolveScopes: () => ({ list_id: ['*'] }),
+};
+
+const app = createSyncularHono({
+  config,
+  // Replace with your real auth: return { actorId, partition } or null (401).
+  authenticate: async () => ({ actorId: 'demo-user', partition: 'demo' }),
+});
+
+const port = Number(process.env.PORT ?? 8787);
+Bun.serve({ port, fetch: app.fetch });
+console.log(`sync server: http://localhost:${port}`);

package/template/minimal/src/smoke.test.ts

@@ -0,0 +1,70 @@
+/**
+ * The template's own smoke test: boots the real Hono server on an ephemeral
+ * port and drives two independent bun:sqlite client cores through it over real
+ * HTTP, asserting they converge. This runs in the scaffolded app's own `bun
+ * test`, AND (because the template lives in the workspace) in the v2 sweep — so
+ * the template itself cannot rot.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import {
+  MemorySegmentStore,
+  SqliteServerStorage,
+  type SyncServerConfig,
+} from '@syncular/server';
+import { createSyncularHono } from '@syncular/server-hono';
+import { makeClient } from './make-client';
+import { schema } from './syncular.generated';
+
+let server: ReturnType<typeof Bun.serve>;
+let baseUrl: string;
+
+beforeAll(() => {
+  const config: SyncServerConfig = {
+    schema,
+    storage: new SqliteServerStorage(':memory:'),
+    segments: new MemorySegmentStore(),
+    resolveScopes: () => ({ list_id: ['*'] }),
+  };
+  const app = createSyncularHono({
+    config,
+    authenticate: async () => ({ actorId: 'demo-user', partition: 'demo' }),
+  });
+  server = Bun.serve({ port: 0, fetch: app.fetch });
+  baseUrl = `http://localhost:${server.port}`;
+});
+
+afterAll(() => {
+  server.stop(true);
+});
+
+test('two clients converge through the server', async () => {
+  const a = makeClient(baseUrl, 'client-a');
+  const b = makeClient(baseUrl, 'client-b');
+  await a.start();
+  await b.start();
+
+  const sub = { id: 'notes', table: 'notes', scopes: { list_id: ['welcome'] } };
+  a.subscribe(sub);
+  b.subscribe(sub);
+
+  a.mutate([
+    {
+      table: 'notes',
+      op: 'upsert',
+      values: {
+        id: 'note-1',
+        list_id: 'welcome',
+        body: 'Hello from client A',
+        updated_at_ms: Date.now(),
+      },
+    },
+  ]);
+  await a.syncUntilIdle();
+  await b.syncUntilIdle();
+
+  const rows = b.query('SELECT id, body FROM notes ORDER BY id');
+  expect(rows).toEqual([{ id: 'note-1', body: 'Hello from client A' }]);
+
+  await a.close();
+  await b.close();
+});

package/template/minimal/src/syncular.generated.ts

@@ -0,0 +1,66 @@
+// Generated by @syncular/typegen — DO NOT EDIT.
+// irVersion: 1
+// irHash: sha256:e2e39c94ce6c13720e1f1579e2523d460fd6bb3fea2f8eaaa114305b7aa332ba
+
+/** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */
+export const schema = {
+  version: 1,
+  tables: [
+    {
+      name: 'notes',
+      columns: [
+        { name: 'id', type: 'string', nullable: false },
+        { name: 'list_id', type: 'string', nullable: false },
+        { name: 'body', type: 'string', nullable: false },
+        { name: 'updated_at_ms', type: 'integer', nullable: false },
+      ],
+      primaryKey: 'id',
+      scopes: [
+        { pattern: 'list:{list_id}', column: 'list_id' },
+      ],
+    },
+  ],
+} as const;
+
+/** One notes row (§2.4 column order). */
+export interface NotesRow {
+  id: string;
+  list_id: string;
+  body: string;
+  updated_at_ms: number;
+}
+
+/** Insert shape: nullable columns may be omitted. */
+export interface NotesInsert {
+  id: string;
+  list_id: string;
+  body: string;
+  updated_at_ms: number;
+}
+
+/** Update shape: primary key required, all other columns optional. */
+export interface NotesUpdate {
+  id: string;
+  list_id?: string;
+  body?: string;
+  updated_at_ms?: number;
+}
+
+/** Kysely `Database` interface (table → Row); the generic for
+ *  @syncular/kysely's SyncularDialect. */
+export interface Database {
+  notes: NotesRow;
+}
+
+export interface NotesInListParams {
+  listId: string;
+}
+
+/** Requested-scope template for the 'notesInList' subscription. */
+export const notesInListSubscription = {
+  name: 'notesInList',
+  table: 'notes',
+  scopes: (params: NotesInListParams): Record<string, string[]> => ({
+    list_id: [params.listId],
+  }),
+} as const;

package/template/minimal/syncular.ir.json

@@ -0,0 +1,66 @@
+{
+  "irVersion": 1,
+  "schemaVersion": 1,
+  "schemaVersions": [
+    {
+      "version": 1,
+      "migrations": [
+        "0001_initial"
+      ]
+    }
+  ],
+  "tables": [
+    {
+      "name": "notes",
+      "primaryKey": "id",
+      "columns": [
+        {
+          "name": "id",
+          "type": "string",
+          "nullable": false
+        },
+        {
+          "name": "list_id",
+          "type": "string",
+          "nullable": false
+        },
+        {
+          "name": "body",
+          "type": "string",
+          "nullable": false
+        },
+        {
+          "name": "updated_at_ms",
+          "type": "integer",
+          "nullable": false
+        }
+      ],
+      "scopes": [
+        {
+          "pattern": "list:{list_id}",
+          "variable": "list_id",
+          "column": "list_id"
+        }
+      ],
+      "extensions": {}
+    }
+  ],
+  "subscriptions": [
+    {
+      "name": "notesInList",
+      "table": "notes",
+      "scopes": [
+        {
+          "variable": "list_id",
+          "values": [
+            {
+              "kind": "parameter",
+              "name": "listId"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "extensions": {}
+}

package/template/minimal/syncular.json

@@ -0,0 +1,17 @@
+{
+  "manifestVersion": 1,
+  "migrations": "./migrations",
+  "output": {
+    "ir": "./syncular.ir.json",
+    "module": "./src/syncular.generated.ts"
+  },
+  "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
+  "tables": [{ "name": "notes", "scopes": ["list:{list_id}"] }],
+  "subscriptions": [
+    {
+      "name": "notesInList",
+      "table": "notes",
+      "scopes": { "list_id": ["{listId}"] }
+    }
+  ]
+}

package/template/minimal/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "customConditions": ["bun"],
+    "lib": ["ES2023"],
+    "types": ["bun"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/template/web/README.md

@@ -0,0 +1,63 @@
+# __PROJECT_NAME__
+
+A [syncular](https://github.com/bkniffler/syncular) v2 browser app: a Hono sync
+server, a WebSocket realtime channel, and a single-pane todo UI whose whole
+client core runs in a Web Worker on OPFS. Everything is served by one Bun
+process.
+
+## Run it
+
+```sh
+bun install
+bun run generate          # syncular.json + migrations → src/syncular.generated.ts
+bun run dev               # http://localhost:8787
+```
+
+Open the URL, add todos, toggle "Go offline" and keep editing — the outbox
+counter grows and drains with idempotent retry on reconnect. Open a second
+browser window on the same URL to watch them converge over the realtime socket.
+
+`bun test` runs a server-level convergence smoke test (the browser UI is
+covered by `tsc`).
+
+> One core per origin: a second *tab* gets a clear not-leader error (multi-tab
+> followers are a roadmap item). Use two windows/profiles to see two clients.
+
+## Layout
+
+| File | What it is |
+|---|---|
+| `syncular.json` + `migrations/` | The schema manifest and SQL — typegen's input |
+| `src/syncular.generated.ts` | Generated by `syncular generate` (committed) |
+| `src/server.ts` | Sync server + WebSocket + static frontend, one Bun process |
+| `src/frontend/main.ts` | The single-pane UI, driving a worker core via RPC |
+| `src/frontend/worker.ts` | The sync worker: the whole client core on OPFS |
+| `src/frontend/index.html` | The page shell |
+| `src/smoke.test.ts` | Server-level convergence smoke test (`bun test`) |
+
+## What to edit first
+
+1. **`src/server.ts` → `resolveScopes`** — the whole authorization story. It
+   runs in your backend next to your auth. The starter returns `['*']`; a real
+   one returns the scope values the authenticated actor may see.
+2. **`src/server.ts` → `authenticate`** — plug in your real session/token
+   check; return `{ actorId, partition }` or `null` for a 401.
+3. **`src/frontend/main.ts`** — the UI. It queries and mutates through the
+   worker handle; grow it into your app.
+4. **`migrations/` + `syncular.json`** — add tables and scopes, then
+   `bun run generate`.
+
+## How the frontend is served
+
+`src/server.ts` builds two bundles with `Bun.build` at startup — `/app.js` (the
+page) and `/worker.js` (the sync worker). Module workers do not inherit the
+page's import map, so the `@sqlite.org/sqlite-wasm` bare specifier is rewritten
+to the served `/vendor/sqlite-wasm/` path in both. For production you would
+build these ahead of time and serve them statically.
+
+## Next
+
+- Want a terminal-only starting point? Scaffold the `minimal` template
+  (`bun create syncular-app my-app --template minimal`).
+- The [docs](https://github.com/bkniffler/syncular) explain scopes, conflicts,
+  bootstrap, realtime, and blobs.

package/template/web/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+*.log
+.DS_Store
+*.sqlite
+*.sqlite-*

package/template/web/migrations/0001_initial/up.sql

@@ -0,0 +1,11 @@
+-- Your schema, one table to start. typegen reads this to derive the schema
+-- SHAPE (column types, primary key); the server manages its own sync_* tables
+-- and never runs this migration.
+CREATE TABLE todos (
+  id TEXT PRIMARY KEY,
+  list_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  done BOOLEAN NOT NULL,
+  position INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+);

package/template/web/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/server.ts",
+    "generate": "syncular generate --manifest-dir .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
+    "@syncular/core": "workspace:*",
+    "@syncular/server": "workspace:*",
+    "@syncular/server-hono": "workspace:*",
+    "@syncular/client": "workspace:*"
+  },
+  "devDependencies": {
+    "@syncular/typegen": "workspace:*",
+    "@types/bun": "latest",
+    "typescript": "^5.9.0"
+  }
+}

package/template/web/src/frontend/index.html

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>__PROJECT_NAME__</title>
+  <style>
+    :root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, sans-serif; }
+    body { margin: 0; padding: 2rem; max-width: 32rem; margin-inline: auto; }
+    header { display: flex; align-items: baseline; gap: 0.75rem; flex-wrap: wrap; margin-bottom: 1rem; }
+    header h1 { font-size: 1.2rem; margin: 0; }
+    .badge { font-size: 0.7rem; padding: 0.1rem 0.45rem; border-radius: 999px; border: 1px solid currentColor; opacity: 0.7; }
+    #status { font-size: 0.8rem; opacity: 0.7; min-height: 1.1em; margin: 0 0 1rem; }
+    form { display: flex; gap: 0.5rem; margin-bottom: 1rem; }
+    form input { flex: 1; padding: 0.4rem 0.6rem; }
+    ul { list-style: none; margin: 0; padding: 0; }
+    li { display: flex; align-items: center; gap: 0.6rem; padding: 0.4rem 0; border-top: 1px solid color-mix(in srgb, currentColor 15%, transparent); }
+    li .title { flex: 1; }
+    li.done .title { text-decoration: line-through; opacity: 0.55; }
+    button { cursor: pointer; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>__PROJECT_NAME__</h1>
+    <span id="outbox" class="badge">outbox 0</span>
+    <button id="offline-btn">Go offline</button>
+  </header>
+  <p id="status">starting…</p>
+  <form id="add-form">
+    <input id="add-input" placeholder="Add a todo…" autocomplete="off" />
+    <button type="submit">Add</button>
+  </form>
+  <ul id="todos"></ul>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>