create-syncular-app 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # create-syncular-app
 
-The `create-syncular-app` scaffolder — the create-app experience for syncular v2.
+The `create-syncular-app` scaffolder — the create-app experience for syncular.
 
 ```sh
 bun create syncular-app my-app            # prompts for the template
@@ -21,9 +21,9 @@ bunx create-syncular-app my-app --template web
 
 > **Third-template candidate: `react`.** [`apps/demo-react`](../../apps/demo-react)
 > is the ready-made source for a hooks-based template — `@syncular/react`
-> (`SyncProvider` + `useTypedQuery` + `useMutation` + `useSyncStatus` +
-> `useWindow`) over the same worker + OPFS core, with the Kysely-typed read
-> layer wired. Slim it the way `web` slims `apps/demo` (drop the three-list
+> (`SyncProvider` + `useQuery` + `useRawSql` + `useMutation` + `useSyncStatus` +
+> `useWindow`) over the same worker + OPFS core, with the named-query read
+> tier wired. Slim it the way `web` slims `apps/demo` (drop the three-list
 > seed to one, keep one hook of each kind) and add it here when a React
 > template is wanted. Not built yet — noted so the shape is on record.
 
@@ -42,7 +42,7 @@ ranges:
   repo's workspace.
 - **default** (a normal `bunx create-…` run): rewrite to
   `PUBLISHED_DEPENDENCY_RANGE` (`src/constants.ts`). **Today that constant is
-  *also* `workspace:*`** because the v2 packages are unpublished and
+  *also* `workspace:*`** because the workspace packages are unpublished and
   version-less (all `private`, no `version` — TODO 6.3), so there is no honest
   semver range yet. The CLI **warns loudly** in this case: a `bun install`
   outside the repo cannot resolve the deps until publishing lands. When the

package/dist/cli.js

@@ -127,12 +127,6 @@ export async function runCli(argv = process.argv.slice(2)) {
         });
         const displayDir = relative(process.cwd(), result.targetDir) || '.';
         console.log(`[${CREATE_BIN}] scaffolded ${result.packageName} (template: ${template}) into ${displayDir}`);
-        if (!result.local) {
-            console.warn(`[${CREATE_BIN}] note: the ${PRODUCT_NAME} v2 packages are not published yet, so\n` +
-                `  the app's dependencies are still workspace:* ranges. Run inside this repo\n` +
-                `  (or pass --local) until publishing lands (TODO 6.3). Use \`${CLI_BIN} generate\`\n` +
-                '  to (re)generate the typed schema.');
-        }
         console.log(nextSteps(displayDir, template));
         return 0;
     }

package/dist/constants.d.ts

@@ -20,19 +20,7 @@ export declare const PRODUCT_NAME = "syncular";
  * question answerable from one spot.
  */
 export declare const WORKSPACE_PACKAGES: readonly ["@syncular/core", "@syncular/server", "@syncular/server-hono", "@syncular/client", "@syncular/typegen"];
