@funkai/prompts 0.1.0

package/docs/file-format/partials.md

@@ -0,0 +1,87 @@
+# 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 Partial
+
+```liquid
+<identity>
+You are {{ role }}, {{ desc }}.
+{% if context %}
+{{ context }}
+{% endif %}
+</identity>
+```
+
+## Constraints Partial
+
+```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/`:
+
+```
+📁 .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`)
+
+## References
+
+- [File Format Overview](overview.md)
+- [Add a Partial](../guides/add-partial.md)

package/docs/guides/add-partial.md

@@ -0,0 +1,75 @@
+# Add a Partial
+
+## Custom Partials
+
+Custom partials live in `.prompts/partials/` and are auto-discovered at build time. They take precedence over built-in SDK partials.
+
+### Steps
+
+1. Scaffold with the CLI or create manually:
+
+```bash
+prompts create summary --partial
+```
+
+Or create `.prompts/partials/<name>.prompt` by hand:
+
+```liquid
+<summary>
+{{ content }}
+{% if notes %}
+Notes: {{ notes }}
+{% endif %}
+</summary>
+```
+
+2. Use in a `.prompt` file:
+
+```liquid
+{% render 'summary', content: 'Analysis complete' %}
+```
+
+3. Run `prompts generate` — the partial is flattened into the generated output.
+
+### Overriding Built-ins
+
+To override a built-in partial, create a file with the same name in `.prompts/partials/` (e.g. `.prompts/partials/identity.prompt`). Custom partials take precedence over SDK built-ins.
+
+## Built-in Partials
+
+Built-in partials require access to the `@funkai/prompts` source.
+
+### Steps
+
+1. Create `packages/prompts/src/prompts/<name>.prompt`.
+
+2. Write the partial template — use XML-style wrapper tags and Liquid variables:
+
+```liquid
+<output>
+{{ content }}
+</output>
+```
+
+3. Test with a consumer `.prompt` file and run `prompts generate`.
+
+4. Document the new partial in `docs/file-format/partials.md`.
+
+## Verification
+
+The generated `.ts` module contains the flattened partial content. No `{% render %}` tags remain.
+
+## Troubleshooting
+
+### Variable reference not supported
+
+**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
+
+- [Partials Reference](../file-format/partials.md)
+- [File Format](../file-format/overview.md)

package/docs/guides/author-prompt.md

