@funkai/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funkai/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "description": "CLI for the funkai AI SDK framework",
   "keywords": [
@@ -31,13 +31,13 @@
   "dependencies": {
     "@kidd-cli/core": "^0.10.0",
     "es-toolkit": "^1.45.1",
-    "liquidjs": "^10.25.0",
+    "liquidjs": "^10.25.1",
     "picomatch": "^4.0.3",
     "ts-pattern": "^5.9.0",
-    "yaml": "^2.8.2",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6",
     "@funkai/config": "0.2.0",
-    "@funkai/prompts": "0.4.0"
+    "@funkai/prompts": "0.4.1"
   },
   "devDependencies": {
     "@kidd-cli/cli": "^0.4.9",

package/src/commands/generate.ts

@@ -15,8 +15,23 @@ export default command({
       ctx.logger.info("Running prompts code generation...");
     }
 
+    const generateHandleArgs: {
+      silent: boolean;
+      out?: string;
+      includes?: readonly string[];
+      partials?: string;
+    } = { silent: ctx.args.silent };
+    if (ctx.args.out !== undefined) {
+      generateHandleArgs.out = ctx.args.out;
+    }
+    if (ctx.args.includes !== undefined) {
+      generateHandleArgs.includes = ctx.args.includes;
+    }
+    if (ctx.args.partials !== undefined) {
+      generateHandleArgs.partials = ctx.args.partials;
+    }
     handleGenerate({
-      args: ctx.args,
+      args: generateHandleArgs,
       config: config.prompts,
       logger: ctx.logger,
       fail: ctx.fail,

package/src/commands/prompts/create.ts

@@ -33,6 +33,9 @@ export default command({
         if (includes.length > 0) {
           // Extract the static base directory from the first include pattern
           const [pattern] = includes;
+          if (pattern === undefined) {
+            return undefined;
+          }
           const parts = pattern.split("/");
           const staticParts = parts.filter((p) => !p.includes("*") && !p.includes("?"));
           if (staticParts.length > 0) {

package/src/commands/prompts/generate.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-import type { FunkaiConfig } from "@funkai/config";
+import type { FunkaiConfig, PromptGroup } from "@funkai/config";
 import { command } from "@kidd-cli/core";
 import { match } from "ts-pattern";
 import { z } from "zod";
@@ -71,7 +71,22 @@ function resolveGenerateArgs(
     fail("Missing --out flag. Provide it via CLI or set prompts.out in funkai.config.ts.");
   }
 
-  return { out, includes, excludes, partials, silent: args.silent };
+  const resolved: {
+    out: string;
+    includes: readonly string[];
+    excludes: readonly string[];
+    silent: boolean;
+    partials?: string;
+  } = {
+    out,
+    includes,
+    excludes,
+    silent: args.silent,
+  };
+  if (partials !== undefined) {
+    resolved.partials = partials;
+  }
+  return resolved;
 }
 
 /**
@@ -82,13 +97,21 @@ function resolveGenerateArgs(
 export function handleGenerate({ args, config, logger, fail }: HandleGenerateParams): void {
   const { out, includes, excludes, partials, silent } = resolveGenerateArgs(args, config, fail);
 
-  const { discovered, lintResults, prompts } = runGeneratePipeline({
-    includes,
-    excludes,
-    out,
-    partials,
-    groups: config && config.groups,
-  });
+  const configGroups = config && config.groups;
+  const pipelineOptions: {
+    includes: readonly string[];
+    excludes: readonly string[];
+    out: string;
+    partials?: string;
+    groups?: readonly PromptGroup[];
+  } = { includes, excludes, out };
+  if (partials !== undefined) {
+    pipelineOptions.partials = partials;
+  }
+  if (configGroups !== undefined) {
+    pipelineOptions.groups = configGroups;
+  }
+  const { discovered, lintResults, prompts } = runGeneratePipeline(pipelineOptions);
 
   if (!silent) {
     logger.info(`Found ${discovered} prompt(s)`);
@@ -149,8 +172,23 @@ export default command({
   options: generateArgs,
   handler(ctx) {
     const config = getConfig(ctx);
+    const generateArgs2: {
+      silent: boolean;
+      out?: string;
+      includes?: readonly string[];
+      partials?: string;
+    } = { silent: ctx.args.silent };
+    if (ctx.args.out !== undefined) {
+      generateArgs2.out = ctx.args.out;
+    }
+    if (ctx.args.includes !== undefined) {
+      generateArgs2.includes = ctx.args.includes;
+    }
+    if (ctx.args.partials !== undefined) {
+      generateArgs2.partials = ctx.args.partials;
+    }
     handleGenerate({
-      args: ctx.args,
+      args: generateArgs2,
       config: config.prompts,
       logger: ctx.logger,
       fail: ctx.fail,

package/src/commands/prompts/lint.ts

@@ -57,7 +57,16 @@ function resolveLintArgs(
   const excludes = (config && config.excludes) ?? [];
   const partials = args.partials ?? (config && config.partials);
 
-  return { includes, excludes, partials, silent: args.silent };
+  const resolved: {
+    includes: readonly string[];
+    excludes: readonly string[];
+    silent: boolean;
+    partials?: string;
+  } = { includes, excludes, silent: args.silent };
+  if (partials !== undefined) {
+    resolved.partials = partials;
+  }
+  return resolved;
 }
 
 /**
@@ -68,7 +77,15 @@ function resolveLintArgs(
 export function handleLint({ args, config, logger, fail }: HandleLintParams): void {
   const { includes, excludes, partials, silent } = resolveLintArgs(args, config, fail);
 
-  const { discovered, results } = runLintPipeline({ includes, excludes, partials });
+  const lintPipelineOptions: {
+    includes: readonly string[];
+    excludes: readonly string[];
+    partials?: string;
+  } = { includes, excludes };
+  if (partials !== undefined) {
+    lintPipelineOptions.partials = partials;
+  }
+  const { discovered, results } = runLintPipeline(lintPipelineOptions);
 
   if (!silent) {
     logger.info(`Linting ${discovered} prompt(s)...`);
@@ -109,8 +126,19 @@ export default command({
   options: lintArgs,
   handler(ctx) {
     const config = getConfig(ctx);
+    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: ctx.args,
+      args: lintHandleArgs,
       config: config.prompts,
       logger: ctx.logger,
       fail: ctx.fail,

package/src/commands/prompts/setup.ts

@@ -56,7 +56,7 @@ export async function setupPrompts(ctx: Pick<Context, "prompts" | "logger">): Pr
     const extensionsPath = resolve(vscodeDir, EXTENSIONS_FILE);
     const extensions = readJsonFile(extensionsPath);
 
-    const currentRecs = (extensions.recommendations ?? []) as string[];
+    const currentRecs = (extensions["recommendations"] ?? []) as string[];
     const extensionId = "sissel.shopify-liquid";
 
     const recommendations = ensureRecommendation(currentRecs, extensionId);
@@ -97,8 +97,8 @@ export async function setupPrompts(ctx: Pick<Context, "prompts" | "logger">): Pr
     const tsconfigPath = resolve(TSCONFIG_FILE);
     const tsconfig = readJsonFile(tsconfigPath);
 
-    const compilerOptions = (tsconfig.compilerOptions ?? {}) as Record<string, unknown>;
-    const existingPaths = (compilerOptions.paths ?? {}) as Record<string, string[]>;
+    const compilerOptions = (tsconfig["compilerOptions"] ?? {}) as Record<string, unknown>;
+    const existingPaths = (compilerOptions["paths"] ?? {}) as Record<string, string[]>;
 
     // oxlint-disable-next-line security/detect-object-injection -- safe: PROMPTS_ALIAS is a known constant string
     if (existingPaths[PROMPTS_ALIAS]) {

package/src/commands/setup.ts

@@ -1,6 +1,7 @@
 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";
 
@@ -44,23 +45,7 @@ export default command({
     });
 
     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 { includes, out } = await resolvePromptSettings(ctx, hasPrompts);
 
       const template = buildConfigTemplate({ hasPrompts, hasAgents, includes, out });
       const configPath = resolve("funkai.config.ts");
@@ -90,6 +75,43 @@ export default command({
 // 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;

package/src/commands/validate.ts

@@ -15,8 +15,19 @@ export default command({
       ctx.logger.info("Running prompts validation...");
     }
 
+    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: ctx.args,
+      args: lintHandleArgs,
       config: config.prompts,
       logger: ctx.logger,
       fail: ctx.fail,
@@ -25,7 +36,7 @@ export default command({
     // --- Future: agents validation ---
 
     if (!silent) {
-      ctx.logger.success("All validations passed.");
+      ctx.logger.success("No errors found.");
     }
   },
 });

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

@@ -108,10 +108,9 @@ function generateSchemaExpression(vars: readonly SchemaVariable[]): string {
 
 /** @private */
 function formatHeader(sourcePath?: string): string {
-  let sourceLine = "";
-  if (sourcePath) {
-    sourceLine = `//  Source:      ${sourcePath}\n`;
-  }
+  const sourceLine = match(sourcePath)
+    .with(undefined, () => "")
+    .otherwise((p) => `//  Source:      ${p}\n`);
   return [
     "// ─── AUTO-GENERATED ────────────────────────────────────────",
     `${sourceLine}//  Regenerate:  funkai prompts generate`,

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 };
           },
         )

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

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 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";
@@ -43,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 {
@@ -81,14 +86,10 @@ function deriveNameFromPath(filePath: string): string {
 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);
-  }
+  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 ".";