db4ai 0.1.0

package/README.md

@@ -0,0 +1,438 @@
+# db4ai
+
+A declarative schema DSL for AI-powered databases. Define your data model and let AI generate structured content on-demand.
+
+## Installation
+
+```bash
+npm install db4ai
+```
+
+## Quick Start
+
+```typescript
+import { DB } from 'db4ai'
+
+const db = DB({
+  $id: 'my-blog-app',  // Required: namespace for your schema
+  Blog: {
+    title: 'Short memorable blog name',
+    description: 'Brief tagline for SEO meta tags',
+    purpose: 'Core mission and value proposition',
+    audience: 'Target reader persona',
+    style: 'Tone and writing style',
+    topics: ['List 5 PascalCase topics covered ->Topic'],
+    posts: ['<-Post'],
+  },
+  Topic: {
+    name: '1-2 word PascalCase name',
+    description: '1 sentence description',
+    titles: ['List 3 blog post titles ->Post'],
+  },
+  Post: {
+    title: 'SEO-optimized title without punctuation',
+    synopsis: '1 sentence overview',
+    content: 'Markdown content (title prepended automatically)',
+  },
+})
+
+// Generate a complete blog with topics and posts
+const blog = await db.Blog('mystartup.ai/blog', {
+  audience: 'Early stage startup founders',
+  style: 'provocative',
+})
+```
+
+## Namespace Configuration
+
+Every schema requires a namespace via `$id` or `$context`. This determines where your data is stored and enables composition of multiple schemas.
+
+### Using `$id`
+
+```typescript
+// Simple namespace (uses https://db4ai.dev by default)
+const db = DB({
+  $id: 'my-app',
+  User: { name: 'User name' },
+})
+
+// Full URL for custom backends
+const db = DB({
+  $id: 'https://db.sb/my-app',
+  User: { name: 'User name' },
+})
+```
+
+### Using `$context` for Composable Schemas
+
+`$context` is ideal when you have multiple `DB()` definitions that should share a namespace:
+
+```typescript
+// StartupBuilder.ts
+export const StartupBuilder = DB({
+  $context: 'startups',
+  Startup: {
+    name: 'Startup name',
+    idea: '->Idea',
+    founders: '->Founder[]',
+  },
+  Idea: { concept: 'Business concept' },
+  Founder: { name: 'Founder name', background: 'Background' },
+})
+
+// SalesBuilder.ts
+export const SalesBuilder = DB({
+  $context: 'startups',  // Same context - shares namespace!
+  Lead: {
+    name: 'Lead name',
+    startup: '->Startup',  // Can reference StartupBuilder types
+  },
+  Deal: { value: 'Deal value', lead: '->Lead' },
+})
+
+// ServiceBuilder.ts
+export const ServiceBuilder = DB({
+  $context: 'startups',  // Same context
+  Service: { name: 'Service name' },
+  Client: { name: 'Client name', services: '->Service[]' },
+})
+```
+
+All three schemas share the `startups` namespace at `https://db4ai.dev/startups`, allowing cross-references between types.
+
+### Result Properties
+
+```typescript
+const db = DB({ $context: 'my-app', User: { name: '' } })
+
+db.namespace  // 'my-app' - the resolved namespace
+db.baseUrl    // 'https://db4ai.dev' - API base URL
+db.context    // 'my-app' - from $context (if used)
+db.id         // undefined - from $id (if used)
+```
+
+## Schema DSL
+
+### Field Descriptions
+
+Every field value is a generation prompt. Empty strings infer the prompt from context:
+
+```typescript
+DB({
+  Product: {
+    name: '',                    // Infer from context
+    tagline: '< 10 words',       // Short constraint
+    description: 'Detailed product description for landing page',
+  },
+})
+```
+
+### References (`->`)
+
+Link to other types. Referenced objects are generated recursively:
+
+```typescript
+DB({
+  Post: {
+    author: '->User',            // Single reference
+    tags: '->Tag[]',             // Array of references
+    reviewer: '->User?',         // Optional reference
+  },
+})
+```
+
+### Fuzzy References (`~>`)
+
+Match existing objects by semantic similarity, generate if no match:
+
+```typescript
+DB({
+  Article: {
+    industry: '~>Industry',      // Match to taxonomy
+    topic: '~>Category?',        // Optional fuzzy match
+  },
+})
+```
+
+### Inline References (`['... ->Type']`)
+
+Generate array items that are also references:
+
+```typescript
+DB({
+  Blog: {
+    // Generate 5 topic names AND create Topic objects for each
+    topics: ['List 5 PascalCase topics ->Topic'],
+  },
+  Topic: {
+    name: '1-2 word PascalCase name',
+  },
+})
+```
+
+### Back References (`['<-Type']`)
+
+Collect objects that reference this one:
+
+```typescript
+DB({
+  Blog: {
+    posts: ['<-Post'],           // All Posts referencing this Blog
+  },
+  Post: {
+    blog: '->Blog',              // Post belongs to Blog
+    title: 'Post title',
+  },
+})
+```
+
+### Union Types (`|`)
+
+Reference multiple possible types:
+
+```typescript
+DB({
+  Comment: {
+    target: '->Post|Product',    // Reference Post OR Product
+  },
+})
+```
+
+### Arrays
+
+String arrays with generation prompts:
+
+```typescript
+DB({
+  Post: {
+    tags: ['List 3-5 relevant tags'],
+    keyPoints: ['Main takeaways from the content'],
+  },
+})
+```
+
+### Nested Objects
+
+Inline object structures:
+
+```typescript
+DB({
+  User: {
+    profile: {
+      bio: 'Short biography',
+      links: ['Social media URLs'],
+    },
+  },
+})
+```
+
+### Optional Fields (`?`)
+
+Fields not required in output:
+
+```typescript
+DB({
+  User: {
+    name: 'Full name',
+    nickname: '?',               // Optional, infer if provided
+    avatar: '->Image?',          // Optional reference
+  },
+})
+```
+
+## API
+
+### `DB(schema)`
+
+Create a schema and get typed accessors:
+
+```typescript
+const db = DB({
+  User: { name: '', email: '' },
+  Post: { title: '', author: '->User' },
+})
+
+db.schema              // Original definition
+db.types               // Parsed type metadata
+db.hash                // Deterministic schema hash
+db.toJSONSchema('User') // JSON Schema for validation
+```
+
+### `db.Type(id, args?)`
+
+Generate or retrieve an object:
+
+```typescript
+// Generate with context
+const blog = await db.Blog('my-blog', {
+  audience: 'developers',
+  style: 'technical',
+})
+
+// Retrieve cached (same args = same result)
+const sameBlog = await db.Blog('my-blog', {
+  audience: 'developers',
+  style: 'technical',
+})
+```
+
+### Low-level Functions
+
+```typescript
+import { parseSchema, parseFieldType, toJSONSchema } from 'db4ai'
+
+// Parse entire schema
+const { types, hash } = parseSchema({ User: { name: '' } })
+
+// Parse single field
+parseFieldType('->User[]')
+// { type: 'reference', ref: 'User', isArray: true }
+
+parseFieldType(['List 3 items ->Tag'])
+// { type: 'array', items: { type: 'string' }, description: '...', refs: ['Tag'] }
+
+// Generate JSON Schema
+const jsonSchema = toJSONSchema(types.User)
+```
+
+## Field Reference
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `''` | Infer from context | `name: ''` |
+| `'prompt'` | Generate with prompt | `bio: 'Short bio'` |
+| `'->Type'` | Reference | `author: '->User'` |
+| `'~>Type'` | Fuzzy reference | `category: '~>Topic'` |
+| `'->Type[]'` | Reference array | `tags: '->Tag[]'` |
+| `'->Type?'` | Optional reference | `image: '->Image?'` |
+| `'->A\|B'` | Union reference | `owner: '->User\|Org'` |
+| `['prompt']` | String array | `tags: ['Keywords']` |
+| `['... ->Type']` | Inline refs | `items: ['List 3 ->Item']` |
+| `['<-Type']` | Back refs | `posts: ['<-Post']` |
+| `{ k: 'v' }` | Nested object | `meta: { title: '' }` |
+| `'?'` | Optional infer | `nickname: '?'` |
+
+## CLI
+
+The db4ai package includes a command-line interface for local development and data management.
+
+### Installation
+
+```bash
+npm install -g db4ai
+# or use with npx
+npx db4ai
+```
+
+### Available Commands
+
+#### scan
+Scan your project for schema definitions, seed files, and workflows.
+
+```bash
+db4ai scan
+```
+
+Options:
+- `--root <path>` - Root directory to scan
+- `--include <glob>` - Glob pattern for files to include
+- `--exclude <glob>` - Glob pattern for files to exclude
+- `--json` - Output as JSON
+
+Discovers:
+- Schema files (`.schema.ts`, `.db.ts`)
+- Seed files (`.seed.ts`, `.seed.mdx`)
+- Workflow files (`.workflow.ts`)
+- Project configuration (`db4.config.ts`)
+
+#### seed
+Execute static and generated seed operations with progress tracking.
+
+```bash
+db4ai seed <seed-name>
+```
+
+Supports:
+- **Static seeds**: Load data from inline JSON or external APIs
+- **Generated seeds**: Use LLM to generate test data
+- Cascading entity generation
+- Resume tokens for interrupted operations
+- Concurrency control and field mapping
+
+#### workflow
+Execute event-triggered and manual workflows with integration support.
+
+```bash
+db4ai workflow <workflow-name>
+```
+
+Features:
+- Event-triggered and scheduled workflows
+- Concurrency control and retry logic
+- Database context and relationship management
+- Logging and error handling
+
+#### sync
+Synchronize data between local runtime and cloud backend.
+
+```bash
+db4ai sync
+```
+
+Enables:
+- Bidirectional data sync
+- Conflict resolution
+- Transaction support
+
+#### dashboard
+Interactive terminal UI for monitoring seeds, workflows, and data generation.
+
+```bash
+db4ai dashboard
+```
+
+Displays:
+- Real-time progress tracking
+- Type and entity statistics
+- Activity feed and event logs
+- Cascade tree visualization
+- Search and filtering
+
+### Project Configuration
+
+Create a `db4.config.ts` file in your project root to configure defaults:
+
+```typescript
+export default {
+  namespace: 'my-app',
+  ai: {
+    model: 'claude-3-5-sonnet-20241022',
+    temperature: 0.7,
+    maxTokens: 4096,
+  },
+  scan: {
+    include: ['src/**/*.ts'],
+    exclude: ['**/*.test.ts'],
+  },
+}
+```
+
+## TypeScript
+
+```typescript
+import type {
+  SchemaDefinition,
+  ParsedSchema,
+  ParsedType,
+  ParsedField,
+  StringField,
+  ReferenceField,
+  ArrayField,
+  ObjectField,
+  JSONSchema,
+} from 'db4ai'
+```
+
+## License
+
+MIT

