@livestore/cli 0.4.0-dev.9 → 0.4.0

package/src/mcp-runtime/runtime.ts

@@ -0,0 +1,147 @@
+import { makeAdapter as makeNodeAdapter } from '@livestore/adapter-node'
+import { UnknownError } from '@livestore/common'
+import { LiveStoreEvent, SystemTables } from '@livestore/common/schema'
+import type { Store } from '@livestore/livestore'
+import { createStorePromise } from '@livestore/livestore'
+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 = ({
+  configPath,
+  storeId,
+  clientId,
+  sessionId,
+}: {
+  configPath: string
+  storeId: string
+  clientId?: string
+  sessionId?: string
+}): Effect.Effect<Store<any>, UnknownError> =>
+  Effect.gen(function* () {
+    if (storeId === '' || typeof storeId !== 'string') {
+      return yield* UnknownError.make({ cause: new Error('Invalid storeId: expected a non-empty string') })
+    }
+
+    const { schema, syncBackendConstructor, syncPayloadSchema, syncPayload } = yield* loadModuleConfig({ configPath })
+
+    // Build Node adapter internally
+    const adapter = makeNodeAdapter({
+      storage: { type: 'in-memory' },
+      ...(clientId !== undefined && clientId !== '' ? { clientId } : {}),
+      ...(sessionId !== undefined && sessionId !== '' ? { sessionId } : {}),
+      sync: {
+        backend: syncBackendConstructor,
+        initialSyncOptions: { _tag: 'Blocking', timeout: 5000 },
+        onSyncError: 'shutdown',
+      },
+    })
+
+    // Create the store
+    const s = yield* Effect.promise(() =>
+      createStorePromise({
+        schema,
+        storeId,
+        adapter,
+        disableDevtools: true,
+        syncPayload,
+        syncPayloadSchema,
+      }),
+    )
+
+    // Replace existing store if any
+    if (store !== undefined) {
+      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))
+
+export const status = Effect.gen(function* () {
+  const opt = yield* getStore
+  if (opt._tag === 'None') {
+    return {
+      _tag: 'disconnected' as const,
+    }
+  }
+  const s = opt.value
+  const tableCounts = Array.from(s.schema.state.sqlite.tables.keys())
+    .filter((name) => !SystemTables.isStateSystemTable(name))
+    .reduce(
+      (acc, name) => {
+        acc[name] = s.query(s.schema.state.sqlite.tables.get(name)!.count())
+        return acc
+      },
+      {} as Record<string, number>,
+    )
+
+  return {
+    _tag: 'connected' as const,
+    storeId: s.storeId,
+    clientId: s.clientId,
+    sessionId: s.sessionId,
+    tableCounts,
+  }
+}).pipe(Effect.withSpan('mcp-runtime:status'))
+
+export const query = Effect.fn('mcp-runtime:query')(function* ({
+  sql,
+  bindValues,
+}: {
+  sql: string
+  bindValues?: readonly any[] | Record<string, unknown>
+}) {
+  const opt = yield* getStore
+  if (opt._tag === 'None') {
+    return yield* Effect.dieMessage('LiveStore not connected. Call livestore_instance_connect first.')
+  }
+  const s = opt.value
+
+  const rows = s.query<Array<Record<string, unknown>>>({ query: sql, bindValues: (bindValues as any) ?? [] })
+  const jsonRows = rows.map((r) => Object.fromEntries(Object.entries(r).map(([k, v]) => [k, v as Schema.JsonValue])))
+  return { rows: jsonRows, rowCount: jsonRows.length }
+})
+
+export const commit = Effect.fn('mcp-runtime:commit')(function* ({
+  events,
+}: {
+  events: ReadonlyArray<{ name: string; args: Schema.JsonValue }>
+}) {
+  const opt = yield* getStore
+  if (opt._tag === 'None') {
+    return yield* Effect.dieMessage('LiveStore not connected. Call livestore_instance_connect first.')
+  }
+  const s = opt.value
+  const InputEventSchema = LiveStoreEvent.Input.makeSchema(s.schema) as Schema.Schema<any>
+  const decoded = events.map((e) => Schema.decodeSync(InputEventSchema)(e))
+  s.commit(...decoded)
+  return { committed: decoded.length }
+})
+
+export const disconnect = Effect.promise(async () => {
+  if (store !== undefined) {
+    try {
+      await store.shutdownPromise()
+    } catch {}
+    store = undefined
+  }
+  return { _tag: 'disconnected' as const }
+}).pipe(Effect.withSpan('mcp-runtime:disconnect'))

package/src/module-loader.ts

@@ -0,0 +1,94 @@
+/**
+ * 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) === true ? configPath : path.resolve(process.cwd(), configPath)
+
+    const fs = yield* FileSystem.FileSystem
+    const exists = yield* fs.exists(abs).pipe(UnknownError.mapToUnknownError)
+    if (exists === false) {
+      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)?.schema
+    if (isLiveStoreSchema(schema) === false) {
+      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)?.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)?.syncPayloadSchema
+    const syncPayloadSchema =
+      syncPayloadSchemaExport === undefined
+        ? Schema.JsonValue
+        : Schema.isSchema(syncPayloadSchemaExport) === true
+          ? (syncPayloadSchemaExport as Schema.Schema<any>)
+          : shouldNeverHappen(
+              `Exported 'syncPayloadSchema' from ${abs} must be an Effect Schema (received ${typeof syncPayloadSchemaExport}).`,
+            )
+
+    const syncPayloadExport = (mod)?.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'))

package/src/package-manager.test.ts

@@ -0,0 +1,66 @@
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import { detectPackageManager, pmCommands } from './package-manager.ts'
+
+Vitest.describe('detectPackageManager', () => {
+  Vitest.it('detects npm from user agent', () => {
+    const result = detectPackageManager('npm/10.2.4 node/v20.11.0 darwin arm64 workspaces/false')
+    Vitest.expect(result).toEqual({ _tag: 'supported', pm: 'npm' })
+  })
+
+  Vitest.it('detects pnpm from user agent', () => {
+    const result = detectPackageManager('pnpm/9.0.6 npm/? node/v22.0.0 darwin arm64')
+    Vitest.expect(result).toEqual({ _tag: 'supported', pm: 'pnpm' })
+  })
+
+  Vitest.it('detects yarn as unsupported', () => {
+    const result = detectPackageManager('yarn/1.22.19 npm/? node/v20.11.0 darwin arm64')
+    Vitest.expect(result).toEqual({ _tag: 'unsupported', pm: 'yarn' })
+  })
+
+  Vitest.it('detects bun from user agent', () => {
+    const result = detectPackageManager('bun/1.1.7')
+    Vitest.expect(result).toEqual({ _tag: 'supported', pm: 'bun' })
+  })
+
+  Vitest.it('falls back to bun for empty user agent', () => {
+    const result = detectPackageManager('')
+    Vitest.expect(result).toEqual({ _tag: 'supported', pm: 'bun' })
+  })
+
+  Vitest.it('uses process.env.npm_config_user_agent when no argument provided', () => {
+    const originalEnv = process.env.npm_config_user_agent
+    try {
+      process.env.npm_config_user_agent = 'pnpm/9.0.6'
+      const result = detectPackageManager()
+      Vitest.expect(result).toEqual({ _tag: 'supported', pm: 'pnpm' })
+    } finally {
+      process.env.npm_config_user_agent = originalEnv
+    }
+  })
+
+  Vitest.it('falls back to bun for unknown user agent', () => {
+    const result = detectPackageManager('some-unknown-tool/1.0.0')
+    Vitest.expect(result).toEqual({ _tag: 'supported', pm: 'bun' })
+  })
+})
+
+Vitest.describe('pmCommands', () => {
+  Vitest.it('provides correct install commands for each package manager', () => {
+    Vitest.expect(pmCommands.install.npm).toBe('npm install')
+    Vitest.expect(pmCommands.install.pnpm).toBe('pnpm install')
+    Vitest.expect(pmCommands.install.bun).toBe('bun install')
+  })
+
+  Vitest.it('provides correct run commands for dev script', () => {
+    Vitest.expect(pmCommands.run.npm('dev')).toBe('npm run dev')
+    Vitest.expect(pmCommands.run.pnpm('dev')).toBe('pnpm dev')
+    Vitest.expect(pmCommands.run.bun('dev')).toBe('bun dev')
+  })
+
+  Vitest.it('provides correct run commands for start script', () => {
+    Vitest.expect(pmCommands.run.npm('start')).toBe('npm run start')
+    Vitest.expect(pmCommands.run.pnpm('start')).toBe('pnpm start')
+    Vitest.expect(pmCommands.run.bun('start')).toBe('bun start')
+  })
+})

package/src/package-manager.ts

@@ -0,0 +1,44 @@
+/**
+ * Supported package managers for LiveStore projects.
+ * Yarn is explicitly not supported due to compatibility issues.
+ */
+export type PackageManager = 'npm' | 'pnpm' | 'bun'
+
+/**
+ * Result of package manager detection.
+ * Returns 'unsupported' for yarn to allow the CLI to show a warning message.
+ */
+export type DetectPackageManagerResult = { _tag: 'supported'; pm: PackageManager } | { _tag: 'unsupported'; pm: 'yarn' }
+
+/**
+ * Detects the package manager used to invoke the CLI based on the `npm_config_user_agent`
+ * environment variable. This env var is set by npm, pnpm, yarn, and bun when running scripts.
+ *
+ * - Returns 'unsupported' for yarn so the CLI can show a recommendation to use bun instead
+ * - Falls back to 'bun' when detection fails (e.g., when run directly without a package manager)
+ */
+export const detectPackageManager = (
+  userAgent = process.env.npm_config_user_agent ?? '',
+): DetectPackageManagerResult => {
+  if (userAgent.startsWith('bun/') === true) return { _tag: 'supported', pm: 'bun' }
+  if (userAgent.startsWith('pnpm/') === true) return { _tag: 'supported', pm: 'pnpm' }
+  if (userAgent.startsWith('npm/') === true) return { _tag: 'supported', pm: 'npm' }
+  if (userAgent.startsWith('yarn/') === true) return { _tag: 'unsupported', pm: 'yarn' }
+
+  // Default to bun when the package manager can't be detected
+  return { _tag: 'supported', pm: 'bun' }
+}
+
+/** Package manager command templates */
+export const pmCommands = {
+  install: {
+    npm: 'npm install',
+    pnpm: 'pnpm install',
+    bun: 'bun install',
+  },
+  run: {
+    npm: (script: string) => `npm run ${script}`,
+    pnpm: (script: string) => `pnpm ${script}`,
+    bun: (script: string) => `bun ${script}`,
+  },
+} as const