@funkai/cli 0.1.0

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

@@ -0,0 +1,230 @@
+import { resolve } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { flattenPartials } from "@/lib/prompts/flatten.js";
+
+const PARTIALS_DIR = resolve(import.meta.dirname, "../../../../../prompts/src/prompts");
+
+describe("flattenPartials", () => {
+  describe("param parsing", () => {
+    it("resolves a single literal param", () => {
+      const template = "{% render 'identity', role: 'Bot' %}";
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("<identity>");
+      expect(result).toContain("You are Bot, .");
+      expect(result).not.toContain("{% render");
+    });
+
+    it("resolves multiple literal params", () => {
+      const template = "{% render 'identity', role: 'TestBot', desc: 'a test agent' %}";
+      const result = flattenPartials(template, [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]);
+
+      expect(result).toContain("You are , helper.");
+      expect(result).not.toContain("{% render");
+    });
+
+    it("throws when the first param uses a variable reference", () => {
+      const template = "{% render 'identity', role: agentRole, desc: 'helper' %}";
+
+      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow(
+        'parameter "role" uses a variable reference',
+      );
+    });
+
+    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(
+        'parameter "desc" uses a variable reference',
+      );
+    });
+
+    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");
+    });
+
+    it("handles extra whitespace around colons in params", () => {
+      const template = "{% render 'identity', role  :  'Bot', desc  :  'helper' %}";
+      const result = flattenPartials(template, [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]);
+
+      expect(result).toContain("You are Test Bot, a helpful assistant.");
+    });
+  });
+
+  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);
+    });
+
+    it("parses a render tag with no params", () => {
+      const template = "{% render 'identity' %}\n\nDone.";
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("<identity>");
+      expect(result).toContain("</identity>");
+      expect(result).not.toContain("{% render");
+    });
+
+    it("parses left-only whitespace trim {%-", () => {
+      const template = "{%- render 'identity', role: 'Bot', desc: 'helper' %}\nDone.";
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("You are Bot, helper.");
+      expect(result).not.toContain("{%-");
+    });
+
+    it("parses right-only whitespace trim -%}", () => {
+      const template = "{% render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("You are Bot, helper.");
+      expect(result).not.toContain("-%}");
+    });
+
+    it("parses both-side whitespace trim {%- -%}", () => {
+      const template = "{%- render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("You are Bot, helper.");
+      expect(result).not.toContain("{%");
+    });
+
+    it("handles extra whitespace between {% and render keyword", () => {
+      const template = "{%    render 'identity', role: 'Bot', desc: 'helper' %}";
+      const result = flattenPartials(template, [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);
+    });
+
+    it("does not match malformed render tags without closing %}", () => {
+      const template = "{% render 'identity'";
+      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+    });
+  });
+
+  describe("integration with real partials", () => {
+    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]);
+
+      expect(result).toContain("<identity>");
+      expect(result).toContain("You are TestBot, a test agent.");
+      expect(result).toContain("</identity>");
+      expect(result).toContain("Follow instructions.");
+      expect(result).not.toContain("{% render");
+    });
+
+    it("flattens constraints partial with no bindings", () => {
+      const template = "{% render 'constraints' %}";
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("<constraints>");
+      expect(result).toContain("</constraints>");
+      expect(result).not.toContain("## In Scope");
+      expect(result).not.toContain("## Out of Scope");
+      expect(result).not.toContain("## Rules");
+      expect(result).not.toContain("{% render");
+    });
+
+    it("flattens tools partial with no bindings (else branch)", () => {
+      const template = "{% render 'tools' %}";
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("<tools>");
+      expect(result).toContain("</tools>");
+      expect(result).toContain("No tools are configured for this agent.");
+      expect(result).not.toContain("{% render");
+    });
+
+    it("flattens multiple render tags in one template", () => {
+      const template = [
+        "{% render 'identity', role: 'Bot', desc: 'helper' %}",
+        "",
+        "{% render 'identity', role: 'Agent', desc: 'analyzer' %}",
+      ].join("\n");
+
+      const result = flattenPartials(template, [PARTIALS_DIR]);
+
+      expect(result).toContain("You are Bot, helper.");
+      expect(result).toContain("You are Agent, analyzer.");
+      expect(result).not.toContain("{% render");
+    });
+
+    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]);
+
+      expect(result).toMatch(/^# System Prompt/);
+      expect(result).toContain("You are Bot, helper.");
+      expect(result).toContain("## Instructions\n\nDo the thing.");
+    });
+
+    it("throws when partial file does not exist", () => {
+      const template = "{% render 'nonexistent' %}";
+
+      expect(() => flattenPartials(template, [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]);
+
+      expect(result).toContain("You are Bot, test.");
+    });
+  });
+
+  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);
+    });
+
+    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]);
+
+      expect(result).toContain("{% if show_identity %}");
+      expect(result).toContain("{% endif %}");
+      expect(result).toContain("{{ instructions }}");
+      expect(result).toContain("You are Bot, helper.");
+      expect(result).not.toContain("{% render");
+    });
+
+    it("returns empty string unchanged", () => {
+      expect(flattenPartials("", [PARTIALS_DIR])).toBe("");
+    });
+
+    it("returns whitespace-only template unchanged", () => {
+      const ws = "   \n\n   ";
+      expect(flattenPartials(ws, [PARTIALS_DIR])).toBe(ws);
+    });
+  });
+});

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

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+
+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");
+    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");
+    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");
+    expect(result.schema).toEqual([
+      { name: "scope", type: "string", required: true },
+      { name: "target", type: "string", required: true },
+    ]);
+  });
+
+  it("parses schema with full object definitions", () => {
+    const content = [
+      "---",
+      "name: test",
+      "schema:",
+      "  scope:",
+      "    type: string",
+      "    description: The scope",
+      "  target:",
+      "    type: string",
+      "    required: false",
+      "---",
+      "",
+    ].join("\n");
+    const result = parseFrontmatter(content, "test.prompt");
+    expect(result.schema).toEqual([
+      { name: "scope", type: "string", required: true, description: "The scope" },
+      { name: "target", type: "string", required: false },
+    ]);
+  });
+
+  it("returns empty schema when no schema field", () => {
+    const content = "---\nname: test\n---\nBody";
+    const result = parseFrontmatter(content, "test.prompt");
+    expect(result.schema).toEqual([]);
+  });
+
+  it("throws on missing frontmatter", () => {
+    expect(() => parseFrontmatter("No frontmatter", "test.prompt")).toThrow("No frontmatter");
+  });
+
+  it("throws on missing name", () => {
+    expect(() => parseFrontmatter("---\nversion: 1\n---\n", "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",
+    );
+  });
+
+  it("returns undefined group when not specified", () => {
+    const content = "---\nname: test\n---\nBody";
+    const result = parseFrontmatter(content, "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(
+      '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");
+    expect(result.group).toBe("agents/specialized");
+  });
+});

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

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import { hasLintErrors, lintPrompt } from "@/lib/prompts/lint.js";
+
+describe("lintPrompt", () => {
+  it("returns no diagnostics when vars match schema", () => {
+    const result = lintPrompt(
+      "test",
+      "test.prompt",
+      [{ name: "scope", type: "string", required: true }],
+      ["scope"],
+    );
+    expect(result.diagnostics).toEqual([]);
+  });
+
+  it("errors on undefined template variable", () => {
+    const result = lintPrompt("test", "test.prompt", [], ["scope"]);
+    expect(result.diagnostics).toHaveLength(1);
+    expect(result.diagnostics[0].level).toBe("error");
+    expect(result.diagnostics[0].message).toContain('Undefined variable "scope"');
+  });
+
+  it("warns on unused schema variable", () => {
+    const result = lintPrompt(
+      "test",
+      "test.prompt",
+      [{ name: "scope", type: "string", required: true }],
+      [],
+    );
+    expect(result.diagnostics).toHaveLength(1);
+    expect(result.diagnostics[0].level).toBe("warn");
+    expect(result.diagnostics[0].message).toContain('Unused variable "scope"');
+  });
+
+  it("reports both errors and warnings", () => {
+    const result = lintPrompt(
+      "test",
+      "test.prompt",
+      [{ name: "declared", type: "string", required: true }],
+      ["undeclared"],
+    );
+    expect(result.diagnostics).toHaveLength(2);
+    const levels = result.diagnostics.map((d) => d.level).toSorted();
+    expect(levels).toEqual(["error", "warn"]);
+  });
+
+  it("returns no diagnostics for prompts with no schema and no vars", () => {
+    const result = lintPrompt("test", "test.prompt", [], []);
+    expect(result.diagnostics).toEqual([]);
+  });
+});
+
+describe("hasLintErrors", () => {
+  it("returns false when no errors", () => {
+    const results = [{ name: "test", filePath: "test.prompt", diagnostics: [] }];
+    expect(hasLintErrors(results)).toBe(false);
+  });
+
+  it("returns true when errors exist", () => {
+    const results = [
+      {
+        name: "test",
+        filePath: "test.prompt",
+        diagnostics: [{ level: "error" as const, message: "oops" }],
+      },
+    ];
+    expect(hasLintErrors(results)).toBe(true);
+  });
+
+  it("returns false when only warnings", () => {
+    const results = [
+      {
+        name: "test",
+        filePath: "test.prompt",
+        diagnostics: [{ level: "warn" as const, message: "hmm" }],
+      },
+    ];
+    expect(hasLintErrors(results)).toBe(false);
+  });
+});

