@funkai/cli 0.1.0

package/src/lib/prompts/flatten.ts

@@ -0,0 +1,91 @@
+import { Liquid } from "liquidjs";
+import { match } from "ts-pattern";
+
+// oxlint-disable-next-line security/detect-unsafe-regex -- template parsing, not adversarial input
+const RENDER_TAG_RE = /\{%-?\s*render\s+'([^']+)'(?:\s*,\s*(.*?))?\s*-?%\}/g;
+const LITERAL_PARAM_RE = /(\w+)\s*:\s*'([^']*)'/g;
+
+interface RenderTag {
+  fullMatch: string;
+  partialName: string;
+  params: Record<string, string>;
+}
+
+/**
+ * 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.
+ */
+function parseParams(raw: string, partialName: string): Record<string, string> {
+  const literalMatches = [...raw.matchAll(LITERAL_PARAM_RE)];
+  const allParamNames = [...raw.matchAll(/(\w+)\s*:/g)].map((m) => m[1]);
+
+  return Object.fromEntries(
+    allParamNames.map((name) => {
+      const literal = literalMatches.find((m) => m[1] === name);
+      if (!literal) {
+        throw new Error(
+          `Cannot flatten {% render '${partialName}' %}: parameter "${name}" uses a variable reference. ` +
+            "Only literal string values are supported at codegen time.",
+        );
+      }
+      return [name, literal[2]];
+    }),
+  );
+}
+
+/**
+ * Find all `{% render %}` tags in a template string.
+ */
+function parseRenderTags(template: string): RenderTag[] {
+  return [...template.matchAll(RENDER_TAG_RE)].map((m) => {
+    const rawParams = match(m[2] != null)
+      .with(true, () => m[2].trim())
+      .otherwise(() => "");
+    const params = match(rawParams.length > 0)
+      .with(true, () => parseParams(rawParams, m[1]))
+      .otherwise(() => ({}));
+
+    return { fullMatch: m[0], partialName: m[1], params };
+  });
+}
+
+/**
+ * Flatten `{% render %}` partial tags in a template at codegen time.
+ *
+ * Finds all `{% render 'name', key: 'value' %}` tags, reads the
+ * corresponding partial file, renders it with the literal parameters,
+ * and replaces the tag with the rendered output.
+ *
+ * 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.
+ * @returns Flattened template with all render tags resolved.
+ */
+export function flattenPartials(template: string, partialsDirs: string[]): string {
+  const tags = parseRenderTags(template);
+  if (tags.length === 0) {
+    return template;
+  }
+
+  const engine = new Liquid({
+    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);
+  }, template);
+
+  return result;
+}

package/src/lib/prompts/frontmatter.ts

@@ -0,0 +1,143 @@
+import { match } from "ts-pattern";
+import { parse as parseYaml } from "yaml";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const NAME_RE = /^[a-z0-9-]+$/;
+
+/**
+ * Parse raw YAML content into a record, wrapping parse errors
+ * with file path context.
+ *
+ * @param yaml - Raw YAML string to parse.
+ * @param filePath - File path for error messages.
+ * @returns The parsed YAML as a record.
+ *
+ * @private
+ */
+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 });
+  }
+}
+
+/**
+ * A variable declared in the frontmatter `schema` block.
+ */
+export interface SchemaVariable {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+}
+
+/**
+ * Parsed frontmatter from a `.prompt` file.
+ */
+export interface ParsedFrontmatter {
+  name: string;
+  group?: string;
+  version?: string;
+  schema: SchemaVariable[];
+}
+
+/**
+ * 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.
+ * @returns Parsed frontmatter with schema variables.
+ * @throws If frontmatter is missing, malformed, or has an invalid name.
+ */
+export function parseFrontmatter(content: string, filePath: string): ParsedFrontmatter {
+  const fmMatch = content.match(FRONTMATTER_RE);
+  if (!fmMatch) {
+    throw new Error(`No frontmatter found in ${filePath}`);
+  }
+
+  const parsed = parseYamlContent(fmMatch[1], filePath);
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`Frontmatter is not a valid object in ${filePath}`);
+  }
+
+  const name = parsed.name;
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error(`Missing or empty "name" in frontmatter: ${filePath}`);
+  }
+
+  if (!NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid prompt name "${name}" in ${filePath}. ` +
+        "Names must be lowercase alphanumeric with hyphens only.",
+    );
+  }
+
+  const group = match(typeof parsed.group === "string")
+    .with(true, () => {
+      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;
+    })
+    .otherwise(() => undefined);
+  const version = match(parsed.version != null)
+    .with(true, () => String(parsed.version))
+    .otherwise(() => undefined);
+
+  const schema = parseSchemaBlock(parsed.schema, filePath);
+
+  return { name, group, version, schema };
+}
+
+/**
+ * Parse the `schema` block from frontmatter into an array of variable definitions.
+ *
+ * @private
+ */
+function parseSchemaBlock(raw: unknown, filePath: string): SchemaVariable[] {
+  if (raw == null) {
+    return [];
+  }
+
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      `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 = match(typeof def.type === "string")
+        .with(true, () => def.type as string)
+        .otherwise(() => "string");
+      const required = def.required !== false;
+      const description = match(typeof def.description === "string")
+        .with(true, () => def.description as string)
+        .otherwise(() => 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? }.",
+    );
+  });
+}

