@funkai/prompts 0.3.0 → 0.4.1

package/docs/codegen.md

@@ -0,0 +1,142 @@
+# Code Generation & Library
+
+The CLI transforms `.prompt` source files into typed TypeScript modules. This doc covers the pipeline stages, generated output shape, and the runtime library API.
+
+## Pipeline
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#313244',
+    'primaryTextColor': '#cdd6f4',
+    'primaryBorderColor': '#6c7086',
+    'lineColor': '#89b4fa',
+    'secondaryColor': '#45475a',
+    'tertiaryColor': '#1e1e2e',
+    'background': '#1e1e2e',
+    'mainBkg': '#313244',
+    'clusterBkg': '#1e1e2e',
+    'clusterBorder': '#45475a'
+  },
+  'flowchart': { 'curve': 'basis', 'padding': 15 }
+}}%%
+flowchart TD
+  classDef core fill:#313244,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+  classDef agent fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+
+  subgraph Per Prompt
+    A[discoverPrompts]:::core --> B[parseFrontmatter]:::core
+    B --> C[clean]:::core
+    C --> D[flattenPartials]:::core
+    D --> E[extractVariables]:::core
+    E --> F[lintPrompt]:::core
+  end
+
+  subgraph Output
+    F --> G[generatePromptModule]:::agent
+    F --> H[generateRegistry]:::agent
+  end
+```
+
+## Pipeline Stages
+
+| Stage             | Input                        | Output                             | Description                                             |
+| ----------------- | ---------------------------- | ---------------------------------- | ------------------------------------------------------- |
+| Discover          | Root directories             | `DiscoveredPrompt[]`               | Scans for `.prompt` files (max depth 5)                 |
+| Parse Frontmatter | Raw file content             | `{ name, group, version, schema }` | Extracts and validates YAML metadata                    |
+| Clean             | Raw content                  | Template string                    | Strips frontmatter delimiters                           |
+| Flatten Partials  | Template with `{% render %}` | Resolved template                  | Inlines partial content with bound params               |
+| Extract Variables | Template string              | `string[]`                         | Finds `{{ var }}`, `{% if var %}`, `{% for x in var %}` |
+| Lint              | Schema + variables           | Diagnostics                        | Checks schema/template variable alignment               |
+
+## Generated Output
+
+### Per-Prompt Module (`<name>.ts`)
+
+Each module exports a default object conforming to `PromptModule`:
+
+| Member                | Type                     | Description                                      |
+| --------------------- | ------------------------ | ------------------------------------------------ |
+| `name`                | `string` (const)         | Prompt name from frontmatter                     |
+| `group`               | `string \| undefined`    | Optional grouping key                            |
+| `schema`              | `ZodObject`              | Zod schema built from frontmatter `schema` block |
+| `render(variables)`   | `(Variables) => string`  | Validates input then renders via LiquidJS        |
+| `validate(variables)` | `(unknown) => Variables` | Zod parse only                                   |
+
+### Registry (`index.ts`)
+
+Aggregates all per-prompt modules into a single entry point:
+
+| Export    | Type                  | Description                                                                                            |
+| --------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `prompts` | `PromptRegistry<...>` | Deep-frozen const object with dot-access, nested by group. Use `typeof prompts` for type-level access. |
+
+## Output Directory
+
+Generated files go to the `--out` directory (conventionally `.prompts/client/`). This subdirectory should be gitignored. The parent `.prompts/` directory also holds `partials/` for custom partials (committed to git). Import generated code via the `~prompts` tsconfig alias.
+
+## Runtime Library API
+
+The library surface provides the runtime engine and registry used by generated code and consuming packages.
+
+### Exports
+
+| Export                 | Type                                | Description                                                                |
+| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| `engine`               | `Liquid`                            | Shared LiquidJS instance (no filesystem, strict filters)                   |
+| `createEngine`         | `(partialsDir, options?) => Liquid` | Factory for filesystem-backed engines (used by CLI for partial resolution) |
+| `clean`                | `(content: string) => string`       | Strips frontmatter, returns render-ready template                          |
+| `createPromptRegistry` | `(modules) => PromptRegistry`       | Creates typed registry from prompt module map                              |
+
+### Engine
+
+The shared `engine` instance is configured with `ownPropertyOnly: true` and `strictFilters: true` for security. No filesystem access -- templates are rendered from strings via `parseAndRenderSync`.
+
+`createEngine` accepts a `partialsDir` and optional overrides. It enables filesystem-backed partial resolution (`.prompt` extension, caching enabled) for use during codegen flattening.
+
+### Registry
+
+`createPromptRegistry` accepts a (possibly nested) record of `PromptModule` objects and namespace nodes. It returns a deep-frozen `PromptRegistry` with direct property access:
+
+```ts
+const prompts = createPromptRegistry({
+  agents: { coverageAssessor },
+  greeting,
+});
+prompts.agents.coverageAssessor.render({ scope: "full" });
+prompts.greeting.render();
+```
+
+Nesting is driven by the `group` field in frontmatter. Each `/`-separated segment becomes a nesting level, with all names converted to camelCase. The registry is frozen at creation time to prevent mutation.
+
+## Consumer Import Pattern
+
+The generated `index.ts` calls `createPromptRegistry` with all prompt modules organized by group and exports a `prompts` const object. Consumers import via the `~prompts` tsconfig alias:
+
+```ts
+import { prompts } from "~prompts";
+
+// Flat (no group)
+const text = prompts.greeting.render();
+
+// Nested (group: agents)
+const text = prompts.agents.coverageAssessor.render({ scope: "full" });
+```
+
+Types are inferred from the object structure, giving full type safety on `render` and `validate` arguments at every nesting level.
+
+## Types Reference
+
+| Type                  | Description                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `PromptModule`        | Interface: `name`, `group`, `schema` (ZodType), `render(vars)`, `validate(vars)`                                          |
+| `PromptNamespace`     | A nested namespace node -- values are `PromptModule` leaves or further nested namespaces                                  |
+| `PromptRegistry`      | Deep-readonly mapped type over a `PromptNamespace` tree                                                                   |
+| `CreateEngineOptions` | Options for `createEngine`: `root`, `partials`, `extname`, `cache`, `strictFilters`, `strictVariables`, `ownPropertyOnly` |
+| `Liquid`              | Re-exported LiquidJS engine type                                                                                          |
+
+## References
+
+- [File Format](file-format.md)
+- [CLI](cli.md)

package/docs/file-format/overview.md

@@ -44,7 +44,7 @@ Names must match `^[a-z0-9-]+$` (lowercase, digits, hyphens). The `name` field i
 
 ## Discovery
 
-The CLI scans `--roots` directories recursively (max depth 5). Files must have the `.prompt` extension. Symbolic links are skipped. Duplicate names across roots cause an error with paths listed.
+The CLI scans `--includes` glob patterns recursively (max depth 5). Files must have the `.prompt` extension. Symbolic links are skipped. Duplicate names across roots cause an error with paths listed.
 
 Results are sorted alphabetically by name.
 

package/docs/file-format.md

@@ -0,0 +1,306 @@
+# .prompt File Format
+
+A `.prompt` file is a LiquidJS template with YAML frontmatter. It is a declarative prompt authoring format compiled to typed TypeScript at build time.
+
+## File Anatomy
+
+Every `.prompt` file has two sections: a YAML frontmatter block delimited by `---` fences, and a LiquidJS template body.
+
+```text
+---
+name: coverage-assessor
+group: agents/coverage-assessor
+schema:
+  scope:
+    type: string
+    description: Assessment scope
+  target:
+    type: string
+    required: false
+---
+
+You are a coverage assessor for {{ scope }}.
+{% if target %}Targeting {{ target }} docs.{% endif %}
+```
+
+| Section             | Description                                                   |
+| ------------------- | ------------------------------------------------------------- |
+| Frontmatter (`---`) | YAML metadata block defining name, group, and variable schema |
+| Body                | LiquidJS template rendered at runtime with typed variables    |
+
+## Template Syntax
+
+| Syntax                                  | Purpose                             |
+| --------------------------------------- | ----------------------------------- |
+| `{{ var }}`                             | Variable output                     |
+| `{{ var \| filter }}`                   | Filtered output                     |
+| `{% if var %}...{% endif %}`            | Conditional                         |
+| `{% for item in list %}...{% endfor %}` | Iteration                           |
+| `{% render 'name', key: 'value' %}`     | Partial inclusion (build-time only) |
+
+Strict filters are enabled -- unknown filters throw an error. Variable access is restricted to own properties only.
+
+## Frontmatter Reference
+
+The YAML frontmatter block defines metadata and the variable schema.
+
+### Fields
+
+| Field     | Required | Type     | Description                                      |
+| --------- | -------- | -------- | ------------------------------------------------ |
+| `name`    | Yes      | `string` | Unique kebab-case identifier (`^[a-z0-9-]+$`)    |
+| `group`   | No       | `string` | Namespace path (e.g. `agents/coverage-assessor`) |
+| `version` | No       | `string` | Version identifier                               |
+| `schema`  | No       | `object` | Variable declarations map                        |
+
+### Validation Rules
+
+- `name` is required and must match `^[a-z0-9-]+$`
+- Frontmatter must be valid YAML between `---` delimiters
+- `schema` must be an object (not an array)
+- Missing or empty `name` throws a parse error with the file path
+- Non-object frontmatter (e.g. a bare string) is rejected
+
+## Schema Variables
+
+Each key under `schema` declares a template variable. Two syntaxes are supported.
+
+**Shorthand** -- type string only, defaults to required:
+
+```yaml
+schema:
+  scope: string
+```
+
+**Full object** -- explicit control over all fields:
+
+```yaml
+schema:
+  scope:
+    type: string
+    required: true
+    description: Assessment scope
+```
+
+Shorthand `scope: string` expands to `{ type: 'string', required: true }`.
+
+### Variable Fields
+
+| Field         | Default  | Description                                          |
+| ------------- | -------- | ---------------------------------------------------- |
+| `type`        | `string` | Variable type (only `string` supported)              |
+| `required`    | `true`   | Whether the variable must be provided at render time |
+| `description` | --       | Human-readable description (used in generated JSDoc) |
+
+## Naming and Discovery
+
+Names must match `^[a-z0-9-]+$` (lowercase, digits, hyphens). The `name` field in frontmatter is required and takes precedence. A file named `prompt.prompt` derives its name from the parent directory (e.g. `agents/gap-detector/prompt.prompt` becomes `gap-detector`).
+
+The CLI scans `--includes` glob patterns recursively (max depth 5). Files must have the `.prompt` extension. Symbolic links are skipped. Duplicate names across roots cause an error with paths listed. Results are sorted alphabetically by name.
+
+### Recommended File Structure
+
+```text
+src/
+  agents/
+    coverage-assessor/
+      prompt.prompt
+  prompts/
+    identity.prompt
+    constraints.prompt
+```
+
+## Partials
+
+Partials are reusable template fragments included with `{% render %}` tags. They are resolved and flattened at build time -- the generated output contains no render tags.
+
+### Syntax
+
+```liquid
+{% render 'identity', role: 'Coverage Assessor', desc: 'an expert at assessing documentation coverage' %}
+```
+
+Only literal string parameters are supported. Variable references (e.g. `key: myVar`) are not allowed and throw an error at codegen time. Whitespace trim variants `{%-` and `-%}` are supported.
+
+### Resolution Order
+
+Partials are resolved from two locations, searched in order (first match wins):
+
+| Priority | Location             | Description                                      |
+| -------- | -------------------- | ------------------------------------------------ |
+| 1        | `.prompts/partials/` | Custom project partials (committed to git)       |
+| 2        | SDK `src/prompts/`   | Built-in partials shipped with `@funkai/prompts` |
+
+Custom partials take precedence -- a custom partial with the same name as a built-in overrides it.
+
+### Built-in Partials
+
+| Partial       | Parameters                                         | Purpose                                             |
+| ------------- | -------------------------------------------------- | --------------------------------------------------- |
+| `identity`    | `role`, `desc`, `context` (optional)               | Agent identity block (`<identity>` wrapper)         |
+| `constraints` | `in_scope`, `out_of_scope`, `rules` (all optional) | Scoping constraints block (`<constraints>` wrapper) |
+| `tools`       | `tools` (optional)                                 | Tool listing block (`<tools>` wrapper)              |
+
+**identity** source:
+
+```liquid
+<identity>
+You are {{ role }}, {{ desc }}.
+{% if context %}
+{{ context }}
+{% endif %}
+</identity>
+```
+
+**constraints** source:
+
+```liquid
+<constraints>
+{% if in_scope %}
+## In Scope
+{% for item in in_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if out_of_scope %}
+## Out of Scope
+{% for item in out_of_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if rules %}
+## Rules
+{% for rule in rules %}
+- {{ rule }}
+{% endfor %}
+{% endif %}
+</constraints>
+```
+
+### Custom Partials
+
+Place custom `.prompt` files in `.prompts/partials/`:
+
+```text
+.prompts/
+  client/       # Generated (gitignored)
+  partials/     # Custom partials (committed)
+    summary.prompt
+```
+
+The CLI auto-discovers this directory:
+
+- `prompts generate` derives it from `--out` (sibling `partials/` dir)
+- `prompts lint` defaults to `.prompts/partials` (configurable via `--partials`)
+
+**Creating a custom partial:**
+
+```bash
+prompts create summary --partial
+```
+
+Or create `.prompts/partials/<name>.prompt` by hand:
+
+```liquid
+<summary>
+{{ content }}
+{% if notes %}
+Notes: {{ notes }}
+{% endif %}
+</summary>
+```
+
+Use it in a `.prompt` file:
+
+```liquid
+{% render 'summary', content: 'Analysis complete' %}
+```
+
+Run `prompts generate` -- the partial is flattened into the generated output. No `{% render %}` tags remain.
+
+**Overriding built-ins:** Create a file with the same name in `.prompts/partials/` (e.g. `.prompts/partials/identity.prompt`). Custom partials take precedence over SDK built-ins.
+
+**Adding a built-in partial (SDK contributors):**
+
+1. Create `packages/prompts/src/prompts/<name>.prompt`
+2. Write the partial template using XML-style wrapper tags and Liquid variables
+3. Test with a consumer `.prompt` file and run `prompts generate`
+
+## Authoring Walkthrough
+
+### Prerequisites
+
+- `@funkai/prompts` installed
+- Project configured ([Setup guide](setup.md))
+
+### Steps
+
+1. **Scaffold** with the CLI:
+
+```bash
+prompts create my-agent --out src/agents/my-agent
+```
+
+2. **Edit** the frontmatter -- set `name`, `group`, and `schema` variables.
+
+3. **Write** the template body using `{{ var }}` syntax and conditionals.
+
+4. **Add partials** if needed:
+
+```liquid
+{% render 'identity', role: 'Analyzer', desc: 'a code analyzer' %}
+```
+
+5. **Lint:**
+
+```bash
+prompts lint --includes "src/agents/**"
+```
+
+6. **Generate:**
+
+```bash
+prompts generate --out .prompts/client --includes "src/agents/**"
+```
+
+7. **Import and use:**
+
+```ts
+import { prompts } from "~prompts";
+
+const text = prompts.myAgent.render({ scope: "full" });
+```
+
+### Verification
+
+- `prompts lint` reports no errors
+- Generated file exists at `.prompts/client/my-agent.ts`
+- TypeScript compiles without errors
+
+### Troubleshooting
+
+#### Undefined variable error
+
+**Fix:** Add the variable to the frontmatter `schema` block.
+
+#### Duplicate prompt name
+
+**Fix:** Two `.prompt` files share the same `name` -- rename one to a unique kebab-case identifier.
+
+#### TypeScript can't find `~prompts`
+
+**Fix:** Run `prompts setup` or add the path alias to `tsconfig.json`. See [setup.md](setup.md).
+
+#### Variable reference not supported in partial
+
+**Fix:** Only literal string params are allowed in `{% render %}` tags. Replace variable references with string literals.
+
+#### Partial not found
+
+**Fix:** Verify the file is in `.prompts/partials/` (custom) or `src/prompts/` (built-in) with `.prompt` extension.
+
+## References
+
+- [Code Generation & Library](codegen.md)
+- [CLI](cli.md)
+- [Setup](setup.md)

package/docs/guides/author-prompt.md

@@ -26,13 +26,13 @@ prompts create my-agent --out src/agents/my-agent
 5. Lint:
 
 ```bash
