schemock 0.0.4-alpha.1 → 0.0.4-alpha.3

package/README.md

@@ -23,6 +23,11 @@ npm install schemock
 npx schemock init
 ```
 
+This creates:
+- `src/schemas/user.ts` - Example schema with User, Post, Comment
+- `schemock.config.ts` - Configuration file
+- `CLAUDE.md` - AI tool configuration (helps Claude Code, Cursor, etc.)
+
 Define your schema:
 
 ```typescript
@@ -87,6 +92,7 @@ schemock <command> [options]
 | `generate:sql` | Generate PostgreSQL schema with RLS |
 | `generate:openapi` | Generate OpenAPI 3.0 specification |
 | `generate:postman` | Generate Postman collection |
+| `setup:ai` | Generate CLAUDE.md for AI tool integration |
 
 ### Generate Options
 
@@ -98,6 +104,7 @@ npx schemock generate [options]
   --config, -c <file>     Config file path
   --only <entities>       Only generate for these entities (comma-separated)
   --exclude <entities>    Exclude these entities (comma-separated)
+  --with-form-schemas     Generate Zod validation, form defaults, and table columns
   --watch, -w             Watch mode - regenerate on changes
   --dry-run               Preview without writing files
   --verbose, -v           Verbose output
@@ -115,6 +122,100 @@ npx schemock generate --exclude audit
 npx schemock generate --adapter supabase --only user,post --verbose
 ```
 
+### Form Schema Generation
+
+Add `--with-form-schemas` to generate Zod validation schemas, form defaults, and table column metadata:
+
+```bash
+npx schemock generate --with-form-schemas
+```
+
+This appends the following to `types.ts` for each entity:
+
+```typescript
+// Zod validation schema with constraints from field definitions
+export const UserFormSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email().min(1, 'Email is required'),
+  role: z.enum(['admin', 'user', 'guest']),
+  bio: z.string().max(500).nullable(),
+});
+
+// Default values for form initialization
+export const UserFormDefaults: z.input<typeof UserFormSchema> = {
+  name: '',
+  email: '',
+  role: 'user',
+  bio: null,
+};
+
+// Inferred TypeScript type
+export type UserFormData = z.infer<typeof UserFormSchema>;
+
+// Table column metadata for building data tables
+export const UserTableColumns: ColumnDef[] = [
+  { key: 'name', label: 'Name', type: 'text', sortable: true, filterable: true },
+  { key: 'email', label: 'Email', type: 'email', sortable: true, filterable: true },
+  { key: 'role', label: 'Role', type: 'enum', sortable: true, filterable: true },
+  { key: 'createdAt', label: 'Created At', type: 'date', sortable: true, filterable: true, hidden: true },
+];
+
+// Union type of valid column keys
+export type UserColumnKey = 'name' | 'email' | 'role' | 'createdAt' | ...;
+```
+
+**Use with react-hook-form:**
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { UserFormSchema, UserFormDefaults, UserFormData } from './generated';
+
+function UserForm() {
+  const form = useForm<UserFormData>({
+    resolver: zodResolver(UserFormSchema),
+    defaultValues: UserFormDefaults,
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      <input {...form.register('name')} />
+      {form.formState.errors.name && <span>{form.formState.errors.name.message}</span>}
+      {/* ... */}
+    </form>
+  );
+}
+```
+
+**Use table columns with any table library:**
+
+```typescript
+import { UserTableColumns } from './generated';
+
+// With TanStack Table
+const columns = UserTableColumns.filter(col => !col.hidden).map(col => ({
+  accessorKey: col.key,
+  header: col.label,
+  enableSorting: col.sortable,
+}));
+
+// With any custom table
+function UserTable({ users }) {
+  return (
+    <table>
+      <thead>
+        <tr>
+          {UserTableColumns.filter(c => !c.hidden).map(col => (
+            <th key={col.key}>{col.label}</th>
+          ))}
+        </tr>
+      </thead>
+      {/* ... */}
+    </table>
+  );
+}
+```
+
 ### SQL Generation
 
 ```bash
@@ -127,6 +228,49 @@ npx schemock generate:sql [options]
   --readme                Generate README documentation
 ```
 
