producs 1.0.1 → 3.0.0

package/cli.js

@@ -1,92 +1,114 @@
 #!/usr/bin/env node
-const { Command } = require("commander");
-const fs = require("fs");
+"use strict";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+//  ProDucs CLI  —  node cli.js <file.pd> [flags]
+//                  producs <file.pd> [flags]   (when installed globally)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const fs   = require("fs");
 const path = require("path");
-const chalk = require("chalk");
-const { ProDucs } = require("./producs.js");
-
-const PAGES_DIR = "/usr/share/producs";
-const program = new Command();
-
-// ───────────────────────────────────────────────
-// Utility functions
-// ───────────────────────────────────────────────
-function listPages(showDesc = false) {
-  if (!fs.existsSync(PAGES_DIR)) {
-    console.log(chalk.red(`No pages directory found at ${PAGES_DIR}`));
-    return;
-  }
+const { ProDucs, ProDucsError } = require("./index.js");
 
-  const files = fs.readdirSync(PAGES_DIR).filter(f => f.endsWith(".prd"));
-  if (files.length === 0) {
-    console.log(chalk.yellow("No .prd pages found in"), PAGES_DIR);
-    return;
-  }
+// ─── ANSI (minimal, used before env is up) ────────────────────────────────────
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim  = (s) => `\x1b[2m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const red  = (s) => `\x1b[31m${s}\x1b[0m`;
 
-  console.log(chalk.bold.cyan("Available ProDucs pages:\n"));
-  for (const file of files) {
-    const name = file.replace(/\.prd$/, "");
-    let desc = "";
-    if (showDesc) {
-      try {
-        const firstLine = fs.readFileSync(path.join(PAGES_DIR, file), "utf8").split("\n")[0];
-        desc = " — " + firstLine.trim();
-      } catch {}
-    }
-    console.log(" • " + chalk.green(name) + chalk.gray(desc));
-  }
-}
+const HELP = `
+${bold(cyan("ProDucs"))} — Professional Documentation Shell DSL  ${dim("v3.0.0")}
+${dim("─".repeat(60))}
+${bold("Usage:")}
+  producs <file.pd> [flags]
+  producs --demo
+  producs --help
 
-// ───────────────────────────────────────────────
-// Page runner
-// ───────────────────────────────────────────────
-function runPage(name) {
-  const filePath = path.join(PAGES_DIR, name.endsWith(".prd") ? name : name + ".prd");
-  if (!fs.existsSync(filePath)) {
-    console.error(chalk.red(`Page not found:`), filePath);
-    console.log();
-    listPages(true);
-    process.exit(1);
-  }
+${bold("Flags:")}
+  ${bold("--debug")}       Verbose debug output to stderr
+  ${bold("--strict")}      Halt on any shell command failure
+  ${bold("--no-color")}    Disable ANSI colors
+  ${bold("--ast")}         Dump AST as JSON and exit (no execution)
+  ${bold("--demo")}        Run the built-in feature demo
+  ${bold("--help")}        Show this message
+  ${bold("--version")}     Print version
+
+${bold("Syntax Quick-Ref:")}
+  ${cyan("#$Cmd['arg1','arg2']")}          inline command
+  ${cyan("#$Cmd1 | #$Cmd2 | #$Cmd3")}     pipe chain (left→right)
+  ${cyan("#$Block['title']")}             open a block
+  ${cyan("#$End_Block")}                  close a block
+  ${cyan("// comment")}                   line comment
+  ${cyan("${varname}")}                   variable interpolation
+
+${bold("Branching (replaces if/else):")}
+  ${cyan("#$Check_eq['expected']")}        sets failed=0 (pass) or failed=1 (fail)
+  ${cyan("#$Branch")}                      runs children only when failed=0
+  ${cyan("  #$Print['it passed']")}
+  ${cyan("#$End_Branch")}
+  ${cyan("#$BranchElse")}                  runs children only when failed=1
+  ${cyan("  #$Print['it failed']")}
+  ${cyan("#$End_BranchElse")}
 
-  const src = fs.readFileSync(filePath, "utf8");
-  const engine = new ProDucs();
+${bold("All Check_* commands:")}
+  Check_eq          Check_neq         Check_contains    Check_not_contains
+  Check_starts      Check_ends        Check_matches     Check_empty
+  Check_nonempty    Check_gt          Check_gte         Check_lt
+  Check_lte         Check_num_eq      Check_num_neq     Check_between
+  Check_failed      Check_passed      Check_var_eq      Check_var_neq
+  Check_failed_error  Check_passed_error
 
-  console.log(chalk.yellowBright(`\n── Running page: ${name} ──\n`));
-  try {
-    const ast = engine.astify(src);
-    engine.execute(ast);
-    console.log(chalk.greenBright("\n✔ Page completed successfully.\n"));
-  } catch (err) {
-    console.error(chalk.red.bold("\n✖ Execution error:"), err.message, "\n");
+${bold("File extension:")}  .pd  (ProDucs script)
+${dim("─".repeat(60))}
+`;
+
+const DEMO = require("fs").readFileSync(
+  require("path").join(__dirname, "examples", "demo.pd"), "utf8"
+);
+// ─── Parse argv ───────────────────────────────────────────────────────────────
+const argv  = process.argv.slice(2);
+const flags = new Set(argv.filter(a => a.startsWith("--")));
+const files = argv.filter(a => !a.startsWith("--"));
+
+if (flags.has("--version")) { process.stdout.write("ProDucs v3.0.0\n"); process.exit(0); }
+if (flags.has("--help") || process.argv.length === 2)    { process.stdout.write(HELP); process.exit(0); }
+
+const opts = {
+  debug:   flags.has("--debug"),
+  strict:  flags.has("--strict"),
+  noColor: flags.has("--no-color"),
+};
+
+const prod = new ProDucs(opts);
+
+// ─── Demo ─────────────────────────────────────────────────────────────────────
+if (flags.has("--demo")) {
+  try { prod.run(DEMO); }
+  catch (e) {
+    process.stderr.write(red(`\n${e.name||"Error"}: ${e.message}\n`));
+    if (opts.debug && e.stack) process.stderr.write(dim(e.stack)+"\n");
     process.exit(1);
   }
+  process.exit(0);
 }
 
-// ───────────────────────────────────────────────
-// CLI setup with commander
-// ───────────────────────────────────────────────
-program
-  .name("producs")
-  .description("Interactive documentation and tutorial runner")
-  .version("1.0.0");
-
-program
-  .command("list")
-  .description("List all available ProDucs pages")
-  .option("-d, --describe", "Show first-line descriptions for each page")
-  .action((options) => listPages(options.describe));
-
-program
-  .command("run <page>")
-  .description("Run a specific ProDucs documentation page")
-  .action(runPage);
-
-program
-  .argument("[page]", "Run a page directly (shortcut for 'run <page>')")
-  .action((page) => {
-    if (page) runPage(page);
-    else listPages(true);
-  });
-
-program.parse(process.argv);
+// ─── File execution ───────────────────────────────────────────────────────────
+const filePath = path.resolve(files[0]);
+let src;
+try { src = fs.readFileSync(filePath, "utf8"); }
+catch (e) {
+  process.stderr.write(red(`Cannot read: ${filePath}\n`));
+  process.exit(1);
+}
+
+if (flags.has("--ast")) {
+  console.log(JSON.stringify(prod.astify(src), null, 2));
+  process.exit(0);
+}
+
+try { prod.run(src); }
+catch (e) {
+  process.stderr.write(red(`\n${e.name||"Error"}: ${e.message}\n`));
+  if (opts.debug && e.stack) process.stderr.write(dim(e.stack)+"\n");
+  process.exit(1);
+}

package/examples/checks.pd

@@ -0,0 +1,126 @@
+// checks.pd — showcase all Check_* commands
+
+#$Header['ProDucs Check Commands Demo']
+
+// ── String Checks ─────────────────────────────────────────────────
+#$Section['String Checks on VALUE']
+
+  #$Set['val','Hello World']
+
+  #$Set['val','${val}'] | #$Check_eq['Hello World']
+  #$Branch
+    #$Color['green','Check_eq: PASS']
+  #$End_Branch
+
+  #$Set['val','${val}'] | #$Check_contains['World']
+  #$Branch
+    #$Color['green','Check_contains: PASS']
+  #$End_Branch
+
+  #$Set['val','${val}'] | #$Check_starts['Hello']
+  #$Branch
+    #$Color['green','Check_starts: PASS']
+  #$End_Branch
+
+  #$Set['val','${val}'] | #$Check_ends['World']
+  #$Branch
+    #$Color['green','Check_ends: PASS']
+  #$End_Branch
+
+  #$Set['val','${val}'] | #$Check_matches['^Hello']
+  #$Branch
+    #$Color['green','Check_matches: PASS']
+  #$End_Branch
+
+  #$Set['empty','']
+  #$Set['empty','${empty}'] | #$Check_empty
+  #$Branch
+    #$Color['green','Check_empty: PASS']
+  #$End_Branch
+
+  #$Set['val','${val}'] | #$Check_nonempty
+  #$Branch
+    #$Color['green','Check_nonempty: PASS']
+  #$End_Branch
+
+#$End_Section
+
+// ── Numeric Checks ────────────────────────────────────────────────
+#$Section['Numeric Checks']
+
+  #$Set['score','85']
+
+  #$Check_gt['score','80']
+  #$Branch
+    #$Color['green','Check_gt score > 80: PASS']
+  #$End_Branch
+
+  #$Check_gte['score','85']
+  #$Branch
+    #$Color['green','Check_gte score >= 85: PASS']
+  #$End_Branch
+
+  #$Check_lt['score','90']
+  #$Branch
+    #$Color['green','Check_lt score < 90: PASS']
+  #$End_Branch
+
+  #$Check_lte['score','85']
+  #$Branch
+    #$Color['green','Check_lte score <= 85: PASS']
+  #$End_Branch
+
+  #$Check_num_eq['score','85']
+  #$Branch
+    #$Color['green','Check_num_eq score == 85: PASS']
+  #$End_Branch
+
+  #$Check_between['score','80','90']
+  #$Branch
+    #$Color['green','Check_between score in [80,90]: PASS']
+  #$End_Branch
+
+#$End_Section
+
+// ── Variable Comparison ───────────────────────────────────────────
+#$Section['Variable Comparison']
+
+  #$Set['a','hello']
+  #$Set['b','hello']
+  #$Set['c','world']
+
+  #$Check_var_eq['a','b']
+  #$Branch
+    #$Color['green','Check_var_eq a===b: PASS']
+  #$End_Branch
+
+  #$Check_var_neq['a','c']
+  #$Branch
+    #$Color['green','Check_var_neq a!==c: PASS']
+  #$End_Branch
+
+#$End_Section
+
+// ── Result / State Checks ─────────────────────────────────────────
+#$Section['Result State Checks']
+
+  // Force a fail state
+  #$Set['x','5'] | #$Check_gt['10']
+
+  #$Check_failed
+  #$Branch
+    #$Color['green','Check_failed: PASS (previous check did fail)']
+  #$End_Branch
+
+  // Now pass
+  #$Set['x','15'] | #$Check_gt['10']
+
+  #$Check_passed
+  #$Branch
+    #$Color['green','Check_passed: PASS (previous check passed)']
+  #$End_Branch
+
+#$End_Section
+
+#$HR
+#$Status['All checks demonstrated']

package/examples/demo.pd

@@ -0,0 +1,113 @@
+#$Header['ProDucs v3.0 Demo']
+
+// ── Variables & Math ──────────────────────────────────────────────
+#$Section['Variables & Math']
+  #$Set['x','40']
+  #$Set['y','2']
+  #$Math['x * y'] | #$Set['product']
+  #$Print['${x} * ${y} = ${product}']
+  #$Inc['x','5']
+  #$Print['x after Inc: ${x}']
+#$End_Section
+
+// ── Pipe chain ────────────────────────────────────────────────────
+#$Section['Pipe Chain']
+  #$Set['msg','  hello world  ']
+  #$Set['msg','${msg}'] | #$Trim | #$Upper | #$Set['msg']
+  #$Print['Processed: ${msg}']
+  #$Len | #$Set['len']
+  #$Print['Length: ${len}']
+#$End_Section
+
+// ── Branch on string check ────────────────────────────────────────
+#$Section['Branch: String Check']
+  #$Set['role','admin']
+  #$Set['role','${role}'] | #$Check_eq['admin']
+  #$Branch
+    #$Color['green','✔ Role is admin']
+  #$End_Branch
+  #$BranchElse
+    #$Color['red','✖ Role is not admin']
+  #$End_BranchElse
+#$End_Section
+
+// ── Branch on numeric check ───────────────────────────────────────
+#$Section['Branch: Numeric Check']
+  #$Set['score','87']
+  #$Check_gte['score','80']
+  #$Branch
+    #$Color['green','✔ Score ${score} >= 80: Pass']
+  #$End_Branch
+  #$BranchElse
+    #$Color['red','✖ Score ${score} < 80: Fail']
+  #$End_BranchElse
+
+  #$Check_between['score','90','100']
+  #$Branch
+    #$Print['Score is A-grade']
+  #$End_Branch
+  #$BranchElse
+    #$Print['Score is not A-grade (${score} not in 90-100)']
+  #$End_BranchElse
+#$End_Section
+
+// ── Repeat ────────────────────────────────────────────────────────
+#$Section['Repeat']
+  #$Repeat['3']
+    #$Print['Iteration ${_i}']
+  #$End_Repeat
+#$End_Section
+
+// ── ForEach ───────────────────────────────────────────────────────
+#$Section['ForEach']
+  #$ForEach['lang','Nova','C','Zig']
+    #$Print['Language: ${lang}']
+  #$End_ForEach
+#$End_Section
+
+// ── Goto & Label ─────────────────────────────────────────────────
+#$Section['Goto & Label']
+  #$Set['skip','yes']
+  #$Set['skip','${skip}'] | #$Check_eq['yes']
+  #$Branch
+    #$Goto['after_block']
+  #$End_Branch
+  #$Print['THIS MUST NOT APPEAR']
+#$Label['after_block']
+  #$Print['✔ Jumped here via Goto']
+#$End_Section
+
+// ── Try / Catch ───────────────────────────────────────────────────
+#$Section['Try / Catch']
+  #$Try
+    #$Assert['1===2','intentional failure']
+  #$Catch
+    #$Print['Caught: ${_error}']
+  #$End_Catch
+  #$End_Try
+#$End_Section
+
+// ── Wait ──────────────────────────────────────────────────────────
+#$Section['Wait']
+  #$Spinner['Waiting 300ms...']
+  #$Wait['300']
+  #$Color['green','Done.']
+#$End_Section
+
+// ── Table ─────────────────────────────────────────────────────────
+#$Section['Table']
+  #$Table
+    #$Row['Command','Category','Description']
+    #$Row['Check_gt','Numeric','Greater-than check']
+    #$Row['Check_between','Numeric','Range check']
+    #$Row['Branch','Control','Run if check passed']
+    #$Row['BranchElse','Control','Run if check failed']
+    #$Row['Goto','Control','Jump to label']
+    #$Row['Wait','Timing','Blocking sleep (ms)']
+    #$Row['Shell_capture','Shell','Capture stdout']
+  #$End_Table
+#$End_Section
+
+#$HR['=']
+#$Status['Demo complete']
+#$Dump_log

package/examples/deploy.pd

@@ -0,0 +1,43 @@
+// deploy.pd — deployment checklist example
+
+#$Header['Deploy Checklist']
+
+#$Section['Pre-flight Checks']
+  #$Require_cmd['git']
+  #$Require_cmd['node']
+  #$Color['green','✔ Required commands found']
+
+  #$Timestamp['iso'] | #$Set['deploy_time']
+  #$Print['Deploy started: ${deploy_time}']
+#$End_Section
+
+#$Section['Branch Check']
+  #$Shell_capture['git branch --show-current'] | #$Set['branch']
+  #$Print['Current branch: ${branch}']
+
+  #$Set['branch','${branch}'] | #$Check_eq['main']
+  #$Branch
+    #$Color['green','✔ On main branch']
+  #$End_Branch
+  #$BranchElse
+    #$Warn['Not on main branch — deploying ${branch}']
+    #$Confirm['Continue anyway?','n']
+    #$Check_passed_error['Aborted by user']
+  #$End_BranchElse
+#$End_Section
+
+#$Section['Build Steps']
+  #$Step['Install dependencies']
+    #$Shell_run['npm ci']
+    #$Status['npm ci']
+  #$End_Step
+
+  #$Step['Run tests']
+    #$Shell_run['npm test']
+    #$Status['npm test']
+  #$End_Step
+#$End_Section
+
+#$HR['═']
+#$Status['Deploy complete']
+#$Dump_log