@@ -0,0 +1,70 @@
+# Author a Prompt
+
+## Prerequisites
+
+- `@funkai/prompts` installed
+- Project configured ([Setup guide](setup-project.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 --roots src/agents
+```
+
+6. Generate:
+
+```bash
+prompts generate --out .prompts/client --roots 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`.
+
+## References
+
+- [File Format](../file-format/overview.md)
+- [CLI Commands](../cli/commands.md)
+- [Partials](../file-format/partials.md)

package/docs/guides/setup-project.md

@@ -0,0 +1,75 @@
+# 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 --roots 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 Commands](../cli/commands.md)
+- [Overview](../overview.md)

package/docs/library/overview.md

@@ -0,0 +1,64 @@
+# 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                              |
+
+## Types
+
+| 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                                                                                          |
+
+## 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 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.
+
+## References
+
+- [Code Generation](../codegen/overview.md)
+- [Overview](../overview.md)

package/docs/overview.md

@@ -0,0 +1,102 @@
+# Prompts SDK Overview
+
+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.
+
+## Architecture
+
+```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 LR
+  P[".prompt files"]:::external
+
+  subgraph CLI ["CLI (Build Time)"]
+    direction LR
+    D[Discover] --> PA[Parse] --> L[Lint] --> F[Flatten] --> C[Codegen]
+  end
+
+  subgraph RT ["Runtime"]
+    direction LR
+    E[Engine] --> R[Registry]
+  end
+
+  P --> D
+  C --> G["Generated .prompts/client/*.ts"]:::agent
+  G --> E
+  R --> O["Rendered string"]:::agent
+
+  class D,PA,L,F,C core
+  class E,R gateway
+
+  style CLI fill:none,stroke:#89b4fa,stroke-width:2px,stroke-dasharray:5 5
+  style RT fill:none,stroke:#fab387,stroke-width:2px,stroke-dasharray:5 5
+
+  classDef external fill:#313244,stroke:#f5c2e7,stroke-width:2px,color:#cdd6f4
+  classDef core fill:#313244,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+  classDef agent fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+  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                                                                         |
+| ------- | ---------- | ---------------------------------------------------------------------------- |
+| CLI     | Build time | Discovers `.prompt` files, validates frontmatter, generates typed TS modules |
+| Library | Runtime    | LiquidJS engine renders templates, registry provides typed access            |
+
+## 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.
+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
+
+- [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)

package/docs/troubleshooting.md

@@ -0,0 +1,37 @@
+# Troubleshooting
+
+## Undefined variable lint error
+
+**Fix:** Add the variable to the frontmatter `schema` block, or remove it from the template.
+
+## Unused variable lint warning
+
+**Fix:** Remove the variable from `schema`, or use it in the template body.
+
+## Duplicate prompt name
+
+**Fix:** Two `.prompt` files share the same `name` field. Rename one to a unique kebab-case identifier.
+
+## Invalid prompt name
+
+**Fix:** Names must match `^[a-z0-9-]+$` — lowercase letters, digits, and hyphens only.
+
+## Partial variable reference error
+
+**Fix:** Only literal string parameters are supported in `{% render %}` tags. Replace variable references with string literals.
+
+## Dangerous variable name
+
+**Fix:** `__proto__`, `constructor`, and `prototype` are forbidden variable names. Choose a different name.
+
+## TypeScript can't find `~prompts`
+
+**Fix:** Add the path alias to `tsconfig.json`: `"~prompts": ["./.prompts/client/index.ts"]`. Or run `prompts setup`.
+
+## Generated files not updating
+
+**Fix:** Re-run `prompts generate` after editing `.prompt` files. Generated output is not watched.
+
+## VSCode shows `.prompt` as plain text
+
+**Fix:** Run `prompts setup` or add `"files.associations": { "*.prompt": "markdown" }` to `.vscode/settings.json`.

package/logo.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 550 160">
+  <defs>
+    <style>
+      .text { font-family: 'SF Mono', 'Fira Code', 'JetBrains Mono', Consolas, monospace; }
+      .brand { fill: #a78bfa; }
+      .dim { fill: #6c7086; }
+    </style>
+  </defs>
+
+  <g transform="translate(24, 20)">
+    <text class="text brand" font-size="13" y="0" xml:space="preserve">██████╗ ██████╗  ██████╗ ███╗   ███╗██████╗ ████████╗███████╗</text>
+    <text class="text brand" font-size="13" y="16" xml:space="preserve">██╔══██╗██╔══██╗██╔═══██╗████╗ ████║██╔══██╗╚══██╔══╝██╔════╝</text>
+    <text class="text brand" font-size="13" y="32" xml:space="preserve">██████╔╝██████╔╝██║   ██║██╔████╔██║██████╔╝   ██║   ███████╗</text>
+    <text class="text brand" font-size="13" y="48" xml:space="preserve">██╔═══╝ ██╔══██╗██║   ██║██║╚██╔╝██║██╔═══╝    ██║   ╚════██║</text>
+    <text class="text brand" font-size="13" y="64" xml:space="preserve">██║     ██║  ██║╚██████╔╝██║ ╚═╝ ██║██║        ██║   ███████║</text>
+    <text class="text brand" font-size="13" y="80" xml:space="preserve">╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚═╝        ╚═╝   ╚══════╝</text>
+
+    <text class="text dim" font-size="12" y="112" x="0">prompt sdk with liquidjs templating and zod validation</text>
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@funkai/prompts",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Prompt SDK with LiquidJS templating and Zod validation",
+  "keywords": [
+    "ai",
+    "codegen",
+    "liquidjs",
+    "prompts",
+    "templates",
+    "typescript",
+    "zod"
+  ],
+  "homepage": "https://github.com/joggrdocs/funkai/tree/main/packages/prompts#readme",
+  "bugs": {
+    "url": "https://github.com/joggrdocs/funkai/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joggrdocs/funkai.git",
+    "directory": "packages/prompts"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/index.d.mts",
+      "import": "./dist/lib/index.mjs"
+    }
+  },
+  "dependencies": {
+    "es-toolkit": "^1.45.1",
+    "liquidjs": "^10.25.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "tsdown": "^0.21.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsdown && cp -r src/prompts dist/prompts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/clean.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import { clean } from "@/clean.js";
+
+describe("clean", () => {
+  it("should strip YAML frontmatter from a prompt file", () => {
+    const input = "---\nname: test-prompt\ngroup: agents\n---\nHello {{ name }}";
+    expect(clean(input)).toBe("Hello {{ name }}");
+  });
+
+  it("should return the string unchanged when no frontmatter is present", () => {
+    const input = "Hello {{ name }}";
+    expect(clean(input)).toBe("Hello {{ name }}");
+  });
+
+  it("should handle Windows-style line endings", () => {
+    const input = "---\r\nname: test\r\n---\r\nHello {{ name }}";
+    expect(clean(input)).toBe("Hello {{ name }}");
+  });
+
+  it("should handle frontmatter with no trailing newline after closing delimiter", () => {
+    const input = "---\nname: test\n---";
+    expect(clean(input)).toBe("");
+  });
+
+  it("should return an empty string when input is empty", () => {
+    expect(clean("")).toBe("");
+  });
+
+  it("should preserve multiline template body after frontmatter", () => {
+    const input = [
+      "---",
+      "name: multi-line",
+      "schema:",
+      "  name: string",
+      "  age: number",
+      "---",
+      "Line 1",
+      "Line 2",
+      "{{ variable }}",
+    ].join("\n");
+    expect(clean(input)).toBe("Line 1\nLine 2\n{{ variable }}");
+  });
+});

package/src/clean.ts

@@ -0,0 +1,25 @@
+import { flow } from "es-toolkit";
+
+const FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
+
+/**
+ * Remove YAML frontmatter from the beginning of a string.
+ *
+ * Frontmatter is a block delimited by `---` at the start of the file.
+ * If no frontmatter is present, the string is returned unchanged.
+ */
+function stripFrontmatter(text: string): string {
+  return text.replace(FRONTMATTER_RE, "");
+}
+
+const pipeline = flow(stripFrontmatter);
+
+/**
+ * Clean a raw `.prompt` file into a render-ready template.
+ *
+ * Runs the source through a pipeline of transforms — currently
+ * strips frontmatter, with more steps added over time.
+ */
+export function clean(text: string): string {
+  return pipeline(text);
+}