@korajs/cli 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/index.d.cts

@@ -59,6 +59,63 @@ declare class DevServerError extends KoraError {
     constructor(binary: string, searchPath: string);
 }
 
+/**
+ * Writes an AGENTS.md into an existing project so AI coding agents follow Kora
+ * conventions. Refuses to overwrite an existing file unless `--force` is passed.
+ */
+declare const agentsCommand: citty.CommandDef<{
+    force: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    framework: {
+        type: "string";
+        description: string;
+    };
+}>;
+
+/**
+ * Canonical AGENTS.md generator.
+ *
+ * `kora agents-md` writes this file into an existing project so AI coding agents
+ * (and humans) build Kora apps correctly instead of drifting to fetch calls,
+ * hand-written types, and loading spinners. New projects scaffolded with
+ * `create-kora-app` already ship an AGENTS.md; this command covers the manual
+ * setup path and lets existing projects regenerate the guidance on demand.
+ */
+/** UI framework whose bindings section the generated AGENTS.md documents. */
+type AgentsFramework = 'react' | 'vue' | 'svelte';
+/** All supported frameworks, for validation and help text. */
+declare const AGENTS_FRAMEWORKS: readonly AgentsFramework[];
+/**
+ * Narrows an arbitrary string to a supported {@link AgentsFramework}.
+ *
+ * @param value - Candidate framework identifier
+ * @returns `true` when `value` is one of the supported frameworks
+ */
+declare function isAgentsFramework(value: string): value is AgentsFramework;
+/**
+ * Detects the UI framework from a project's package manifest by looking for the
+ * matching `@korajs/*` binding package in dependencies or devDependencies.
+ *
+ * @param manifest - Parsed `package.json` contents
+ * @returns The detected framework, or `null` when no binding package is present
+ */
+declare function detectFrameworkFromManifest(manifest: unknown): AgentsFramework | null;
+/**
+ * Renders the full AGENTS.md document for the given framework.
+ *
+ * The body (golden rules, data API cheat sheet, conflict handling, sync notes,
+ * commands) is framework-agnostic; only the bindings section changes. File paths
+ * are described as conventions so the guidance is correct for both scaffolded and
+ * manually configured projects.
+ *
+ * @param framework - UI framework whose bindings to document
+ * @returns The complete AGENTS.md file contents, terminated with a trailing newline
+ */
+declare function generateAgentsMd(framework: AgentsFramework): string;
+
 /**
  * Generates TypeScript interfaces from a SchemaDefinition.
  * For each collection, produces three interfaces:
@@ -692,4 +749,4 @@ interface SyncProviderPresetOptions {
  */
 declare function applySyncProviderPreset(options: SyncProviderPresetOptions): Promise<void>;
 
-export { type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, determineTemplateFromSelections, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };
+export { AGENTS_FRAMEWORKS, type AgentsFramework, type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, agentsCommand, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, detectFrameworkFromManifest, determineTemplateFromSelections, generateAgentsMd, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAgentsFramework, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };

package/dist/index.d.ts

@@ -59,6 +59,63 @@ declare class DevServerError extends KoraError {
     constructor(binary: string, searchPath: string);
 }
 
