@livestore/cli 0.4.0-dev.9 → 0.5.0-dev.0

package/src/commands/new-project.ts

@@ -1,7 +1,10 @@
 import * as os from 'node:os'
 import * as nodePath from 'node:path'
+
+import { sluggify } from '@livestore/utils'
 import {
-  Command,
+  ChildProcess,
+  ChildProcessSpawner,
   Console,
   Effect,
   FileSystem,
@@ -12,60 +15,86 @@ 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,
-  type: Schema.Literal('dir', 'file'),
+  type: Schema.Literals(['dir', 'file']),
   path: Schema.String,
   download_url: Schema.NullOr(Schema.String),
 })
 
 const GitHubContentsResponseSchema = Schema.Array(GitHubContentSchema)
 
+const githubRequest = (url: string) => {
+  const request = HttpClientRequest.get(url).pipe(HttpClientRequest.setHeader('accept', 'application/vnd.github+json'))
+  const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN
+  return token === undefined ? request : request.pipe(HttpClientRequest.setHeader('authorization', `Bearer ${token}`))
+}
+
+/** 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', {
+export class ExampleNotFoundError extends Schema.TaggedError<ExampleNotFoundError>(
+  '~@livestore/cli/ExampleNotFoundError',
+)('ExampleNotFoundError', {
   exampleName: Schema.String,
   availableExamples: Schema.Array(Schema.String),
   message: Schema.String,
 }) {}
 
-export class NetworkError extends Schema.TaggedError<NetworkError>()('NetworkError', {
+export class NetworkError extends Schema.TaggedError<NetworkError>('~@livestore/cli/NetworkError')('NetworkError', {
   cause: Schema.Unknown,
   message: Schema.String,
 }) {}
 
-export class DirectoryExistsError extends Schema.TaggedError<DirectoryExistsError>()('DirectoryExistsError', {
+export class DirectoryExistsError extends Schema.TaggedError<DirectoryExistsError>(
+  '~@livestore/cli/DirectoryExistsError',
+)('DirectoryExistsError', {
   path: Schema.String,
   message: Schema.String,
 }) {}
 
+export class NoExamplesError extends Schema.TaggedError<NoExamplesError>('~@livestore/cli/NoExamplesError')(
+  'NoExamplesError',
+  {
+    message: Schema.String,
+  },
+) {}
+
 // 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 request = githubRequest(url)
     const response = yield* HttpClient.execute(request).pipe(
       Effect.scoped,
-      Effect.catchAll(
+      Effect.catch(
         (error) =>
           new NetworkError({
             cause: error,
-            message: `Failed to fetch examples from GitHub: ${error}`,
+            message: `Failed to fetch examples from GitHub: ${String(error)}`,
           }),
       ),
     )
 
     const responseText = yield* response.text
 
-    const examples = yield* Schema.decodeUnknown(GitHubContentsResponseSchema)(JSON.parse(responseText)).pipe(
-      Effect.catchAll(
+    const examples = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(GitHubContentsResponseSchema))(
+      responseText,
+    ).pipe(
+      Effect.catch(
         (error) =>
           new NetworkError({
             cause: error,
-            message: `Failed to parse GitHub API response: ${error}`,
+            message: `Failed to parse GitHub API response: ${String(error)}`,
           }),
       ),
     )
@@ -73,7 +102,7 @@ const fetchExamples = (branch: string) =>
     const exampleNames = examples
       .filter((item) => item.type === 'dir')
       .map((item) => item.name)
-      .sort()
+      .toSorted()
 
     yield* Effect.log(`Found ${exampleNames.length} examples: ${exampleNames.join(', ')}`)
 
@@ -84,7 +113,7 @@ const fetchExamples = (branch: string) =>
 const selectExample = (examples: string[]) =>
   Effect.gen(function* () {
     if (examples.length === 0) {
-      return yield* Effect.fail(new Error('No examples available'))
+      return yield* new NoExamplesError({ message: 'No examples available' })
     }
 
     const prompt = Cli.Prompt.select({
@@ -100,24 +129,26 @@ 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 spawner = yield* ChildProcessSpawner.ChildProcessSpawner
 
     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)
+    const request = githubRequest(tarballUrl)
 
     const response = yield* HttpClient.execute(request).pipe(
       Effect.scoped,
-      Effect.catchAll(
+      Effect.catch(
         (error) =>
           new NetworkError({
             cause: error,
-            message: `Failed to download tarball: ${error}`,
+            message: `Failed to download tarball: ${String(error)}`,
           }),
       ),
     )
@@ -135,14 +166,13 @@ const downloadExample = (exampleName: string, branch: string, destinationPath: s
     const extractDir = nodePath.join(tempDir, `extract-${Date.now()}`)
     yield* fs.makeDirectory(extractDir, { recursive: true })
 
-    // Extract tarball using Effect Command
-    yield* Command.make('tar', '-xzf', tarballPath, '-C', extractDir).pipe(
-      Command.exitCode,
-      Effect.catchAll(
+    // Extract tarball using a child process
+    yield* spawner.exitCode(ChildProcess.make('tar', ['-xzf', tarballPath, '-C', extractDir])).pipe(
+      Effect.catch(
         (error) =>
           new NetworkError({
             cause: error,
-            message: `Failed to extract tarball: ${error}`,
+            message: `Failed to extract tarball: ${String(error)}`,
           }),
       ),
     )
@@ -163,7 +193,7 @@ const downloadExample = (exampleName: string, branch: string, destinationPath: s
     // Check if the example exists
     const exampleExists = yield* fs.exists(exampleSourcePath)
 
-    if (!exampleExists) {
+    if (exampleExists === false) {
       return yield* new ExampleNotFoundError({
         exampleName,
         availableExamples: [],
@@ -171,56 +201,60 @@ const downloadExample = (exampleName: string, branch: string, destinationPath: s
       })
     }
 
-    // Copy the example directory contents to the destination using Effect Command
-    yield* Command.make('cp', '-r', `${exampleSourcePath}/.`, destinationPath).pipe(
-      Command.exitCode,
-      Effect.catchAll(
+    // Copy the example directory contents to the destination using a child process
+    yield* spawner.exitCode(ChildProcess.make('cp', ['-r', `${exampleSourcePath}/.`, destinationPath])).pipe(
+      Effect.catch(
         (error) =>
           new NetworkError({
             cause: error,
-            message: `Failed to copy example files: ${error}`,
+            message: `Failed to copy example files: ${String(error)}`,
           }),
       ),
     )
 
     // Clean up extract directory
-    yield* fs.remove(extractDir, { recursive: true }).pipe(Effect.catchAll(() => Effect.void))
+    yield* fs.remove(extractDir, { recursive: true }).pipe(Effect.catch(() => Effect.void))
 
     // Clean up tarball
-    yield* fs.remove(tarballPath).pipe(Effect.catchAll(() => Effect.void))
+    yield* fs.remove(tarballPath).pipe(Effect.catch(() => Effect.void))
 
     yield* Console.log(`✅ Example "${exampleName}" created successfully at: ${destinationPath}`)
   })
 
-export const newProjectCommand = Cli.Command.make(
-  'new-project',
+export const createCommand = Cli.Command.make(
+  'create',
   {
-    example: Cli.Options.text('example').pipe(
-      Cli.Options.optional,
-      Cli.Options.withDescription('Example name to create (bypasses interactive selection)'),
+    example: Cli.Flag.string('example').pipe(
+      Cli.Flag.optional,
+      Cli.Flag.withDescription('Example name to create (bypasses interactive selection)'),
     ),
-    branch: Cli.Options.text('branch').pipe(
-      Cli.Options.withDefault('dev'),
-      Cli.Options.withDescription('Branch to fetch examples from'),
+    ref: Cli.Flag.string('ref').pipe(
+      Cli.Flag.withAlias('commit'),
+      Cli.Flag.withAlias('branch'),
+      Cli.Flag.withAlias('tag'),
+      Cli.Flag.withDefault('main'),
+      Cli.Flag.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,
-      Cli.Args.withDescription('Destination path for the new project'),
+    path: Cli.Argument.string('path').pipe(
+      Cli.Argument.optional,
+      Cli.Argument.withDescription('Destination path for the new project'),
     ),
   },
   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')
@@ -232,10 +266,10 @@ export const newProjectCommand = Cli.Command.make(
     }
 
     // Select example (from CLI option or interactive prompt)
-    const selectedExample = Option.isSome(example) ? example.value : yield* selectExample(examples)
+    const selectedExample = Option.isSome(example) === true ? example.value : yield* selectExample(examples)
 
     // Validate selected example exists
-    if (!examples.includes(selectedExample)) {
+    if (examples.includes(selectedExample) === false) {
       yield* Console.log(`❌ Example "${selectedExample}" not found`)
       yield* Console.log(`Available examples: ${examples.join(', ')}`)
       return yield* new ExampleNotFoundError({
@@ -246,18 +280,51 @@ export const newProjectCommand = Cli.Command.make(
     }
 
     // Determine destination path
-    const destinationPath = Option.isSome(path) ? nodePath.resolve(path.value) : nodePath.resolve(selectedExample)
+    const destinationPath =
+      Option.isSome(path) === true ? 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.decodeUnknownEffect(Schema.fromJsonString(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-content/architecture.ts

@@ -28,9 +28,9 @@ LiveStore implements distributed systems principles from Martin Kleppmann's rese
 \`\`\`typescript
 // Materialized views from event log
 const materializers = State.SQLite.materializers(events, {
-  'TodoCreated': ({ id, text, createdAt }) => 
+  'TodoCreated': ({ id, text, createdAt }) =>
     tables.todos.insert({ id, text, completed: false, createdAt }),
-  'TodoCompleted': ({ id }) => 
+  'TodoCompleted': ({ id }) =>
     tables.todos.update({ completed: true }).where({ id })
 })
 \`\`\`
@@ -46,7 +46,7 @@ const materializers = State.SQLite.materializers(events, {
 const events = {
   todoCompleted: Events.synced({
     name: 'v1.TodoCompleted',
-    schema: Schema.Struct({ 
+    schema: Schema.Struct({
       id: Schema.String,
       completedAt: Schema.Date // For conflict resolution
     })

package/src/mcp-content/features.ts

@@ -149,7 +149,7 @@ await testStore.replay([
 
 ### Developer Tools
 - **Event Inspector**: Real-time event log visualization
-- **Query Profiler**: Performance analysis for slow queries  
+- **Query Profiler**: Performance analysis for slow queries
 - **Sync Monitor**: Network synchronization health dashboard
 - **Schema Explorer**: Interactive database schema browsing
 

package/src/mcp-content/getting-started.ts

@@ -36,13 +36,13 @@ export const tables = {
       createdAt: State.SQLite.integer({ schema: Schema.DateFromNumber }),
     },
   }),
-  
+
   // Client-only state (not synced)
   uiState: State.SQLite.clientDocument({
     name: 'uiState',
-    schema: Schema.Struct({ 
-      newTodoText: Schema.String, 
-      filter: Schema.Literal('all', 'active', 'completed') 
+    schema: Schema.Struct({
+      newTodoText: Schema.String,
+      filter: Schema.Literal('all', 'active', 'completed')
     }),
     default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
   }),
@@ -52,10 +52,10 @@ export const tables = {
 export const events = {
   todoCreated: Events.synced({
     name: 'v1.TodoCreated',
-    schema: Schema.Struct({ 
-      id: Schema.String, 
+    schema: Schema.Struct({
+      id: Schema.String,
       text: Schema.String,
-      createdAt: Schema.Date 
+      createdAt: Schema.Date
     }),
   }),
   todoCompleted: Events.synced({
@@ -70,23 +70,23 @@ export const events = {
     name: 'v1.TodoDeleted',
     schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }),
   }),
-  
+
   // UI state events (local only)
   uiStateSet: tables.uiState.set,
 }
 
 // Materializers map events to state changes
 const materializers = State.SQLite.materializers(events, {
-  'v1.TodoCreated': ({ id, text, createdAt }) => 
+  'v1.TodoCreated': ({ id, text, createdAt }) =>
     tables.todos.insert({ id, text, completed: false, createdAt }),
-    
-  'v1.TodoCompleted': ({ id }) => 
+
+  'v1.TodoCompleted': ({ id }) =>
     tables.todos.update({ completed: true }).where({ id }),
-    
-  'v1.TodoUncompleted': ({ id }) => 
+
+  'v1.TodoUncompleted': ({ id }) =>
     tables.todos.update({ completed: false }).where({ id }),
-    
-  'v1.TodoDeleted': ({ id, deletedAt }) => 
+
+  'v1.TodoDeleted': ({ id, deletedAt }) =>
     tables.todos.update({ deletedAt }).where({ id }),
 })
 
@@ -144,28 +144,28 @@ const TodoApp: React.FC = () => {
   const activeTodos = useLiveQuery(activeTodos$)
   const completedTodos = useLiveQuery(completedTodos$)
   const uiState = useLiveQuery(uiState$)
-  
+
   const createTodo = (text: string) => {
     const id = crypto.randomUUID()
     dispatchEvent(events.todoCreated({ id, text, createdAt: new Date() }))
   }
-  
+
   const toggleTodo = (id: string, completed: boolean) => {
     dispatchEvent(
-      completed 
+      completed
         ? events.todoCompleted({ id })
         : events.todoUncompleted({ id })
     )
   }
-  
+
   const deleteTodo = (id: string) => {
     dispatchEvent(events.todoDeleted({ id, deletedAt: new Date() }))
   }
-  
+
   return (
     <div className="todo-app">
       <h1>Local-First Todos</h1>
-      
+
       {/* Add todo form */}
       <form onSubmit={(e) => {
         e.preventDefault()
@@ -179,13 +179,13 @@ const TodoApp: React.FC = () => {
         <input name="todo" placeholder="What needs to be done?" />
         <button type="submit">Add Todo</button>
       </form>
-      
+
       {/* Active todos */}
       <div className="todo-list">
         <h2>Active ({activeTodos.length})</h2>
         {activeTodos.map(todo => (
           <div key={todo.id} className="todo-item">
-            <input 
+            <input
               type="checkbox"
               checked={false}
               onChange={() => toggleTodo(todo.id, true)}
@@ -195,13 +195,13 @@ const TodoApp: React.FC = () => {
           </div>
         ))}
       </div>
-      
+
       {/* Completed todos */}
       <div className="todo-list">
         <h2>Completed ({completedTodos.length})</h2>
         {completedTodos.map(todo => (
           <div key={todo.id} className="todo-item completed">
-            <input 
+            <input
               type="checkbox"
               checked={true}
               onChange={() => toggleTodo(todo.id, false)}
@@ -225,16 +225,16 @@ export default TodoApp
 <template>
   <div class="todo-app">
     <h1>Local-First Todos</h1>
-    
+
     <form @submit.prevent="createTodo">
       <input v-model="newTodoText" placeholder="What needs to be done?" />
       <button type="submit">Add Todo</button>
     </form>
-    
+
     <div class="todo-list">
       <h2>Active ({{ activeTodos.length }})</h2>
       <div v-for="todo in activeTodos" :key="todo.id" class="todo-item">
-        <input 
+        <input
           type="checkbox"
           :checked="false"
           @change="toggleTodo(todo.id, true)"
@@ -258,10 +258,10 @@ const newTodoText = ref('')
 const createTodo = () => {
   if (newTodoText.value.trim()) {
     const id = crypto.randomUUID()
-    dispatchEvent(events.todoCreated({ 
-      id, 
-      text: newTodoText.value.trim(), 
-      createdAt: new Date() 
+    dispatchEvent(events.todoCreated({
+      id,
+      text: newTodoText.value.trim(),
+      createdAt: new Date()
     }))
     newTodoText.value = ''
   }
@@ -269,7 +269,7 @@ const createTodo = () => {
 
 const toggleTodo = (id: string, completed: boolean) => {
   dispatchEvent(
-    completed 
+    completed
       ? events.todoCompleted({ id })
       : events.todoUncompleted({ id })
   )
@@ -332,7 +332,7 @@ Multiple users can collaborate in real-time. Conflicts are automatically resolve
 \`\`\`typescript
 // Custom conflict resolution
 const materializers = State.SQLite.materializers(events, {
-  'v1.TodoTextChanged': ({ id, text, editedAt }) => 
+  'v1.TodoTextChanged': ({ id, text, editedAt }) =>
     // Use timestamp for conflict resolution
     tables.todos
       .update({ text, editedAt })
@@ -350,18 +350,18 @@ import { schema, events } from './schema.js'
 
 test('creating and completing todos', async () => {
   const store = createTestStore(schema)
-  
+
   // Dispatch events
   await store.dispatch([
     events.todoCreated({ id: '1', text: 'Test todo', createdAt: new Date() }),
     events.todoCompleted({ id: '1' })
   ])
-  
+
   // Query final state
   const completedTodos = await store.query(
     tables.todos.select().where({ completed: true })
   )
-  
+
   expect(completedTodos).toHaveLength(1)
   expect(completedTodos[0].text).toBe('Test todo')
 })

package/src/mcp-content/overview.ts

@@ -26,7 +26,7 @@ LiveStore is a production-ready local-first data platform that combines the imme
 
 ### 🔐 End-to-End Type Safety
 - **Schema-first development** with Effect-based validation
-- **Compile-time query validation** prevents runtime errors  
+- **Compile-time query validation** prevents runtime errors
 - **Automatic TypeScript generation** from schema definitions
 - **Runtime safety** with comprehensive input validation
 
@@ -43,7 +43,7 @@ LiveStore is a production-ready local-first data platform that combines the imme
 - **Design tools** with multiplayer editing capabilities
 - **Chat applications** with offline message queuing
 
-### 📱 Mobile-First Applications  
+### 📱 Mobile-First Applications
 - **Field service apps** that work in areas with poor connectivity
 - **Healthcare applications** with sensitive data that must stay local
 - **Educational apps** for students in low-connectivity environments
@@ -61,16 +61,16 @@ LiveStore is a production-ready local-first data platform that combines the imme
 graph TB
     UI[UI Framework] --> Queries[Reactive Queries]
     UI --> Events[Event Dispatch]
-    
+
     Events --> EventLog[Event Log]
     EventLog --> Materializers[Materializers]
     Materializers --> SQLite[SQLite Database]
     Queries --> SQLite
-    
+
     EventLog --> Sync[Sync Engine]
     Sync --> Network[Network Layer]
     Network --> Server[Sync Server]
-    
+
     Server --> OtherClients[Other Clients]
     OtherClients --> Server
     Server --> Network
@@ -95,7 +95,7 @@ Unlike traditional ORMs that hide change tracking, LiveStore makes all state cha
 ### Sophisticated Conflict Resolution
 LiveStore handles conflicts intelligently using multiple strategies:
 - **Last-Write-Wins**: Simple timestamp-based resolution
-- **Semantic Merging**: Application-specific conflict resolution logic  
+- **Semantic Merging**: Application-specific conflict resolution logic
 - **Operational Transforms**: For real-time collaborative text editing
 - **CRDT Integration**: Conflict-free data types for specific use cases