@funkai/cli 0.2.0 → 0.3.0

package/src/commands/setup.ts

@@ -1,12 +1,137 @@
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
 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) {
+      let includes = ["src/prompts/**"];
+      let out = ".prompts/client";
+
+      if (hasPrompts) {
+        const includesInput = await ctx.prompts.text({
+          message: "Prompt include patterns (comma-separated)",
+          defaultValue: "src/prompts/**",
+          placeholder: "src/prompts/**",
+        });
+        includes = includesInput.split(",").map((r) => r.trim());
+
+        out = await ctx.prompts.text({
+          message: "Output directory for generated prompt modules",
+          defaultValue: ".prompts/client",
+          placeholder: ".prompts/client",
+        });
+      }
+
+      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 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,19 +1,26 @@
 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 });
+    handleLint({
+      args: ctx.args,
+      config: config.prompts,
+      logger: ctx.logger,
+      fail: ctx.fail,
+    });
 
     // --- Future: agents validation ---
 

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/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,79 @@ 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 {
+  let sourceLine = "";
+  if (sourcePath) {
+    sourceLine = `//  Source:      ${sourcePath}\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 +186,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 +213,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 +224,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 +241,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 +266,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 +286,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/paths.ts

@@ -1,6 +1,7 @@
 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";
@@ -14,6 +15,16 @@ export interface DiscoveredPrompt {
   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
 // ---------------------------------------------------------------------------
@@ -58,6 +69,34 @@ 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.
  *
@@ -110,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.
  *
- * @param roots - Directories to scan recursively.
- * @returns Sorted, deduplicated list of discovered prompts.
- * @throws If duplicate prompt names are found across roots.
+ * 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 options - Include and exclude glob patterns.
+ * @returns Sorted list of discovered prompts.
  */
-export function discoverPrompts(roots: readonly string[]): readonly 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));
 }