IMPROVEMENT: allow_regex and deny_regex hardened to allow flags, and handle malformed regex' better

Author: PredictabilityAtScale

README.md

@@ -63,9 +63,14 @@ sampling:
   temperature: 0.7
 context:
   inputs:
-    - user_message
+    - name: user_message
+      non_empty: true
+      reject_secrets: true
     - name: app_context
       max_size: 2000
+      allow_regex:
+        pattern: "^[A-Za-z0-9 _-]+$"
+        flags: "i"
 includes:
   - ./shared/tone.md
 ---
@@ -127,11 +132,12 @@ Supported values for `warnings.contextSize` are `auto`, `off`, `result-only`, `c
 - **Overrides** — Environment and tier-based overrides (base → env → tier → runtime)
 - **4 provider adapters** — OpenAI, Anthropic, Gemini, OpenRouter — body-only output
 - **Validation** — Zod schema validation, Levenshtein-based "did you mean?" for typos, variable usage checks
+- **Context hardening** — structured regexes with flags, `/pattern/i` convenience syntax, and built-in `non_empty` / `reject_secrets` validators
 - **Context size guardrails** — optional per-input `max_size` metadata with non-blocking render-time warnings
 - **Warning controls** — top-level config can suppress or emit context size warnings differently in dev and prod
 - **Caching** — LRU cache with mtime-based invalidation
 - **CLI** — init, validate, compile, render, inspect, skill
-- **Compiled artifacts** — Pre-compile `.md` → JSON or ESM for production
+- **Compiled artifacts** — Pre-compile `.md` → JSON or ESM for production, with validation before artifacts are written
 
 ## Provider Adapters
 
@@ -381,10 +387,10 @@ promptopskit init [dir]
 promptopskit skill
 
 # Validate all .md files in a directory
-promptopskit validate <dir> [--strict]
+promptopskit validate [sourceDir] [--source <dir>] [--strict]
 
 # Compile .md → JSON/ESM artifacts
-promptopskit compile [src] [out] [--dry-run] [--format json|esm] [--no-clean]
+promptopskit compile [sourceDir] [outputDir] [--source <dir>] [--output <dir>] [--dry-run] [--format json|esm] [--no-clean]
 
 # Render a prompt preview (auto-loads .test.yaml sidecar)
 promptopskit render <file> [--env <name>] [--tier <name>] [--vars <file>] [--json]
@@ -507,7 +513,7 @@ Prompt files use YAML front matter with these fields:
 | `response` | `object` | `{ format, stream }` |
 | `tools` | `array` | Tool references (string names or inline definitions) |
 | `mcp` | `object` | MCP server references |
-| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `max_size`, `trim`, and `allow_regex`/`deny_regex` controls |
+| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `max_size`, `trim`, structured or literal `allow_regex`/`deny_regex`, and built-in `non_empty` / `reject_secrets` validators |
 | `includes` | `string[]` | Paths to included prompt files |
 | `environments` | `object` | Named environment overrides |
 | `tiers` | `object` | Named tier overrides |

SKILL.md

@@ -66,7 +66,7 @@ the fields required by that specific file:
 | `response` | object | no | `{ format: text|json|markdown, stream: boolean }` |
 | `tools` | array | no | Tool names (strings) or inline definitions with `{ name, description, input_schema }` |
 | `mcp` | object | no | `{ servers: [string | { name, config }] }` |
-| `context.inputs` | `Array<string | { name, max_size?, trim?, allow_regex?, deny_regex? }>` | no | Declared variable names used in templates, with optional size budgets and runtime hardening controls |
+| `context.inputs` | `Array<string | { name, max_size?, trim?, allow_regex?, deny_regex?, non_empty?, reject_secrets? }>` | no | Declared variable names used in templates, with optional size budgets and runtime hardening controls |
 | `context.history` | object | no | `{ max_items: number }` |
 | `includes` | string[] | no | Relative paths to other prompt files to include |
 | `environments` | object | no | Per-environment overrides (see Overrides) |
@@ -102,6 +102,8 @@ Rules:
 - Use object-form inputs with `max_size` when a variable is likely to grow large and should trigger early warnings
 - Use `trim` to enforce byte budgets before interpolation when `max_size` is set
 - Use `allow_regex` for allowlist checks and `deny_regex` for blocklist checks on risky inputs
+- Prefer structured regexes like `{ pattern, flags }`; `/pattern/i` strings are also accepted and normalized internally
+- Use `non_empty: true` for required user text and `reject_secrets: true` for common secret redaction checks
 - Escape literal braces with `\{{` and `\}}`
 - In strict mode, missing variables throw an error
 - In permissive mode, unresolved placeholders are left intact
@@ -119,6 +121,8 @@ context:
 If a rendered value exceeds `max_size`, `renderPrompt()` emits a non-blocking `POK030` warning.
 At render time, callers can also pass `onContextOverflow` to transform oversized values before warnings/rendering.
 
+Malformed `allow_regex` and `deny_regex` values fail during `validate` and `compile`, not just at render time. When regex compilation fails, the error includes the prompt id, variable name, field name, and raw configured value.
+
 Example: this is the minimal valid shape for a prompt that references
 `{{ pull_request }}` even when provider/model are inherited from defaults:
 

docs/api-reference.md

@@ -114,7 +114,7 @@ const result = await kit.validatePrompt('support/reply');
 // { valid: boolean, errors: ValidationError[], warnings: ValidationError[] }
 ```
 
