@funkai/cli 0.2.0 → 0.3.1

package/src/commands/setup.ts

@@ -1,12 +1,159 @@
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import type { Context } from "@kidd-cli/core";
 import { command } from "@kidd-cli/core";
+import { match } from "ts-pattern";
+
+import { setupPrompts } from "@/commands/prompts/setup.js";
+
+/** @private */
+const CONFIG_TEMPLATE_AGENTS_ONLY = `import { defineConfig } from "@funkai/config";
+
+export default defineConfig({
+  agents: {},
+});
+`;
 
 export default command({
   description: "Set up your project for the funkai SDK",
   async handler(ctx) {
     ctx.logger.intro("funkai — Project Setup");
-    ctx.logger.info("Run domain-specific setup commands:");
-    ctx.logger.step("funkai prompts setup  — Configure IDE and project for .prompt files");
-    ctx.logger.step("funkai agents setup   — (coming soon)");
-    ctx.logger.outro("Choose the setup command for your domain.");
+
+    // --- Domain selection ---
+    const domains = await ctx.prompts.multiselect({
+      message: "Which domains do you want to set up?",
+      options: [
+        {
+          value: "prompts" as const,
+          label: "Prompts",
+          hint: "LiquidJS templating, codegen, IDE integration",
+        },
+        { value: "agents" as const, label: "Agents", hint: "Agent scaffolding and configuration" },
+      ],
+      initialValues: ["prompts" as const],
+      required: true,
+    });
+
+    const hasPrompts = domains.includes("prompts");
+    const hasAgents = domains.includes("agents");
+
+    // --- Create funkai.config.ts ---
+    const shouldCreateConfig = await ctx.prompts.confirm({
+      message: "Create funkai.config.ts?",
+      initialValue: true,
+    });
+
+    if (shouldCreateConfig) {
+      const { includes, out } = await resolvePromptSettings(ctx, hasPrompts);
+
+      const template = buildConfigTemplate({ hasPrompts, hasAgents, includes, out });
+      const configPath = resolve("funkai.config.ts");
+      // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: writing config file to project root
+      writeFileSync(configPath, template, "utf8");
+      ctx.logger.success(`Created ${configPath}`);
+    }
+
+    // --- Run domain-specific setup ---
+    if (hasPrompts) {
+      ctx.logger.info("");
+      ctx.logger.info("Configuring Prompts...");
+      await setupPrompts(ctx);
+    }
+
+    if (hasAgents) {
+      ctx.logger.info("");
+      ctx.logger.info("Agents configuration is not yet available.");
+      ctx.logger.info("The agents section has been added to your config for future use.");
+    }
+
+    ctx.logger.outro("Project setup complete.");
   },
 });
+
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
+/** @private */
+interface PromptSettings {
+  readonly includes: readonly string[];
+  readonly out: string;
+}
+
+/**
+ * Gather prompt include patterns and output directory from the user.
+ *
+ * @private
+ * @param ctx - CLI context for prompts.
+ * @param hasPrompts - Whether the prompts domain is selected.
+ * @returns The resolved prompt settings.
+ */
+async function resolvePromptSettings(ctx: Context, hasPrompts: boolean): Promise<PromptSettings> {
+  if (!hasPrompts) {
+    return { includes: ["src/prompts/**"], out: ".prompts/client" };
+  }
+
+  const includesInput = await ctx.prompts.text({
+    message: "Prompt include patterns (comma-separated)",
+    defaultValue: "src/prompts/**",
+    placeholder: "src/prompts/**",
+  });
+
+  const out = await ctx.prompts.text({
+    message: "Output directory for generated prompt modules",
+    defaultValue: ".prompts/client",
+    placeholder: ".prompts/client",
+  });
+
+  return {
+    includes: includesInput.split(",").map((r) => r.trim()),
+    out,
+  };
+}
+
+/** @private */
+interface ConfigTemplateOptions {
+  readonly hasPrompts: boolean;
+  readonly hasAgents: boolean;
+  readonly includes: readonly string[];
+  readonly out: string;
+}
+
+/** @private */
+function buildConfigTemplate({
+  hasPrompts,
+  hasAgents,
+  includes,
+  out,
+}: ConfigTemplateOptions): string {
+  if (hasPrompts && hasAgents) {
+    return buildCustomTemplate(includes, out, true);
+  }
+  if (hasPrompts) {
+    return buildCustomTemplate(includes, out, false);
+  }
+  return CONFIG_TEMPLATE_AGENTS_ONLY;
+}
+
+/** @private */
+function buildCustomTemplate(
+  includes: readonly string[],
+  out: string,
+  includeAgents: boolean,
+): string {
+  const includesStr = includes.map((r) => `"${r}"`).join(", ");
+  const agentsBlock = match(includeAgents)
+    .with(true, () => "\n  agents: {},\n")
+    .with(false, () => "\n")
+    .exhaustive();
+
+  return `import { defineConfig } from "@funkai/config";
+
+export default defineConfig({
+  prompts: {
+    includes: [${includesStr}],
+    out: "${out}",
+  },${agentsBlock}});
+`;
+}