-prompts lint --roots src/agents
+prompts lint --includes "src/agents/**"
 ```
 
 6. Generate:
 
 ```bash
-prompts generate --out .prompts/client --roots src/agents
+prompts generate --out .prompts/client --includes "src/agents/**"
 ```
 
 7. Import and use:

package/docs/guides/setup-project.md

@@ -50,7 +50,7 @@ Or configure manually (steps 3-6).
 ```json
 {
   "scripts": {
-    "prompts:generate": "prompts generate --out .prompts/client --roots prompts src/agents"
+    "prompts:generate": "prompts generate --out .prompts/client --includes \"prompts/**\" \"src/agents/**\""
   }
 }
 ```

package/docs/overview.md

@@ -1,4 +1,4 @@
-# Prompts SDK Overview
+# Prompts SDK
 
 Prompt authoring SDK with two surfaces: a **CLI** for build-time code generation from `.prompt` files, and a **library** for runtime template rendering with full type safety.
 
@@ -51,28 +51,6 @@ flowchart LR
   classDef gateway fill:#313244,stroke:#fab387,stroke-width:2px,color:#cdd6f4
 ```
 
-## Package Structure
-
-```
-📁 packages/prompts/
-├── 📁 src/
-│   ├── 📁 prompts/            # Built-in partials (identity, constraints, tools)
-│   ├── 📄 engine.ts           # LiquidJS engine factory
-│   ├── 📄 registry.ts         # Typed prompt registry
-│   ├── 📄 clean.ts            # Frontmatter stripping pipeline
-│   ├── 📄 partials-dir.ts     # PARTIALS_DIR export for CLI/consumers
-│   ├── 📄 types.ts            # PromptModule, PromptNamespace, PromptRegistry types
-│   └── 📄 index.ts            # Public exports
-└── 📁 docs/
-
-📁 packages/cli/               # @funkai/cli — CLI binary (see @funkai/cli README)
-├── 📁 commands/               # generate, lint, create, setup
-├── 📁 src/lib/                # codegen, frontmatter, flatten, lint, paths
-└── 📄 index.ts                # CLI entry point (kidd-cli)
-```
-
-> **Note:** The CLI was extracted to `@funkai/cli`. Install it separately for the `prompts` binary.
-
 ## Dual Surface
 
 | Surface | When       | What                                                                         |
