@funkai/cli 0.1.4 → 0.2.0

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

@@ -5,20 +5,20 @@ import { parseFrontmatter } from "@/lib/prompts/frontmatter.js";
 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/codegen.ts

@@ -13,6 +13,10 @@ export interface ParsedPrompt {
   readonly sourcePath: string;
 }
 
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
 /**
  * Convert a kebab-case name to PascalCase.
  *
@@ -55,6 +59,22 @@ function escapeTemplateLiteral(str: string): string {
     .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 [];
+}
+
 /**
  * Generate the Zod schema expression for a list of schema variables.
  *
@@ -68,13 +88,9 @@ function generateSchemaExpression(vars: readonly SchemaVariable[]): string {
   const fields = vars
     .map((v) => {
       const base = "z.string()";
-      // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-      const expr: string = (() => {
-        if (v.required) {
-          return base;
-        }
-        return `${base}.optional()`;
-      })();
+      const expr = match(v.required)
+        .with(true, () => base)
+        .otherwise(() => `${base}.optional()`);
       return `  ${v.name}: ${expr},`;
     })
     .join("\n");
@@ -102,15 +118,9 @@ const HEADER = [
 export function generatePromptModule(prompt: ParsedPrompt): string {
   const escaped = escapeTemplateLiteral(prompt.template);
   const schemaExpr = generateSchemaExpression(prompt.schema);
-  // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-  const groupValue: string = (() => {
-    if (prompt.group) {
-      return `'${prompt.group}' as const`;
-    }
-    return "undefined";
-  })();
+  const groupValue = formatGroupValue(prompt.group);
 
-  const lines: string[] = [
+  const lines: readonly string[] = [
     HEADER,
     `// Source: ${prompt.sourcePath}`,
     "",
@@ -171,13 +181,7 @@ interface TreeNode {
 function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
   return prompts.reduce<Record<string, unknown>>((root, prompt) => {
     const importName = toCamelCase(prompt.name);
-    // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-    const segments: string[] = (() => {
-      if (prompt.group) {
-        return prompt.group.split("/").map(toCamelCase);
-      }
-      return [];
-    })();
+    const segments = parseGroupSegments(prompt.group);
 
     const target = segments.reduce<Record<string, unknown>>((current, segment) => {
       const existing = current[segment];
@@ -212,22 +216,18 @@ 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);
 
-  const lines: string[] = [];
-  for (const [key, value] of Object.entries(node)) {
-    if (typeof value === "string") {
-      lines.push(`${pad}${key},`);
-    } else {
-      lines.push(`${pad}${key}: {`);
-      for (const child of serializeTree(value, indent + 1)) {
-        lines.push(child);
-      }
-      lines.push(`${pad}},`);
-    }
-  }
-  return lines;
+  return Object.entries(node).flatMap(([key, value]) =>
+    match(typeof value)
+      .with("string", () => [`${pad}${key},`])
+      .otherwise(() => [
+        `${pad}${key}: {`,
+        ...serializeTree(value as TreeNode, indent + 1),
+        `${pad}},`,
+      ]),
+  );
 }
 
 /**
@@ -247,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,22 +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) => {
-      // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-      const root: string = (() => {
-        if (Array.isArray(variable)) {
-          return String(variable[0]);
-        }
-        return String(variable);
-      })();
+      const root = extractRoot(variable);
 
       if (DANGEROUS_NAMES.has(root)) {
         throw new Error(`Dangerous variable name "${root}" is not allowed in prompt templates`);

package/src/lib/prompts/flatten.ts

@@ -10,11 +10,25 @@ interface RenderTag {
   params: Record<string, string>;
 }
 
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
+/** @private */
+function parseParamsOrEmpty(raw: string, partialName: string): Record<string, string> {
+  if (raw.length > 0) {
+    return parseParams(raw, partialName);
+  }
+  return {};
+}
+
 /**
  * Parse literal string parameters from a render tag's param string.
  *
  * Only supports literal string values (e.g. `role: 'Bot'`).
  * Throws if a parameter value is a variable reference.
+ *
+ * @private
  */
 function parseParams(raw: string, partialName: string): Record<string, string> {
   const literalMatches = [...raw.matchAll(LITERAL_PARAM_RE)];
@@ -34,23 +48,56 @@ function parseParams(raw: string, partialName: string): Record<string, string> {
   );
 }
 
