@claudetools/tools 0.8.11 → 0.9.0

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

@@ -0,0 +1,552 @@
+/**
+ * Source location for provenance tracking.
+ * Every AST node includes this to enable tracing generated code back to spec.
+ */
+export interface SourceLocation {
+    /** 1-based line number */
+    startLine: number;
+    /** 1-based column number */
+    startColumn: number;
+    /** 1-based line number */
+    endLine: number;
+    /** 1-based column number */
+    endColumn: number;
+    /** Character offset from start of file */
+    startOffset: number;
+    /** Character offset from start of file */
+    endOffset: number;
+}
+/**
+ * Base interface for all AST nodes
+ */
+export interface BaseNode {
+    /** Source location for provenance */
+    loc: SourceLocation;
+}
+/**
+ * Root AST node representing a complete Kappa specification
+ */
+export interface KappaSpec extends BaseNode {
+    kind: 'KappaSpec';
+    /** Project configuration (optional - can be inferred) */
+    project?: ProjectBlock;
+    /** Authentication configuration */
+    auth?: AuthBlock;
+    /** Entity definitions */
+    entities: EntityBlock[];
+    /** API definitions */
+    apis: APIBlock[];
+    /** User journey definitions */
+    journeys: JourneyBlock[];
+    /** Page/route definitions */
+    pages: PageBlock[];
+    /** Component definitions */
+    components: ComponentBlock[];
+    /** Form definitions */
+    forms: FormBlock[];
+    /** Design system configuration */
+    design?: DesignBlock;
+}
+export type StackType = 'tanstack-start' | 'next' | 'remix' | 'sveltekit' | 'astro' | 'express' | 'hono' | 'elysia';
+export type DatabaseType = 'postgres' | 'mysql' | 'sqlite' | 'turso' | 'mongodb';
+export type AuthType = 'jwt' | 'session' | 'oauth';
+export type UILibrary = 'shadcn' | 'mui' | 'chakra' | 'tailwind-only';
+/**
+ * Project configuration block
+ */
+export interface ProjectBlock extends BaseNode {
+    kind: 'ProjectBlock';
+    /** Project name */
+    name: string;
+    /** Semantic version */
+    version?: string;
+    /** Target stack/framework */
+    stack: StackType;
+    /** Database type */
+    database?: DatabaseType;
+    /** Authentication strategy */
+    auth?: AuthType;
+    /** UI component library */
+    ui?: UILibrary;
+}
+export type HashAlgorithm = 'argon2id' | 'bcrypt';
+export interface HashConfig extends BaseNode {
+    kind: 'HashConfig';
+    algorithm: HashAlgorithm;
+    /** Memory cost for argon2id (e.g., "64mb") */
+    memory?: string;
+    /** Iterations for argon2id */
+    iterations?: number;
+    /** Parallelism for argon2id */
+    parallelism?: number;
+    /** Rounds for bcrypt */
+    rounds?: number;
+}
+export type RefreshStrategy = 'sliding' | 'fixed' | 'none';
+/**
+ * JWT authentication configuration
+ */
+export interface JWTConfig extends BaseNode {
+    kind: 'JWTConfig';
+    /** Environment variable for secret */
+    secret: string;
+    /** Token issuer */
+    issuer?: string;
+    /** Token audience */
+    audience?: string;
+    /** Token expiration (e.g., "7d", "1h") */
+    expires: string;
+    /** Refresh token strategy */
+    refresh?: RefreshStrategy;
+    /** Password hashing configuration */
+    hash: HashConfig;
+}
+/**
+ * Session-based authentication configuration
+ */
+export interface SessionConfig extends BaseNode {
+    kind: 'SessionConfig';
+    /** Session duration */
+    duration: string;
+    /** Cookie configuration */
+    cookie?: {
+        name?: string;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+    };
+    /** Password hashing configuration */
+    hash: HashConfig;
+}
+/**
+ * Authentication block
+ */
+export interface AuthBlock extends BaseNode {
+    kind: 'AuthBlock';
+    type: 'jwt' | 'session';
+    jwt?: JWTConfig;
+    session?: SessionConfig;
+}
+export type PrimitiveType = 'string' | 'int' | 'float' | 'bool' | 'email' | 'url' | 'uuid' | 'phone' | 'slug' | 'markdown' | 'json' | 'timestamp' | 'date' | 'time' | 'duration';
+export interface PrimitiveFieldType {
+    kind: 'primitive';
+    type: PrimitiveType;
+    /** Range constraint for strings/numbers (e.g., 2..100) */
+    range?: {
+        min?: number;
+        max?: number;
+    };
+}
+export interface EnumFieldType {
+    kind: 'enum';
+    values: string[];
+}
+export interface ReferenceFieldType {
+    kind: 'reference';
+    entity: string;
+    optional: boolean;
+}
+export interface ArrayFieldType {
+    kind: 'array';
+    itemType: FieldType;
+}
+export type FieldType = PrimitiveFieldType | EnumFieldType | ReferenceFieldType | ArrayFieldType;
+export type FieldModifier = 'primary' | 'unique' | 'auto' | 'immutable' | 'internal' | 'hashed' | 'optional';
+export interface EntityField extends BaseNode {
+    kind: 'EntityField';
+    name: string;
+    type: FieldType;
+    modifiers: FieldModifier[];
+    /** Default value expression */
+    defaultValue?: string;
+    /** Update trigger (e.g., "on_update" for updated_at) */
+    updateTrigger?: boolean;
+}
+export type RelationType = 'has_many' | 'has_one' | 'belongs_to' | 'many_to_many';
+export type CascadeAction = 'delete' | 'nullify' | 'restrict';
+export interface EntityRelationship extends BaseNode {
+    kind: 'EntityRelationship';
+    type: RelationType;
+    entity: string;
+    /** Alias for the relationship (e.g., "as owner") */
+    as?: string;
+    /** Through entity for many-to-many */
+    through?: string;
+    /** Cascade behavior on delete */
+    cascade?: CascadeAction;
+}
+export type CapabilityAction = 'create' | 'read' | 'update' | 'delete' | 'invite';
+export interface Capability extends BaseNode {
+    kind: 'Capability';
+    allowed: boolean;
+    action: CapabilityAction;
+    /** Target entity (if different from self) */
+    target?: string;
+    /** Condition for the capability (e.g., "where: member_of") */
+    condition?: string;
+    /** Additional target context (e.g., "to: Team") */
+    targetContext?: string;
+    /** Unless condition for cannot (e.g., "unless: no_owned_projects") */
+    unless?: string;
+}
+export type LifecycleEvent = 'on_create' | 'on_update' | 'on_delete';
+export interface LifecycleHook extends BaseNode {
+    kind: 'LifecycleHook';
+    event: LifecycleEvent;
+    /** Field that triggers update hook (optional, for on_update) */
+    field?: string;
+    /** Actions to perform */
+    actions: LifecycleAction[];
+}
+export type LifecycleActionType = 'send_email' | 'log_audit' | 'enqueue' | 'anonymize' | 'transfer_ownership' | 'require_reverification';
+export interface LifecycleAction extends BaseNode {
+    kind: 'LifecycleAction';
+    type: LifecycleActionType;
+    /** Parameters for the action */
+    params: Record<string, string | string[]>;
+}
+export interface EntityIndex extends BaseNode {
+    kind: 'EntityIndex';
+    fields: string[];
+    unique?: boolean;
+}
+/**
+ * Enhanced entity block with capabilities and lifecycle
+ */
+export interface EntityBlock extends BaseNode {
+    kind: 'EntityBlock';
+    name: string;
+    fields: EntityField[];
+    relationships: EntityRelationship[];
+    capabilities: Capability[];
+    lifecycleHooks: LifecycleHook[];
+    indexes: EntityIndex[];
+}
+export type EffectType = 'DB' | 'Auth' | 'Email' | 'Audit' | 'Queue' | 'Cache' | 'External';
+export interface APIParameter extends BaseNode {
+    kind: 'APIParameter';
+    name: string;
+    type: FieldType;
+    optional: boolean;
+}
+export interface APIReturnType extends BaseNode {
+    kind: 'APIReturnType';
+    /** Entity name or inline type */
+    type: string;
+    /** Is it an array? */
+    isArray: boolean;
+    /** Joined data (e.g., "Member & { user: User }") */
+    joined?: {
+        field: string;
+        entity: string;
+    }[];
+}
+export interface APIOperation extends BaseNode {
+    kind: 'APIOperation';
+    name: string;
+    parameters: APIParameter[];
+    effects: EffectType[];
+    returnType: APIReturnType;
+    /** Error types that can be thrown */
+    throws?: string[];
+    /** Rate limit (e.g., "10/minute") */
+    rateLimit?: string;
+    /** Permission check (e.g., "owner_of") */
+    check?: string;
+    /** Audit configuration */
+    audit?: 'always' | 'on_error' | 'never';
+    /** Cache duration */
+    cache?: string;
+    /** Deprecation message */
+    deprecated?: string;
+}
+export type CRUDAction = 'create' | 'read' | 'update' | 'delete' | 'list';
+export interface CRUDShorthand extends BaseNode {
+    kind: 'CRUDShorthand';
+    entity: string;
+    actions: {
+        action: CRUDAction;
+        effects: EffectType[];
+        check?: string;
+        filter?: string;
+        scope?: string;
+    }[];
+}
+/**
+ * API definition block
+ */
+export interface APIBlock extends BaseNode {
+    kind: 'APIBlock';
+    name: string;
+    operations: APIOperation[];
+    crud: CRUDShorthand[];
+}
+export interface JourneyStep extends BaseNode {
+    kind: 'JourneyStep';
+    name: string;
+    /** Page to render */
+    page?: string;
+    /** Action to perform */
+    action?: string;
+    /** Next step name */
+    next?: string;
+    /** Wait for condition */
+    waitFor?: string;
+    /** Timeout with fallback */
+    timeout?: {
+        duration: string;
+        fallback: string;
+    };
+    /** Skip condition */
+    skipIf?: string;
+    /** Can be skipped by user */
+    skippable?: boolean;
+    /** Error handling */
+    onError?: {
+        action: string;
+        behavior: 'stay' | 'retry' | 'next';
+    };
+    /** Is this the final step? */
+    complete?: boolean;
+}
+export interface JourneyRecovery extends BaseNode {
+    kind: 'JourneyRecovery';
+    /** Step that triggers recovery */
+    step: string;
+    /** Recovery action (e.g., "send_reminder(after: 1h, max: 3)") */
+    action: string;
+}
+/**
+ * User journey definition
+ */
+export interface JourneyBlock extends BaseNode {
+    kind: 'JourneyBlock';
+    name: string;
+    /** Actor type (e.g., "new_user") */
+    actor: string;
+    steps: JourneyStep[];
+    /** Events to track */
+    track?: string[];
+    /** Recovery handlers */
+    recovery: JourneyRecovery[];
+}
+export interface PageLoader extends BaseNode {
+    kind: 'PageLoader';
+    name: string;
+    /** API call or expression */
+    source: string;
+}
+export interface PageAction extends BaseNode {
+    kind: 'PageAction';
+    name: string;
+    /** Action trigger (e.g., "modal(CreateProjectForm) -> api.create_project -> refresh") */
+    handler: string;
+}
+export interface PageLayout extends BaseNode {
+    kind: 'PageLayout';
+    component: string;
+    props: Record<string, string>;
+    children?: PageLayout[];
+}
+/**
+ * Page/route definition
+ */
+export interface PageBlock extends BaseNode {
+    kind: 'PageBlock';
+    name: string;
+    /** Route path (e.g., "/dashboard", "/projects/:id") */
+    route: string;
+    /** Route guard (e.g., "authenticated", "guest_only") */
+    guard?: string;
+    /** Component to render (for simple pages) */
+    component?: string;
+    /** Data loaders */
+    loaders: PageLoader[];
+    /** Layout composition */
+    layout?: PageLayout;
+    /** Page actions */
+    actions: PageAction[];
+    /** Page title (can include interpolation) */
+    title?: string;
+    /** Meta tags */
+    meta?: Record<string, string>;
+}
+export interface ComponentProp extends BaseNode {
+    kind: 'ComponentProp';
+    name: string;
+    type: string;
+    optional: boolean;
+}
+export interface ComponentStructure extends BaseNode {
+    kind: 'ComponentStructure';
+    type: string;
+    props: Record<string, string>;
+    children?: ComponentStructure[];
+}
+export interface ComponentVariant extends BaseNode {
+    kind: 'ComponentVariant';
+    name: string;
+    /** Modifications (e.g., "hide(body.meta, footer.avatar_group)") */
+    modifications: string[];
+}
+export interface CompoundPart extends BaseNode {
+    kind: 'CompoundPart';
+    name: string;
+    element: string;
+    props?: string[];
+}
+/**
+ * Component definition
+ */
+export interface ComponentBlock extends BaseNode {
+    kind: 'ComponentBlock';
+    name: string;
+    props: ComponentProp[];
+    structure?: ComponentStructure;
+    variants: ComponentVariant[];
+    /** Compound component parts */
+    compound?: CompoundPart[];
+    /** Default composition for compound components */
+    defaultComposition?: ComponentStructure;
+}
+export type FormFieldType = 'text' | 'textarea' | 'email' | 'password' | 'number' | 'select' | 'multiselect' | 'checkbox' | 'radio' | 'date' | 'time' | 'datetime' | 'file';
+export interface FormFieldOption extends BaseNode {
+    kind: 'FormFieldOption';
+    value: string;
+    label: string;
+    icon?: string;
+}
+export interface FormField extends BaseNode {
+    kind: 'FormField';
+    name: string;
+    type: FormFieldType;
+    label: string;
+    placeholder?: string;
+    /** Validation expression */
+    validate?: string;
+    required: boolean;
+    /** Default value */
+    defaultValue?: string;
+    /** Static options */
+    options?: FormFieldOption[];
+    /** Dynamic options source */
+    optionsFrom?: string;
+    /** Additional config (e.g., rows for textarea) */
+    config?: Record<string, string | number | boolean>;
+}
+export interface FormSubmit extends BaseNode {
+    kind: 'FormSubmit';
+    /** API action to call */
+    action: string;
+    /** Button text */
+    button: string;
+    /** Loading text */
+    loading?: string;
+    /** Success handler */
+    onSuccess: string;
+    /** Error handler */
+    onError: string;
+}
+export interface FormLayoutRow extends BaseNode {
+    kind: 'FormLayoutRow';
+    fields: string[];
+    columns?: number;
+}
+/**
+ * Form definition
+ */
+export interface FormBlock extends BaseNode {
+    kind: 'FormBlock';
+    name: string;
+    fields: FormField[];
+    submit: FormSubmit;
+    layout: FormLayoutRow[];
+}
+export interface ColorValue {
+    /** Hex color or reference (e.g., "#3B82F6" or "darken(primary, 10%)") */
+    value: string;
+    /** Is this a function call? */
+    isFunction: boolean;
+    /** Function name if isFunction */
+    functionName?: 'darken' | 'lighten' | 'alpha';
+    /** Function arguments if isFunction */
+    functionArgs?: (string | number)[];
+}
+export interface ColorPalette extends BaseNode {
+    kind: 'ColorPalette';
+    colors: Record<string, ColorValue>;
+}
+export interface TypographyConfig extends BaseNode {
+    kind: 'TypographyConfig';
+    fontFamily?: string;
+    fontMono?: string;
+    scale?: Record<string, string>;
+    weight?: Record<string, number>;
+}
+export interface SpacingConfig extends BaseNode {
+    kind: 'SpacingConfig';
+    unit?: string;
+    scale?: number[];
+}
+export interface BorderConfig extends BaseNode {
+    kind: 'BorderConfig';
+    radius?: Record<string, string>;
+    width?: string;
+    color?: string;
+}
+export interface ShadowConfig extends BaseNode {
+    kind: 'ShadowConfig';
+    shadows: Record<string, string>;
+}
+export interface MotionConfig extends BaseNode {
+    kind: 'MotionConfig';
+    duration?: Record<string, string>;
+    easing?: Record<string, string>;
+}
+/**
+ * Design system configuration
+ */
+export interface DesignBlock extends BaseNode {
+    kind: 'DesignBlock';
+    colors: ColorPalette;
+    /** Dark mode color overrides */
+    darkColors?: ColorPalette;
+    typography?: TypographyConfig;
+    spacing?: SpacingConfig;
+    borders?: BorderConfig;
+    shadows?: ShadowConfig;
+    motion?: MotionConfig;
+}
+/**
+ * All possible AST node types
+ */
+export type KappaNode = KappaSpec | ProjectBlock | AuthBlock | EntityBlock | APIBlock | JourneyBlock | PageBlock | ComponentBlock | FormBlock | DesignBlock | EntityField | EntityRelationship | Capability | LifecycleHook | LifecycleAction | EntityIndex | APIOperation | APIParameter | APIReturnType | CRUDShorthand | JourneyStep | JourneyRecovery | PageLoader | PageAction | PageLayout | ComponentProp | ComponentStructure | ComponentVariant | CompoundPart | FormField | FormFieldOption | FormSubmit | FormLayoutRow | ColorPalette | TypographyConfig | SpacingConfig | BorderConfig | ShadowConfig | MotionConfig | HashConfig | JWTConfig | SessionConfig;
+/**
+ * Extract node type from kind string
+ */
+export type NodeOfKind<K extends KappaNode['kind']> = Extract<KappaNode, {
+    kind: K;
+}>;
+/**
+ * Visitor function type for AST traversal
+ */
+export type NodeVisitor<T = void> = {
+    [K in KappaNode['kind']]?: (node: NodeOfKind<K>) => T;
+};
+export interface ParseError {
+    message: string;
+    location: SourceLocation;
+    /** Error code for programmatic handling */
+    code?: string;
+}
+export interface ParseResult {
+    success: boolean;
+    ast?: KappaSpec;
+    errors: ParseError[];
+    /** Warnings that don't prevent parsing */
+    warnings: ParseError[];
+}
+/**
+ * Convert EntityBlock to legacy EntitySpec format for existing generators
+ */
+export declare function toEntitySpec(entity: EntityBlock): import('./parser.js').EntitySpec;