package/dist/cli/bin.d.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * db4ai CLI - Command Line Interface
+ *
+ * Entry point for the db4ai CLI tool.
+ */
+export declare const CLI_VERSION = "0.1.0";
+/** Available CLI commands */
+export type Command = 'scan' | 'seed' | 'workflow' | 'sync' | 'dashboard';
+/** Parsed CLI arguments */
+export interface ParsedArgs {
+    version: boolean;
+    help: boolean;
+    command?: Command;
+    subcommand?: string;
+    args: string[];
+    config?: string;
+    verbose: boolean;
+    quiet: boolean;
+    noColor: boolean;
+    json: boolean;
+}
+/** Output streams for CLI (allows injection for testing) */
+export interface OutputStreams {
+    stdout: {
+        write: (s: string) => void;
+    };
+    stderr: {
+        write: (s: string) => void;
+    };
+}
+/**
+ * Parse CLI arguments into a structured format
+ * @param args - Raw command line arguments (process.argv.slice(2))
+ * @returns Parsed arguments with flags, command, and remaining args
+ */
+export declare function parseArgs(args: string[]): ParsedArgs;
+export declare function handleScan(args: string[], streams: OutputStreams): Promise<number>;
+export declare function handleSeed(args: string[], streams: OutputStreams): Promise<number>;
+export declare function handleWorkflow(args: string[], streams: OutputStreams): Promise<number>;
+export declare function handleSync(args: string[], subcommand: string | undefined, streams: OutputStreams): Promise<number>;
+export declare function handleDashboard(args: string[], streams: OutputStreams): Promise<number>;
+/**
+ * Main CLI entry point
+ * @param args - Command line arguments
+ * @param options - Optional output streams for testing
+ * @returns Exit code (0 = success, 1 = error, 2 = invalid args)
+ */
+export declare function run(args: string[], options?: Partial<OutputStreams>): Promise<number>;
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../cli/bin.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAMH,eAAO,MAAM,WAAW,UAAU,CAAA;AAElC,6BAA6B;AAC7B,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,WAAW,CAAA;AAEzE,2BAA2B;AAC3B,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAA;IACtC,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAA;CACvC;AAwKD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAgHpD;AAGD,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;;;;GAKG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GACnC,OAAO,CAAC,MAAM,CAAC,CAuEjB"}