+/**
+ * Writes an AGENTS.md into an existing project so AI coding agents follow Kora
+ * conventions. Refuses to overwrite an existing file unless `--force` is passed.
+ */
+declare const agentsCommand: citty.CommandDef<{
+    force: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    framework: {
+        type: "string";
+        description: string;
+    };
+}>;
+
+/**
+ * Canonical AGENTS.md generator.
+ *
+ * `kora agents-md` writes this file into an existing project so AI coding agents
+ * (and humans) build Kora apps correctly instead of drifting to fetch calls,
+ * hand-written types, and loading spinners. New projects scaffolded with
+ * `create-kora-app` already ship an AGENTS.md; this command covers the manual
+ * setup path and lets existing projects regenerate the guidance on demand.
+ */
+/** UI framework whose bindings section the generated AGENTS.md documents. */
+type AgentsFramework = 'react' | 'vue' | 'svelte';
+/** All supported frameworks, for validation and help text. */
+declare const AGENTS_FRAMEWORKS: readonly AgentsFramework[];
+/**
+ * Narrows an arbitrary string to a supported {@link AgentsFramework}.
+ *
+ * @param value - Candidate framework identifier
+ * @returns `true` when `value` is one of the supported frameworks
+ */
+declare function isAgentsFramework(value: string): value is AgentsFramework;
+/**
+ * Detects the UI framework from a project's package manifest by looking for the
+ * matching `@korajs/*` binding package in dependencies or devDependencies.
+ *
+ * @param manifest - Parsed `package.json` contents
+ * @returns The detected framework, or `null` when no binding package is present
+ */
+declare function detectFrameworkFromManifest(manifest: unknown): AgentsFramework | null;
+/**
+ * Renders the full AGENTS.md document for the given framework.
+ *
+ * The body (golden rules, data API cheat sheet, conflict handling, sync notes,
+ * commands) is framework-agnostic; only the bindings section changes. File paths
+ * are described as conventions so the guidance is correct for both scaffolded and
+ * manually configured projects.
+ *
+ * @param framework - UI framework whose bindings to document
+ * @returns The complete AGENTS.md file contents, terminated with a trailing newline
+ */
+declare function generateAgentsMd(framework: AgentsFramework): string;
+
 /**
  * Generates TypeScript interfaces from a SchemaDefinition.
  * For each collection, produces three interfaces:
@@ -692,4 +749,4 @@ interface SyncProviderPresetOptions {
  */
 declare function applySyncProviderPreset(options: SyncProviderPresetOptions): Promise<void>;
 
-export { type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, determineTemplateFromSelections, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };
+export { AGENTS_FRAMEWORKS, type AgentsFramework, type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, agentsCommand, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, detectFrameworkFromManifest, determineTemplateFromSelections, generateAgentsMd, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAgentsFramework, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };

package/dist/index.js

