dirac-lang 0.1.2

package/src/tags/parameters.ts

@@ -0,0 +1,79 @@
+/**
+ * <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<string | 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 and RETURN output
+    if (session.debug) {
+      console.error(`[PARAMETERS] Selecting all children (${caller.children.length} elements)`);
+    }
+    // Save current output buffer
+    const prevOutput = session.output;
+    session.output = [];
+    for (const child of caller.children) {
+      await integrate(session, child);
+    }
+    const captured = session.output.join('');
+    session.output = prevOutput;
+    return captured;
+  } 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) {
+        setVariable(session, attrName, value, false);
+        // Debug: print variable stack after setting
+        console.error(`[PARAMETERS] Variable stack after setting '${attrName}':`, JSON.stringify(session.variables));
+      }
+      for (const child of element.children) {
+        await integrate(session, child);
+      }
+    }
+    
+  } else {
+    throw new Error(`<parameters> invalid select: ${select}`);
+  }
+}

package/src/tags/require_module.ts

@@ -0,0 +1,19 @@
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { setVariable } from '../runtime/session.js';
+
+/**
+ * <require_module name="mongodb" var="mongo" />
+ * Loads a Node.js module and stores it in a session variable.
+ */
+export async function executeRequireModule(session: DiracSession, element: DiracElement): Promise<void> {
+  const name = element.attributes.name;
+  const varName = element.attributes.var || name;
+  if (!name) throw new Error('<require_module> missing name attribute');
+  try {
+    // Dynamically import the module (ESM compatible)
+    const mod = await import(name);
+    setVariable(session, varName, mod, true); // visible: true
+  } catch (err) {
+    throw new Error(`<require_module> failed to load module '${name}': ${err}`);
+  }
+}

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/system.ts

@@ -0,0 +1,70 @@
+/**
+ * <system> tag - Execute shell commands
+ * Spawns a Unix process and runs the command
+ */
+
+import type { DiracSession, DiracElement } from '../types/index.js';
+import { substituteVariables, emit } from '../runtime/session.js';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { integrate } from '../runtime/interpreter.js';
+
+const execAsync = promisify(exec);
+
+export async function executeSystem(session: DiracSession, element: DiracElement): Promise<void> {
+  // Build command from text content or children
+  let command: string;
+  
+  // Check if has non-text children (actual element children)
+  const hasElementChildren = element.children.some(child => child.tag !== '');
+  
+  if (hasElementChildren) {
+    // Execute children to build command dynamically
+    const beforeOutput = session.output.length;
+    
+    for (const child of element.children) {
+      await integrate(session, child);
+    }
+    
+    // Collect output from children as the command
+    const childOutput = session.output.slice(beforeOutput);
+    command = childOutput.join('');
+    
+    // Remove child output from main output
+    session.output = session.output.slice(0, beforeOutput);
+  } else if (element.text) {
+    // Simple text command with variable substitution
+    command = substituteVariables(session, element.text);
+  } else {
+    throw new Error('<system> requires command content');
+  }
+  
+  if (!command.trim()) {
+    return;
+  }
+  
+  if (session.debug) {
+    console.error(`[SYSTEM] Executing: ${command}`);
+  }
+  
+  try {
+    const { stdout, stderr } = await execAsync(command, {
+      encoding: 'utf-8',
+      maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+    });
+    
+    // Emit stdout
+    if (stdout) {
+      emit(session, stdout);
+    }
+    
+    // Emit stderr if debug mode
+    if (stderr && session.debug) {
+      console.error(`[SYSTEM STDERR] ${stderr}`);
+    }
+    
+  } catch (error: any) {
+    const errorMsg = error.message || String(error);
+    throw new Error(`System command failed: ${errorMsg}`);
+  }
+}

package/src/tags/variable.ts