package/src/commands/validate.ts

@@ -1,24 +1,42 @@
 import { command } from "@kidd-cli/core";
 
 import { handleLint, lintArgs } from "./prompts/lint.js";
+import { getConfig } from "@/config.js";
 
 export default command({
   description: "Run all validations across the funkai SDK",
   options: lintArgs,
   handler(ctx) {
     const { silent } = ctx.args;
+    const config = getConfig(ctx);
 
     // --- Prompts validation ---
     if (!silent) {
       ctx.logger.info("Running prompts validation...");
     }
 
-    handleLint({ args: ctx.args, logger: ctx.logger, fail: ctx.fail });
+    const lintHandleArgs: {
+      silent: boolean;
+      includes?: readonly string[];
+      partials?: string;
+    } = { silent: ctx.args.silent };
+    if (ctx.args.includes !== undefined) {
+      lintHandleArgs.includes = ctx.args.includes;
+    }
+    if (ctx.args.partials !== undefined) {
+      lintHandleArgs.partials = ctx.args.partials;
+    }
+    handleLint({
+      args: lintHandleArgs,
+      config: config.prompts,
+      logger: ctx.logger,
+      fail: ctx.fail,
+    });
 
     // --- Future: agents validation ---
 
     if (!silent) {
-      ctx.logger.success("All validations passed.");
+      ctx.logger.success("No errors found.");
     }
   },
 });

package/src/config.ts

@@ -0,0 +1,28 @@
+import type { FunkaiConfig } from "@funkai/config";
+import { configSchema } from "@funkai/config";
+import type { ConfigType, Context } from "@kidd-cli/core";
+
+export { configSchema };
+
+/**
+ * Extract the typed funkai config from a command context.
+ *
+ * kidd-cli's `Merge<CliConfig, TConfig>` erases augmented keys when
+ * `TConfig` defaults to `Record<string, unknown>`, so we cast here.
+ *
+ * @param ctx - The CLI context.
+ * @returns The typed funkai configuration.
+ *
+ * @example
+ * ```ts
+ * const config = getConfig(ctx);
+ * const promptsConfig = config.prompts;
+ * ```
+ */
+export function getConfig(ctx: Pick<Context, "config">): Readonly<FunkaiConfig> {
+  return ctx.config as unknown as Readonly<FunkaiConfig>;
+}
+
+declare module "@kidd-cli/core" {
+  interface CliConfig extends ConfigType<typeof configSchema> {}
+}

package/src/index.ts

@@ -10,6 +10,7 @@ import promptsLint from "@/commands/prompts/lint.js";
 import promptsSetup from "@/commands/prompts/setup.js";
 import setup from "@/commands/setup.js";
 import validate from "@/commands/validate.js";