@@ -83,20 +61,15 @@ flowchart LR
 ## Quick Start
 
 1. Create a `.prompt` file with YAML frontmatter and a LiquidJS template body.
-2. Run `prompts generate --out .prompts/client --roots src/agents` to produce typed modules.
+2. Run `prompts generate --out .prompts/client --includes "src/agents/**"` to produce typed modules.
 3. Import from the `~prompts` alias in your application code.
 4. Call `.render({ vars })` with full type safety derived from the Zod schema in frontmatter.
 
-## References
+## Documentation
 
-- [File Format](file-format/overview.md)
-- [Frontmatter](file-format/frontmatter.md)
-- [Partials](file-format/partials.md)
-- [CLI](cli/overview.md)
-- [CLI Commands](cli/commands.md)
-- [Code Generation](codegen/overview.md)
-- [Library API](library/overview.md)
-- [Guide: Author a Prompt](guides/author-prompt.md)
-- [Guide: Setup Project](guides/setup-project.md)
-- [Guide: Add a Partial](guides/add-partial.md)
-- [Troubleshooting](troubleshooting.md)
+| Topic                                   | Description                                                               |
+| --------------------------------------- | ------------------------------------------------------------------------- |
+| [File Format](file-format.md)           | .prompt anatomy, frontmatter, schema variables, partials, authoring guide |
+| [Code Generation & Library](codegen.md) | Build pipeline, generated output, runtime API, consumer patterns          |
+| [Project Setup](setup.md)               | VSCode, .gitignore, tsconfig, package.json configuration                  |
+| [Troubleshooting](troubleshooting.md)   | Common errors and fixes                                                   |

