@constela/ai 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Constela Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,357 @@
+declare const AI_PROVIDERS: readonly ["anthropic", "openai"];
+type AiProviderType = (typeof AI_PROVIDERS)[number];
+declare const AI_OUTPUT_TYPES: readonly ["component", "view", "suggestion"];
+type AiOutputType = (typeof AI_OUTPUT_TYPES)[number];
+interface GenerationContext {
+    existingComponents?: string[];
+    theme?: Record<string, unknown>;
+    schema?: Record<string, unknown>;
+}
+interface SecurityOptions$1 {
+    allowedTags?: string[];
+    allowedActions?: string[];
+    allowedUrlPatterns?: string[];
+    maxNestingDepth?: number;
+}
+interface GenerateOptions {
+    prompt: string;
+    output: AiOutputType;
+    context?: GenerationContext;
+    security?: SecurityOptions$1;
+}
+interface ProviderGenerateOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    systemPrompt?: string;
+}
+interface ProviderResponse {
+    content: string;
+    model: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+interface AiProvider {
+    readonly name: AiProviderType;
+    generate(prompt: string, options?: ProviderGenerateOptions): Promise<ProviderResponse>;
+    isConfigured(): boolean;
+}
+
+type AiErrorCode = 'PROVIDER_NOT_CONFIGURED' | 'PROVIDER_NOT_FOUND' | 'API_ERROR' | 'VALIDATION_ERROR' | 'SECURITY_VIOLATION' | 'RATE_LIMIT_EXCEEDED';
+declare class AiError extends Error {
+    readonly code: AiErrorCode;
+    constructor(message: string, code: AiErrorCode);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: AiErrorCode;
+    };
+}
+declare class ValidationError$1 extends AiError {
+    readonly violations: string[];
+    constructor(message: string, violations: string[]);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: AiErrorCode;
+        violations: string[];
+    };
+}
+declare class SecurityError extends AiError {
+    readonly violation: string;
+    constructor(message: string, violation: string);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: AiErrorCode;
+        violation: string;
+    };
+}
+
+/**
+ * Security whitelist definitions for DSL validation
+ *
+ * Defines forbidden tags and actions that should never appear in AI-generated DSL.
+ */
+declare const FORBIDDEN_TAGS: readonly ["script", "iframe", "object", "embed", "form"];
+declare const FORBIDDEN_ACTIONS: readonly ["import", "call", "dom"];
+declare const RESTRICTED_ACTIONS: readonly ["fetch"];
+type ForbiddenTag = (typeof FORBIDDEN_TAGS)[number];
+type ForbiddenAction = (typeof FORBIDDEN_ACTIONS)[number];
+type RestrictedAction = (typeof RESTRICTED_ACTIONS)[number];
+/**
+ * Type guard to check if a tag is forbidden.
+ * Case-sensitive: only lowercase tags are forbidden.
+ */
+declare function isForbiddenTag(tag: unknown): tag is ForbiddenTag;
+/**
+ * Type guard to check if an action is forbidden.
+ * Case-sensitive: only lowercase actions are forbidden.
+ */
+declare function isForbiddenAction(action: unknown): action is ForbiddenAction;
+/**
+ * Type guard to check if an action is restricted (requires explicit whitelist).
+ * Case-sensitive: only lowercase actions are restricted.
+ */
+declare function isRestrictedAction(action: unknown): action is RestrictedAction;
+
+/**
+ * URL validation utilities for security enforcement
+ *
+ * Validates URLs to prevent XSS and other injection attacks.
+ */
+declare const FORBIDDEN_URL_SCHEMES: readonly ["javascript:", "data:", "vbscript:"];
+type ForbiddenUrlScheme = (typeof FORBIDDEN_URL_SCHEMES)[number];
+interface UrlValidationOptions {
+    allowedDomains?: string[];
+    allowRelative?: boolean;
+}
+interface UrlValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Check if a URL uses a forbidden scheme.
+ * Case-insensitive for scheme matching.
+ */
+declare function isForbiddenScheme(url: string): boolean;
+/**
+ * Validate a URL against security rules.
+ */
+declare function validateUrl(url: string, options?: UrlValidationOptions): UrlValidationResult;
+
+/**
+ * DSL Validator
+ *
+ * Validates AI-generated DSL against security rules to prevent XSS,
+ * script injection, and other malicious content.
+ */
+/**
+ * Security options for validation context
+ */
+interface SecurityOptions {
+    allowedTags?: string[];
+    allowedActions?: string[];
+    allowedUrlPatterns?: string[];
+    maxNestingDepth?: number;
+}
+/**
+ * Validation context for DSL validation
+ */
+interface ValidationContext {
+    security?: SecurityOptions;
+    path?: string;
+}
+/**
+ * Validation error with optional path and code
+ */
+interface ValidationError {
+    message: string;
+    path?: string;
+    code?: string;
+}
+/**
+ * Result of DSL validation
+ */
+interface DslValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validate a complete DSL structure
+ */
+declare function validateDsl(dsl: unknown, context?: ValidationContext): DslValidationResult;
+/**
+ * Validate a single DSL node
+ */
+declare function validateNode(node: unknown, context?: ValidationContext): ValidationError[];
+/**
+ * Validate an array of actions
+ */
+declare function validateActions(actions: unknown, context?: ValidationContext): ValidationError[];
+
+declare abstract class BaseProvider implements AiProvider {
+    abstract readonly name: AiProviderType;
+    abstract generate(prompt: string, options?: ProviderGenerateOptions): Promise<ProviderResponse>;
+    abstract isConfigured(): boolean;
+    protected validatePrompt(prompt: string): void;
+    protected getEnvVar(name: string): string | undefined;
+}
+
+interface AnthropicProviderOptions {
+    apiKey?: string;
+    defaultModel?: string;
+}
+declare class AnthropicProvider extends BaseProvider {
+    readonly name: AiProviderType;
+    private readonly apiKey;
+    private readonly defaultModel;
+    constructor(options?: AnthropicProviderOptions);
+    isConfigured(): boolean;
+    generate(prompt: string, options?: ProviderGenerateOptions): Promise<ProviderResponse>;
+}
+declare function createAnthropicProvider(options?: AnthropicProviderOptions): AnthropicProvider;
+
+interface OpenAIProviderOptions {
+    apiKey?: string;
+    defaultModel?: string;
+}
+declare class OpenAIProvider extends BaseProvider {
+    readonly name: AiProviderType;
+    private readonly apiKey;
+    private readonly defaultModel;
+    constructor(options?: OpenAIProviderOptions);
+    isConfigured(): boolean;
+    generate(prompt: string, options?: ProviderGenerateOptions): Promise<ProviderResponse>;
+}
+declare function createOpenAIProvider(options?: OpenAIProviderOptions): OpenAIProvider;
+
+interface ProviderFactory {
+    create(type: AiProviderType): AiProvider;
+    getAvailable(): readonly AiProviderType[];
+    isAvailable(type: AiProviderType): boolean;
+}
+declare function createProviderFactory(): ProviderFactory;
+declare function getProvider(type: AiProviderType): AiProvider;
+
+/**
+ * Component prompt builder for Constela DSL generation
+ */
+
+/**
+ * Options for building a component prompt
+ */
+interface ComponentPromptOptions {
+    description: string;
+    context?: GenerationContext;
+    constraints?: string[];
+}
+/**
+ * System prompt for component generation
+ */
+declare const COMPONENT_SYSTEM_PROMPT = "You are a Constela DSL component generator.\n\nYour task is to generate valid Constela DSL JSON for UI components based on user descriptions.\n\nOutput Requirements:\n- Return valid JSON representing a Constela DSL component\n- The JSON must have a \"type\" property specifying the component type\n- Include a \"props\" object for component properties\n- Include \"children\" array for nested elements if needed\n- Include \"actions\" array for event handlers if needed\n\nSecurity Rules:\n- Do NOT use forbidden tags: script, iframe, object, embed, form\n- Do NOT use forbidden actions: import, call, dom\n- Keep nesting depth reasonable\n\nAlways output raw JSON, optionally wrapped in a markdown code block.";
+/**
+ * Build a user prompt for component generation
+ */
+declare function buildComponentPrompt(options: ComponentPromptOptions): string;
+
+/**
+ * View prompt builder for Constela DSL generation
+ */
+
+/**
+ * Options for building a view prompt
+ */
+interface ViewPromptOptions {
+    description: string;
+    context?: GenerationContext;
+    constraints?: string[];
+}
+/**
+ * System prompt for view generation
+ */
+declare const VIEW_SYSTEM_PROMPT = "You are a Constela DSL view generator.\n\nYour task is to generate valid Constela DSL JSON for complete views, pages, screens, and layouts based on user descriptions.\n\nOutput Requirements:\n- Return valid JSON representing a Constela DSL view\n- The root element should typically be a \"view\" or layout component\n- Include a \"props\" object for view properties (title, layout options, etc.)\n- Include \"children\" array for the view's content structure\n- Include \"actions\" array for page-level event handlers if needed\n- Structure the view with proper layout containers and nested components\n\nSecurity Rules:\n- Do NOT use forbidden tags: script, iframe, object, embed, form\n- Do NOT use forbidden actions: import, call, dom\n- Keep nesting depth reasonable\n\nAlways output raw JSON, optionally wrapped in a markdown code block.";
+/**
+ * Build a user prompt for view generation
+ */
+declare function buildViewPrompt(options: ViewPromptOptions): string;
+
+/**
+ * Suggest prompt builder for Constela DSL analysis
+ */
+/**
+ * Aspects that can be analyzed for suggestions
+ */
+type SuggestionAspect = 'accessibility' | 'performance' | 'security' | 'ux';
+/**
+ * Severity levels for suggestions
+ */
+type SuggestionSeverity = 'low' | 'medium' | 'high';
+/**
+ * A suggestion for improving DSL
+ */
+interface Suggestion {
+    aspect: SuggestionAspect;
+    issue: string;
+    recommendation: string;
+    location?: string;
+    severity: SuggestionSeverity;
+}
+/**
+ * Options for building a suggest prompt
+ */
+interface SuggestPromptOptions {
+    dsl: unknown;
+    aspect: SuggestionAspect;
+}
+/**
+ * System prompt for suggestion generation
+ */
+declare const SUGGEST_SYSTEM_PROMPT = "You are a Constela DSL code reviewer.\n\nYour task is to analyze Constela DSL and provide suggestions for improvements.\n\nOutput Requirements:\n- Return a JSON array of suggestion objects\n- Each suggestion must have: aspect, issue, recommendation, severity\n- Optionally include location (e.g., \"children[0].props\")\n- Severity levels: low, medium, high\n- Aspects: accessibility, performance, security, ux\n\nFocus Areas by Aspect:\n- accessibility: ARIA labels, keyboard navigation, screen reader support, color contrast\n- performance: unnecessary nesting, heavy components, render optimization\n- security: dangerous props, untrusted URLs, injection risks\n- ux: usability issues, confusing layouts, missing feedback, touch targets\n\nAlways output a JSON array, optionally wrapped in a markdown code block.";
+/**
+ * Build a user prompt for suggestion generation
+ */
+declare function buildSuggestPrompt(options: SuggestPromptOptions): string;
+/**
+ * Parse AI response into suggestions array
+ * Returns empty array for invalid responses
+ */
+declare function parseSuggestions(response: string): Suggestion[];
+
+/**
+ * DSL Generator
+ *
+ * Main class for generating Constela DSL using AI providers
+ */
+
+/**
+ * Options for creating a DslGenerator
+ */
+interface DslGeneratorOptions {
+    provider: AiProviderType;
+    providerInstance?: AiProvider;
+    security?: SecurityOptions$1;
+    context?: GenerationContext;
+}
+/**
+ * Result of DSL generation
+ */
+interface GenerateResult {
+    dsl: Record<string, unknown>;
+    raw: string;
+    validated: boolean;
+    errors?: string[];
+}
+/**
+ * Main class for generating DSL
+ */
+declare class DslGenerator {
+    private readonly providerType;
+    private readonly provider;
+    private readonly security;
+    private readonly context;
+    constructor(options: DslGeneratorOptions);
+    /**
+     * Generate DSL from a prompt
+     */
+    generate(options: GenerateOptions): Promise<GenerateResult>;
+    /**
+     * Validate DSL against security rules
+     */
+    validate(dsl: unknown, securityOverrides?: SecurityOptions$1): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Parse AI response and extract JSON
+     */
+    parseResponse(response: string): Record<string, unknown>;
+}
+/**
+ * Factory function to create a DslGenerator
+ */
+declare function createDslGenerator(options: DslGeneratorOptions): DslGenerator;
+
+export { AI_OUTPUT_TYPES, AI_PROVIDERS, AiError, type AiErrorCode, type AiOutputType, type AiProvider, type AiProviderType, AnthropicProvider, type AnthropicProviderOptions, BaseProvider, COMPONENT_SYSTEM_PROMPT, type ComponentPromptOptions, DslGenerator, type DslGeneratorOptions, type ValidationError as DslValidationError, type DslValidationResult, FORBIDDEN_ACTIONS, FORBIDDEN_TAGS, FORBIDDEN_URL_SCHEMES, type ForbiddenAction, type ForbiddenTag, type ForbiddenUrlScheme, type GenerateOptions, type GenerateResult, type GenerationContext, OpenAIProvider, type OpenAIProviderOptions, type ProviderFactory, type ProviderGenerateOptions, type ProviderResponse, RESTRICTED_ACTIONS, type RestrictedAction, SUGGEST_SYSTEM_PROMPT, SecurityError, type SecurityOptions$1 as SecurityOptions, type SuggestPromptOptions, type Suggestion, type SuggestionAspect, type UrlValidationOptions, type UrlValidationResult, VIEW_SYSTEM_PROMPT, type ValidationContext, ValidationError$1 as ValidationError, type ViewPromptOptions, buildComponentPrompt, buildSuggestPrompt, buildViewPrompt, createAnthropicProvider, createDslGenerator, createOpenAIProvider, createProviderFactory, getProvider, isForbiddenAction, isForbiddenScheme, isForbiddenTag, isRestrictedAction, parseSuggestions, validateActions, validateDsl, validateNode, validateUrl };

