@funkai/cli 0.1.4 → 0.3.0

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] };
 }
 
 /**

package/src/lib/prompts/paths.ts

@@ -1,35 +1,56 @@
 import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
-import { basename, extname, join, resolve } from "node:path";
+import { basename, extname, join, relative, resolve } from "node:path";
+
+import picomatch from "picomatch";
+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;
 }
 
+/**
+ * Options for prompt discovery.
+ */
+export interface DiscoverPromptsOptions {
+  /** Glob patterns to scan for `.prompt` files (defaults to `['./**']`). */
+  readonly includes: readonly string[];
+  /** Glob patterns to exclude from discovery. */
+  readonly excludes?: readonly 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;
-  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 +58,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);
@@ -46,8 +69,38 @@ function deriveNameFromPath(filePath: string): string {
   return stem;
 }
 
+/**
+ * Extract the static base directory from a glob pattern.
+ *
+ * Returns the longest directory prefix before any glob characters
+ * (`*`, `?`, `{`, `[`). Falls back to `'.'` if the pattern starts
+ * with a glob character.
+ *
+ * @private
+ */
+function extractBaseDir(pattern: string): string {
+  const globChars = new Set(["*", "?", "{", "["]);
+  const parts = pattern.split("/");
+  const staticParts: string[] = [];
+
+  for (const part of parts) {
+    if ([...part].some((ch) => globChars.has(ch))) {
+      break;
+    }
+    staticParts.push(part);
+  }
+
+  if (staticParts.length === 0) {
+    return ".";
+  }
+
+  return staticParts.join("/");
+}
+
 /**
  * Recursively scan a directory for `.prompt` files.
+ *
+ * @private
  */
 function scanDirectory(dir: string, depth: number): DiscoveredPrompt[] {
   if (depth > MAX_DEPTH) {
@@ -96,23 +149,36 @@ function scanDirectory(dir: string, depth: number): DiscoveredPrompt[] {
 }
 
 /**
- * Discover all `.prompt` files from the given root directories.
+ * Discover all `.prompt` files matching the given include/exclude patterns.
+ *
+ * Extracts base directories from the include patterns, scans them
+ * recursively, then filters results through picomatch.
+ *
+ * Name uniqueness is **not** enforced here — prompts with the same name
+ * are allowed as long as they belong to different groups. Uniqueness
+ * is validated downstream in the pipeline after frontmatter parsing,
+ * where group information is available.
  *
- * @param roots - Directories to scan recursively.
- * @returns Sorted, deduplicated list of discovered prompts.
- * @throws If duplicate prompt names are found across roots.
+ * @param options - Include and exclude glob patterns.
+ * @returns Sorted list of discovered prompts.
  */
-export function discoverPrompts(roots: readonly string[]): DiscoveredPrompt[] {
-  const all = roots.flatMap((root) => scanDirectory(resolve(root), 0));
+export function discoverPrompts(options: DiscoverPromptsOptions): readonly DiscoveredPrompt[] {
+  const { includes, excludes = [] } = options;
 
-  const byName = Map.groupBy(all, (prompt) => prompt.name);
+  const baseDirs = [...new Set(includes.map((pattern) => resolve(extractBaseDir(pattern))))];
+  const all = baseDirs.flatMap((dir) => scanDirectory(dir, 0));
 
-  const duplicate = [...byName.entries()].find(([, prompts]) => prompts.length > 1);
-  if (duplicate) {
-    const [name, prompts] = duplicate;
-    const paths = prompts.map((p) => p.filePath).join("\n  ");
-    throw new Error(`Duplicate prompt name "${name}" found in:\n  ${paths}`);
-  }
+  const isIncluded = picomatch(includes as string[]);
+  const isExcluded = picomatch(excludes as string[]);
+
+  const filtered = all.filter((prompt) => {
+    const matchPath = relative(process.cwd(), prompt.filePath).replaceAll("\\", "/");
+    return isIncluded(matchPath) && !isExcluded(matchPath);
+  });
+
+  const deduped = [
+    ...new Map(filtered.map((prompt) => [prompt.filePath, prompt] as const)).values(),
+  ];
 
-  return all.toSorted((a, b) => a.name.localeCompare(b.name));
+  return deduped.toSorted((a, b) => a.name.localeCompare(b.name));
 }