@funkai/prompts 0.3.0 → 0.4.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @funkai/prompts@0.3.0 build /home/runner/work/funkai/funkai/packages/prompts
+> @funkai/prompts@0.4.1 build /home/runner/work/funkai/funkai/packages/prompts
 > tsdown && cp -r src/prompts dist/prompts
 
 ℹ tsdown v0.21.4 powered by rolldown v1.0.0-rc.9
@@ -8,21 +8,21 @@
 ℹ target: node22
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/lib/index.mjs                  1.70 kB │ gzip: 0.82 kB
+ℹ dist/lib/index.mjs                  3.99 kB │ gzip: 1.56 kB
 ℹ dist/lib/cli.mjs                    1.39 kB │ gzip: 0.75 kB
 ℹ dist/lib/runtime.mjs                0.08 kB │ gzip: 0.08 kB
-ℹ dist/lib/index.mjs.map              2.71 kB │ gzip: 1.16 kB
+ℹ dist/lib/index.mjs.map              6.42 kB │ gzip: 2.30 kB
 ℹ dist/lib/cli.mjs.map                1.86 kB │ gzip: 0.90 kB
-ℹ dist/lib/engine-CPKs9QbX.mjs.map    1.67 kB │ gzip: 0.85 kB
-ℹ dist/lib/engine-CPKs9QbX.mjs        1.17 kB │ gzip: 0.62 kB
-ℹ dist/lib/types-2PI_9h-M.d.mts.map   0.53 kB │ gzip: 0.29 kB
-ℹ dist/lib/engine-CQfJbVz6.d.mts.map  0.22 kB │ gzip: 0.18 kB
-ℹ dist/lib/index.d.mts.map            0.19 kB │ gzip: 0.15 kB
+ℹ dist/lib/engine-Bhv5Zxdu.mjs.map    1.75 kB │ gzip: 0.87 kB
+ℹ dist/lib/engine-Bhv5Zxdu.mjs        1.21 kB │ gzip: 0.64 kB
+ℹ dist/lib/types-DmnHC99v.d.mts.map   0.66 kB │ gzip: 0.34 kB
+ℹ dist/lib/index.d.mts.map            0.45 kB │ gzip: 0.25 kB
+ℹ dist/lib/engine-BAYeiay3.d.mts.map  0.22 kB │ gzip: 0.17 kB
 ℹ dist/lib/cli.d.mts.map              0.18 kB │ gzip: 0.15 kB
-ℹ dist/lib/index.d.mts                1.04 kB │ gzip: 0.54 kB
+ℹ dist/lib/index.d.mts                3.02 kB │ gzip: 1.14 kB
 ℹ dist/lib/cli.d.mts                  0.94 kB │ gzip: 0.53 kB
 ℹ dist/lib/runtime.d.mts              0.08 kB │ gzip: 0.08 kB
-ℹ dist/lib/types-2PI_9h-M.d.mts       1.43 kB │ gzip: 0.69 kB
-ℹ dist/lib/engine-CQfJbVz6.d.mts      1.08 kB │ gzip: 0.58 kB
-ℹ 16 files, total: 16.28 kB
-✔ Build complete in 1612ms
+ℹ dist/lib/types-DmnHC99v.d.mts       2.17 kB │ gzip: 0.94 kB
+ℹ dist/lib/engine-BAYeiay3.d.mts      1.08 kB │ gzip: 0.58 kB
+ℹ 16 files, total: 25.52 kB
+✔ Build complete in 2824ms

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @funkai/prompts
 
+## 0.4.1
+
+### Patch Changes
+
+- ef51bd7: fix(packages/prompts): enable strictVariables, fix deepFreeze mutation, add @throws docs
+
+  - Add `strictVariables: true` to shared liquid engine — template/schema mismatches now throw instead of silently rendering empty strings
+  - Fix `deepFreeze` to shallow-copy nested namespace objects before freezing (previously mutated caller references)
+  - Replace `for...of` loop in `deepFreeze` with `Object.entries().reduce()`
+  - Add `@throws {ZodError}` documentation to `render()` and `validate()` methods
+
+## 0.4.0
+
+### Minor Changes
+
+- c8569db: feat(prompts): add createPrompt, createPromptGroup, and config-based group assignment
+
+  - Add `createPrompt<T>(config)` factory for building prompt modules at runtime and codegen
+  - Add `createPromptGroup(name, prompts)` for grouping prompt modules into namespaces
+  - Add `PromptConfig<T>` type for prompt module configuration
+  - Codegen now uses `createPrompt()` instead of raw object literals
+  - Scope name uniqueness to group+name instead of global name
+  - Derive file slugs and import names from group+name to avoid collisions
+  - Replace `roots` config field with `includes`/`excludes` glob patterns
+  - Add `groups` config field for pattern-based group assignment via picomatch
+  - Frontmatter `group` takes precedence over config-defined groups
+  - Updated banner format for generated files
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -39,7 +39,7 @@ You are a {{ tone }} writer.
 ### Generate typed modules
 
 ```bash
-npx funkai prompts generate --out .prompts/client --roots src/agents
+npx funkai prompts generate --out .prompts/client --includes "src/agents/**"
 ```
 
 ### Consume prompts
