@hivecommons/promptargs 0.6.0 → 0.8.0

package/README.md

@@ -1,6 +1,12 @@
+<p align="center">
+  <img src="docs/assets/promptargs-logo.svg" alt="Promptargs" width="120" height="120">
+</p>
+
 # promptargs 🏴‍☠️
 
-**Template arguments for AI prompts.**
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+Template arguments for AI prompts.
 
 You write a prompt with blanks (`{{like_this}}`), and promptargs fills them in.
 
@@ -22,6 +28,8 @@ Works as a **CLI** and as a **skill** in Claude Code, Copilot, Goose, and Bob.
 
 ## Install
 
+Requires Node.js 22 or newer.
+
 ### CLI
 
 ```bash
@@ -34,9 +42,29 @@ Or just run it without installing:
 npx @hivecommons/promptargs help
 ```
 
-### As a Slash Command / Skill
+### As an Agent Skill
+
+promptargs ships an [Agent Skill](https://agentskills.io/specification) at [`skills/promptargs/SKILL.md`](skills/promptargs/SKILL.md), loaded by GitHub Copilot (CLI, cloud agent, VS Code agent mode) and Claude Code.
+
+**With the GitHub CLI** (2.90.0 or later):
+```bash
+gh skill install hivecommons/promptargs promptargs
+```
+
+**Manually** (copy the `skills/promptargs/` directory):
+```bash
+# Copilot
+mkdir -p ~/.copilot/skills
+cp -r skills/promptargs ~/.copilot/skills/
+
+# Claude Code
+mkdir -p ~/.claude/skills
+cp -r skills/promptargs ~/.claude/skills/
+```
+
+Use `.github/skills/` or `.claude/skills/` inside a project instead to share it with your team.
 
-This repo ships skill files for multiple AI coding tools. Install the one(s) you use:
+### As a Slash Command (other tools)
 
 **Claude Code:**
 ```bash
@@ -59,8 +87,6 @@ curl -o ~/.bob/skills/promptargs.md \
   https://raw.githubusercontent.com/hivecommons/promptargs/main/.bob/skills/promptargs.md
 ```
 
-**Copilot:** Automatically detected from `.github/copilot-instructions.md` when you clone this repo.
-
 ---
 
 ## Quick Start (3 steps)
@@ -116,7 +142,15 @@ A blank looks like this: `{{name}}`
 
 A blank with a default looks like this: `{{name=hello}}` (promptargs extension)
 
-That's the basics. You also get the full Mustache spec — comments (`{{! ignore me}}`), sections, partials, and more.
+Padding inside the braces is fine too — `{{ name }}` and `{{ name=hello }}` mean the same thing.
+
+Names may use letters, digits, `_` and `-` (`{{file-name}}`). Dotted names such as `{{repo.owner}}` are rejected with an error — use `{{repo_owner}}`; the switch names `no-interactive`, `cross`, `json` and `status` are also rejected, as they are reserved for CLI switches. Likewise, the template file names `help`, `env`, `ui`, `init`, `list` and `show` are reserved for the subcommands of the same name; such a template is listed as unreachable by `promptargs list` (and `show` warns), because the subcommand always wins.
+
+A default may appear on any occurrence of a blank (`{{name}} … {{name=hello}}`); if two occurrences give different defaults, the first one wins.
+
+That's the basics. Mustache comments (`{{! ignore me}}`) work as documented and are safe to use.
+
+Mustache **sections** (`{{#flag}}...{{/flag}}`) and **partials** (`{{>name}}`) are parsed too, but aren't practically usable yet: promptargs only resolves plain `{{name}}` / `{{name=default}}` tags from `--flag=value`, auto-detected context, defaults, or interactive fill — a section's condition name is never filled this way (so its content is always dropped, or always kept for an inverted `{{^name}}` section), and partial content is never supplied, so `{{>name}}` always expands to nothing. Stick to plain blanks and comments; avoid sections and partials for now.
 
 ### Red means "you need to fill this in"
 
@@ -212,6 +246,34 @@ promptargs "Review {{file}} for {{focus}}" \
 ✅ [3/3]: file=db.go    focus=correctness
 ```
 
+When arrays have different lengths, the number of runs is the length of the longest array, and shorter arrays repeat (cycle around):
+
+```bash
+promptargs "Review {{file}} for {{focus}}" \
+  --file=api.go,auth.go,db.go \
+  --focus=security
+```
+
+```
+✅ [1/3]: file=api.go   focus=security
+✅ [2/3]: file=auth.go  focus=security
+✅ [3/3]: file=db.go    focus=security
+```
+
+Or with two unequal arrays:
+
+```bash
+promptargs "Review {{file}} for {{focus}}" \
+  --file=a.go,b.go,c.go \
+  --focus=x,y
+```
+
+```
+✅ [1/3]: file=a.go  focus=x
+✅ [2/3]: file=b.go  focus=y
+✅ [3/3]: file=c.go  focus=x
+```
+
 **Cross-product mode (`--cross`):** every combination of every value:
 
 ```bash
@@ -246,12 +308,20 @@ promptargs "Review {{file}} for {{focus}}" \
 
 Project templates override personal ones with the same name.
 
+Symlinked `*.md` entries are followed only when their real target is inside the same `.prompts/` directory (a sub-directory is fine); a symlink whose target escapes the directory is listed with an error and refused when run, so a cloned repo cannot make `promptargs` read files elsewhere on your machine. Symlinks to directories and dangling symlinks are skipped.
+
 ---
 
 ## Auto-Magic Variables ✨
 
 promptargs discovers variables from two sources:
 
+Run `promptargs env` any time to preview exactly what's auto-detected in your current shell before you run a template:
+
+```bash
+promptargs env
+```
+
 ### 1. Git context (always detected)
 
 These variable names fill themselves automatically when you're in a git repo:
@@ -277,16 +347,20 @@ promptargs "Connect to {{DATABASE_URL}} in {{AWS_REGION}}"
 
 In the **Builder UI** (`promptargs ui`), click "Show terminal env" to see all available env vars from your shell. Click any one to insert it at the cursor.
 
-Common useful env vars: `NODE_ENV`, `AWS_REGION`, `DATABASE_URL`, `GITHUB_TOKEN`, `CI`, `USER`, `EDITOR`, `PATH`.
+Common useful env vars: `NODE_ENV`, `AWS_REGION`, `CI`, `USER`, `EDITOR`, `PATH`, `SHELL`.
+
+Credential-looking names are intentionally **excluded** from auto-detection: anything containing `TOKEN`, `SECRET`, `PASSWORD`/`PASSWD`/`PASSPHRASE`, `CREDENTIAL`, `API_KEY`/`ACCESS_KEY`/`PRIVATE_KEY`, `BEARER`, `COOKIE`, `WEBHOOK`, `JWT`, `HMAC`, `OAUTH`, `CONNECTION_STRING`, or the `_`-delimited words `AUTH`, `KEY`/`KEYS`, `PWD`, `PAT`, `PASS`, `DSN` (so `GITHUB_TOKEN`, `SIGNING_KEY`, `MYSQL_PWD`, `GITHUB_PAT` and `SLACK_WEBHOOK_URL` are all refused, while `PATH`, `PWD`, `KEYBOARD` and `AUTHOR` still work). Credential-**shaped** values are excluded whatever the name: URLs with a password in them (`postgres://user:pass@host/db`), PEM blocks, JWTs, and well-known token prefixes (`ghp_`, `github_pat_`, `glpat-`, `sk-`, `xoxb-`, `AKIA…`, `npm_…`, …). A repo-controlled template can therefore never expand `{{GITHUB_TOKEN}}` or `{{DATABASE_URL}}` into a secret, even though an explicit `--flag=value` can still pass any value you choose. This also applies to the Builder UI's "Show terminal env" list.
 
 ### Priority
 
 You can always override any auto-detected value with a flag. The order is:
 
 1. `--flag=value` (explicit, always wins)
-2. Interactive prompt (if no flag and not `--no-interactive`)
-3. Auto-detect from environment
-4. Template default (`{{name=fallback}}`)
+2. Auto-detect from environment (git context and terminal env vars)
+3. Template default (`{{name=fallback}}`)
+4. Interactive prompt — only for variables still unfilled, and only without `--no-interactive`
+
+A variable that auto-detects or has a default is never prompted for; pass `--name=value` to override it.
 
 ---
 
@@ -343,6 +417,41 @@ promptargs ui --port=4000
 
 ---
 
+## Privacy & Diagnostics
+
+promptargs does not collect or export telemetry. There is no telemetry SDK, metrics endpoint, or observability backend configured anywhere in this package — nothing you run ever phones home.
+
+All runtime diagnostics are human-readable console output (CLI status/errors, UI startup/port messages). The **Builder UI** (`promptargs ui`) binds to loopback only (`127.0.0.1`) and rejects requests with a non-local `Host` header, so the page — including the auto-detected Git and terminal environment values it embeds (see [Auto-Magic Variables](#auto-magic-variables-)) — is never reachable from other machines on your network.
+
+**Opt-in structured diagnostics:** set `PROMPTARGS_LOG=json` to make diagnostics (CLI errors and iteration progress, UI Host rejections, asset failures, unreadable prompts directories, and one line per UI request) print as JSON lines on stderr with a fixed field set: `event`, plus `status`, `duration_ms`, `error_class` (`usage`, `not_found`, `io`, `port_in_use`, `unknown`), `count`, `current`, `total` where relevant. Template contents, argument values, paths and error messages are never logged. When unset, output is unchanged. Nothing is sent over the network.
+
+If observability is ever added in the future, it will be explicit opt-in, bounded to local diagnostics, and will exclude environment values, template/prompt content, file paths, diffs, and user identifiers. No network exporter will be added unless you explicitly configure a backend yourself.
+
+---
+
+## Use as a Library
+
+The package also exports its building blocks as an ES module (Node.js 22+). Install it first with `npm install @hivecommons/promptargs`.
+
+```js
+import { parseVars, expand } from '@hivecommons/promptargs';
+
+const template = 'Review {{file}} for {{focus=correctness}} issues.';
+
+parseVars(template);
+// [{ name: 'file', ... }, { name: 'focus', defaultValue: 'correctness', ... }]
+
+expand(template, { file: 'src/app.ts', focus: 'security' });
+// 'Review src/app.ts for security issues.'
+
+expand(template, { file: 'src/app.ts' });
+// 'Review src/app.ts for correctness issues.'  (defaults fill missing values)
+```
+
+Variables with no value and no default are left as `{{name}}` in the output. Other exports: `autodetect`, `autodetectAll`, `AUTODETECT_VARS`, `loadTemplates`, `findTemplate`, `resolve` and `renderStatus`.
+
+---
+
 ## Write Your Own Template
 
 Create a file in `.prompts/` with any name ending in `.md`:
@@ -379,13 +488,13 @@ promptargs review --file=src/main.ts --no-interactive | claude -p "do this revie
 # Goose
 promptargs review --file=src/main.ts --no-interactive | goose run
 
-# Copilot
-promptargs review --file=src/main.ts --no-interactive | gh copilot explain
+# Copilot CLI (needs the standalone `copilot` CLI, installed and signed in)
+copilot -p "$(promptargs review --file=src/main.ts --no-interactive)"
 ```
 
 ### As a skill inside your AI tool
 
-If you installed the skill (see [Install](#as-a-skill)), use it directly inside your session:
+If you installed the skill (see [Install](#as-an-agent-skill)), use it directly inside your session:
 
 **Claude Code:**
 ```
@@ -394,7 +503,7 @@ If you installed the skill (see [Install](#as-a-skill)), use it directly inside
 
 **Goose / Bob:** The skill is automatically available after install — ask your agent to "use promptargs" or run a template.
 
-**Copilot:** The instructions in `.github/copilot-instructions.md` teach Copilot about promptargs when you're in a repo that has it.
+**Copilot:** Installed skills load automatically; ask Copilot to use promptargs.
 
 ---
 
@@ -409,6 +518,7 @@ If you installed the skill (see [Install](#as-a-skill)), use it directly inside
 | `promptargs review --file=x` | Run template with flags |
 | `promptargs review` | Run template interactively |
 | `promptargs "inline {{var}}"` | Use inline template |
+| `promptargs env` | Show auto-detected variable values |
 | `--no-interactive` | Skip questions, use defaults only |
 | `--cross` | Cross-product mode (all combinations) |
 | `--json` | Output as JSON |
@@ -416,8 +526,23 @@ If you installed the skill (see [Install](#as-a-skill)), use it directly inside
 | `... \| claude -p "do this"` | Pipe to Claude |
 | `... \| goose run` | Pipe to Goose |
 
+The switch names `no-interactive`, `cross`, `json` and `status` are reserved and cannot be used as template variable names.
+
+---
+
+## Contributing & Community
+
+promptargs is part of [Hive Commons](https://hivecommons.dev), a family of tools for working with AI agents.
+
+- Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks, and pull request guidelines.
+- Found a bug or have an idea? Open an [issue](https://github.com/hivecommons/promptargs/issues).
+- Reporting a security vulnerability? Follow [SECURITY.md](SECURITY.md) to report it privately, not through public issues.
+- Please follow the [Hive Commons Code of Conduct](https://github.com/hivecommons/.github/blob/main/CODE_OF_CONDUCT.md).
+
 ---
 
 ## License
 
 Apache-2.0
+
+Pirate flag icon: [Twemoji](https://twemoji.twitter.com/), [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/).

package/dist/autodetect.d.ts

@@ -2,5 +2,7 @@
  * Auto-detect variable values from the current environment.
  */
 export declare const AUTODETECT_VARS: string[];
+export declare function isSensitiveEnvName(name: string): boolean;
+export declare function isSensitiveEnvValue(value: string): boolean;
 export declare function autodetect(varName: string): string | undefined;
 export declare function autodetectAll(varNames: string[]): Record<string, string>;

package/dist/autodetect.js

@@ -2,9 +2,24 @@
  * Auto-detect variable values from the current environment.
  */
 import { execSync } from 'node:child_process';
+// gh is the only network call on the UI startup path; bound it so a stalled gh
+// (hung proxy, expired auth) cannot hang startup.
+const GH_TIMEOUT_MS = 5000;
+// execSync's default 1 MiB maxBuffer makes `git diff` on a large staged change
+// throw ENOBUFS, which the catch below turns into a silent "nothing detected"
+// (#281). Raise it so large diffs are returned rather than dropped.
+const GIT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 function git(cmd) {
     try {
-        return execSync(`git ${cmd}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const out = execSync(`git ${cmd}`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: GIT_MAX_BUFFER_BYTES,
+        }).trim();
+        // Success with empty output (detached HEAD for `branch --show-current`,
+        // clean tree for `diff`) is "nothing detected", not an empty value —
+        // otherwise it would override the template default and skip the prompt.
+        return out || undefined;
     }
     catch {
         return undefined;
@@ -32,6 +47,7 @@ const DETECTORS = {
             const out = execSync('gh pr view --json number --jq .number', {
                 encoding: 'utf8',
                 stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: GH_TIMEOUT_MS,
             }).trim();
             return out || undefined;
         }
@@ -40,15 +56,64 @@ const DETECTORS = {
         }
     },
     user: () => git('config user.name'),
-    date: () => new Date().toISOString().split('T')[0],
+    date: () => new Date().toLocaleDateString('sv-SE'),
 };
 export const AUTODETECT_VARS = Object.keys(DETECTORS);
+// Env var names that look like credentials. The implicit process.env fallback
+// must never expand these into prompt output (templates are repo-controlled),
+// and the builder UI must never embed them in the served page.
+//
+// Word-bounded alternatives use (^|_)…(_|$) so PATH, KEYBOARD, PWD (the shell
+// cwd) and AUTHOR stay detectable while GITHUB_PAT, SIGNING_KEY, MYSQL_PWD and
+// AUTH_HEADER do not.
+const SENSITIVE_ENV_PATTERN = new RegExp([
+    'TOKEN', 'SECRET', 'PASSWORD', 'PASSWD', 'PASSPHRASE', 'CREDENTIAL',
+    'API_?KEY', 'ACCESS_KEY', 'PRIVATE_KEY', 'BEARER', 'COOKIE', 'WEBHOOK',
+    'JWT', 'HMAC', 'OAUTH', 'AUTHORI[SZ]ATION', 'CONN(?:ECTION)?_?STR(?:ING)?',
+    '(?:^|_)AUTH(?:_|$)', '(?:^|_)KEYS?(?:_|$)', '_PWD(?:_|$)',
+    '(?:^|_)PAT(?:_|$)', '(?:^|_)PASS(?:_|$)', '(?:^|_)DSN(?:_|$)',
+].join('|'), 'i');
+export function isSensitiveEnvName(name) {
+    return SENSITIVE_ENV_PATTERN.test(name);
+}
+// Values that are credentials regardless of what the variable is called:
+// a URL carrying a password in its userinfo (DATABASE_URL, REDIS_URL,
+// MONGO_URI, SENTRY_DSN), PEM blocks, JWTs, HTTP Authorization header values
+// (Bearer/Basic), and the fixed prefixes vendors stamp on their tokens so
+// scanners can recognise them.
+const SENSITIVE_ENV_VALUE_PATTERN = new RegExp([
+    '^[a-z][a-z0-9+.-]*://[^/\\s:@]*:[^/\\s@]+@',
+    '-----BEGIN ',
+    '^eyJ[\\w-]+\\.eyJ[\\w-]+\\.',
+    '^(?:Bearer|Basic)\\s+\\S+',
+    '^(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{20,}',
+    '^glpat-[\\w-]{20,}',
+    '^sk-[A-Za-z0-9_-]{20,}',
+    '^sk_(?:live|test)_[A-Za-z0-9]{10,}',
+    '^xox[abprs]-[\\w-]{10,}',
+    '^AKIA[0-9A-Z]{16}$',
+    '^AIza[\\w-]{35}$',
+    '^npm_[A-Za-z0-9]{36}$',
+    '^hvs\\.[\\w-]{20,}',
+].join('|'), 'i');
+export function isSensitiveEnvValue(value) {
+    return SENSITIVE_ENV_VALUE_PATTERN.test(value);
+}
 export function autodetect(varName) {
-    const detector = DETECTORS[varName];
-    if (detector)
-        return detector();
-    // Fall back to terminal environment variables
-    return process.env[varName] ?? undefined;
+    // Own-property check: {{constructor}} / {{toString}} must not resolve to
+    // Object.prototype members.
+    if (Object.hasOwn(DETECTORS, varName))
+        return DETECTORS[varName]();
+    // Fall back to terminal environment variables — but never implicitly expand
+    // credential-looking names ({{GITHUB_TOKEN}} in a repo template must not
+    // exfiltrate secrets into the generated prompt) or credential-shaped values
+    // under innocuous names ({{DATABASE_URL}}). Explicit --flags still work.
+    if (isSensitiveEnvName(varName) || !Object.hasOwn(process.env, varName))
+        return undefined;
+    const value = process.env[varName];
+    if (value === undefined || isSensitiveEnvValue(value))
+        return undefined;
+    return value;
 }
 export function autodetectAll(varNames) {
     const result = {};

package/dist/autodetect.js.map

@@ -1 +1 @@
-{"version":3,"file":"autodetect.js","sourceRoot":"","sources":["../src/autodetect.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,SAAS,GAAG,CAAC,GAAW;IACtB,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,OAAO,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,SAAS,GAA6C;IAC1D,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,uBAAuB,CAAC;IAC1C,IAAI,EAAE,GAAG,EAAE;QACT,MAAM,MAAM,GAAG,GAAG,CAAC,uBAAuB,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACpD,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,GAAG,EAAE,GAAG,EAAE;QACR,MAAM,MAAM,GAAG,GAAG,CAAC,uBAAuB,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACjE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC;IAC/C,EAAE,EAAE,GAAG,EAAE;QACP,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,QAAQ,CAAC,uCAAuC,EAAE;gBAC5D,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;aAChC,CAAC,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,GAAG,IAAI,SAAS,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC;IACnC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACnD,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAEtD,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,QAAQ;QAAE,OAAO,QAAQ,EAAE,CAAC;IAChC,8CAA8C;IAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,SAAS,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC9C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"autodetect.js","sourceRoot":"","sources":["../src/autodetect.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,+EAA+E;AAC/E,kDAAkD;AAClD,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B,+EAA+E;AAC/E,8EAA8E;AAC9E,oEAAoE;AACpE,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9C,SAAS,GAAG,CAAC,GAAW;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,GAAG,EAAE,EAAE;YACjC,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YAC/B,SAAS,EAAE,oBAAoB;SAChC,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,wEAAwE;QACxE,qEAAqE;QACrE,wEAAwE;QACxE,OAAO,GAAG,IAAI,SAAS,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,SAAS,GAA6C;IAC1D,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,uBAAuB,CAAC;IAC1C,IAAI,EAAE,GAAG,EAAE;QACT,MAAM,MAAM,GAAG,GAAG,CAAC,uBAAuB,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACpD,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,GAAG,EAAE,GAAG,EAAE;QACR,MAAM,MAAM,GAAG,GAAG,CAAC,uBAAuB,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACjE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC;IAC/C,EAAE,EAAE,GAAG,EAAE;QACP,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,QAAQ,CAAC,uCAAuC,EAAE;gBAC5D,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;gBAC/B,OAAO,EAAE,aAAa;aACvB,CAAC,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,GAAG,IAAI,SAAS,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC;IACnC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC;CACnD,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,8EAA8E;AAC9E,+DAA+D;AAC/D,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,sBAAsB;AACtB,MAAM,qBAAqB,GAAG,IAAI,MAAM,CACtC;IACE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY;IACnE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS;IACtE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,8BAA8B;IAC1E,oBAAoB,EAAE,qBAAqB,EAAE,aAAa;IAC1D,mBAAmB,EAAE,oBAAoB,EAAE,mBAAmB;CAC/D,CAAC,IAAI,CAAC,GAAG,CAAC,EACX,GAAG,CACJ,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,yEAAyE;AACzE,sEAAsE;AACtE,6EAA6E;AAC7E,0EAA0E;AAC1E,+BAA+B;AAC/B,MAAM,2BAA2B,GAAG,IAAI,MAAM,CAC5C;IACE,4CAA4C;IAC5C,aAAa;IACb,6BAA6B;IAC7B,2BAA2B;IAC3B,8CAA8C;IAC9C,oBAAoB;IACpB,wBAAwB;IACxB,oCAAoC;IACpC,yBAAyB;IACzB,oBAAoB;IACpB,kBAAkB;IAClB,uBAAuB;IACvB,oBAAoB;CACrB,CAAC,IAAI,CAAC,GAAG,CAAC,EACX,GAAG,CACJ,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,2BAA2B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,yEAAyE;IACzE,4BAA4B;IAC5B,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;IACnE,4EAA4E;IAC5E,yEAAyE;IACzE,4EAA4E;IAC5E,yEAAyE;IACzE,IAAI,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1F,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,IAAI,mBAAmB,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC9C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cli.js

@@ -9,14 +9,15 @@
  *   promptargs init                     # create .prompts/ with examples
  *   promptargs show <template>          # show template with vars highlighted
  */
-import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
 import { parseVars, expand } from './parser.js';
-import { findTemplate, loadTemplates } from './loader.js';
+import { findTemplate } from './loader.js';
 import { resolve } from './resolver.js';
 import { renderStatus } from './status.js';
-import { autodetect, AUTODETECT_VARS } from './autodetect.js';
 import { startUI } from './ui.js';
+import { UsageError, assertNoReservedVars, parseFlags, parsePort, SUBCOMMANDS } from './flags.js';
+import { diag, classifyError } from './log.js';
+import { doInit, doList, doShow, printEnv } from './commands.js';
+import { sanitizeForTerminal } from './sanitize.js';
 const HELP = `
 promptargs — Template arguments for AI prompts 🏴‍☠️
 
@@ -33,9 +34,9 @@ Usage:
 Flags:
   --no-interactive    Skip interactive prompts (use defaults/auto only)
   --cross             Cross-product mode: all combinations of array values
-  --parallel          Run array iterations in parallel (print all at once)
   --json              Output as JSON instead of plain text
   --status            Print status line only (for IDE integration)
+  --var value         Same as --var=value (switches above take no value)
 
 Array values:
   --file=a.go,b.go    Comma-separated → one run per value
@@ -43,54 +44,48 @@ Array values:
   --file=@list.txt    File → one value per line
 
 Iteration modes:
-  Default (zip):      --file=a,b --focus=x,y  → 2 runs (a+x, b+y)
+  Default (zip):      --file=a,b --focus=x,y  → 2 runs (a+x, b+y); shorter arrays repeat
   Cross-product:      --file=a,b --focus=x,y --cross  → 4 runs (a+x, a+y, b+x, b+y)
 
 Templates live in:
   .prompts/           Project-level (checked into repo)
   ~/.prompts/         User-level (personal templates)
 `;
-const EXAMPLE_REVIEW = `Review {{file}} for {{focus=correctness}} issues.
-Be {{tone=concise}} in your feedback.
-Focus on real bugs, not style nitpicks.
-`;
-const EXAMPLE_EXPLAIN = `Explain what {{file}} does in {{style=simple}} terms.
-Assume the reader is a {{audience=junior developer}}.
-`;
-const EXAMPLE_FIX = `Fix the {{issue}} in {{file}}.
-The expected behavior is: {{expected}}
-The actual behavior is: {{actual}}
-`;
+// The shared set supplies the runtime gate and its names supply the key union.
+// The Record makes adding a subcommand without a handler (or vice versa) a type error.
+const SUBCOMMAND_HANDLERS = {
+    help: () => {
+        console.log(HELP);
+        printEnv();
+    },
+    env: () => printEnv(),
+    ui: (args) => {
+        const flags = parseFlags(args);
+        startUI(parsePort(flags));
+    },
+    init: () => doInit(),
+    list: () => doList(),
+    show: (args) => doShow(args[0]),
+};
+function isSubcommand(value) {
+    return SUBCOMMANDS.has(value);
+}
 async function main() {
     const args = process.argv.slice(2);
-    if (args.length === 0 || args[0] === 'help' || args[0] === '--help') {
+    if (args.length === 0 || args[0] === '--help') {
         console.log(HELP);
         printEnv();
         return;
     }
-    if (args[0] === 'env') {
-        printEnv();
+    const command = args[0];
+    if (isSubcommand(command)) {
+        await SUBCOMMAND_HANDLERS[command](args.slice(1));
         return;
     }
-    if (args[0] === 'ui') {
-        const flags = parseFlags(args.slice(1));
-        const port = flags['port'] ? Number(flags['port']) : undefined;
-        startUI(port);
-        return;
-    }
-    if (args[0] === 'init') {
-        return doInit();
-    }
-    if (args[0] === 'list') {
-        return doList();
-    }
-    if (args[0] === 'show') {
-        return doShow(args[1]);
-    }
     // Run a template
     const templateName = args[0];
     const flags = parseFlags(args.slice(1));
-    const interactive = !flags['no-interactive'];
+    const interactive = !flags['no-interactive'] && process.stdin.isTTY === true;
     const cross = 'cross' in flags;
     const asJson = 'json' in flags;
     const statusOnly = 'status' in flags;
@@ -104,24 +99,31 @@ async function main() {
     else {
         const tpl = findTemplate(templateName);
         if (!tpl) {
-            console.error(`Template "${templateName}" not found.`);
-            console.error('Run "promptargs list" to see available templates.');
-            console.error('Run "promptargs init" to create example templates.');
-            process.exit(1);
-            return;
+            throw new UsageError(`Template "${templateName}" not found.\n` +
+                'Run "promptargs list" to see available templates.\n' +
+                'Run "promptargs init" to create example templates.');
         }
         content = tpl.content;
         name = tpl.name;
     }
     const vars = parseVars(content);
+    assertNoReservedVars(vars);
     if (vars.length === 0) {
-        // No variables — just output the template as-is
-        console.log(content);
+        // No variables — skip expand() so Mustache-style content that is not a promptargs blank stays untouched
+        if (statusOnly) {
+            console.log(renderStatus(name, vars, {}, undefined, new Set()));
+        }
+        else if (asJson) {
+            console.log(JSON.stringify(content, null, 2));
+        }
+        else {
+            console.log(content);
+        }
         return;
     }
-    const { iterations } = await resolve(vars, flags, interactive, cross);
+    const { iterations, defaulted } = await resolve(vars, flags, interactive, cross);
     if (statusOnly) {
-        const status = renderStatus(name, vars, iterations[0]);
+        const status = renderStatus(name, vars, iterations[0], undefined, defaulted);
         console.log(status);
         return;
     }
@@ -133,8 +135,8 @@ async function main() {
             const status = renderStatus(name, vars, values, {
                 current: i + 1,
                 total: iterations.length,
-            });
-            console.error(status);
+            }, defaulted);
+            diag('cli_iteration', { current: i + 1, total: iterations.length }, status);
         }
         results.push(expanded);
     }
@@ -145,101 +147,8 @@ async function main() {
         console.log(results.join('\n---\n'));
     }
 }
-function parseFlags(args) {
-    const flags = {};
-    for (const arg of args) {
-        if (arg.startsWith('--')) {
-            const eq = arg.indexOf('=');
-            if (eq > 0) {
-                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
-            }
-            else {
-                flags[arg.slice(2)] = 'true';
-            }
-        }
-    }
-    return flags;
-}
-function doInit() {
-    const dir = join(process.cwd(), '.prompts');
-    if (existsSync(dir)) {
-        console.log('.prompts/ already exists!');
-        return;
-    }
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'review.md'), EXAMPLE_REVIEW);
-    writeFileSync(join(dir, 'explain.md'), EXAMPLE_EXPLAIN);
-    writeFileSync(join(dir, 'fix.md'), EXAMPLE_FIX);
-    console.log('Created .prompts/ with 3 example templates:');
-    console.log('  review.md  — Code review with focus area');
-    console.log('  explain.md — Explain code simply');
-    console.log('  fix.md     — Bug fix template');
-    console.log('');
-    console.log('Try it: promptargs review --file=src/main.ts');
-}
-function doList() {
-    const templates = loadTemplates();
-    if (templates.length === 0) {
-        console.log('No templates found.');
-        console.log('Run "promptargs init" to create example templates.');
-        return;
-    }
-    console.log('Available templates:\n');
-    for (const t of templates) {
-        const vars = parseVars(t.content);
-        const varNames = vars.map(v => {
-            if (v.defaultValue !== undefined)
-                return `${v.name}=${v.defaultValue}`;
-            return v.name;
-        });
-        const source = t.source === 'user' ? ' (user)' : '';
-        console.log(`  ${t.name}${source}`);
-        console.log(`    vars: {{${varNames.join('}}  {{')}}}`);
-        console.log('');
-    }
-}
-function doShow(templateName) {
-    if (!templateName) {
-        console.error('Usage: promptargs show <template>');
-        process.exit(1);
-        return;
-    }
-    const tpl = findTemplate(templateName);
-    if (!tpl) {
-        console.error(`Template "${templateName}" not found.`);
-        process.exit(1);
-        return;
-    }
-    const highlighted = tpl.content.replace(/\{\{(\w+)(?:=([^}]*))?\}\}/g, (_m, varName, defaultVal) => {
-        if (defaultVal !== undefined) {
-            return `\x1b[33m{{${varName}=${defaultVal}}}\x1b[0m`;
-        }
-        return `\x1b[31m{{${varName}}}\x1b[0m`;
-    });
-    console.log(`Template: ${tpl.name} (${tpl.path})\n`);
-    console.log(highlighted);
-    console.log('\n\x1b[31mred\x1b[0m = required  \x1b[33myellow\x1b[0m = has default');
-}
-const DIFF_PREVIEW_MAX_CHARS = 60;
-function printEnv() {
-    console.log('Auto-detected variables:\n');
-    for (const name of AUTODETECT_VARS) {
-        const value = autodetect(name);
-        if (value !== undefined) {
-            let display = value;
-            if (name === 'diff' && display.length > DIFF_PREVIEW_MAX_CHARS) {
-                display = display.slice(0, DIFF_PREVIEW_MAX_CHARS) + '...';
-            }
-            console.log(`  \x1b[32m{{${name}}}\x1b[0m = ${display}`);
-        }
-        else {
-            console.log(`  \x1b[90m{{${name}}}\x1b[0m = (not detected)`);
-        }
-    }
-    console.log('');
-}
 main().catch(err => {
-    console.error(err.message);
+    diag('cli_error', { error_class: classifyError(err) }, sanitizeForTerminal(String(err.message)));
     process.exit(1);
 });
 //# sourceMappingURL=cli.js.map