producs 1.0.1 → 3.0.0

package/README.md

@@ -0,0 +1,245 @@
+# ProDucs v3.0
+
+**Professional Documentation Shell DSL** — a modular, pipeable terminal scripting language for advanced CLI documentation and automation.
+
+## Install
+
+```bash
+npm install          # install deps
+npm link             # optional: install `producs` globally
+```
+
+## Run
+
+```bash
+node cli.js script.pd          # run a .pd file
+node cli.js --demo             # built-in feature demo
+node cli.js --ast script.pd    # dump AST as JSON
+node cli.js --help             # full usage
+```
+
+Or if installed globally:
+```bash
+producs script.pd
+```
+
+---
+
+## Syntax
+
+```
+// line comment
+
+#$CommandName['arg1','arg2']       inline command
+#$Cmd1 | #$Cmd2 | #$Cmd3          pipe chain (output of each → input of next)
+${varname}                         variable interpolation
+
+#$BlockName['arg']                 open a block
+  ...children...
+#$End_BlockName                    close the block
+```
+
+---
+
+## Branching
+
+ProDucs replaces if/else with an explicit **check → branch** model:
+
+1. A `Check_*` command runs and sets `failed=0` (pass) or `failed=1` (fail)
+2. `#$Branch` runs its children only when `failed=0`
+3. `#$BranchElse` runs its children only when `failed=1`
+
+```
+#$Set['score','92']
+#$Check_gte['score','90']
+#$Branch
+  #$Color['green','A grade!']
+#$End_Branch
+#$BranchElse
+  #$Color['yellow','Below A grade']
+#$End_BranchElse
+```
+
+---
+
+## All Check Commands
+
+### String checks (operate on `VALUE`)
+
+| Command | Description |
+|---|---|
+| `Check_eq['expected']` | Pass if VALUE === expected |
+| `Check_neq['expected']` | Pass if VALUE !== expected |
+| `Check_contains['needle']` | Pass if VALUE contains needle |
+| `Check_not_contains['needle']` | Pass if VALUE does NOT contain needle |
+| `Check_starts['prefix']` | Pass if VALUE starts with prefix |
+| `Check_ends['suffix']` | Pass if VALUE ends with suffix |
+| `Check_matches['regex','flags']` | Pass if VALUE matches regex |
+| `Check_empty` | Pass if VALUE is empty string |
+| `Check_nonempty` | Pass if VALUE is not empty |
+
+### Numeric checks
+
+Two forms: `Check_gt['varname','number']` or `Check_gt['number']` (uses VALUE as number).
+
+| Command | Description |
+|---|---|
+| `Check_gt['var','n']` | Pass if var > n |
+| `Check_gte['var','n']` | Pass if var >= n |
+| `Check_lt['var','n']` | Pass if var < n |
+| `Check_lte['var','n']` | Pass if var <= n |
+| `Check_num_eq['var','n']` | Pass if var == n (numeric) |
+| `Check_num_neq['var','n']` | Pass if var != n (numeric) |
+| `Check_between['var','lo','hi']` | Pass if lo <= var <= hi |
+
+### Variable comparison
+
+| Command | Description |
+|---|---|
+| `Check_var_eq['a','b']` | Pass if var a === var b |
+| `Check_var_neq['a','b']` | Pass if var a !== var b |
+
+### Result checks
+
+| Command | Description |
+|---|---|
+| `Check_failed` | Pass if previous result was failed |
+| `Check_passed` | Pass if previous result was passed |
+| `Check_failed_error['msg']` | Throw error if previous result was failed |
+| `Check_passed_error['msg']` | Throw error if previous result passed |
+
+---
+
+## Command Reference
+
+### I/O
+| Command | Description |
+|---|---|
+| `> ['prompt']` | Prompt user for input |
+| `Print['text']` | Print to stdout |
+| `Warn['text']` | Print yellow warning to stderr |
+| `Error_print['text']` | Print red error to stderr |
+| `Pause['msg']` | Block until ENTER |
+| `Confirm['msg','default']` | y/n prompt |
+| `Select['label','opt1',...]` | Numbered menu |
+
+### Variables
+| Command | Description |
+|---|---|
+| `Set['name','value']` | Set a variable |
+| `Unset['name']` | Delete a variable |
+| `Export['name','value']` | Set variable and push to `process.env` |
+| `Env_get['KEY']` | Read `process.env.KEY` → VALUE |
+| `Env_set['KEY']` | Write VALUE → `process.env.KEY` |
+
+### Shell
+| Command | Description |
+|---|---|
+| `Shell_run` | Run VALUE/text child as shell command (inherit stdio) |
+| `Shell_capture` | Run command, capture stdout → VALUE |
+
+### String ops
+`Trim` `Upper` `Lower` `Len` `Replace['pat','rep','flags']`
+`Slice['start','end']` `Split['sep']` `Join['sep']`
+`Default['fallback']` `Concat['suffix',...]`
+
+### Math
+`Int` `Float` `Abs` `Round` `Floor` `Ceil`
+`Math['expr']` `Inc['var','step']` `Dec['var','step']`
+
+### Data
+`Hash['algo']` `Timestamp['iso'|'unix'|'ms']`
+`Json_get['a.b.c']` `Json_set['a.b','val']`
+
+### File I/O
+`Read_file['path']` `Write_file['path']` `Append_file['path']`
+
+### Control
+`Goto['label']` `Label['name']` `Exit['code']`
+`Assert['JS expr','msg']`
+`Require_env['VAR']` `Require_cmd['cmd']`
+
+### Timing
+`Wait['ms']` — blocking sleep in milliseconds
+
+### Blocks
+| Block | Description |
+|---|---|
+| `#$> ['prompt']` | Prompt block |
+| `#$Branch` | Run if last check passed (failed=0) |
+| `#$BranchElse` | Run if last check failed (failed=1) |
+| `#$Repeat['N']` | Loop N times (`_i` = index) |
+| `#$ForEach['var','a','b',...]` | Iterate over items |
+| `#$Try` + `#$Catch` | Error handling (`_error` set in Catch) |
+| `#$Section['title']` | Formatted section heading |
+| `#$Step['desc']` | Auto-numbered step |
+| `#$Group['label']` | Logical grouping with bracket lines |
+| `#$Table` + `#$Row[...]` | ASCII table |
+
+### Visual
+`HR['char']` `Header['title']` `Color['name','text']`
+`Progress['pct','width','label']` `Spinner['msg']` `Status['label']`
+
+### Runtime
+`Debug['on'|'off']` `Strict['on'|'off']` `Color_off`
+`Log['label']` `Dump_log` `Help` `Version`
+
+---
+
+## Example Script
+
+```
+// install.pd — sample deployment doc script
+
+#$Header['Deploy Checklist']
+#$Require_cmd['git']
+#$Require_cmd['node']
+
+#$Section['Pre-flight']
+  #$Shell_capture['git branch --show-current'] | #$Set['branch']
+  #$Print['Branch: ${branch}']
+  #$Set['branch','${branch}'] | #$Check_eq['main']
+  #$BranchElse
+    #$Warn['Not on main branch!']
+  #$End_BranchElse
+#$End_Section
+
+#$Section['Build']
+  #$Step['Install dependencies']
+    #$Shell_run
+    npm ci
+    #$End_Shell_run
+  #$End_Step
+#$End_Section
+
+#$Status['Deploy complete']
+```
+
+---
+
+## Programmatic API
+
+```js
+const { ProDucs } = require("producs");
+
+const prod = new ProDucs({ debug: false, strict: false, noColor: false });
+
+// Register custom command
+prod.register("Shout", (node, input) => {
+  const msg = input.VALUE.toUpperCase() + "!!!";
+  process.stdout.write(msg + "\n");
+  return { VALUE: msg, failed: 0 };
+}, { doc: "Uppercase and add exclamation marks" });
+
+// Pre-set variables
+prod.set("env", "production");
+
+// Run a script
+prod.run(`
+  #$Set['greeting','hello']
+  #$Set['greeting','${greeting}'] | #$Shout
+`);
+
+// Read back vars
+console.log(prod.vars()); // { greeting: "HELLO!!!", env: "production" }
+```

