dirac-browser 0.1.1

package/dist/runtime/parser.js

@@ -0,0 +1,135 @@
+/**
+ * XML Parser for Dirac (.di files)
+ */
+import { XMLParser } from 'fast-xml-parser';
+export class DiracParser {
+    constructor() {
+        this.parser = new XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '@_',
+            trimValues: true,
+            parseAttributeValue: false,
+            parseTagValue: false,
+            textNodeName: '#text',
+            cdataPropName: '#cdata',
+            preserveOrder: true, // Preserve element order!
+            commentPropName: '#comment',
+        });
+    }
+    parse(source) {
+        // Strip shebang line if present
+        if (source.startsWith('#!')) {
+            source = source.replace(/^#!.*\n/, '');
+        }
+        const result = this.parser.parse(source);
+        // With preserveOrder, result is an array
+        if (!Array.isArray(result) || result.length === 0) {
+            throw new Error('Empty or invalid XML');
+        }
+        // Find the first non-comment element
+        for (const item of result) {
+            if (!item['#comment']) {
+                return this.convertOrderedToElement(item);
+            }
+        }
+        throw new Error('No root element found');
+    }
+    convertOrderedToElement(obj) {
+        // obj is like { "tagname": [...children], ":@": {...attributes} }
+        const tagName = Object.keys(obj).find(k => k !== ':@' && k !== '#comment');
+        if (!tagName) {
+            throw new Error('Invalid element structure');
+        }
+        const element = {
+            tag: tagName,
+            attributes: {},
+            children: [],
+        };
+        // Extract attributes
+        if (obj[':@']) {
+            for (const [key, value] of Object.entries(obj[':@'])) {
+                if (key.startsWith('@_')) {
+                    element.attributes[key.slice(2)] = value;
+                }
+            }
+        }
+        // Extract children
+        const children = obj[tagName];
+        if (Array.isArray(children)) {
+            for (const child of children) {
+                if (child['#text']) {
+                    // Text node - add as child AND to element.text for backward compat
+                    element.children.push({
+                        tag: '',
+                        text: child['#text'],
+                        attributes: {},
+                        children: []
+                    });
+                    // Also set element.text if not set (for simple text-only elements)
+                    if (!element.text) {
+                        element.text = child['#text'];
+                    }
+                    else {
+                        element.text += child['#text'];
+                    }
+                }
+                else if (child['#comment']) {
+                    // Skip comments
+                    continue;
+                }
+                else {
+                    // Child element
+                    element.children.push(this.convertOrderedToElement(child));
+                }
+            }
+        }
+        return element;
+    }
+    // Old method - no longer used
+    convertToElement(obj, tagName) {
+        if (!tagName) {
+            // Root level - find the actual tag
+            const keys = Object.keys(obj);
+            if (keys.length === 0) {
+                throw new Error('Empty XML');
+            }
+            tagName = keys[0];
+            obj = obj[tagName];
+        }
+        const element = {
+            tag: tagName,
+            attributes: {},
+            children: [],
+        };
+        if (typeof obj === 'string') {
+            element.text = obj;
+            return element;
+        }
+        if (!obj) {
+            return element;
+        }
+        // Extract attributes and children
+        for (const key of Object.keys(obj)) {
+            const value = obj[key];
+            if (key === '#text') {
+                element.text = value;
+            }
+            else if (key.startsWith('@_')) {
+                // Attribute
+                element.attributes[key.slice(2)] = value;
+            }
+            else {
+                // Child element
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        element.children.push(this.convertToElement(item, key));
+                    }
+                }
+                else {
+                    element.children.push(this.convertToElement(value, key));
+                }
+            }
+        }
+        return element;
+    }
+}