@@ -94,8 +94,8 @@ Use `{% render 'name', key: 'value' %}` to include shared partials. Partials res
 
 ## Documentation
 
-For comprehensive documentation, see [docs/overview.md](docs/overview.md).
+For comprehensive documentation, see the [Prompts concept](/concepts/prompts) and [Prompts CLI reference](/reference/prompts/cli).
 
 ## License
 
-[MIT](../../LICENSE)
+[MIT](https://github.com/joggrdocs/funkai/blob/main/LICENSE)

package/dist/lib/cli.d.mts

@@ -1,5 +1,5 @@
-import { n as Liquid, t as CreateEngineOptions } from "./types-2PI_9h-M.mjs";
-import { t as createEngine } from "./engine-CQfJbVz6.mjs";
+import { n as Liquid, t as CreateEngineOptions } from "./types-DmnHC99v.mjs";
+import { t as createEngine } from "./engine-BAYeiay3.mjs";
 
 //#region src/clean.d.ts
 /**

package/dist/lib/cli.mjs

@@ -1,4 +1,4 @@
-import { t as createEngine } from "./engine-CPKs9QbX.mjs";
+import { t as createEngine } from "./engine-Bhv5Zxdu.mjs";
 import { flow } from "es-toolkit";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/lib/{engine-CQfJbVz6.d.mts → engine-BAYeiay3.d.mts}

@@ -1,4 +1,4 @@
-import { t as CreateEngineOptions } from "./types-2PI_9h-M.mjs";
+import { t as CreateEngineOptions } from "./types-DmnHC99v.mjs";
 import { Liquid } from "liquidjs";
 
 //#region src/engine.d.ts
@@ -25,4 +25,4 @@ declare function createEngine(partialsDir: string, options?: Partial<CreateEngin
 declare const liquidEngine: Liquid;
 //#endregion
 export { liquidEngine as n, createEngine as t };
-//# sourceMappingURL=engine-CQfJbVz6.d.mts.map
+//# sourceMappingURL=engine-BAYeiay3.d.mts.map

package/dist/lib/{engine-CQfJbVz6.d.mts.map → engine-BAYeiay3.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"engine-CQfJbVz6.d.mts","names":[],"sources":["../../src/engine.ts"],"mappings":";;;;;;AAcA;;;;;;;;iBAAgB,YAAA,CAAa,WAAA,UAAqB,OAAA,GAAU,OAAA,CAAQ,mBAAA,IAAuB,MAAA;;;;;;;AAsB3F;;;cAAa,YAAA,EAAY,MAAA"}
+{"version":3,"file":"engine-BAYeiay3.d.mts","names":[],"sources":["../../src/engine.ts"],"mappings":";;;;;;AAcA;;;;;;;;iBAAgB,YAAA,CAAa,WAAA,UAAqB,OAAA,GAAU,OAAA,CAAQ,mBAAA,IAAuB,MAAA;;;;;;;AAuB3F;;;cAAa,YAAA,EAAY,MAAA"}

package/dist/lib/{engine-CPKs9QbX.mjs → engine-Bhv5Zxdu.mjs}

@@ -18,6 +18,7 @@ function createEngine(partialsDir, options) {
 		cache: true,
 		...options,
 		strictFilters: true,
+		strictVariables: true,
 		ownPropertyOnly: true
 	});
 }
@@ -32,9 +33,10 @@ function createEngine(partialsDir, options) {
 */
 const liquidEngine = new Liquid({
 	strictFilters: true,
+	strictVariables: true,
 	ownPropertyOnly: true
 });
 //#endregion
 export { liquidEngine as n, createEngine as t };
 
-//# sourceMappingURL=engine-CPKs9QbX.mjs.map
+//# sourceMappingURL=engine-Bhv5Zxdu.mjs.map

package/dist/lib/{engine-CPKs9QbX.mjs.map → engine-Bhv5Zxdu.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"engine-CPKs9QbX.mjs","names":[],"sources":["../../src/engine.ts"],"sourcesContent":["import { Liquid } from \"liquidjs\";\n\nimport type { CreateEngineOptions } from \"./types.js\";\n\n/**\n * Create a LiquidJS engine with custom options.\n *\n * The `partialsDir` is used as the root for `{% render %}` resolution.\n * The `.prompt` extension is appended automatically.\n *\n * @param partialsDir - Root directory for `{% render %}` partial resolution.\n * @param options - Optional overrides for the LiquidJS engine configuration.\n * @returns A configured {@link Liquid} engine instance.\n */\nexport function createEngine(partialsDir: string, options?: Partial<CreateEngineOptions>): Liquid {\n  return new Liquid({\n    root: [partialsDir],\n    partials: [partialsDir],\n    extname: \".prompt\",\n    cache: true,\n    ...options,\n    // Safety defaults — applied after spread so callers cannot disable them\n    strictFilters: true,\n    ownPropertyOnly: true,\n  });\n}\n\n/**\n * Shared LiquidJS engine for rendering prompt templates at runtime.\n *\n * Partials are flattened at codegen time by the CLI, so this engine\n * only needs to handle `{{ var }}` expressions and basic Liquid\n * control flow (`{% if %}`, `{% for %}`). No filesystem access required.\n *\n * @type {Liquid}\n */\nexport const liquidEngine = new Liquid({\n  strictFilters: true,\n  ownPropertyOnly: true,\n});\n"],"mappings":";;;;;;;;;;;;AAcA,SAAgB,aAAa,aAAqB,SAAgD;AAChG,QAAO,IAAI,OAAO;EAChB,MAAM,CAAC,YAAY;EACnB,UAAU,CAAC,YAAY;EACvB,SAAS;EACT,OAAO;EACP,GAAG;EAEH,eAAe;EACf,iBAAiB;EAClB,CAAC;;;;;;;;;;;AAYJ,MAAa,eAAe,IAAI,OAAO;CACrC,eAAe;CACf,iBAAiB;CAClB,CAAC"}
+{"version":3,"file":"engine-Bhv5Zxdu.mjs","names":[],"sources":["../../src/engine.ts"],"sourcesContent":["import { Liquid } from \"liquidjs\";\n\nimport type { CreateEngineOptions } from \"./types.js\";\n\n/**\n * Create a LiquidJS engine with custom options.\n *\n * The `partialsDir` is used as the root for `{% render %}` resolution.\n * The `.prompt` extension is appended automatically.\n *\n * @param partialsDir - Root directory for `{% render %}` partial resolution.\n * @param options - Optional overrides for the LiquidJS engine configuration.\n * @returns A configured {@link Liquid} engine instance.\n */\nexport function createEngine(partialsDir: string, options?: Partial<CreateEngineOptions>): Liquid {\n  return new Liquid({\n    root: [partialsDir],\n    partials: [partialsDir],\n    extname: \".prompt\",\n    cache: true,\n    ...options,\n    // Safety defaults — applied after spread so callers cannot disable them\n    strictFilters: true,\n    strictVariables: true,\n    ownPropertyOnly: true,\n  });\n}\n\n/**\n * Shared LiquidJS engine for rendering prompt templates at runtime.\n *\n * Partials are flattened at codegen time by the CLI, so this engine\n * only needs to handle `{{ var }}` expressions and basic Liquid\n * control flow (`{% if %}`, `{% for %}`). No filesystem access required.\n *\n * @type {Liquid}\n */\nexport const liquidEngine = new Liquid({\n  strictFilters: true,\n  strictVariables: true,\n  ownPropertyOnly: true,\n});\n"],"mappings":";;;;;;;;;;;;AAcA,SAAgB,aAAa,aAAqB,SAAgD;AAChG,QAAO,IAAI,OAAO;EAChB,MAAM,CAAC,YAAY;EACnB,UAAU,CAAC,YAAY;EACvB,SAAS;EACT,OAAO;EACP,GAAG;EAEH,eAAe;EACf,iBAAiB;EACjB,iBAAiB;EAClB,CAAC;;;;;;;;;;;AAYJ,MAAa,eAAe,IAAI,OAAO;CACrC,eAAe;CACf,iBAAiB;CACjB,iBAAiB;CAClB,CAAC"}

package/dist/lib/index.d.mts

@@ -1,5 +1,62 @@
-import { a as PromptRegistry, i as PromptNamespace, r as PromptModule } from "./types-2PI_9h-M.mjs";
+import { a as PromptNamespace, i as PromptModule, o as PromptRegistry, r as PromptConfig } from "./types-DmnHC99v.mjs";
 
+//#region src/group.d.ts
+/**
+ * Create a prompt group namespace from a record of prompt modules.
+ *
+ * Sets the `group` field on each module to the given group name,
+ * producing a new namespace object without mutating the originals.
+ *
+ * @param name - Group name applied to each prompt (e.g. `'agents'`, `'agents/core'`).
+ * @param prompts - Record of prompt modules to group.
+ * @returns A new {@link PromptNamespace} with group-tagged prompt modules.
+ *
+ * @example
+ * ```ts
+ * import { createPrompt, createPromptGroup } from '@funkai/prompts'
+ * import { z } from 'zod'
+ *
+ * const agents = createPromptGroup('agents', {
+ *   greeting: createPrompt({
+ *     name: 'greeting',
+ *     template: 'Hello {{ name }}!',
+ *     schema: z.object({ name: z.string() }),
+ *   }),
+ * })
+ *
+ * agents.greeting.render({ name: 'Alice' })
+ * ```
+ */
+declare function createPromptGroup<T extends Record<string, PromptModule>>(name: string, prompts: T): T;
+//#endregion
+//#region src/prompt.d.ts
+/**
+ * Create a prompt module from a config object.
+ *
+ * Encapsulates template rendering (via LiquidJS) and variable validation
+ * (via Zod) into a single {@link PromptModule}. Works for both codegen
+ * output and runtime on-the-fly prompt construction.
+ *
+ * @param config - Prompt configuration with name, template, schema, and optional group.
+ * @returns A {@link PromptModule} with `render` and `validate` methods.
+ *
+ * @example
+ * ```ts
+ * import { createPrompt } from '@funkai/prompts'
+ * import { z } from 'zod'
+ *
+ * const greeting = createPrompt({
+ *   name: 'greeting',
+ *   template: 'Hello {{ name }}, welcome to {{ place }}!',
+ *   schema: z.object({ name: z.string(), place: z.string() }),
+ * })
+ *
+ * greeting.render({ name: 'Alice', place: 'Wonderland' })
+ * // => "Hello Alice, welcome to Wonderland!"
+ * ```
+ */
+declare function createPrompt<T>(config: PromptConfig<T>): PromptModule<T>;
+//#endregion
 //#region src/registry.d.ts
 /**
  * Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.
@@ -22,5 +79,5 @@ import { a as PromptRegistry, i as PromptNamespace, r as PromptModule } from "./
  */
 declare function createPromptRegistry<T extends PromptNamespace>(modules: T): PromptRegistry<T>;
 //#endregion
-export { type PromptModule, type PromptNamespace, type PromptRegistry, createPromptRegistry };
+export { type PromptConfig, type PromptModule, type PromptNamespace, type PromptRegistry, createPrompt, createPromptGroup, createPromptRegistry };
 //# sourceMappingURL=index.d.mts.map

package/dist/lib/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/registry.ts"],"mappings":";;;;;AAqBA;;;;;;;;;;;;;;;;;iBAAgB,oBAAA,WAA+B,eAAA,CAAA,CAAiB,OAAA,EAAS,CAAA,GAAI,cAAA,CAAe,CAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/group.ts","../../src/prompt.ts","../../src/registry.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;ACAA;;;iBDAgB,iBAAA,WAA4B,MAAA,SAAe,YAAA,EAAA,CACzD,IAAA,UACA,OAAA,EAAS,CAAA,GACR,CAAA;;;;;AAHH;;;;;;;;;;;;;;;;;;;;;ACAA;;iBAAgB,YAAA,GAAA,CAAgB,MAAA,EAAQ,YAAA,CAAa,CAAA,IAAK,YAAA,CAAa,CAAA;;;;;ADAvE;;;;;;;;;;;;;;;;;iBEPgB,oBAAA,WAA+B,eAAA,CAAA,CAAiB,OAAA,EAAS,CAAA,GAAI,cAAA,CAAe,CAAA"}

package/dist/lib/index.mjs

@@ -1,3 +1,79 @@
+import { n as liquidEngine } from "./engine-Bhv5Zxdu.mjs";
+//#region src/group.ts
+/**
+* Create a prompt group namespace from a record of prompt modules.
+*
+* Sets the `group` field on each module to the given group name,
+* producing a new namespace object without mutating the originals.
+*
+* @param name - Group name applied to each prompt (e.g. `'agents'`, `'agents/core'`).
+* @param prompts - Record of prompt modules to group.
+* @returns A new {@link PromptNamespace} with group-tagged prompt modules.
+*
+* @example
+* ```ts
+* import { createPrompt, createPromptGroup } from '@funkai/prompts'
+* import { z } from 'zod'
+*
+* const agents = createPromptGroup('agents', {
+*   greeting: createPrompt({
+*     name: 'greeting',
+*     template: 'Hello {{ name }}!',
+*     schema: z.object({ name: z.string() }),
+*   }),
+* })
+*
+* agents.greeting.render({ name: 'Alice' })
+* ```
+*/
+function createPromptGroup(name, prompts) {
+	return Object.fromEntries(Object.entries(prompts).map(([key, module]) => [key, {
+		...module,
+		group: name
+	}]));
+}
+//#endregion
+//#region src/prompt.ts
+/**
+* Create a prompt module from a config object.
+*
+* Encapsulates template rendering (via LiquidJS) and variable validation
+* (via Zod) into a single {@link PromptModule}. Works for both codegen
+* output and runtime on-the-fly prompt construction.
+*
+* @param config - Prompt configuration with name, template, schema, and optional group.
+* @returns A {@link PromptModule} with `render` and `validate` methods.
+*
+* @example
+* ```ts
+* import { createPrompt } from '@funkai/prompts'
+* import { z } from 'zod'
+*
+* const greeting = createPrompt({
+*   name: 'greeting',
+*   template: 'Hello {{ name }}, welcome to {{ place }}!',
+*   schema: z.object({ name: z.string(), place: z.string() }),
+* })
+*
+* greeting.render({ name: 'Alice', place: 'Wonderland' })
+* // => "Hello Alice, welcome to Wonderland!"
+* ```
+*/
+function createPrompt(config) {
+	const { name, group, template, schema } = config;
+	return {
+		name,
+		group,
+		schema,
+		render(variables) {
+			return liquidEngine.parseAndRenderSync(template, schema.parse(variables));
+		},
+		validate(variables) {
+			return schema.parse(variables);
+		}
+	};
+}
+//#endregion
 //#region src/registry.ts
 /**
 * Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.
@@ -42,11 +118,15 @@ function isPromptModule(value) {
 * @private
 */
 function deepFreeze(obj) {
-	Object.freeze(obj);
-	for (const value of Object.values(obj)) if (typeof value === "object" && value !== null && !Object.isFrozen(value) && !isPromptModule(value)) deepFreeze(value);
-	return obj;
+	const copied = Object.entries(obj).reduce((acc, [key, value]) => {
+		if (typeof value === "object" && value !== null && !isPromptModule(value)) acc[key] = deepFreeze({ ...value });
+		else acc[key] = value;
+		return acc;
+	}, {});
+	Object.freeze(copied);
+	return copied;
 }
 //#endregion
-export { createPromptRegistry };
+export { createPrompt, createPromptGroup, createPromptRegistry };
 
 //# sourceMappingURL=index.mjs.map

package/dist/lib/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/registry.ts"],"sourcesContent":["import type { PromptModule, PromptNamespace, PromptRegistry } from \"./types.js\";\n\n/**\n * Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.\n *\n * The registry is typically created by generated code — the CLI produces\n * an `index.ts` that calls `createPromptRegistry()` with all discovered\n * prompt modules keyed by camelCase name, nested by group.\n *\n * @param modules - Record mapping camelCase prompt names (or group namespaces) to their modules.\n * @returns A deep-frozen, typed record with direct property access.\n *\n * @example\n * ```ts\n * const prompts = createPromptRegistry({\n *   agents: { coverageAssessor },\n *   greeting,\n * })\n * prompts.agents.coverageAssessor.render({ scope: 'full' })\n * ```\n */\nexport function createPromptRegistry<T extends PromptNamespace>(modules: T): PromptRegistry<T> {\n  return deepFreeze({ ...modules });\n}\n\n// ---------------------------------------------------------------------------\n// Private\n// ---------------------------------------------------------------------------\n\n/**\n * Check whether a value looks like a PromptModule leaf.\n * Leaves have `name`, `schema`, and `render` — namespaces do not.\n *\n * @private\n */\nfunction isPromptModule(value: unknown): value is PromptModule {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"render\" in value &&\n    \"schema\" in value &&\n    \"name\" in value\n  );\n}\n\n/**\n * Recursively freeze a prompt namespace tree.\n * Only recurses into plain namespace nodes — PromptModule leaves\n * (which contain Zod schemas) are intentionally left unfrozen\n * to avoid breaking Zod internal state.\n *\n * @param obj - The namespace object to freeze.\n * @returns The frozen object cast to its deep-readonly type.\n *\n * @private\n */\nfunction deepFreeze<T extends PromptNamespace>(obj: T): PromptRegistry<T> {\n  Object.freeze(obj);\n  for (const value of Object.values(obj)) {\n    if (\n      typeof value === \"object\" &&\n      value !== null &&\n      !Object.isFrozen(value) &&\n      !isPromptModule(value)\n    ) {\n      deepFreeze(value as PromptNamespace);\n    }\n  }\n  return obj as PromptRegistry<T>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,qBAAgD,SAA+B;AAC7F,QAAO,WAAW,EAAE,GAAG,SAAS,CAAC;;;;;;;;AAanC,SAAS,eAAe,OAAuC;AAC7D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,YAAY,SACZ,YAAY,SACZ,UAAU;;;;;;;;;;;;;AAed,SAAS,WAAsC,KAA2B;AACxE,QAAO,OAAO,IAAI;AAClB,MAAK,MAAM,SAAS,OAAO,OAAO,IAAI,CACpC,KACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,OAAO,SAAS,MAAM,IACvB,CAAC,eAAe,MAAM,CAEtB,YAAW,MAAyB;AAGxC,QAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/group.ts","../../src/prompt.ts","../../src/registry.ts"],"sourcesContent":["import type { PromptModule } from \"./types.js\";\n\n/**\n * Create a prompt group namespace from a record of prompt modules.\n *\n * Sets the `group` field on each module to the given group name,\n * producing a new namespace object without mutating the originals.\n *\n * @param name - Group name applied to each prompt (e.g. `'agents'`, `'agents/core'`).\n * @param prompts - Record of prompt modules to group.\n * @returns A new {@link PromptNamespace} with group-tagged prompt modules.\n *\n * @example\n * ```ts\n * import { createPrompt, createPromptGroup } from '@funkai/prompts'\n * import { z } from 'zod'\n *\n * const agents = createPromptGroup('agents', {\n *   greeting: createPrompt({\n *     name: 'greeting',\n *     template: 'Hello {{ name }}!',\n *     schema: z.object({ name: z.string() }),\n *   }),\n * })\n *\n * agents.greeting.render({ name: 'Alice' })\n * ```\n */\nexport function createPromptGroup<T extends Record<string, PromptModule>>(\n  name: string,\n  prompts: T,\n): T {\n  return Object.fromEntries(\n    Object.entries(prompts).map(([key, module]) => [key, { ...module, group: name }]),\n  ) as T;\n}\n","import { liquidEngine } from \"./engine.js\";\nimport type { PromptConfig, PromptModule } from \"./types.js\";\n\n/**\n * Create a prompt module from a config object.\n *\n * Encapsulates template rendering (via LiquidJS) and variable validation\n * (via Zod) into a single {@link PromptModule}. Works for both codegen\n * output and runtime on-the-fly prompt construction.\n *\n * @param config - Prompt configuration with name, template, schema, and optional group.\n * @returns A {@link PromptModule} with `render` and `validate` methods.\n *\n * @example\n * ```ts\n * import { createPrompt } from '@funkai/prompts'\n * import { z } from 'zod'\n *\n * const greeting = createPrompt({\n *   name: 'greeting',\n *   template: 'Hello {{ name }}, welcome to {{ place }}!',\n *   schema: z.object({ name: z.string(), place: z.string() }),\n * })\n *\n * greeting.render({ name: 'Alice', place: 'Wonderland' })\n * // => \"Hello Alice, welcome to Wonderland!\"\n * ```\n */\nexport function createPrompt<T>(config: PromptConfig<T>): PromptModule<T> {\n  const { name, group, template, schema } = config;\n\n  return {\n    name,\n    group,\n    schema,\n    /**\n     * Render the prompt template with the given variables.\n     *\n     * @param variables - Template variables matching the prompt schema.\n     * @returns The rendered prompt string.\n     * @throws {ZodError} If variables fail schema validation.\n     */\n    render(variables: T): string {\n      return liquidEngine.parseAndRenderSync(\n        template,\n        schema.parse(variables) as Record<string, unknown>,\n      );\n    },\n    /**\n     * Validate variables against the prompt schema.\n     *\n     * @param variables - Variables to validate.\n     * @returns The parsed and validated variables.\n     * @throws {ZodError} If variables fail schema validation.\n     */\n    validate(variables: unknown): T {\n      return schema.parse(variables);\n    },\n  };\n}\n","import type { PromptModule, PromptNamespace, PromptRegistry } from \"./types.js\";\n\n/**\n * Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.\n *\n * The registry is typically created by generated code — the CLI produces\n * an `index.ts` that calls `createPromptRegistry()` with all discovered\n * prompt modules keyed by camelCase name, nested by group.\n *\n * @param modules - Record mapping camelCase prompt names (or group namespaces) to their modules.\n * @returns A deep-frozen, typed record with direct property access.\n *\n * @example\n * ```ts\n * const prompts = createPromptRegistry({\n *   agents: { coverageAssessor },\n *   greeting,\n * })\n * prompts.agents.coverageAssessor.render({ scope: 'full' })\n * ```\n */\nexport function createPromptRegistry<T extends PromptNamespace>(modules: T): PromptRegistry<T> {\n  return deepFreeze({ ...modules });\n}\n\n// ---------------------------------------------------------------------------\n// Private\n// ---------------------------------------------------------------------------\n\n/**\n * Check whether a value looks like a PromptModule leaf.\n * Leaves have `name`, `schema`, and `render` — namespaces do not.\n *\n * @private\n */\nfunction isPromptModule(value: unknown): value is PromptModule {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"render\" in value &&\n    \"schema\" in value &&\n    \"name\" in value\n  );\n}\n\n/**\n * Recursively freeze a prompt namespace tree.\n * Only recurses into plain namespace nodes — PromptModule leaves\n * (which contain Zod schemas) are intentionally left unfrozen\n * to avoid breaking Zod internal state.\n *\n * @param obj - The namespace object to freeze.\n * @returns The frozen object cast to its deep-readonly type.\n *\n * @private\n */\nfunction deepFreeze<T extends PromptNamespace>(obj: T): PromptRegistry<T> {\n  const copied = Object.entries(obj).reduce<Record<string, unknown>>((acc, [key, value]) => {\n    const isNamespace = typeof value === \"object\" && value !== null && !isPromptModule(value);\n    if (isNamespace) {\n      acc[key] = deepFreeze({ ...value } as PromptNamespace);\n    } else {\n      acc[key] = value;\n    }\n    return acc;\n  }, {});\n\n  Object.freeze(copied);\n  return copied as PromptRegistry<T>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,kBACd,MACA,SACG;AACH,QAAO,OAAO,YACZ,OAAO,QAAQ,QAAQ,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,KAAK;EAAE,GAAG;EAAQ,OAAO;EAAM,CAAC,CAAC,CAClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACNH,SAAgB,aAAgB,QAA0C;CACxE,MAAM,EAAE,MAAM,OAAO,UAAU,WAAW;AAE1C,QAAO;EACL;EACA;EACA;EAQA,OAAO,WAAsB;AAC3B,UAAO,aAAa,mBAClB,UACA,OAAO,MAAM,UAAU,CACxB;;EASH,SAAS,WAAuB;AAC9B,UAAO,OAAO,MAAM,UAAU;;EAEjC;;;;;;;;;;;;;;;;;;;;;;;ACrCH,SAAgB,qBAAgD,SAA+B;AAC7F,QAAO,WAAW,EAAE,GAAG,SAAS,CAAC;;;;;;;;AAanC,SAAS,eAAe,OAAuC;AAC7D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,YAAY,SACZ,YAAY,SACZ,UAAU;;;;;;;;;;;;;AAed,SAAS,WAAsC,KAA2B;CACxE,MAAM,SAAS,OAAO,QAAQ,IAAI,CAAC,QAAiC,KAAK,CAAC,KAAK,WAAW;AAExF,MADoB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,eAAe,MAAM,CAEvF,KAAI,OAAO,WAAW,EAAE,GAAG,OAAO,CAAoB;MAEtD,KAAI,OAAO;AAEb,SAAO;IACN,EAAE,CAAC;AAEN,QAAO,OAAO,OAAO;AACrB,QAAO"}

