@funkai/cli 0.2.0 → 0.3.1

package/src/lib/prompts/lint.ts

@@ -17,6 +17,20 @@ export interface LintResult {
   readonly diagnostics: readonly LintDiagnostic[];
 }
 
+/**
+ * Parameters for linting a single prompt.
+ */
+export interface LintPromptParams {
+  /** Prompt name (for error messages). */
+  readonly name: string;
+  /** Source file path (for error messages). */
+  readonly filePath: string;
+  /** Variables declared in frontmatter schema. */
+  readonly schemaVars: readonly SchemaVariable[];
+  /** Variables extracted from the template body. */
+  readonly templateVars: readonly string[];
+}
+
 /**
  * Lint a prompt by comparing declared schema variables against
  * variables actually used in the template body.
@@ -24,18 +38,25 @@ export interface LintResult {
  * - **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.
+ * @param params - Lint prompt parameters.
  * @returns Lint result with diagnostics.
+ *
+ * @example
+ * ```ts
+ * const result = lintPrompt({
+ *   name: 'greeting',
+ *   filePath: 'prompts/greeting.prompt',
+ *   schemaVars: [{ name: 'name', type: 'string', required: true }],
+ *   templateVars: ['name'],
+ * });
+ * ```
  */
-export function lintPrompt(
-  name: string,
-  filePath: string,
-  schemaVars: readonly SchemaVariable[],
-  templateVars: readonly string[],
-): LintResult {
+export function lintPrompt({
+  name,
+  filePath,
+  schemaVars,
+  templateVars,
+}: LintPromptParams): LintResult {
   const declared = new Set(schemaVars.map((v) => v.name));
   const used = new Set(templateVars);
 

package/src/lib/prompts/paths.ts

@@ -1,6 +1,8 @@
 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 { match } from "ts-pattern";
 import { parse as parseYaml } from "yaml";
 
 import { FRONTMATTER_RE, NAME_RE } from "./frontmatter.js";
@@ -14,6 +16,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
 // ---------------------------------------------------------------------------
@@ -32,9 +44,13 @@ function extractName(content: string): string | undefined {
   }
 
   try {
-    const parsed = parseYaml(fmMatch[1]) as Record<string, unknown> | null;
-    if (parsed !== null && parsed !== undefined && typeof parsed.name === "string") {
-      return parsed.name;
+    const [, fmContent] = fmMatch;
+    if (fmContent === undefined) {
+      return undefined;
+    }
+    const parsed = parseYaml(fmContent) as Record<string, unknown> | null;
+    if (parsed !== null && parsed !== undefined && typeof parsed["name"] === "string") {
+      return parsed["name"];
     }
     return undefined;
   } catch {
@@ -58,6 +74,30 @@ 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 firstGlobIndex = parts.findIndex((part) => [...part].some((ch) => globChars.has(ch)));
+  const staticParts = match(firstGlobIndex)
+    .with(-1, () => parts)
+    .otherwise(() => parts.slice(0, firstGlobIndex));
+
+  if (staticParts.length === 0) {
+    return ".";
+  }
+
+  return staticParts.join("/");
+}
+
 /**
  * Recursively scan a directory for `.prompt` files.
  *
@@ -110,23 +150,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.
  *
- * @param roots - Directories to scan recursively.
- * @returns Sorted, deduplicated list of discovered prompts.
- * @throws If duplicate prompt names are found across roots.
+ * 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));
 }

package/src/lib/prompts/pipeline.ts

@@ -1,16 +1,71 @@
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
 
+import type { PromptGroup } from "@funkai/config";
 import { clean, PARTIALS_DIR } from "@funkai/prompts/cli";
+import { isNil } from "es-toolkit";
+import picomatch from "picomatch";
 
+import { toFileSlug } from "./codegen.js";
 import type { ParsedPrompt } from "./codegen.js";
 import { extractVariables } from "./extract-variables.js";
 import { flattenPartials } from "./flatten.js";
 import { parseFrontmatter } from "./frontmatter.js";
+import type { SchemaVariable } from "./frontmatter.js";
 import { lintPrompt } from "./lint.js";
 import type { LintResult } from "./lint.js";
 import { discoverPrompts } from "./paths.js";
 
+/**
+ * Validate that no two prompts share the same group+name combination.
+ *
+ * @param prompts - Parsed prompts with group and name fields.
+ * @throws If duplicate group+name combinations are found.
+ *
+ * @private
+ */
+function validateUniqueness(prompts: readonly ParsedPrompt[]): void {
+  const bySlug = Map.groupBy(prompts, (p) => toFileSlug(p.name, p.group));
+  const duplicate = [...bySlug.entries()].find(([, entries]) => entries.length > 1);
+
+  if (duplicate) {
+    const [slug, entries] = duplicate;
+    const paths = entries.map((p) => p.sourcePath).join("\n  ");
+    throw new Error(`Duplicate prompt "${slug}" (group+name) found in:\n  ${paths}`);
+  }
+}
+
+/**
+ * Resolve a prompt's group from config-defined group patterns.
+ *
+ * Matches the prompt's file path against each group's `includes`/`excludes`
+ * patterns. First matching group wins.
+ *
+ * @param filePath - Absolute path to the prompt file.
+ * @param groups - Config-defined group definitions.
+ * @returns The matching group name, or undefined if no match.
+ *
+ * @private
+ */
+function resolveGroupFromConfig(
+  filePath: string,
+  groups: readonly PromptGroup[],
+): string | undefined {
+  const matchPath = relative(process.cwd(), filePath).replaceAll("\\", "/");
+
+  const matched = groups.find((group) => {
+    const isIncluded = picomatch(group.includes as string[]);
+    const isExcluded = picomatch((group.excludes ?? []) as string[]);
+    return isIncluded(matchPath) && !isExcluded(matchPath);
+  });
+
+  if (isNil(matched)) {
+    return undefined;
+  }
+
+  return matched.name;
+}
+
 /**
  * Resolve the list of partial directories to search.
  *
@@ -30,7 +85,8 @@ function resolvePartialsDirs(customDir: string): readonly string[] {
  * Options for the prompts lint pipeline.
  */
 export interface LintPipelineOptions {
-  readonly roots: readonly string[];
+  readonly includes: readonly string[];
+  readonly excludes?: readonly string[];
   readonly partials?: string;
 }
 
@@ -49,7 +105,14 @@ export interface LintPipelineResult {
  * @returns Lint results for all discovered prompts.
  */
 export function runLintPipeline(options: LintPipelineOptions): LintPipelineResult {
-  const discovered = discoverPrompts([...options.roots]);
+  const discoverLintOptions: {
+    includes: string[];
+    excludes?: string[];
+  } = { includes: [...options.includes] };
+  if (options.excludes !== undefined) {
+    discoverLintOptions.excludes = [...options.excludes];
+  }
+  const discovered = discoverPrompts(discoverLintOptions);
   const customPartialsDir = resolve(options.partials ?? ".prompts/partials");
   const partialsDirs = resolvePartialsDirs(customPartialsDir);
 
@@ -59,7 +122,12 @@ export function runLintPipeline(options: LintPipelineOptions): LintPipelineResul
     const frontmatter = parseFrontmatter({ content: raw, filePath: d.filePath });
     const template = flattenPartials({ template: clean(raw), partialsDirs });
     const templateVars = extractVariables(template);
-    return lintPrompt(frontmatter.name, d.filePath, frontmatter.schema, templateVars);
+    return lintPrompt({
+      name: frontmatter.name,
+      filePath: d.filePath,
+      schemaVars: frontmatter.schema,
+      templateVars,
+    });
   });
 
   return { discovered: discovered.length, results };
@@ -69,9 +137,11 @@ export function runLintPipeline(options: LintPipelineOptions): LintPipelineResul
  * Options for the prompts generate pipeline.
  */
 export interface GeneratePipelineOptions {
-  readonly roots: readonly string[];
+  readonly includes: readonly string[];
+  readonly excludes?: readonly string[];
   readonly out: string;
   readonly partials?: string;
+  readonly groups?: readonly PromptGroup[];
 }
 
 /**
@@ -92,9 +162,17 @@ export interface GeneratePipelineResult {
  * @returns Parsed prompts ready for code generation, along with lint results.
  */
 export function runGeneratePipeline(options: GeneratePipelineOptions): GeneratePipelineResult {
-  const discovered = discoverPrompts([...options.roots]);
+  const discoverGenerateOptions: {
+    includes: string[];
+    excludes?: string[];
+  } = { includes: [...options.includes] };
+  if (options.excludes !== undefined) {
+    discoverGenerateOptions.excludes = [...options.excludes];
+  }
+  const discovered = discoverPrompts(discoverGenerateOptions);
   const customPartialsDir = resolve(options.partials ?? resolve(options.out, "../partials"));
   const partialsDirs = resolvePartialsDirs(customPartialsDir);
+  const configGroups = options.groups ?? [];
 
   const processed = discovered.map((d) => {
     // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading discovered prompt file
@@ -103,21 +181,41 @@ export function runGeneratePipeline(options: GeneratePipelineOptions): GenerateP
     const template = flattenPartials({ template: clean(raw), partialsDirs });
     const templateVars = extractVariables(template);
 
+    // Frontmatter group wins; fall back to config-defined group patterns
+    const group = frontmatter.group ?? resolveGroupFromConfig(d.filePath, configGroups);
+
+    const promptObj: {
+      name: string;
+      schema: readonly SchemaVariable[];
+      template: string;
+      sourcePath: string;
+      group?: string;
+    } = {
+      name: frontmatter.name,
+      schema: frontmatter.schema,
+      template,
+      sourcePath: d.filePath,
+    };
+    if (group !== undefined) {
+      promptObj.group = group;
+    }
     return {
-      lintResult: lintPrompt(frontmatter.name, d.filePath, frontmatter.schema, templateVars),
-      prompt: {
+      lintResult: lintPrompt({
         name: frontmatter.name,
-        group: frontmatter.group,
-        schema: frontmatter.schema,
-        template,
-        sourcePath: d.filePath,
-      } satisfies ParsedPrompt,
+        filePath: d.filePath,
+        schemaVars: frontmatter.schema,
+        templateVars,
+      }),
+      prompt: promptObj satisfies ParsedPrompt,
     };
   });
 
+  const prompts = processed.map((p) => p.prompt);
+  validateUniqueness(prompts);
+
   return {
     discovered: discovered.length,
     lintResults: processed.map((p) => p.lintResult),
-    prompts: processed.map((p) => p.prompt),
+    prompts,
   };
 }

package/tsconfig.json

@@ -5,15 +5,23 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "lib": ["ES2024"],
+    "types": ["node"],
+
     "strict": true,
-    "esModuleInterop": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
+
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
+
     "outDir": "./dist",
     "rootDir": ".",
     "paths": {