dirac-browser 0.1.1

package/src/tags/if.ts

@@ -0,0 +1,58 @@
+/**
+ * <if> tag - conditional execution
+ * Maps to mask_tag_if in MASK
+ */
+
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { substituteVariables, getVariable } from '../runtime/session.js';
+import { integrateChildren } from '../runtime/interpreter.js';
+
+export async function executeIf(session: DiracSession, element: DiracElement): Promise<void> {
+  const test = element.attributes.test;
+  
+  if (!test) {
+    throw new Error('<if> requires test attribute');
+  }
+  
+  const condition = evaluateCondition(session, test);
+  
+  if (condition) {
+    await integrateChildren(session, element);
+  }
+}
+
+function evaluateCondition(session: DiracSession, test: string): boolean {
+  // Substitute variables first
+  const substituted = substituteVariables(session, test);
+  
+  // Simple condition evaluation (can be enhanced later)
+  // Supports: ==, !=, <, >, <=, >=
+  
+  const operators = ['==', '!=', '<=', '>=', '<', '>'];
+  
+  for (const op of operators) {
+    const parts = substituted.split(op);
+    if (parts.length === 2) {
+      const left = parts[0].trim();
+      const right = parts[1].trim();
+      
+      switch (op) {
+        case '==':
+          return left === right;
+        case '!=':
+          return left !== right;
+        case '<':
+          return parseFloat(left) < parseFloat(right);
+        case '>':
+          return parseFloat(left) > parseFloat(right);
+        case '<=':
+          return parseFloat(left) <= parseFloat(right);
+        case '>=':
+          return parseFloat(left) >= parseFloat(right);
+      }
+    }
+  }
+  
+  // If no operator, treat as boolean (non-empty = true)
+  return substituted.trim() !== '' && substituted.trim() !== '0' && substituted.trim() !== 'false';
+}

package/src/tags/llm.ts

@@ -0,0 +1,88 @@
+/**
+ * <llm> tag - Call LLM via backend service
+ * Browser edition - makes HTTP calls to dirac-server
+ */
+
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { setVariable, emit } from '../runtime/session.js';
+
+export async function executeLLM(session: DiracSession, element: DiracElement): Promise<void> {
+  const model = element.attributes.model || 'claude-sonnet-4-20250514';
+  const userPrompt = element.attributes.prompt || element.text || '';
+  const name = element.attributes.name;
+  const temperature = parseFloat(element.attributes.temperature || '0');
+  const maxTokens = parseInt(element.attributes['max-tokens'] || '100', 10);
+
+  if (!userPrompt) {
+    throw new Error('<llm> requires prompt attribute or text content');
+  }
+
+  // Reflect subroutines for system prompt
+  // Use getAvailableSubroutines from session
+  // (imported from ../runtime/session.js)
+  // @ts-ignore
+  const { getAvailableSubroutines } = await import('../runtime/session.js');
+  const subroutines = getAvailableSubroutines(session);
+  let systemPrompt = 'You are an expert Dirac command generator.\nAvailable subroutines:';
+  for (const sub of subroutines) {
+    systemPrompt += `\n- <${sub.name} />: ${sub.description || ''}`;
+    if (sub.parameters && sub.parameters.length > 0) {
+      systemPrompt += ' Parameters: ' + sub.parameters.map(p => `${p.name} (${p.type || 'string'})`).join(', ');
+    }
+  }
+  systemPrompt += '\nInstructions: Output only valid Dirac XML tags. Do not include explanations or extra text.';
+
+  // Example (optional):
+  // systemPrompt += '\nExample: User: Show me my inventory\nOutput: <inventory />';
+
+  // Final prompt
+  const prompt = systemPrompt + '\nUser: ' + userPrompt + '\nOutput:';
+
+  // Get backend URL from config
+  const backendUrl = session.config.llmBackendUrl || 'http://localhost:3000';
+
+  if (session.debug) {
+    console.error(`[LLM] Calling backend: ${backendUrl}/api/llm/complete`);
+    console.error(`[LLM] Model: ${model}, Prompt length: ${prompt.length}`);
+  }
+  
+  try {
+    // Call backend LLM API
+    const response = await fetch(`${backendUrl}/api/llm/complete`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        prompt,
+        temperature,
+        maxTokens
+      })
+    });
+    
+    if (!response.ok) {
+      throw new Error(`LLM API error: ${response.status} ${response.statusText}`);
+    }
+    
+    const data = await response.json();
+    const result = data.response || '';
+    
+    if (session.debug) {
+      console.error(`[LLM] Response length: ${result.length}`);
+    }
+    
+    // Store result if name provided
+    if (name) {
+      setVariable(session, name, result, false);
+    }
+    
+    // Emit result
+    emit(session, result);
+    
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    console.error('[LLM] Error:', errorMsg);
+    throw new Error(`LLM call failed: ${errorMsg}`);
+  }
+}