package/dist/lib/runtime.d.mts

@@ -1,2 +1,2 @@
-import { n as liquidEngine } from "./engine-CQfJbVz6.mjs";
+import { n as liquidEngine } from "./engine-BAYeiay3.mjs";
 export { liquidEngine };

package/dist/lib/runtime.mjs

@@ -1,2 +1,2 @@
-import { n as liquidEngine } from "./engine-CPKs9QbX.mjs";
+import { n as liquidEngine } from "./engine-Bhv5Zxdu.mjs";
 export { liquidEngine };

package/dist/lib/{types-2PI_9h-M.d.mts → types-DmnHC99v.d.mts}

@@ -7,7 +7,29 @@ import { ZodType } from "zod";
  */
 type CreateEngineOptions = Pick<LiquidOptions, "root" | "partials" | "extname" | "cache" | "strictVariables">;
 /**
- * A single prompt module produced by codegen.
+ * Configuration for creating a prompt module via {@link createPrompt}.
+ *
+ * @example
+ * ```ts
+ * const config: PromptConfig<{ name: string }> = {
+ *   name: 'greeting',
+ *   template: 'Hello {{ name }}!',
+ *   schema: z.object({ name: z.string() }),
+ * }
+ * ```
+ */
+interface PromptConfig<T = unknown> {
+  /** Kebab-case prompt identifier (e.g. `'greeting'`, `'worker-system'`). */
+  readonly name: string;
+  /** LiquidJS template string with `{{ variable }}` expressions. */
+  readonly template: string;
+  /** Zod schema for validating template variables. */
+  readonly schema: ZodType<T>;
+  /** Optional group path (e.g. `'agents'`, `'agents/core'`). */
+  readonly group?: string;
+}
+/**
+ * A single prompt module produced by {@link createPrompt} or codegen.
  *
  * Each `.prompt` file generates a default export conforming to this shape.
  */
