@livestore/cli 0.0.0-snapshot-b2da08eec7583e23c0679970016a84b93438039e → 0.0.0-snapshot-bc54ad4b4319f020f2f8d040e4fe96a766c4e49d

package/src/commands/mcp-tool-handlers.ts

@@ -1,14 +1,20 @@
-import { Effect } from '@livestore/utils/effect'
+import { Effect, FetchHttpClient, Layer, type Toolkit } from '@livestore/utils/effect'
+import { PlatformNode } from '@livestore/utils/node'
 import { blogSchemaContent } from '../mcp-content/schemas/blog.ts'
 import { ecommerceSchemaContent } from '../mcp-content/schemas/ecommerce.ts'
 import { socialSchemaContent } from '../mcp-content/schemas/social.ts'
 import { todoSchemaContent } from '../mcp-content/schemas/todo.ts'
 import * as Runtime from '../mcp-runtime/runtime.ts'
+import * as SyncOps from '../sync-operations.ts'
 import { coachToolHandler } from './mcp-coach.ts'
 import { livestoreToolkit } from './mcp-tools-defs.ts'
 
-// Tool handlers using Tim Smart's pattern
-export const toolHandlers: any = livestoreToolkit.of({
+/** Layer providing FileSystem and HttpClient for sync operations */
+const SyncOpsLayer = Layer.mergeAll(PlatformNode.NodeFileSystem.layer, FetchHttpClient.layer)
+
+type LivestoreToolHandlers = Toolkit.HandlersFrom<Toolkit.Tools<typeof livestoreToolkit>>
+
+export const toolHandlers: LivestoreToolHandlers = livestoreToolkit.of({
   livestore_coach: coachToolHandler,
 
   livestore_generate_schema: Effect.fnUntraced(function* ({ schemaType, customDescription }) {
@@ -121,8 +127,13 @@ export const schema = Schema.create({
   }),
 
   // Connect the single in-process LiveStore instance from user module
-  livestore_instance_connect: Effect.fnUntraced(function* ({ storePath, storeId, clientId, sessionId }) {
-    const store = yield* Runtime.init({ storePath, storeId, clientId, sessionId }).pipe(Effect.orDie)
+  livestore_instance_connect: Effect.fnUntraced(function* ({ configPath, storeId, clientId, sessionId }) {
+    const store = yield* Runtime.init({
+      configPath,
+      storeId,
+      ...(clientId !== undefined ? { clientId } : {}),
+      ...(sessionId !== undefined ? { sessionId } : {}),
+    }).pipe(Effect.orDie)
     const eventNames = Array.from(store.schema.eventsDefsMap.keys())
     const tableNames = Array.from(store.schema.state.sqlite.tables.keys())
 
@@ -156,4 +167,38 @@ export const schema = Schema.create({
   livestore_instance_disconnect: Effect.fnUntraced(function* () {
     return yield* Runtime.disconnect
   }),
+
+  // Sync export - pull all events from sync backend
+  livestore_sync_export: Effect.fnUntraced(function* ({ configPath, storeId, clientId }) {
+    const result = yield* SyncOps.pullEventsFromSyncBackend({
+      configPath,
+      storeId,
+      clientId: clientId ?? 'mcp-export',
+    }).pipe(Effect.scoped, Effect.provide(SyncOpsLayer), Effect.orDie)
+
+    return {
+      storeId: result.storeId,
+      eventCount: result.eventCount,
+      exportedAt: result.exportedAt,
+      data: result.data,
+    }
+  }),
+
+  // Sync import - push events to sync backend
+  livestore_sync_import: Effect.fnUntraced(function* ({ configPath, storeId, clientId, data, force, dryRun }) {
+    const result = yield* SyncOps.pushEventsToSyncBackend({
+      configPath,
+      storeId,
+      clientId: clientId ?? 'mcp-import',
+      data,
+      force: force ?? false,
+      dryRun: dryRun ?? false,
+    }).pipe(Effect.scoped, Effect.provide(SyncOpsLayer), Effect.orDie)
+
+    return {
+      storeId: result.storeId,
+      eventCount: result.eventCount,
+      dryRun: result.dryRun,
+    }
+  }),
 })

package/src/commands/mcp-tools-defs.ts

@@ -43,7 +43,7 @@ export const livestoreToolkit = Toolkit.make(
 Notes:
 - Only one instance can be active at a time; calling connect again shuts down and replaces the previous instance.
 - Reconnecting creates a fresh, in-memory client database. The state visible to queries is populated by your backend's initial sync behavior; depending on configuration, you may briefly observe empty or partial data until sync completes.
-- \`storePath\` is resolved relative to the current working directory.
+- \`configPath\` is resolved relative to the current working directory.
 - \`syncBackend\` must be a function (factory) that returns a backend; \`syncPayload\` must be JSON-serializable.
 
 Module contract (generic example):
@@ -63,13 +63,13 @@ export const syncPayload = { authToken: process.env.LIVESTORE_SYNC_AUTH_TOKEN ??
 
 Connect parameters:
 {
-  "storePath": "<path-to-your-mcp-module>.ts",
+  "configPath": "livestore-cli.config.ts",
   "storeId": "<store-id>"
 }
 
 Optional identifiers to group client state on the server:
 {
-  "storePath": "<path-to-your-mcp-module>.ts",
+  "configPath": "livestore-cli.config.ts",
   "storeId": "<store-id>",
   "clientId": "<client-id>",
   "sessionId": "<session-id>"
@@ -86,7 +86,7 @@ Returns on success:
   }
 }`,
     parameters: {
-      storePath: Schema.String.annotations({
+      configPath: Schema.String.annotations({
         description: 'Path to a module that exports named variables: schema and syncBackend',
       }),
       storeId: Schema.String.annotations({ description: 'Required store id for the LiveStore instance.' }),
@@ -226,4 +226,92 @@ Example success:
     parameters: {},
     success: Schema.TaggedStruct('disconnected', {}),
   }),
+
+  Tool.make('livestore_sync_export', {
+    description: `Export all events from a sync backend to JSON data.
+
+This tool connects directly to the sync backend (without creating a full LiveStore instance) and pulls all events. Useful for backup, migration, and debugging.
+
+Module contract (same as livestore_instance_connect):
+\`\`\`ts
+export { schema } from './src/livestore/schema.ts'
+export const syncBackend = makeWsSync({ url: process.env.LIVESTORE_SYNC_URL ?? 'ws://localhost:8787' })
+export const syncPayload = { authToken: process.env.LIVESTORE_SYNC_AUTH_TOKEN }
+\`\`\`
+
+Example parameters:
+{
+  "configPath": "livestore-cli.config.ts",
+  "storeId": "my-store"
+}
+
+Returns on success:
+{
+  "storeId": "my-store",
+  "eventCount": 127,
+  "exportedAt": "2024-01-15T10:30:00.000Z",
+  "data": { "version": 1, "storeId": "my-store", ... }
+}`,
+    parameters: {
+      configPath: Schema.String.annotations({
+        description: 'Path to a module that exports schema and syncBackend',
+      }),
+      storeId: Schema.String.annotations({ description: 'Store identifier' }),
+      clientId: Schema.optional(Schema.String.annotations({ description: 'Client identifier (default: mcp-export)' })),
+    },
+    success: Schema.Struct({
+      storeId: Schema.String,
+      eventCount: Schema.Number,
+      exportedAt: Schema.String,
+      data: Schema.JsonValue.annotations({ description: 'The export file data (can be saved or passed to import)' }),
+    }),
+  }).annotate(Tool.Readonly, true),
+
+  Tool.make('livestore_sync_import', {
+    description: `Import events from export data to a sync backend.
+
+This tool connects directly to the sync backend and pushes events. The sync backend must be empty.
+
+Example parameters:
+{
+  "configPath": "livestore-cli.config.ts",
+  "storeId": "my-store",
+  "data": { "version": 1, "storeId": "my-store", "events": [...] }
+}
+
+With options:
+{
+  "configPath": "livestore-cli.config.ts",
+  "storeId": "my-store",
+  "data": { ... },
+  "force": true,  // Import even if store ID doesn't match
+  "dryRun": true  // Validate without importing
+}
+
+Returns on success:
+{
+  "storeId": "my-store",
+  "eventCount": 127,
+  "dryRun": false
+}`,
+    parameters: {
+      configPath: Schema.String.annotations({
+        description: 'Path to a module that exports schema and syncBackend',
+      }),
+      storeId: Schema.String.annotations({ description: 'Store identifier' }),
+      clientId: Schema.optional(Schema.String.annotations({ description: 'Client identifier (default: mcp-import)' })),
+      data: Schema.JsonValue.annotations({
+        description: 'The export data to import (from livestore_sync_export or a file)',
+      }),
+      force: Schema.optional(
+        Schema.Boolean.annotations({ description: 'Force import even if store ID does not match' }),
+      ),
+      dryRun: Schema.optional(Schema.Boolean.annotations({ description: 'Validate without actually importing' })),
+    },
+    success: Schema.Struct({
+      storeId: Schema.String,
+      eventCount: Schema.Number,
+      dryRun: Schema.Boolean,
+    }),
+  }).annotate(Tool.Destructive, true),
 )

package/src/mcp-runtime/runtime.ts

@@ -1,77 +1,40 @@
-import path from 'node:path'
-import { pathToFileURL } from 'node:url'
 import { makeAdapter as makeNodeAdapter } from '@livestore/adapter-node'
-import { isLiveStoreSchema, LiveStoreEvent, SystemTables } from '@livestore/common/schema'
+import { UnknownError } from '@livestore/common'
+import { LiveStoreEvent, SystemTables } from '@livestore/common/schema'
 import type { Store } from '@livestore/livestore'
 import { createStorePromise } from '@livestore/livestore'
-import { shouldNeverHappen } from '@livestore/utils'
-import { Effect, Option, Schema } from '@livestore/utils/effect'
+import { Effect, FetchHttpClient, Layer, Option, Schema } from '@livestore/utils/effect'
+import { PlatformNode } from '@livestore/utils/node'
+
+import { loadModuleConfig } from '../module-loader.ts'
 
 /** Currently connected store */
 let store: Store<any> | undefined
 
+/** Layer providing FileSystem and HttpClient for module loading */
+const ModuleLoaderLayer = Layer.mergeAll(PlatformNode.NodeFileSystem.layer, FetchHttpClient.layer)
+
 /**
  * Dynamically imports a module that exports a `makeStore({ storeId }): Promise<Store>` function,
  * calls it with the provided storeId, and caches the Store instance for subsequent tool calls.
  */
 export const init = ({
-  storePath,
+  configPath,
   storeId,
   clientId,
   sessionId,
 }: {
-  storePath: string
+  configPath: string
   storeId: string
   clientId?: string
   sessionId?: string
-}) =>
-  Effect.promise(async () => {
+}): Effect.Effect<Store<any>, UnknownError> =>
+  Effect.gen(function* () {
     if (!storeId || typeof storeId !== 'string') {
-      throw new Error('Invalid storeId: expected a non-empty string')
-    }
-    // Resolve to absolute path and import as file URL
-    const abs = path.isAbsolute(storePath) ? storePath : path.resolve(process.cwd(), storePath)
-    const mod = await import(pathToFileURL(abs).href)
-
-    // Validate required exports
-    const schema = (mod as any)?.schema
-    if (!isLiveStoreSchema(schema)) {
-      throw new Error(
-        `Module at ${abs} must export a valid LiveStore 'schema'. Ex: export { schema } from './src/livestore/schema.ts'`,
-      )
+      return yield* UnknownError.make({ cause: new Error('Invalid storeId: expected a non-empty string') })
     }
 
-    const syncBackend = (mod as any)?.syncBackend
-    if (typeof syncBackend !== 'function') {
-      throw new Error(
-        `Module at ${abs} must export a 'syncBackend' constructor (e.g., makeWsSync({ url })). Ex: export const syncBackend = makeWsSync({ url })`,
-      )
-    }
-
-    // Optional: syncPayload for authenticated backends
-    const syncPayloadSchemaExport = (mod as any)?.syncPayloadSchema
-    const syncPayloadSchema =
-      syncPayloadSchemaExport === undefined
-        ? Schema.JsonValue
-        : Schema.isSchema(syncPayloadSchemaExport)
-          ? (syncPayloadSchemaExport as Schema.Schema<any>)
-          : shouldNeverHappen(
-              `Exported 'syncPayloadSchema' from ${abs} must be an Effect Schema (received ${typeof syncPayloadSchemaExport}).`,
-            )
-
-    const syncPayloadExport = (mod as any)?.syncPayload
-    const syncPayload =
-      syncPayloadExport === undefined
-        ? undefined
-        : (() => {
-            try {
-              return Schema.decodeSync(syncPayloadSchema)(syncPayloadExport)
-            } catch (error) {
-              throw new Error(
-                `Failed to decode 'syncPayload' from ${abs} using the provided schema: ${(error as Error).message}`,
-              )
-            }
-          })()
+    const { schema, syncBackendConstructor, syncPayloadSchema, syncPayload } = yield* loadModuleConfig({ configPath })
 
     // Build Node adapter internally
     const adapter = makeNodeAdapter({
@@ -79,32 +42,36 @@ export const init = ({
       ...(clientId ? { clientId } : {}),
       ...(sessionId ? { sessionId } : {}),
       sync: {
-        backend: syncBackend as any,
+        backend: syncBackendConstructor,
         initialSyncOptions: { _tag: 'Blocking', timeout: 5000 },
         onSyncError: 'shutdown',
       },
     })
 
     // Create the store
-    const s = await createStorePromise({
-      schema,
-      storeId,
-      adapter,
-      disableDevtools: true,
-      syncPayload,
-      syncPayloadSchema,
-    })
+    const s = yield* Effect.promise(() =>
+      createStorePromise({
+        schema,
+        storeId,
+        adapter,
+        disableDevtools: true,
+        syncPayload,
+        syncPayloadSchema,
+      }),
+    )
 
     // Replace existing store if any
     if (store) {
-      try {
-        await store.shutdownPromise()
-      } catch {}
+      yield* Effect.promise(async () => {
+        try {
+          await store!.shutdownPromise()
+        } catch {}
+      })
     }
 
     store = s
     return store
-  })
+  }).pipe(Effect.provide(ModuleLoaderLayer), Effect.withSpan('mcp-runtime:init'))
 
 export const getStore = Effect.sync(() => Option.fromNullable(store))
 

package/src/module-loader.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared module loading utility for CLI and MCP.
+ * Loads and validates user config modules that export schema, syncBackend, and optional syncPayload.
+ */
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { SyncBackend } from '@livestore/common'
+import { UnknownError } from '@livestore/common'
+import { isLiveStoreSchema, type LiveStoreSchema } from '@livestore/common/schema'
+import { shouldNeverHappen } from '@livestore/utils'
+import { Effect, FileSystem, Schema } from '@livestore/utils/effect'
+
+export interface ModuleConfig {
+  schema: LiveStoreSchema
+  syncBackendConstructor: SyncBackend.SyncBackendConstructor
+  syncPayloadSchema: Schema.Schema<any>
+  syncPayload: unknown
+}
+
+/**
+ * Loads and validates a user config module.
+ * The module must export:
+ * - `schema`: A valid LiveStore schema
+ * - `syncBackend`: A sync backend constructor function
+ * - `syncPayloadSchema` (optional): Schema for validating syncPayload
+ * - `syncPayload` (optional): Payload data for the sync backend
+ */
+export const loadModuleConfig = ({
+  configPath,
+}: {
+  configPath: string
+}): Effect.Effect<ModuleConfig, UnknownError, FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const abs = path.isAbsolute(configPath) ? configPath : path.resolve(process.cwd(), configPath)
+
+    const fs = yield* FileSystem.FileSystem
+    const exists = yield* fs.exists(abs).pipe(UnknownError.mapToUnknownError)
+    if (!exists) {
+      return yield* UnknownError.make({
+        cause: `Store module not found at ${abs}`,
+        note: 'Make sure the path points to a valid LiveStore module',
+      })
+    }
+
+    const mod = yield* Effect.tryPromise({
+      try: () => import(pathToFileURL(abs).href),
+      catch: (cause) =>
+        UnknownError.make({
+          cause,
+          note: `Failed to import module at ${abs}`,
+        }),
+    })
+
+    const schema = (mod as any)?.schema
+    if (!isLiveStoreSchema(schema)) {
+      return yield* UnknownError.make({
+        cause: `Module at ${abs} must export a valid LiveStore 'schema'`,
+        note: `Ex: export { schema } from './src/livestore/schema.ts'`,
+      })
+    }
+
+    const syncBackendConstructor = (mod as any)?.syncBackend
+    if (typeof syncBackendConstructor !== 'function') {
+      return yield* UnknownError.make({
+        cause: `Module at ${abs} must export a 'syncBackend' constructor`,
+        note: `Ex: export const syncBackend = makeWsSync({ url })`,
+      })
+    }
+
+    const syncPayloadSchemaExport = (mod as any)?.syncPayloadSchema
+    const syncPayloadSchema =
+      syncPayloadSchemaExport === undefined
+        ? Schema.JsonValue
+        : Schema.isSchema(syncPayloadSchemaExport)
+          ? (syncPayloadSchemaExport as Schema.Schema<any>)
+          : shouldNeverHappen(
+              `Exported 'syncPayloadSchema' from ${abs} must be an Effect Schema (received ${typeof syncPayloadSchemaExport}).`,
+            )
+
+    const syncPayloadExport = (mod as any)?.syncPayload
+    const syncPayload = yield* (
+      syncPayloadExport === undefined
+        ? Effect.succeed<unknown>(undefined)
+        : Schema.decodeUnknown(syncPayloadSchema)(syncPayloadExport)
+    ).pipe(UnknownError.mapToUnknownError)
+
+    return {
+      schema,
+      syncBackendConstructor,
+      syncPayloadSchema,
+      syncPayload,
+    }
+  }).pipe(Effect.withSpan('module-loader:loadModuleConfig'))