package/dist/runtime/session.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Session management - Browser edition (no LLM SDKs)
+ */
+import type { DiracSession, DiracConfig, DiracElement } from '../types/index.js';
+export declare function createSession(config?: DiracConfig): DiracSession;
+export declare function setVariable(session: DiracSession, name: string, value: any, visible?: boolean): void;
+export declare function getVariable(session: DiracSession, name: string): any;
+export declare function hasVariable(session: DiracSession, name: string): boolean;
+/**
+ * Set boundary marker for local variables
+ * Maps to var_info_set_boundary in MASK
+ */
+export declare function setBoundary(session: DiracSession): number;
+/**
+ * Pop variables back to boundary (cleanup local scope)
+ * Maps to var_info_pop_to_boundary in MASK
+ */
+export declare function popToBoundary(session: DiracSession): void;
+/**
+ * Clean private variables but keep visible ones
+ * Maps to var_info_clean_to_boundary in MASK
+ */
+export declare function cleanToBoundary(session: DiracSession): void;
+export declare function registerSubroutine(session: DiracSession, name: string, element: DiracElement, description?: string, parameters?: any[]): void;
+export declare function getSubroutine(session: DiracSession, name: string): DiracElement | undefined;
+export declare function setSubroutineBoundary(session: DiracSession): number;
+export declare function popSubroutinesToBoundary(session: DiracSession): void;
+export declare function cleanSubroutinesToBoundary(session: DiracSession): void;
+export declare function substituteVariables(session: DiracSession, text: string): string;
+export declare function emit(session: DiracSession, content: string): void;
+export declare function getOutput(session: DiracSession): string;
+/**
+ * Get all available subroutines for reflection
+ * Used by LLM adapter to auto-generate prompts
+ */
+export declare function getAvailableSubroutines(session: DiracSession): {
+    name: string;
+    description: string | undefined;
+    parameters: import("../types/index.js").ParameterMetadata[];
+}[];
+export declare function pushParameters(session: DiracSession, params: DiracElement[]): void;
+export declare function popParameters(session: DiracSession): DiracElement[] | undefined;
+export declare function getCurrentParameters(session: DiracSession): DiracElement[] | undefined;

package/dist/runtime/session.js

