@claudetools/tools 0.8.10 → 0.9.0

package/dist/codedna/kappa-cli.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// =============================================================================
+// Kappa v2.5 CLI
+// =============================================================================
+//
+// Command-line interface for the Kappa DSL.
+// Parse, validate, and generate code from Kappa specifications.
+//
+import { parseArgs } from 'node:util';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, watch } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+import { parseToAST } from './kappa-parser.js';
+import { validateKappaSpec, formatValidationResults } from './kappa-validator.js';
+import { generateDrizzleSchema } from './kappa-drizzle-generator.js';
+import { generateZodSchemas } from './kappa-zod-generator.js';
+import { generateTypeScriptTypes } from './kappa-types-generator.js';
+import { generateAPI } from './kappa-api-generator.js';
+// =============================================================================
+// Version
+// =============================================================================
+const VERSION = '2.5.0';
+// =============================================================================
+// Help Text
+// =============================================================================
+const HELP_TEXT = `
+Kappa v${VERSION} - Declarative Application Specification Language
+
+Usage:
+  kappa [command] [options] <file.kappa>
+
+Commands:
+  parse      Parse and display the AST
+  validate   Validate the specification
+  generate   Generate code from the specification (default)
+
+Options:
+  -h, --help        Show this help message
+  -v, --version     Show version number
+  -o, --output      Output directory (default: ./generated)
+  -w, --watch       Watch for changes and regenerate
+  -q, --quiet       Suppress non-error output
+  --validate        Validate before generating (default: true)
+  --generate        What to generate: drizzle,zod,types,api (default: all)
+  --framework       API framework: hono,express,trpc (default: hono)
+  --dialect         Database dialect: postgresql,sqlite,mysql (default: postgresql)
+
+Examples:
+  kappa app.kappa                    # Generate all code
+  kappa validate app.kappa           # Validate only
+  kappa parse app.kappa              # Show AST
+  kappa -o src/db app.kappa          # Output to src/db
+  kappa --generate drizzle,zod app.kappa  # Generate specific outputs
+  kappa -w app.kappa                 # Watch mode
+
+`;
+// =============================================================================
+// CLI Parsing
+// =============================================================================
+function parseCliArgs() {
+    const { values, positionals } = parseArgs({
+        options: {
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+            output: { type: 'string', short: 'o', default: './generated' },
+            watch: { type: 'boolean', short: 'w', default: false },
+            validate: { type: 'boolean', default: true },
+            generate: { type: 'string', multiple: true, default: [] },
+            framework: { type: 'string', default: 'hono' },
+            dialect: { type: 'string', default: 'postgresql' },
+            quiet: { type: 'boolean', short: 'q', default: false },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    // Determine command and file
+    let command = 'generate';
+    let file = '';
+    if (positionals.length === 1) {
+        // Just a file - default to generate
+        file = positionals[0];
+    }
+    else if (positionals.length >= 2) {
+        // Command and file
+        command = positionals[0];
+        file = positionals[1];
+    }
+    // Parse generate option (can be comma-separated)
+    let generateList = [];
+    const generateOpt = values.generate;
+    if (generateOpt && generateOpt.length > 0) {
+        for (const g of generateOpt) {
+            generateList.push(...g.split(','));
+        }
+    }
+    if (generateList.length === 0) {
+        generateList = ['drizzle', 'zod', 'types', 'api'];
+    }
+    return {
+        options: {
+            help: values.help ?? false,
+            version: values.version ?? false,
+            output: values.output ?? './generated',
+            watch: values.watch ?? false,
+            validate: values.validate ?? true,
+            generate: generateList,
+            framework: values.framework ?? 'hono',
+            dialect: values.dialect ?? 'postgresql',
+            quiet: values.quiet ?? false,
+        },
+        command,
+        file,
+    };
+}
+// =============================================================================
+// Commands
+// =============================================================================
+function log(options, message) {
+    if (!options.quiet) {
+        console.log(message);
+    }
+}
+function parseCommand(file, options) {
+    const content = readFileSync(file, 'utf-8');
+    const ast = parseToAST(content);
+    if (!ast) {
+        console.error(`Error: Failed to parse ${file}`);
+        return null;
+    }
+    log(options, JSON.stringify(ast, null, 2));
+    return ast;
+}
+function validateCommand(file, options) {
+    const content = readFileSync(file, 'utf-8');
+    const ast = parseToAST(content);
+    if (!ast) {
+        console.error(`Error: Failed to parse ${file}`);
+        return false;
+    }
+    const result = validateKappaSpec(ast);
+    const formatted = formatValidationResults(result);
+    if (result.valid) {
+        log(options, `✓ ${file} is valid`);
+        if (result.warnings.length > 0) {
+            console.log(formatted);
+        }
+        return true;
+    }
+    else {
+        console.error(`✗ ${file} has errors:`);
+        console.error(formatted);
+        return false;
+    }
+}
+function generateCommand(file, options) {
+    const content = readFileSync(file, 'utf-8');
+    const ast = parseToAST(content);
+    if (!ast) {
+        console.error(`Error: Failed to parse ${file}`);
+        return false;
+    }
+    // Validate first if requested
+    if (options.validate) {
+        const result = validateKappaSpec(ast);
+        if (!result.valid) {
+            console.error(`✗ Validation failed for ${file}:`);
+            console.error(formatValidationResults(result));
+            return false;
+        }
+    }
+    // Ensure output directory exists
+    if (!existsSync(options.output)) {
+        mkdirSync(options.output, { recursive: true });
+    }
+    const specName = basename(file, extname(file));
+    let filesWritten = 0;
+    // Generate Drizzle schema
+    if (options.generate.includes('drizzle') && ast.entities.length > 0) {
+        const drizzle = generateDrizzleSchema(ast.entities, {
+            dialect: options.dialect,
+            provenance: true,
+        });
+        writeFileSync(join(options.output, `${specName}.schema.ts`), drizzle.schema);
+        filesWritten++;
+        if (drizzle.types) {
+            writeFileSync(join(options.output, `${specName}.schema.types.ts`), drizzle.types);
+            filesWritten++;
+        }
+        if (drizzle.relations) {
+            writeFileSync(join(options.output, `${specName}.relations.ts`), drizzle.relations);
+            filesWritten++;
+        }
+        log(options, `  ✓ Drizzle schema`);
+    }
+    // Generate Zod schemas
+    if (options.generate.includes('zod') && ast.entities.length > 0) {
+        const zod = generateZodSchemas(ast.entities, { provenance: true });
+        writeFileSync(join(options.output, `${specName}.schemas.ts`), zod.schemas);
+        filesWritten++;
+        log(options, `  ✓ Zod validation schemas`);
+    }
+    // Generate TypeScript types
+    if (options.generate.includes('types') && ast.entities.length > 0) {
+        const types = generateTypeScriptTypes(ast.entities, { provenance: true });
+        writeFileSync(join(options.output, `${specName}.types.ts`), types.types);
+        filesWritten++;
+        log(options, `  ✓ TypeScript types`);
+    }
+    // Generate API routes
+    if (options.generate.includes('api') && ast.apis.length > 0) {
+        const api = generateAPI(ast.apis, {
+            framework: options.framework,
+            provenance: true,
+        });
+        writeFileSync(join(options.output, `${specName}.routes.ts`), api.routes);
+        filesWritten++;
+        if (api.validation) {
+            writeFileSync(join(options.output, `${specName}.validation.ts`), api.validation);
+            filesWritten++;
+        }
+        if (api.errors) {
+            writeFileSync(join(options.output, `${specName}.errors.ts`), api.errors);
+            filesWritten++;
+        }
+        log(options, `  ✓ API routes (${options.framework})`);
+    }
+    log(options, `\n✓ Generated ${filesWritten} files to ${options.output}/`);
+    return true;
+}
+function watchMode(file, options) {
+    log(options, `Watching ${file} for changes...`);
+    log(options, 'Press Ctrl+C to stop.\n');
+    // Initial generation
+    generateCommand(file, options);
+    // Watch for changes
+    const watcher = watch(file, (eventType) => {
+        if (eventType === 'change') {
+            log(options, `\n[${new Date().toLocaleTimeString()}] File changed, regenerating...`);
+            generateCommand(file, options);
+        }
+    });
+    // Handle Ctrl+C
+    process.on('SIGINT', () => {
+        watcher.close();
+        log(options, '\nStopped watching.');
+        process.exit(0);
+    });
+}
+// =============================================================================
+// Main
+// =============================================================================
+async function main() {
+    const { options, command, file } = parseCliArgs();
+    // Handle help
+    if (options.help) {
+        console.log(HELP_TEXT);
+        process.exit(0);
+    }
+    // Handle version
+    if (options.version) {
+        console.log(`Kappa v${VERSION}`);
+        process.exit(0);
+    }
+    // Require a file
+    if (!file) {
+        console.error('Error: No input file specified.');
+        console.error('Usage: kappa [command] [options] <file.kappa>');
+        console.error('Run "kappa --help" for more information.');
+        process.exit(1);
+    }
+    // Check file exists
+    if (!existsSync(file)) {
+        console.error(`Error: File not found: ${file}`);
+        process.exit(1);
+    }
+    // Execute command
+    let success = true;
+    switch (command) {
+        case 'parse':
+            const ast = parseCommand(file, options);
+            success = ast !== null;
+            break;
+        case 'validate':
+            success = validateCommand(file, options);
+            break;
+        case 'generate':
+        default:
+            if (options.watch) {
+                watchMode(file, options);
+                return; // Watch mode doesn't exit
+            }
+            else {
+                success = generateCommand(file, options);
+            }
+            break;
+    }
+    process.exit(success ? 0 : 1);
+}
+// Run if executed directly
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/codedna/kappa-component-generator.d.ts

@@ -0,0 +1,47 @@
+import type { ComponentBlock } from './kappa-ast.js';
+export interface ComponentGeneratorOptions {
+    /** Add provenance comments (default: true) */
+    provenance?: boolean;
+    /** Generate TypeScript (default: true) */
+    typescript?: boolean;
+    /** Use forwardRef (default: false) */
+    forwardRef?: boolean;
+    /** Base path for components (default: 'components') */
+    basePath?: string;
+}
+export interface GeneratedComponent {
+    /** Component file path */
+    path: string;
+    /** Component content */
+    content: string;
+}
+export interface GeneratedComponents {
+    /** Generated component files */
+    components: GeneratedComponent[];
+}
+export declare class KappaComponentGenerator {
+    private provenance;
+    private typescript;
+    private forwardRef;
+    private basePath;
+    constructor(options?: ComponentGeneratorOptions);
+    /**
+     * Generate component files from ComponentBlock AST nodes
+     */
+    generate(components: ComponentBlock[]): GeneratedComponents;
+    private generateSimpleComponent;
+    private generatePropsInterface;
+    private generateFunctionComponent;
+    private generateForwardRefComponent;
+    private getDestructuredProps;
+    private generateStructureJSX;
+    private generateVariants;
+    private generateCompoundComponent;
+    private generateCompoundPart;
+    private mapPropType;
+    private toKebabCase;
+}
+/**
+ * Generate component files from Kappa ComponentBlock nodes
+ */
+export declare function generateComponents(components: ComponentBlock[], options?: ComponentGeneratorOptions): GeneratedComponents;

package/dist/codedna/kappa-component-generator.js

@@ -0,0 +1,295 @@
+// =============================================================================
+// Kappa v2.5 Component Generator
+// =============================================================================
+//
+// Generates React components from Kappa ComponentBlock AST.
+// Supports compound components, variants, and structured layouts.
+//
+// =============================================================================
+// Generator Class
+// =============================================================================
+export class KappaComponentGenerator {
+    provenance;
+    typescript;
+    forwardRef;
+    basePath;
+    constructor(options = {}) {
+        this.provenance = options.provenance ?? true;
+        this.typescript = options.typescript ?? true;
+        this.forwardRef = options.forwardRef ?? false;
+        this.basePath = options.basePath ?? 'components';
+    }
+    /**
+     * Generate component files from ComponentBlock AST nodes
+     */
+    generate(components) {
+        const generatedComponents = [];
+        for (const component of components) {
+            if (component.compound && component.compound.length > 0) {
+                generatedComponents.push(this.generateCompoundComponent(component));
+            }
+            else {
+                generatedComponents.push(this.generateSimpleComponent(component));
+            }
+        }
+        return { components: generatedComponents };
+    }
+    // ===========================================================================
+    // Simple Component Generation
+    // ===========================================================================
+    generateSimpleComponent(component) {
+        const lines = [];
+        const ext = this.typescript ? 'tsx' : 'jsx';
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Component: ${component.name}`);
+            lines.push('');
+        }
+        // Imports
+        if (this.forwardRef) {
+            lines.push("import { forwardRef } from 'react';");
+        }
+        lines.push("import { cn } from '@/lib/utils';");
+        lines.push('');
+        // Props interface
+        if (this.typescript) {
+            lines.push(this.generatePropsInterface(component));
+            lines.push('');
+        }
+        // Component
+        if (this.forwardRef) {
+            lines.push(this.generateForwardRefComponent(component));
+        }
+        else {
+            lines.push(this.generateFunctionComponent(component));
+        }
+        // Variants
+        if (component.variants.length > 0) {
+            lines.push('');
+            lines.push(this.generateVariants(component));
+        }
+        return {
+            path: `${this.basePath}/${this.toKebabCase(component.name)}.${ext}`,
+            content: lines.join('\n'),
+        };
+    }
+    generatePropsInterface(component) {
+        const lines = [];
+        const propsName = `${component.name}Props`;
+        lines.push(`export interface ${propsName} {`);
+        for (const prop of component.props) {
+            const optional = prop.optional ? '?' : '';
+            lines.push(`  ${prop.name}${optional}: ${this.mapPropType(prop.type)};`);
+        }
+        // Add className and children by default
+        lines.push('  className?: string;');
+        lines.push('  children?: React.ReactNode;');
+        lines.push('}');
+        return lines.join('\n');
+    }
+    generateFunctionComponent(component) {
+        const lines = [];
+        const propsType = this.typescript ? `: ${component.name}Props` : '';
+        const destructuredProps = this.getDestructuredProps(component);
+        lines.push(`export function ${component.name}({ ${destructuredProps} }${propsType}) {`);
+        lines.push('  return (');
+        if (component.structure) {
+            lines.push(this.generateStructureJSX(component.structure, 4));
+        }
+        else {
+            lines.push(`    <div className={cn('${this.toKebabCase(component.name)}', className)}>`);
+            lines.push('      {children}');
+            lines.push('    </div>');
+        }
+        lines.push('  );');
+        lines.push('}');
+        return lines.join('\n');
+    }
+    generateForwardRefComponent(component) {
+        const lines = [];
+        const propsType = this.typescript ? `${component.name}Props` : '';
+        const refType = this.typescript ? ', HTMLDivElement' : '';
+        const destructuredProps = this.getDestructuredProps(component);
+        lines.push(`export const ${component.name} = forwardRef<${refType.slice(2)}${propsType ? `, ${propsType}` : ''}>(`);
+        lines.push(`  function ${component.name}({ ${destructuredProps} }, ref) {`);
+        lines.push('    return (');
+        if (component.structure) {
+            lines.push(this.generateStructureJSX(component.structure, 6, 'ref={ref}'));
+        }
+        else {
+            lines.push(`      <div ref={ref} className={cn('${this.toKebabCase(component.name)}', className)}>`);
+            lines.push('        {children}');
+            lines.push('      </div>');
+        }
+        lines.push('    );');
+        lines.push('  }');
+        lines.push(');');
+        return lines.join('\n');
+    }
+    getDestructuredProps(component) {
+        const propNames = component.props.map((p) => p.name);
+        propNames.push('className', 'children');
+        return propNames.join(', ');
+    }
+    generateStructureJSX(structure, indent, extraProps = '') {
+        const spaces = ' '.repeat(indent);
+        const lines = [];
+        const props = Object.entries(structure.props || {})
+            .map(([k, v]) => `${k}="${v}"`)
+            .join(' ');
+        const allProps = [extraProps, props, 'className={cn(className)}'].filter(Boolean).join(' ');
+        if (structure.children && structure.children.length > 0) {
+            lines.push(`${spaces}<${structure.type} ${allProps}>`);
+            for (const child of structure.children) {
+                lines.push(this.generateStructureJSX(child, indent + 2));
+            }
+            lines.push(`${spaces}</${structure.type}>`);
+        }
+        else {
+            lines.push(`${spaces}<${structure.type} ${allProps}>{children}</${structure.type}>`);
+        }
+        return lines.join('\n');
+    }
+    generateVariants(component) {
+        const lines = [];
+        lines.push('// Variants');
+        for (const variant of component.variants) {
+            const variantName = `${component.name}${variant.name}`;
+            lines.push(`export const ${variantName} = ${component.name};`);
+            lines.push(`${variantName}.displayName = '${variantName}';`);
+        }
+        return lines.join('\n');
+    }
+    // ===========================================================================
+    // Compound Component Generation
+    // ===========================================================================
+    generateCompoundComponent(component) {
+        const lines = [];
+        const ext = this.typescript ? 'tsx' : 'jsx';
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Compound Component: ${component.name}`);
+            lines.push('');
+        }
+        // Imports
+        lines.push("import { createContext, useContext } from 'react';");
+        lines.push("import { cn } from '@/lib/utils';");
+        lines.push('');
+        // Context
+        if (this.typescript) {
+            lines.push(`interface ${component.name}ContextValue {`);
+            for (const prop of component.props) {
+                lines.push(`  ${prop.name}${prop.optional ? '?' : ''}: ${this.mapPropType(prop.type)};`);
+            }
+            lines.push('}');
+            lines.push('');
+        }
+        const contextType = this.typescript ? `${component.name}ContextValue | null` : '';
+        lines.push(`const ${component.name}Context = createContext<${contextType}>(null);`);
+        lines.push('');
+        // Hook
+        lines.push(`function use${component.name}() {`);
+        lines.push(`  const context = useContext(${component.name}Context);`);
+        lines.push('  if (!context) {');
+        lines.push(`    throw new Error('${component.name} compound components must be used within ${component.name}');`);
+        lines.push('  }');
+        lines.push('  return context;');
+        lines.push('}');
+        lines.push('');
+        // Root component props
+        if (this.typescript) {
+            lines.push(this.generatePropsInterface(component));
+            lines.push('');
+        }
+        // Root component
+        const destructuredProps = this.getDestructuredProps(component);
+        const propsType = this.typescript ? `: ${component.name}Props` : '';
+        lines.push(`function ${component.name}Root({ ${destructuredProps} }${propsType}) {`);
+        const contextValue = component.props.map((p) => p.name).join(', ');
+        lines.push(`  const value = { ${contextValue} };`);
+        lines.push('');
+        lines.push('  return (');
+        lines.push(`    <${component.name}Context.Provider value={value}>`);
+        lines.push(`      <div className={cn('${this.toKebabCase(component.name)}', className)}>`);
+        lines.push('        {children}');
+        lines.push('      </div>');
+        lines.push(`    </${component.name}Context.Provider>`);
+        lines.push('  );');
+        lines.push('}');
+        lines.push('');
+        // Compound parts
+        for (const part of component.compound) {
+            lines.push(this.generateCompoundPart(component.name, part));
+            lines.push('');
+        }
+        // Export compound object
+        lines.push(`export const ${component.name} = Object.assign(${component.name}Root, {`);
+        for (const part of component.compound) {
+            lines.push(`  ${part.name}: ${component.name}${part.name},`);
+        }
+        lines.push('});');
+        return {
+            path: `${this.basePath}/${this.toKebabCase(component.name)}.${ext}`,
+            content: lines.join('\n'),
+        };
+    }
+    generateCompoundPart(parentName, part) {
+        const lines = [];
+        const partName = `${parentName}${part.name}`;
+        if (this.typescript) {
+            lines.push(`interface ${partName}Props {`);
+            lines.push('  className?: string;');
+            lines.push('  children?: React.ReactNode;');
+            if (part.props) {
+                for (const prop of part.props) {
+                    lines.push(`  ${prop}?: string;`);
+                }
+            }
+            lines.push('}');
+            lines.push('');
+        }
+        const propsType = this.typescript ? `: ${partName}Props` : '';
+        const propsStr = part.props ? `{ className, children, ${part.props.join(', ')} }` : '{ className, children }';
+        lines.push(`function ${partName}(${propsStr}${propsType}) {`);
+        lines.push(`  const context = use${parentName}();`);
+        lines.push('');
+        lines.push('  return (');
+        lines.push(`    <${part.element} className={cn('${this.toKebabCase(partName)}', className)}>`);
+        lines.push('      {children}');
+        lines.push(`    </${part.element}>`);
+        lines.push('  );');
+        lines.push('}');
+        return lines.join('\n');
+    }
+    // ===========================================================================
+    // Helpers
+    // ===========================================================================
+    mapPropType(type) {
+        const typeMap = {
+            string: 'string',
+            number: 'number',
+            boolean: 'boolean',
+            node: 'React.ReactNode',
+            element: 'React.ReactElement',
+            func: '() => void',
+            array: 'unknown[]',
+            object: 'Record<string, unknown>',
+        };
+        return typeMap[type] || type;
+    }
+    toKebabCase(str) {
+        return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    }
+}
+// =============================================================================
+// Convenience Function
+// =============================================================================
+/**
+ * Generate component files from Kappa ComponentBlock nodes
+ */
+export function generateComponents(components, options = {}) {
+    const generator = new KappaComponentGenerator(options);
+    return generator.generate(components);
+}

package/dist/codedna/kappa-design-generator.d.ts

@@ -0,0 +1,52 @@
+import type { DesignBlock } from './kappa-ast.js';
+export type DesignOutputFormat = 'css' | 'tailwind' | 'both';
+export interface DesignGeneratorOptions {
+    /** Output format (default: 'both') */
+    format?: DesignOutputFormat;
+    /** Add provenance comments (default: true) */
+    provenance?: boolean;
+    /** CSS custom property prefix (default: '') */
+    prefix?: string;
+    /** Use HSL values instead of hex (default: false) */
+    hsl?: boolean;
+}
+export interface GeneratedDesign {
+    /** CSS variables file */
+    css?: {
+        path: string;
+        content: string;
+    };
+    /** Tailwind config extension */
+    tailwind?: {
+        path: string;
+        content: string;
+    };
+}
+export declare class KappaDesignGenerator {
+    private format;
+    private provenance;
+    private prefix;
+    private hsl;
+    constructor(options?: DesignGeneratorOptions);
+    /**
+     * Generate design files from DesignBlock AST
+     */
+    generate(design: DesignBlock): GeneratedDesign;
+    private generateCSS;
+    private generateColorVariables;
+    private resolveColorValue;
+    private generateTypographyVariables;
+    private generateSpacingVariables;
+    private generateBorderVariables;
+    private generateShadowVariables;
+    private generateMotionVariables;
+    private generateTailwind;
+    private hexToHsl;
+    private adjustColor;
+    private addAlpha;
+    private toKebabCase;
+}
+/**
+ * Generate design system files from Kappa DesignBlock
+ */
+export declare function generateDesign(design: DesignBlock, options?: DesignGeneratorOptions): GeneratedDesign;