@livestore/cli 0.4.0-dev.9 → 0.4.0

package/src/commands/import-export.ts

@@ -0,0 +1,283 @@
+import path from 'node:path'
+
+import type { UnknownError } from '@livestore/common'
+import { Console, Effect, FileSystem, type HttpClient, Schema, type Scope } from '@livestore/utils/effect'
+import { Cli } from '@livestore/utils/node'
+
+import * as SyncOps from '../sync-operations.ts'
+
+const jsonStringifyPretty = Schema.encodeSync(Schema.parseJson({ space: 2 }))
+const jsonParse = Schema.decodeUnknownSync(Schema.parseJson())
+
+const LARGE_EVENT_WARNING_THRESHOLD = 100_000
+
+/**
+ * Export events from the sync backend to a JSON file.
+ */
+const exportEvents = ({
+  configPath,
+  storeId,
+  clientId,
+  outputPath,
+}: {
+  configPath: string
+  storeId: string
+  clientId: string
+  outputPath: string
+}): Effect.Effect<
+  void,
+  SyncOps.ExportError | SyncOps.ConnectionError | UnknownError,
+  FileSystem.FileSystem | HttpClient.HttpClient | Scope.Scope
+> =>
+  Effect.gen(function* () {
+    yield* Console.log(`Connecting to sync backend...`)
+
+    const result = yield* SyncOps.pullEventsFromSyncBackend({ configPath, storeId, clientId })
+
+    yield* Console.log(`✓ Connected to sync backend: ${result.backendName}`)
+    yield* Console.log(`Pulled ${result.eventCount} events`)
+    if (result.eventCount > LARGE_EVENT_WARNING_THRESHOLD) {
+      yield* Console.log(
+        `Warning: exporting ${result.eventCount} events may consume significant memory. Consider exporting on a machine with enough RAM.`,
+      )
+    }
+
+    const fs = yield* FileSystem.FileSystem
+    const absOutputPath = path.isAbsolute(outputPath) === true ? outputPath : path.resolve(process.cwd(), outputPath)
+
+    yield* fs.writeFileString(absOutputPath, jsonStringifyPretty(result.data)).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SyncOps.ExportError({
+            cause,
+            note: `Failed to write export file: ${String(cause)}`,
+          }),
+      ),
+    )
+
+    yield* Console.log(`Exported ${result.eventCount} events to ${absOutputPath}`)
+  }).pipe(Effect.withSpan('cli:export'))
+
+/**
+ * Import events from a JSON file to the sync backend.
+ */
+const importEvents = ({
+  configPath,
+  storeId,
+  clientId,
+  inputPath,
+  force,
+  dryRun,
+}: {
+  configPath: string
+  storeId: string
+  clientId: string
+  inputPath: string
+  force: boolean
+  dryRun: boolean
+}): Effect.Effect<
+  void,
+  SyncOps.ImportError | SyncOps.ConnectionError | UnknownError,
+  FileSystem.FileSystem | HttpClient.HttpClient | Scope.Scope
+> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const absInputPath = path.isAbsolute(inputPath) === true ? inputPath : path.resolve(process.cwd(), inputPath)
+
+    const exists = yield* fs.exists(absInputPath).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SyncOps.ImportError({
+            cause,
+            note: `Failed to check file existence: ${String(cause)}`,
+          }),
+      ),
+    )
+    if (exists === false) {
+      return yield* new SyncOps.ImportError({
+        cause: new Error(`File not found: ${absInputPath}`),
+        note: `Import file does not exist at ${absInputPath}`,
+      })
+    }
+
+    yield* Console.log(`Reading import file...`)
+
+    const fileContent = yield* fs.readFileString(absInputPath).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SyncOps.ImportError({
+            cause,
+            note: `Failed to read import file: ${String(cause)}`,
+          }),
+      ),
+    )
+
+    const parsedContent = yield* Effect.try({
+      try: () => jsonParse(fileContent),
+      catch: (error) =>
+        new SyncOps.ImportError({
+          cause: new Error(`Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`),
+          note: `Invalid JSON in import file: ${error instanceof Error ? error.message : String(error)}`,
+        }),
+    })
+
+    /** Validate export file format before proceeding */
+    const validation = yield* SyncOps.validateExportData({ data: parsedContent, targetStoreId: storeId })
+
+    if (validation.storeIdMismatch === true) {
+      if (force !== true) {
+        return yield* new SyncOps.ImportError({
+          cause: new Error(`Store ID mismatch: file has '${validation.sourceStoreId}', expected '${storeId}'`),
+          note: `The export file was created for a different store. Use --force to import anyway.`,
+        })
+      }
+      yield* Console.log(
+        `Store ID mismatch: file has '${validation.sourceStoreId}', importing to '${storeId}' (--force)`,
+      )
+    }
+
+    yield* Console.log(`Found ${validation.eventCount} events in export file`)
+    if (validation.eventCount > LARGE_EVENT_WARNING_THRESHOLD) {
+      yield* Console.log(
+        `Warning: importing ${validation.eventCount} events may consume significant memory. Ensure the machine has enough RAM.`,
+      )
+    }
+
+    if (dryRun === true) {
+      yield* Console.log(`Dry run - validating import file...`)
+      yield* Console.log(`Dry run complete. ${validation.eventCount} events would be imported.`)
+      return
+    }
+
+    yield* Console.log(`Checking for existing events...`)
+
+    yield* Console.log(`Connecting to sync backend...`)
+    yield* Console.log(`Pushing events to sync backend...`)
+
+    const result = yield* SyncOps.pushEventsToSyncBackend({
+      configPath,
+      storeId,
+      clientId,
+      data: parsedContent,
+      force,
+      dryRun: false,
+      onProgress: (pushed, total) => Console.log(`  Pushed ${pushed}/${total} events`),
+    })
+
+    yield* Console.log(`✓ Connected to sync backend: ${result.backendName ?? 'unknown'}`)
+    yield* Console.log(`Successfully imported ${result.eventCount} events`)
+  }).pipe(Effect.withSpan('cli:import'))
+
+export const exportCommand = Cli.Command.make(
+  'export',
+  {
+    config: Cli.Options.text('config').pipe(
+      Cli.Options.withAlias('c'),
+      Cli.Options.withDescription('Path to the config module that exports schema and syncBackend'),
+    ),
+    storeId: Cli.Options.text('store-id').pipe(
+      Cli.Options.withAlias('i'),
+      Cli.Options.withDescription('Store identifier'),
+    ),
+    clientId: Cli.Options.text('client-id').pipe(
+      Cli.Options.withDefault('cli-export'),
+      Cli.Options.withDescription('Client identifier for the sync connection'),
+    ),
+    output: Cli.Args.text({ name: 'file' }).pipe(Cli.Args.withDescription('Output JSON file path')),
+  },
+  Effect.fn(function* ({
+    config,
+    storeId,
+    clientId,
+    output,
+  }: {
+    config: string
+    storeId: string
+    clientId: string
+    output: string
+  }) {
+    yield* Console.log(`Exporting events from LiveStore...`)
+    yield* Console.log(`   Config: ${config}`)
+    yield* Console.log(`   Store ID: ${storeId}`)
+    yield* Console.log(`   Output: ${output}`)
+    yield* Console.log('')
+
+    yield* exportEvents({
+      configPath: config,
+      storeId,
+      clientId,
+      outputPath: output,
+    }).pipe(Effect.scoped)
+  }),
+).pipe(
+  Cli.Command.withDescription(
+    'Export all events from the sync backend to a JSON file. Useful for backup and migration.',
+  ),
+)
+
+export const importCommand = Cli.Command.make(
+  'import',
+  {
+    config: Cli.Options.text('config').pipe(
+      Cli.Options.withAlias('c'),
+      Cli.Options.withDescription('Path to the config module that exports schema and syncBackend'),
+    ),
+    storeId: Cli.Options.text('store-id').pipe(
+      Cli.Options.withAlias('i'),
+      Cli.Options.withDescription('Store identifier'),
+    ),
+    clientId: Cli.Options.text('client-id').pipe(
+      Cli.Options.withDefault('cli-import'),
+      Cli.Options.withDescription('Client identifier for the sync connection'),
+    ),
+    force: Cli.Options.boolean('force').pipe(
+      Cli.Options.withAlias('f'),
+      Cli.Options.withDefault(false),
+      Cli.Options.withDescription('Force import even if store ID does not match'),
+    ),
+    dryRun: Cli.Options.boolean('dry-run').pipe(
+      Cli.Options.withDefault(false),
+      Cli.Options.withDescription('Validate the import file without actually importing'),
+    ),
+    input: Cli.Args.text({ name: 'file' }).pipe(Cli.Args.withDescription('Input JSON file to import')),
+  },
+  Effect.fn(function* ({
+    config,
+    storeId,
+    clientId,
+    force,
+    dryRun,
+    input,
+  }: {
+    config: string
+    storeId: string
+    clientId: string
+    force: boolean
+    dryRun: boolean
+    input: string
+  }) {
+    yield* Console.log(`Importing events to LiveStore...`)
+    yield* Console.log(`   Config: ${config}`)
+    yield* Console.log(`   Store ID: ${storeId}`)
+    yield* Console.log(`   Input: ${input}`)
+    if (force === true) yield* Console.log(`   Force: enabled`)
+    if (dryRun === true) yield* Console.log(`   Dry run: enabled`)
+    yield* Console.log('')
+
+    yield* importEvents({
+      configPath: config,
+      storeId,
+      clientId,
+      inputPath: input,
+      force,
+      dryRun,
+    }).pipe(Effect.scoped)
+  }),
+).pipe(
+  Cli.Command.withDescription('Import events from a JSON file to the sync backend. The sync backend must be empty.'),
+)
+
+export const syncCommand = Cli.Command.make('sync').pipe(
+  Cli.Command.withSubcommands([exportCommand, importCommand]),
+  Cli.Command.withDescription('Import and export events from the sync backend'),
+)