package/src/tags/loop.ts

@@ -0,0 +1,43 @@
+/**
+ * <loop> tag - iteration
+ * Maps to mask_tag_loop in MASK
+ */
+
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { setVariable, substituteVariables, getVariable } from '../runtime/session.js';
+import { integrateChildren } from '../runtime/interpreter.js';
+
+export async function executeLoop(session: DiracSession, element: DiracElement): Promise<void> {
+  const countAttr = element.attributes.count;
+  const varName = element.attributes.var || 'i';
+  
+  if (!countAttr) {
+    throw new Error('<loop> requires count attribute');
+  }
+  
+  const count = parseInt(substituteVariables(session, countAttr), 10);
+  
+  if (isNaN(count) || count < 0) {
+    throw new Error(`Invalid loop count: ${countAttr}`);
+  }
+  
+  const wasBreak = session.isBreak;
+  session.isBreak = false;
+  
+  for (let i = 0; i < count; i++) {
+    setVariable(session, varName, i, false);
+    
+    await integrateChildren(session, element);
+    
+    if (session.isBreak) {
+      session.isBreak = false;
+      break;
+    }
+    
+    if (session.isReturn) {
+      break;
+    }
+  }
+  
+  session.isBreak = wasBreak;
+}

package/src/tags/output.ts

@@ -0,0 +1,23 @@
+/**
+ * <output> tag - emit content
+ * Maps to mask_tag_output in MASK
+ */
+
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { emit, substituteVariables } from '../runtime/session.js';
+import { integrateChildren } from '../runtime/interpreter.js';
+
+export async function executeOutput(session: DiracSession, element: DiracElement): Promise<void> {
+  // If has children, process them (handles mixed content)
+  if (element.children && element.children.length > 0) {
+    await integrateChildren(session, element);
+    return;
+  }
+  
+  // If only text content, use it (with variable substitution)
+  if (element.text) {
+    const content = substituteVariables(session, element.text);
+    emit(session, content);
+    return;
+  }
+}

package/src/tags/parameters.ts

@@ -0,0 +1,77 @@
+/**
+ * <parameters> tag - Access parameters passed to subroutine
+ * Maps to MASK parameter selection syntax
+ */
+
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { getCurrentParameters, emit, setVariable } from '../runtime/session.js';
+import { integrate } from '../runtime/interpreter.js';
+
+export async function executeParameters(session: DiracSession, element: DiracElement): Promise<void> {
+  const select = element.attributes.select;
+  
+  if (!select) {
+    throw new Error('<parameters> requires select attribute');
+  }
+  
+  // Get parameters from current call context
+  const params = getCurrentParameters(session);
+  
+  if (!params || params.length === 0) {
+    if (session.debug) {
+      console.error(`[PARAMETERS] No parameters available`);
+    }
+    return;
+  }
+  
+  // The caller element is params[0] (the calling tag itself)
+  const caller = params[0];
+  
+  if (select === '*') {
+    // Select all child elements - execute them
+    if (session.debug) {
+      console.error(`[PARAMETERS] Selecting all children (${caller.children.length} elements)`);
+    }
+    
+    for (const child of caller.children) {
+      await integrate(session, child);
+    }
+    
+  } else if (select.startsWith('@')) {
+    // Select attribute(s)
+    const attrName = select.slice(1); // Remove '@'
+    
+    if (attrName === '*') {
+      // Select all attributes
+      if (session.debug) {
+        console.error(`[PARAMETERS] Selecting all attributes`);
+      }
+      
+      const attrs = Object.entries(caller.attributes)
+        .map(([key, val]) => `${key}="${val}"`)
+        .join(' ');
+      emit(session, attrs);
+      
+    } else {
+      // Select specific attribute - automatically create variable with that name
+      const value = caller.attributes[attrName];
+      
+      if (session.debug) {
+        console.error(`[PARAMETERS] Setting variable '${attrName}' = '${value}'`);
+      }
+      
+      if (value !== undefined) {
+        // Automatically create variable (like defvar)
+        setVariable(session, attrName, value, false);
+      }
+      
+      // Execute children if any (for additional processing)
+      for (const child of element.children) {
+        await integrate(session, child);
+      }
+    }
+    
+  } else {
+    throw new Error(`<parameters> invalid select: ${select}`);
+  }
+}