@@ -1,21 +1,26 @@
 #!/usr/bin/env node
 import {
+  AGENTS_FRAMEWORKS,
   DEPLOY_PLATFORMS,
   FlyAdapter,
   NodeFlyCommandRunner,
   NodeRailwayCommandRunner,
   RailwayAdapter,
   StubDeployAdapter,
+  agentsCommand,
   buildClient,
   bundleServer,
   createDeployAdapter,
   deployCommand,
+  detectFrameworkFromManifest,
+  generateAgentsMd,
   generateDeployPackageJson,
   generateDockerIgnore,
   generateDockerfile,
   generateFlyToml,
   generateRailwayJson,
   generateTypes,
+  isAgentsFramework,
   isDeployPlatform,
   readDeployState,
   resetDeployState,
@@ -27,7 +32,7 @@ import {
   writeDockerfileArtifact,
   writeFlyTomlArtifact,
   writeRailwayJsonArtifact
-} from "./chunk-EOWLAAIV.js";
+} from "./chunk-4IKCHRJ6.js";
 import {
   ClackPromptClient,
   CliError,
@@ -54,9 +59,10 @@ import {
   saveResolvedPreferences,
   shouldSavePreferences,
   validateProjectName
-} from "./chunk-B5YS4STN.js";
+} from "./chunk-G2PBYMMA.js";
 import "./chunk-5NI2FEQL.js";
 export {
+  AGENTS_FRAMEWORKS,
   ClackPromptClient,
   CliError,
   DEPLOY_PLATFORMS,
@@ -75,13 +81,16 @@ export {
   StubDeployAdapter,
   TEMPLATES,
   TEMPLATE_INFO,
+  agentsCommand,
   applySyncProviderPreset,
   buildClient,
   bundleServer,
   createDeployAdapter,
   createPromptClient,
   deployCommand,
+  detectFrameworkFromManifest,
   determineTemplateFromSelections,
+  generateAgentsMd,
   generateDeployPackageJson,
   generateDockerIgnore,
   generateDockerfile,
@@ -90,6 +99,7 @@ export {
   generateTypes,
   getCreatePreferencesOrDefault,
   getDefaultCreatePreferences,
+  isAgentsFramework,
   isAuthValue,
   isDatabaseProviderValue,
   isDatabaseValue,

package/dist/{spectator-manager-E2LH2P54.js → spectator-manager-FTH2NFSE.js}

@@ -39,6 +39,7 @@ var SpectatorManager = class {
         MergeEngine: (await import("@korajs/merge")).MergeEngine,
         SyncEngine: (await import("@korajs/sync")).SyncEngine,
         WebSocketTransport: (await import("@korajs/sync")).WebSocketTransport,
+        WebSocket: (await import("ws")).default,
         testing: await import("korajs/testing"),
         SimpleEventEmitter: (await import("@korajs/core/internal")).SimpleEventEmitter
       };
@@ -57,7 +58,9 @@ var SpectatorManager = class {
     const unsubscribeAudit = mods.testing.wireAuditPersistence(store, emitter);
     const syncStore = new mods.testing.MergeAwareSyncStore(store, mergeEngine, emitter);
     const engine = new mods.SyncEngine({
-      transport: new mods.WebSocketTransport(),
+      transport: new mods.WebSocketTransport({
+        WebSocketImpl: mods.WebSocket
+      }),
       store: syncStore,
       queueStorage: new mods.testing.StoreQueueStorage(adapter),
       syncState: new mods.testing.StoreSyncStatePersistence(store),
@@ -139,4 +142,4 @@ var SpectatorManager = class {
 export {
   SpectatorManager
 };
-//# sourceMappingURL=spectator-manager-E2LH2P54.js.map
+//# sourceMappingURL=spectator-manager-FTH2NFSE.js.map

package/dist/spectator-manager-FTH2NFSE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/studio/spectator-manager.ts"],"sourcesContent":["import { mkdtempSync, rmSync } from 'node:fs'\nimport { tmpdir } from 'node:os'\nimport { join } from 'node:path'\nimport type { SchemaDefinition } from '@korajs/core'\nimport type { WebSocketConstructor } from '@korajs/sync'\n\n/**\n * Kora Studio SPECTATOR: live, read-only inspection of a production sync\n * server.\n *\n * The spectator is a REAL Kora client — its own store, merge pipeline, and\n * sync engine — connected to the target server over the real WebSocket\n * protocol. It materializes its own replica into a throwaway database, which\n * every Studio view (records, per-field writers, op log, DAG, time travel,\n * merge audit) then reads. Nothing is simulated: what Studio shows is exactly\n * what any device syncing against that server computes.\n *\n * Read-only by construction: the spectator exposes NO mutation API, so it can\n * never push an operation to the server. It only receives, applies, and\n * observes. The server sees an ordinary client whose version vector starts\n * empty (so it receives the full history — which is what makes production\n * time travel possible) and which never sends operations.\n */\n\nexport interface SpectatorStatus {\n\turl: string\n\tconnected: boolean\n\toperationsReceived: number\n\tlastEventAt: number | null\n\tdbPath: string\n}\n\nexport interface SpectatorEvent {\n\tseq: number\n\tat: number\n\ttype: string\n\tsummary: string\n}\n\nexport interface SpectatorOptions {\n\turl: string\n\tschema: SchemaDefinition\n\t/** Bearer token forwarded through the sync auth handshake. */\n\ttoken?: string\n\t/** Client schema version override. Defaults to schema.version. */\n\tschemaVersion?: number\n}\n\n// NOTE: 'operation:applied' is in the event spec but not yet emitted by the\n// store — received-op counting uses 'sync:received' batches instead.\nconst FORWARDED_EVENTS = [\n\t'merge:started',\n\t'merge:conflict',\n\t'merge:completed',\n\t'sync:connected',\n\t'sync:disconnected',\n\t'sync:received',\n\t'sync:apply-failed',\n] as const\n\nconst MAX_EVENT_BUFFER = 500\n\n/** Structural types for the lazily-imported runtime packages. */\ninterface SpectatorRuntime {\n\tstore: {\n\t\topen(): Promise<void>\n\t\tclose(): Promise<void>\n\t\tsetLocalMutationHandler(handler: unknown): void\n\t}\n\tengine: { start(): Promise<void>; stop(): Promise<void> }\n\tunsubscribers: Array<() => void>\n}\n\nexport class SpectatorManager {\n\tprivate runtime: SpectatorRuntime | null = null\n\tprivate tmpDir: string | null = null\n\tprivate connected = false\n\tprivate operationsReceived = 0\n\tprivate lastEventAt: number | null = null\n\tprivate eventSeq = 0\n\tprivate readonly eventBuffer: SpectatorEvent[] = []\n\tprivate readonly eventListeners = new Set<(event: SpectatorEvent) => void>()\n\treadonly dbPath: string\n\n\tconstructor(private readonly options: SpectatorOptions) {\n\t\tthis.tmpDir = mkdtempSync(join(tmpdir(), 'kora-studio-spectator-'))\n\t\tthis.dbPath = join(this.tmpDir, 'spectator-replica.db')\n\t}\n\n\tasync start(): Promise<void> {\n\t\tlet mods: {\n\t\t\tStore: typeof import('@korajs/store').Store\n\t\t\tBetterSqlite3Adapter: typeof import('@korajs/store/better-sqlite3').BetterSqlite3Adapter\n\t\t\tMergeEngine: typeof import('@korajs/merge').MergeEngine\n\t\t\tSyncEngine: typeof import('@korajs/sync').SyncEngine\n\t\t\tWebSocketTransport: typeof import('@korajs/sync').WebSocketTransport\n\t\t\tWebSocket: typeof import('ws').default\n\t\t\ttesting: typeof import('korajs/testing')\n\t\t\tSimpleEventEmitter: typeof import('@korajs/core/internal').SimpleEventEmitter\n\t\t}\n\t\ttry {\n\t\t\tmods = {\n\t\t\t\tStore: (await import('@korajs/store')).Store,\n\t\t\t\tBetterSqlite3Adapter: (await import('@korajs/store/better-sqlite3')).BetterSqlite3Adapter,\n\t\t\t\tMergeEngine: (await import('@korajs/merge')).MergeEngine,\n\t\t\t\tSyncEngine: (await import('@korajs/sync')).SyncEngine,\n\t\t\t\tWebSocketTransport: (await import('@korajs/sync')).WebSocketTransport,\n\t\t\t\tWebSocket: (await import('ws')).default,\n\t\t\t\ttesting: await import('korajs/testing'),\n\t\t\t\tSimpleEventEmitter: (await import('@korajs/core/internal')).SimpleEventEmitter,\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tthrow new Error(\n\t\t\t\t`Spectator mode needs the Kora runtime packages installed (pnpm add -D korajs @korajs/store @korajs/merge @korajs/sync better-sqlite3). Underlying error: ${\n\t\t\t\t\terror instanceof Error ? error.message : String(error)\n\t\t\t\t}`,\n\t\t\t)\n\t\t}\n\n\t\tconst emitter = new mods.SimpleEventEmitter()\n\t\tconst adapter = new mods.BetterSqlite3Adapter(this.dbPath)\n\t\tconst store = new mods.Store({ schema: this.options.schema, adapter, emitter })\n\t\tawait store.open()\n\n\t\tconst mergeEngine = new mods.MergeEngine()\n\t\tconst pipeline = new mods.testing.ApplyPipeline({ store, mergeEngine, emitter })\n\t\tstore.setLocalMutationHandler(pipeline)\n\n\t\t// Production parity: merge decisions persist to the audit trail.\n\t\tconst unsubscribeAudit = mods.testing.wireAuditPersistence(store, emitter)\n\n\t\tconst syncStore = new mods.testing.MergeAwareSyncStore(store, mergeEngine, emitter)\n\t\tconst engine = new mods.SyncEngine({\n\t\t\ttransport: new mods.WebSocketTransport({\n\t\t\t\tWebSocketImpl: mods.WebSocket as unknown as WebSocketConstructor,\n\t\t\t}),\n\t\t\tstore: syncStore,\n\t\t\tqueueStorage: new mods.testing.StoreQueueStorage(adapter),\n\t\t\tsyncState: new mods.testing.StoreSyncStatePersistence(store),\n\t\t\tconfig: {\n\t\t\t\turl: this.options.url,\n\t\t\t\tschemaVersion: this.options.schemaVersion ?? this.options.schema.version,\n\t\t\t\t...(this.options.token\n\t\t\t\t\t? { auth: async () => ({ token: this.options.token as string }) }\n\t\t\t\t\t: {}),\n\t\t\t},\n\t\t\temitter,\n\t\t})\n\n\t\tconst unsubscribers = FORWARDED_EVENTS.map((type) =>\n\t\t\temitter.on(type, (event: Record<string, unknown>) => {\n\t\t\t\tthis.lastEventAt = Date.now()\n\t\t\t\tif (type === 'sync:connected') {\n\t\t\t\t\tthis.connected = true\n\t\t\t\t}\n\t\t\t\tif (type === 'sync:disconnected') {\n\t\t\t\t\tthis.connected = false\n\t\t\t\t}\n\t\t\t\tif (type === 'sync:received' && Array.isArray(event.operations)) {\n\t\t\t\t\tthis.operationsReceived += event.operations.length\n\t\t\t\t}\n\t\t\t\tthis.pushEvent(type, event)\n\t\t\t}),\n\t\t)\n\t\tunsubscribers.push(unsubscribeAudit)\n\n\t\tthis.runtime = { store, engine, unsubscribers }\n\t\tawait engine.start()\n\t}\n\n\tstatus(): SpectatorStatus {\n\t\treturn {\n\t\t\turl: this.options.url,\n\t\t\tconnected: this.connected,\n\t\t\toperationsReceived: this.operationsReceived,\n\t\t\tlastEventAt: this.lastEventAt,\n\t\t\tdbPath: this.dbPath,\n\t\t}\n\t}\n\n\trecentEvents(): SpectatorEvent[] {\n\t\treturn [...this.eventBuffer]\n\t}\n\n\tonEvent(listener: (event: SpectatorEvent) => void): () => void {\n\t\tthis.eventListeners.add(listener)\n\t\treturn () => this.eventListeners.delete(listener)\n\t}\n\n\tasync close(): Promise<void> {\n\t\tif (this.runtime) {\n\t\t\tfor (const unsub of this.runtime.unsubscribers) {\n\t\t\t\tunsub()\n\t\t\t}\n\t\t\tawait this.runtime.engine.stop().catch(() => {})\n\t\t\tawait this.runtime.store.close().catch(() => {})\n\t\t\tthis.runtime = null\n\t\t}\n\t\tif (this.tmpDir) {\n\t\t\trmSync(this.tmpDir, { recursive: true, force: true })\n\t\t\tthis.tmpDir = null\n\t\t}\n\t}\n\n\tprivate pushEvent(type: string, payload: Record<string, unknown>): void {\n\t\tconst summary =\n\t\t\ttype === 'sync:received' && Array.isArray(payload.operations)\n\t\t\t\t? `received ${payload.operations.length} op(s)`\n\t\t\t\t: type.replace('sync:', '').replace('merge:', 'merge ')\n\t\tconst event: SpectatorEvent = {\n\t\t\tseq: ++this.eventSeq,\n\t\t\tat: Date.now(),\n\t\t\ttype,\n\t\t\tsummary,\n\t\t}\n\t\tthis.eventBuffer.push(event)\n\t\tif (this.eventBuffer.length > MAX_EVENT_BUFFER) {\n\t\t\tthis.eventBuffer.shift()\n\t\t}\n\t\tfor (const listener of this.eventListeners) {\n\t\t\tlistener(event)\n\t\t}\n\t}\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korajs/cli",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.11",
   "description": "Kora.js CLI tooling and project scaffolding",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -37,22 +37,24 @@
     "conf": "^15.1.0",
     "esbuild": "^0.28.0",
     "validate-npm-package-name": "^7.0.2",
-    "@korajs/core": "1.0.0-beta.1"
+    "ws": "^8.18.0",
+    "@korajs/core": "1.0.0-beta.11"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.5.2",
     "@types/validate-npm-package-name": "^4.0.2",
+    "@types/ws": "^8.5.13",
     "better-sqlite3": "^12.8.0",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",
     "vitest": "^3.0.4",
-    "@korajs/store": "1.0.0-beta.1",
-    "@korajs/server": "1.0.0-beta.1",
-    "@korajs/merge": "1.0.0-beta.1",
-    "korajs": "1.0.0-beta.1",
-    "@korajs/sync": "1.0.0-beta.1",
-    "@korajs/test": "1.0.0-beta.1"
+    "@korajs/server": "1.0.0-beta.11",
+    "@korajs/sync": "1.0.0-beta.11",
+    "@korajs/store": "1.0.0-beta.11",
+    "@korajs/test": "1.0.0-beta.11",
+    "@korajs/merge": "1.0.0-beta.11",
+    "korajs": "1.0.0-beta.11"
   },
   "license": "MIT",
   "scripts": {

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

@@ -47,7 +47,7 @@ To enable real-time sync across devices, update `src/main.tsx`:
 const app = createApp({
   schema,
   sync: {
-    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001',
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001/kora-sync',
   },
   // ...
 })

package/templates/react-basic/src/main.tsx

@@ -12,7 +12,7 @@ const app = createApp({
 	store: {
 		workerUrl: koraWorkerUrl,
 	},
-	devtools: true,
+	devtools: import.meta.env.DEV,
 })
 
 createRoot(document.getElementById('root')!).render(

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

@@ -1,4 +1,5 @@
 interface ImportMetaEnv {
+	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
 }
 

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

@@ -6,23 +6,26 @@ import { defineConfig } from 'vite'
 
 /**
  * Adds Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers
- * required for SharedArrayBuffer. Without these headers, OPFS SAH Pool VFS
- * cannot be used and SQLite WASM falls back to in-memory storage (no persistence).
+ * enabling SharedArrayBuffer where browsers support it while keeping common
+ * third-party embeds such as YouTube and Vimeo usable. Kora falls back to
+ * durable IndexedDB storage when SharedArrayBuffer is unavailable.
  */
 function crossOriginIsolation(): Plugin {
+	const embedderPolicy = process.env.KORA_COEP_POLICY || 'credentialless'
+
 	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')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				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')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},

package/templates/react-sync/README.md.hbs

@@ -11,7 +11,7 @@ npm run dev
 This starts both the Vite dev server and the Kora sync server.
 
 - **App**: http://localhost:5173
-- **Sync server**: ws://localhost:3001
+- **Sync server**: ws://localhost:3001/kora-sync
 
 ## Project Structure
 
@@ -40,11 +40,12 @@ writes, and `useTodos.ts` is the React binding that exposes todo data and action
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `VITE_SYNC_URL` | `ws://localhost:3001` | WebSocket URL for the sync server |
+| `VITE_SYNC_URL` | `ws://localhost:3001/kora-sync` | WebSocket URL for the sync endpoint |
 | `VITE_AUTH_URL` | current origin | HTTP URL for `/auth/*` routes |
 | `PORT` | `3001` | Sync server port |
-| `KORA_SERVER_DB` | `./kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
-| `KORA_AUTH_DB` | `./kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `KORA_SERVER_DB` | `./.kora/kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
+| `KORA_AUTH_DB` | `./.kora/kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `KORA_COEP_POLICY` | `credentialless` | Dev/preview Cross-Origin-Embedder-Policy. Use `require-corp` only when every embedded resource opts in. |
 | `DATABASE_URL` | (none) | PostgreSQL connection string for production sync server deployments |
 | `KORA_SYNC_PATH` | `/kora-sync` | WebSocket path exposed by the sync server |
 | `KORA_AUTH_SECRET` | (none) | Enables built-in `/auth/*` routes and authenticated sync when set |
@@ -94,7 +95,7 @@ The client and sync server must be deployed separately:
 Set `VITE_SYNC_URL` to your deployed sync server URL when building:
 
 ```bash
-VITE_SYNC_URL=wss://your-server.example.com npm run build
+VITE_SYNC_URL=wss://your-server.example.com/kora-sync npm run build
 ```
 
 ## Learn More

package/templates/react-sync/server.ts

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from 'node:fs'
 import {
 	type CreateKoraAuthServerOptions,
 	createKoraAuthServer,
@@ -12,6 +13,45 @@ import {
 } from '@korajs/server'
 import schema from './src/schema'
 
+loadLocalEnv()
+
+function loadLocalEnv(mode = process.env.NODE_ENV || 'development') {
+	const existingKeys = new Set(Object.keys(process.env))
+	for (const file of ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]) {
+		if (!existsSync(file)) continue
+		for (const [key, value] of Object.entries(parseEnvFile(readFileSync(file, 'utf8')))) {
+			if (!existingKeys.has(key)) {
+				process.env[key] = value
+			}
+		}
+	}
+}
+
+function parseEnvFile(contents: string): Record<string, string> {
+	const env: Record<string, string> = {}
+	for (const rawLine of contents.split(/\r?\n/)) {
+		const line = rawLine.trim()
+		if (!line || line.startsWith('#')) continue
+		const normalized = line.startsWith('export ') ? line.slice('export '.length).trim() : line
+		const equalsIndex = normalized.indexOf('=')
+		if (equalsIndex <= 0) continue
+		const key = normalized.slice(0, equalsIndex).trim()
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue
+		env[key] = parseEnvValue(normalized.slice(equalsIndex + 1).trim())
+	}
+	return env
+}
+
+function parseEnvValue(value: string): string {
+	const quote = value[0]
+	if ((quote === '"' || quote === "'") && value[value.length - 1] === quote) {
+		const inner = value.slice(1, -1)
+		return quote === '"' ? inner.replace(/\\n/g, '\n').replace(/\\r/g, '\r') : inner
+	}
+	const commentIndex = value.search(/\s#/)
+	return (commentIndex >= 0 ? value.slice(0, commentIndex) : value).trim()
+}
+
 async function createStore() {
 	if (process.env.DATABASE_URL) {
 		return createPostgresServerStore({
@@ -20,7 +60,7 @@ async function createStore() {
 	}
 
 	return createSqliteServerStore({
-		filename: process.env.KORA_SERVER_DB || './kora-server.db',
+		filename: process.env.KORA_SERVER_DB || './.kora/kora-server.db',
 	})
 }
 
@@ -36,7 +76,10 @@ async function start() {
 		staticDir: './dist',
 		syncPath,
 		httpRoutes: auth ? [{ path: '/auth', handle: auth.handleRequest }] : undefined,
-		syncOptions: auth ? { auth: auth.auth } : undefined,
+		syncOptions: {
+			schemaVersion: schema.version,
+			...(auth ? { auth: auth.auth } : {}),
+		},
 		operationalAuth: {
 			adminToken: process.env.KORA_ADMIN_TOKEN,
 			metricsToken: process.env.KORA_METRICS_TOKEN,
@@ -72,7 +115,7 @@ async function createOAuthConfig(): Promise<CreateKoraAuthServerOptions['oauth']
 	const oauthStores = process.env.DATABASE_URL
 		? await createPostgresOAuthStores({ connectionString: process.env.DATABASE_URL })
 		: await createSqliteOAuthStores({
-				filename: process.env.KORA_AUTH_DB || './kora-auth.db',
+				filename: process.env.KORA_AUTH_DB || './.kora/kora-auth.db',
 			})
 
 	return {

package/templates/react-sync/src/main.tsx

@@ -26,7 +26,7 @@ const app = createApp({
 	store: {
 		workerUrl: koraWorkerUrl,
 	},
-	devtools: true,
+	devtools: import.meta.env.DEV,
 })
 
 // Connect to sync server once the app is ready

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

@@ -1,4 +1,5 @@
 interface ImportMetaEnv {
+	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
 }
 

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

@@ -6,23 +6,26 @@ import { defineConfig } from 'vite'
 
 /**
  * Adds Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers
- * required for SharedArrayBuffer. Without these headers, OPFS SAH Pool VFS
- * cannot be used and SQLite WASM falls back to in-memory storage (no persistence).
+ * enabling SharedArrayBuffer where browsers support it while keeping common
+ * third-party embeds such as YouTube and Vimeo usable. Kora falls back to
+ * durable IndexedDB storage when SharedArrayBuffer is unavailable.
  */
 function crossOriginIsolation(): Plugin {
+	const embedderPolicy = process.env.KORA_COEP_POLICY || 'credentialless'
+
 	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')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				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')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},
@@ -81,12 +84,19 @@ export default defineConfig({
 	},
 	server: {
 		allowedHosts: true,
+		watch: {
+			ignored: ['**/.kora/**', '**/kora/generated/**', '**/*.db', '**/*.db-shm', '**/*.db-wal'],
+		},
 		proxy: {
 			'/kora-sync': {
 				target: 'ws://localhost:3001',
 				ws: true,
 				rewriteWsOrigin: true,
 			},
+			'/auth': {
+				target: 'http://localhost:3001',
+				changeOrigin: true,
+			},
 		},
 	},
 })

package/templates/react-tailwind/README.md.hbs

@@ -47,7 +47,7 @@ To enable real-time sync across devices, update `src/main.tsx`:
 const app = createApp({
   schema,
   sync: {
-    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001',
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001/kora-sync',
   },
   // ...
 })

package/templates/react-tailwind/src/main.tsx

@@ -12,7 +12,7 @@ const app = createApp({
 	store: {
 		workerUrl: koraWorkerUrl,
 	},
-	devtools: true,
+	devtools: import.meta.env.DEV,
 })
 
 createRoot(document.getElementById('root')!).render(

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

@@ -1,4 +1,5 @@
 interface ImportMetaEnv {
+	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
 }
 

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

@@ -7,23 +7,26 @@ import { defineConfig } from 'vite'
 
 /**
  * Adds Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers
- * required for SharedArrayBuffer. Without these headers, OPFS SAH Pool VFS
- * cannot be used and SQLite WASM falls back to in-memory storage (no persistence).
+ * enabling SharedArrayBuffer where browsers support it while keeping common
+ * third-party embeds such as YouTube and Vimeo usable. Kora falls back to
+ * durable IndexedDB storage when SharedArrayBuffer is unavailable.
  */
 function crossOriginIsolation(): Plugin {
+	const embedderPolicy = process.env.KORA_COEP_POLICY || 'credentialless'
+
 	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')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				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')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},