@@ -0,0 +1,171 @@
+/**
+ * Session management - Browser edition (no LLM SDKs)
+ */
+export function createSession(config = {}) {
+    // Browser version - no LLM client
+    let llmClient = null;
+    return {
+        variables: [],
+        subroutines: [],
+        varBoundary: 0,
+        subBoundary: 0,
+        parameterStack: [],
+        output: [],
+        llmClient,
+        limits: {
+            maxLLMCalls: config.maxLLMCalls || 100,
+            currentLLMCalls: 0,
+            maxDepth: config.maxDepth || 50,
+            currentDepth: 0,
+        },
+        isReturn: false,
+        isBreak: false,
+        debug: config.debug || false,
+        config, // Store config reference
+    };
+}
+// Variable management (maps to var_info functions in MASK)
+export function setVariable(session, name, value, visible = false) {
+    session.variables.push({
+        name,
+        value,
+        visible,
+        boundary: session.varBoundary,
+        passby: 'value',
+    });
+}
+export function getVariable(session, name) {
+    // Search from end (most recent) to beginning
+    for (let i = session.variables.length - 1; i >= 0; i--) {
+        if (session.variables[i].name === name) {
+            return session.variables[i].value;
+        }
+    }
+    return undefined;
+}
+export function hasVariable(session, name) {
+    return session.variables.some(v => v.name === name);
+}
+/**
+ * Set boundary marker for local variables
+ * Maps to var_info_set_boundary in MASK
+ */
+export function setBoundary(session) {
+    const oldBoundary = session.varBoundary;
+    session.varBoundary = session.variables.length;
+    return oldBoundary;
+}
+/**
+ * Pop variables back to boundary (cleanup local scope)
+ * Maps to var_info_pop_to_boundary in MASK
+ */
+export function popToBoundary(session) {
+    session.variables = session.variables.slice(0, session.varBoundary);
+}
+/**
+ * Clean private variables but keep visible ones
+ * Maps to var_info_clean_to_boundary in MASK
+ */
+export function cleanToBoundary(session) {
+    const kept = [];
+    for (let i = 0; i < session.varBoundary; i++) {
+        kept.push(session.variables[i]);
+    }
+    for (let i = session.varBoundary; i < session.variables.length; i++) {
+        if (session.variables[i].visible) {
+            kept.push(session.variables[i]);
+        }
+    }
+    session.variables = kept;
+    session.varBoundary = kept.length;
+}
+// Subroutine management (maps to subroutine functions in MASK)
+export function registerSubroutine(session, name, element, description, parameters) {
+    console.log(`📝 Registering subroutine: ${name}`, { description, paramCount: parameters?.length || 0 });
+    session.subroutines.push({
+        name,
+        element,
+        boundary: session.subBoundary,
+        description,
+        parameters,
+    });
+    console.log(`✅ Total subroutines registered: ${session.subroutines.length}`);
+}
+export function getSubroutine(session, name) {
+    console.log(`🔍 Looking up subroutine: ${name} (${session.subroutines.length} registered)`);
+    console.log('Available subroutines:', session.subroutines.map(s => s.name));
+    // Search from end (most recent) to beginning
+    for (let i = session.subroutines.length - 1; i >= 0; i--) {
+        if (session.subroutines[i].name === name) {
+            console.log(`✅ Found subroutine: ${name}`);
+            return session.subroutines[i].element;
+        }
+    }
+    console.log(`❌ Subroutine not found: ${name}`);
+    return undefined;
+}
+export function setSubroutineBoundary(session) {
+    const oldBoundary = session.subBoundary;
+    session.subBoundary = session.subroutines.length;
+    return oldBoundary;
+}
+export function popSubroutinesToBoundary(session) {
+    session.subroutines = session.subroutines.slice(0, session.subBoundary);
+}
+export function cleanSubroutinesToBoundary(session) {
+    // For now, same as pop (visibility not implemented for subroutines yet)
+    popSubroutinesToBoundary(session);
+}
+// Variable substitution (maps to var_replace functions in MASK)
+export function substituteVariables(session, text) {
+    // Decode HTML entities first
+    let decoded = text
+        .replace(/&#10;/g, '\n')
+        .replace(/&#13;/g, '\r')
+        .replace(/&#9;/g, '\t')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'");
+    // Substitute both ${var}/$var and {var} patterns
+    return decoded
+        .replace(/\$\{?(\w+)\}?/g, (match, varName) => {
+        const value = getVariable(session, varName);
+        return value !== undefined ? String(value) : match;
+    })
+        .replace(/\{(\w+)\}/g, (match, varName) => {
+        const value = getVariable(session, varName);
+        return value !== undefined ? String(value) : match;
+    });
+}
+// Output management
+export function emit(session, content) {
+    session.output.push(content);
+}
+export function getOutput(session) {
+    return session.output.join('');
+}
+/**
+ * Get all available subroutines for reflection
+ * Used by LLM adapter to auto-generate prompts
+ */
+export function getAvailableSubroutines(session) {
+    return session.subroutines
+        .filter(sub => sub.description || sub.parameters)
+        .map(sub => ({
+        name: sub.name,
+        description: sub.description,
+        parameters: sub.parameters || []
+    }));
+}
+// Parameter stack (for subroutine calls)
+export function pushParameters(session, params) {
+    session.parameterStack.push(params);
+}
+export function popParameters(session) {
+    return session.parameterStack.pop();
+}
+export function getCurrentParameters(session) {
+    return session.parameterStack[session.parameterStack.length - 1];
+}

package/dist/tags/assign.d.ts

@@ -0,0 +1,6 @@
+/**
+ * <assign> tag - assign value to existing variable
+ * Maps to mask_tag_assign in MASK
+ */
+import type { DiracSession, DiracElement } from '../types/index.js';
+export declare function executeAssign(session: DiracSession, element: DiracElement): void;

package/dist/tags/assign.js

@@ -0,0 +1,32 @@
+/**
+ * <assign> tag - assign value to existing variable
+ * Maps to mask_tag_assign in MASK
+ */
+import { setVariable, substituteVariables } from '../runtime/session.js';
+export function executeAssign(session, element) {
+    const name = element.attributes.name;
+    const valueAttr = element.attributes.value;
+    if (!name) {
+        throw new Error('<assign> requires name attribute');
+    }
+    // Get value
+    let value;
+    if (valueAttr !== undefined) {
+        value = substituteVariables(session, valueAttr);
+    }
+    else if (element.text) {
+        value = substituteVariables(session, element.text);
+    }
+    else {
+        value = '';
+    }
+    // Find existing variable and update it
+    for (let i = session.variables.length - 1; i >= 0; i--) {
+        if (session.variables[i].name === name) {
+            session.variables[i].value = value;
+            return;
+        }
+    }
+    // Variable not found - create it (same as MASK behavior)
+    setVariable(session, name, value, false);
+}

package/dist/tags/call.d.ts

@@ -0,0 +1,6 @@
+/**
+ * <call> tag - invoke subroutine
+ * Maps to mask_call_integrate in MASK
+ */
+import type { DiracSession, DiracElement } from '../types/index.js';
+export declare function executeCall(session: DiracSession, element: DiracElement): Promise<void>;

package/dist/tags/call.js

@@ -0,0 +1,130 @@
+/**
+ * <call> tag - invoke subroutine
+ * Maps to mask_call_integrate in MASK
+ */
+import { getSubroutine, setBoundary, cleanToBoundary, pushParameters, popParameters, substituteVariables, setVariable, getVariable, } from '../runtime/session.js';
+import { integrateChildren } from '../runtime/interpreter.js';
+export async function executeCall(session, element) {
+    // Support both <call name="FOO" /> and direct <FOO /> syntax
+    // For <call> tag, use name/subroutine attribute
+    // For direct syntax, use element.tag
+    let name;
+    if (element.tag === 'call') {
+        // Explicit <call> tag - use name or subroutine attribute
+        name = element.attributes.name || element.attributes.subroutine || '';
+    }
+    else {
+        // Direct tag syntax - use tag name itself, ignore name attribute
+        name = element.tag;
+    }
+    if (!name) {
+        throw new Error('<call> requires name or subroutine attribute');
+    }
+    const subroutine = getSubroutine(session, name);
+    if (!subroutine) {
+        throw new Error(`Subroutine '${name}' not found`);
+    }
+    // Handle extension (parent subroutine)
+    const extendsName = subroutine.attributes.extends;
+    if (extendsName) {
+        const parent = getSubroutine(session, extendsName);
+        if (parent) {
+            // Call parent first
+            await executeCallInternal(session, parent, element);
+        }
+    }
+    // Call this subroutine
+    await executeCallInternal(session, subroutine, element);
+}
+async function executeCallInternal(session, subroutine, callElement) {
+    // Set boundary for local scope
+    const oldBoundary = setBoundary(session);
+    const wasReturn = session.isReturn;
+    session.isReturn = false;
+    // Substitute variables in call element attributes before pushing to parameter stack
+    const substitutedElement = {
+        tag: callElement.tag,
+        attributes: {},
+        children: callElement.children
+    };
+    // Process each attribute for {variable} substitution
+    for (const [key, value] of Object.entries(callElement.attributes)) {
+        if (typeof value === 'string') {
+            substitutedElement.attributes[key] = substituteVariables(session, value);
+        }
+        else {
+            substitutedElement.attributes[key] = value;
+        }
+    }
+    // Push caller element onto parameter stack for <parameters select="*|@*|@attr"/> access
+    pushParameters(session, [substitutedElement]);
+    try {
+        // Bind call attributes as variables (for <call name="foo" x="1" y="2"/> style)
+        // This allows ${x} and ${y} to be used in the subroutine body
+        for (const [key, value] of Object.entries(substitutedElement.attributes)) {
+            // Skip special attributes
+            if (key === 'name' || key === 'subroutine')
+                continue;
+            // Set as local variable
+            setVariable(session, key, value, false);
+        }
+        // Bind parameters (for <call><parameters>...</parameters></call> style)
+        const paramElements = callElement.children.filter(c => c.tag === 'parameters');
+        if (paramElements.length > 0) {
+            await bindParameters(session, subroutine, paramElements[0]);
+        }
+        // Execute subroutine body
+        await integrateChildren(session, subroutine);
+    }
+    finally {
+        // Pop parameter stack
+        popParameters(session);
+        // Clean up scope (keep visible variables)
+        session.varBoundary = oldBoundary;
+        cleanToBoundary(session);
+        session.isReturn = wasReturn;
+    }
+}
+async function bindParameters(session, subroutine, callParams) {
+    // Find <parameters> definition in subroutine
+    const paramDef = subroutine.children.find(c => c.tag === 'parameters');
+    if (!paramDef) {
+        return; // No parameters defined
+    }
+    // Get variable definitions from parameter declaration
+    const paramVars = paramDef.children.filter(c => c.tag === 'variable');
+    const callVars = callParams.children.filter(c => c.tag === 'variable');
+    // Bind each parameter
+    for (let i = 0; i < paramVars.length; i++) {
+        const paramVar = paramVars[i];
+        const callVar = callVars[i];
+        const paramName = paramVar.attributes.name;
+        const passby = paramVar.attributes.passby || 'value';
+        if (!paramName)
+            continue;
+        let value;
+        if (callVar) {
+            // Get value from call site
+            const callValue = callVar.attributes.value;
+            if (callValue) {
+                if (passby === 'ref') {
+                    // Pass by reference - store variable name
+                    setVariable(session, paramName, getVariable(session, callValue), false);
+                    session.variables[session.variables.length - 1].passby = 'ref';
+                    session.variables[session.variables.length - 1].refName = callValue;
+                }
+                else {
+                    // Pass by value
+                    value = substituteVariables(session, callValue);
+                    setVariable(session, paramName, value, false);
+                }
+            }
+        }
+        else {
+            // No value provided - use default if available
+            const defaultValue = paramVar.attributes.default || '';
+            value = substituteVariables(session, defaultValue);
+            setVariable(session, paramName, value, false);
+        }
+    }
+}

package/dist/tags/defvar.d.ts

@@ -0,0 +1,6 @@
+/**
+ * <defvar> tag - define variable
+ * Maps to mask_tag_defvar in MASK
+ */
+import type { DiracSession, DiracElement } from '../types/index.js';
+export declare function executeDefvar(session: DiracSession, element: DiracElement): void;

package/dist/tags/defvar.js

@@ -0,0 +1,27 @@
+/**
+ * <defvar> tag - define variable
+ * Maps to mask_tag_defvar in MASK
+ */
+import { setVariable, substituteVariables } from '../runtime/session.js';
+export function executeDefvar(session, element) {
+    const name = element.attributes.name;
+    const valueAttr = element.attributes.value;
+    const visibleAttr = element.attributes.visible || 'false';
+    if (!name) {
+        throw new Error('<defvar> requires name attribute');
+    }
+    // Determine visibility
+    const visible = visibleAttr === 'true' || visibleAttr === 'variable' || visibleAttr === 'both';
+    // Get value (from attribute or text content)
+    let value;
+    if (valueAttr !== undefined) {
+        value = substituteVariables(session, valueAttr);
+    }
+    else if (element.text) {
+        value = substituteVariables(session, element.text);
+    }
+    else {
+        value = '';
+    }
+    setVariable(session, name, value, visible);
+}

package/dist/tags/eval.d.ts

@@ -0,0 +1,6 @@
+/**
+ * <eval> tag - evaluate JavaScript expression
+ * Maps to mask_tag_eval in MASK (but for JS, not C)
+ */
+import type { DiracSession, DiracElement } from '../types/index.js';
+export declare function executeEval(session: DiracSession, element: DiracElement): Promise<void>;

package/dist/tags/eval.js

@@ -0,0 +1,55 @@
+/**
+ * <eval> tag - evaluate JavaScript expression
+ * Maps to mask_tag_eval in MASK (but for JS, not C)
+ */
+import { setVariable } from '../runtime/session.js';
+// AsyncFunction constructor
+const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+export async function executeEval(session, element) {
+    const name = element.attributes.name;
+    const exprAttr = element.attributes.expr;
+    // Get expression - replace ${var} with var (will be passed as actual JS vars)
+    let expr;
+    if (exprAttr) {
+        expr = exprAttr.replace(/\$\{(\w+)\}/g, '$1');
+    }
+    else if (element.text) {
+        expr = element.text.replace(/\$\{(\w+)\}/g, '$1');
+    }
+    else {
+        throw new Error('<eval> requires expr attribute or text content');
+    }
+    if (session.debug) {
+        console.error(`[EVAL] Code after substitution:\n${expr}\n`);
+    }
+    try {
+        // Build context object with all variables
+        const context = {};
+        for (const v of session.variables) {
+            context[v.name] = v.value;
+        }
+        // Add customContext if provided (for Angular services, etc.)
+        if (session.config.customContext) {
+            Object.assign(context, session.config.customContext);
+        }
+        // Add helper to get current parameters from stack
+        context.getParams = () => {
+            const params = session.parameterStack[session.parameterStack.length - 1];
+            return params && params[0] ? params[0] : null;
+        };
+        let result;
+        // Execute as async function to support top-level await
+        const func = new AsyncFunction(...Object.keys(context), expr);
+        result = await func(...Object.values(context));
+        if (session.debug) {
+            console.error(`[EVAL] Result: ${JSON.stringify(result)}`);
+        }
+        // Store result if name provided
+        if (name) {
+            setVariable(session, name, result, false);
+        }
+    }
+    catch (error) {
+        throw new Error(`Eval error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/tags/execute.d.ts

@@ -0,0 +1,6 @@
+/**
+ * <execute> tag - Execute dynamically generated Dirac code
+ * Takes LLM-generated or variable content and interprets it as Dirac XML
+ */
+import type { DiracSession, DiracElement } from '../types/index.js';
+export declare function executeExecute(session: DiracSession, element: DiracElement): Promise<void>;

package/dist/tags/execute.js

@@ -0,0 +1,45 @@
+/**
+ * <execute> tag - Execute dynamically generated Dirac code
+ * Takes LLM-generated or variable content and interprets it as Dirac XML
+ */
+import { getVariable, substituteVariables } from '../runtime/session.js';
+import { DiracParser } from '../runtime/parser.js';
+import { integrate } from '../runtime/interpreter.js';
+export async function executeExecute(session, element) {
+    const sourceAttr = element.attributes.source;
+    // Get the Dirac code to execute
+    let diracCode;
+    if (sourceAttr) {
+        // Get from variable
+        diracCode = getVariable(session, sourceAttr);
+        if (!diracCode) {
+            throw new Error(`<execute> source variable '${sourceAttr}' not found`);
+        }
+    }
+    else if (element.text) {
+        // Get from text content (with variable substitution)
+        diracCode = substituteVariables(session, element.text);
+    }
+    else {
+        throw new Error('<execute> requires source attribute or text content');
+    }
+    if (session.debug) {
+        console.error(`[EXECUTE] Interpreting dynamic code:\n${diracCode}\n`);
+    }
+    // Strip markdown code blocks if present
+    diracCode = diracCode.trim();
+    if (diracCode.startsWith('```')) {
+        // Remove markdown code fences
+        diracCode = diracCode.replace(/^```(?:xml|html)?\n?/m, '').replace(/\n?```$/m, '').trim();
+    }
+    try {
+        // Parse the dynamic Dirac code
+        const parser = new DiracParser();
+        const dynamicAST = parser.parse(diracCode);
+        // Execute the dynamically generated code
+        await integrate(session, dynamicAST);
+    }
+    catch (error) {
+        throw new Error(`Execute error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}