@livestore/cli 0.4.0 → 0.5.0-dev.1

package/src/bin.ts

@@ -1,25 +1,26 @@
 #!/usr/bin/env node
 
 import { liveStoreVersion } from '@livestore/common'
-import { Console, Effect, FetchHttpClient, Layer, Logger, LogLevel } from '@livestore/utils/effect'
+import { Console, Effect, FetchHttpClient, Layer, Logger, References } from '@livestore/utils/effect'
 import { Cli, PlatformNode } from '@livestore/utils/node'
 
 import { command } from './cli.ts'
 
 const cli = Cli.Command.run(command, {
-  name: 'livestore',
   version: liveStoreVersion,
 })
 
-const showExperimentalWarning = Console.log('⚠️  Warning: LiveStore CLI is experimental and under active development')
+const showExperimentalWarning = Console.error('⚠️  Warning: LiveStore CLI is experimental and under active development')
 
 const layer = Layer.mergeAll(
-  PlatformNode.NodeContext.layer,
+  PlatformNode.NodeServices.layer,
   FetchHttpClient.layer,
-  Logger.minimumLogLevel(LogLevel.Info),
+  Layer.succeed(References.MinimumLogLevel, 'Info'),
+  // Keep stdout available for command data and protocol transports such as MCP stdio.
+  Layer.succeed(Logger.LogToStderr, true),
 )
 
 Effect.gen(function* () {
   yield* showExperimentalWarning
-  return yield* cli(process.argv)
+  return yield* cli
 }).pipe(Effect.provide(layer), PlatformNode.NodeRuntime.runMain)

package/src/cli.ts

@@ -5,5 +5,5 @@ import { mcpCommand } from './commands/mcp.ts'
 import { createCommand } from './commands/new-project.ts'
 
 export const command = Cli.Command.make('livestore', {
-  verbose: Cli.Options.boolean('verbose').pipe(Cli.Options.withDefault(false)),
+  verbose: Cli.Flag.Boolean('verbose').pipe(Cli.Flag.withDefault(false)),
 }).pipe(Cli.Command.withSubcommands([mcpCommand, createCommand, syncCommand]))

package/src/commands/__fixtures__/mcp-protocol-server.ts

@@ -0,0 +1,12 @@
+import { McpServer } from 'effect/ai'
+
+import { Effect, Layer } from '@livestore/utils/effect'
+import { PlatformNode } from '@livestore/utils/node'
+
+import { supportedMcpProtocols } from '../mcp-protocols.ts'
+
+McpServer.layerStdio({
+  name: 'livestore-mcp-protocol-test',
+  version: '0.0.0',
+  protocols: supportedMcpProtocols,
+}).pipe(Layer.provide(PlatformNode.NodeStdio.layer), Layer.launch, Effect.scoped, PlatformNode.NodeRuntime.runMain)

package/src/commands/import-export.ts

@@ -6,8 +6,8 @@ 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 jsonStringifyPretty = (value: SyncOps.ExportFile) => JSON.stringify(value, null, 2)
+const jsonParse = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown))
 
 const LARGE_EVENT_WARNING_THRESHOLD = 100_000
 