+### AI Tool Integration
+
+Schemock can generate configuration files that help AI coding assistants (like Claude Code, Cursor, etc.) understand your project and avoid modifying auto-generated code.
+
+**Automatic setup (recommended):**
+
+When you run `schemock init`, a `CLAUDE.md` file is automatically created with:
+- List of generated directories that AI should not modify
+- Schema DSL reference for AI assistance
+- Common tasks and CLI commands
+
+**Manual setup for existing projects:**
+
+```bash
+# Generate/update CLAUDE.md
+npx schemock setup:ai
+
+# Also generate .cursorrules for Cursor IDE
+npx schemock setup:ai --cursor
+
+# Preview without writing files
+npx schemock setup:ai --dry-run
+```
+
+**What the AI configuration includes:**
+- **Generated files warning** - Tells AI which directories contain auto-generated code
+- **Schema DSL reference** - Helps AI write correct schema definitions
+- **Common tasks** - Guides AI on how to add fields, entities, relations
+- **CLI commands** - Reference for generation commands
+
+**Safe merging:** If you already have a `CLAUDE.md`, Schemock appends its section without overwriting your existing content. Clear markers (`<!-- SCHEMOCK:START -->` / `<!-- SCHEMOCK:END -->`) identify the auto-generated portion.
+
+**Options:**
+
+```bash
+npx schemock setup:ai [options]
+
+  --cursor                Also generate .cursorrules for Cursor IDE
+  --force                 Overwrite existing .cursorrules even if not created by Schemock
+  --dry-run               Preview without writing files
+  --output, -o <dir>      Output directory (default: current directory)
+```
+
 ## Schema DSL
 
 ### Field Types