+/** @private */
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Render a single partial tag via LiquidJS, wrapping errors with context.
+ *
+ * @private
+ */
+function renderPartial(engine: Liquid, tag: RenderTag): string {
+  const liquidTag = `{% render '${tag.partialName}' ${Object.entries(tag.params)
+    .map(([k, v]) => `${k}: '${v}'`)
+    .join(", ")} %}`;
+  try {
+    return engine.parseAndRenderSync(liquidTag);
+  } catch (error) {
+    throw new Error(`Failed to render partial '${tag.partialName}': ${errorMessage(error)}`, {
+      cause: error,
+    });
+  }
+}
+
 /**
  * Find all `{% render %}` tags in a template string.
+ *
+ * @private
  */
 function parseRenderTags(template: string): RenderTag[] {
   return [...template.matchAll(RENDER_TAG_RE)].map((m) => {
     const rawParams: string = (m[2] ?? "").trim();
-    const params: Record<string, string> = (() => {
-      if (rawParams.length > 0) {
-        return parseParams(rawParams, m[1]);
-      }
-      return {};
-    })();
+    const params = parseParamsOrEmpty(rawParams, m[1]);
 
     return { fullMatch: m[0], partialName: m[1], params };
   });
 }
 
+/**
+ * Parameters for flattening partial render tags.
+ */
+export interface FlattenPartialsParams {
+  /** Template string (frontmatter already stripped). */
+  readonly template: string;
+  /** Directories to search for partial `.prompt` files. */
+  readonly partialsDirs: readonly string[];
+}
+
 /**
  * Flatten `{% render %}` partial tags in a template at codegen time.
  *
@@ -61,11 +108,15 @@ function parseRenderTags(template: string): RenderTag[] {
  * All other Liquid expressions (`{{ var }}`, `{% if %}`, `{% for %}`)
  * are preserved for runtime rendering.
  *
- * @param template - Template string (frontmatter already stripped).
- * @param partialsDirs - Directories to search for partial `.prompt` files.
+ * @param params - Template content and partial directories.
  * @returns Flattened template with all render tags resolved.
+ * @example
+ * ```ts
+ * flattenPartials({ template: "{% render 'header' %}\nBody", partialsDirs: ["./partials"] });
+ * // "Welcome!\nBody"
+ * ```
  */