-/**
- * The dependency range written into a scaffolded app's package.json when NOT
- * scaffolding for in-tree testing (see {@link scaffoldApp}'s `local` flag).
- *
- * The v2 packages are unpublished and version-less today (all `private`, no
- * `version` field — final identity + the release train is TODO 6.3). Until
- * they publish there is no honest semver range to point at, so this is a
- * `workspace:*`-shaped LOCAL default too, and the CLI warns loudly that a
- * published install is not yet possible. When the packages ship, replace this
- * with `^<version>` (or teach the CLI to read the published version) — one
- * edit, here.
- */
-export declare const PUBLISHED_DEPENDENCY_RANGE = "workspace:*";
+export declare const PUBLISHED_DEPENDENCY_RANGE: string;
 /** Placeholder tokens substituted verbatim during scaffold (dumb + greppable). */
 export declare const PLACEHOLDER: {
     /** Replaced by the chosen project name in package.json/README. */

package/dist/constants.js

@@ -1,3 +1,4 @@
+import { createRequire } from 'node:module';
 /**
  * The ONE place naming lives (TODO 6.3 is a product decision — final package
  * identity is not settled). Every user-visible name the scaffolder emits comes
@@ -30,15 +31,13 @@ export const WORKSPACE_PACKAGES = [
  * The dependency range written into a scaffolded app's package.json when NOT
  * scaffolding for in-tree testing (see {@link scaffoldApp}'s `local` flag).
  *
- * The v2 packages are unpublished and version-less today (all `private`, no
- * `version` field — final identity + the release train is TODO 6.3). Until
- * they publish there is no honest semver range to point at, so this is a
- * `workspace:*`-shaped LOCAL default too, and the CLI warns loudly that a
- * published install is not yet possible. When the packages ship, replace this
- * with `^<version>` (or teach the CLI to read the published version) — one
- * edit, here.
+ * Derived from this package's own version: the release train bumps every
+ * @syncular/* package in lockstep, so `^<own version>` is always an honest
+ * published range — no constant to remember on each release.
  */
-export const PUBLISHED_DEPENDENCY_RANGE = 'workspace:*';
+const ownVersion = createRequire(import.meta.url)('../package.json')
+    .version;
+export const PUBLISHED_DEPENDENCY_RANGE = `^${ownVersion}`;
 /** Placeholder tokens substituted verbatim during scaffold (dumb + greppable). */
 export const PLACEHOLDER = {
     /** Replaced by the chosen project name in package.json/README. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-syncular-app",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Scaffold a new Syncular app: `create-syncular-app`",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -31,7 +31,7 @@
   "exports": {
     ".": {
       "bun": "./src/index.ts",
-      "browser": "./src/index.ts",
+      "browser": "./dist/index.js",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"

package/src/cli.ts

@@ -149,14 +149,6 @@ export async function runCli(argv = process.argv.slice(2)): Promise<number> {
     console.log(
       `[${CREATE_BIN}] scaffolded ${result.packageName} (template: ${template}) into ${displayDir}`,
     );
-    if (!result.local) {
-      console.warn(
-        `[${CREATE_BIN}] note: the ${PRODUCT_NAME} v2 packages are not published yet, so\n` +
-          `  the app's dependencies are still workspace:* ranges. Run inside this repo\n` +
-          `  (or pass --local) until publishing lands (TODO 6.3). Use \`${CLI_BIN} generate\`\n` +
-          '  to (re)generate the typed schema.',
-      );
-    }
     console.log(nextSteps(displayDir, template));
     return 0;
   } catch (error) {

package/src/constants.ts

@@ -1,3 +1,5 @@
+import { createRequire } from 'node:module';
+
 /**
  * The ONE place naming lives (TODO 6.3 is a product decision — final package
  * identity is not settled). Every user-visible name the scaffolder emits comes
@@ -36,15 +38,14 @@ export const WORKSPACE_PACKAGES = [
  * The dependency range written into a scaffolded app's package.json when NOT
  * scaffolding for in-tree testing (see {@link scaffoldApp}'s `local` flag).
  *
- * The v2 packages are unpublished and version-less today (all `private`, no
- * `version` field — final identity + the release train is TODO 6.3). Until
- * they publish there is no honest semver range to point at, so this is a
- * `workspace:*`-shaped LOCAL default too, and the CLI warns loudly that a
- * published install is not yet possible. When the packages ship, replace this
- * with `^<version>` (or teach the CLI to read the published version) — one
- * edit, here.
+ * Derived from this package's own version: the release train bumps every
+ * @syncular/* package in lockstep, so `^<own version>` is always an honest
+ * published range — no constant to remember on each release.
  */
-export const PUBLISHED_DEPENDENCY_RANGE = 'workspace:*';
+const ownVersion = createRequire(import.meta.url)('../package.json')
+  .version as string;
+
+export const PUBLISHED_DEPENDENCY_RANGE = `^${ownVersion}`;
 
 /** Placeholder tokens substituted verbatim during scaffold (dumb + greppable). */
 export const PLACEHOLDER = {

package/template/minimal/README.md

@@ -1,6 +1,6 @@
 # __PROJECT_NAME__
 
-A minimal [syncular](https://github.com/bkniffler/syncular) v2 app: a schema, a
+A minimal [syncular](https://github.com/bkniffler/syncular) app: a schema, a
 ~30-line server, and two client cores that converge — all in a terminal, no
 browser. This is the shape you grow a real backend from.
 

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

@@ -2,7 +2,7 @@
  * 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
+ * test`, AND (because the template lives in the workspace) in the repo test sweep — so
  * the template itself cannot rot.
  */
 import { afterAll, beforeAll, expect, test } from 'bun:test';

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

@@ -25,31 +25,25 @@ export const schema = {
 /** One notes row (§2.4 column order). */
 export interface NotesRow {
   id: string;
-  list_id: string;
+  listId: string;
   body: string;
-  updated_at_ms: number;
+  updatedAtMs: number;
 }
 
 /** Insert shape: nullable columns may be omitted. */
 export interface NotesInsert {
   id: string;
-  list_id: string;
+  listId: string;
   body: string;
-  updated_at_ms: number;
+  updatedAtMs: number;
 }
 
 /** Update shape: primary key required, all other columns optional. */
 export interface NotesUpdate {
   id: string;
-  list_id?: string;
+  listId?: string;
   body?: string;
-  updated_at_ms?: number;
-}
-
-/** Kysely `Database` interface (table → Row); the generic for
- *  @syncular/kysely's SyncularDialect. */
-export interface Database {
-  notes: NotesRow;
+  updatedAtMs?: number;
 }
 
 export interface NotesInListParams {

package/template/web/README.md

@@ -1,6 +1,6 @@
 # __PROJECT_NAME__
 
-A [syncular](https://github.com/bkniffler/syncular) v2 browser app: a Hono sync
+A [syncular](https://github.com/bkniffler/syncular) 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.
@@ -20,8 +20,10 @@ 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.
+> One core per origin: the first tab leads (owns the worker, the OPFS
+> database, and the socket) and every further tab follows it over a
+> BroadcastChannel — same API, one sync loop. Use two windows/profiles to
+> see two separate clients converge.
 
 ## Layout
 

package/template/web/src/frontend/main.ts

@@ -6,15 +6,15 @@
  * query/mutate/subscribe messages and re-renders. This is the real browser
  * shape; grow your app from here.
  *
- * Open two browser windows on the same URL to watch them converge over the
- * realtime socket. (One core per origin: a second TAB gets a clear not-leader
- * error — multi-tab followers are a roadmap item. Separate windows/profiles or
- * the two-window trick show convergence today.)
+ * One core per origin: the first tab wins the leader lock and spawns the
+ * worker; every further tab becomes a follower proxying the same API to the
+ * leader over a BroadcastChannel (and promotes in place when the leader
+ * closes). Open two tabs — or two browser windows for two separate actors —
+ * to watch them converge over the realtime socket.
  */
 import {
   ClientSyncError,
   createSyncClientHandle,
-  NOT_LEADER_CODE,
   type SqlRow,
 } from '@syncular/client';
 import { schema, todoListSubscription } from '../syncular.generated';
@@ -57,14 +57,6 @@ async function main(): Promise<void> {
     onSynced: () => void refresh(),
   });
 
-  if (!handle.isLeader) {
-    throw new ClientSyncError(
-      NOT_LEADER_CODE,
-      'another tab already owns this app’s core — close it first ' +
-        '(multi-tab followers are a roadmap item).',
-    );
-  }
-
   await handle.subscribe({
     id: 'todos',
     table: 'todos',

package/template/web/src/server.ts

@@ -58,6 +58,10 @@ const build = await Bun.build({
     join(import.meta.dir, 'frontend', 'worker.ts'),
   ],
   target: 'browser',
+  // Resolve syncular packages through their `bun` condition (TS source,
+  // shipped in the npm tarballs) — bun transpiles it, and a `--local`
+  // workspace link works without a dist build.
+  conditions: ['bun'],
   sourcemap: 'inline',
   external: ['@sqlite.org/sqlite-wasm'],
 });

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

@@ -27,37 +27,31 @@ export const schema = {
 /** One todos row (§2.4 column order). */
 export interface TodosRow {
   id: string;
-  list_id: string;
+  listId: string;
   title: string;
   done: boolean;
   position: number;
-  updated_at_ms: number;
+  updatedAtMs: number;
 }
 
 /** Insert shape: nullable columns may be omitted. */
 export interface TodosInsert {
   id: string;
-  list_id: string;
+  listId: string;
   title: string;
   done: boolean;
   position: number;
-  updated_at_ms: number;
+  updatedAtMs: number;
 }
 
 /** Update shape: primary key required, all other columns optional. */
 export interface TodosUpdate {
   id: string;
-  list_id?: string;
+  listId?: string;
   title?: string;
   done?: boolean;
   position?: number;
-  updated_at_ms?: number;
-}
-
-/** Kysely `Database` interface (table → Row); the generic for
- *  @syncular/kysely's SyncularDialect. */
-export interface Database {
-  todos: TodosRow;
+  updatedAtMs?: number;
 }
 
 export interface TodoListParams {