+import { configSchema } from "@/config.js";
 
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json") as { readonly version: string };
@@ -18,6 +19,9 @@ await cli({
   description: "CLI for the funkai AI SDK framework",
   name: "funkai",
   version: packageJson.version,
+  config: {
+    schema: configSchema,
+  },
   commands: {
     generate,
     setup,

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

@@ -4,48 +4,60 @@ 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"],
-    );
+    const result = lintPrompt({
+      name: "test",
+      filePath: "test.prompt",
+      schemaVars: [{ name: "scope", type: "string", required: true }],
+      templateVars: ["scope"],
+    });
     expect(result.diagnostics).toEqual([]);
   });
 
   it("errors on undefined template variable", () => {
-    const result = lintPrompt("test", "test.prompt", [], ["scope"]);
+    const result = lintPrompt({
+      name: "test",
+      filePath: "test.prompt",
+      schemaVars: [],
+      templateVars: ["scope"],
+    });
     expect(result.diagnostics).toHaveLength(1);
-    expect(result.diagnostics[0].level).toBe("error");
-    expect(result.diagnostics[0].message).toContain('Undefined variable "scope"');
+    const [diag0] = result.diagnostics;
+    expect(diag0?.level).toBe("error");
+    expect(diag0?.message).toContain('Undefined variable "scope"');
   });
 
   it("warns on unused schema variable", () => {
-    const result = lintPrompt(
-      "test",
-      "test.prompt",
-      [{ name: "scope", type: "string", required: true }],
-      [],
-    );
+    const result = lintPrompt({
+      name: "test",
+      filePath: "test.prompt",
+      schemaVars: [{ name: "scope", type: "string", required: true }],
+      templateVars: [],
+    });
     expect(result.diagnostics).toHaveLength(1);
-    expect(result.diagnostics[0].level).toBe("warn");
-    expect(result.diagnostics[0].message).toContain('Unused variable "scope"');
+    const [diag0] = result.diagnostics;
+    expect(diag0?.level).toBe("warn");
+    expect(diag0?.message).toContain('Unused variable "scope"');
   });
 
   it("reports both errors and warnings", () => {
-    const result = lintPrompt(
-      "test",
-      "test.prompt",
-      [{ name: "declared", type: "string", required: true }],
-      ["undeclared"],
-    );
+    const result = lintPrompt({
+      name: "test",
+      filePath: "test.prompt",
+      schemaVars: [{ name: "declared", type: "string", required: true }],
+      templateVars: ["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", [], []);
+    const result = lintPrompt({
+      name: "test",
+      filePath: "test.prompt",
+      schemaVars: [],
+      templateVars: [],
+    });
     expect(result.diagnostics).toEqual([]);
   });
 });

package/src/lib/prompts/codegen.ts

@@ -67,6 +67,14 @@ function formatGroupValue(group: string | undefined): string {
   return "undefined";
 }
 