-export function flattenPartials(template: string, partialsDirs: readonly string[]): string {
+export function flattenPartials({ template, partialsDirs }: FlattenPartialsParams): string {
   const tags = parseRenderTags(template);
   if (tags.length === 0) {
     return template;
@@ -78,13 +129,8 @@ export function flattenPartials(template: string, partialsDirs: readonly string[
   });
 
   const result = tags.reduce((acc, tag) => {
-    const rendered = engine.parseAndRenderSync(
-      `{% render '${tag.partialName}' ${Object.entries(tag.params)
-        .map(([k, v]) => `${k}: '${v}'`)
-        .join(", ")} %}`,
-    );
-
-    return acc.replace(tag.fullMatch, rendered);
+    const rendered = renderPartial(engine, tag);
+    return acc.replace(tag.fullMatch, () => rendered);
   }, template);
 
   return result;

package/src/lib/prompts/frontmatter.ts

@@ -1,6 +1,10 @@
+import { match, P } from "ts-pattern";
 import { parse as parseYaml } from "yaml";
 
+/** Regex matching YAML frontmatter fenced by `---` delimiters. */
 export const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/** Regex validating prompt names (lowercase alphanumeric with hyphens). */
 export const NAME_RE = /^[a-z0-9-]+$/;
 
 /**
@@ -41,18 +45,32 @@ export interface ParsedFrontmatter {
   readonly schema: readonly SchemaVariable[];
 }
 
+/**
+ * Parameters for parsing frontmatter from a `.prompt` file.
+ */
+export interface ParseFrontmatterParams {
+  /** Raw file content (including frontmatter fences). */
+  readonly content: string;
+  /** File path for error messages. */
+  readonly filePath: string;
+}
+
 /**
  * Parse YAML frontmatter from a `.prompt` file's raw content.
  *
  * Extracts `name`, `group`, `version`, and `schema` fields.
  * The `schema` field maps variable names to their type definitions.
  *
- * @param content - Raw file content (including frontmatter fences).
- * @param filePath - File path for error messages.
+ * @param params - Content and file path to parse.
  * @returns Parsed frontmatter with schema variables.
  * @throws If frontmatter is missing, malformed, or has an invalid name.
+ * @example
+ * ```ts
+ * const fm = parseFrontmatter({ content: "---\nname: greeting\n---\nHello!", filePath: "greeting.prompt" });
+ * // { name: "greeting", group: undefined, version: undefined, schema: [] }
+ * ```
  */
-export function parseFrontmatter(content: string, filePath: string): ParsedFrontmatter {
+export function parseFrontmatter({ content, filePath }: ParseFrontmatterParams): ParsedFrontmatter {
   const fmMatch = content.match(FRONTMATTER_RE);
   if (!fmMatch) {
     throw new Error(`No frontmatter found in ${filePath}`);
@@ -76,37 +94,70 @@ export function parseFrontmatter(content: string, filePath: string): ParsedFront
     );
   }
 
-  const group: string | undefined = (() => {
-    if (typeof parsed.group === "string") {
-      const g = parsed.group as string;
-      const invalidSegment = g.split("/").find((segment) => !NAME_RE.test(segment));
-      if (invalidSegment !== undefined) {
-        throw new Error(
-          `Invalid group segment "${invalidSegment}" in ${filePath}. Group segments must be lowercase alphanumeric with hyphens only.`,
-        );
-      }
-      return g;
-    }
-    return undefined;
-  })();
-  const version: string | undefined = (() => {
-    if (parsed.version !== null && parsed.version !== undefined) {
-      return String(parsed.version);
-    }
-    return undefined;
-  })();
+  const group = parseGroup(parsed.group, filePath);
+  const version = parseVersion(parsed.version);
 
   const schema = parseSchemaBlock(parsed.schema, filePath);
 
   return { name, group, version, schema };
 }
 
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
+/** @private */
+function stringOrDefault(value: unknown, fallback: string): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  return fallback;
+}
+
+/** @private */
+function stringOrUndefined(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    return value;
+  }
+  return undefined;
+}
+
+/**
+ * Validate and extract the `group` field from parsed frontmatter.
+ *
+ * @private
+ */
+function parseGroup(raw: unknown, filePath: string): string | undefined {
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const invalidSegment = raw.split("/").find((segment) => !NAME_RE.test(segment));
+  if (invalidSegment !== undefined) {
+    throw new Error(
+      `Invalid group segment "${invalidSegment}" in ${filePath}. Group segments must be lowercase alphanumeric with hyphens only.`,
+    );
+  }
+  return raw;
+}
+
+/**
+ * Extract the `version` field from parsed frontmatter.
+ *
+ * @private
+ */
+function parseVersion(raw: unknown): string | undefined {
+  if (raw !== null && raw !== undefined) {
+    return String(raw);
+  }
+  return undefined;
+}
+
 /**
  * Parse the `schema` block from frontmatter into an array of variable definitions.
  *
  * @private
  */
-function parseSchemaBlock(raw: unknown, filePath: string): SchemaVariable[] {
+function parseSchemaBlock(raw: unknown, filePath: string): readonly SchemaVariable[] {
   if (raw === null || raw === undefined) {
     return [];
   }
@@ -119,34 +170,27 @@ function parseSchemaBlock(raw: unknown, filePath: string): SchemaVariable[] {
 
   const schema = raw as Record<string, unknown>;
 
-  return Object.entries(schema).map(([varName, value]): SchemaVariable => {
-    if (typeof value === "string") {
-      return { name: varName, type: value, required: true };
-    }
-
-    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-      const def = value as Record<string, unknown>;
-      // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-      const type: string = (() => {
-        if (typeof def.type === "string") {
-          return def.type as string;
-        }
-        return "string";
-      })();
-      const required = def.required !== false;
-      const description: string | undefined = (() => {
-        if (typeof def.description === "string") {
-          return def.description as string;
-        }
-        return undefined;
-      })();
-
-      return { name: varName, type, required, description };
-    }
-
-    throw new Error(
-      `Invalid schema definition for "${varName}" in ${filePath}. ` +
-        "Expected a type string or an object with { type, required?, description? }.",
-    );
-  });
+  return Object.entries(schema).map(
+    ([varName, value]): SchemaVariable =>
+      match(value)
+        .with(P.string, (v) => ({ name: varName, type: v, required: true }))
+        .with(
+          P.when(
+            (v): v is Record<string, unknown> =>
+              typeof v === "object" && v !== null && !Array.isArray(v),
+          ),
+          (def) => {
+            const type = stringOrDefault(def.type, "string");
+            const required = def.required !== false;
+            const description = stringOrUndefined(def.description);
+            return { name: varName, type, required, description };
+          },
+        )
+        .otherwise(() => {
+          throw new Error(
+            `Invalid schema definition for "${varName}" in ${filePath}. ` +
+              "Expected a type string or an object with { type, required?, description? }.",
+          );
+        }),
+  );
 }