-`validatePrompt()` covers schema, include-graph, and variable declaration issues. Render-time context size warnings are produced by `renderPrompt()`, not validation.
+`validatePrompt()` covers schema, include-graph, variable declaration issues, and context regex compilation. Render-time context size warnings are produced by `renderPrompt()`, not validation.
 
 ## `kit.clearCache()`
 
@@ -219,6 +219,8 @@ const result = validateAsset(asset, ['id', 'schema_version', 'model'], 'hello.md
 // { valid: boolean, errors: ValidationError[], warnings: ValidationError[] }
 ```
 
+`validateAsset()` reports malformed `allow_regex` and `deny_regex` values before runtime, including the prompt id, variable name, field name, and raw configured value in the error message.
+
 ### `validateAssetWithIncludes(asset, filePath, frontMatterKeys?)`
 
 Validate a prompt asset including its include graph (checks for missing files and circular includes).

docs/cli.md

@@ -36,19 +36,21 @@ Existing files are skipped. If a `package.json` exists, suggests adding a `build
 Validate all prompt `.md` files in a directory.
 
 ```bash
-promptopskit validate <dir> [--strict]
+promptopskit validate [sourceDir] [--source <dir>] [--strict]
 ```
 
 | Option | Description |
 |--------|-------------|
-| `<dir>` | Directory to validate (required) |
+| `<sourceDir>` | Source directory to validate (defaults to `./prompts`) |
+| `--source`, `-s` | Explicit source directory override |
 | `--strict` | Treat warnings as errors (exit code 1) |
 
 Checks:
 - Zod schema validation against the prompt asset schema
 - Missing required fields (`id`, body sections)
 - Unknown front matter keys with Levenshtein-based "did you mean?" suggestions
 - Variable usage — used but undeclared, declared but unused
+- Context regex compilation for `allow_regex` and `deny_regex`
 - Include resolution — missing files, circular includes
 - Folder defaults inheritance from `defaults.md` (provider, model, metadata, system instructions)
 
@@ -65,13 +67,13 @@ Output per file:
 Compile `.md` prompt files to JSON or ESM artifacts.
 
 ```bash
-promptopskit compile [src] [out] [--dry-run] [--format json|esm] [--no-clean]
+promptopskit compile [sourceDir] [outputDir] [--source <dir>] [--output <dir>] [--dry-run] [--format json|esm] [--no-clean]
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `<src>` | `./prompts` | Source directory |
-| `<out>` | `./.generated-prompts/json` | Output directory |
+| `<sourceDir>` | `./prompts` | Source directory |
+| `<outputDir>` | `./.generated-prompts/json` | Output directory |
 | `--source`, `-s` | — | Explicit source directory override |
 | `--output`, `-o` | — | Explicit output directory override |
 | `--format` | `json` | Output format: `json` or `esm` |
@@ -80,6 +82,8 @@ promptopskit compile [src] [out] [--dry-run] [--format json|esm] [--no-clean]
 
 Includes are resolved during compilation so compiled artifacts are self-sufficient. The output directory is cleared by default before compiling (unless `--no-clean` is set).
 
+Compilation runs validation before writing artifacts. Invalid `allow_regex` or `deny_regex` definitions fail the compile step early with `POK013` instead of surfacing later during `renderPrompt()`.
+
 If you omit `<out>`, the CLI chooses `./.generated-prompts/json` for `json` and `./.generated-prompts/esm` for `esm`.
 
 `defaults.md` files are treated as configuration inputs and are not compiled as standalone prompts.

docs/getting-started.md

@@ -43,8 +43,11 @@ sampling:
   temperature: 0.7
 context:
   inputs:
-    - user_message
-    - app_context
+    - name: user_message
+      non_empty: true
+      reject_secrets: true
+    - name: app_context
+      allow_regex: "/^[A-Za-z0-9 _-]+$/i"
 includes:
   - ./shared/tone.md
 ---
@@ -114,15 +117,15 @@ Your application owns the HTTP call — PromptOpsKit produces the request body o
 npx promptopskit validate ./prompts
 ```
 
-This checks all `.md` files for schema errors, unknown front matter keys (with "did you mean?" suggestions), and variable usage mismatches.
+This checks all `.md` files for schema errors, unknown front matter keys (with "did you mean?" suggestions), variable usage mismatches, and malformed context regex definitions.
 
 ## Compile for production
 
 ```bash
 npx promptopskit compile
 ```
 
-Pre-compiles `.md` files to JSON (or ESM) artifacts so deployments skip parsing entirely. Add to your build scripts:
+Pre-compiles `.md` files to JSON (or ESM) artifacts so deployments skip parsing entirely. Compilation validates prompt files first, so malformed regex definitions fail before artifacts are written. Add to your build scripts:
 
 ```json
 {

docs/index.md

@@ -5,7 +5,7 @@ Open-source developer toolkit for managing prompts, system instructions, tools,
 ## Guides
 
 - [Getting Started](./getting-started.md) — Install, scaffold, and render your first prompt
-- [Prompt Format](./prompt-format.md) — Markdown structure, YAML front matter, H1 sections, variables, and `defaults.md` inheritance
+- [Prompt Format](./prompt-format.md) — Markdown structure, YAML front matter, H1 sections, variables, context hardening, and `defaults.md` inheritance
 - [Composition](./composition.md) — Share system instructions across prompts with `includes`
 - [Overrides](./overrides.md) — Environment and tier-based overrides for dev/prod/free/pro
 - [Providers](./providers.md) — Provider adapters for OpenAI, Anthropic, Gemini, and OpenRouter
@@ -18,7 +18,7 @@ Open-source developer toolkit for managing prompts, system instructions, tools,
 - [API Reference](./api-reference.md) — TypeScript API: `createPromptOpsKit`, `renderPrompt`, standalone functions
 - [Schema](./schema.md) — Full YAML front matter schema reference
 - [Testing](./testing.md) — Test helpers, mock assets, and sidecar test files
-- [Validation](./validation.md) — Schema validation, "did you mean?" suggestions, variable checks
+- [Validation](./validation.md) — Schema validation, "did you mean?" suggestions, variable checks, and early regex validation
 
 ## Also see
 

docs/prompt-format.md

@@ -169,15 +169,19 @@ Each entry can be either a string variable name or an object with:
 - `name` — the template variable name
 - `max_size` — optional UTF-8 byte limit for the injected value
 - `trim` — optional trim-to-budget (`true`/`end` keeps first bytes, `start` keeps trailing bytes) applied when `max_size` is set
-- `allow_regex` — optional allowlist regex; input must match (throws `POK031` on mismatch)
-- `deny_regex` — optional blocklist regex; input must not match (throws `POK032` on match)
+- `allow_regex` — optional allowlist regex; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags }` and throws `POK031` on mismatch
+- `deny_regex` — optional blocklist regex; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags }` and throws `POK032` on match
+- `non_empty` — optional boolean validator; throws `POK033` when the final value is blank or whitespace-only
+- `reject_secrets` — optional boolean validator; throws `POK034` when the value matches the built-in secret detector
 
 The validator warns about:
 - Variables used in templates but not declared in `context.inputs`
 - Variables declared in `context.inputs` but never used
 
 At render time, PromptOpsKit also emits a non-blocking `POK030` warning when a provided variable exceeds its declared `max_size`. In source and auto modes, the warning is also written to `console.warn` to make local development issues visible early.
 
+Malformed `allow_regex` and `deny_regex` values fail during `validate` and `compile` with `POK013`, so bad patterns are caught before runtime.
+
 Example hardened input definition:
 
 ```yaml
