@funkai/cli 0.1.3 → 0.2.0

package/src/lib/prompts/__tests__/flatten.test.ts

@@ -6,11 +6,11 @@ import { flattenPartials } from "@/lib/prompts/flatten.js";
 
 const PARTIALS_DIR = resolve(import.meta.dirname, "../../../../../prompts/src/prompts");
 
-describe("flattenPartials", () => {
+describe(flattenPartials, () => {
   describe("param parsing", () => {
     it("resolves a single literal param", () => {
       const template = "{% render 'identity', role: 'Bot' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("You are Bot, .");
@@ -19,14 +19,14 @@ describe("flattenPartials", () => {
 
     it("resolves multiple literal params", () => {
       const template = "{% render 'identity', role: 'TestBot', desc: 'a test agent' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are TestBot, a test agent.");
     });
 
     it("accepts an empty string as a valid literal param value", () => {
       const template = "{% render 'identity', role: '', desc: 'helper' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are , helper.");
       expect(result).not.toContain("{% render");
@@ -35,7 +35,7 @@ describe("flattenPartials", () => {
     it("throws when the first param uses a variable reference", () => {
       const template = "{% render 'identity', role: agentRole, desc: 'helper' %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow(
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
         'parameter "role" uses a variable reference',
       );
     });
@@ -43,7 +43,7 @@ describe("flattenPartials", () => {
     it("throws when a non-first param uses a variable reference", () => {
       const template = "{% render 'identity', role: 'Bot', desc: myDesc %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow(
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
         'parameter "desc" uses a variable reference',
       );
     });
@@ -51,19 +51,21 @@ describe("flattenPartials", () => {
     it("throws when all params are variable references", () => {
       const template = "{% render 'identity', role: agentRole, desc: agentDesc %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow("uses a variable reference");
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
+        "uses a variable reference",
+      );
     });
 
     it("handles extra whitespace around colons in params", () => {
       const template = "{% render 'identity', role  :  'Bot', desc  :  'helper' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
     });
 
     it("handles param values containing spaces", () => {
       const template = "{% render 'identity', role: 'Test Bot', desc: 'a helpful assistant' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Test Bot, a helpful assistant.");
     });
@@ -72,12 +74,12 @@ describe("flattenPartials", () => {
   describe("render tag parsing", () => {
     it("returns template unchanged when no render tags exist", () => {
       const template = "<identity>\nYou are a bot.\n</identity>";
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("parses a render tag with no params", () => {
       const template = "{% render 'identity' %}\n\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("</identity>");
@@ -86,7 +88,7 @@ describe("flattenPartials", () => {
 
     it("parses left-only whitespace trim {%-", () => {
       const template = "{%- render 'identity', role: 'Bot', desc: 'helper' %}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("{%-");
@@ -94,7 +96,7 @@ describe("flattenPartials", () => {
 
     it("parses right-only whitespace trim -%}", () => {
       const template = "{% render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("-%}");
@@ -102,7 +104,7 @@ describe("flattenPartials", () => {
 
     it("parses both-side whitespace trim {%- -%}", () => {
       const template = "{%- render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("{%");
@@ -110,19 +112,19 @@ describe("flattenPartials", () => {
 
     it("handles extra whitespace between {% and render keyword", () => {
       const template = "{%    render 'identity', role: 'Bot', desc: 'helper' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
     });
 
     it("does not match render tags with double quotes", () => {
       const template = '{% render "identity" %}';
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("does not match malformed render tags without closing %}", () => {
       const template = "{% render 'identity'";
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
   });
 
@@ -130,7 +132,7 @@ describe("flattenPartials", () => {
     it("flattens identity partial with literal params", () => {
       const template =
         "{% render 'identity', role: 'TestBot', desc: 'a test agent' %}\n\nFollow instructions.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("You are TestBot, a test agent.");
@@ -141,7 +143,7 @@ describe("flattenPartials", () => {
 
     it("flattens constraints partial with no bindings", () => {
       const template = "{% render 'constraints' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<constraints>");
       expect(result).toContain("</constraints>");
@@ -153,7 +155,7 @@ describe("flattenPartials", () => {
 
     it("flattens tools partial with no bindings (else branch)", () => {
       const template = "{% render 'tools' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<tools>");
       expect(result).toContain("</tools>");
@@ -168,7 +170,7 @@ describe("flattenPartials", () => {
         "{% render 'identity', role: 'Agent', desc: 'analyzer' %}",
       ].join("\n");
 
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).toContain("You are Agent, analyzer.");
@@ -178,7 +180,7 @@ describe("flattenPartials", () => {
     it("preserves surrounding markdown content", () => {
       const template =
         "# System Prompt\n\n{% render 'identity', role: 'Bot', desc: 'helper' %}\n\n## Instructions\n\nDo the thing.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toMatch(/^# System Prompt/);
       expect(result).toContain("You are Bot, helper.");
@@ -188,13 +190,13 @@ describe("flattenPartials", () => {
     it("throws when partial file does not exist", () => {
       const template = "{% render 'nonexistent' %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow();
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow();
     });
 
     it("searches multiple partialsDirs in order", () => {
       const emptyDir = resolve(import.meta.dirname);
       const template = "{% render 'identity', role: 'Bot', desc: 'test' %}";
-      const result = flattenPartials(template, [emptyDir, PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [emptyDir, PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, test.");
     });
@@ -203,13 +205,13 @@ describe("flattenPartials", () => {
   describe("template preservation", () => {
     it("preserves {{ var }} and {% if %} expressions", () => {
       const template = "Hello {{ name }}.\n{% if context %}{{ context }}{% endif %}";
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("flattens render tag while preserving surrounding Liquid blocks", () => {
       const template =
         "{% if show_identity %}\n{% render 'identity', role: 'Bot', desc: 'helper' %}\n{% endif %}\n\n{{ instructions }}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("{% if show_identity %}");
       expect(result).toContain("{% endif %}");
@@ -219,12 +221,12 @@ describe("flattenPartials", () => {
     });
 
     it("returns empty string unchanged", () => {
-      expect(flattenPartials("", [PARTIALS_DIR])).toBe("");
+      expect(flattenPartials({ template: "", partialsDirs: [PARTIALS_DIR] })).toBe("");
     });
 
     it("returns whitespace-only template unchanged", () => {
       const ws = "   \n\n   ";
-      expect(flattenPartials(ws, [PARTIALS_DIR])).toBe(ws);
+      expect(flattenPartials({ template: ws, partialsDirs: [PARTIALS_DIR] })).toBe(ws);
     });
   });
 });

package/src/lib/prompts/__tests__/frontmatter.test.ts

@@ -2,23 +2,23 @@ import { describe, expect, it } from "vitest";
 
 import { parseFrontmatter } from "@/lib/prompts/frontmatter.js";
 
-describe("parseFrontmatter", () => {
+describe(parseFrontmatter, () => {
   it("parses name from frontmatter", () => {
     const content = "---\nname: my-prompt\n---\nHello";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.name).toBe("my-prompt");
   });
 
   it("parses group and version", () => {
     const content = "---\nname: test\ngroup: agents/test\nversion: 2\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.group).toBe("agents/test");
     expect(result.version).toBe("2");
   });
 
   it("parses schema with shorthand type strings", () => {
     const content = "---\nname: test\nschema:\n  scope: string\n  target: string\n---\n";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.schema).toEqual([
       { name: "scope", type: "string", required: true },
       { name: "target", type: "string", required: true },
@@ -39,7 +39,7 @@ describe("parseFrontmatter", () => {
       "---",
       "",
     ].join("\n");
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.schema).toEqual([
       { name: "scope", type: "string", required: true, description: "The scope" },
       { name: "target", type: "string", required: false },
@@ -48,42 +48,44 @@ describe("parseFrontmatter", () => {
 
   it("returns empty schema when no schema field", () => {
     const content = "---\nname: test\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.schema).toEqual([]);
   });
 
   it("throws on missing frontmatter", () => {
-    expect(() => parseFrontmatter("No frontmatter", "test.prompt")).toThrow("No frontmatter");
+    expect(() => parseFrontmatter({ content: "No frontmatter", filePath: "test.prompt" })).toThrow(
+      "No frontmatter",
+    );
   });
 
   it("throws on missing name", () => {
-    expect(() => parseFrontmatter("---\nversion: 1\n---\n", "test.prompt")).toThrow(
-      'Missing or empty "name"',
-    );
+    expect(() =>
+      parseFrontmatter({ content: "---\nversion: 1\n---\n", filePath: "test.prompt" }),
+    ).toThrow('Missing or empty "name"');
   });
 
   it("throws on invalid name format", () => {
-    expect(() => parseFrontmatter("---\nname: My Prompt\n---\n", "test.prompt")).toThrow(
-      "Invalid prompt name",
-    );
+    expect(() =>
+      parseFrontmatter({ content: "---\nname: My Prompt\n---\n", filePath: "test.prompt" }),
+    ).toThrow("Invalid prompt name");
   });
 
   it("returns undefined group when not specified", () => {
     const content = "---\nname: test\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.group).toBeUndefined();
   });
 
   it("should throw on invalid group segment", () => {
     const content = "---\nname: test\ngroup: agents/INVALID\n---\nBody";
-    expect(() => parseFrontmatter(content, "test.prompt")).toThrow(
+    expect(() => parseFrontmatter({ content, filePath: "test.prompt" })).toThrow(
       'Invalid group segment "INVALID"',
     );
   });
 
   it("should accept valid multi-segment group", () => {
     const content = "---\nname: test\ngroup: agents/specialized\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.group).toBe("agents/specialized");
   });
 });

package/src/lib/prompts/__tests__/lint.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import { hasLintErrors, lintPrompt } from "@/lib/prompts/lint.js";
 
-describe("lintPrompt", () => {
+describe(lintPrompt, () => {
   it("returns no diagnostics when vars match schema", () => {
     const result = lintPrompt(
       "test",
@@ -50,10 +50,10 @@ describe("lintPrompt", () => {
   });
 });
 
-describe("hasLintErrors", () => {
+describe(hasLintErrors, () => {
   it("returns false when no errors", () => {
     const results = [{ name: "test", filePath: "test.prompt", diagnostics: [] }];
-    expect(hasLintErrors(results)).toBe(false);
+    expect(hasLintErrors(results)).toBeFalsy();
   });
 
   it("returns true when errors exist", () => {
@@ -64,7 +64,7 @@ describe("hasLintErrors", () => {
         diagnostics: [{ level: "error" as const, message: "oops" }],
       },
     ];
-    expect(hasLintErrors(results)).toBe(true);
+    expect(hasLintErrors(results)).toBeTruthy();
   });
 
   it("returns false when only warnings", () => {
@@ -75,6 +75,6 @@ describe("hasLintErrors", () => {
         diagnostics: [{ level: "warn" as const, message: "hmm" }],
       },
     ];
-    expect(hasLintErrors(results)).toBe(false);
+    expect(hasLintErrors(results)).toBeFalsy();
   });
 });

package/src/lib/prompts/codegen.ts

@@ -13,6 +13,10 @@ export interface ParsedPrompt {
   readonly sourcePath: string;
 }
 
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
 /**
  * Convert a kebab-case name to PascalCase.
  *
@@ -24,7 +28,7 @@ export interface ParsedPrompt {
 function toPascalCase(name: string): string {
   return name
     .split("-")
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
     .join("");
 }
 
@@ -38,7 +42,7 @@ function toPascalCase(name: string): string {
  */
 function toCamelCase(name: string): string {
   const pascal = toPascalCase(name);
-  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  return `${pascal.charAt(0).toLowerCase()}${pascal.slice(1)}`;
 }
 
 /**
@@ -49,7 +53,26 @@ function toCamelCase(name: string): string {
  * @private
  */
 function escapeTemplateLiteral(str: string): string {
-  return str.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+  return str
+    .replaceAll("\\", String.raw`\\`)
+    .replaceAll("`", "\\`")
+    .replaceAll("${", "\\${");
+}
+
+/** @private */
+function formatGroupValue(group: string | undefined): string {
+  if (group) {
+    return `'${group}' as const`;
+  }
+  return "undefined";
+}
+
+/** @private */
+function parseGroupSegments(group: string | undefined): readonly string[] {
+  if (group) {
+    return group.split("/").map(toCamelCase);
+  }
+  return [];
 }
 
 /**
@@ -65,7 +88,9 @@ function generateSchemaExpression(vars: readonly SchemaVariable[]): string {
   const fields = vars
     .map((v) => {
       const base = "z.string()";
-      const expr = v.required ? base : `${base}.optional()`;
+      const expr = match(v.required)
+        .with(true, () => base)
+        .otherwise(() => `${base}.optional()`);
       return `  ${v.name}: ${expr},`;
     })
     .join("\n");
@@ -93,9 +118,9 @@ const HEADER = [
 export function generatePromptModule(prompt: ParsedPrompt): string {
   const escaped = escapeTemplateLiteral(prompt.template);
   const schemaExpr = generateSchemaExpression(prompt.schema);
-  const groupValue = prompt.group != null ? `'${prompt.group}' as const` : "undefined";
+  const groupValue = formatGroupValue(prompt.group);
 
-  const lines: string[] = [
+  const lines: readonly string[] = [
     HEADER,
     `// Source: ${prompt.sourcePath}`,
     "",
@@ -140,9 +165,9 @@ export function generatePromptModule(prompt: ParsedPrompt): string {
  * A tree node used during registry code generation.
  * Leaves hold the camelCase import name; branches hold nested nodes.
  */
-type TreeNode = {
+interface TreeNode {
   readonly [key: string]: string | TreeNode;
-};
+}
 
 /**
  * Build a nested tree from sorted prompts, grouped by their `group` field.
@@ -156,17 +181,16 @@ type TreeNode = {
 function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
   return prompts.reduce<Record<string, unknown>>((root, prompt) => {
     const importName = toCamelCase(prompt.name);
-    const segments = prompt.group ? prompt.group.split("/").map(toCamelCase) : [];
+    const segments = parseGroupSegments(prompt.group);
 
     const target = segments.reduce<Record<string, unknown>>((current, segment) => {
       const existing = current[segment];
       if (typeof existing === "string") {
-        throw new Error(
-          `Collision: prompt "${existing}" and group namespace "${segment}" ` +
-            "share the same key at the same level.",
+        throw new TypeError(
+          `Collision: prompt "${existing}" and group namespace "${segment}" share the same key at the same level.`,
         );
       }
-      if (existing == null) {
+      if (existing === null || existing === undefined) {
         current[segment] = {};
       }
       return current[segment] as Record<string, unknown>;
@@ -174,8 +198,7 @@ function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
 
     if (typeof target[importName] === "object" && target[importName] !== null) {
       throw new Error(
-        `Collision: prompt "${importName}" conflicts with existing group namespace ` +
-          `"${importName}" at the same level.`,
+        `Collision: prompt "${importName}" conflicts with existing group namespace "${importName}" at the same level.`,
       );
     }
 
@@ -193,13 +216,17 @@ function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
  *
  * @private
  */
-function serializeTree(node: TreeNode, indent: number): string[] {
+function serializeTree(node: TreeNode, indent: number): readonly string[] {
   const pad = "  ".repeat(indent);
 
   return Object.entries(node).flatMap(([key, value]) =>
-    typeof value === "string"
-      ? [`${pad}${key},`]
-      : [`${pad}${key}: {`, ...serializeTree(value, indent + 1), `${pad}},`],
+    match(typeof value)
+      .with("string", () => [`${pad}${key},`])
+      .otherwise(() => [
+        `${pad}${key}: {`,
+        ...serializeTree(value as TreeNode, indent + 1),
+        `${pad}},`,
+      ]),
   );
 }
 
@@ -220,7 +247,7 @@ export function generateRegistry(prompts: readonly ParsedPrompt[]): string {
   const tree = buildTree(sorted);
   const treeLines = serializeTree(tree, 1);
 
-  const lines: string[] = [
+  const lines: readonly string[] = [
     HEADER,
     "",
     "import { createPromptRegistry } from '@funkai/prompts'",

package/src/lib/prompts/extract-variables.ts

@@ -2,6 +2,17 @@ import { Liquid } from "liquidjs";
 
 const DANGEROUS_NAMES = new Set(["constructor", "__proto__", "prototype"]);
 
+/** Module-level engine — no config needed for variable extraction. */
+const engine = new Liquid();
+
+/** @private */
+function extractRoot(variable: unknown): string {
+  if (Array.isArray(variable)) {
+    return String(variable[0]);
+  }
+  return String(variable);
+}
+
 /**
  * Extract top-level variable names from a Liquid template string.
  *
@@ -9,16 +20,22 @@ const DANGEROUS_NAMES = new Set(["constructor", "__proto__", "prototype"]);
  * and extract all referenced variable names. Only returns the root
  * variable name (e.g. `user` from `{{ user.name }}`).
  *
+ * @param template - The Liquid template string to parse.
+ * @returns Sorted, deduplicated array of top-level variable names.
  * @throws {Error} If a variable name is dangerous (e.g. `__proto__`)
+ * @example
+ * ```ts
+ * extractVariables("Hello {{ user.name }}, you have {{ count }} items");
+ * // ["count", "user"]
+ * ```
  */
-export function extractVariables(template: string): string[] {
-  const engine = new Liquid();
+export function extractVariables(template: string): readonly string[] {
   const parsed = engine.parse(template);
   const variables = engine.variablesSync(parsed);
 
   const roots = new Set(
     variables.map((variable) => {
-      const root = Array.isArray(variable) ? String(variable[0]) : String(variable);
+      const root = extractRoot(variable);
 
       if (DANGEROUS_NAMES.has(root)) {
         throw new Error(`Dangerous variable name "${root}" is not allowed in prompt templates`);