@@ -562,6 +706,109 @@ export default defineConfig({
 });
 ```
 
+## File Organization
+
+Schemock supports organizing schemas across multiple files and directories. The CLI discovers all schemas via glob patterns and merges them before generation - **no code changes needed**.
+
+### Recommended Structure
+
+```
+src/schemas/
+├── entities/           # Entity definitions (defineData)
+│   ├── user.ts
+│   ├── post.ts
+│   └── comment.ts
+├── endpoints/          # Custom API endpoints (defineEndpoint)
+│   ├── search.ts
+│   └── bulk-operations.ts
+├── views/              # Composite views (defineView)
+│   └── user-profile.ts
+└── index.ts            # Optional barrel exports
+```
+
+Or organize by domain:
+
+```
+src/schemas/
+├── auth/
+│   ├── user.ts
+│   ├── session.ts
+│   └── auth-endpoints.ts
+├── content/
+│   ├── post.ts
+│   ├── comment.ts
+│   └── search-endpoint.ts
+└── billing/
+    ├── subscription.ts
+    └── payment.ts
+```
+
+### How It Works
+
+1. **Discovery is file-agnostic** - The glob pattern `./src/schemas/**/*.ts` catches all files
+2. **References are string-based** - Relations use entity names, not imports:
+   ```typescript
+   // entities/post.ts
+   belongsTo('user')  // References 'user' by name, not import
+   field.ref('user')  // Same - string reference
+   ```
+3. **Merging happens before analysis** - All schemas are combined, so cross-file references resolve correctly
+4. **Endpoints access all entities** - `mockResolver` receives `db` with every entity:
+   ```typescript
+   // endpoints/search.ts
+   mockResolver: async ({ db }) => {
+     const users = db.user.findMany(...);  // Works!
+     const posts = db.post.findMany(...);  // Works!
+   }
+   ```
+
+### Configuration
+
+A single glob pattern discovers everything:
+
+```typescript
+// schemock.config.ts
+export default {
+  schemas: './src/schemas/**/*.ts',  // Catches all subdirectories
+  output: './src/generated',
+  // ...
+};
+```
+
+### Cross-File Example
+
+```typescript
+// entities/user.ts
+export const User = defineData('user', {
+  id: field.uuid(),
+  name: field.string(),
+}, {
+  relations: {
+    posts: hasMany('post'),  // String reference to Post
+  },
+});
+
+// entities/post.ts (separate file)
+export const Post = defineData('post', {
+  id: field.uuid(),
+  authorId: field.ref('user'),  // String reference to User
+}, {
+  relations: {
+    author: belongsTo('user'),  // String reference to User
+  },
+});
+
+// endpoints/stats.ts (separate file)
+export const StatsEndpoint = defineEndpoint('/api/stats', {
+  mockResolver: async ({ db }) => ({
+    userCount: db.user.count(),   // Access User entity
+    postCount: db.post.count(),   // Access Post entity
+  }),
+});
+```
+
+All three files are discovered, merged, and work together seamlessly.
+
 ## Multi-Target Generation
 
 Generate multiple outputs from a single schema - client SDKs, API routes, and server handlers all at once:

package/dist/cli/index.d.mts

@@ -452,6 +452,8 @@ interface GenerateOptions {
     only?: string[];
     /** Exclude these entities (applies to all targets) */
     exclude?: string[];
+    /** Generate form schemas (Zod validation, defaults, column metadata) */
+    withFormSchemas?: boolean;
 }
 /**
  * Options for the generate:sql command
@@ -598,6 +600,115 @@ declare function analyzeSchemas(schemas: EntitySchema[], config: SchemockConfig)
  */
 declare function generate(options: GenerateOptions): Promise<void>;
 
+/**
+ * CLAUDE.md generator for Schemock
+ *
+ * Generates AI-friendly documentation that helps Claude Code understand
+ * how to work with Schemock projects without corrupting user content.
+ *
+ * @module cli/generators/claude-md
+ * @category CLI
+ */
+
+/**
+ * Result of CLAUDE.md generation
+ */
+interface ClaudeMdResult {
+    /** Whether CLAUDE.md was created (vs updated) */
+    created: boolean;
+    /** Whether the file was modified */
+    modified: boolean;
+    /** The final content */
+    content: string;
+    /** Path to the file */
+    path: string;
+    /** Warning messages if any */
+    warnings: string[];
+}
+/**
+ * Generate the Schemock section content based on config
+ *
+ * @param config - Schemock configuration
+ * @returns Markdown content for the Schemock section
+ */
+declare function generateSchemockSection(config: SchemockConfig): string;
+/**
+ * Merge Schemock section into existing CLAUDE.md content
+ *
+ * This function is careful to:
+ * 1. Preserve all user content outside the Schemock section
+ * 2. Replace existing Schemock section if present
+ * 3. Append new section if not present
+ * 4. Not corrupt any existing formatting
+ *
+ * @param existingContent - Current CLAUDE.md content (or empty string)
+ * @param schemockSection - The Schemock section to insert
+ * @returns Updated content with Schemock section
+ */
+declare function mergeClaudeMdContent(existingContent: string, schemockSection: string): {
+    content: string;
+    wasUpdated: boolean;
+};
+/**
+ * Generate the complete CLAUDE.md content
+ *
+ * @param config - Schemock configuration
+ * @param existingContent - Existing CLAUDE.md content (if any)
+ * @returns Generated/merged content and metadata
+ */
+declare function generateClaudeMd(config: SchemockConfig, existingContent?: string): ClaudeMdResult;
+/**
+ * Generate .cursorrules content (Cursor IDE equivalent)
+ *
+ * @param config - Schemock configuration
+ * @returns Content for .cursorrules file
+ */
+declare function generateCursorRules(config: SchemockConfig): string;
+
+/**
+ * Setup AI configuration command for Schemock CLI
+ *
+ * Generates CLAUDE.md and optionally .cursorrules to help AI tools
+ * understand how to work with Schemock projects.
+ *
+ * @module cli/commands/setup-ai
+ * @category CLI
+ */
+
+/**
+ * Options for setup:ai command
+ */
+interface SetupAIOptions {
+    /** Config file path */
+    config?: string;
+    /** Also generate .cursorrules */
+    cursor?: boolean;
+    /** Dry run - show what would be generated */
+    dryRun?: boolean;
+    /** Force overwrite without checking for existing content */
+    force?: boolean;
+    /** Output directory (defaults to current directory) */
+    output?: string;
+}
+/**
+ * Result of setup:ai command
+ */
+interface SetupAIResult {
+    claudeMd: ClaudeMdResult;
+    cursorRules?: {
+        created: boolean;
+        modified: boolean;
+        path: string;
+    };
+}
+/**
+ * Main setup:ai command
+ *
+ * @param options - Command options
+ * @returns Result of the operation
+ */
+declare function setupAI(options?: SetupAIOptions): Promise<SetupAIResult>;
+
 /**
  * Pluralization utility for entity names
  *
@@ -910,4 +1021,19 @@ declare function generateFirebaseClient(schemas: AnalyzedSchema[], config: Fireb
  */
 declare function generateFetchClient(schemas: AnalyzedSchema[], config: FetchAdapterConfig): string;
 
-export { type AnalyzedComputed, type AnalyzedEndpoint, type AnalyzedEndpointField, type AnalyzedField, type AnalyzedIndex, type AnalyzedRLS, type AnalyzedRPC, type AnalyzedRelation, type AnalyzedSchema, type AuthProviderConfig, CodeBuilder, type FakerMapping, type FetchAdapterConfig, type FirebaseAdapterConfig, type GenerateOptions, type GenerateSQLOptions, type GenerationTarget, type GraphQLAdapterConfig, type MockAdapterConfig, type PGliteAdapterConfig, type PluralizeConfig, RLSBypass, RLSConfig, RLSScopeMapping, type SQLGeneratorResult, type SchemockConfig, type SupabaseAdapterConfig, type TargetMiddlewareConfig, type TargetType, analyzeSchemas, defineConfig, discoverSchemas, fieldToFakerCall, fieldToTsType, generate, generateFetchClient, generateFirebaseClient, generateHooks, generateMockClient, generateMockDb, generateMockHandlers, generateSeed, generateSupabaseClient, generateTypes, getDefaultConfig, getRelativePath, loadConfig, pluralize, primitiveToTs, toCamelCase, toPascalCase };
+/**
+ * Form schema generator - generates Zod validation schemas, form defaults, and table column metadata
+ *
+ * @module cli/generators/form-schemas
+ * @category CLI
+ */
+
+/**
+ * Generate form-related schemas and metadata for all entities
+ *
+ * @param schemas - Analyzed schemas
+ * @returns Generated TypeScript code
+ */
+declare function generateFormSchemas(schemas: AnalyzedSchema[]): string;
+
+export { type AnalyzedComputed, type AnalyzedEndpoint, type AnalyzedEndpointField, type AnalyzedField, type AnalyzedIndex, type AnalyzedRLS, type AnalyzedRPC, type AnalyzedRelation, type AnalyzedSchema, type AuthProviderConfig, CodeBuilder, type FakerMapping, type FetchAdapterConfig, type FirebaseAdapterConfig, type GenerateOptions, type GenerateSQLOptions, type GenerationTarget, type GraphQLAdapterConfig, type MockAdapterConfig, type PGliteAdapterConfig, type PluralizeConfig, RLSBypass, RLSConfig, RLSScopeMapping, type SQLGeneratorResult, type SchemockConfig, type SupabaseAdapterConfig, type TargetMiddlewareConfig, type TargetType, analyzeSchemas, defineConfig, discoverSchemas, fieldToFakerCall, fieldToTsType, generate, generateClaudeMd, generateCursorRules, generateFetchClient, generateFirebaseClient, generateFormSchemas, generateHooks, generateMockClient, generateMockDb, generateMockHandlers, generateSchemockSection, generateSeed, generateSupabaseClient, generateTypes, getDefaultConfig, getRelativePath, loadConfig, mergeClaudeMdContent, pluralize, primitiveToTs, setupAI, toCamelCase, toPascalCase };

package/dist/cli/index.d.ts

@@ -452,6 +452,8 @@ interface GenerateOptions {
     only?: string[];
     /** Exclude these entities (applies to all targets) */
     exclude?: string[];
+    /** Generate form schemas (Zod validation, defaults, column metadata) */
+    withFormSchemas?: boolean;
 }
 /**
  * Options for the generate:sql command
@@ -598,6 +600,115 @@ declare function analyzeSchemas(schemas: EntitySchema[], config: SchemockConfig)
  */
 declare function generate(options: GenerateOptions): Promise<void>;
 
+/**
+ * CLAUDE.md generator for Schemock
+ *
+ * Generates AI-friendly documentation that helps Claude Code understand
+ * how to work with Schemock projects without corrupting user content.
+ *
+ * @module cli/generators/claude-md
+ * @category CLI
+ */
+
+/**
+ * Result of CLAUDE.md generation
+ */
+interface ClaudeMdResult {
+    /** Whether CLAUDE.md was created (vs updated) */
+    created: boolean;
+    /** Whether the file was modified */
+    modified: boolean;
+    /** The final content */
+    content: string;
+    /** Path to the file */
+    path: string;
+    /** Warning messages if any */
+    warnings: string[];
+}
+/**
+ * Generate the Schemock section content based on config
+ *
+ * @param config - Schemock configuration
+ * @returns Markdown content for the Schemock section
+ */
+declare function generateSchemockSection(config: SchemockConfig): string;
+/**
+ * Merge Schemock section into existing CLAUDE.md content
+ *
+ * This function is careful to:
+ * 1. Preserve all user content outside the Schemock section
+ * 2. Replace existing Schemock section if present
+ * 3. Append new section if not present
+ * 4. Not corrupt any existing formatting
+ *
+ * @param existingContent - Current CLAUDE.md content (or empty string)
+ * @param schemockSection - The Schemock section to insert
+ * @returns Updated content with Schemock section
+ */
+declare function mergeClaudeMdContent(existingContent: string, schemockSection: string): {
+    content: string;
+    wasUpdated: boolean;
+};
+/**
+ * Generate the complete CLAUDE.md content
+ *
+ * @param config - Schemock configuration
+ * @param existingContent - Existing CLAUDE.md content (if any)
+ * @returns Generated/merged content and metadata
+ */
+declare function generateClaudeMd(config: SchemockConfig, existingContent?: string): ClaudeMdResult;
+/**
+ * Generate .cursorrules content (Cursor IDE equivalent)
+ *
+ * @param config - Schemock configuration
+ * @returns Content for .cursorrules file
+ */
+declare function generateCursorRules(config: SchemockConfig): string;
+
+/**
+ * Setup AI configuration command for Schemock CLI
+ *
+ * Generates CLAUDE.md and optionally .cursorrules to help AI tools
+ * understand how to work with Schemock projects.
+ *
+ * @module cli/commands/setup-ai
+ * @category CLI
+ */
+
+/**
+ * Options for setup:ai command
+ */
+interface SetupAIOptions {
+    /** Config file path */
+    config?: string;
+    /** Also generate .cursorrules */
+    cursor?: boolean;
+    /** Dry run - show what would be generated */
+    dryRun?: boolean;
+    /** Force overwrite without checking for existing content */
+    force?: boolean;
+    /** Output directory (defaults to current directory) */
+    output?: string;
+}
+/**
+ * Result of setup:ai command
+ */
+interface SetupAIResult {
+    claudeMd: ClaudeMdResult;
+    cursorRules?: {
+        created: boolean;
+        modified: boolean;
+        path: string;
+    };
+}
+/**
+ * Main setup:ai command
+ *
+ * @param options - Command options
+ * @returns Result of the operation
+ */
+declare function setupAI(options?: SetupAIOptions): Promise<SetupAIResult>;
+
 /**
  * Pluralization utility for entity names
  *
@@ -910,4 +1021,19 @@ declare function generateFirebaseClient(schemas: AnalyzedSchema[], config: Fireb
  */
 declare function generateFetchClient(schemas: AnalyzedSchema[], config: FetchAdapterConfig): string;
 
-export { type AnalyzedComputed, type AnalyzedEndpoint, type AnalyzedEndpointField, type AnalyzedField, type AnalyzedIndex, type AnalyzedRLS, type AnalyzedRPC, type AnalyzedRelation, type AnalyzedSchema, type AuthProviderConfig, CodeBuilder, type FakerMapping, type FetchAdapterConfig, type FirebaseAdapterConfig, type GenerateOptions, type GenerateSQLOptions, type GenerationTarget, type GraphQLAdapterConfig, type MockAdapterConfig, type PGliteAdapterConfig, type PluralizeConfig, RLSBypass, RLSConfig, RLSScopeMapping, type SQLGeneratorResult, type SchemockConfig, type SupabaseAdapterConfig, type TargetMiddlewareConfig, type TargetType, analyzeSchemas, defineConfig, discoverSchemas, fieldToFakerCall, fieldToTsType, generate, generateFetchClient, generateFirebaseClient, generateHooks, generateMockClient, generateMockDb, generateMockHandlers, generateSeed, generateSupabaseClient, generateTypes, getDefaultConfig, getRelativePath, loadConfig, pluralize, primitiveToTs, toCamelCase, toPascalCase };
+/**
+ * Form schema generator - generates Zod validation schemas, form defaults, and table column metadata
+ *
+ * @module cli/generators/form-schemas
+ * @category CLI
+ */
+
+/**
+ * Generate form-related schemas and metadata for all entities
+ *
+ * @param schemas - Analyzed schemas
+ * @returns Generated TypeScript code
+ */
+declare function generateFormSchemas(schemas: AnalyzedSchema[]): string;
+
+export { type AnalyzedComputed, type AnalyzedEndpoint, type AnalyzedEndpointField, type AnalyzedField, type AnalyzedIndex, type AnalyzedRLS, type AnalyzedRPC, type AnalyzedRelation, type AnalyzedSchema, type AuthProviderConfig, CodeBuilder, type FakerMapping, type FetchAdapterConfig, type FirebaseAdapterConfig, type GenerateOptions, type GenerateSQLOptions, type GenerationTarget, type GraphQLAdapterConfig, type MockAdapterConfig, type PGliteAdapterConfig, type PluralizeConfig, RLSBypass, RLSConfig, RLSScopeMapping, type SQLGeneratorResult, type SchemockConfig, type SupabaseAdapterConfig, type TargetMiddlewareConfig, type TargetType, analyzeSchemas, defineConfig, discoverSchemas, fieldToFakerCall, fieldToTsType, generate, generateClaudeMd, generateCursorRules, generateFetchClient, generateFirebaseClient, generateFormSchemas, generateHooks, generateMockClient, generateMockDb, generateMockHandlers, generateSchemockSection, generateSeed, generateSupabaseClient, generateTypes, getDefaultConfig, getRelativePath, loadConfig, mergeClaudeMdContent, pluralize, primitiveToTs, setupAI, toCamelCase, toPascalCase };