package/src/commands/mcp-coach.ts

@@ -1,15 +1,7 @@
+import { LanguageModel } from '@effect/ai'
 import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai'
-import {
-  AiError,
-  Config,
-  Effect,
-  FetchHttpClient,
-  LanguageModel,
-  Layer,
-  Prompt,
-  Schema,
-  Tool,
-} from '@livestore/utils/effect'
+
+import { AiError, Config, Effect, FetchHttpClient, Layer, Prompt, Schema, Tool } from '@livestore/utils/effect'
 
 // Define the coach tool that analyzes LiveStore usage
 export const coachTool = Tool.make('livestore_coach', {
@@ -45,24 +37,33 @@ export const coachTool = Tool.make('livestore_coach', {
   failure: AiError.AiError,
 })
 
-const OpenAiClientLayer = OpenAiClient.layerConfig({
-  apiKey: Config.redacted('OPENAI_API_KEY'),
-})
+/** Composed layer: HttpClient → OpenAiClient → LanguageModel */
+const LanguageModelLayer = OpenAiLanguageModel.layer({ model: 'gpt-4o-mini' }).pipe(
+  Layer.provide(OpenAiClient.layerConfig({ apiKey: Config.redacted('OPENAI_API_KEY') })),
+  Layer.provide(FetchHttpClient.layer),
+)
 
-const OpenAiModel = OpenAiLanguageModel.layer({
-  model: 'gpt-5-nano',
-})
+type CoachToolHandlerInput = {
+  readonly code: string
+  readonly codeType?: string | undefined
+}
 
-// Coach tool handler that uses OpenAI for analysis
-export const coachToolHandler = Effect.fnUntraced(
-  function* ({ code, codeType }) {
-    // Build the analysis prompt
-    const codeTypeContext = codeType ? `This is ${codeType} code using LiveStore. ` : 'This is LiveStore code. '
+type CoachToolResult = {
+  readonly feedback: string
+  readonly score: number | undefined
+  readonly suggestions: string[]
+}
 
-    const prompt = Prompt.makeMessage('user', {
-      content: [
-        Prompt.makePart('text', {
-          text: `${codeTypeContext}Please review the following code and provide helpful feedback focusing on:
+/** Coach tool handler that uses OpenAI for analysis */
+export const coachToolHandler: (input: CoachToolHandlerInput) => Effect.Effect<CoachToolResult, AiError.AiError> =
+  Effect.fn('mcp-coach-handler')(({ code, codeType }) => {
+    const effect = Effect.gen(function* () {
+      const codeTypeContext = codeType !== undefined ? `This is ${codeType} code using LiveStore. ` : 'This is LiveStore code. '
+
+      const prompt = Prompt.makeMessage('user', {
+        content: [
+          Prompt.makePart('text', {
+            text: `${codeTypeContext}Please review the following code and provide helpful feedback focusing on:
 
 1. LiveStore best practices and conventions
 2. Schema design and relationships (if applicable)
@@ -84,47 +85,46 @@ Please provide:
 4. Any potential issues or concerns
 
 Format your response as constructive feedback that helps developers improve their LiveStore usage.`,
-        }),
-      ],
-    })
+          }),
+        ],
+      })
+
+      const systemPrompt = Prompt.makeMessage('system', {
+        content: `You are an expert LiveStore developer and code reviewer. Provide constructive, specific, and actionable feedback on LiveStore code. Focus on best practices, performance, and maintainability.`,
+      })
 
-    const systemPrompt = Prompt.makeMessage('system', {
-      content: `You are an expert LiveStore developer and code reviewer. Provide constructive, specific, and actionable feedback on LiveStore code. Focus on best practices, performance, and maintainability.`,
+      const llm = yield* LanguageModel.LanguageModel
+      const completion = yield* llm.generateText({ prompt: Prompt.fromMessages([systemPrompt, prompt]) })
+
+      const feedback = completion.text ?? 'Unable to generate feedback'
+
+      const suggestions = feedback
+        .split('\n')
+        .filter(
+          (line: string) =>
+            line.trim().startsWith('-') ||
+            line.trim().startsWith('*') ||
+            line.trim().startsWith('•') ||
+            line.toLowerCase().includes('recommend') ||
+            line.toLowerCase().includes('consider') ||
+            line.toLowerCase().includes('improve'),
+        )
+        .map((line: string) => line.replace(/^[-*•]\s*/, '').trim())
+        .filter((suggestion: string) => suggestion.length > 10)
+        .slice(0, 5)
+
+      const scoreMatch = feedback.match(/(?:score|rating|quality).*?(\d+(?:\.\d+)?)/i)
+      const score = scoreMatch !== null ? Number.parseFloat(scoreMatch[1] ?? '0') : undefined
+
+      return {
+        feedback,
+        score: score !== undefined && score >= 1 && score <= 10 ? score : undefined,
+        suggestions,
+      }
     })
 
-    // Get OpenAI client and call the API
-    const llm = yield* LanguageModel.LanguageModel
-    const completion = yield* llm.generateText({ prompt: Prompt.fromMessages([systemPrompt, prompt]) })
-
-    const feedback = completion.text ?? 'Unable to generate feedback'
-
-    // Extract suggestions from the feedback (simple approach)
-    const suggestions: string[] = feedback
-      .split('\n')
-      .filter(
-        (line: string) =>
-          line.trim().startsWith('-') ||
-          line.trim().startsWith('*') ||
-          line.trim().startsWith('•') ||
-          line.toLowerCase().includes('recommend') ||
-          line.toLowerCase().includes('consider') ||
-          line.toLowerCase().includes('improve'),
-      )
-      .map((line: string) => line.replace(/^[-*•]\s*/, '').trim())
-      .filter((suggestion: string) => suggestion.length > 10)
-      .slice(0, 5) // Limit to 5 suggestions
-
-    // Try to extract a score (simple regex approach)
-    const scoreMatch = feedback.match(/(?:score|rating|quality).*?(\d+(?:\.\d+)?)/i)
-    const score = scoreMatch ? Number.parseFloat(scoreMatch[1] ?? '0') : undefined
-
-    return {
-      feedback,
-      score: score && score >= 1 && score <= 10 ? score : undefined,
-      suggestions,
-    }
-  },
-  Effect.provide(Layer.provideMerge(OpenAiModel, OpenAiClientLayer)),
-  Effect.provide(FetchHttpClient.layer),
-  Effect.catchTag('ConfigError', (e) => Effect.die(e)),
-)
+    return effect.pipe(
+      Effect.provide(LanguageModelLayer),
+      Effect.catchTag('ConfigError', (e) => Effect.die(e)),
+    )
+  })

package/src/commands/{mcp-tools.ts → mcp-tool-handlers.ts}

@@ -1,61 +1,21 @@
-import { Effect, Schema, Tool, Toolkit } 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 { coachTool, coachToolHandler } from './mcp-coach.ts'
-
-// Create toolkit with tools and handlers following Tim Smart's pattern
-export const livestoreToolkit = Toolkit.make(
-  coachTool,
-
-  Tool.make('livestore_generate_schema', {
-    description:
-      'Generate a LiveStore schema for a specific use case. Choose from predefined types (todo, blog, social, ecommerce) or request a custom schema by providing a description.',
-    parameters: {
-      schemaType: Schema.String.annotations({
-        description: "Schema type: 'todo', 'blog', 'social', 'ecommerce', or 'custom'",
-      }),
-      customDescription: Schema.optional(
-        Schema.String.annotations({
-          description:
-            "For custom schemas: describe your data model needs (e.g., 'user management system with roles and permissions')",
-        }),
-      ),
-    },
-    success: Schema.Struct({
-      schemaCode: Schema.String.annotations({
-        description: 'The generated LiveStore schema TypeScript code',
-      }),
-      explanation: Schema.String.annotations({
-        description: 'Brief explanation of the schema structure',
-      }),
-    }),
-  }),
+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'
+
+/** Layer providing FileSystem and HttpClient for sync operations */
+const SyncOpsLayer = Layer.mergeAll(PlatformNode.NodeFileSystem.layer, FetchHttpClient.layer)
 
-  Tool.make('livestore_get_example_schema', {
-    description:
-      'Get a complete example LiveStore schema with TypeScript code. Returns ready-to-use schema definitions for common application types.',
-    parameters: {
-      type: Schema.String.annotations({
-        description: "Example type: 'todo', 'blog', 'social', or 'ecommerce'",
-      }),
-    },
-    success: Schema.Struct({
-      schemaCode: Schema.String.annotations({
-        description: 'The complete LiveStore schema code',
-      }),
-      description: Schema.String.annotations({
-        description: 'Description of what this schema models',
-      }),
-    }),
-  })
-    .annotate(Tool.Readonly, true)
-    .annotate(Tool.Destructive, false),
-)
-
-// Tool handlers using Tim Smart's pattern
-export const toolHandlers = livestoreToolkit.of({
+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 }) {
@@ -80,7 +40,7 @@ export const toolHandlers = livestoreToolkit.of({
         explanation = 'E-commerce schema with products, categories, orders, and inventory'
         break
       case 'custom': {
-        if (!customDescription) {
+        if (customDescription == null) {
           schemaCode = `// Custom schema requested but no description provided
 import { Schema } from '@livestore/livestore'
 
@@ -99,11 +59,11 @@ export const schema = Schema.create({
         }
 
         // Generate a basic custom schema based on description
-        const tableName = customDescription.toLowerCase().includes('user')
+        const tableName = customDescription.toLowerCase().includes('user') === true
           ? 'users'
-          : customDescription.toLowerCase().includes('product')
+          : customDescription.toLowerCase().includes('product') === true
             ? 'products'
-            : customDescription.toLowerCase().includes('post')
+            : customDescription.toLowerCase().includes('post') === true
               ? 'posts'
               : 'items'
 
@@ -166,4 +126,80 @@ export const schema = Schema.create({
 
     return { schemaCode, description }
   }),
+
+  // Connect the single in-process LiveStore instance from user module
+  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())
+
+    return {
+      storeId: store.storeId,
+      clientId: store.clientId,
+      sessionId: store.sessionId,
+      schemaInfo: {
+        tableNames,
+        eventNames,
+      },
+    }
+  }),
+
+  // Execute a raw SQL query against the local client DB
+  livestore_instance_query: Effect.fnUntraced(function* ({ sql, bindValues }) {
+    return yield* Runtime.query({ sql, bindValues })
+  }),
+
+  // Validate and commit events
+  livestore_instance_commit_events: Effect.fnUntraced(function* ({ events }) {
+    return yield* Runtime.commit({ events })
+  }),
+
+  // Status
+  livestore_instance_status: Effect.fnUntraced(function* () {
+    return yield* Runtime.status
+  }),
+
+  // Disconnect
+  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,
+    }
+  }),
 })