package/dist/codedna/kappa-ast.js

@@ -0,0 +1,141 @@
+// =============================================================================
+// Kappa v2.5 Abstract Syntax Tree Types
+// =============================================================================
+//
+// Complete type definitions for Kappa specification language AST.
+// All nodes include source location tracking for provenance.
+//
+// Reference: docs/research/2026-01-02-kappa-v2.5-specification.md
+//
+// =============================================================================
+// Backwards Compatibility with EntitySpec
+// =============================================================================
+/**
+ * Convert EntityBlock to legacy EntitySpec format for existing generators
+ */
+export function toEntitySpec(entity) {
+    return {
+        name: entity.name,
+        fields: entity.fields.map(field => ({
+            name: field.name,
+            type: fieldTypeToLegacy(field.type),
+            constraints: modifiersToConstraints(field.modifiers, field.type),
+        })),
+        hooks: lifecycleToLegacy(entity.lifecycleHooks),
+        permissions: capabilitiesToLegacy(entity.capabilities),
+    };
+}
+function fieldTypeToLegacy(type) {
+    switch (type.kind) {
+        case 'primitive':
+            const primitiveMap = {
+                string: 'string',
+                int: 'integer',
+                float: 'decimal',
+                bool: 'boolean',
+                timestamp: 'datetime',
+                date: 'datetime',
+                time: 'datetime',
+            };
+            return {
+                kind: 'primitive',
+                value: (primitiveMap[type.type] || type.type),
+            };
+        case 'enum':
+            return { kind: 'enum', values: type.values };
+        case 'reference':
+            return { kind: 'reference', entity: type.entity };
+        case 'array':
+            if (type.itemType.kind === 'primitive') {
+                const itemMap = {
+                    string: 'string',
+                    int: 'integer',
+                    float: 'decimal',
+                    bool: 'boolean',
+                };
+                return {
+                    kind: 'array',
+                    itemType: (itemMap[type.itemType.type] || 'string'),
+                };
+            }
+            return { kind: 'array', itemType: 'string' };
+        default:
+            return { kind: 'primitive', value: 'string' };
+    }
+}
+function modifiersToConstraints(modifiers, type) {
+    const constraints = [];
+    for (const mod of modifiers) {
+        switch (mod) {
+            case 'unique':
+                constraints.push({ kind: 'unique' });
+                break;
+            case 'hashed':
+                constraints.push({ kind: 'hashed' });
+                break;
+            case 'optional':
+                constraints.push({ kind: 'nullable' });
+                break;
+            case 'immutable':
+                constraints.push({ kind: 'immutable' });
+                break;
+            case 'primary':
+            case 'auto':
+            case 'internal':
+                // These don't map to existing constraints
+                break;
+        }
+    }
+    // Add required if not optional
+    if (!modifiers.includes('optional')) {
+        constraints.push({ kind: 'required' });
+    }
+    // Add type-based constraints
+    if (type.kind === 'primitive') {
+        if (type.type === 'email') {
+            constraints.push({ kind: 'email' });
+        }
+        if (type.type === 'url') {
+            constraints.push({ kind: 'url' });
+        }
+        if (type.range) {
+            if (type.range.min !== undefined) {
+                constraints.push({ kind: 'min', value: type.range.min });
+            }
+            if (type.range.max !== undefined) {
+                constraints.push({ kind: 'max', value: type.range.max });
+            }
+        }
+    }
+    return constraints;
+}
+function lifecycleToLegacy(hooks) {
+    if (hooks.length === 0)
+        return undefined;
+    const result = {};
+    for (const hook of hooks) {
+        const actions = hook.actions.map(a => `${a.type}(${JSON.stringify(a.params)})`);
+        switch (hook.event) {
+            case 'on_create':
+                result.afterCreate = actions;
+                break;
+            case 'on_update':
+                result.afterUpdate = actions;
+                break;
+            case 'on_delete':
+                result.beforeDelete = actions;
+                break;
+        }
+    }
+    return result;
+}
+function capabilitiesToLegacy(capabilities) {
+    if (capabilities.length === 0)
+        return undefined;
+    return capabilities
+        .filter(c => c.allowed && ['create', 'read', 'update', 'delete'].includes(c.action))
+        .map(c => ({
+        action: c.action,
+        condition: c.condition,
+    }));
+}

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};