package/src/tags/subroutine.ts

@@ -0,0 +1,52 @@
+/**
+ * <subroutine> tag - define reusable code block
+ * Maps to mask_tag_subroutine in MASK
+ */
+
+import type { DiracSession, DiracElement, ParameterMetadata } from '../types/index.js';
+import { registerSubroutine } from '../runtime/session.js';
+
+export function executeSubroutine(session: DiracSession, element: DiracElement): void {
+  const name = element.attributes.name;
+  
+  if (!name) {
+    throw new Error('<subroutine> requires name attribute');
+  }
+  
+  // Extract metadata from attributes (no structural changes!)
+  const description = element.attributes.description;
+  const parameters: ParameterMetadata[] = [];
+  
+  // Parse param- prefixed attributes for metadata
+  // e.g., param-color="string:required:Color name:red|blue|green"
+  for (const [attrName, attrValue] of Object.entries(element.attributes)) {
+    if (attrName.startsWith('param-')) {
+      const paramName = attrName.substring(6); // Remove "param-" prefix
+      
+      // Parse format: "type:required:description:enum1|enum2|..."
+      const parts = attrValue.split(':');
+      const paramMeta: ParameterMetadata = {
+        name: paramName,
+        type: parts[0] || 'string',
+        required: parts[1] === 'required',
+        description: parts[2] || undefined,
+      };
+      
+      // Parse enum if present (after 3rd colon)
+      if (parts[3]) {
+        paramMeta.enum = parts[3].split('|');
+      }
+      
+      parameters.push(paramMeta);
+    }
+  }
+  
+  // Store subroutine exactly as before (preserves nesting and extends)
+  const subroutine: DiracElement = {
+    tag: 'subroutine',
+    attributes: { ...element.attributes },
+    children: element.children,
+  };
+  
+  registerSubroutine(session, name, subroutine, description, parameters.length > 0 ? parameters : undefined);
+}

package/src/tags/variable.ts

@@ -0,0 +1,27 @@
+/**
+ * <variable> tag - retrieve variable value
+ * Outputs the stored variable content (text or tags)
+ */
+
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { getVariable, emit } from '../runtime/session.js';
+
+export function executeVariable(session: DiracSession, element: DiracElement): void {
+  const name = element.attributes.name;
+  
+  if (!name) {
+    throw new Error('<variable> requires name attribute');
+  }
+  
+  const value = getVariable(session, name);
+  
+  if (value === undefined) {
+    if (session.debug) {
+      console.error(`[Warning] Variable '${name}' is undefined`);
+    }
+    return;
+  }
+  
+  // Output the variable value
+  emit(session, String(value));
+}

package/src/types/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Core types for Dirac interpreter
+ * Directly based on MASK C implementation
+ */
+
+export interface DiracElement {
+  tag: string;
+  attributes: Record<string, string>;
+  children: DiracElement[];
+  text?: string;
+}
+
+/**
+ * Variable info - maps to VarInfo in MASK
+ */
+export interface Variable {
+  name: string;
+  value: any;
+  visible: boolean;
+  boundary: number;  // scope boundary marker
+  passby: 'value' | 'ref';
+  refName?: string;  // for pass-by-reference
+}
+
+/**
+ * Subroutine info - maps to Subroutine in MASK
+ */
+export interface Subroutine {
+  name: string;
+  element: DiracElement;
+  boundary: number;  // scope boundary marker
+  extends?: string;  // parent subroutine
+  description?: string;  // For LLM reflection
+  parameters?: ParameterMetadata[];  // For LLM reflection
+}
+
+/**
+ * Parameter metadata for reflection API
+ */
+export interface ParameterMetadata {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+  enum?: string[];
+}
+
+/**
+ * Execution context - maps to MaskSession in MASK
+ */
+export interface DiracSession {
+  // Variable stack (all variables are on stack)
+  variables: Variable[];
+  
+  // Subroutine registry
+  subroutines: Subroutine[];
+  
+  // Scope boundaries (for cleanup)
+  varBoundary: number;
+  subBoundary: number;
+  
+  // Parameter stack (for subroutine calls)
+  parameterStack: DiracElement[][];
+  
+  // Output buffer
+  output: string[];
+  
+  // LLM client
+  llmClient?: any;
+  
+  // Execution limits
+  limits: {
+    maxLLMCalls: number;
+    currentLLMCalls: number;
+    maxDepth: number;
+    currentDepth: number;
+  };
+  
+  // Control flow
+  isReturn: boolean;
+  isBreak: boolean;
+  
+  // Debugging
+  debug: boolean;
+  
+  // Import tracking
+  currentFile?: string;
+  importedFiles?: Set<string>;
+  
+  // Configuration reference
+  config: DiracConfig;
+}
+
+export interface DiracConfig {
+  apiKey?: string;
+  model?: string;
+  debug?: boolean;
+  maxLLMCalls?: number;
+  maxDepth?: number;
+  filePath?: string;  // Current file path for imports
+  customContext?: Record<string, any>;  // Custom context for browser integration
+  llmBackendUrl?: string;  // Backend URL for LLM calls (browser edition)
+}

