@livestore/cli 0.4.0-dev.18 → 0.4.0-dev.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/cli",
-  "version": "0.4.0-dev.18",
+  "version": "0.4.0-dev.20",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -11,16 +11,17 @@
   },
   "dependencies": {
     "@effect/ai-openai": "0.32.0",
-    "@livestore/adapter-node": "0.4.0-dev.18",
-    "@livestore/common": "0.4.0-dev.18",
-    "@livestore/peer-deps": "0.4.0-dev.18",
-    "@livestore/sync-cf": "0.4.0-dev.18",
-    "@livestore/livestore": "0.4.0-dev.18",
-    "@livestore/utils": "0.4.0-dev.18"
+    "@livestore/adapter-node": "0.4.0-dev.20",
+    "@livestore/common": "0.4.0-dev.20",
+    "@livestore/utils": "0.4.0-dev.20",
+    "@livestore/livestore": "0.4.0-dev.20",
+    "@livestore/peer-deps": "0.4.0-dev.20",
+    "@livestore/sync-cf": "0.4.0-dev.20"
   },
   "devDependencies": {
-    "@types/node": "24.9.2",
-    "typescript": "5.9.2"
+    "@types/node": "24.10.1",
+    "typescript": "5.9.2",
+    "@livestore/utils-dev": "0.4.0-dev.20"
   },
   "files": [
     "package.json",

package/src/commands/new-project.ts

@@ -1,5 +1,6 @@
 import * as os from 'node:os'
 import * as nodePath from 'node:path'
+import { sluggify } from '@livestore/utils'
 import {
   Command,
   Console,
@@ -12,6 +13,8 @@ import {
 } from '@livestore/utils/effect'
 import { Cli } from '@livestore/utils/node'
 
+import { detectPackageManager, pmCommands } from '../package-manager.ts'
+
 // Schema for GitHub API response
 const GitHubContentSchema = Schema.Struct({
   name: Schema.String,
@@ -22,6 +25,11 @@ const GitHubContentSchema = Schema.Struct({
 
 const GitHubContentsResponseSchema = Schema.Array(GitHubContentSchema)
 
+/** Schema for parsing package.json scripts (dev or start) */
+const PackageJsonScriptsSchema = Schema.Struct({
+  scripts: Schema.Union(Schema.Struct({ dev: Schema.String }), Schema.Struct({ start: Schema.String })),
+})
+
 // Error types
 export class ExampleNotFoundError extends Schema.TaggedError<ExampleNotFoundError>()('ExampleNotFoundError', {
   exampleName: Schema.String,
@@ -40,11 +48,11 @@ export class DirectoryExistsError extends Schema.TaggedError<DirectoryExistsErro
 }) {}
 
 // Fetch available examples from GitHub
-const fetchExamples = (branch: string) =>
+const fetchExamples = (ref: string) =>
   Effect.gen(function* () {
-    const url = `https://api.github.com/repos/livestorejs/livestore/contents/examples?ref=${branch}`
+    const url = `https://api.github.com/repos/livestorejs/livestore/contents/examples?ref=${ref}`
 
-    yield* Effect.log(`Fetching examples from branch: ${branch}`)
+    yield* Effect.log(`Fetching examples from ref: ${ref}`)
 
     const request = HttpClientRequest.get(url)
     const response = yield* HttpClient.execute(request).pipe(
@@ -100,13 +108,13 @@ const selectExample = (examples: string[]) =>
   })
 
 // Download and extract example using tiged approach
-const downloadExample = (exampleName: string, branch: string, destinationPath: string) =>
+const downloadExample = (exampleName: string, ref: string, destinationPath: string) =>
   Effect.gen(function* () {
-    yield* Console.log(`📥 Downloading example "${exampleName}" from branch "${branch}"...`)
+    yield* Console.log(`📥 Downloading example "${exampleName}" from ref "${ref}"...`)
 
     const tempDir = yield* Effect.sync(() => os.tmpdir())
-    const tarballPath = nodePath.join(tempDir, `livestore-${branch}-${Date.now()}.tar.gz`)
-    const tarballUrl = `https://api.github.com/repos/livestorejs/livestore/tarball/${branch}`
+    const tarballPath = nodePath.join(tempDir, `livestore-${sluggify(ref)}-${Date.now()}.tar.gz`)
+    const tarballUrl = `https://api.github.com/repos/livestorejs/livestore/tarball/${ref}`
 
     // Download tarball directly
     const request = HttpClientRequest.get(tarballUrl)
@@ -199,9 +207,14 @@ export const createCommand = Cli.Command.make(
       Cli.Options.optional,
       Cli.Options.withDescription('Example name to create (bypasses interactive selection)'),
     ),
-    branch: Cli.Options.text('branch').pipe(
+    ref: Cli.Options.text('ref').pipe(
+      Cli.Options.withAlias('commit'),
+      Cli.Options.withAlias('branch'),
+      Cli.Options.withAlias('tag'),
       Cli.Options.withDefault('dev'),
-      Cli.Options.withDescription('Branch to fetch examples from'),
+      Cli.Options.withDescription(
+        'The name of the commit/branch/tag to fetch examples from. Pull requests refs must be fully-formed (e.g., `refs/pull/123/merge`).',
+      ),
     ),
     path: Cli.Args.text({ name: 'path' }).pipe(
       Cli.Args.optional,
@@ -210,17 +223,17 @@ export const createCommand = Cli.Command.make(
   },
   Effect.fn(function* ({
     example,
-    branch,
+    ref,
     path,
   }: {
     example: Option.Option<string>
-    branch: string
+    ref: string
     path: Option.Option<string>
   }) {
     yield* Effect.log('🚀 Creating new LiveStore project...')
 
     // Fetch available examples
-    const examples = yield* fetchExamples(branch)
+    const examples = yield* fetchExamples(ref)
 
     if (examples.length === 0) {
       yield* Console.log('❌ No examples found in the repository')
@@ -249,15 +262,45 @@ export const createCommand = Cli.Command.make(
     const destinationPath = Option.isSome(path) ? nodePath.resolve(path.value) : nodePath.resolve(selectedExample)
 
     // Download and extract the example
-    yield* downloadExample(selectedExample, branch, destinationPath)
+    yield* downloadExample(selectedExample, ref, destinationPath)
+
+    // Detect available run script (dev or start) from the created project's package.json.
+    // Some examples use "dev" (web projects), others use "start" (Expo projects),
+    // and some have no run script at all (e.g., node-effect-cli).
+    const fs = yield* FileSystem.FileSystem
+    const packageJsonPath = nodePath.join(destinationPath, 'package.json')
+    const packageJsonContent = yield* fs.readFileString(packageJsonPath)
+    const runScript = yield* Schema.decodeUnknown(Schema.parseJson(PackageJsonScriptsSchema))(packageJsonContent).pipe(
+      Effect.map((pkg) => ('dev' in pkg.scripts ? ('dev' as const) : ('start' as const))),
+      Effect.orElseSucceed(() => undefined),
+    )
+
+    // Detect which package manager was used to invoke the CLI (via npm_config_user_agent).
+    // This ensures the "next steps" instructions match how the user ran the create command.
+    const pmResult = detectPackageManager()
 
-    // Success message
     yield* Console.log('\n🎉 Project created successfully!')
     yield* Console.log(`📁 Location: ${destinationPath}`)
     yield* Console.log('\n📋 Next steps:')
     yield* Console.log(`   cd ${nodePath.basename(destinationPath)}`)
-    yield* Console.log('   pnpm install    # Install dependencies')
-    yield* Console.log('   pnpm dev        # Start development server')
+
+    // Yarn is not recommended for LiveStore projects. When detected, show a warning
+    // and suggest using bun instead for the next steps.
+    if (pmResult._tag === 'unsupported') {
+      yield* Console.log('   bun install    # Install dependencies (yarn is not recommended)')
+      if (runScript !== undefined) {
+        yield* Console.log(`   bun ${runScript}        # Start development server`)
+      }
+      yield* Console.log('\n⚠️  Yarn is not recommended for LiveStore projects.')
+      yield* Console.log('   We recommend using bun, pnpm, or npm instead.')
+      yield* Console.log('   The commands above use bun by default.')
+    } else {
+      const pm = pmResult.pm
+      yield* Console.log(`   ${pmCommands.install[pm]}    # Install dependencies`)
+      if (runScript !== undefined) {
+        yield* Console.log(`   ${pmCommands.run[pm](runScript)}        # Start development server`)
+      }
+    }
     yield* Console.log('\n💡 Tip: Run `git init` if you want to initialize version control')
   }),
 )

package/src/mcp-runtime/runtime.ts

@@ -155,8 +155,8 @@ export const commit = ({ events }: { events: ReadonlyArray<{ name: string; args:
       return yield* Effect.dieMessage('LiveStore not connected. Call livestore_instance_connect first.')
     }
     const s = opt.value
-    const PartialEventSchema = LiveStoreEvent.makeEventDefPartialSchema(s.schema) as Schema.Schema<any>
-    const decoded = events.map((e) => Schema.decodeSync(PartialEventSchema)(e))
+    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 }
   }).pipe(Effect.withSpan('mcp-runtime:commit'))

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/')) return { _tag: 'supported', pm: 'bun' }
+  if (userAgent.startsWith('pnpm/')) return { _tag: 'supported', pm: 'pnpm' }
+  if (userAgent.startsWith('npm/')) return { _tag: 'supported', pm: 'npm' }
+  if (userAgent.startsWith('yarn/')) 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