package/src/lib/prompts/lint.ts

@@ -0,0 +1,74 @@
+import type { SchemaVariable } from "./frontmatter.js";
+
+/**
+ * A single lint diagnostic.
+ */
+export interface LintDiagnostic {
+  level: "error" | "warn";
+  message: string;
+}
+
+/**
+ * Result of linting a single prompt file.
+ */
+export interface LintResult {
+  name: string;
+  filePath: string;
+  diagnostics: LintDiagnostic[];
+}
+
+/**
+ * Lint a prompt by comparing declared schema variables against
+ * variables actually used in the template body.
+ *
+ * - **Error**: template uses a variable NOT declared in the schema (undefined var).
+ * - **Warn**: schema declares a variable NOT used in the template (unused var).
+ *
+ * @param name - Prompt name (for error messages).
+ * @param filePath - Source file path (for error messages).
+ * @param schemaVars - Variables declared in frontmatter schema.
+ * @param templateVars - Variables extracted from the template body.
+ * @returns Lint result with diagnostics.
+ */
+export function lintPrompt(
+  name: string,
+  filePath: string,
+  schemaVars: SchemaVariable[],
+  templateVars: 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.",
+      });
+    }
+  }
+
+  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.`,
+      });
+    }
+  }
+
+  return { name, filePath, diagnostics };
+}
+
+/**
+ * Check whether any lint results contain errors.
+ */
+export function hasLintErrors(results: LintResult[]): boolean {
+  return results.some((r) => r.diagnostics.some((d) => d.level === "error"));
+}

package/src/lib/prompts/paths.ts

@@ -0,0 +1,118 @@
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+
+const MAX_DEPTH = 5;
+const PROMPT_EXT = ".prompt";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const NAME_RE = /^[a-z0-9-]+$/;
+
+export interface DiscoveredPrompt {
+  name: string;
+  filePath: string;
+}
+
+/**
+ * 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.
+ */
+function extractName(content: string): string | undefined {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) {
+    return undefined;
+  }
+
+  const frontmatter = match[1];
+  const nameLine = frontmatter.split("\n").find((line) => line.startsWith("name:"));
+  if (!nameLine) {
+    return undefined;
+  }
+
+  return nameLine.slice("name:".length).trim();
+}
+
+/**
+ * Derive a prompt name from a file path when no frontmatter name is present.
+ *
+ * If the file is named `prompt.prompt`, uses the parent directory name.
+ * Otherwise uses the file stem (e.g. `my-agent.prompt` -> `my-agent`).
+ */
+function deriveNameFromPath(filePath: string): string {
+  const stem = basename(filePath, PROMPT_EXT);
+  if (stem === "prompt") {
+    return basename(resolve(filePath, ".."));
+  }
+  return stem;
+}
+
+/**
+ * Recursively scan a directory for `.prompt` files.
+ */
+function scanDirectory(dir: string, depth: number): DiscoveredPrompt[] {
+  if (depth > MAX_DEPTH) {
+    return [];
+  }
+  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: directory traversal for prompt discovery
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: stat check on traversed directory
+  const stat = lstatSync(dir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    return [];
+  }
+
+  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading entries from traversed directory
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  return entries
+    .filter((entry) => !entry.isSymbolicLink())
+    .flatMap((entry): DiscoveredPrompt[] => {
+      const fullPath = join(dir, entry.name);
+
+      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 name = extractName(content) ?? deriveNameFromPath(fullPath);
+
+        if (!NAME_RE.test(name)) {
+          throw new Error(
+            `Invalid prompt name "${name}" from ${fullPath}. ` +
+              "Names must be lowercase alphanumeric with hyphens only.",
+          );
+        }
+
+        return [{ name, filePath: fullPath }];
+      }
+
+      if (entry.isDirectory()) {
+        return scanDirectory(fullPath, depth + 1);
+      }
+
+      return [];
+    });
+}
+
+/**
+ * Discover all `.prompt` files from the given root directories.
+ *
+ * @param roots - Directories to scan recursively.
+ * @returns Sorted, deduplicated list of discovered prompts.
+ * @throws If duplicate prompt names are found across roots.
+ */
+export function discoverPrompts(roots: string[]): DiscoveredPrompt[] {
+  const all = roots.flatMap((root) => scanDirectory(resolve(root), 0));
+
+  const byName = Map.groupBy(all, (prompt) => prompt.name);
+
+  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}`);
+  }
+
+  return all.toSorted((a, b) => a.name.localeCompare(b.name));
+}

