@claudetools/tools 0.8.10 → 0.9.0

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

@@ -0,0 +1,57 @@
+import type { PageBlock } from './kappa-ast.js';
+export type PageFramework = 'tanstack-start' | 'nextjs';
+export interface PageGeneratorOptions {
+    /** Target framework (default: 'tanstack-start') */
+    framework?: PageFramework;
+    /** Add provenance comments (default: true) */
+    provenance?: boolean;
+    /** Generate TypeScript (default: true) */
+    typescript?: boolean;
+    /** Use client components by default (Next.js only) */
+    clientComponents?: boolean;
+}
+export interface GeneratedPage {
+    /** Page file path (relative) */
+    path: string;
+    /** Page content */
+    content: string;
+    /** Loader file (if separate) */
+    loader?: {
+        path: string;
+        content: string;
+    };
+}
+export interface GeneratedPages {
+    /** Generated page files */
+    pages: GeneratedPage[];
+    /** Shared layout files */
+    layouts?: {
+        path: string;
+        content: string;
+    }[];
+}
+export declare class KappaPageGenerator {
+    private framework;
+    private provenance;
+    private typescript;
+    private clientComponents;
+    constructor(options?: PageGeneratorOptions);
+    /**
+     * Generate page files from PageBlock AST nodes
+     */
+    generate(pages: PageBlock[]): GeneratedPages;
+    private generateTanStackPage;
+    private generateTanStackLoader;
+    private generateNextJSPage;
+    private generateNextJSLoader;
+    private generateLayoutJSX;
+    private generateActionHandler;
+    private routeToFilePath;
+    private extractRouteParams;
+    private toCamelCase;
+    private toPascalCase;
+}
+/**
+ * Generate page files from Kappa PageBlock nodes
+ */
+export declare function generatePages(pages: PageBlock[], options?: PageGeneratorOptions): GeneratedPages;

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