+/** @private */
+function formatGroupJsdoc(group: string | undefined): readonly string[] {
+  if (group) {
+    return [" *", ` * @group ${group}`];
+  }
+  return [];
+}
+
 /** @private */
 function parseGroupSegments(group: string | undefined): readonly string[] {
   if (group) {
@@ -98,34 +106,78 @@ function generateSchemaExpression(vars: readonly SchemaVariable[]): string {
   return `z.object({\n${fields}\n})`;
 }
 
-const HEADER = [
-  "/*",
-  "|==========================================================================",
-  "| AUTO-GENERATED — DO NOT EDIT",
-  "|==========================================================================",
-  "|",
-  "| Run `funkai prompts generate` to regenerate.",
-  "|",
-  "*/",
-].join("\n");
+/** @private */
+function formatHeader(sourcePath?: string): string {
+  const sourceLine = match(sourcePath)
+    .with(undefined, () => "")
+    .otherwise((p) => `//  Source:      ${p}\n`);
+  return [
+    "// ─── AUTO-GENERATED ────────────────────────────────────────",
+    `${sourceLine}//  Regenerate:  funkai prompts generate`,
+    "// ───────────────────────────────────────────────────────────",
+  ].join("\n");
+}
+
+/**
+ * Derive a unique file slug from group + name.
+ *
+ * Ungrouped prompts use the name alone. Grouped prompts
+ * join group segments and name with hyphens.
+ *
+ * @param name - The prompt name (kebab-case).
+ * @param group - Optional group path (e.g., 'core/agent').
+ * @returns The file slug string.
+ *
+ * @example
+ * ```ts
+ * toFileSlug('system', 'core/agent')      // => 'core-agent-system'
+ * toFileSlug('greeting', undefined)        // => 'greeting'
+ * ```
+ */
+export function toFileSlug(name: string, group?: string): string {
+  if (group) {
+    return `${group.replaceAll("/", "-")}-${name}`;
+  }
+  return name;
+}
+
+/**
+ * Derive a unique import name (camelCase) from group + name.
+ *
+ * @param name - The prompt name (kebab-case).
+ * @param group - Optional group path (e.g., 'core/agent').
+ * @returns The camelCase import identifier.
+ *
+ * @example
+ * ```ts
+ * toImportName('system', 'core/agent')     // => 'coreAgentSystem'
+ * toImportName('greeting', undefined)       // => 'greeting'
+ * ```
+ */
+export function toImportName(name: string, group?: string): string {
+  return toCamelCase(toFileSlug(name, group));
+}
 
 /**
  * Generate a per-prompt TypeScript module with a default export.
  *
- * The module contains the Zod schema, inlined template, and
- * `render` / `validate` functions.
+ * The module uses `createPrompt` from `@funkai/prompts` to
+ * encapsulate the Zod schema, inlined template, and render logic.
+ *
+ * @param prompt - The parsed prompt configuration.
+ * @returns The generated TypeScript module source code.
  */
 export function generatePromptModule(prompt: ParsedPrompt): string {
   const escaped = escapeTemplateLiteral(prompt.template);
   const schemaExpr = generateSchemaExpression(prompt.schema);
   const groupValue = formatGroupValue(prompt.group);
+  const header = formatHeader(prompt.sourcePath);
 
   const lines: readonly string[] = [
-    HEADER,
-    `// Source: ${prompt.sourcePath}`,
+    header,
     "",
     "import { z } from 'zod'",
-    "import { liquidEngine } from '@funkai/prompts/runtime'",
+    "import { createPrompt } from '@funkai/prompts'",
     "",
     `const schema = ${schemaExpr}`,
     "",
@@ -133,28 +185,16 @@ export function generatePromptModule(prompt: ParsedPrompt): string {
     "",
     `const template = \`${escaped}\``,
     "",
-    "export default {",
-    `  name: '${prompt.name}' as const,`,
+    "/**",
+    ` * **${prompt.name}** prompt module.`,
+    ...formatGroupJsdoc(prompt.group),
+    " */",
+    "export default createPrompt<Variables>({",
+    `  name: '${prompt.name}',`,
     `  group: ${groupValue},`,
+    "  template,",
     "  schema,",
-    ...match(prompt.schema.length)
-      .with(0, () => [
-        "  render(variables?: undefined): string {",
-        "    return liquidEngine.parseAndRenderSync(template, {})",
-        "  },",
-        "  validate(variables?: undefined): Variables {",
-        "    return schema.parse(variables ?? {})",
-        "  },",
-      ])
-      .otherwise(() => [
-        "  render(variables: Variables): string {",
-        "    return liquidEngine.parseAndRenderSync(template, schema.parse(variables))",
-        "  },",
-        "  validate(variables: unknown): Variables {",
-        "    return schema.parse(variables)",
-        "  },",
-      ]),
-    "}",
+    "})",
     "",
   ];
 
@@ -172,6 +212,9 @@ interface TreeNode {
 /**
  * Build a nested tree from sorted prompts, grouped by their `group` field.
  *
+ * Leaf values are the unique import name derived from group+name,
+ * so prompts with the same name in different groups do not collide.
+ *
  * @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.
@@ -180,7 +223,8 @@ interface TreeNode {
  */
 function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
   return prompts.reduce<Record<string, unknown>>((root, prompt) => {
-    const importName = toCamelCase(prompt.name);
+    const leafKey = toCamelCase(prompt.name);
+    const importName = toImportName(prompt.name, prompt.group);
     const segments = parseGroupSegments(prompt.group);
 
     const target = segments.reduce<Record<string, unknown>>((current, segment) => {
@@ -196,13 +240,13 @@ function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
       return current[segment] as Record<string, unknown>;
     }, root);
 
-    if (typeof target[importName] === "object" && target[importName] !== null) {
+    if (typeof target[leafKey] === "object" && target[leafKey] !== null) {
       throw new Error(
-        `Collision: prompt "${importName}" conflicts with existing group namespace "${importName}" at the same level.`,
+        `Collision: prompt "${leafKey}" conflicts with existing group namespace "${leafKey}" at the same level.`,
       );
     }
 
-    target[importName] = importName;
+    target[leafKey] = importName;
     return root;
   }, {}) as TreeNode;
 }
@@ -221,7 +265,12 @@ function serializeTree(node: TreeNode, indent: number): readonly string[] {
 
   return Object.entries(node).flatMap(([key, value]) =>
     match(typeof value)
-      .with("string", () => [`${pad}${key},`])
+      .with("string", () => {
+        if (key === value) {
+          return [`${pad}${key},`];
+        }
+        return [`${pad}${key}: ${value as string},`];
+      })
       .otherwise(() => [
         `${pad}${key}: {`,
         ...serializeTree(value as TreeNode, indent + 1),
@@ -236,19 +285,39 @@ function serializeTree(node: TreeNode, indent: number): readonly string[] {
  *
  * Prompts are organized into a nested object structure based on their
  * `group` field, with each `/`-separated segment becoming a nesting level.
+ *
+ * @param prompts - Sorted parsed prompts to include in the registry.
+ * @returns The generated TypeScript source for the registry index module.
+ *
+ * @example
+ * ```ts
+ * const source = generateRegistry([
+ *   { name: 'system', group: 'core/agent', schema: [], template: '...', sourcePath: 'prompts/system.prompt' },
+ * ])
+ * writeFileSync('index.ts', source)
+ * ```
  */
 export function generateRegistry(prompts: readonly ParsedPrompt[]): string {
-  const sorted = [...prompts].toSorted((a, b) => a.name.localeCompare(b.name));
+  const sorted = [...prompts].toSorted((a, b) => {
+    const slugA = toFileSlug(a.name, a.group);
+    const slugB = toFileSlug(b.name, b.group);
+    return slugA.localeCompare(slugB);
+  });
 
   const imports = sorted
-    .map((p) => `import ${toCamelCase(p.name)} from './${p.name}.js'`)
+    .map((p) => {
+      const importName = toImportName(p.name, p.group);
+      const fileSlug = toFileSlug(p.name, p.group);
+      return `import ${importName} from './${fileSlug}.js'`;
+    })
     .join("\n");
 
   const tree = buildTree(sorted);
   const treeLines = serializeTree(tree, 1);
+  const header = formatHeader();
 
   const lines: readonly string[] = [
-    HEADER,
+    header,
     "",
     "import { createPromptRegistry } from '@funkai/prompts'",
     imports,

package/src/lib/prompts/flatten.ts

@@ -32,18 +32,19 @@ function parseParamsOrEmpty(raw: string, partialName: string): Record<string, st
  */
 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]);
+  const allParamNames = [...raw.matchAll(/(\w+)\s*:/g)].map(([, m1]) => m1);
 
   return Object.fromEntries(
     allParamNames.map((name) => {
-      const literal = literalMatches.find((m) => m[1] === name);
+      const literal = literalMatches.find(([, m1]) => m1 === 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]];
+      const { 2: literalValue } = literal;
+      return [name, literalValue];
     }),
   );
 }
@@ -81,10 +82,14 @@ function renderPartial(engine: Liquid, tag: RenderTag): string {
  */
 function parseRenderTags(template: string): RenderTag[] {
   return [...template.matchAll(RENDER_TAG_RE)].map((m) => {
+    const [, partialName] = m;
+    if (partialName === undefined) {
+      throw new Error("Malformed render tag: missing partial name");
+    }
     const rawParams: string = (m[2] ?? "").trim();
-    const params = parseParamsOrEmpty(rawParams, m[1]);
+    const params = parseParamsOrEmpty(rawParams, partialName);
 
-    return { fullMatch: m[0], partialName: m[1], params };
+    return { fullMatch: m[0], partialName, params };
   });
 }
 

package/src/lib/prompts/frontmatter.ts

@@ -76,7 +76,11 @@ export function parseFrontmatter({ content, filePath }: ParseFrontmatterParams):
     throw new Error(`No frontmatter found in ${filePath}`);
   }
 
-  const parsed = parseYamlContent(fmMatch[1], filePath);
+  const [, fmContent] = fmMatch;
+  if (fmContent === undefined) {
+    throw new Error(`No frontmatter content found in ${filePath}`);
+  }
+  const parsed = parseYamlContent(fmContent, filePath);
 
   if (!parsed || typeof parsed !== "object") {
     throw new Error(`Frontmatter is not a valid object in ${filePath}`);
@@ -94,12 +98,24 @@ export function parseFrontmatter({ content, filePath }: ParseFrontmatterParams):
     );
   }
 
-  const group = parseGroup(parsed.group, filePath);
-  const version = parseVersion(parsed.version);
+  const group = parseGroup(parsed["group"], filePath);
+  const version = parseVersion(parsed["version"]);
 
-  const schema = parseSchemaBlock(parsed.schema, filePath);
+  const schema = parseSchemaBlock(parsed["schema"], filePath);
 
-  return { name, group, version, schema };
+  const result: {
+    name: string;
+    schema: readonly SchemaVariable[];
+    group?: string;
+    version?: string;
+  } = { name, schema };
+  if (group !== undefined) {
+    result.group = group;
+  }
+  if (version !== undefined) {
+    result.version = version;
+  }
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -180,9 +196,9 @@ function parseSchemaBlock(raw: unknown, filePath: string): readonly SchemaVariab
               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);
+            const type = stringOrDefault(def["type"], "string");
+            const required = def["required"] !== false;
+            const description = stringOrUndefined(def["description"]);
             return { name: varName, type, required, description };
           },
         )