package/README.pd

@@ -0,0 +1,352 @@
+// readme.pd — ProDucs interactive README + tutorial
+// Run with:  node cli.js examples/readme.pd
+
+#$Header['ProDucs v3.0']
+#$Print['Professional Documentation Shell DSL']
+#$Print['A modular, pipeable terminal scripting language.']
+#$HR
+
+// ── Welcome ───────────────────────────────────────────────────────
+#$Section['Welcome']
+  #$Print['Before we dive into the docs, let us show you how ProDucs works.']
+  #$Print['This README will teach you the syntax interactively.']
+  #$Print['']
+  #$Input['What is your name?'] | #$Set['user']
+  #$Color['green','Hey ${user}! Let us get started.']
+#$End_Section
+
+// ── Lesson 1: Commands ────────────────────────────────────────────
+#$Section['Lesson 1: Commands']
+  #$Print['Every ProDucs command looks like this:']
+  #$Print['']
+  #$Color['cyan','  #$CommandName[arg1,arg2]']
+  #$Print['']
+  #$Print['For example, #$Print[hello] prints "hello" to the terminal.']
+  #$Print['Let us try it. Type something and we will print it back.']
+  #$Print['']
+  #$Input['Type anything:'] | #$Set['input1']
+  #$Print['']
+  #$Color['green','  → ${input1}']
+  #$Print['']
+  #$Color['dim','That was: #$Print[${input1}]']
+  #$Pause['Press ENTER to continue...']
+#$End_Section
+
+// ── Lesson 2: Variables ───────────────────────────────────────────
+#$Section['Lesson 2: Variables']
+  #$Print['Variables are set with #$Set and referenced with ${name}.']
+  #$Print['']
+  #$Color['cyan','  #$Set[name,world]']
+  #$Color['cyan','  #$Print[Hello ${name}]']
+  #$Print['']
+  #$Print['Give us a word to store:']
+  #$Input['Enter a word:'] | #$Set['word']
+  #$Print['']
+  #$Color['green','  Stored → word = "${word}"']
+  #$Print['']
+  #$Print['Now we can use it: Hello ${word}!']
+  #$Pause['Press ENTER to continue...']
+#$End_Section
+
+// ── Lesson 3: Pipes ───────────────────────────────────────────────
+#$Section['Lesson 3: Pipe Chains']
+  #$Print['Pipes pass the output of one command into the next:']
+  #$Print['']
+  #$Color['cyan','  #$Set[msg,  hello world  ] | #$Trim | #$Upper | #$Set[msg]']
+  #$Print['']
+  #$Print['We will run that chain live on your word "${word}".']
+  #$Print['Predict the output before you press ENTER.']
+  #$Pause['Press ENTER to run it...']
+  #$Set['word','  ${word}  '] | #$Trim | #$Upper | #$Set['result']
+  #$Print['']
+  #$Color['green','  → ${result}']
+  #$Print['']
+  #$Color['dim','Trimmed whitespace, then uppercased. Pipes compose left to right.']
+  #$Pause['Press ENTER to continue...']
+#$End_Section
+
+// ── Lesson 4: Checks & Branching ─────────────────────────────────
+#$Section['Lesson 4: Checks and Branching']
+  #$Print['ProDucs has no if/else. Instead:']
+  #$Print['']
+  #$Color['dim','  1. A Check_* command sets failed=0 (pass) or failed=1 (fail)']
+  #$Color['dim','  2. #$Branch runs only when failed=0']
+  #$Color['dim','  3. #$BranchElse runs only when failed=1']
+  #$Print['']
+  #$Print['Let us try it. Enter a number and we will tell you if it is above 50.']
+  #$Print['']
+  #$Input['Enter a number:'] | #$Set['num']
+  #$Check_gt['num','50']
+  #$Branch
+    #$Color['green','  ✔ ${num} is greater than 50']
+  #$End_Branch
+  #$BranchElse
+    #$Color['yellow','  ${num} is 50 or below']
+  #$End_BranchElse
+  #$Pause['Press ENTER to continue...']
+#$End_Section
+
+// ── Lesson 5: Write your own ──────────────────────────────────────
+#$Section['Lesson 5: Your Turn']
+  #$Print['You have now seen:']
+  #$Print['  • Commands   #$Print[text]']
+  #$Print['  • Variables  #$Set[name,value]  →  ${name}']
+  #$Print['  • Pipes      #$Cmd1 | #$Cmd2 | #$Cmd3']
+  #$Print['  • Branching  #$Check_* → #$Branch / #$BranchElse']
+  #$Print['']
+  #$Print['Here is a mini script to try yourself:']
+  #$Print['']
+  #$Color['cyan','  #$Set[city,Paris]']
+  #$Color['cyan','  #$Set[city,${city}] | #$Upper | #$Set[city]']
+  #$Color['cyan','  #$Check_eq[city,PARIS]']
+  #$Color['cyan','  #$Branch']
+  #$Color['cyan','    #$Color[green,City is PARIS!]']
+  #$Color['cyan','  #$End_Branch']
+  #$Print['']
+  #$Print['Save it as test.pd and run:  node cli.js test.pd']
+  #$Pause['Press ENTER to finish...']
+#$End_Section
+
+// ── Reference ─────────────────────────────────────────────────────
+#$Section['Install']
+  #$Table
+    #$Row['Command','What it does']
+    #$Row['npm install','Install dependencies']
+    #$Row['npm link','Install producs globally (optional)']
+  #$End_Table
+#$End_Section
+
+#$Section['Running Scripts']
+  #$Table
+    #$Row['Command','What it does']
+    #$Row['node cli.js script.pd','Run a .pd file']
+    #$Row['node cli.js --demo','Run the built-in feature demo']
+    #$Row['node cli.js --ast script.pd','Dump AST as JSON (no execution)']
+    #$Row['node cli.js --help','Full usage reference']
+    #$Row['producs script.pd','Run globally (after npm link)']
+  #$End_Table
+#$End_Section
+
+#$Section['Check Commands']
+
+  #$Group['String checks (operate on VALUE)']
+    #$Table
+      #$Row['Command','Passes when']
+      #$Row['Check_eq[expected]','VALUE === expected']
+      #$Row['Check_neq[expected]','VALUE !== expected']
+      #$Row['Check_contains[needle]','VALUE contains needle']
+      #$Row['Check_not_contains[needle]','VALUE does NOT contain needle']
+      #$Row['Check_starts[prefix]','VALUE starts with prefix']
+      #$Row['Check_ends[suffix]','VALUE ends with suffix']
+      #$Row['Check_matches[regex]','VALUE matches regex']
+      #$Row['Check_empty','VALUE is empty string']
+      #$Row['Check_nonempty','VALUE is not empty']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Numeric checks']
+    #$Table
+      #$Row['Command','Passes when']
+      #$Row['Check_gt[var,n]','var > n']
+      #$Row['Check_gte[var,n]','var >= n']
+      #$Row['Check_lt[var,n]','var < n']
+      #$Row['Check_lte[var,n]','var <= n']
+      #$Row['Check_num_eq[var,n]','var == n (numeric)']
+      #$Row['Check_num_neq[var,n]','var != n (numeric)']
+      #$Row['Check_between[var,lo,hi]','lo <= var <= hi']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Variable comparison']
+    #$Table
+      #$Row['Command','Passes when']
+      #$Row['Check_var_eq[a,b]','var a === var b']
+      #$Row['Check_var_neq[a,b]','var a !== var b']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Result checks']
+    #$Table
+      #$Row['Command','Passes when']
+      #$Row['Check_failed','Previous result was failed']
+      #$Row['Check_passed','Previous result was passed']
+      #$Row['Check_failed_error[msg]','Throws error if previous result failed']
+      #$Row['Check_passed_error[msg]','Throws error if previous result passed']
+    #$End_Table
+  #$End_Group
+
+#$End_Section
+
+#$Section['Command Reference']
+
+  #$Group['I/O']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['> [prompt]','Prompt block (block form, use #$End_>)']
+      #$Row['Input[prompt]','Prompt for input, pipeable inline → VALUE']
+      #$Row['Print[text]','Print to stdout']
+      #$Row['Warn[text]','Print yellow warning to stderr']
+      #$Row['Error_print[text]','Print red error to stderr']
+      #$Row['Pause[msg]','Block until ENTER']
+      #$Row['Confirm[msg,default]','y/n prompt']
+      #$Row['Select[label,opt1,...]','Numbered menu']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Variables']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Set[name,value]','Set a variable']
+      #$Row['Unset[name]','Delete a variable']
+      #$Row['Export[name,value]','Set variable and push to process.env']
+      #$Row['Env_get[KEY]','Read process.env.KEY into VALUE']
+      #$Row['Env_set[KEY]','Write VALUE into process.env.KEY']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Shell']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Shell_run','Run VALUE/text child as shell command (inherit stdio)']
+      #$Row['Shell_capture','Run command and capture stdout into VALUE']
+    #$End_Table
+  #$End_Group
+
+  #$Group['String ops']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Trim','Remove leading/trailing whitespace']
+      #$Row['Upper','Uppercase VALUE']
+      #$Row['Lower','Lowercase VALUE']
+      #$Row['Len','Length of VALUE']
+      #$Row['Replace[pat,rep,flags]','Regex replace']
+      #$Row['Slice[start,end]','Substring']
+      #$Row['Split[sep]','Split VALUE by separator']
+      #$Row['Join[sep]','Join VALUE by separator']
+      #$Row['Default[fallback]','Use fallback if VALUE is empty']
+      #$Row['Concat[suffix,...]','Append to VALUE']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Math']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Int','Truncate VALUE to integer']
+      #$Row['Float','Parse VALUE as float']
+      #$Row['Abs','Absolute value']
+      #$Row['Round / Floor / Ceil','Rounding']
+      #$Row['Math[expr]','Evaluate JS expression with vars in scope']
+      #$Row['Inc[var,step]','Increment variable']
+      #$Row['Dec[var,step]','Decrement variable']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Data']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Hash[algo]','Hash VALUE (md5, sha256, ...)']
+      #$Row['Timestamp[iso|unix|ms]','Current timestamp']
+      #$Row['Json_get[a.b.c]','Get dot-path from JSON VALUE']
+      #$Row['Json_set[a.b,val]','Set dot-path in JSON VALUE']
+    #$End_Table
+  #$End_Group
+
+  #$Group['File I/O']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Read_file[path]','Read file into VALUE']
+      #$Row['Write_file[path]','Write VALUE to file']
+      #$Row['Append_file[path]','Append VALUE to file']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Control']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Goto[label]','Jump to matching Label']
+      #$Row['Label[name]','Jump target for Goto']
+      #$Row['Exit[code]','Terminate process']
+      #$Row['Assert[expr,msg]','Throw if JS expression is falsy']
+      #$Row['Require_env[VAR]','Throw if env var is unset']
+      #$Row['Require_cmd[cmd]','Throw if command not on PATH']
+      #$Row['Wait[ms]','Blocking sleep in milliseconds']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Blocks']
+    #$Table
+      #$Row['Block','Description']
+      #$Row['#$> [prompt]','Prompt block']
+      #$Row['#$Branch','Run if last check passed (failed=0)']
+      #$Row['#$BranchElse','Run if last check failed (failed=1)']
+      #$Row['#$Repeat[N]','Loop N times (_i = index)']
+      #$Row['#$ForEach[var,a,b,...]','Iterate over items']
+      #$Row['#$Try + #$Catch','Error handling (_error set in Catch)']
+      #$Row['#$Section[title]','Formatted section heading']
+      #$Row['#$Step[desc]','Auto-numbered step']
+      #$Row['#$Group[label]','Logical grouping with bracket lines']
+      #$Row['#$Table + #$Row[...]','ASCII table']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Visual']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['HR[char]','Full-width horizontal rule']
+      #$Row['Header[title]','Prominent banner header']
+      #$Row['Color[name,text]','Print in ANSI color']
+      #$Row['Progress[pct,width,label]','Progress bar']
+      #$Row['Spinner[msg]','Spinner-style status line']
+      #$Row['Status[label]','OK/FAIL badge for current result']
+    #$End_Table
+  #$End_Group
+
+  #$Group['Runtime']
+    #$Table
+      #$Row['Command','Description']
+      #$Row['Debug[on|off]','Toggle verbose debug output']
+      #$Row['Strict[on|off]','Halt on any shell command failure']
+      #$Row['Color_off','Disable ANSI colors']
+      #$Row['Log[label]','Append VALUE + status to execution log']
+      #$Row['Dump_log','Print execution log to stdout']
+      #$Row['Help','List all commands with descriptions']
+      #$Row['Version','Print ProDucs version']
+    #$End_Table
+  #$End_Group
+
+#$End_Section
+
+#$Section['Programmatic API']
+  #$Step['Require the module']
+    #$Color['cyan','const { ProDucs } = require("producs");']
+  #$End_Step
+  #$Step['Create an instance']
+    #$Color['cyan','const prod = new ProDucs({ debug: false, strict: false, noColor: false });']
+  #$End_Step
+  #$Step['Register a custom command']
+    #$Color['cyan','prod.register("Shout", (node, input) => {']
+    #$Color['cyan','  const msg = input.VALUE.toUpperCase() + "!!!";']
+    #$Color['cyan','  process.stdout.write(msg + "\\n");']
+    #$Color['cyan','  return { VALUE: msg, failed: 0 };']
+    #$Color['cyan','}, { doc: "Uppercase and add exclamation marks" });']
+  #$End_Step
+  #$Step['Pre-set variables and run a script']
+    #$Color['cyan','prod.set("env", "production");']
+    #$Color['cyan','prod.run(`#$Set[greeting,hello] | #$Shout`);']
+    #$Color['cyan','console.log(prod.vars()); // { greeting: "HELLO!!!", env: "production" }']
+  #$End_Step
+#$End_Section
+
+// ── Live footer ───────────────────────────────────────────────────
+#$Section['About this file']
+  #$Print['This README is a valid ProDucs script.']
+  #$Print['Every section, table, and lesson above was rendered by ProDucs itself.']
+  #$HR['-']
+  #$Timestamp['iso'] | #$Set['now']
+  #$Color['green','✔ Rendered at ${now}']
+  #$Version
+#$End_Section
+
+#$HR['═']
+#$Color['green','Thanks for going through it, ${user}!']
+#$Status['ProDucs README']