@@ -39,5 +61,5 @@ interface PromptNamespace {
  */
 type PromptRegistry<T extends PromptNamespace> = { readonly [K in keyof T]: T[K] extends PromptModule ? T[K] : T[K] extends PromptNamespace ? PromptRegistry<T[K]> : T[K] };
 //#endregion
-export { PromptRegistry as a, PromptNamespace as i, Liquid$1 as n, PromptModule as r, CreateEngineOptions as t };
-//# sourceMappingURL=types-2PI_9h-M.d.mts.map
+export { PromptNamespace as a, PromptModule as i, Liquid$1 as n, PromptRegistry as o, PromptConfig as r, CreateEngineOptions as t };
+//# sourceMappingURL=types-DmnHC99v.d.mts.map

package/dist/lib/types-DmnHC99v.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-DmnHC99v.d.mts","names":[],"sources":["../../src/types.ts"],"mappings":";;;;;;AAMA;KAAY,mBAAA,GAAsB,IAAA,CAChC,aAAA;;;;AAgBF;;;;;;;;;UAAiB,YAAA;EAQN;EAAA,SANA,IAAA;EAMK;EAAA,SAJL,QAAA;EAYkB;EAAA,SAVlB,MAAA,EAAQ,OAAA,CAAQ,CAAA;EAaA;EAAA,SAXhB,KAAA;AAAA;;;;;;UAQM,YAAA;EAAA,SACN,IAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA,EAAQ,OAAA,CAAQ,CAAA;EACzB,MAAA,CAAO,SAAA,EAAW,CAAA;EAClB,QAAA,CAAS,SAAA,YAAqB,CAAA;AAAA;;;;;UAOf,eAAA;EAAA,UACL,GAAA,WAAc,YAAA,GAAe,eAAA;AAAA;;;;;;;;AAezC;;;;;KAAY,cAAA,WAAyB,eAAA,2BACd,CAAA,GAAI,CAAA,CAAE,CAAA,UAAW,YAAA,GAClC,CAAA,CAAE,CAAA,IACF,CAAA,CAAE,CAAA,UAAW,eAAA,GACX,cAAA,CAAe,CAAA,CAAE,CAAA,KACjB,CAAA,CAAE,CAAA"}

package/docs/cli/commands.md

@@ -6,14 +6,14 @@ Generate typed TypeScript modules from `.prompt` files.
 
 **Alias:** `gen`
 
-| Flag       | Alias | Required | Description                                             |
-| ---------- | ----- | -------- | ------------------------------------------------------- |
-| `--out`    | `-o`  | Yes      | Output directory for generated files                    |
-| `--roots`  | `-r`  | Yes      | Space-separated directories to scan for `.prompt` files |
-| `--silent` | ---   | No       | Suppress output except errors                           |
+| Flag         | Alias | Required | Description                               |
+| ------------ | ----- | -------- | ----------------------------------------- |
+| `--out`      | `-o`  | Yes      | Output directory for generated files      |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files |
+| `--silent`   | ---   | No       | Suppress output except errors             |
 
 ```bash
-prompts generate --out .prompts/client --roots prompts src/agents src/workflows
+prompts generate --out .prompts/client --includes "prompts/**" "src/agents/**" "src/workflows/**"
 ```
 
 Custom partials are auto-discovered from the sibling `partials/` directory (relative to `--out`).
@@ -26,7 +26,7 @@ Validate `.prompt` files without generating output.
 
 | Flag         | Alias | Required | Description                                              |
 | ------------ | ----- | -------- | -------------------------------------------------------- |
-| `--roots`    | `-r`  | Yes      | Directories to scan                                      |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files                |
 | `--partials` | `-p`  | No       | Custom partials directory (default: `.prompts/partials`) |
 | `--silent`   | ---   | No       | Suppress output except errors                            |
 
@@ -38,7 +38,7 @@ Validate `.prompt` files without generating output.
 | Warn  | Schema variable not used in template     |
 
 ```bash
-prompts lint --roots prompts src/agents
+prompts lint --includes "prompts/**" "src/agents/**"
 ```
 
 ## `prompts create`

package/docs/cli/overview.md

@@ -61,7 +61,7 @@ Add a generate script to your `package.json`:
 ```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/cli.md

@@ -0,0 +1,132 @@
+# CLI
+
+The `prompts` CLI discovers, validates, and generates typed TypeScript from `.prompt` files.
+
+## Installation
+
+Available as the `prompts` binary from `@funkai/cli`. Install it as a workspace dependency:
+
+```bash
+pnpm add @funkai/cli --workspace
+```
+
+## Workflow
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#313244',
+    'primaryTextColor': '#cdd6f4',
+    'primaryBorderColor': '#6c7086',
+    'lineColor': '#89b4fa',
+    'secondaryColor': '#45475a',
+    'tertiaryColor': '#1e1e2e',
+    'actorBkg': '#313244',
+    'actorBorder': '#89b4fa',
+    'actorTextColor': '#cdd6f4',
+    'signalColor': '#cdd6f4',
+    'signalTextColor': '#cdd6f4'
+  }
+}}%%
+sequenceDiagram
+    participant Dev as Developer
+    participant CLI as prompts CLI
+    participant FS as File System
+
+    Dev->>CLI: prompts generate
+    CLI->>FS: Discover .prompt files from --includes globs
+    CLI->>CLI: Parse frontmatter + extract variables
+    CLI->>CLI: Lint (schema vs template match)
+    CLI->>CLI: Flatten partials
+    CLI->>FS: Write generated .ts modules
+    FS-->>Dev: Import typed prompts from ~prompts
+```
+
+## Commands Reference
+
+### `prompts generate`
+
+Generate typed TypeScript modules from `.prompt` files.
+
+**Alias:** `gen`
+
+| Flag         | Alias | Required | Description                               |
+| ------------ | ----- | -------- | ----------------------------------------- |
+| `--out`      | `-o`  | Yes      | Output directory for generated files      |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files |
+| `--silent`   | ---   | No       | Suppress output except errors             |
+
+```bash
+prompts generate --out .prompts/client --includes "prompts/**" "src/agents/**" "src/workflows/**"
+```
+
+Custom partials are auto-discovered from the sibling `partials/` directory (relative to `--out`).
+
+Runs lint validation automatically before generating. Exits with code 1 on lint errors.
+
+### `prompts lint`
+
+Validate `.prompt` files without generating output.
+
+| Flag         | Alias | Required | Description                                              |
+| ------------ | ----- | -------- | -------------------------------------------------------- |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files                |
+| `--partials` | `-p`  | No       | Custom partials directory (default: `.prompts/partials`) |
+| `--silent`   | ---   | No       | Suppress output except errors                            |
+
+**Diagnostics:**
+
+| Level | Meaning                                  |
+| ----- | ---------------------------------------- |
+| Error | Template variable not declared in schema |
+| Warn  | Schema variable not used in template     |
+
+```bash
+prompts lint --includes "prompts/**" "src/agents/**"
+```
+
+### `prompts create`
+
+Scaffold a new `.prompt` file.
+
+| Arg/Flag    | Required | Description                                                   |
+| ----------- | -------- | ------------------------------------------------------------- |
+| `<name>`    | Yes      | Prompt name (kebab-case)                                      |
+| `--out`     | No       | Output directory (defaults to cwd)                            |
+| `--partial` | No       | Create as a partial in `.prompts/partials/` (ignores `--out`) |
+
+```bash
+prompts create coverage-assessor --out src/agents/coverage-assessor
+prompts create summary --partial
+```
+
+### `prompts setup`
+
+Interactive project configuration for `.prompt` development. No flags -- fully interactive.
+
+Configures:
+
+1. VSCode file association (`*.prompt` -> Markdown)
+2. VSCode Liquid extension recommendation
+3. `.gitignore` entry for generated `.prompts/client/` directory
+4. `tsconfig.json` path alias (`~prompts` -> `./.prompts/client/index.ts`)
+
+## Integration
+
+Add a generate script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "prompts:generate": "prompts generate --out .prompts/client --includes \"prompts/**\" \"src/agents/**\""
+  }
+}
+```
+
+## References
+
+- [File Format](file-format.md)
+- [Code Generation & Library](codegen.md)
+- [Setup](setup.md)
+- [Troubleshooting](troubleshooting.md)