@@ -186,7 +190,13 @@ context:
     - name: user_id
       trim: true
       max_size: 24
-      allow_regex: "^user_[a-z0-9]+$"
+      allow_regex:
+        pattern: "^user_[a-z0-9]+$"
+        flags: "i"
+    - name: pull_request_body
+      non_empty: true
+      reject_secrets: true
+      deny_regex: "/(ignore previous instructions|system:)/i"
 ```
 
 ## Minimal example

docs/schema.md

@@ -139,7 +139,7 @@ context:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `inputs` | `Array<string | { name, max_size?, trim?, allow_regex?, deny_regex? }>` | Expected variable names, optionally with size and runtime sanitization constraints |
+| `inputs` | `Array<string | { name, max_size?, trim?, allow_regex?, deny_regex?, non_empty?, reject_secrets? }>` | Expected variable names, optionally with size and runtime sanitization constraints |
 | `history` | `object` | History settings |
 | `history.max_items` | `number` | Maximum history items |
 
@@ -156,8 +156,12 @@ Object-form inputs add optional controls:
 
 - `max_size`: checked during `renderPrompt()` and can produce `POK030` warnings.
 - `trim`: trims incoming values to the `max_size` budget before interpolation (`true`/`end` keeps leading bytes, `start` keeps trailing bytes).
-- `allow_regex`: allowlist validation before interpolation; non-matches throw `POK031`.
-- `deny_regex`: blocklist validation before interpolation; matches throw `POK032`.
+- `allow_regex`: allowlist validation before interpolation; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags }`, and non-matches throw `POK031`.
+- `deny_regex`: blocklist validation before interpolation; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags }`, and matches throw `POK032`.
+- `non_empty`: rejects blank or whitespace-only values with `POK033`.
+- `reject_secrets`: rejects common secret-like strings with `POK034`.
+
+Malformed `allow_regex` and `deny_regex` values are reported during `validate` and `compile` with `POK013`.
 
 ## `includes`
 

docs/validation.md

@@ -1,6 +1,6 @@
 # Validation
 
-PromptOpsKit validates prompts at multiple levels — schema structure, front matter keys, variable usage, and include graphs. Render-time context size limits are checked separately during prompt rendering.
+PromptOpsKit validates prompts at multiple levels — schema structure, front matter keys, variable usage, context regex compilation, and include graphs. Render-time context size limits are checked separately during prompt rendering.
 
 ## Quick start
 
@@ -34,8 +34,10 @@ const result = await kit.validatePrompt('support/reply');
 | `POK010` | Warning | Unknown front matter key (with "did you mean?" suggestion) |
 | `POK011` | Warning | Variable used in template but not declared in `context.inputs` |
 | `POK012` | Warning | Variable declared in `context.inputs` but never used |
-| `POK013` | Error | Invalid context regex pattern (`allow_regex` or `deny_regex`) |
+| `POK013` | Error | Invalid context regex pattern (`allow_regex` or `deny_regex`), including prompt id, variable name, field name, and raw configured value |
 | `POK014` | Warning | `trim` configured without `max_size` (trim-to-budget skipped) |
+| `POK033` | Runtime error | `non_empty` validation failed |
+| `POK034` | Runtime error | `reject_secrets` validation matched |
 | `POK020` | Error | Include resolution failed (missing file) |
 | `POK021` | Error | Circular include detected |
 
@@ -96,17 +98,25 @@ context:
   inputs:
     - name: user_id
       trim: true
-      allow_regex: "^user_[a-z0-9]+$"
+      allow_regex:
+        pattern: "^user_[a-z0-9]+$"
+        flags: "i"
     - name: user_message
-      deny_regex: "([Ii]gnore previous instructions|[Ss]ystem:)"
+      deny_regex: "/(ignore previous instructions|system:)/i"
+      non_empty: true
+      reject_secrets: true
 ```
 
 - `trim` trims values to the `max_size` byte budget before interpolation.
 - `allow_regex` enforces an allowlist pattern before interpolation and throws `POK031` when a value fails validation.
 - `deny_regex` enforces a blocklist pattern before interpolation and throws `POK032` when a value matches.