package/src/lib/prompts/lint.ts

@@ -36,34 +36,29 @@ export function lintPrompt(
   schemaVars: readonly SchemaVariable[],
   templateVars: readonly string[],
 ): LintResult {
-  const diagnostics: LintDiagnostic[] = [];
   const declared = new Set(schemaVars.map((v) => v.name));
   const used = new Set(templateVars);
 
-  for (const varName of used) {
-    if (!declared.has(varName)) {
-      diagnostics.push({
-        level: "error",
-        message:
-          `Undefined variable "${varName}" in ${name}.prompt\n` +
-          `  Variable "${varName}" is used in the template but not declared in frontmatter schema.\n` +
-          "  Add it to the schema section in the frontmatter.",
-      });
-    }
-  }
+  const undeclaredErrors: readonly LintDiagnostic[] = [...used]
+    .filter((varName) => !declared.has(varName))
+    .map((varName) => ({
+      level: "error" as const,
+      message:
+        `Undefined variable "${varName}" in ${name}.prompt\n` +
+        `  Variable "${varName}" is used in the template but not declared in frontmatter schema.\n` +
+        "  Add it to the schema section in the frontmatter.",
+    }));
 
-  for (const varName of declared) {
-    if (!used.has(varName)) {
-      diagnostics.push({
-        level: "warn",
-        message:
-          `Unused variable "${varName}" in ${name}.prompt\n` +
-          `  Variable "${varName}" is declared in the schema but never used in the template.`,
-      });
-    }
-  }
+  const unusedWarnings: readonly LintDiagnostic[] = [...declared]
+    .filter((varName) => !used.has(varName))
+    .map((varName) => ({
+      level: "warn" as const,
+      message:
+        `Unused variable "${varName}" in ${name}.prompt\n` +
+        `  Variable "${varName}" is declared in the schema but never used in the template.`,
+    }));
 
-  return { name, filePath, diagnostics };
+  return { name, filePath, diagnostics: [...undeclaredErrors, ...unusedWarnings] };
 }
 
 /**