@@ -171,19 +171,19 @@ const importEvents = ({
 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'),
+    config: Cli.Flag.String('config').pipe(
+      Cli.Flag.withAlias('c'),
+      Cli.Flag.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'),
+    storeId: Cli.Flag.String('store-id').pipe(
+      Cli.Flag.withAlias('i'),
+      Cli.Flag.withDescription('Store identifier'),
     ),
-    clientId: Cli.Options.text('client-id').pipe(
-      Cli.Options.withDefault('cli-export'),
-      Cli.Options.withDescription('Client identifier for the sync connection'),
+    clientId: Cli.Flag.String('client-id').pipe(
+      Cli.Flag.withDefault('cli-export'),
+      Cli.Flag.withDescription('Client identifier for the sync connection'),
     ),
-    output: Cli.Args.text({ name: 'file' }).pipe(Cli.Args.withDescription('Output JSON file path')),
+    output: Cli.Argument.String('file').pipe(Cli.Argument.withDescription('Output JSON file path')),
   },
   Effect.fn(function* ({
     config,
@@ -218,28 +218,28 @@ export const exportCommand = Cli.Command.make(
 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'),
+    config: Cli.Flag.String('config').pipe(
+      Cli.Flag.withAlias('c'),
+      Cli.Flag.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'),
+    storeId: Cli.Flag.String('store-id').pipe(
+      Cli.Flag.withAlias('i'),
+      Cli.Flag.withDescription('Store identifier'),
     ),
-    clientId: Cli.Options.text('client-id').pipe(
-      Cli.Options.withDefault('cli-import'),
-      Cli.Options.withDescription('Client identifier for the sync connection'),
+    clientId: Cli.Flag.String('client-id').pipe(
+      Cli.Flag.withDefault('cli-import'),
+      Cli.Flag.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'),
+    force: Cli.Flag.Boolean('force').pipe(
+      Cli.Flag.withAlias('f'),
+      Cli.Flag.withDefault(false),
+      Cli.Flag.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'),
+    dryRun: Cli.Flag.Boolean('dry-run').pipe(
+      Cli.Flag.withDefault(false),
+      Cli.Flag.withDescription('Validate the import file without actually importing'),
     ),
-    input: Cli.Args.text({ name: 'file' }).pipe(Cli.Args.withDescription('Input JSON file to import')),
+    input: Cli.Argument.String('file').pipe(Cli.Argument.withDescription('Input JSON file to import')),
   },
   Effect.fn(function* ({
     config,

package/src/commands/mcp-coach.ts

@@ -1,36 +1,36 @@
-import { LanguageModel } from '@effect/ai'
+import { AiError, LanguageModel, Prompt, Tool } from 'effect/ai'
 import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai'
 
-import { AiError, Config, Effect, FetchHttpClient, Layer, Prompt, Schema, Tool } from '@livestore/utils/effect'
+import { Config, Effect, FetchHttpClient, Layer, Schema } from '@livestore/utils/effect'
 
 // Define the coach tool that analyzes LiveStore usage
 export const coachTool = Tool.make('livestore_coach', {
   description:
     'Analyze LiveStore code (schemas, queries, mutations, etc.) and provide AI-powered feedback on best practices, performance, and improvements.',
-  parameters: {
-    code: Schema.String.annotations({
+  parameters: Schema.Struct({
+    code: Schema.String.annotate({
       description: 'The LiveStore code to analyze (TypeScript/JavaScript)',
     }),
     codeType: Schema.optional(
-      Schema.String.annotations({
+      Schema.String.annotate({
         description: "Type of code being analyzed: 'schema', 'query', 'mutation', 'component', or 'general'",
       }),
     ),
-  },
+  }),
   success: Schema.Struct({
-    feedback: Schema.String.annotations({
+    feedback: Schema.String.annotate({
       description: 'AI-generated feedback and recommendations for the code',
     }),
     score: Schema.optional(
-      Schema.Number.annotations({
+      Schema.Finite.annotate({
         description: 'Code quality score from 1-10 (optional)',
       }),
     ),
     suggestions: Schema.Array(
-      Schema.String.annotations({
+      Schema.String.annotate({
         description: 'Specific actionable suggestions for improvement',
       }),
-    ).annotations({
+    ).annotate({
       description: 'List of specific improvement suggestions',
     }),
   }),
@@ -39,7 +39,7 @@ export const coachTool = Tool.make('livestore_coach', {
 
 /** 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(OpenAiClient.layerConfig({ apiKey: Config.Redacted('OPENAI_API_KEY') })),
   Layer.provide(FetchHttpClient.layer),
 )
 
@@ -58,7 +58,8 @@ type CoachToolResult = {
 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 codeTypeContext =
+        codeType !== undefined ? `This is ${codeType} code using LiveStore. ` : 'This is LiveStore code. '
 
       const prompt = Prompt.makeMessage('user', {
         content: [

package/src/commands/mcp-protocols.test.ts

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import { supportedMcpProtocols } from './mcp-protocols.ts'
+
+const protocolVersions = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'] as const
+
+Vitest.describe('supportedMcpProtocols', () => {
+  Vitest.it('keeps the fallback protocol newest-first', () => {
+    Vitest.expect(supportedMcpProtocols.map((protocol) => protocol.protocolVersion)).toEqual(protocolVersions)
+  })
+
+  Vitest.it.each(protocolVersions)('negotiates an exact %s stdio initialize offer', async (protocolVersion) => {
+    const response = await initialize(protocolVersion)
+
+    Vitest.expect(response.result?.protocolVersion).toBe(protocolVersion)
+  })
+})
+
+const initialize = (protocolVersion: (typeof protocolVersions)[number]) =>
+  new Promise<InitializeResponse>((resolve, reject) => {
+    const child = spawn('bun', [new URL('./__fixtures__/mcp-protocol-server.ts', import.meta.url).pathname], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+
+    const timeout = setTimeout(() => {
+      child.kill('SIGTERM')
+      reject(new Error(`MCP initialize timed out. stdout=${stdout} stderr=${stderr}`))
+    }, 5_000)
+
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      if (stdout.endsWith('\n') === false) return
+
+      try {
+        const response = JSON.parse(stdout.trim()) as InitializeResponse
+        clearTimeout(timeout)
+        child.kill('SIGTERM')
+        resolve(response)
+      } catch (error) {
+        clearTimeout(timeout)
+        child.kill('SIGTERM')
+        reject(error)
+      }
+    })
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', (error) => {
+      clearTimeout(timeout)
+      reject(error)
+    })
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion,
+          capabilities: {},
+          clientInfo: { name: 'livestore-mcp-protocol-test', version: '0.0.0' },
+        },
+      })}\n`,
+    )
+  })
+
+interface InitializeResponse {
+  readonly result?: {
+    readonly protocolVersion?: string
+  }
+}

package/src/commands/mcp-protocols.ts

@@ -0,0 +1,12 @@
+import { McpProtocol } from 'effect/ai'
+
+/**
+ * MCP stdio selects an exact offered version when available and otherwise
+ * falls back to the first adapter, so keep every supported adapter newest-first.
+ */
+export const supportedMcpProtocols = [
+  McpProtocol.v2025_11_25,
+  McpProtocol.v2025_06_18,
+  McpProtocol.v2025_03_26,
+  McpProtocol.v2024_11_05,
+] as const

package/src/commands/mcp-stdio.test.ts

@@ -0,0 +1,93 @@
+import { spawn } from 'node:child_process'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+Vitest.describe('mcp server stdio', () => {
+  Vitest.it('reserves stdout for JSON-RPC messages', async () => {
+    const response = await initialize()
+
+    Vitest.expect(response.result?.protocolVersion).toBe('2025-06-18')
+  })
+})
+
+/** Exercises the real CLI entrypoint so root-level warnings and logs cannot corrupt MCP framing. */
+const initialize = () =>
+  new Promise<InitializeResponse>((resolve, reject) => {
+    const child = spawn('bun', [new URL('../bin.ts', import.meta.url).pathname, 'mcp', 'server'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdoutBuffer = ''
+    let stderr = ''
+    let settled = false
+
+    const finish = (result: { readonly response: InitializeResponse } | { readonly error: unknown }) => {
+      if (settled === true) return
+      settled = true
+      clearTimeout(timeout)
+      child.kill('SIGTERM')
+      if ('error' in result) reject(result.error)
+      else resolve(result.response)
+    }
+
+    const timeout = setTimeout(() => {
+      finish({ error: new Error(`MCP initialize timed out. stdout=${stdoutBuffer} stderr=${stderr}`) })
+    }, 5_000)
+
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdoutBuffer += chunk
+      const lines = stdoutBuffer.split('\n')
+      stdoutBuffer = lines.pop() ?? ''
+
+      for (const line of lines) {
+        if (line.length === 0) continue
+
+        try {
+          const message = JSON.parse(line) as InitializeResponse
+          if (message.jsonrpc !== '2.0') {
+            finish({ error: new Error(`MCP stdout contained a non-JSON-RPC message: ${line}`) })
+            return
+          }
+          if (message.id === 1) {
+            finish({ response: message })
+            return
+          }
+        } catch (error) {
+          finish({ error: new Error(`MCP stdout contained invalid JSON: ${line}`, { cause: error }) })
+          return
+        }
+      }
+    })
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', (error) => {
+      finish({ error })
+    })
+    child.on('exit', (code) => {
+      if (settled === false) {
+        finish({ error: new Error(`MCP server exited before initialize completed (code ${code}). stderr=${stderr}`) })
+      }
+    })
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-06-18',
+          capabilities: {},
+          clientInfo: { name: 'livestore-mcp-stdio-test', version: '0.0.0' },
+        },
+      })}\n`,
+    )
+  })
+
+interface InitializeResponse {
+  readonly jsonrpc?: unknown
+  readonly id?: unknown
+  readonly result?: {
+    readonly protocolVersion?: string
+  }
+}

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

@@ -1,4 +1,6 @@
-import { Effect, FetchHttpClient, Layer, type Toolkit } from '@livestore/utils/effect'
+import { type Toolkit } from 'effect/ai'
+
+import { Effect, FetchHttpClient, Layer } from '@livestore/utils/effect'
 import { PlatformNode } from '@livestore/utils/node'
 
 import { blogSchemaContent } from '../mcp-content/schemas/blog.ts'
@@ -59,13 +61,14 @@ export const schema = Schema.create({
         }
 
         // Generate a basic custom schema based on description
-        const tableName = customDescription.toLowerCase().includes('user') === true
-          ? 'users'
-          : customDescription.toLowerCase().includes('product') === true
-            ? 'products'
-            : customDescription.toLowerCase().includes('post') === true
-              ? 'posts'
-              : 'items'
+        const tableName =
+          customDescription.toLowerCase().includes('user') === true
+            ? 'users'
+            : customDescription.toLowerCase().includes('product') === true
+              ? 'products'
+              : customDescription.toLowerCase().includes('post') === true
+                ? 'posts'
+                : 'items'
 
         schemaCode = `// Custom schema based on: ${customDescription}
 import { Schema } from '@livestore/livestore'

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

@@ -0,0 +1,13 @@
+import { Tool } from 'effect/ai'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import { livestoreToolkit } from './mcp-tools-defs.ts'
+
+Vitest.describe('livestoreToolkit', () => {
+  Vitest.it('exposes MCP-compatible object parameter schemas', () => {
+    for (const tool of Object.values(livestoreToolkit.tools)) {
+      Vitest.expect(Tool.getJsonSchema(tool), tool.name).toMatchObject({ type: 'object' })
+    }
+  })
+})