producs 1.0.1 → 3.0.0

package/index.js

@@ -1,185 +1,1115 @@
+#!/usr/bin/env node
+"use strict";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+//  ProDucs  —  Professional Documentation Shell DSL  v3.0
+//
+//  Pipe syntax:  #$Cmd1 | #$Cmd2 | #$Cmd3
+//  Block syntax: #$Block['arg']  …  #$End_Block
+//  Variables:    ${name}
+//  Comments:     // line comment
+//
+//  Branching model (no If/Else):
+//    #$Set['x','10']
+//    #$Check_gt['x','5']   ← sets failed=0 (pass) or failed=1 (fail)
+//    #$Branch               ← runs children only when failed=0
+//      #$Print['x is > 5']
+//    #$End_Branch
+//    #$BranchElse           ← runs children only when failed=1
+//      #$Print['x is not > 5']
+//    #$End_BranchElse
+// ═══════════════════════════════════════════════════════════════════════════════
+
 const { execSync } = require("child_process");
-const prompt = require("prompt-sync")({ sigint: true });
+const crypto = require("crypto");
+const fs     = require("fs");
 
-class ProDucs {
-  constructor() {
-    this.commands = {
-      ">": (text, value, promptText = "") => {
-        const result = prompt(promptText || text || "");
-        return { VALUE: result, failed: result ? 0 : 1 };
-      },
-      Check_equals: (text, value, expected) => ({
-        VALUE: value.VALUE,
-        failed: value.VALUE === expected ? 0 : 1
-      }),
-      Check_failed_error: (text, value, msg) => {
-        if (value.failed) throw new Error(msg || "Check failed!");
-        return value;
-      },
-      Shell_run: (text, value) => {
-        execSync(value.VALUE, { stdio: "inherit" });
-        return { VALUE: value.VALUE, failed: 0 };
-      },
-      Text: (text, value, str) => ({ VALUE: str || text, failed: 0 })
-    };
-  }
-
-  // ──────────────────────────── TOKENIZER ────────────────────────────
-  tokenize(src) {
-    const tokens = [];
-    let i = 0;
-    const peek = () => src[i];
-    const next = () => src[i++];
-    const eof = () => i >= src.length;
-    const skipSpaces = () => { while (!eof() && /\s/.test(peek())) next(); };
-
-    const readIdent = () => {
-      let name = "";
-      while (!eof() && /[A-Za-z0-9_>]/.test(peek())) name += next();
-      return name;
-    };
-
-    const readArgs = () => {
-      const args = [];
-      let buf = "";
-      if (peek() === "[") {
-        next();
-        while (!eof()) {
-          const c = next();
-          if (c === "]") break;
-          if (c === ",") {
-            args.push(buf.trim().replace(/^'|'$/g, ""));
-            buf = "";
-          } else buf += c;
-        }
-        if (buf.trim()) args.push(buf.trim().replace(/^'|'$/g, ""));
-      }
-      return args;
-    };
+let promptSync;
+try { promptSync = require("prompt-sync")({ sigint: true }); }
+catch { promptSync = (msg) => { process.stdout.write(msg || ""); return ""; }; }
+
+// ─── ANSI ─────────────────────────────────────────────────────────────────────
+const C = {
+  reset:"\x1b[0m", bold:"\x1b[1m", dim:"\x1b[2m",
+  red:"\x1b[31m",  green:"\x1b[32m", yellow:"\x1b[33m",
+  blue:"\x1b[34m", cyan:"\x1b[36m",  white:"\x1b[37m",
+  bgred:"\x1b[41m",bggreen:"\x1b[42m",bgblue:"\x1b[44m",
+};
+
+// ─── JS reserved words (must not be injected as var names) ────────────────────
+const RESERVED_JS = new Set([
+  "break","case","catch","class","const","continue","debugger","default",
+  "delete","do","else","export","extends","finally","for","function","if",
+  "import","in","instanceof","let","new","return","static","super","switch",
+  "this","throw","try","typeof","var","void","while","with","yield",
+  "enum","await","null","true","false","undefined","NaN","Infinity",
+  "constructor","prototype","__proto__",
+]);
+
+// ─── Result ───────────────────────────────────────────────────────────────────
+const mkResult   = (VALUE="", failed=0, meta={}) =>
+  ({ VALUE: String(VALUE ?? ""), failed: Number(failed), ...meta });
+const okResult   = (VALUE="", meta={}) => mkResult(VALUE, 0, meta);
+const failResult = (VALUE="", meta={}) => mkResult(VALUE, 1, meta);
+
+const out = (s) => process.stdout.write(s);
+const err = (s) => process.stderr.write(s);
+const pad = (s, n) => String(s).padEnd(n).slice(0, n);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+//  ERRORS
+// ═══════════════════════════════════════════════════════════════════════════════
+class ProDucsError extends Error {
+  constructor(msg, loc) {
+    super(loc ? `[${loc.line}:${loc.col}] ${msg}` : msg);
+    this.name = "ProDucsError";
+    this.loc  = loc;
+  }
+}
+class GotoSignal {
+  constructor(label) { this.label = label; }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+//  RUNTIME ENV  (per-instance)
+// ═══════════════════════════════════════════════════════════════════════════════
+class RuntimeEnv {
+  constructor() { this.reset(); }
+
+  reset() {
+    this.vars     = {};
+    this.labels   = {};   // name → { node, list }  — list is the actual array
+    this.log      = [];
+    this.stepNum  = 0;
+    this.startMs  = Date.now();
+    this.debug    = false;
+    this.strict   = false;
+    this.colorOff = false;
+  }
+
+  col(code, s) { return this.colorOff ? s : `${code}${s}${C.reset}`; }
+  bold(s)      { return this.col(C.bold, s); }
+  dim(s)       { return this.col(C.dim,  s); }
+  cyan(s)      { return this.col(C.cyan, s); }
+  green(s)     { return this.col(C.green,s); }
+  red(s)       { return this.col(C.red,  s); }
+  yellow(s)    { return this.col(C.yellow,s);}
+  blue(s)      { return this.col(C.blue, s); }
+
+  termW()      { return process.stdout.columns || 80; }
+  hr(ch="─")   { return ch.repeat(this.termW()); }
+
+  interpolate(str) {
+    return String(str ?? "").replace(/\$\{([^}]+)\}/g, (_, k) => this.vars[k] ?? "");
+  }
+
+  /** Produce safe `var x = "val";` bindings for new Function, skipping reserved names */
+  safeBindings(extra = {}) {
+    const SAFE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+    return Object.entries({ ...this.vars, ...extra })
+      .filter(([k]) => SAFE.test(k) && !RESERVED_JS.has(k))
+      .map(([k, v]) => {
+        const n = Number(v);
+        const val = (v !== "" && !isNaN(n)) ? n : JSON.stringify(String(v));
+        return `var ${k} = ${val};`;
+      })
+      .join("\n");
+  }
+
+  logEntry(cmd, msg, ok=true) {
+    this.log.push({ t: Date.now() - this.startMs, cmd, msg, ok });
+    if (this.debug) err(this.dim(`[DBG] ${cmd}: ${msg}`) + "\n");
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+//  TOKENIZER
+// ═══════════════════════════════════════════════════════════════════════════════
+class Tokenizer {
+  constructor(src) { this.src=src; this.i=0; this.line=1; this.col=1; }
 
-    while (!eof()) {
-      skipSpaces();
+  peek(n=0) { return this.src[this.i+n]; }
+  eof()     { return this.i >= this.src.length; }
+  next() {
+    const c = this.src[this.i++];
+    if (c==="\n") { this.line++; this.col=1; } else this.col++;
+    return c;
+  }
+  skipSpaces() { while (!this.eof() && /[ \t\r\n]/.test(this.peek())) this.next(); }
+
+  readIdent() {
+    let s="";
+    while (!this.eof() && /[A-Za-z0-9_>!]/.test(this.peek())) s += this.next();
+    return s;
+  }
+
+  /** Read [...] args supporting single-quote, double-quote, or bare words */
+  readArgs() {
+    if (this.peek() !== "[") return [];
+    this.next();
+    const args=[]; let buf="", inQ=null, wasQ=false;
+    while (!this.eof()) {
+      const c = this.peek();
+      if (!inQ && (c==="'" || c==='"'))  { inQ=c; wasQ=true; this.next(); continue; }
+      if (inQ  && c===inQ)               { inQ=null; this.next(); continue; }
+      if (!inQ && c===",") {
+        args.push(wasQ ? buf : buf.trim());
+        buf=""; wasQ=false; this.next(); continue;
+      }
+      if (!inQ && c==="]") { this.next(); break; }
+      buf += this.next();
+    }
+    // push last arg: if quoted preserve spaces, else trim; skip if empty bare word
+    if (wasQ || buf.trim()) args.push(wasQ ? buf : buf.trim());
+    return args;
+  }
 
-      if (peek() === "#" && src[i + 1] === "$") {
-        i += 2;
-        if (src.startsWith("End_", i)) {
-          i += 4;
-          const name = readIdent();
-          tokens.push({ type: "COMMAND_END", name });
+  tokenize() {
+    const tokens=[];
+    while (!this.eof()) {
+      // line comment
+      if (this.peek()==="/" && this.peek(1)==="/") {
+        while (!this.eof() && this.peek()!=="\n") this.next();
+        continue;
+      }
+      // explicit pipe  |  (not ||)
+      if (this.peek()==="|" && this.peek(1)!=="|") {
+        const loc={line:this.line,col:this.col};
+        this.next(); this.skipSpaces();
+        tokens.push({type:"PIPE",loc});
+        continue;
+      }
+      // command  #$…
+      if (this.peek()==="#" && this.peek(1)==="$") {
+        this.next(); this.next();
+        const loc={line:this.line,col:this.col};
+        if (this.src.startsWith("End_", this.i)) {
+          this.i+=4;
+          tokens.push({type:"COMMAND_END", name:this.readIdent(), loc});
         } else {
-          const name = readIdent();
-          const args = readArgs();
-          tokens.push({ type: "COMMAND_START", name, args });
+          const name=this.readIdent(), args=this.readArgs();
+          tokens.push({type:"COMMAND_START", name, args, loc});
         }
-      } else {
-        let text = "";
-        while (!eof() && !(peek() === "#" && src[i + 1] === "$")) text += next();
-        if (text.trim()) tokens.push({ type: "TEXT", value: text.trim() });
+        continue;
+      }
+      // raw text
+      let text="";
+      const loc={line:this.line,col:this.col};
+      while (!this.eof()
+        && !(this.peek()==="#" && this.peek(1)==="$")
+        && !(this.peek()==="/" && this.peek(1)==="/")
+        && !(this.peek()==="|" && this.peek(1)!=="|")) {
+        text += this.next();
       }
+      const trimmed=text.trim();
+      if (trimmed) tokens.push({type:"TEXT", value:trimmed, loc});
     }
-
     return tokens;
   }
+}
 
-  // ──────────────────────────── PARSER ────────────────────────────
-  parse(tokens) {
-    const root = [];
-    const stack = [];
-
-    for (let i = 0; i < tokens.length; i++) {
-      const token = tokens[i];
-
-      if (token.type === "COMMAND_START") {
-        const node = {
-          type: token.name,
-          args: token.args,
-          children: [],
-          pipedCommands: []
-        };
-
-        // Inline (pipe) commands
-        if (stack.length && !token.name.startsWith("End_")) {
-          const parent = stack.at(-1);
-          if (parent.type === ">" || parent.pipedCommands.length) {
-            parent.pipedCommands.push(node);
-            continue;
-          }
-        }
+// ═══════════════════════════════════════════════════════════════════════════════
+//  PARSER
+// ═══════════════════════════════════════════════════════════════════════════════
+class Parser {
+  constructor(tokens) { this.tokens=tokens; this.pos=0; }
 
-        // Block commands
-        stack.push(node);
+  // Block commands: opened with #$X, closed with #$End_X
+  // Children are collected between open/close.
+  // Everything else is inline (pipeable).
+  static BLOCK_CMDS = new Set([
+    ">", "Branch", "BranchElse",
+    "Repeat", "ForEach",
+    "Try", "Catch",
+    "Section", "Step", "Group", "Table",
+  ]);
 
-      } else if (token.type === "COMMAND_END") {
-        const last = stack.pop();
+  peek()  { return this.tokens[this.pos]; }
+  eof()   { return this.pos >= this.tokens.length; }
+  mkNode(tok) {
+    return { type:tok.name, args:tok.args, loc:tok.loc, children:[], pipes:[] };
+  }
+
+  collectPipes(head) {
+    while (!this.eof() && this.peek().type==="PIPE") {
+      const pipeTok = this.tokens[this.pos++];
+      const next    = this.peek();
+      if (!next || next.type!=="COMMAND_START")
+        throw new SyntaxError(`[${pipeTok.loc.line}:${pipeTok.loc.col}] Expected command after |`);
+      if (Parser.BLOCK_CMDS.has(next.name))
+        throw new SyntaxError(`[${next.loc.line}:${next.loc.col}] Block command '${next.name}' cannot be piped`);
+      this.pos++;
+      head.pipes.push(this.mkNode(next));
+    }
+  }
+
+  parse() {
+    const root=[], stack=[];
+    while (!this.eof()) {
+      const tok = this.tokens[this.pos++];
+
+      if (tok.type==="TEXT") {
+        const node={type:"Text", value:tok.value, loc:tok.loc};
+        (stack.length ? stack.at(-1).children : root).push(node);
+        continue;
+      }
+      if (tok.type==="PIPE")
+        throw new SyntaxError(`[${tok.loc.line}:${tok.loc.col}] Unexpected | — must follow a command`);
+
+      if (tok.type==="COMMAND_END") {
+        const last=stack.pop();
         if (!last)
-          throw new Error(`Unexpected #$End_${token.name}`);
-        if (last.type !== token.name)
-          throw new Error(`Mismatched end: expected #$End_${last.type}, got #$End_${token.name}`);
-        if (stack.length) stack.at(-1).children.push(last);
-        else root.push(last);
-      } else if (token.type === "TEXT") {
-        const node = { type: "Text", value: token.value };
-        if (stack.length) stack.at(-1).children.push(node);
-        else root.push(node);
+          throw new SyntaxError(`[${tok.loc.line}:${tok.loc.col}] Unexpected #$End_${tok.name}`);
+        if (last.type!==tok.name)
+          throw new SyntaxError(`[${tok.loc.line}:${tok.loc.col}] Mismatched: expected #$End_${last.type}, got #$End_${tok.name}`);
+        (stack.length ? stack.at(-1).children : root).push(last);
+        continue;
       }
-    }
 
-    if (stack.length) throw new Error(`Unclosed command: ${stack.at(-1).type}`);
+      if (tok.type==="COMMAND_START") {
+        const node=this.mkNode(tok);
+        if (Parser.BLOCK_CMDS.has(tok.name)) {
+          stack.push(node);
+        } else {
+          this.collectPipes(node);
+          (stack.length ? stack.at(-1).children : root).push(node);
+        }
+      }
+    }
+    if (stack.length)
+      throw new SyntaxError(`Unclosed: #$${stack.at(-1).type} at line ${stack.at(-1).loc?.line}`);
     return root;
   }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+//  COMMAND REGISTRY
+// ═══════════════════════════════════════════════════════════════════════════════
+class CommandRegistry {
+  constructor(env) { this.env=env; this._cmds=new Map(); this._registerAll(); }
 
-  astify(text) {
-    return this.parse(this.tokenize(text));
+  register(name, fn, meta={}) { this._cmds.set(name,{fn,...meta}); return this; }
+  get(name)  { return this._cmds.get(name); }
+  has(name)  { return this._cmds.has(name); }
+  list()     { return [...this._cmds.keys()].sort(); }
+
+  resolveText(node) {
+    const tc=node.children?.find(c=>c.type==="Text");
+    return tc ? this.env.interpolate(tc.value) : "";
   }
+  resolveArg(a)     { return this.env.interpolate(a ?? ""); }
+  resolveArgs(args) { return (args||[]).map(a=>this.resolveArg(a)); }
 
-  // ──────────────────────────── EXECUTION ────────────────────────────
-  executeNode(node, input = { VALUE: "", failed: 0 }) {
-    // Handle text nodes directly
-    if (node.type === "Text")
-      return { VALUE: console.log(node.value), failed: 0 };
+  // Safe expression evaluator — vars injected via safeBindings
+  evalExpr(expr, extra={}) {
+    const bindings = this.env.safeBindings(extra);
+    // eslint-disable-next-line no-new-func
+    return new Function(`"use strict";\n${bindings}\nreturn (${expr});`)();
+  }
 
-    const cmd = this.commands[node.type];
-    if (!cmd) throw new Error(`Unknown command: ${node.type}`);
+  // Coerce a value from env.vars to a number for comparisons
+  numVar(name) {
+    const v = this.env.vars[name];
+    if (v === undefined) throw new ProDucsError(`Variable not found: ${name}`);
+    const n = Number(v);
+    if (isNaN(n)) throw new ProDucsError(`Variable '${name}' = '${v}' is not numeric`);
+    return n;
+  }
 
-    // Get the first text child as `text`
-    const textChild = node.children.find(c => c.type === "Text");
-    const text = textChild ? textChild.value : "";
+  _registerAll() {
+    const env=this.env, R=this;
+    const itp =(s)    => env.interpolate(s);
+    const rA  =(args) => R.resolveArgs(args);
+    const rT  =(node) => R.resolveText(node);
 
-    // Base execution (text, value, ...args)
-    let current = cmd(text, input, ...node.args);
+    // ══════════════════════════════════════════════════════════════════════════
+    //  I / O
+    // ══════════════════════════════════════════════════════════════════════════
 
-    // Inline piped commands
-    for (const pipe of node.pipedCommands) {
-      const fn = this.commands[pipe.type];
-      if (!fn) throw new Error(`Unknown piped command: ${pipe.type}`);
-      const pipeText = pipe.children.find(c => c.type === "Text")?.value || "";
-      current = fn(pipeText, current, ...pipe.args);
-    }
+    R.register(">", (node,input) => {
+      const [promptText=""] = rA(node.args);
+      const msg = promptText || rT(node) || "";
+      const val = promptSync(msg ? env.cyan(msg)+" " : "");
+      if (val===null) throw new Error("Aborted (Ctrl-C)");
+      return val.trim() ? okResult(val.trim()) : failResult("",{reason:"empty"});
+    }, { doc:"Prompt user for input" });
 
-    // Block children
-    for (const child of node.children) {
-      if (child.type !== "Text") current = this.executeNode(child, current);
-    }
+    R.register("Print", (node,input) => {
+      const [str=""] = rA(node.args);
+      const msg = node.args.length > 0 ? str : (rT(node) || input.VALUE);
+      out(msg+"\n"); return okResult(msg);
+    }, { doc:"Print arg or VALUE to stdout" });
 
-    return current;
+    R.register("Warn", (node,input) => {
+      const [str=""] = rA(node.args);
+      const msg = str || input.VALUE;
+      err(env.yellow("⚠ WARN: "+msg)+"\n");
+      return mkResult(msg,1);
+    }, { doc:"Print yellow warning to stderr (sets failed=1)" });
+
+    R.register("Error_print", (node,input) => {
+      const [str=""] = rA(node.args);
+      const msg = str || input.VALUE;
+      err(env.red("✖ ERROR: "+msg)+"\n");
+      return failResult(msg);
+    }, { doc:"Print red error to stderr" });
+
+    R.register("Pause", (node,input) => {
+      const [msg="Press ENTER to continue…"] = rA(node.args);
+      promptSync(env.dim(msg)); return okResult(input.VALUE);
+    }, { doc:"Block until ENTER pressed" });
+
+    R.register("Input", (node,input) => {
+      const [promptText=""] = rA(node.args);
+      const val = promptSync(promptText ? env.cyan(promptText)+" " : "");
+      if (val===null) throw new Error("Aborted (Ctrl-C)");
+      return val.trim() ? okResult(val.trim()) : failResult("",{reason:"empty"});
+    }, { doc:"Input['prompt'] — prompt for input, pipeable inline (VALUE = trimmed input)" });
+
+    R.register("Confirm", (node,input) => {
+      const [msg="Continue?",def="y"] = rA(node.args);
+      const ans = promptSync(env.cyan(msg)+env.dim(` [${def==="y"?"Y/n":"y/N"}] `)) || def;
+      return mkResult(ans.trim(), /^y(es)?$/i.test(ans.trim()) ? 0 : 1);
+    }, { doc:"y/n prompt — Confirm['message','default']" });
+
+    R.register("Select", (node,input) => {
+      const [label="Choose",...opts] = rA(node.args);
+      out(env.bold(label)+"\n");
+      opts.forEach((o,i)=>out(`  ${env.cyan(String(i+1))}. ${o}\n`));
+      const ans = promptSync(env.dim("Enter number: ")) || "";
+      const idx = parseInt(ans.trim(),10)-1;
+      return (idx<0||idx>=opts.length) ? failResult(ans,{reason:"invalid"}) : okResult(opts[idx]);
+    }, { doc:"Select['label','opt1','opt2',...] — numbered menu" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  VARIABLES
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Set", (node,input) => {
+      const [name,val=""] = rA(node.args);
+      if (!name) return failResult(input.VALUE,{reason:"Set requires a name"});
+      const value = val!=="" ? val : input.VALUE;
+      env.vars[name]=value;
+      env.logEntry("Set",`${name}=${value}`);
+      return okResult(value);
+    }, { doc:"Set['name','value'] or pipe VALUE into variable" });
+
+    R.register("Unset", (node,input) => {
+      const [name=""] = rA(node.args);
+      delete env.vars[name]; return okResult(input.VALUE);
+    }, { doc:"Delete a variable" });
+
+    R.register("Export", (node,input) => {
+      const [name,val=""] = rA(node.args);
+      const value = val!=="" ? val : input.VALUE;
+      process.env[name]=value; env.vars[name]=value;
+      return okResult(value);
+    }, { doc:"Export variable to process.env" });
+
+    R.register("Env_get", (node,input) => {
+      const [key=""] = rA(node.args);
+      const val = process.env[key] ?? "";
+      return val ? okResult(val) : failResult("",{reason:`env ${key} not set`});
+    }, { doc:"Get a process.env variable → VALUE" });
+
+    R.register("Env_set", (node,input) => {
+      const [key=""] = rA(node.args);
+      process.env[key]=input.VALUE; return okResult(input.VALUE);
+    }, { doc:"Set process.env[key] = VALUE" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  CHECKS  — all set failed=0 (pass) or failed=1 (fail)
+    //  String checks operate on VALUE.
+    //  Numeric / variable checks take variable names as args.
+    // ══════════════════════════════════════════════════════════════════════════
+
+    // ── String checks (on VALUE) ──────────────────────────────────────────────
+
+    R.register("Check_eq", (node,input) => {
+      const [expected=""] = rA(node.args);
+      const ok = input.VALUE === expected;
+      env.logEntry("Check_eq",`"${input.VALUE}" === "${expected}" → ${ok}`);
+      return mkResult(input.VALUE, ok?0:1);
+    }, { doc:"Pass if VALUE === arg[0]" });
+
+    R.register("Check_neq", (node,input) => {
+      const [expected=""] = rA(node.args);
+      return mkResult(input.VALUE, input.VALUE!==expected?0:1);
+    }, { doc:"Pass if VALUE !== arg[0]" });
+
+    R.register("Check_contains", (node,input) => {
+      const [needle=""] = rA(node.args);
+      return mkResult(input.VALUE, input.VALUE.includes(needle)?0:1);
+    }, { doc:"Pass if VALUE contains arg[0]" });
+
+    R.register("Check_not_contains", (node,input) => {
+      const [needle=""] = rA(node.args);
+      return mkResult(input.VALUE, !input.VALUE.includes(needle)?0:1);
+    }, { doc:"Pass if VALUE does NOT contain arg[0]" });
+
+    R.register("Check_starts", (node,input) => {
+      const [prefix=""] = rA(node.args);
+      return mkResult(input.VALUE, input.VALUE.startsWith(prefix)?0:1);
+    }, { doc:"Pass if VALUE starts with arg[0]" });
+
+    R.register("Check_ends", (node,input) => {
+      const [suffix=""] = rA(node.args);
+      return mkResult(input.VALUE, input.VALUE.endsWith(suffix)?0:1);
+    }, { doc:"Pass if VALUE ends with arg[0]" });
+
+    R.register("Check_matches", (node,input) => {
+      const [pattern=".*",flags=""] = rA(node.args);
+      return mkResult(input.VALUE, new RegExp(pattern,flags).test(input.VALUE)?0:1);
+    }, { doc:"Pass if VALUE matches regex arg[0]" });
+
+    R.register("Check_empty", (node,input) => {
+      return mkResult(input.VALUE, input.VALUE===""?0:1);
+    }, { doc:"Pass if VALUE is empty string" });
+
+    R.register("Check_nonempty", (node,input) => {
+      return mkResult(input.VALUE, input.VALUE!==""?0:1);
+    }, { doc:"Pass if VALUE is not empty" });
+
+    // ── Numeric checks (arg = variable name, compared against a literal) ──────
+
+    R.register("Check_gt", (node,input) => {
+      // Check_gt['varname','number']  OR  Check_gt['number'] (uses VALUE as number)
+      const [a,b] = rA(node.args);
+      if (b!==undefined) {
+        const left=Number(env.vars[a]??a), right=Number(b);
+        return mkResult(input.VALUE, left>right?0:1);
+      }
+      return mkResult(input.VALUE, Number(input.VALUE)>Number(a)?0:1);
+    }, { doc:"Pass if var/VALUE > number  — Check_gt['var','n'] or Check_gt['n']" });
+
+    R.register("Check_gte", (node,input) => {
+      const [a,b] = rA(node.args);
+      if (b!==undefined) {
+        return mkResult(input.VALUE, Number(env.vars[a]??a)>=Number(b)?0:1);
+      }
+      return mkResult(input.VALUE, Number(input.VALUE)>=Number(a)?0:1);
+    }, { doc:"Pass if var/VALUE >= number" });
+
+    R.register("Check_lt", (node,input) => {
+      const [a,b] = rA(node.args);
+      if (b!==undefined) {
+        return mkResult(input.VALUE, Number(env.vars[a]??a)<Number(b)?0:1);
+      }
+      return mkResult(input.VALUE, Number(input.VALUE)<Number(a)?0:1);
+    }, { doc:"Pass if var/VALUE < number" });
+
+    R.register("Check_lte", (node,input) => {
+      const [a,b] = rA(node.args);
+      if (b!==undefined) {
+        return mkResult(input.VALUE, Number(env.vars[a]??a)<=Number(b)?0:1);
+      }
+      return mkResult(input.VALUE, Number(input.VALUE)<=Number(a)?0:1);
+    }, { doc:"Pass if var/VALUE <= number" });
+
+    R.register("Check_num_eq", (node,input) => {
+      const [a,b] = rA(node.args);
+      if (b!==undefined) {
+        return mkResult(input.VALUE, Number(env.vars[a]??a)===Number(b)?0:1);
+      }
+      return mkResult(input.VALUE, Number(input.VALUE)===Number(a)?0:1);
+    }, { doc:"Pass if var/VALUE == number (numeric equality)" });
+
+    R.register("Check_num_neq", (node,input) => {
+      const [a,b] = rA(node.args);
+      if (b!==undefined) {
+        return mkResult(input.VALUE, Number(env.vars[a]??a)!==Number(b)?0:1);
+      }
+      return mkResult(input.VALUE, Number(input.VALUE)!==Number(a)?0:1);
+    }, { doc:"Pass if var/VALUE != number" });
+
+    R.register("Check_between", (node,input) => {
+      const [a,lo,hi] = rA(node.args);
+      if (lo!==undefined && hi!==undefined) {
+        const v=Number(env.vars[a]??a);
+        return mkResult(input.VALUE, v>=Number(lo)&&v<=Number(hi)?0:1);
+      }
+      const v=Number(input.VALUE);
+      return mkResult(input.VALUE, v>=Number(a)&&v<=Number(lo)?0:1);
+    }, { doc:"Pass if var/VALUE between lo and hi (inclusive) — Check_between['var','lo','hi']" });
+
+    // ── Boolean / logical checks ──────────────────────────────────────────────
+
+    R.register("Check_failed", (node,input) => {
+      return mkResult(input.VALUE, input.failed?0:1);
+    }, { doc:"Pass if previous result was failed" });
+
+    R.register("Check_passed", (node,input) => {
+      return mkResult(input.VALUE, !input.failed?0:1);
+    }, { doc:"Pass if previous result was passed" });
+
+    R.register("Check_var_eq", (node,input) => {
+      // Compare two variables by name
+      const [a,b] = rA(node.args);
+      return mkResult(input.VALUE, (env.vars[a]??"")===(env.vars[b]??"")?0:1);
+    }, { doc:"Pass if var a === var b — Check_var_eq['a','b']" });
+
+    R.register("Check_var_neq", (node,input) => {
+      const [a,b] = rA(node.args);
+      return mkResult(input.VALUE, (env.vars[a]??"")===(env.vars[b]??"")?1:0);
+    }, { doc:"Pass if var a !== var b" });
+
+    // ── Error gates ───────────────────────────────────────────────────────────
+
+    R.register("Check_failed_error", (node,input) => {
+      const [msg="Check failed"] = rA(node.args);
+      if (input.failed) throw new ProDucsError(msg, node.loc);
+      return input;
+    }, { doc:"Throw if previous result is failed" });
+
+    R.register("Check_passed_error", (node,input) => {
+      const [msg="Unexpected pass"] = rA(node.args);
+      if (!input.failed) throw new ProDucsError(msg, node.loc);
+      return input;
+    }, { doc:"Throw if previous result passed" });
+
+    // ── Assert (arbitrary JS expression using vars) ───────────────────────────
+    R.register("Assert", (node,input) => {
+      const [expr="",msg="Assertion failed"] = rA(node.args);
+      try {
+        const ok = R.evalExpr(expr, {VALUE:input.VALUE});
+        if (!ok) throw new ProDucsError(msg, node.loc);
+        return input;
+      } catch(e) {
+        if (e instanceof ProDucsError) throw e;
+        throw new ProDucsError(`Assert eval error: ${e.message}`, node.loc);
+      }
+    }, { doc:"Assert['JS expr','msg'] — throw if expression is falsy" });
+
+    // ── Guards ────────────────────────────────────────────────────────────────
+    R.register("Require_env", (node,input) => {
+      const [key=""] = rA(node.args);
+      if (!process.env[key])
+        throw new ProDucsError(`Required env var not set: ${key}`, node.loc);
+      return okResult(process.env[key]);
+    }, { doc:"Halt if env var is missing" });
+
+    R.register("Require_cmd", (node,input) => {
+      const [cmd=""] = rA(node.args);
+      try { execSync(`command -v ${cmd}`,{stdio:"ignore"}); return okResult(cmd); }
+      catch { throw new ProDucsError(`Required command not found: ${cmd}`, node.loc); }
+    }, { doc:"Halt if shell command not in PATH" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  SHELL
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Shell_run", (node,input) => {
+      const cmd = itp(rT(node)||input.VALUE);
+      if (!cmd) return failResult("",{reason:"no command"});
+      try {
+        execSync(cmd,{stdio:"inherit",env:{...process.env,...env.vars}});
+        return okResult(cmd);
+      } catch(e) {
+        if (env.strict) throw e;
+        return failResult(cmd,{reason:e.message, code:e.status});
+      }
+    }, { doc:"Run VALUE or text child as shell command" });
+
+    R.register("Shell_capture", (node,input) => {
+      const cmd = itp(rT(node)||input.VALUE);
+      if (!cmd) return failResult("",{reason:"no command"});
+      try {
+        const stdout = execSync(cmd,{encoding:"utf8",env:{...process.env,...env.vars}});
+        return okResult(stdout.trim());
+      } catch(e) {
+        if (env.strict) throw e;
+        return failResult(e.stdout?.trim()||"",{reason:e.message});
+      }
+    }, { doc:"Run command, capture stdout → VALUE" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  STRING OPS
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Trim",  (_,i)=>okResult(i.VALUE.trim()),        {doc:"Trim whitespace from VALUE"});
+    R.register("Upper", (_,i)=>okResult(i.VALUE.toUpperCase()), {doc:"Uppercase VALUE"});
+    R.register("Lower", (_,i)=>okResult(i.VALUE.toLowerCase()), {doc:"Lowercase VALUE"});
+    R.register("Len",   (_,i)=>okResult(String(i.VALUE.length)),{doc:"String length → VALUE"});
+
+    R.register("Replace", (node,input) => {
+      const [from="",to="",flags="g"] = rA(node.args);
+      return okResult(input.VALUE.replace(new RegExp(from,flags),to));
+    }, { doc:"Replace['pattern','replacement','flags']" });
+
+    R.register("Slice", (node,input) => {
+      const [start="0",end=""] = rA(node.args);
+      return okResult(end!=="" ? input.VALUE.slice(Number(start),Number(end)) : input.VALUE.slice(Number(start)));
+    }, { doc:"Slice['start','end']" });
+
+    R.register("Split", (node,input) => {
+      const [sep=","] = rA(node.args);
+      return okResult(JSON.stringify(input.VALUE.split(sep)));
+    }, { doc:"Split VALUE by sep → JSON array string" });
+
+    R.register("Join", (node,input) => {
+      const [sep=","] = rA(node.args);
+      let arr; try { arr=JSON.parse(input.VALUE); } catch { arr=[input.VALUE]; }
+      return okResult(arr.join(sep));
+    }, { doc:"Join JSON array VALUE by separator" });
+
+    R.register("Default", (node,input) => {
+      const [fallback=""] = rA(node.args);
+      return okResult(input.VALUE!=="" ? input.VALUE : fallback);
+    }, { doc:"Replace empty VALUE with fallback" });
+
+    R.register("Concat", (node,input) => {
+      const parts = rA(node.args);
+      return okResult(input.VALUE + parts.join(""));
+    }, { doc:"Concat['suffix1','suffix2',...] — append to VALUE" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  NUMERIC / MATH
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Int",   (_,i)=>okResult(String(parseInt(i.VALUE,10)||0)));
+    R.register("Float", (_,i)=>okResult(String(parseFloat(i.VALUE)||0)));
+    R.register("Abs",   (_,i)=>okResult(String(Math.abs(Number(i.VALUE)))));
+    R.register("Round", (_,i)=>okResult(String(Math.round(Number(i.VALUE)))));
+    R.register("Floor", (_,i)=>okResult(String(Math.floor(Number(i.VALUE)))));
+    R.register("Ceil",  (_,i)=>okResult(String(Math.ceil(Number(i.VALUE)))));
+
+    R.register("Math", (node,input) => {
+      const [expr=""] = rA(node.args);
+      const expression = expr || input.VALUE;
+      try {
+        return okResult(String(R.evalExpr(expression,{VALUE:input.VALUE})));
+      } catch(e) {
+        return failResult("NaN",{reason:e.message});
+      }
+    }, { doc:"Math['expr'] — evaluate JS math using vars as identifiers" });
+
+    R.register("Inc", (node,input) => {
+      const [name="",step="1"] = rA(node.args);
+      const key  = name || input.VALUE;
+      const newV = (Number(env.vars[key]||0)+Number(step));
+      env.vars[key]=String(newV);
+      return okResult(String(newV));
+    }, { doc:"Increment a variable: Inc['varname','step']" });
+
+    R.register("Dec", (node,input) => {
+      const [name="",step="1"] = rA(node.args);
+      const key  = name || input.VALUE;
+      const newV = (Number(env.vars[key]||0)-Number(step));
+      env.vars[key]=String(newV);
+      return okResult(String(newV));
+    }, { doc:"Decrement a variable: Dec['varname','step']" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  DATA / CRYPTO
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Hash", (node,input) => {
+      const [algo="md5"] = rA(node.args);
+      try { return okResult(crypto.createHash(algo).update(input.VALUE).digest("hex")); }
+      catch(e) { return failResult("",{reason:e.message}); }
+    }, { doc:"Hash['algo'] VALUE (default md5)" });
+
+    R.register("Timestamp", (node,input) => {
+      const [fmt="iso"] = rA(node.args);
+      const now=new Date();
+      return okResult(fmt==="unix" ? String(Math.floor(now/1000)) : fmt==="ms" ? String(now.getTime()) : now.toISOString());
+    }, { doc:"Timestamp['iso'|'unix'|'ms']" });
+
+    R.register("Json_get", (node,input) => {
+      const [keyPath=""] = rA(node.args);
+      try {
+        const obj=JSON.parse(input.VALUE);
+        const val=keyPath.split(".").reduce((o,k)=>o?.[k],obj);
+        return val!==undefined ? okResult(JSON.stringify(val)) : failResult("",{reason:"key not found"});
+      } catch(e) { return failResult("",{reason:e.message}); }
+    }, { doc:"Get dot-path from JSON VALUE: Json_get['a.b.c']" });
+
+    R.register("Json_set", (node,input) => {
+      const [keyPath="",val=""] = rA(node.args);
+      try {
+        const obj=JSON.parse(input.VALUE);
+        const keys=keyPath.split(".");
+        let cur=obj;
+        for (let i=0;i<keys.length-1;i++) cur=(cur[keys[i]]??={});
+        cur[keys.at(-1)]=val;
+        return okResult(JSON.stringify(obj));
+      } catch(e) { return failResult(input.VALUE,{reason:e.message}); }
+    }, { doc:"Set dot-path in JSON VALUE: Json_set['a.b','val']" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  FILE I/O
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Read_file", (node,input) => {
+      const [p=""] = rA(node.args);
+      const path=p||input.VALUE;
+      try { return okResult(fs.readFileSync(path,"utf8").trim()); }
+      catch(e) { return failResult("",{reason:e.message}); }
+    }, { doc:"Read file → VALUE" });
+
+    R.register("Write_file", (node,input) => {
+      const [p=""] = rA(node.args);
+      fs.writeFileSync(p, rT(node)||input.VALUE, "utf8");
+      return okResult(p);
+    }, { doc:"Write VALUE to file: Write_file['path']" });
+
+    R.register("Append_file", (node,input) => {
+      const [p=""] = rA(node.args);
+      fs.appendFileSync(p, (rT(node)||input.VALUE)+"\n","utf8");
+      return okResult(p);
+    }, { doc:"Append VALUE to file" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  CONTROL FLOW
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Goto", (node,input) => {
+      const [label=""] = rA(node.args);
+      if (!label) throw new ProDucsError("Goto requires a label name", node.loc);
+      throw new GotoSignal(label);
+    }, { doc:"Goto['label'] — jump to matching Label" });
+
+    R.register("Label", (node,input) => input,
+      { doc:"Label['name'] — jump target for Goto" });
+
+    R.register("Exit", (node,input) => {
+      const [code="0"] = rA(node.args);
+      process.exit(Number(code)||0);
+    }, { doc:"Exit['code'] — terminate process" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  TIMING
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Wait", (node,input) => {
+      const [ms="0"] = rA(node.args);
+      const n=Math.max(0,Number(ms)||0);
+      const end=Date.now()+n;
+      while (Date.now()<end) {}
+      return okResult(String(n));
+    }, { doc:"Wait['ms'] — blocking sleep in milliseconds" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  LOGGING
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Log", (node,input) => {
+      const [label="LOG"] = rA(node.args);
+      env.logEntry(label, input.VALUE, !input.failed);
+      return input;
+    }, { doc:"Append VALUE+status to execution log" });
+
+    R.register("Dump_log", (node,input) => {
+      out(env.bold("\n─── Execution Log ───\n"));
+      env.log.forEach(e=>{
+        const ts=env.dim(`[+${e.t}ms]`);
+        const sym=e.ok ? env.green("✔") : env.red("✖");
+        out(`${ts} ${sym} ${env.bold(e.cmd)}: ${e.msg}\n`);
+      });
+      return okResult(String(env.log.length));
+    }, { doc:"Print execution log to stdout" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  VISUAL
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("HR", (node,input) => {
+      const [ch="─"] = rA(node.args);
+      out(env.dim(env.hr(ch))+"\n"); return okResult(input.VALUE);
+    }, { doc:"Print full-width horizontal rule" });
+
+    R.register("Header", (node,input) => {
+      const [title=""] = rA(node.args);
+      const t=title||input.VALUE, line=env.hr("═");
+      out(`\n${env.col(C.bold+C.cyan,line)}\n`);
+      out(`${env.col(C.bold+C.cyan,"  "+t)}\n`);
+      out(`${env.col(C.bold+C.cyan,line)}\n\n`);
+      return okResult(t);
+    }, { doc:"Print prominent banner header" });
+
+    R.register("Color", (node,input) => {
+      const [colorName="white",str=""] = rA(node.args);
+      const msg=str||input.VALUE;
+      out(env.col(C[colorName]||C.white,msg)+"\n");
+      return okResult(msg);
+    }, { doc:"Color['name','text'] — print in ANSI color" });
+
+    R.register("Progress", (node,input) => {
+      const [pct="0",width="40",label=""] = rA(node.args);
+      const p=Math.min(100,Math.max(0,Number(pct)));
+      const w=Number(width), fill=Math.round(p/100*w);
+      const bar=env.col(C.green,"█".repeat(fill))+env.dim("░".repeat(w-fill));
+      out(`${bar} ${env.bold(String(p)+"%")} ${label}\n`);
+      return okResult(String(p));
+    }, { doc:"Progress['percent','width','label']" });
+
+    R.register("Spinner", (node,input) => {
+      const [msg="Working…"] = rA(node.args);
+      out(env.cyan("⠿ ")+msg+"\n"); return okResult(input.VALUE);
+    }, { doc:"Print spinner-style status line" });
+
+    R.register("Status", (node,input) => {
+      const [label=""] = rA(node.args);
+      const ok=!input.failed;
+      const sym=ok ? env.green("✔") : env.red("✖");
+      const tag=ok ? env.col(C.bggreen+C.white," OK ") : env.col(C.bgred+C.white," FAIL ");
+      out(`${sym} ${tag}  ${label||input.VALUE}\n`);
+      return input;
+    }, { doc:"Print OK/FAIL badge for current result" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  RUNTIME CONTROL
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Debug", (node,input) => {
+      const [onoff="on"] = rA(node.args);
+      env.debug=onoff!=="off";
+      err(env.dim(`[debug ${env.debug?"ON":"OFF"}]\n`));
+      return okResult(input.VALUE);
+    }, { doc:"Debug['on'|'off'] — toggle debug output" });
+
+    R.register("Strict", (node,input) => {
+      const [onoff="on"] = rA(node.args);
+      env.strict=onoff!=="off"; return okResult(input.VALUE);
+    }, { doc:"Strict['on'|'off'] — halt on shell failure" });
+
+    R.register("Color_off", (node,input) => {
+      env.colorOff=true; return okResult(input.VALUE);
+    }, { doc:"Disable ANSI colors" });
+
+    // ══════════════════════════════════════════════════════════════════════════
+    //  META
+    // ══════════════════════════════════════════════════════════════════════════
+
+    R.register("Help", (node,input) => {
+      out(env.col(C.bold+C.cyan,"\nProDucs Commands\n"));
+      out(env.dim(env.hr()+"\n"));
+      for (const [name,def] of this._cmds)
+        out(`  ${env.bold(pad(name,26))}${env.dim(def.doc||"")}\n`);
+      out("\n"); return okResult(input.VALUE);
+    }, { doc:"List all commands with descriptions" });
+
+    R.register("Version", (node,input) => {
+      const v="ProDucs v3.0.0";
+      out(env.cyan(v)+"\n"); return okResult(v);
+    }, { doc:"Print ProDucs version" });
+
+    // Block stubs (for Help only — executed by Executor)
+    const stub=(name,doc)=>R.register(name,null,{isBlock:true,doc});
+    stub(">",          "Prompt block — VALUE piped into children");
+    stub("Branch",     "Branch — runs children only when failed=0 (check passed)");
+    stub("BranchElse", "BranchElse — runs children only when failed=1 (check failed)");
+    stub("Repeat",     "Repeat['N'] — loop N times (_i available as index)");
+    stub("ForEach",    "ForEach['var','a','b',...] — iterate over items");
+    stub("Try",        "Try — errors caught by sibling Catch block");
+    stub("Catch",      "Catch — runs when Try threw (_error set)");
+    stub("Section",    "Section['title'] — formatted section heading");
+    stub("Step",       "Step['desc'] — auto-numbered step");
+    stub("Group",      "Group['label'] — logical grouping with bracket lines");
+    stub("Table",      "Table — ASCII table; Row children define rows");
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+//  EXECUTOR
+// ═══════════════════════════════════════════════════════════════════════════════
+class Executor {
+  constructor(registry, env) { this.registry=registry; this.env=env; }
+
+  /** Pre-pass: walk all node lists and register Label positions */
+  indexLabels(nodes) {
+    for (const node of nodes) {
+      if (node.type==="Label") {
+        const [name=""] = this.registry.resolveArgs(node.args);
+        if (name) this.env.labels[name]={node, list:nodes};
+      }
+      if (node.children?.length) this.indexLabels(node.children);
+    }
   }
 
   execute(ast) {
-    let result = { VALUE: "", failed: 0 };
-    for (const node of ast) {
-      result = this.executeNode(node, result);
+    this.indexLabels(ast);
+    return this.executeList(ast);
+  }
+
+  /**
+   * Execute a flat node list. Catches GotoSignal if the target label's
+   * canonical list is THIS list; otherwise re-throws so a parent list handles it.
+   */
+  executeList(nodes, input=mkResult(), start=0, end=nodes.length) {
+    let result=input, i=start;
+    while (i<end) {
+      try {
+        result=this.executeNode(nodes[i], result);
+        i++;
+      } catch(signal) {
+        if (!(signal instanceof GotoSignal)) throw signal;
+        const entry=this.env.labels[signal.label];
+        if (!entry) throw new ProDucsError(`Goto: label '${signal.label}' not found`);
+        if (entry.list!==nodes) throw signal;   // propagate to parent list
+        i=nodes.indexOf(entry.node)+1;           // jump past the Label node
+      }
     }
     return result;
   }
+
+  executeNode(node, input=mkResult()) {
+    this.env.stepNum++;
+
+    // ── Text ──────────────────────────────────────────────────────────────────
+    if (node.type==="Text") {
+      const msg=this.env.interpolate(node.value);
+      if (!msg.trim()) return okResult(msg);
+      out(msg+"\n"); return okResult(msg);
+    }
+
+    // ── Branch (run if failed===0) ────────────────────────────────────────────
+    if (node.type==="Branch") {
+      if (!input.failed) return this.executeList(node.children, input);
+      return input;
+    }
+
+    // ── BranchElse (run if failed===1) ────────────────────────────────────────
+    if (node.type==="BranchElse") {
+      if (input.failed) return this.executeList(node.children, input);
+      return input;
+    }
+
+    // ── Repeat ────────────────────────────────────────────────────────────────
+    if (node.type==="Repeat") {
+      const [n="1"] = this.registry.resolveArgs(node.args);
+      const count=Math.max(0,parseInt(this.env.interpolate(n),10)||0);
+      let cur=input;
+      for (let i=0;i<count;i++) {
+        this.env.vars["_i"]=String(i);
+        cur=this.executeList(node.children,cur);
+      }
+      return cur;
+    }
+
+    // ── ForEach ───────────────────────────────────────────────────────────────
+    if (node.type==="ForEach") {
+      const [varName="_item",...items] = this.registry.resolveArgs(node.args);
+      let cur=input;
+      for (const item of items) {
+        this.env.vars[varName]=this.env.interpolate(item);
+        cur=this.executeList(node.children,cur);
+      }
+      return cur;
+    }
+
+    // ── Try / Catch ───────────────────────────────────────────────────────────
+    if (node.type==="Try") {
+      const catchIdx=node.children.findIndex(c=>c.type==="Catch");
+      const tryEnd=catchIdx===-1 ? node.children.length : catchIdx;
+      let cur=input;
+      try {
+        cur=this.executeList(node.children,cur,0,tryEnd);
+      } catch(e) {
+        if (e instanceof GotoSignal) throw e;
+        if (catchIdx!==-1) {
+          this.env.vars["_error"]=e.message;
+          cur=this.executeList(node.children[catchIdx].children, failResult(e.message));
+        } else throw e;
+      }
+      return cur;
+    }
+
+    // ── Section ───────────────────────────────────────────────────────────────
+    if (node.type==="Section") {
+      const [title=""] = this.registry.resolveArgs(node.args);
+      const t=this.env.interpolate(title);
+      out(`\n${this.env.col(C.bold+C.blue,"▶ "+t)}\n`);
+      out(this.env.col(C.blue,this.env.hr("─"))+"\n");
+      return this.executeList(node.children, input);
+    }
+
+    // ── Step ──────────────────────────────────────────────────────────────────
+    if (node.type==="Step") {
+      const [desc=""] = this.registry.resolveArgs(node.args);
+      out(`\n${this.env.col(C.bold+C.cyan,`[${this.env.stepNum}]`)} `+
+          `${this.env.bold(this.env.interpolate(desc))}\n`);
+      return this.executeList(node.children, input);
+    }
+
+    // ── Group ─────────────────────────────────────────────────────────────────
+    if (node.type==="Group") {
+      const [label=""] = this.registry.resolveArgs(node.args);
+      const l=this.env.interpolate(label);
+      if (l) out(this.env.dim(`┌── ${l} ──\n`));
+      const cur=this.executeList(node.children, input);
+      if (l) out(this.env.dim("└──\n"));
+      return cur;
+    }
+
+    // ── Table ─────────────────────────────────────────────────────────────────
+    if (node.type==="Table") {
+      const rowNodes=node.children.filter(c=>c.type==="Row");
+      if (!rowNodes.length) return input;
+      const rows=rowNodes.map(r=>this.registry.resolveArgs(r.args));
+      const ncols=rows[0].length;
+      const widths=Array.from({length:ncols},(_,ci)=>Math.max(...rows.map(r=>(r[ci]||"").length)));
+      const sep="┼"+widths.map(w=>"─".repeat(w+2)).join("┼")+"┼";
+      const fmt=(row,isHdr)=>"│"+row.map((c,i)=>{
+        const s=pad(c||"",widths[i]);
+        return " "+(isHdr?this.env.bold(s):s)+" ";
+      }).join("│")+"│";
+      out("\n");
+      rows.forEach((row,ri)=>{
+        if (ri===1) out(this.env.dim(sep)+"\n");
+        out(fmt(row,ri===0)+"\n");
+      });
+      out("\n");
+      return okResult(String(rows.length));
+    }
+
+    // ── Inline command + pipe chain ───────────────────────────────────────────
+    const def=this.registry.get(node.type);
+    if (!def) throw new ProDucsError(`Unknown command: ${node.type}`, node.loc);
+    if (def.isBlock) throw new ProDucsError(
+      `Block command '${node.type}' must be closed with #$End_${node.type}`, node.loc);
+
+    let current=def.fn(node,input);
+    for (const pipe of (node.pipes||[])) {
+      const pdef=this.registry.get(pipe.type);
+      if (!pdef) throw new ProDucsError(`Unknown piped command: ${pipe.type}`, pipe.loc);
+      if (pdef.isBlock) throw new ProDucsError(
+        `Block command '${pipe.type}' cannot be a pipe target`, pipe.loc);
+      current=pdef.fn(pipe,current);
+    }
+    return current;
+  }
 }
 
-// ──────────────────────────── Example ────────────────────────────
-const src = `
-Hi
-#$> Type your command: #$Check_equals['ls -la'] #$Check_failed_error['expected ls -la!'] #$Shell_run #$End_>
-`;
+// ═══════════════════════════════════════════════════════════════════════════════
+//  PUBLIC API
+// ═══════════════════════════════════════════════════════════════════════════════
+class ProDucs {
+  constructor(opts={}) {
+    this.env      = new RuntimeEnv();
+    this.registry = new CommandRegistry(this.env);
+    this.executor = new Executor(this.registry, this.env);
+    if (opts.debug)   this.env.debug    = true;
+    if (opts.strict)  this.env.strict   = true;
+    if (opts.noColor) this.env.colorOff = true;
+  }
+
+  register(name,fn,meta={}) { this.registry.register(name,fn,meta); return this; }
+  tokenize(src)  { return new Tokenizer(src).tokenize(); }
+  parse(tokens)  { return new Parser(tokens).parse(); }
+  astify(src)    { return this.parse(this.tokenize(src)); }
+  execute(ast)   { return this.executor.execute(ast); }
+
+  run(src) {
+    this.env.reset();
+    return this.execute(this.astify(src));
+  }
+
+  set(name,value) { this.env.vars[name]=String(value); return this; }
+  vars()          { return {...this.env.vars}; }
+}
 
-const prod = new ProDucs();
-const ast = prod.astify(src);
-console.log("AST:", JSON.stringify(ast, null, 2));
-prod.execute(ast);
+module.exports = {
+  ProDucs, ProDucsError, GotoSignal,
+  RuntimeEnv, Tokenizer, Parser, Executor, CommandRegistry,
+};