package/docs/setup.md

@@ -0,0 +1,76 @@
+# Setup Prompt Development
+
+## Prerequisites
+
+- Node 24
+- pnpm workspace
+
+## Steps
+
+1. Install:
+
+```bash
+pnpm add @funkai/prompts --workspace
+```
+
+2. Run interactive setup:
+
+```bash
+prompts setup
+```
+
+Or configure manually (steps 3-6).
+
+3. Add VSCode file association in `.vscode/settings.json`:
+
+```json
+{
+  "files.associations": {
+    "*.prompt": "markdown"
+  }
+}
+```
+
+4. Add `.prompts/client/` to `.gitignore`.
+
+5. Add `~prompts` path alias to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "~prompts": ["./.prompts/client/index.ts"]
+    }
+  }
+}
+```
+
+6. Add generate script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "prompts:generate": "prompts generate --out .prompts/client --includes \"prompts/**\" \"src/agents/**\""
+  }
+}
+```
+
+## Verification
+
+Run `prompts generate` and verify `.prompts/client/` directory is created with an `index.ts`.
+
+## Troubleshooting
+
+### VSCode not highlighting `.prompt` files
+
+**Fix:** Check `.vscode/settings.json` file association is set correctly.
+
+### TypeScript can't resolve `~prompts`
+
+**Fix:** Verify `tsconfig.json` paths alias points to `./.prompts/client/index.ts`.
+
+## References
+
+- [CLI](cli.md)
+- [File Format](file-format.md)
+- [Code Generation & Library](codegen.md)

package/docs/troubleshooting.md

@@ -14,7 +14,7 @@
 
 ## Invalid prompt name
 
-**Fix:** Names must match `^[a-z0-9-]+$` — lowercase letters, digits, and hyphens only.
+**Fix:** Names must match `^[a-z0-9-]+$` -- lowercase letters, digits, and hyphens only.
 
 ## Partial variable reference error
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funkai/prompts",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "private": false,
   "description": "Prompt SDK with LiquidJS templating and Zod validation",
   "keywords": [
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "es-toolkit": "^1.45.1",
-    "liquidjs": "^10.25.0",
+    "liquidjs": "^10.25.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/engine.ts

@@ -21,6 +21,7 @@ export function createEngine(partialsDir: string, options?: Partial<CreateEngine
     ...options,
     // Safety defaults — applied after spread so callers cannot disable them
     strictFilters: true,
+    strictVariables: true,
     ownPropertyOnly: true,
   });
 }
@@ -36,5 +37,6 @@ export function createEngine(partialsDir: string, options?: Partial<CreateEngine
  */
 export const liquidEngine = new Liquid({
   strictFilters: true,
+  strictVariables: true,
   ownPropertyOnly: true,
 });