package/src/lib/prompts/pipeline.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { clean, PARTIALS_DIR } from "@funkai/prompts";
+import { match } from "ts-pattern";
+
+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 { discoverPrompts } from "./paths.js";
+
+/**
+ * Options for the prompts lint pipeline.
+ */
+export interface LintPipelineOptions {
+  readonly roots: readonly string[];
+  readonly partials?: string;
+}
+
+/**
+ * Result of running the prompts lint pipeline.
+ */
+export interface LintPipelineResult {
+  readonly discovered: number;
+  readonly results: readonly LintResult[];
+}
+
+/**
+ * Run the prompts lint pipeline: discover, parse, and validate .prompt files.
+ *
+ * @param options - Pipeline configuration.
+ * @returns Lint results for all discovered prompts.
+ */
+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 = match(existsSync(customPartialsDir))
+    .with(true, () => [customPartialsDir, PARTIALS_DIR])
+    .otherwise(() => [PARTIALS_DIR]);
+
+  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 templateVars = extractVariables(template);
+    return lintPrompt(frontmatter.name, d.filePath, frontmatter.schema, templateVars);
+  });
+
+  return { discovered: discovered.length, results };
+}
+
+/**
+ * Options for the prompts generate pipeline.
+ */
+export interface GeneratePipelineOptions {
+  readonly roots: readonly string[];
+  readonly out: string;
+  readonly partials?: string;
+}
+
+/**
+ * Result of running the prompts generate pipeline.
+ */
+export interface GeneratePipelineResult {
+  readonly discovered: number;
+  readonly lintResults: readonly LintResult[];
+  readonly prompts: readonly ParsedPrompt[];
+}
+
+/**
+ * Run the prompts generate pipeline: discover, parse, lint, and prepare prompts for codegen.
+ *
+ * Does NOT write files — returns the prepared data for the caller to write.
+ *
+ * @param options - Pipeline configuration.
+ * @returns Parsed prompts ready for code generation, along with lint results.
+ */
+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 = match(existsSync(customPartialsDir))
+    .with(true, () => [customPartialsDir, PARTIALS_DIR])
+    .otherwise(() => [PARTIALS_DIR]);
+
+  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 templateVars = extractVariables(template);
+
+    return {
+      lintResult: lintPrompt(frontmatter.name, d.filePath, frontmatter.schema, templateVars),
+      prompt: {
+        name: frontmatter.name,
+        group: frontmatter.group,
+        schema: frontmatter.schema,
+        template,
+        sourcePath: d.filePath,
+      } satisfies ParsedPrompt,
+    };
+  });
+
+  return {
+    discovered: discovered.length,
+    lintResults: processed.map((p) => p.lintResult),
+    prompts: processed.map((p) => p.prompt),
+  };
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2024"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,21 @@
+import { resolve } from "node:path";
+
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.{ts,tsx}"],
+    passWithNoTests: true,
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts", "src/**/*.test-d.ts", "src/**/index.ts"],
+      reporter: ["text", "lcov"],
+    },
+  },
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "./src"),
+    },
+  },
+});