package/src/lib/prompts/codegen.ts

@@ -0,0 +1,240 @@
+import { match } from "ts-pattern";
+
+import type { SchemaVariable } from "./frontmatter.js";
+
+/**
+ * Fully parsed prompt ready for code generation.
+ */
+export interface ParsedPrompt {
+  name: string;
+  group?: string;
+  schema: SchemaVariable[];
+  template: string;
+  sourcePath: string;
+}
+
+/**
+ * Convert a kebab-case name to PascalCase.
+ *
+ * @param name - Kebab-case string to convert.
+ * @returns PascalCase version of the name.
+ *
+ * @private
+ */
+function toPascalCase(name: string): string {
+  return name
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/**
+ * Convert a kebab-case name to camelCase.
+ *
+ * @param name - Kebab-case string to convert.
+ * @returns camelCase version of the name.
+ *
+ * @private
+ */
+function toCamelCase(name: string): string {
+  const pascal = toPascalCase(name);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+/**
+ * Escape a template string for embedding inside a JS template literal.
+ *
+ * Backticks, `${`, and backslashes must be escaped.
+ *
+ * @private
+ */
+function escapeTemplateLiteral(str: string): string {
+  return str.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+
+/**
+ * Generate the Zod schema expression for a list of schema variables.
+ *
+ * @private
+ */
+function generateSchemaExpression(vars: SchemaVariable[]): string {
+  if (vars.length === 0) {
+    return "z.object({})";
+  }
+
+  const fields = vars
+    .map((v) => {
+      const base = "z.string()";
+      const expr = match(v.required)
+        .with(true, () => base)
+        .otherwise(() => `${base}.optional()`);
+      return `  ${v.name}: ${expr},`;
+    })
+    .join("\n");
+
+  return `z.object({\n${fields}\n})`;
+}
+
+const HEADER = [
+  "/*",
+  "|==========================================================================",
+  "| AUTO-GENERATED — DO NOT EDIT",
+  "|==========================================================================",
+  "|",
+  "| Run `funkai prompts generate` to regenerate.",
+  "|",
+  "*/",
+].join("\n");
+
+/**
+ * Generate a per-prompt TypeScript module with a default export.
+ *
+ * The module contains the Zod schema, inlined template, and
+ * `render` / `validate` functions.
+ */
+export function generatePromptModule(prompt: ParsedPrompt): string {
+  const escaped = escapeTemplateLiteral(prompt.template);
+  const schemaExpr = generateSchemaExpression(prompt.schema);
+  const groupValue = match(prompt.group != null)
+    .with(true, () => `'${prompt.group}' as const`)
+    .otherwise(() => "undefined");
+
+  const lines: string[] = [
+    HEADER,
+    `// Source: ${prompt.sourcePath}`,
+    "",
+    "import { z } from 'zod'",
+    "import { engine } from '@funkai/prompts'",
+    "",
+    `const schema = ${schemaExpr}`,
+    "",
+    "type Variables = z.infer<typeof schema>",
+    "",
+    `const template = \`${escaped}\``,
+    "",
+    "export default {",
+    `  name: '${prompt.name}' as const,`,
+    `  group: ${groupValue},`,
+    "  schema,",
+    ...match(prompt.schema.length)
+      .with(0, () => [
+        "  render(variables?: undefined): string {",
+        "    return engine.parseAndRenderSync(template, {})",
+        "  },",
+        "  validate(variables?: undefined): Variables {",
+        "    return schema.parse(variables ?? {})",
+        "  },",
+      ])
+      .otherwise(() => [
+        "  render(variables: Variables): string {",
+        "    return engine.parseAndRenderSync(template, schema.parse(variables))",
+        "  },",
+        "  validate(variables: unknown): Variables {",
+        "    return schema.parse(variables)",
+        "  },",
+      ]),
+    "}",
+    "",
+  ];
+
+  return lines.join("\n");
+}
+
+/**
+ * A tree node used during registry code generation.
+ * Leaves hold the camelCase import name; branches hold nested nodes.
+ */
+type TreeNode = {
+  readonly [key: string]: string | TreeNode;
+};
+
+/**
+ * Build a nested tree from sorted prompts, grouped by their `group` field.
+ *
+ * @param prompts - Sorted parsed prompts.
+ * @returns A tree where leaves are import names and branches are group namespaces.
+ * @throws If a prompt name collides with a group namespace at the same level.
+ *
+ * @private
+ */
+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 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.",
+        );
+      }
+      if (existing == null) {
+        current[segment] = {};
+      }
+      return current[segment] as Record<string, unknown>;
+    }, root);
+
+    if (typeof target[importName] === "object" && target[importName] !== null) {
+      throw new Error(
+        `Collision: prompt "${importName}" conflicts with existing group namespace ` +
+          `"${importName}" at the same level.`,
+      );
+    }
+
+    target[importName] = importName;
+    return root;
+  }, {}) as TreeNode;
+}
+
+/**
+ * Serialize a tree node into indented object literal lines.
+ *
+ * @param node - The tree node to serialize.
+ * @param indent - Current indentation level.
+ * @returns Array of source lines forming the object literal body.
+ *
+ * @private
+ */
+function serializeTree(node: TreeNode, indent: number): string[] {
+  const pad = "  ".repeat(indent);
+
+  return Object.entries(node).flatMap(([key, value]) =>
+    typeof value === "string"
+      ? [`${pad}${key},`]
+      : [`${pad}${key}: {`, ...serializeTree(value, indent + 1), `${pad}},`],
+  );
+}
+
+/**
+ * Generate the registry `index.ts` that wires all prompt modules
+ * together via `createPromptRegistry()`.
+ *
+ * Prompts are organized into a nested object structure based on their
+ * `group` field, with each `/`-separated segment becoming a nesting level.
+ */
+export function generateRegistry(prompts: ParsedPrompt[]): string {
+  const sorted = [...prompts].toSorted((a, b) => a.name.localeCompare(b.name));
+
+  const imports = sorted
+    .map((p) => `import ${toCamelCase(p.name)} from './${p.name}.js'`)
+    .join("\n");
+
+  const tree = buildTree(sorted);
+  const treeLines = serializeTree(tree, 1);
+
+  const lines: string[] = [
+    HEADER,
+    "",
+    "import { createPromptRegistry } from '@funkai/prompts'",
+    imports,
+    "",
+    "export const prompts = createPromptRegistry({",
+    ...treeLines,
+    "})",
+    "",
+  ];
+
+  return lines.join("\n");
+}

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

@@ -0,0 +1,32 @@
+import { Liquid } from "liquidjs";
+
+const DANGEROUS_NAMES = new Set(["constructor", "__proto__", "prototype"]);
+
+/**
+ * Extract top-level variable names from a Liquid template string.
+ *
+ * Uses LiquidJS's built-in `variablesSync` to parse the template AST
+ * and extract all referenced variable names. Only returns the root
+ * variable name (e.g. `user` from `{{ user.name }}`).
+ *
+ * @throws {Error} If a variable name is dangerous (e.g. `__proto__`)
+ */
+export function extractVariables(template: string): string[] {
+  const engine = new Liquid();
+  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);
+
+      if (DANGEROUS_NAMES.has(root)) {
+        throw new Error(`Dangerous variable name "${root}" is not allowed in prompt templates`);
+      }
+
+      return root;
+    }),
+  );
+
+  return [...roots].toSorted();
+}