@@ -0,0 +1,338 @@
+// =============================================================================
+// Kappa v2.5 Page Generator
+// =============================================================================
+//
+// Generates page/route components from Kappa PageBlock AST.
+// Supports TanStack Start and Next.js App Router.
+//
+// =============================================================================
+// Generator Class
+// =============================================================================
+export class KappaPageGenerator {
+    framework;
+    provenance;
+    typescript;
+    clientComponents;
+    constructor(options = {}) {
+        this.framework = options.framework ?? 'tanstack-start';
+        this.provenance = options.provenance ?? true;
+        this.typescript = options.typescript ?? true;
+        this.clientComponents = options.clientComponents ?? false;
+    }
+    /**
+     * Generate page files from PageBlock AST nodes
+     */
+    generate(pages) {
+        const generatedPages = [];
+        for (const page of pages) {
+            if (this.framework === 'tanstack-start') {
+                generatedPages.push(this.generateTanStackPage(page));
+            }
+            else {
+                generatedPages.push(this.generateNextJSPage(page));
+            }
+        }
+        return { pages: generatedPages };
+    }
+    // ===========================================================================
+    // TanStack Start Generation
+    // ===========================================================================
+    generateTanStackPage(page) {
+        const lines = [];
+        const ext = this.typescript ? 'tsx' : 'jsx';
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Page: ${page.name}`);
+            lines.push('');
+        }
+        // Imports
+        lines.push("import { createFileRoute } from '@tanstack/react-router';");
+        if (page.loaders.length > 0) {
+            lines.push("import { createServerFn } from '@tanstack/start';");
+        }
+        lines.push('');
+        // Generate loaders as server functions
+        for (const loader of page.loaders) {
+            lines.push(this.generateTanStackLoader(loader));
+            lines.push('');
+        }
+        // Generate route definition
+        lines.push(`export const Route = createFileRoute('${page.route}')({`);
+        // Add loader if present
+        if (page.loaders.length > 0) {
+            const loaderCalls = page.loaders.map((l) => `${this.toCamelCase(l.name)}()`).join(', ');
+            if (page.loaders.length === 1) {
+                lines.push(`  loader: () => ${loaderCalls},`);
+            }
+            else {
+                lines.push(`  loader: async () => {`);
+                lines.push(`    const [${page.loaders.map((l) => this.toCamelCase(l.name) + 'Data').join(', ')}] = await Promise.all([${loaderCalls}]);`);
+                lines.push(`    return { ${page.loaders.map((l) => this.toCamelCase(l.name) + 'Data').join(', ')} };`);
+                lines.push(`  },`);
+            }
+        }
+        // Add meta
+        if (page.title || page.meta) {
+            lines.push(`  meta: () => [{`);
+            if (page.title) {
+                lines.push(`    title: '${page.title}',`);
+            }
+            if (page.meta) {
+                for (const [key, value] of Object.entries(page.meta)) {
+                    lines.push(`    ${key}: '${value}',`);
+                }
+            }
+            lines.push(`  }],`);
+        }
+        // Add beforeLoad for guards
+        if (page.guard) {
+            lines.push(`  beforeLoad: ({ context }) => {`);
+            if (page.guard === 'authenticated') {
+                lines.push(`    if (!context.auth?.user) {`);
+                lines.push(`      throw redirect({ to: '/login' });`);
+                lines.push(`    }`);
+            }
+            else if (page.guard === 'guest_only') {
+                lines.push(`    if (context.auth?.user) {`);
+                lines.push(`      throw redirect({ to: '/dashboard' });`);
+                lines.push(`    }`);
+            }
+            lines.push(`  },`);
+        }
+        lines.push(`  component: ${page.name}Page,`);
+        lines.push('});');
+        lines.push('');
+        // Generate component
+        lines.push(`function ${page.name}Page() {`);
+        if (page.loaders.length > 0) {
+            lines.push(`  const loaderData = Route.useLoaderData();`);
+        }
+        lines.push(`  return (`);
+        // Generate layout or simple content
+        if (page.layout) {
+            lines.push(this.generateLayoutJSX(page.layout, 4));
+        }
+        else if (page.component) {
+            lines.push(`    <${page.component} />`);
+        }
+        else {
+            lines.push(`    <div>`);
+            lines.push(`      <h1>${page.title || page.name}</h1>`);
+            if (page.loaders.length > 0) {
+                lines.push(`      {/* Loader data available in loaderData */}`);
+            }
+            lines.push(`    </div>`);
+        }
+        lines.push(`  );`);
+        lines.push('}');
+        // Generate action handlers
+        if (page.actions.length > 0) {
+            lines.push('');
+            for (const action of page.actions) {
+                lines.push(this.generateActionHandler(action));
+            }
+        }
+        const routePath = this.routeToFilePath(page.route, 'tanstack-start');
+        return {
+            path: `app/routes/${routePath}.${ext}`,
+            content: lines.join('\n'),
+        };
+    }
+    generateTanStackLoader(loader) {
+        const fnName = this.toCamelCase(loader.name);
+        const lines = [];
+        lines.push(`const ${fnName} = createServerFn('GET', async () => {`);
+        lines.push(`  // TODO: Implement loader - ${loader.source}`);
+        lines.push(`  return { /* ${loader.name} data */ };`);
+        lines.push('});');
+        return lines.join('\n');
+    }
+    // ===========================================================================
+    // Next.js App Router Generation
+    // ===========================================================================
+    generateNextJSPage(page) {
+        const lines = [];
+        const ext = this.typescript ? 'tsx' : 'jsx';
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Page: ${page.name}`);
+            lines.push('');
+        }
+        // Client directive if needed
+        if (this.clientComponents || page.actions.length > 0) {
+            lines.push("'use client';");
+            lines.push('');
+        }
+        // Imports
+        if (page.meta || page.title) {
+            lines.push("import type { Metadata } from 'next';");
+        }
+        if (page.guard) {
+            lines.push("import { redirect } from 'next/navigation';");
+        }
+        lines.push('');
+        // Generate metadata export
+        if (page.title || page.meta) {
+            lines.push('export const metadata: Metadata = {');
+            if (page.title) {
+                lines.push(`  title: '${page.title}',`);
+            }
+            if (page.meta?.description) {
+                lines.push(`  description: '${page.meta.description}',`);
+            }
+            lines.push('};');
+            lines.push('');
+        }
+        // Generate params type for dynamic routes
+        const params = this.extractRouteParams(page.route);
+        const hasParams = params.length > 0;
+        if (hasParams && this.typescript) {
+            lines.push(`interface PageProps {`);
+            lines.push(`  params: { ${params.map((p) => `${p}: string`).join('; ')} };`);
+            lines.push(`}`);
+            lines.push('');
+        }
+        // Generate page component
+        const propsType = hasParams ? (this.typescript ? ': PageProps' : '') : '';
+        const isAsync = page.loaders.length > 0;
+        lines.push(`export default ${isAsync ? 'async ' : ''}function ${page.name}Page(${hasParams ? `{ params }${propsType}` : ''}) {`);
+        // Add guard logic
+        if (page.guard) {
+            lines.push(`  // Guard: ${page.guard}`);
+            if (page.guard === 'authenticated') {
+                lines.push(`  // TODO: Check authentication`);
+                lines.push(`  // if (!session) redirect('/login');`);
+            }
+            else if (page.guard === 'guest_only') {
+                lines.push(`  // TODO: Check if guest`);
+                lines.push(`  // if (session) redirect('/dashboard');`);
+            }
+            lines.push('');
+        }
+        // Add loader calls
+        if (page.loaders.length > 0) {
+            for (const loader of page.loaders) {
+                const varName = this.toCamelCase(loader.name);
+                lines.push(`  // Loader: ${loader.name}`);
+                lines.push(`  const ${varName} = await fetch${this.toPascalCase(loader.name)}();`);
+            }
+            lines.push('');
+        }
+        lines.push(`  return (`);
+        // Generate layout or simple content
+        if (page.layout) {
+            lines.push(this.generateLayoutJSX(page.layout, 4));
+        }
+        else if (page.component) {
+            lines.push(`    <${page.component} />`);
+        }
+        else {
+            lines.push(`    <div>`);
+            lines.push(`      <h1>${page.title || page.name}</h1>`);
+            lines.push(`    </div>`);
+        }
+        lines.push(`  );`);
+        lines.push('}');
+        // Generate loader functions
+        if (page.loaders.length > 0) {
+            lines.push('');
+            lines.push('// --- Data Fetching ---');
+            for (const loader of page.loaders) {
+                lines.push('');
+                lines.push(this.generateNextJSLoader(loader));
+            }
+        }
+        // Generate action handlers
+        if (page.actions.length > 0) {
+            lines.push('');
+            lines.push('// --- Actions ---');
+            for (const action of page.actions) {
+                lines.push('');
+                lines.push(this.generateActionHandler(action));
+            }
+        }
+        const routePath = this.routeToFilePath(page.route, 'nextjs');
+        return {
+            path: `app/${routePath}/page.${ext}`,
+            content: lines.join('\n'),
+        };
+    }
+    generateNextJSLoader(loader) {
+        const fnName = `fetch${this.toPascalCase(loader.name)}`;
+        const lines = [];
+        lines.push(`async function ${fnName}() {`);
+        lines.push(`  // TODO: Implement - ${loader.source}`);
+        lines.push(`  return { /* ${loader.name} data */ };`);
+        lines.push('}');
+        return lines.join('\n');
+    }
+    // ===========================================================================
+    // Shared Helpers
+    // ===========================================================================
+    generateLayoutJSX(layout, indent) {
+        const spaces = ' '.repeat(indent);
+        const lines = [];
+        const props = Object.entries(layout.props || {})
+            .map(([k, v]) => `${k}="${v}"`)
+            .join(' ');
+        const propsStr = props ? ` ${props}` : '';
+        if (layout.children && layout.children.length > 0) {
+            lines.push(`${spaces}<${layout.component}${propsStr}>`);
+            for (const child of layout.children) {
+                lines.push(this.generateLayoutJSX(child, indent + 2));
+            }
+            lines.push(`${spaces}</${layout.component}>`);
+        }
+        else {
+            lines.push(`${spaces}<${layout.component}${propsStr} />`);
+        }
+        return lines.join('\n');
+    }
+    generateActionHandler(action) {
+        const fnName = this.toCamelCase(action.name);
+        const lines = [];
+        lines.push(`function ${fnName}() {`);
+        lines.push(`  // TODO: Implement action - ${action.handler}`);
+        lines.push('}');
+        return lines.join('\n');
+    }
+    routeToFilePath(route, framework) {
+        // Convert route like "/projects/:id" to file path
+        let path = route.replace(/^\//, ''); // Remove leading slash
+        if (framework === 'tanstack-start') {
+            // TanStack: /projects/:id -> projects.$id
+            path = path.replace(/\//g, '.').replace(/:(\w+)/g, '$$$1');
+            if (path === '')
+                path = '_index';
+        }
+        else {
+            // Next.js: /projects/:id -> projects/[id]
+            path = path.replace(/:(\w+)/g, '[$1]');
+            if (path === '')
+                path = '(home)';
+        }
+        return path;
+    }
+    extractRouteParams(route) {
+        const matches = route.match(/:(\w+)/g) || [];
+        return matches.map((m) => m.slice(1));
+    }
+    toCamelCase(str) {
+        return str.charAt(0).toLowerCase() + str.slice(1);
+    }
+    toPascalCase(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+}
+// =============================================================================
+// Convenience Function
+// =============================================================================
+/**
+ * Generate page files from Kappa PageBlock nodes
+ */
+export function generatePages(pages, options = {}) {
+    const generator = new KappaPageGenerator(options);
+    return generator.generate(pages);
+}

package/dist/codedna/kappa-parser.d.ts

@@ -0,0 +1,261 @@
+import { CstParser, IToken, CstNode } from 'chevrotain';
+import { KappaSpec, ProjectBlock, AuthBlock, HashConfig, EntityBlock, EntityField, FieldType, FieldModifier, EntityRelationship, Capability, LifecycleHook, APIBlock, APIOperation, APIReturnType, CRUDShorthand, CRUDAction, EffectType, APIParameter, JourneyBlock, JourneyStep, PageBlock, ComponentBlock, FormBlock, FormField, DesignBlock } from './kappa-ast.js';
+declare class KappaParser extends CstParser {
+    constructor();
+    kappaSpec: import("chevrotain").ParserMethod<[], CstNode>;
+    projectBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    projectProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    stackValue: import("chevrotain").ParserMethod<[], CstNode>;
+    databaseValue: import("chevrotain").ParserMethod<[], CstNode>;
+    authTypeValue: import("chevrotain").ParserMethod<[], CstNode>;
+    uiValue: import("chevrotain").ParserMethod<[], CstNode>;
+    authBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    authProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    envCall: import("chevrotain").ParserMethod<[], CstNode>;
+    refreshValue: import("chevrotain").ParserMethod<[], CstNode>;
+    hashConfig: import("chevrotain").ParserMethod<[], CstNode>;
+    hashParams: import("chevrotain").ParserMethod<[], CstNode>;
+    entityBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    fieldName: import("chevrotain").ParserMethod<[], CstNode>;
+    entityField: import("chevrotain").ParserMethod<[], CstNode>;
+    fieldType: import("chevrotain").ParserMethod<[], CstNode>;
+    innerFieldType: import("chevrotain").ParserMethod<[], CstNode>;
+    rangeConstraint: import("chevrotain").ParserMethod<[], CstNode>;
+    fieldModifier: import("chevrotain").ParserMethod<[], CstNode>;
+    defaultValue: import("chevrotain").ParserMethod<[], CstNode>;
+    entityRelationship: import("chevrotain").ParserMethod<[], CstNode>;
+    entityCapability: import("chevrotain").ParserMethod<[], CstNode>;
+    capabilityList: import("chevrotain").ParserMethod<[], CstNode>;
+    singleCapability: import("chevrotain").ParserMethod<[], CstNode>;
+    capabilityAction: import("chevrotain").ParserMethod<[], CstNode>;
+    capabilityCondition: import("chevrotain").ParserMethod<[], CstNode>;
+    entityLifecycleHook: import("chevrotain").ParserMethod<[], CstNode>;
+    hookAction: import("chevrotain").ParserMethod<[], CstNode>;
+    hookActionParam: import("chevrotain").ParserMethod<[], CstNode>;
+    arrayLiteral: import("chevrotain").ParserMethod<[], CstNode>;
+    apiBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    crudShorthand: import("chevrotain").ParserMethod<[], CstNode>;
+    crudActionList: import("chevrotain").ParserMethod<[], CstNode>;
+    crudAction: import("chevrotain").ParserMethod<[], CstNode>;
+    apiEndpoint: import("chevrotain").ParserMethod<[], CstNode>;
+    parameterList: import("chevrotain").ParserMethod<[], CstNode>;
+    parameter: import("chevrotain").ParserMethod<[], CstNode>;
+    parameterType: import("chevrotain").ParserMethod<[], CstNode>;
+    effectAnnotation: import("chevrotain").ParserMethod<[], CstNode>;
+    effectList: import("chevrotain").ParserMethod<[], CstNode>;
+    effect: import("chevrotain").ParserMethod<[], CstNode>;
+    returnType: import("chevrotain").ParserMethod<[], CstNode>;
+    returnTypeInner: import("chevrotain").ParserMethod<[], CstNode>;
+    objectTypeFields: import("chevrotain").ParserMethod<[], CstNode>;
+    objectTypeField: import("chevrotain").ParserMethod<[], CstNode>;
+    journeyBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    journeyProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    journeyStep: import("chevrotain").ParserMethod<[], CstNode>;
+    journeyStepProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    pageBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    pageProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    metaProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    componentBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    componentProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    propDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+    stateDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+    handlerDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+    formBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    formProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    formFieldDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+    formFieldType: import("chevrotain").ParserMethod<[], CstNode>;
+    formFieldProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    submitProperty: import("chevrotain").ParserMethod<[], CstNode>;
+    validationRule: import("chevrotain").ParserMethod<[], CstNode>;
+    designBlock: import("chevrotain").ParserMethod<[], CstNode>;
+    designSection: import("chevrotain").ParserMethod<[], CstNode>;
+    colorDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+    typographyDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+    spacingDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+    animationDefinition: import("chevrotain").ParserMethod<[], CstNode>;
+}
+declare const parser: KappaParser;
+declare const BaseCstVisitor: new (...args: any[]) => import("chevrotain").ICstVisitor<any, any>;
+declare class KappaAstBuilder extends BaseCstVisitor {
+    constructor();
+    private getLocation;
+    private findFirstToken;
+    private findLastToken;
+    kappaSpec(ctx: Record<string, unknown>): KappaSpec;
+    projectBlock(ctx: Record<string, unknown>): ProjectBlock;
+    projectProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: string;
+    };
+    stackValue(ctx: Record<string, IToken[]>): string;
+    databaseValue(ctx: Record<string, IToken[]>): string;
+    authTypeValue(ctx: Record<string, IToken[]>): string;
+    uiValue(ctx: Record<string, IToken[]>): string;
+    authBlock(ctx: Record<string, unknown>): AuthBlock;
+    authProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: unknown;
+    };
+    envCall(ctx: Record<string, IToken[]>): string;
+    refreshValue(ctx: Record<string, IToken[]>): string;
+    hashConfig(ctx: Record<string, unknown>): HashConfig;
+    hashParams(ctx: Record<string, unknown>): Record<string, unknown>;
+    entityBlock(ctx: Record<string, unknown>): EntityBlock;
+    entityField(ctx: Record<string, unknown>): EntityField;
+    fieldName(ctx: Record<string, unknown>): string;
+    fieldType(ctx: Record<string, unknown>): FieldType;
+    innerFieldType(ctx: Record<string, unknown>): FieldType;
+    rangeConstraint(ctx: Record<string, IToken[]>): {
+        min?: number;
+        max?: number;
+    };
+    fieldModifier(ctx: Record<string, IToken[]>): FieldModifier;
+    defaultValue(ctx: Record<string, IToken[]>): string;
+    entityRelationship(ctx: Record<string, unknown>): EntityRelationship;
+    entityCapability(ctx: Record<string, unknown>): Capability;
+    capabilityList(ctx: Record<string, unknown>): unknown[];
+    singleCapability(ctx: Record<string, unknown>): {
+        action: string;
+        entity: string;
+        condition?: {
+            type: 'where' | 'unless';
+            value: string;
+        };
+    };
+    capabilityAction(ctx: Record<string, IToken[]>): string;
+    capabilityCondition(ctx: Record<string, IToken[]>): {
+        type: 'where' | 'unless';
+        value: string;
+    };
+    entityLifecycleHook(ctx: Record<string, unknown>): LifecycleHook;
+    hookAction(ctx: Record<string, unknown>): {
+        name: string;
+        params: Record<string, unknown>;
+    };
+    hookActionParam(ctx: Record<string, unknown>): {
+        name: string;
+        value: unknown;
+    };
+    arrayLiteral(ctx: Record<string, IToken[]>): string[];
+    apiBlock(ctx: Record<string, unknown>): APIBlock;
+    crudShorthand(ctx: Record<string, unknown>): CRUDShorthand;
+    crudActionList(ctx: Record<string, unknown>): CRUDAction[];
+    crudAction(ctx: Record<string, IToken[]>): CRUDAction;
+    apiEndpoint(ctx: Record<string, unknown>): APIOperation;
+    parameterList(ctx: Record<string, unknown>): APIParameter[];
+    parameter(ctx: Record<string, unknown>): APIParameter;
+    parameterType(ctx: Record<string, IToken[]>): string;
+    effectAnnotation(ctx: Record<string, unknown>): EffectType[];
+    effectList(ctx: Record<string, unknown>): EffectType[];
+    effect(ctx: Record<string, IToken[]>): EffectType;
+    returnType(ctx: Record<string, unknown>): APIReturnType;
+    returnTypeInner(ctx: Record<string, unknown> | CstNode[]): {
+        type: string;
+        joined?: {
+            field: string;
+            entity: string;
+        }[];
+    };
+    objectTypeFields(ctx: Record<string, unknown>): {
+        name: string;
+        type: string;
+    }[];
+    objectTypeField(ctx: Record<string, unknown>): {
+        name: string;
+        type: string;
+    };
+    journeyBlock(ctx: Record<string, unknown>): JourneyBlock;
+    journeyProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: unknown;
+    };
+    journeyStep(ctx: Record<string, unknown>): JourneyStep;
+    journeyStepProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: string;
+    };
+    pageBlock(ctx: Record<string, unknown>): PageBlock;
+    pageProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: unknown;
+    };
+    metaProperty(ctx: Record<string, IToken[]>): {
+        name: string;
+        value: string;
+    };
+    componentBlock(ctx: Record<string, unknown>): ComponentBlock;
+    componentProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: unknown[];
+    };
+    propDefinition(ctx: Record<string, unknown>): {
+        name: string;
+        type: string;
+        optional: boolean;
+    };
+    stateDefinition(ctx: Record<string, unknown>): {
+        name: string;
+        type: string;
+        defaultValue?: string;
+    };
+    handlerDefinition(ctx: Record<string, unknown>): {
+        name: string;
+        effects: EffectType[];
+    };
+    formBlock(ctx: Record<string, unknown>): FormBlock;
+    formProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: unknown;
+    };
+    formFieldDefinition(ctx: Record<string, unknown>): FormField;
+    formFieldType(ctx: Record<string, IToken[]>): string;
+    formFieldProperty(ctx: Record<string, unknown>): {
+        type: string;
+        value: unknown;
+    };
+    submitProperty(ctx: Record<string, IToken[]>): {
+        type: string;
+        value: string;
+    };
+    validationRule(ctx: Record<string, IToken[]>): {
+        name: string;
+        value: string;
+    };
+    designBlock(ctx: Record<string, unknown>): DesignBlock;
+    designSection(ctx: Record<string, unknown>): {
+        type: string;
+        value: unknown;
+    };
+    colorDefinition(ctx: Record<string, unknown>): {
+        name: string;
+        value: string;
+    };
+    typographyDefinition(ctx: Record<string, IToken[]>): {
+        name: string;
+        value: string;
+    };
+    spacingDefinition(ctx: Record<string, IToken[]>): {
+        name: string;
+        value: string;
+    };
+    animationDefinition(ctx: Record<string, IToken[]>): {
+        name: string;
+        value: string;
+    };
+}
+export interface ParseResult {
+    success: boolean;
+    ast?: KappaSpec;
+    errors: Array<{
+        message: string;
+        line?: number;
+        column?: number;
+    }>;
+}
+export declare function parse(source: string): ParseResult;
+/**
+ * Convenience function that parses source and returns the AST directly.
+ * Returns null if parsing fails.
+ */
+export declare function parseToAST(source: string): KappaSpec | null;
+export { parser, KappaParser, KappaAstBuilder };