@@ -0,0 +1,25 @@
+/**
+ * <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) {
+    // Debug: print the full element for diagnosis
+    console.error('[VariableTagError] <variable> tag missing name attribute:', JSON.stringify(element));
+    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,101 @@
+/**
+ * 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
+}
+
+/**
+ * Parameter metadata for introspection
+ */
+export interface ParameterMetadata {
+  name: string;
+  type?: string;
+  required?: boolean;
+  description?: string;
+  enum?: string[];
+}
+
+/**
+ * Subroutine info - maps to Subroutine in MASK
+ */
+export interface Subroutine {
+  name: string;
+  element: DiracElement;
+  boundary: number;  // scope boundary marker
+  extends?: string;  // parent subroutine
+  // Metadata for reflection/introspection
+  description?: string;
+  parameters?: ParameterMetadata[];
+}
+
+/**
+ * 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>;
+}
+
+export interface DiracConfig {
+  apiKey?: string;
+  model?: string;
+  debug?: boolean;
+  maxLLMCalls?: number;
+  maxDepth?: number;
+  filePath?: string;  // Current file path for imports
+  llmProvider?: string;
+  llmModel?: string;
+}

package/src/utils/llm-adapter.ts

@@ -0,0 +1,113 @@
+/**
+ * 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;
+}
+
+/**
+ * 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(' ')}/>`;
+    }
+  };
+}
+
+/**
+ * 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/tools/create-library.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+# Create a new Dirac library with proper structure
+
+if [ -z "$1" ]; then
+  echo "Usage: ./create-library.sh <library-name>"
+  echo "Example: ./create-library.sh crypto"
+  exit 1
+fi
+
+LIBNAME="$1"
+DIRNAME="dirac-$LIBNAME"
+LIBNAME_UPPER=$(echo "$LIBNAME" | tr '[:lower:]' '[:upper:]')
+
+echo "Creating Dirac library: $DIRNAME"
+echo "Prefix convention: ${LIBNAME_UPPER}_"
+echo ""
+
+# Create directory structure
+mkdir -p "$DIRNAME"/{lib,examples,tests}
+
+# Create package.json
+cat > "$DIRNAME/package.json" << EOF
+{
+  "name": "dirac-$LIBNAME",
+  "version": "0.1.0",
+  "description": "$LIBNAME library for Dirac",
+  "main": "lib/index.di",
+  "scripts": {
+    "test": "dirac tests/test.di",
+    "example": "dirac examples/demo.di"
+  },
+  "keywords": [
+    "dirac",
+    "$LIBNAME"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/dirac-$LIBNAME"
+  },
+  "dirac": {
+    "version": ">=0.1.0"
+  }
+}
+EOF
+
+# Create lib/index.di
+cat > "$DIRNAME/lib/index.di" << 'DIRAC_EOF'
+<dirac>
+
+<!-- All tags use the library prefix to avoid naming conflicts -->
+<subroutine name="LIBPREFIX_EXAMPLE">
+  <eval>
+    const caller = getParams();
+    const input = caller.attributes.input || 'no input';
+    console.log('Processed: ' + input);
+  </eval>
+</subroutine>
+
+</dirac>
+DIRAC_EOF
+
+# Replace the placeholder with actual library name
+sed -i '' "s/LIBPREFIX_/${LIBNAME_UPPER}_/g" "$DIRNAME/lib/index.di"
+
+# Create examples/demo.di
+cat > "$DIRNAME/examples/demo.di" << EOF
+#!/usr/bin/env dirac
+<dirac>
+  <import src="../lib/index.di"/>
+
+  <output>Demo:&#10;</output>
+  <${LIBNAME_UPPER}_EXAMPLE input="test"/>
+</dirac>
+EOF
+
+chmod +x "$DIRNAME/examples/demo.di"
+
+# Create tests/test.di
+cat > "$DIRNAME/tests/test.di" << 'EOF'
+#!/usr/bin/env dirac
+<dirac>
+  <import src="../lib/index.di"/>
+
+  <output>Running tests...&#10;</output>
+  <EXAMPLE input="test"/>
+  <output>Tests passed!&#10;</output>
+</dirac>
+EOF
+
+chmod +x "$DIRNAME/tests/test.di"
+
+# Create README.md
+cat > "$DIRNAME/README.md" << EOF
+# dirac-$LIBNAME
+
+$LIBNAME library for Dirac.
+
+## Installation
+
+\`\`\`bash
+npm install dirac-$LIBNAME
+\`\`\`
+
+## Usage
+
+\`\`\`xml
+<dirac>
+  <import src="./node_modules/dirac-$LIBNAME/lib/index.di"/>
+  
+  <EXAMPLE input="hello"/>
+</dirac>
+\`\`\`
+
+## API
+
+### EXAMPLE
+
+**Attributes:**
+- \`input\` (string) - Input text
+
+## Development
+
+\`\`\`bash
+# Run examples
+npm run example
+
+# Run tests
+npm test
+\`\`\`
+
+## License
+
+MIT
+EOF
+
+# Create .gitignore
+cat > "$DIRNAME/.gitignore" << 'EOF'
+node_modules/
+.DS_Store
+*.log
+EOF
+
+# Create LICENSE
+cat > "$DIRNAME/LICENSE" << 'EOF'
+MIT License
+
+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.
+EOF
+
+echo "✅ Library created: $DIRNAME/"
+echo ""
+echo "Next steps:"
+echo "  cd $DIRNAME"
+echo "  npm run example    # Test your library"
+echo "  npm test          # Run tests"
+echo "  git init          # Initialize git"
+echo "  npm publish       # Publish to npm"

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}