@livestore/cli 0.0.0-snapshot-2ac5fd340c97c9e07fe4c5dc6d31d5132aa6557c.0

package/src/commands/new-project.ts

@@ -0,0 +1,263 @@
+import * as os from 'node:os'
+import * as nodePath from 'node:path'
+import {
+  Command,
+  Console,
+  Effect,
+  FileSystem,
+  HttpClient,
+  HttpClientRequest,
+  Option,
+  Schema,
+} from '@livestore/utils/effect'
+import { Cli } from '@livestore/utils/node'
+
+// Schema for GitHub API response
+const GitHubContentSchema = Schema.Struct({
+  name: Schema.String,
+  type: Schema.Literal('dir', 'file'),
+  path: Schema.String,
+  download_url: Schema.NullOr(Schema.String),
+})
+
+const GitHubContentsResponseSchema = Schema.Array(GitHubContentSchema)
+
+// Error types
+export class ExampleNotFoundError extends Schema.TaggedError<ExampleNotFoundError>()('ExampleNotFoundError', {
+  exampleName: Schema.String,
+  availableExamples: Schema.Array(Schema.String),
+  message: Schema.String,
+}) {}
+
+export class NetworkError extends Schema.TaggedError<NetworkError>()('NetworkError', {
+  cause: Schema.Unknown,
+  message: Schema.String,
+}) {}
+
+export class DirectoryExistsError extends Schema.TaggedError<DirectoryExistsError>()('DirectoryExistsError', {
+  path: Schema.String,
+  message: Schema.String,
+}) {}
+
+// Fetch available examples from GitHub
+const fetchExamples = (branch: string) =>
+  Effect.gen(function* () {
+    const url = `https://api.github.com/repos/livestorejs/livestore/contents/examples?ref=${branch}`
+
+    yield* Effect.log(`Fetching examples from branch: ${branch}`)
+
+    const request = HttpClientRequest.get(url)
+    const response = yield* HttpClient.execute(request).pipe(
+      Effect.scoped,
+      Effect.catchAll(
+        (error) =>
+          new NetworkError({
+            cause: error,
+            message: `Failed to fetch examples from GitHub: ${error}`,
+          }),
+      ),
+    )
+
+    const responseText = yield* response.text
+
+    const examples = yield* Schema.decodeUnknown(GitHubContentsResponseSchema)(JSON.parse(responseText)).pipe(
+      Effect.catchAll(
+        (error) =>
+          new NetworkError({
+            cause: error,
+            message: `Failed to parse GitHub API response: ${error}`,
+          }),
+      ),
+    )
+
+    const exampleNames = examples
+      .filter((item) => item.type === 'dir')
+      .map((item) => item.name)
+      .sort()
+
+    yield* Effect.log(`Found ${exampleNames.length} examples: ${exampleNames.join(', ')}`)
+
+    return exampleNames
+  })
+
+// Interactive example selection
+const selectExample = (examples: string[]) =>
+  Effect.gen(function* () {
+    if (examples.length === 0) {
+      return yield* Effect.fail(new Error('No examples available'))
+    }
+
+    const prompt = Cli.Prompt.select({
+      message: '📦 Select a LiveStore example to create:',
+      choices: examples.map((example) => ({
+        title: example,
+        value: example,
+        description: `Create a new project using the ${example} example`,
+      })),
+    })
+
+    return yield* Cli.Prompt.run(prompt)
+  })
+
+// Download and extract example using tiged approach
+const downloadExample = (exampleName: string, branch: string, destinationPath: string) =>
+  Effect.gen(function* () {
+    yield* Console.log(`📥 Downloading example "${exampleName}" from branch "${branch}"...`)
+
+    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}`
+
+    // Download tarball directly
+    const request = HttpClientRequest.get(tarballUrl)
+
+    const response = yield* HttpClient.execute(request).pipe(
+      Effect.scoped,
+      Effect.catchAll(
+        (error) =>
+          new NetworkError({
+            cause: error,
+            message: `Failed to download tarball: ${error}`,
+          }),
+      ),
+    )
+
+    const fs = yield* FileSystem.FileSystem
+
+    // Write tarball to temp file
+    const tarballBuffer = yield* response.arrayBuffer
+    yield* fs.writeFile(tarballPath, new Uint8Array(tarballBuffer))
+
+    // Create destination directory
+    yield* fs.makeDirectory(destinationPath, { recursive: true })
+
+    // Extract the tarball to a temporary directory first
+    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(
+        (error) =>
+          new NetworkError({
+            cause: error,
+            message: `Failed to extract tarball: ${error}`,
+          }),
+      ),
+    )
+
+    // Find the extracted directory (it will be named like livestorejs-livestore-{hash})
+    const extractedDirs = yield* fs.readDirectory(extractDir)
+
+    if (extractedDirs.length === 0) {
+      return yield* new NetworkError({
+        cause: 'No extracted directory found',
+        message: 'Failed to find extracted repository directory',
+      })
+    }
+
+    const repoDir = nodePath.join(extractDir, extractedDirs[0]!)
+    const exampleSourcePath = nodePath.join(repoDir, 'examples', exampleName)
+
+    // Check if the example exists
+    const exampleExists = yield* fs.exists(exampleSourcePath)
+
+    if (!exampleExists) {
+      return yield* new ExampleNotFoundError({
+        exampleName,
+        availableExamples: [],
+        message: `Example "${exampleName}" not found in the extracted repository`,
+      })
+    }
+
+    // Copy the example directory contents to the destination using Effect Command
+    yield* Command.make('cp', '-r', `${exampleSourcePath}/.`, destinationPath).pipe(
+      Command.exitCode,
+      Effect.catchAll(
+        (error) =>
+          new NetworkError({
+            cause: error,
+            message: `Failed to copy example files: ${error}`,
+          }),
+      ),
+    )
+
+    // Clean up extract directory
+    yield* fs.remove(extractDir, { recursive: true }).pipe(Effect.catchAll(() => Effect.void))
+
+    // Clean up tarball
+    yield* fs.remove(tarballPath).pipe(Effect.catchAll(() => Effect.void))
+
+    yield* Console.log(`✅ Example "${exampleName}" created successfully at: ${destinationPath}`)
+  })
+
+export const newProjectCommand = Cli.Command.make(
+  'new-project',
+  {
+    example: Cli.Options.text('example').pipe(
+      Cli.Options.optional,
+      Cli.Options.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'),
+    ),
+    path: Cli.Args.text({ name: 'path' }).pipe(
+      Cli.Args.optional,
+      Cli.Args.withDescription('Destination path for the new project'),
+    ),
+  },
+  Effect.fn(function* ({
+    example,
+    branch,
+    path,
+  }: {
+    example: Option.Option<string>
+    branch: string
+    path: Option.Option<string>
+  }) {
+    yield* Effect.log('🚀 Creating new LiveStore project...')
+
+    // Fetch available examples
+    const examples = yield* fetchExamples(branch)
+
+    if (examples.length === 0) {
+      yield* Console.log('❌ No examples found in the repository')
+      return yield* new ExampleNotFoundError({
+        exampleName: '',
+        availableExamples: [],
+        message: 'No examples available',
+      })
+    }
+
+    // Select example (from CLI option or interactive prompt)
+    const selectedExample = Option.isSome(example) ? example.value : yield* selectExample(examples)
+
+    // Validate selected example exists
+    if (!examples.includes(selectedExample)) {
+      yield* Console.log(`❌ Example "${selectedExample}" not found`)
+      yield* Console.log(`Available examples: ${examples.join(', ')}`)
+      return yield* new ExampleNotFoundError({
+        exampleName: selectedExample,
+        availableExamples: examples,
+        message: `Example "${selectedExample}" not found`,
+      })
+    }
+
+    // Determine destination path
+    const destinationPath = Option.isSome(path) ? nodePath.resolve(path.value) : nodePath.resolve(selectedExample)
+
+    // Download and extract the example
+    yield* downloadExample(selectedExample, branch, destinationPath)
+
+    // 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')
+    yield* Console.log('\n💡 Tip: Run `git init` if you want to initialize version control')
+  }),
+)

package/src/mcp-content/architecture.ts

@@ -0,0 +1,170 @@
+export const architectureContent = `# LiveStore Architecture: Local-First Data Management
+
+LiveStore implements distributed systems principles from Martin Kleppmann's research on local-first software, ensuring data consistency, availability, and partition tolerance in collaborative applications.
+
+## Core Architectural Principles
+
+### 1. Local-First Data Storage
+- **Immediate Response**: All operations execute against local SQLite database first
+- **Offline Capability**: Full application functionality without network connectivity
+- **Data Ownership**: Users maintain complete control over their data
+- **Performance**: Sub-millisecond query responses from local storage
+
+### 2. Event Sourcing & CRDT-Inspired Conflict Resolution
+- **Immutable Event Log**: All changes recorded as immutable events
+- **Deterministic Replay**: State reconstruction from event sequence
+- **Conflict-Free Operations**: Events designed for commutative application
+- **Causal Ordering**: Lamport timestamps ensure causally consistent ordering
+
+### 3. Eventually Consistent Synchronization
+- **Asynchronous Replication**: Events sync when network available
+- **Convergence Guarantee**: All replicas converge to same state
+- **Conflict Resolution**: Last-write-wins with semantic merging strategies
+- **Incremental Sync**: Only transmit events since last synchronization
+
+## System Components
+
+### 🗄️ State Layer (SQLite + Materializers)
+\`\`\`typescript
+// Materialized views from event log
+const materializers = State.SQLite.materializers(events, {
+  'TodoCreated': ({ id, text, createdAt }) => 
+    tables.todos.insert({ id, text, completed: false, createdAt }),
+  'TodoCompleted': ({ id }) => 
+    tables.todos.update({ completed: true }).where({ id })
+})
+\`\`\`
+
+**Responsibilities:**
+- Maintain denormalized query-optimized state
+- Apply events to update materialized views
+- Support efficient reactive queries
+- Handle schema migrations
+
+### 📝 Event System (Append-Only Log)
+\`\`\`typescript
+const events = {
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ 
+      id: Schema.String,
+      completedAt: Schema.Date // For conflict resolution
+    })
+  })
+}
+\`\`\`
+
+**Characteristics:**
+- Immutable event log (append-only)
+- Cryptographically signed events for integrity
+- Causal dependencies tracked via vector clocks
+- Schema versioning for backward compatibility
+
+### 🔄 Synchronization Engine
+\`\`\`typescript
+// Conflict resolution during sync
+const mergeResult = SyncState.merge({
+  syncState: currentState,
+  payload: incomingEvents,
+  isEqualEvent: (a, b) => a.id === b.id && a.type === b.type
+})
+\`\`\`
+
+**Merge Strategies:**
+- **Advance**: New events extend current state
+- **Rebase**: Rollback conflicting events, apply remote, replay local
+- **Reject**: Ignore events that violate invariants
+
+### 🌐 Network Layer & Adapters
+\`\`\`typescript
+// Platform-specific sync adapters
+export const WebAdapter = {
+  storage: OPFSSQLiteStorage, // Origin Private File System
+  transport: WebSocketSync,
+  worker: SharedWorker        // Cross-tab synchronization
+}
+\`\`\`
+
+**Adapter Implementations:**
+- **Web**: OPFS storage, SharedWorker coordination, WebSocket sync
+- **Node**: File system storage, cluster coordination, HTTP/WebSocket
+- **Mobile**: Native SQLite, background sync, push notifications
+
+## Distributed Systems Properties
+
+### CAP Theorem Considerations
+- **Consistency**: Eventually consistent (not strongly consistent)
+- **Availability**: Always available for reads/writes (local-first)
+- **Partition Tolerance**: Continues operation during network partitions
+
+*Trade-off: Chooses Availability + Partition Tolerance over strong Consistency*
+
+### ACID Properties (Local Transactions)
+- **Atomicity**: Event application is atomic within SQLite transaction
+- **Consistency**: Materializers maintain data integrity constraints
+- **Isolation**: Concurrent operations isolated via SQLite WAL mode
+- **Durability**: Events persisted to disk before acknowledgment
+
+### Conflict Resolution Strategies
+
+1. **Semantic Conflict Resolution**
+   - Application-specific merge logic
+   - E.g., text editing uses operational transforms
+
+2. **Last-Write-Wins (LWW)**
+   - Timestamps determine winner
+   - Simple but can lose data
+
+3. **Multi-Value Registers**
+   - Preserve all conflicting values
+   - User or application resolves
+
+4. **Commutative Operations**
+   - Operations designed to commute
+   - E.g., increment/decrement counters
+
+## Performance & Scalability
+
+### Query Performance
+- **Reactive Queries**: Automatically update UI on data changes
+- **Indexed Access**: SQLite B-tree indexes for fast lookups
+- **Prepared Statements**: Query compilation cached for reuse
+- **Batch Operations**: Multiple events applied in single transaction
+
+### Memory Management
+- **Incremental Loading**: Large datasets loaded on-demand
+- **Query Result Caching**: Expensive query results cached
+- **Event Log Compaction**: Periodic snapshotting and log truncation
+- **Connection Pooling**: Database connections reused across operations
+
+### Network Optimization
+- **Delta Synchronization**: Only sync events since last checkpoint
+- **Compression**: Event payloads compressed for network transfer
+- **Batching**: Multiple events transmitted in single round-trip
+- **Exponential Backoff**: Retry failed sync with increasing delays
+
+## Security Model
+
+### Data Integrity
+- **Event Signatures**: Cryptographic signatures prevent tampering
+- **Merkle Trees**: Efficient verification of event log integrity
+- **Schema Validation**: All events validated against defined schemas
+
+### Access Control
+- **Client-Side Authorization**: Fine-grained permissions in local database
+- **Sync Filtering**: Server filters events based on user permissions
+- **Encryption**: End-to-end encryption for sensitive data
+
+## Observability
+
+### Distributed Tracing
+- **Event Causality**: Trace event propagation across replicas
+- **Sync Performance**: Monitor replication lag and throughput
+- **Conflict Metrics**: Track merge conflicts and resolution strategies
+
+### Health Monitoring
+- **Storage Usage**: Local database size and growth rate
+- **Network Health**: Connection quality and sync success rates
+- **Error Tracking**: Failed operations and their root causes
+
+This architecture enables applications that work seamlessly offline, sync reliably when online, and provide immediate feedback to users while maintaining data consistency across all replicas.`

package/src/mcp-content/features.ts

@@ -0,0 +1,176 @@
+export const featuresContent = `# LiveStore Features: Production-Ready Local-First Data
+
+LiveStore provides battle-tested primitives for building collaborative, offline-capable applications with the reliability and performance of modern distributed systems.
+
+## 🏠 Local-First Architecture
+
+### Offline-First Operation
+- **Zero Latency**: All operations execute against local SQLite database
+- **Offline Capable**: Full application functionality without network connectivity
+- **Network Resilient**: Graceful degradation during connectivity issues
+- **Background Sync**: Automatic synchronization when network becomes available
+
+### Immediate Consistency
+- **Optimistic Updates**: UI updates immediately on user action
+- **Rollback on Conflict**: Automatic rollback and retry on merge conflicts
+- **Causal Consistency**: Operations maintain causal ordering across replicas
+
+## 🔄 Event-Driven Synchronization
+
+### Conflict-Free Event Model
+\`\`\`typescript
+// Events designed for conflict-free merging
+const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({
+      id: Schema.String,      // Deterministic ordering
+      createdAt: Schema.Date, // Timestamp for LWW resolution
+      position: Schema.Number // Fractional indexing for reordering
+    })
+  })
+}
+\`\`\`
+
+### Sophisticated Merge Strategies
+- **Last-Write-Wins**: Timestamp-based conflict resolution
+- **Semantic Merging**: Application-specific merge logic
+- **Operational Transform**: Real-time collaborative text editing
+- **CRDT Integration**: Conflict-free replicated data types
+
+### Incremental Synchronization
+- **Delta Sync**: Only transmit changes since last synchronization
+- **Vector Clocks**: Efficient causal dependency tracking
+- **Merkle Trees**: Efficient integrity verification
+- **Batch Optimization**: Multiple events in single network round-trip
+
+## 📊 Reactive Query Engine
+
+### Real-Time Reactivity
+\`\`\`typescript
+// Queries automatically update when underlying data changes
+const activeTodos$ = queryDb(
+  tables.todos
+    .select()
+    .where({ completed: false, deletedAt: null })
+    .orderBy('position'),
+  { label: 'activeTodos' }
+)
+\`\`\`
+
+### Advanced Query Capabilities
+- **Joins & Aggregations**: Full SQL expressiveness
+- **Reactive Subscriptions**: Automatic UI updates on data changes
+- **Query Optimization**: SQLite query planner with B-tree indexes
+- **Prepared Statements**: Cached query compilation for performance
+
+### Framework Integrations
+- **React**: \`useLiveQuery()\` hook for reactive components
+- **Vue**: Composables for reactive data binding
+- **Solid**: Reactive primitives integration
+- **Svelte**: Store-based reactive updates
+
+## 🔐 End-to-End Type Safety
+
+### Schema-First Development
+\`\`\`typescript
+// Type safety from database to UI
+const todoSchema = State.SQLite.table({
+  name: 'todos',
+  columns: {
+    id: State.SQLite.text({ primaryKey: true }),
+    title: State.SQLite.text(),
+    completed: State.SQLite.boolean()
+  }
+})
+
+// Fully typed queries
+type Todo = typeof todoSchema.select.Type // { id: string, title: string, completed: boolean }
+\`\`\`
+
+### Runtime Validation
+- **Schema Validation**: All events validated against Effect schemas
+- **Migration Safety**: Type-safe schema evolution
+- **Parse Don't Validate**: Schema types flow through entire application
+
+## 🌐 Multi-Platform Support
+
+### Web Platform
+- **Origin Private File System**: Persistent storage in modern browsers
+- **SharedWorker**: Cross-tab synchronization and resource sharing
+- **IndexedDB Fallback**: Compatibility with older browsers
+- **Service Worker**: Background synchronization
+
+### Node.js Platform
+- **File System Storage**: Native SQLite database files
+- **Cluster Coordination**: Multi-process synchronization
+- **HTTP/WebSocket Sync**: Flexible transport protocols
+- **Background Jobs**: Scheduled synchronization tasks
+
+### Mobile Platforms (Expo/React Native)
+- **Native SQLite**: Platform-optimized database performance
+- **Background Sync**: Synchronization during app backgrounding
+- **Push Notifications**: Real-time update notifications
+- **Secure Storage**: Encrypted local data storage
+
+## 🚀 Performance & Scalability
+
+### Query Performance
+- **Sub-millisecond Queries**: Local SQLite performance
+- **Efficient Indexing**: Automatic index recommendations
+- **Result Set Streaming**: Large datasets loaded incrementally
+- **Query Result Caching**: Expensive computations cached
+
+### Memory Management
+- **Lazy Loading**: Data loaded on-demand
+- **Connection Pooling**: Database connections efficiently reused
+- **Event Log Compaction**: Periodic snapshots prevent unbounded growth
+- **Garbage Collection**: Automatic cleanup of obsolete data
+
+### Network Optimization
+- **Compression**: Event payloads compressed for transmission
+- **Request Batching**: Multiple operations in single request
+- **Connection Pooling**: HTTP/WebSocket connections reused
+- **Exponential Backoff**: Intelligent retry strategies
+
+## 🏗️ Developer Experience
+
+### Testing & Debugging
+\`\`\`typescript
+// Built-in testing utilities
+const testStore = createTestStore(schema)
+
+// Deterministic event replay for testing
+await testStore.replay([
+  events.todoCreated({ id: '1', title: 'Test todo' }),
+  events.todoCompleted({ id: '1' })
+])
+\`\`\`
+
+### Developer Tools
+- **Event Inspector**: Real-time event log visualization
+- **Query Profiler**: Performance analysis for slow queries  
+- **Sync Monitor**: Network synchronization health dashboard
+- **Schema Explorer**: Interactive database schema browsing
+
+### Production Monitoring
+- **Distributed Tracing**: Event propagation across replicas
+- **Performance Metrics**: Query latency and throughput monitoring
+- **Error Tracking**: Comprehensive error reporting and alerting
+- **Health Checks**: Automated system health verification
+
+## 🔒 Security & Privacy
+
+### Data Protection
+- **End-to-End Encryption**: Client-side encryption before transmission
+- **Event Signatures**: Cryptographic integrity verification
+- **Access Control**: Fine-grained permission system
+- **Audit Logging**: Comprehensive security event logging
+
+### Privacy by Design
+- **Local Data Control**: Users maintain complete data ownership
+- **Selective Sync**: Fine-grained control over data sharing
+- **Data Minimization**: Only sync necessary data
+- **GDPR Compliance**: Built-in privacy compliance features
+
+LiveStore combines the reliability of traditional databases with the performance and user experience of local-first applications, enabling you to build applications that users love while maintaining the technical rigor of distributed systems.`