-- During static validation, malformed `allow_regex` or `deny_regex` patterns are reported as `POK013`.
+- `non_empty` rejects blank or whitespace-only values with `POK033`.
+- `reject_secrets` rejects common secret-like strings with `POK034`.
+- During static validation and compilation, malformed `allow_regex` or `deny_regex` patterns are reported as `POK013`.
 - During static validation, `trim` without `max_size` returns a `POK014` warning.
 
+Regex compilation errors include the prompt id, variable name, field name, and raw configured value to make bad prompt definitions easy to locate.
+
 You can override that behavior at the kit level:
 
 ```typescript

src/cli/commands/compile.ts

@@ -2,6 +2,7 @@ import { readdir, writeFile, mkdir, rm } from 'node:fs/promises';
 import { join, extname, relative, dirname } from 'node:path';
 import { loadPromptFile } from '../../parser/index.js';
 import { resolveIncludes } from '../../composition/index.js';
+import { validateAssetWithIncludes } from '../../validation/index.js';
 import { DEFAULT_PROMPTS_DIR, defaultCompiledDirForFormat } from '../../prompt-resolution.js';
 
 const HELP = `
@@ -59,7 +60,12 @@ export async function compile(args: string[]): Promise<void> {
     const outPath = join(outputDir, rel + outExt);
 
     try {
-      const { asset: parsed } = await loadPromptFile(file, { defaultsRoot: sourceDir });
+      const { asset: parsed, raw } = await loadPromptFile(file, { defaultsRoot: sourceDir });
+
+      const validation = await validateAssetWithIncludes(parsed, file, Object.keys(raw.frontMatter));
+      if (validation.errors.length > 0) {
+        throw new Error(validation.errors.map((error) => `${error.code}: ${error.message}`).join('\n    '));
+      }
 
       // Resolve includes so compiled artifacts are self-sufficient
       const asset = (parsed.includes && parsed.includes.length > 0)