package/src/utils/llm-adapter.ts

@@ -0,0 +1,118 @@
+/**
+ * LLM Adapter - Auto-generate prompts and JSON→XML converters
+ * from Dirac subroutine definitions
+ */
+
+import type { DiracSession } from '../types/index.js';
+import { getAvailableSubroutines } from '../runtime/session.js';
+
+export interface LLMPromptGenerator {
+  generatePrompt(userInput: string): string;
+  intentToXML(intent: any): string | null;
+  getAvailableActions(): string[];
+}
+
+/**
+ * Create LLM adapter from session's registered subroutines
+ */
+export function createLLMAdapter(session: DiracSession): LLMPromptGenerator {
+  const subroutines = getAvailableSubroutines(session);
+  
+  // Build JSON schema from subroutines
+  const actions = subroutines.map(s => `"${s.name}"`).join('|');
+  
+  // Build examples
+  const examples = subroutines.slice(0, 3).map(sub => {
+    if (!sub.parameters || sub.parameters.length === 0) {
+      return `"${sub.name}" → {"action":"${sub.name}","params":{}}`;
+    }
+    
+    const firstParam = sub.parameters[0];
+    const exampleValue = firstParam.enum?.[0] || 'value';
+    return `"call ${sub.name}" → {"action":"${sub.name}","params":{"${firstParam.name}":"${exampleValue}"}}`;
+  }).join('\n');
+  
+  return {
+    generatePrompt(userInput: string): string {
+      return `You are a command parser. Convert user input to JSON.
+Return ONLY valid JSON, no other text.
+
+Format: {"action": ${actions}, "params": {}}
+
+Examples:
+${examples}
+
+User: ${userInput}
+JSON:`;
+    },
+    
+    intentToXML(intent: any): string | null {
+      if (!intent || !intent.action) return null;
+      
+      const sub = subroutines.find(s => s.name === intent.action);
+      if (!sub) return null;
+      
+      const attrs: string[] = [`name="${sub.name}"`];
+      
+      // Map params to XML attributes
+      if (sub.parameters) {
+        for (const param of sub.parameters) {
+          const value = intent.params?.[param.name];
+          
+          if (value != null) {
+            // Validate enum if present
+            if (param.enum && !param.enum.includes(value)) {
+              return null;
+            }
+            attrs.push(`${param.name}="${value}"`);
+          } else if (param.required) {
+            return null; // Missing required parameter
+          }
+        }
+      }
+      
+      return `<call ${attrs.join(' ')}/>`;
+    },
+    
+    getAvailableActions(): string[] {
+      return subroutines.map(s => s.name);
+    }
+  };
+}
+
+/**
+ * Higher-level helper: execute user command via LLM
+ */
+export async function executeUserCommand(
+  session: DiracSession,
+  userInput: string,
+  llmExecuteFn: (prompt: string) => Promise<string>
+): Promise<{ success: boolean; xml?: string; error?: string }> {
+  try {
+    const adapter = createLLMAdapter(session);
+    const prompt = adapter.generatePrompt(userInput);
+    
+    // Call LLM
+    const llmResponse = await llmExecuteFn(prompt);
+    
+    // Parse JSON
+    let jsonStr = llmResponse.trim();
+    jsonStr = jsonStr.replace(/```json\s*/g, '').replace(/```\s*/g, '');
+    
+    const intent = JSON.parse(jsonStr);
+    
+    // Convert to XML
+    const xml = adapter.intentToXML(intent);
+    
+    if (!xml) {
+      return { success: false, error: 'Could not convert intent to valid command' };
+    }
+    
+    return { success: true, xml };
+  } catch (error) {
+    return { 
+      success: false, 
+      error: error instanceof Error ? error.message : String(error) 
+    };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}