@funkai/cli 0.1.3 → 0.2.0

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,18 +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 = m[2] != null ? m[2].trim() : "";
-    const params = rawParams.length > 0 ? parseParams(rawParams, m[1]) : {};
+    const rawParams: string = (m[2] ?? "").trim();
+    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.
  *
@@ -56,30 +108,29 @@ 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: string[]): string {
+export function flattenPartials({ template, partialsDirs }: FlattenPartialsParams): string {
   const tags = parseRenderTags(template);
   if (tags.length === 0) {
     return template;
   }
 
   const engine = new Liquid({
-    root: partialsDirs,
-    partials: partialsDirs,
+    root: [...partialsDirs],
+    partials: [...partialsDirs],
     extname: ".prompt",
   });
 
   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-]+$/;
 
 /**
@@ -16,8 +20,8 @@ export const NAME_RE = /^[a-z0-9-]+$/;
 function parseYamlContent(yaml: string, filePath: string): Record<string, unknown> {
   try {
     return parseYaml(yaml) as Record<string, unknown>;
-  } catch (err) {
-    throw new Error(`Failed to parse YAML frontmatter in ${filePath}: ${err}`, { cause: err });
+  } catch (error) {
+    throw new Error(`Failed to parse YAML frontmatter in ${filePath}: ${error}`, { cause: error });
   }
 }
 
@@ -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}`);
@@ -64,7 +82,7 @@ export function parseFrontmatter(content: string, filePath: string): ParsedFront
     throw new Error(`Frontmatter is not a valid object in ${filePath}`);
   }
 
-  const name = parsed.name;
+  const { name } = parsed;
   if (typeof name !== "string" || name.length === 0) {
     throw new Error(`Missing or empty "name" in frontmatter: ${filePath}`);
   }
@@ -76,63 +94,103 @@ export function parseFrontmatter(content: string, filePath: string): ParsedFront
     );
   }
 
-  const group =
-    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;
-        })()
-      : undefined;
-  const version = parsed.version != null ? String(parsed.version) : 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[] {
-  if (raw == null) {
+function parseSchemaBlock(raw: unknown, filePath: string): readonly SchemaVariable[] {
+  if (raw === null || raw === undefined) {
     return [];
   }
 
   if (typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error(
+    throw new TypeError(
       `Invalid "schema" in ${filePath}: expected an object mapping variable names to definitions`,
     );
   }
 
   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>;
-      const type = typeof def.type === "string" ? (def.type as string) : "string";
-      const required = def.required !== false;
-      const description =
-        typeof def.description === "string" ? (def.description as string) : 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] };
 }
 
 /**

package/src/lib/prompts/paths.ts

@@ -1,35 +1,45 @@
 import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 
+import { parse as parseYaml } from "yaml";
+
 import { FRONTMATTER_RE, NAME_RE } from "./frontmatter.js";
 
 const MAX_DEPTH = 5;
 const PROMPT_EXT = ".prompt";
 
+/** A `.prompt` file discovered during directory scanning. */
 export interface DiscoveredPrompt {
   readonly name: string;
   readonly filePath: string;
 }
 
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
 /**
  * Extract the `name` field from YAML frontmatter.
  *
- * This is a lightweight extraction that avoids pulling in a full YAML parser.
- * It looks for `name: <value>` in the frontmatter block.
+ * Uses a proper YAML parser to handle quoted values and edge cases.
+ *
+ * @private
  */
 function extractName(content: string): string | undefined {
-  const match = content.match(FRONTMATTER_RE);
-  if (!match) {
+  const fmMatch = content.match(FRONTMATTER_RE);
+  if (!fmMatch) {
     return undefined;
   }
 
-  const frontmatter = match[1];
-  const nameLine = frontmatter.split("\n").find((line) => line.startsWith("name:"));
-  if (!nameLine) {
+  try {
+    const parsed = parseYaml(fmMatch[1]) as Record<string, unknown> | null;
+    if (parsed !== null && parsed !== undefined && typeof parsed.name === "string") {
+      return parsed.name;
+    }
+    return undefined;
+  } catch {
     return undefined;
   }
-
-  return nameLine.slice("name:".length).trim();
 }
 
 /**
@@ -37,6 +47,8 @@ function extractName(content: string): string | undefined {
  *
  * If the file is named `prompt.prompt`, uses the parent directory name.
  * Otherwise uses the file stem (e.g. `my-agent.prompt` -> `my-agent`).
+ *
+ * @private
  */
 function deriveNameFromPath(filePath: string): string {
   const stem = basename(filePath, PROMPT_EXT);
@@ -48,6 +60,8 @@ function deriveNameFromPath(filePath: string): string {
 
 /**
  * Recursively scan a directory for `.prompt` files.
+ *
+ * @private
  */
 function scanDirectory(dir: string, depth: number): DiscoveredPrompt[] {
   if (depth > MAX_DEPTH) {
@@ -74,7 +88,7 @@ function scanDirectory(dir: string, depth: number): DiscoveredPrompt[] {
 
       if (entry.isFile() && extname(entry.name) === PROMPT_EXT) {
         // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading prompt file content for name extraction
-        const content = readFileSync(fullPath, "utf-8");
+        const content = readFileSync(fullPath, "utf8");
         const name = extractName(content) ?? deriveNameFromPath(fullPath);
 
         if (!NAME_RE.test(name)) {
@@ -102,7 +116,7 @@ function scanDirectory(dir: string, depth: number): DiscoveredPrompt[] {
  * @returns Sorted, deduplicated list of discovered prompts.
  * @throws If duplicate prompt names are found across roots.
  */
-export function discoverPrompts(roots: readonly string[]): DiscoveredPrompt[] {
+export function discoverPrompts(roots: readonly string[]): readonly DiscoveredPrompt[] {
   const all = roots.flatMap((root) => scanDirectory(resolve(root), 0));
 
   const byName = Map.groupBy(all, (prompt) => prompt.name);

package/src/lib/prompts/pipeline.ts

@@ -3,13 +3,29 @@ import { resolve } from "node:path";
 
 import { clean, PARTIALS_DIR } from "@funkai/prompts/cli";
 
-import { type ParsedPrompt } from "./codegen.js";
+import type { ParsedPrompt } from "./codegen.js";
 import { extractVariables } from "./extract-variables.js";
 import { flattenPartials } from "./flatten.js";
 import { parseFrontmatter } from "./frontmatter.js";
-import { lintPrompt, type LintResult } from "./lint.js";
+import { lintPrompt } from "./lint.js";
+import type { LintResult } from "./lint.js";
 import { discoverPrompts } from "./paths.js";
 
+/**
+ * Resolve the list of partial directories to search.
+ *
+ * @private
+ * @param customDir - Custom partials directory path.
+ * @returns Array of directories to search for partials.
+ */
+// oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: checking custom partials directory from CLI config
+function resolvePartialsDirs(customDir: string): readonly string[] {
+  if (existsSync(customDir)) {
+    return [customDir, PARTIALS_DIR];
+  }
+  return [PARTIALS_DIR];
+}
+
 /**
  * Options for the prompts lint pipeline.
  */
@@ -35,16 +51,13 @@ export interface LintPipelineResult {
 export function runLintPipeline(options: LintPipelineOptions): LintPipelineResult {
   const discovered = discoverPrompts([...options.roots]);
   const customPartialsDir = resolve(options.partials ?? ".prompts/partials");
-  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: checking custom partials directory from CLI config
-  const partialsDirs = existsSync(customPartialsDir)
-    ? [customPartialsDir, PARTIALS_DIR]
-    : [PARTIALS_DIR];
+  const partialsDirs = resolvePartialsDirs(customPartialsDir);
 
   const results = discovered.map((d) => {
     // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading discovered prompt file
-    const raw = readFileSync(d.filePath, "utf-8");
-    const frontmatter = parseFrontmatter(raw, d.filePath);
-    const template = flattenPartials(clean(raw), partialsDirs);
+    const raw = readFileSync(d.filePath, "utf8");
+    const frontmatter = parseFrontmatter({ content: raw, filePath: d.filePath });
+    const template = flattenPartials({ template: clean(raw), partialsDirs });
     const templateVars = extractVariables(template);
     return lintPrompt(frontmatter.name, d.filePath, frontmatter.schema, templateVars);
   });
@@ -81,16 +94,13 @@ export interface GeneratePipelineResult {
 export function runGeneratePipeline(options: GeneratePipelineOptions): GeneratePipelineResult {
   const discovered = discoverPrompts([...options.roots]);
   const customPartialsDir = resolve(options.partials ?? resolve(options.out, "../partials"));
-  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: checking custom partials directory from CLI config
-  const partialsDirs = existsSync(customPartialsDir)
-    ? [customPartialsDir, PARTIALS_DIR]
-    : [PARTIALS_DIR];
+  const partialsDirs = resolvePartialsDirs(customPartialsDir);
 
   const processed = discovered.map((d) => {
     // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading discovered prompt file
-    const raw = readFileSync(d.filePath, "utf-8");
-    const frontmatter = parseFrontmatter(raw, d.filePath);
-    const template = flattenPartials(clean(raw), partialsDirs);
+    const raw = readFileSync(d.filePath, "utf8");
+    const frontmatter = parseFrontmatter({ content: raw, filePath: d.filePath });
+    const template = flattenPartials({ template: clean(raw), partialsDirs });
     const templateVars = extractVariables(template);
 
     return {