package/dist/index.js

@@ -0,0 +1,840 @@
+// src/types.ts
+var AI_PROVIDERS = Object.freeze(["anthropic", "openai"]);
+var AI_OUTPUT_TYPES = Object.freeze(["component", "view", "suggestion"]);
+
+// src/errors.ts
+var AiError = class _AiError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "AiError";
+    Object.setPrototypeOf(this, _AiError.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code
+    };
+  }
+};
+var ValidationError = class _ValidationError extends AiError {
+  constructor(message, violations) {
+    super(message, "VALIDATION_ERROR");
+    this.violations = violations;
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      violations: this.violations
+    };
+  }
+};
+var SecurityError = class _SecurityError extends AiError {
+  constructor(message, violation) {
+    super(message, "SECURITY_VIOLATION");
+    this.violation = violation;
+    this.name = "SecurityError";
+    Object.setPrototypeOf(this, _SecurityError.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      violation: this.violation
+    };
+  }
+};
+
+// src/security/whitelist.ts
+var FORBIDDEN_TAGS = Object.freeze([
+  "script",
+  "iframe",
+  "object",
+  "embed",
+  "form"
+]);
+var FORBIDDEN_ACTIONS = Object.freeze([
+  "import",
+  "call",
+  "dom"
+]);
+var RESTRICTED_ACTIONS = Object.freeze([
+  "fetch"
+]);
+function isForbiddenTag(tag) {
+  if (typeof tag !== "string") {
+    return false;
+  }
+  return FORBIDDEN_TAGS.includes(tag);
+}
+function isForbiddenAction(action) {
+  if (typeof action !== "string") {
+    return false;
+  }
+  return FORBIDDEN_ACTIONS.includes(action);
+}
+function isRestrictedAction(action) {
+  if (typeof action !== "string") {
+    return false;
+  }
+  return RESTRICTED_ACTIONS.includes(action);
+}
+
+// src/security/url-validator.ts
+var FORBIDDEN_URL_SCHEMES = Object.freeze([
+  "javascript:",
+  "data:",
+  "vbscript:"
+]);
+function isForbiddenScheme(url) {
+  const trimmedUrl = url.trim().toLowerCase();
+  const decodedUrl = tryDecodeUri(trimmedUrl);
+  return FORBIDDEN_URL_SCHEMES.some(
+    (scheme) => trimmedUrl.startsWith(scheme) || decodedUrl.startsWith(scheme)
+  );
+}
+function tryDecodeUri(url) {
+  try {
+    return decodeURIComponent(url);
+  } catch {
+    return url;
+  }
+}
+function validateUrl(url, options) {
+  const trimmedUrl = url.trim();
+  if (trimmedUrl === "") {
+    return { valid: false, reason: "Empty URL is not allowed" };
+  }
+  if (isForbiddenScheme(trimmedUrl)) {
+    const lowerUrl = trimmedUrl.toLowerCase();
+    let scheme = "unknown";
+    for (const forbiddenScheme of FORBIDDEN_URL_SCHEMES) {
+      if (lowerUrl.startsWith(forbiddenScheme) || tryDecodeUri(lowerUrl).startsWith(forbiddenScheme)) {
+        scheme = forbiddenScheme.replace(":", "");
+        break;
+      }
+    }
+    return { valid: false, reason: `Forbidden URL scheme: ${scheme}` };
+  }
+  const isRelative = !trimmedUrl.includes("://") && !trimmedUrl.startsWith("//");
+  const allowRelative = options?.allowRelative ?? true;
+  if (isRelative) {
+    return allowRelative ? { valid: true } : { valid: false, reason: "Relative URLs are not allowed" };
+  }
+  if (options?.allowedDomains && options.allowedDomains.length > 0) {
+    try {
+      const urlObj = new URL(trimmedUrl);
+      const hostname = urlObj.hostname.toLowerCase();
+      const isAllowed = options.allowedDomains.some((domain) => {
+        const lowerDomain = domain.toLowerCase();
+        return hostname === lowerDomain;
+      });
+      if (!isAllowed) {
+        return { valid: false, reason: `Domain not in allowed list: ${hostname}` };
+      }
+    } catch {
+      return { valid: false, reason: "Invalid URL format" };
+    }
+  }
+  return { valid: true };
+}
+
+// src/validator.ts
+var DEFAULT_MAX_NESTING_DEPTH = 32;
+function validateDsl(dsl, context) {
+  const errors = [];
+  const basePath = context?.path ?? "root";
+  if (!isPlainObject(dsl)) {
+    errors.push({
+      message: "DSL must be a non-null object",
+      path: basePath,
+      code: "INVALID_DSL"
+    });
+    return { valid: false, errors };
+  }
+  const nodeErrors = validateNodeRecursive(
+    dsl,
+    { ...context, path: basePath },
+    0
+  );
+  errors.push(...nodeErrors);
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateNode(node, context) {
+  if (!isPlainObject(node)) {
+    return [];
+  }
+  const errors = [];
+  const path = context?.path ?? "node";
+  const dslNode = node;
+  if (dslNode.type && isForbiddenTag(dslNode.type)) {
+    errors.push({
+      message: "Forbidden tag: " + dslNode.type,
+      path,
+      code: "FORBIDDEN_TAG"
+    });
+  }
+  if (context?.security?.allowedTags && context.security.allowedTags.length > 0 && dslNode.type) {
+    if (!context.security.allowedTags.includes(dslNode.type)) {
+      errors.push({
+        message: "Tag not in allowed list: " + dslNode.type,
+        path,
+        code: "TAG_NOT_ALLOWED"
+      });
+    }
+  }
+  if (dslNode.actions) {
+    const actionErrors = validateActions(dslNode.actions, {
+      ...context,
+      path: path + ".actions"
+    });
+    errors.push(...actionErrors);
+  }
+  return errors;
+}
+function validateActions(actions, context) {
+  if (actions === null || actions === void 0) {
+    return [];
+  }
+  if (!Array.isArray(actions)) {
+    return [];
+  }
+  const errors = [];
+  const basePath = context?.path ?? "actions";
+  const allowedActions = context?.security?.allowedActions ?? [];
+  const allowedUrlPatterns = context?.security?.allowedUrlPatterns ?? [];
+  actions.forEach((action, index) => {
+    if (!isPlainObject(action)) {
+      return;
+    }
+    const actionPath = basePath + "[" + index + "]";
+    const dslAction = action;
+    const actionType = dslAction.type;
+    if (!actionType) {
+      return;
+    }
+    if (isForbiddenAction(actionType)) {
+      errors.push({
+        message: "Forbidden action: " + actionType,
+        path: actionPath,
+        code: "FORBIDDEN_ACTION"
+      });
+      return;
+    }
+    if (isRestrictedAction(actionType)) {
+      if (!allowedActions.includes(actionType)) {
+        errors.push({
+          message: "Restricted action requires explicit whitelist: " + actionType,
+          path: actionPath,
+          code: "RESTRICTED_ACTION"
+        });
+        return;
+      }
+      if (actionType === "fetch" && dslAction.payload?.["url"]) {
+        const url = String(dslAction.payload["url"]);
+        const urlValidation = validateActionUrl(url, allowedUrlPatterns);
+        if (!urlValidation.valid) {
+          errors.push({
+            message: urlValidation.reason ?? "Invalid URL",
+            path: actionPath + ".payload.url",
+            code: "INVALID_URL"
+          });
+        }
+      }
+    }
+    if (context?.security?.allowedActions && !isStandardAction(actionType) && !allowedActions.includes(actionType)) {
+      errors.push({
+        message: "Action not in allowed list: " + actionType,
+        path: actionPath,
+        code: "ACTION_NOT_ALLOWED"
+      });
+    }
+    if (actionType === "navigate" && dslAction.payload) {
+      const url = dslAction.payload["url"] ?? dslAction.payload["path"];
+      if (url && typeof url === "string") {
+        const urlResult = validateUrl(url);
+        if (!urlResult.valid) {
+          errors.push({
+            message: urlResult.reason ?? "Invalid navigation URL",
+            path: actionPath + ".payload.url",
+            code: "INVALID_URL"
+          });
+        }
+      }
+    }
+  });
+  return errors;
+}
+var STANDARD_ACTIONS = ["navigate", "setState", "emit", "submit"];
+function isStandardAction(action) {
+  return STANDARD_ACTIONS.includes(action);
+}
+function validateNodeRecursive(node, context, depth) {
+  const errors = [];
+  const path = context.path ?? "root";
+  const maxDepth = context.security?.maxNestingDepth ?? DEFAULT_MAX_NESTING_DEPTH;
+  if (depth > maxDepth) {
+    errors.push({
+      message: "Maximum nesting depth exceeded: " + depth + " > " + maxDepth,
+      path,
+      code: "MAX_DEPTH_EXCEEDED"
+    });
+    return errors;
+  }
+  const nodeErrors = validateNode(node, context);
+  errors.push(...nodeErrors);
+  if (Array.isArray(node.children)) {
+    node.children.forEach((child, index) => {
+      if (isPlainObject(child)) {
+        const childErrors = validateNodeRecursive(
+          child,
+          { ...context, path: path + ".children[" + index + "]" },
+          depth + 1
+        );
+        errors.push(...childErrors);
+      }
+    });
+  }
+  return errors;
+}
+function validateActionUrl(url, allowedPatterns) {
+  if (isForbiddenScheme(url)) {
+    const scheme = url.toLowerCase().split(":")[0];
+    return { valid: false, reason: "Forbidden URL scheme: " + scheme };
+  }
+  if (allowedPatterns.length === 0) {
+    return { valid: true };
+  }
+  for (const pattern of allowedPatterns) {
+    if (matchUrlPattern(url, pattern)) {
+      return { valid: true };
+    }
+  }
+  return { valid: false, reason: "URL does not match allowed patterns: " + url };
+}
+function matchUrlPattern(url, pattern) {
+  let regexPattern = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === "*") {
+      regexPattern += ".*";
+    } else if (".+?^${}()|[]\\".includes(char)) {
+      regexPattern += "\\" + char;
+    } else {
+      regexPattern += char;
+    }
+  }
+  const regex = new RegExp("^" + regexPattern + "$");
+  return regex.test(url);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/providers/anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+
+// src/providers/base.ts
+var BaseProvider = class {
+  validatePrompt(prompt) {
+    if (!prompt || typeof prompt !== "string" || prompt.trim().length === 0) {
+      throw new AiError("Prompt cannot be empty", "VALIDATION_ERROR");
+    }
+  }
+  getEnvVar(name) {
+    return process.env[name];
+  }
+};
+
+// src/providers/anthropic.ts
+var DEFAULT_MODEL = "claude-sonnet-4-20250514";
+var DEFAULT_MAX_TOKENS = 4096;
+var AnthropicProvider = class extends BaseProvider {
+  name = "anthropic";
+  apiKey;
+  defaultModel;
+  constructor(options) {
+    super();
+    this.apiKey = options?.apiKey ?? this.getEnvVar("ANTHROPIC_API_KEY");
+    this.defaultModel = options?.defaultModel ?? DEFAULT_MODEL;
+  }
+  isConfigured() {
+    return Boolean(this.apiKey && this.apiKey.length > 0);
+  }
+  async generate(prompt, options) {
+    if (!this.isConfigured()) {
+      throw new AiError(
+        "Anthropic provider is not configured. Please set ANTHROPIC_API_KEY environment variable or provide apiKey in options.",
+        "PROVIDER_NOT_CONFIGURED"
+      );
+    }
+    this.validatePrompt(prompt);
+    try {
+      const client = new Anthropic({ apiKey: this.apiKey });
+      const params = {
+        model: options?.model ?? this.defaultModel,
+        max_tokens: options?.maxTokens ?? DEFAULT_MAX_TOKENS,
+        messages: [{ role: "user", content: prompt }]
+      };
+      if (options?.temperature !== void 0) {
+        params.temperature = options.temperature;
+      }
+      if (options?.systemPrompt !== void 0) {
+        params.system = options.systemPrompt;
+      }
+      const response = await client.messages.create(params);
+      const textContent = response.content.find((block) => block.type === "text");
+      const content = textContent && "text" in textContent ? textContent.text : "";
+      const result = {
+        content,
+        model: response.model
+      };
+      if (response.usage) {
+        result.usage = {
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens
+        };
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof AiError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : "Unknown error occurred";
+      throw new AiError(`Anthropic API error: ${message}`, "API_ERROR");
+    }
+  }
+};
+function createAnthropicProvider(options) {
+  return new AnthropicProvider(options);
+}
+
+// src/providers/openai.ts
+import OpenAI from "openai";
+var DEFAULT_MODEL2 = "gpt-4o";
+var DEFAULT_MAX_TOKENS2 = 4096;
+var OpenAIProvider = class extends BaseProvider {
+  name = "openai";
+  apiKey;
+  defaultModel;
+  constructor(options) {
+    super();
+    this.apiKey = options?.apiKey ?? this.getEnvVar("OPENAI_API_KEY");
+    this.defaultModel = options?.defaultModel ?? DEFAULT_MODEL2;
+  }
+  isConfigured() {
+    return Boolean(this.apiKey && this.apiKey.length > 0);
+  }
+  async generate(prompt, options) {
+    if (!this.isConfigured()) {
+      throw new AiError(
+        "OpenAI provider is not configured. Please set OPENAI_API_KEY environment variable or provide apiKey in options.",
+        "PROVIDER_NOT_CONFIGURED"
+      );
+    }
+    this.validatePrompt(prompt);
+    try {
+      const client = new OpenAI({ apiKey: this.apiKey });
+      const messages = [];
+      if (options?.systemPrompt) {
+        messages.push({ role: "system", content: options.systemPrompt });
+      }
+      messages.push({ role: "user", content: prompt });
+      const params = {
+        model: options?.model ?? this.defaultModel,
+        max_tokens: options?.maxTokens ?? DEFAULT_MAX_TOKENS2,
+        messages
+      };
+      if (options?.temperature !== void 0) {
+        params.temperature = options.temperature;
+      }
+      const response = await client.chat.completions.create(params);
+      const content = response.choices[0]?.message?.content;
+      if (content === null || content === void 0) {
+        throw new AiError("OpenAI returned empty response", "API_ERROR");
+      }
+      const result = {
+        content,
+        model: response.model
+      };
+      if (response.usage) {
+        result.usage = {
+          inputTokens: response.usage.prompt_tokens,
+          outputTokens: response.usage.completion_tokens
+        };
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof AiError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : "Unknown error occurred";
+      throw new AiError(`OpenAI API error: ${message}`, "API_ERROR");
+    }
+  }
+};
+function createOpenAIProvider(options) {
+  return new OpenAIProvider(options);
+}
+
+// src/providers/index.ts
+function createProviderFactory() {
+  return {
+    create(type) {
+      switch (type) {
+        case "anthropic":
+          return createAnthropicProvider();
+        case "openai":
+          return createOpenAIProvider();
+        default:
+          throw new AiError(
+            `Unknown provider type: ${type}. Available providers: ${AI_PROVIDERS.join(", ")}`,
+            "PROVIDER_NOT_FOUND"
+          );
+      }
+    },
+    getAvailable() {
+      return AI_PROVIDERS;
+    },
+    isAvailable(type) {
+      try {
+        const provider = this.create(type);
+        return provider.isConfigured();
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+function getProvider(type) {
+  const factory = createProviderFactory();
+  return factory.create(type);
+}
+
+// src/prompts/component.ts
+var COMPONENT_SYSTEM_PROMPT = `You are a Constela DSL component generator.
+
+Your task is to generate valid Constela DSL JSON for UI components based on user descriptions.
+
+Output Requirements:
+- Return valid JSON representing a Constela DSL component
+- The JSON must have a "type" property specifying the component type
+- Include a "props" object for component properties
+- Include "children" array for nested elements if needed
+- Include "actions" array for event handlers if needed
+
+Security Rules:
+- Do NOT use forbidden tags: script, iframe, object, embed, form
+- Do NOT use forbidden actions: import, call, dom
+- Keep nesting depth reasonable
+
+Always output raw JSON, optionally wrapped in a markdown code block.`;
+function buildComponentPrompt(options) {
+  const { description, context, constraints } = options;
+  const parts = [];
+  parts.push("Create a Constela DSL component based on the following description:\n\n" + description);
+  if (context) {
+    const contextParts = [];
+    if (context.existingComponents && context.existingComponents.length > 0) {
+      contextParts.push("Available components: " + context.existingComponents.join(", "));
+    }
+    if (context.theme && Object.keys(context.theme).length > 0) {
+      contextParts.push("Theme: " + JSON.stringify(context.theme));
+    }
+    if (context.schema && Object.keys(context.schema).length > 0) {
+      contextParts.push("Schema: " + JSON.stringify(context.schema));
+    }
+    if (contextParts.length > 0) {
+      parts.push("\nContext:\n" + contextParts.join("\n"));
+    }
+  }
+  if (constraints && constraints.length > 0) {
+    parts.push("\nConstraints:\n" + constraints.map((c) => "- " + c).join("\n"));
+  }
+  return parts.join("\n");
+}
+
+// src/prompts/view.ts
+var VIEW_SYSTEM_PROMPT = `You are a Constela DSL view generator.
+
+Your task is to generate valid Constela DSL JSON for complete views, pages, screens, and layouts based on user descriptions.
+
+Output Requirements:
+- Return valid JSON representing a Constela DSL view
+- The root element should typically be a "view" or layout component
+- Include a "props" object for view properties (title, layout options, etc.)
+- Include "children" array for the view's content structure
+- Include "actions" array for page-level event handlers if needed
+- Structure the view with proper layout containers and nested components
+
+Security Rules:
+- Do NOT use forbidden tags: script, iframe, object, embed, form
+- Do NOT use forbidden actions: import, call, dom
+- Keep nesting depth reasonable
+
+Always output raw JSON, optionally wrapped in a markdown code block.`;
+function buildViewPrompt(options) {
+  const { description, context, constraints } = options;
+  const parts = [];
+  parts.push("Create a Constela DSL view based on the following description:\n\n" + description);
+  if (context) {
+    const contextParts = [];
+    if (context.existingComponents && context.existingComponents.length > 0) {
+      contextParts.push("Available components: " + context.existingComponents.join(", "));
+    }
+    if (context.theme && Object.keys(context.theme).length > 0) {
+      contextParts.push("Theme: " + JSON.stringify(context.theme));
+    }
+    if (context.schema && Object.keys(context.schema).length > 0) {
+      contextParts.push("Schema: " + JSON.stringify(context.schema));
+    }
+    if (contextParts.length > 0) {
+      parts.push("\nContext:\n" + contextParts.join("\n"));
+    }
+  }
+  if (constraints && constraints.length > 0) {
+    parts.push("\nConstraints:\n" + constraints.map((c) => "- " + c).join("\n"));
+  }
+  return parts.join("\n");
+}
+
+// src/prompts/suggest.ts
+var VALID_ASPECTS = ["accessibility", "performance", "security", "ux"];
+var VALID_SEVERITIES = ["low", "medium", "high"];
+var SUGGEST_SYSTEM_PROMPT = `You are a Constela DSL code reviewer.
+
+Your task is to analyze Constela DSL and provide suggestions for improvements.
+
+Output Requirements:
+- Return a JSON array of suggestion objects
+- Each suggestion must have: aspect, issue, recommendation, severity
+- Optionally include location (e.g., "children[0].props")
+- Severity levels: low, medium, high
+- Aspects: accessibility, performance, security, ux
+
+Focus Areas by Aspect:
+- accessibility: ARIA labels, keyboard navigation, screen reader support, color contrast
+- performance: unnecessary nesting, heavy components, render optimization
+- security: dangerous props, untrusted URLs, injection risks
+- ux: usability issues, confusing layouts, missing feedback, touch targets
+
+Always output a JSON array, optionally wrapped in a markdown code block.`;
+function buildSuggestPrompt(options) {
+  const { dsl, aspect } = options;
+  const dslString = typeof dsl === "string" ? dsl : JSON.stringify(dsl, null, 2);
+  return `Analyze the following Constela DSL for ${aspect} issues and provide suggestions:
+
+\`\`\`json
+${dslString}
+\`\`\`
+
+Focus specifically on ${aspect} concerns. Return a JSON array of suggestions.`;
+}
+function extractJson(response) {
+  const trimmed = response.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  const codeBlockMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (codeBlockMatch?.[1]) {
+    return codeBlockMatch[1].trim();
+  }
+  return trimmed;
+}
+function isValidSuggestion(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  const suggestion = obj;
+  if (typeof suggestion["aspect"] !== "string" || typeof suggestion["issue"] !== "string" || typeof suggestion["recommendation"] !== "string" || typeof suggestion["severity"] !== "string") {
+    return false;
+  }
+  if (!VALID_ASPECTS.includes(suggestion["aspect"])) {
+    return false;
+  }
+  if (!VALID_SEVERITIES.includes(suggestion["severity"])) {
+    return false;
+  }
+  if (suggestion["location"] !== void 0 && typeof suggestion["location"] !== "string") {
+    return false;
+  }
+  return true;
+}
+function parseSuggestions(response) {
+  const jsonString = extractJson(response);
+  if (!jsonString) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(jsonString);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    const validSuggestions = parsed.filter(isValidSuggestion);
+    if (parsed.length > 0 && validSuggestions.length === 0) {
+      return [];
+    }
+    return validSuggestions;
+  } catch {
+    return [];
+  }
+}
+
+// src/generator.ts
+var DslGenerator = class {
+  providerType;
+  provider;
+  security;
+  context;
+  constructor(options) {
+    this.providerType = options.provider;
+    this.provider = options.providerInstance ?? getProvider(options.provider);
+    this.security = options.security ?? {};
+    this.context = options.context ?? {};
+  }
+  /**
+   * Generate DSL from a prompt
+   */
+  async generate(options) {
+    const { prompt, output, context, security } = options;
+    const mergedContext = {
+      ...this.context,
+      ...context
+    };
+    const mergedSecurity = {
+      ...this.security,
+      ...security
+    };
+    let userPrompt;
+    let systemPrompt;
+    switch (output) {
+      case "component":
+        userPrompt = buildComponentPrompt({
+          description: prompt,
+          context: mergedContext
+        });
+        systemPrompt = COMPONENT_SYSTEM_PROMPT;
+        break;
+      case "view":
+        userPrompt = buildViewPrompt({
+          description: prompt,
+          context: mergedContext
+        });
+        systemPrompt = VIEW_SYSTEM_PROMPT;
+        break;
+      case "suggestion":
+        userPrompt = buildSuggestPrompt({
+          dsl: {},
+          aspect: "accessibility"
+        });
+        systemPrompt = SUGGEST_SYSTEM_PROMPT;
+        break;
+      default:
+        userPrompt = prompt;
+        systemPrompt = COMPONENT_SYSTEM_PROMPT;
+    }
+    const response = await this.provider.generate(userPrompt, {
+      systemPrompt
+    });
+    const raw = response.content;
+    const dsl = this.parseResponse(raw);
+    const validationResult = this.validate(dsl, mergedSecurity);
+    if (validationResult.valid) {
+      return {
+        dsl,
+        raw,
+        validated: true
+      };
+    }
+    return {
+      dsl,
+      raw,
+      validated: false,
+      errors: validationResult.errors
+    };
+  }
+  /**
+   * Validate DSL against security rules
+   */
+  validate(dsl, securityOverrides) {
+    const mergedSecurity = {
+      ...this.security,
+      ...securityOverrides
+    };
+    const result = validateDsl(dsl, {
+      security: mergedSecurity
+    });
+    return {
+      valid: result.valid,
+      errors: result.errors.map((e) => e.message)
+    };
+  }
+  /**
+   * Parse AI response and extract JSON
+   */
+  parseResponse(response) {
+    const trimmed = response.trim();
+    if (trimmed === "") {
+      throw new Error("Empty response");
+    }
+    const codeBlockMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const jsonString = codeBlockMatch?.[1]?.trim() ?? trimmed;
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonString);
+    } catch {
+      throw new Error("Invalid JSON in response");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("Response must be a JSON object");
+    }
+    return parsed;
+  }
+};
+function createDslGenerator(options) {
+  return new DslGenerator(options);
+}
+export {
+  AI_OUTPUT_TYPES,
+  AI_PROVIDERS,
+  AiError,
+  AnthropicProvider,
+  BaseProvider,
+  COMPONENT_SYSTEM_PROMPT,
+  DslGenerator,
+  FORBIDDEN_ACTIONS,
+  FORBIDDEN_TAGS,
+  FORBIDDEN_URL_SCHEMES,
+  OpenAIProvider,
+  RESTRICTED_ACTIONS,
+  SUGGEST_SYSTEM_PROMPT,
+  SecurityError,
+  VIEW_SYSTEM_PROMPT,
+  ValidationError,
+  buildComponentPrompt,
+  buildSuggestPrompt,
+  buildViewPrompt,
+  createAnthropicProvider,
+  createDslGenerator,
+  createOpenAIProvider,
+  createProviderFactory,
+  getProvider,
+  isForbiddenAction,
+  isForbiddenScheme,
+  isForbiddenTag,
+  isRestrictedAction,
+  parseSuggestions,
+  validateActions,
+  validateDsl,
+  validateNode,
+  validateUrl
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@constela/ai",
+  "version": "1.0.0",
+  "description": "AI provider abstraction layer for Constela DSL",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "openai": "^4.96.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@constela/core": "0.16.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}