@funkai/cli 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funkai/cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "private": false,
   "description": "CLI for the funkai AI SDK framework",
   "keywords": [
@@ -30,11 +30,12 @@
   },
   "dependencies": {
     "@kidd-cli/core": "^0.10.0",
+    "es-toolkit": "^1.45.1",
     "liquidjs": "^10.25.0",
     "ts-pattern": "^5.9.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@funkai/prompts": "0.2.0"
+    "@funkai/prompts": "0.3.0"
   },
   "devDependencies": {
     "@kidd-cli/cli": "^0.4.9",

package/src/commands/generate.ts

@@ -13,7 +13,7 @@ export default command({
       ctx.logger.info("Running prompts code generation...");
     }
 
-    handleGenerate(ctx.args, ctx.logger, ctx.fail);
+    handleGenerate({ args: ctx.args, logger: ctx.logger, fail: ctx.fail });
 
     // --- Future: agents codegen ---
   },

package/src/commands/prompts/create.ts

@@ -5,6 +5,7 @@ import { command } from "@kidd-cli/core";
 import { match, P } from "ts-pattern";
 import { z } from "zod";
 
+/** @private */
 const createTemplate = (name: string) => `---
 name: ${name}
 ---

package/src/commands/prompts/generate.ts

@@ -2,12 +2,14 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { command } from "@kidd-cli/core";
+import { match } from "ts-pattern";
 import { z } from "zod";
 
 import { generatePromptModule, generateRegistry } from "@/lib/prompts/codegen.js";
 import { hasLintErrors } from "@/lib/prompts/lint.js";
 import { runGeneratePipeline } from "@/lib/prompts/pipeline.js";
 
+/** Zod schema for the `prompts generate` CLI arguments. */
 export const generateArgs = z.object({
   out: z.string().describe("Output directory for generated files"),
   roots: z.array(z.string()).describe("Root directories to scan for .prompt files"),
@@ -15,31 +17,35 @@ export const generateArgs = z.object({
   silent: z.boolean().default(false).describe("Suppress output except errors"),
 });
 
+/** Inferred type of the `prompts generate` CLI arguments. */
 export type GenerateArgs = z.infer<typeof generateArgs>;
 
 /**
- * Shared handler for prompts code generation.
- *
- * @param args - Parsed CLI arguments.
- * @param logger - Logger instance from the command context.
- * @param fail - Failure callback from the command context.
+ * Parameters for the shared generate handler.
  */
-export function handleGenerate(
-  args: {
+export interface HandleGenerateParams {
+  readonly args: {
     readonly out: string;
     readonly roots: readonly string[];
     readonly partials?: string;
     readonly silent: boolean;
-  },
-  logger: {
+  };
+  readonly logger: {
     info: (msg: string) => void;
     step: (msg: string) => void;
     error: (msg: string) => void;
     warn: (msg: string) => void;
     success: (msg: string) => void;
-  },
-  fail: (msg: string) => never,
-): void {
+  };
+  readonly fail: (msg: string) => never;
+}
+
+/**
+ * Shared handler for prompts code generation.
+ *
+ * @param params - Handler context with args, logger, and fail callback.
+ */
+export function handleGenerate({ args, logger, fail }: HandleGenerateParams): void {
   const { out, roots, partials, silent } = args;
 
   const { discovered, lintResults, prompts } = runGeneratePipeline({ roots, out, partials });
@@ -50,25 +56,20 @@ export function handleGenerate(
 
   if (!silent) {
     for (const prompt of prompts) {
-      // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-      const varList: string = (() => {
-        if (prompt.schema.length > 0) {
-          return ` (${prompt.schema.map((v) => v.name).join(", ")})`;
-        }
-        return "";
-      })();
+      const varList = formatVarList(prompt.schema);
       logger.step(`${prompt.name}${varList}`);
     }
   }
 
-  for (const result of lintResults) {
-    for (const diag of result.diagnostics) {
-      if (diag.level === "error") {
-        logger.error(diag.message);
-      } else {
-        logger.warn(diag.message);
-      }
-    }
+  for (const diag of lintResults.flatMap((result) => result.diagnostics)) {
+    match(diag.level)
+      .with("error", () => logger.error(diag.message))
+      .with("warn", () => {
+        if (!silent) {
+          logger.warn(diag.message);
+        }
+      })
+      .exhaustive();
   }
 
   if (hasLintErrors(lintResults)) {
@@ -94,10 +95,18 @@ export function handleGenerate(
   }
 }
 
+/** @private */
+function formatVarList(schema: readonly { readonly name: string }[]): string {
+  if (schema.length > 0) {
+    return ` (${schema.map((v) => v.name).join(", ")})`;
+  }
+  return "";
+}
+
 export default command({
   description: "Generate TypeScript modules from .prompt files",
   options: generateArgs,
   handler(ctx) {
-    handleGenerate(ctx.args, ctx.logger, ctx.fail);
+    handleGenerate({ args: ctx.args, logger: ctx.logger, fail: ctx.fail });
   },
 });

package/src/commands/prompts/lint.ts

@@ -1,33 +1,43 @@
 import { command } from "@kidd-cli/core";
+import { match } from "ts-pattern";
 import { z } from "zod";
 
 import { hasLintErrors } from "@/lib/prompts/lint.js";
 import { runLintPipeline } from "@/lib/prompts/pipeline.js";
 
+/** Zod schema for the `prompts lint` CLI arguments. */
 export const lintArgs = z.object({
   roots: z.array(z.string()).describe("Root directories to scan for .prompt files"),
   partials: z.string().optional().describe("Custom partials directory"),
   silent: z.boolean().default(false).describe("Suppress output except errors"),
 });
 
+/** Inferred type of the `prompts lint` CLI arguments. */
 export type LintArgs = z.infer<typeof lintArgs>;
 
 /**
- * Shared handler for prompts lint/validation.
- *
- * @param args - Parsed CLI arguments.
- * @param logger - Logger instance from the command context.
- * @param fail - Failure callback from the command context.
+ * Parameters for the shared lint handler.
  */
-export function handleLint(
-  args: { readonly roots: readonly string[]; readonly partials?: string; readonly silent: boolean },
-  logger: {
+export interface HandleLintParams {
+  readonly args: {
+    readonly roots: readonly string[];
+    readonly partials?: string;
+    readonly silent: boolean;
+  };
+  readonly logger: {
     info: (msg: string) => void;
     error: (msg: string) => void;
     warn: (msg: string) => void;
-  },
-  fail: (msg: string) => never,
-): void {
+  };
+  readonly fail: (msg: string) => never;
+}
+
+/**
+ * Shared handler for prompts lint/validation.
+ *
+ * @param params - Handler context with args, logger, and fail callback.
+ */
+export function handleLint({ args, logger, fail }: HandleLintParams): void {
   const { roots, partials, silent } = args;
 
   const { discovered, results } = runLintPipeline({ roots, partials });
@@ -39,11 +49,10 @@ export function handleLint(
   const diagnostics = results.flatMap((result) => result.diagnostics);
 
   for (const diag of diagnostics) {
-    if (diag.level === "error") {
-      logger.error(diag.message);
-    } else {
-      logger.warn(diag.message);
-    }
+    match(diag.level)
+      .with("error", () => logger.error(diag.message))
+      .with("warn", () => logger.warn(diag.message))
+      .exhaustive();
   }
 
   const errorCount = diagnostics.filter((d) => d.level === "error").length;
@@ -71,6 +80,6 @@ export default command({
   description: "Validate .prompt files for schema/template mismatches",
   options: lintArgs,
   handler(ctx) {
-    handleLint(ctx.args, ctx.logger, ctx.fail);
+    handleLint({ args: ctx.args, logger: ctx.logger, fail: ctx.fail });
   },
 });

package/src/commands/prompts/setup.ts

@@ -57,13 +57,7 @@ export default command({
       const currentRecs = (extensions.recommendations ?? []) as string[];
       const extensionId = "sissel.shopify-liquid";
 
-      // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-      const recommendations: string[] = (() => {
-        if (currentRecs.includes(extensionId)) {
-          return currentRecs;
-        }
-        return [...currentRecs, extensionId];
-      })();
+      const recommendations = ensureRecommendation(currentRecs, extensionId);
       const updatedExtensions = {
         ...extensions,
         recommendations,
@@ -80,24 +74,12 @@ export default command({
 
     if (shouldGitignore) {
       const gitignorePath = resolve(GITIGNORE_FILE);
-      // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-      const existing: string = (() => {
-        if (existsSync(gitignorePath)) {
-          return readFileSync(gitignorePath, "utf8");
-        }
-        return "";
-      })();
+      const existing = readFileOrEmpty(gitignorePath);
 
       if (existing.includes(GITIGNORE_ENTRY)) {
         ctx.logger.info(`${GITIGNORE_ENTRY} already in ${gitignorePath}`);
       } else {
-        // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-        const separator: string = (() => {
-          if (existing.length > 0 && !existing.endsWith("\n")) {
-            return "\n";
-          }
-          return "";
-        })();
+        const separator = trailingSeparator(existing);
         const block = `${separator}\n# Generated prompt client (created by \`funkai prompts generate\`)\n${GITIGNORE_ENTRY}\n`;
         writeFileSync(gitignorePath, `${existing}${block}`, "utf8");
         ctx.logger.success(`Added ${GITIGNORE_ENTRY} to ${gitignorePath}`);
@@ -141,9 +123,49 @@ export default command({
   },
 });
 
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
+/** @private */
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+/** @private */
+function ensureRecommendation(current: readonly string[], id: string): string[] {
+  if (current.includes(id)) {
+    return [...current];
+  }
+  return [...current, id];
+}
+
+/** @private */
+function readFileOrEmpty(filePath: string): string {
+  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading file from CLI discovery
+  if (existsSync(filePath)) {
+    return readFileSync(filePath, "utf8");
+  }
+  return "";
+}
+
+/** @private */
+function trailingSeparator(content: string): string {
+  if (content.length > 0 && !content.endsWith("\n")) {
+    return "\n";
+  }
+  return "";
+}
+
 /**
- * Read a JSON file, returning an empty object if it doesn't exist
- * or contains invalid JSON.
+ * Read a JSON file, returning an empty object if it doesn't exist.
+ * Throws if the file exists but contains invalid JSON, preventing
+ * silent data loss from overwriting malformed config files.
+ *
+ * @private
  */
 function readJsonFile(filePath: string): Record<string, unknown> {
   // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: tsconfig path from CLI discovery
@@ -151,11 +173,15 @@ function readJsonFile(filePath: string): Record<string, unknown> {
     return {};
   }
 
+  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading tsconfig file
+  const content = readFileSync(filePath, "utf8");
   try {
-    // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: reading tsconfig file
-    const content = readFileSync(filePath, "utf8");
     return JSON.parse(content) as Record<string, unknown>;
-  } catch {
-    return {};
+  } catch (error) {
+    throw new Error(
+      `Failed to parse ${filePath}: ${errorMessage(error)}. ` +
+        "Fix the JSON syntax or remove the file before running setup.",
+      { cause: error },
+    );
   }
 }

package/src/commands/validate.ts

@@ -13,7 +13,7 @@ export default command({
       ctx.logger.info("Running prompts validation...");
     }
 
-    handleLint(ctx.args, ctx.logger, ctx.fail);
+    handleLint({ args: ctx.args, logger: ctx.logger, fail: ctx.fail });
 
     // --- Future: agents validation ---
 

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

@@ -10,7 +10,7 @@ describe(flattenPartials, () => {
   describe("param parsing", () => {
     it("resolves a single literal param", () => {
       const template = "{% render 'identity', role: 'Bot' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("You are Bot, .");
@@ -19,14 +19,14 @@ describe(flattenPartials, () => {
 
     it("resolves multiple literal params", () => {
       const template = "{% render 'identity', role: 'TestBot', desc: 'a test agent' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [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]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are , helper.");
       expect(result).not.toContain("{% render");
@@ -35,7 +35,7 @@ describe(flattenPartials, () => {
     it("throws when the first param uses a variable reference", () => {
       const template = "{% render 'identity', role: agentRole, desc: 'helper' %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow(
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
         'parameter "role" uses a variable reference',
       );
     });
@@ -43,7 +43,7 @@ describe(flattenPartials, () => {
     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(
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
         'parameter "desc" uses a variable reference',
       );
     });
@@ -51,19 +51,21 @@ describe(flattenPartials, () => {
     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");
+      expect(() => flattenPartials({ template, partialsDirs: [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]);
+      const result = flattenPartials({ template, partialsDirs: [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]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Test Bot, a helpful assistant.");
     });
@@ -72,12 +74,12 @@ describe(flattenPartials, () => {
   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);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("parses a render tag with no params", () => {
       const template = "{% render 'identity' %}\n\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("</identity>");
@@ -86,7 +88,7 @@ describe(flattenPartials, () => {
 
     it("parses left-only whitespace trim {%-", () => {
       const template = "{%- render 'identity', role: 'Bot', desc: 'helper' %}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("{%-");
@@ -94,7 +96,7 @@ describe(flattenPartials, () => {
 
     it("parses right-only whitespace trim -%}", () => {
       const template = "{% render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("-%}");
@@ -102,7 +104,7 @@ describe(flattenPartials, () => {
 
     it("parses both-side whitespace trim {%- -%}", () => {
       const template = "{%- render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("{%");
@@ -110,19 +112,19 @@ describe(flattenPartials, () => {
 
     it("handles extra whitespace between {% and render keyword", () => {
       const template = "{%    render 'identity', role: 'Bot', desc: 'helper' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [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);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("does not match malformed render tags without closing %}", () => {
       const template = "{% render 'identity'";
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
   });
 
@@ -130,7 +132,7 @@ describe(flattenPartials, () => {
     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]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("You are TestBot, a test agent.");
@@ -141,7 +143,7 @@ describe(flattenPartials, () => {
 
     it("flattens constraints partial with no bindings", () => {
       const template = "{% render 'constraints' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<constraints>");
       expect(result).toContain("</constraints>");
@@ -153,7 +155,7 @@ describe(flattenPartials, () => {
 
     it("flattens tools partial with no bindings (else branch)", () => {
       const template = "{% render 'tools' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<tools>");
       expect(result).toContain("</tools>");
@@ -168,7 +170,7 @@ describe(flattenPartials, () => {
         "{% render 'identity', role: 'Agent', desc: 'analyzer' %}",
       ].join("\n");
 
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).toContain("You are Agent, analyzer.");
@@ -178,7 +180,7 @@ describe(flattenPartials, () => {
     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]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toMatch(/^# System Prompt/);
       expect(result).toContain("You are Bot, helper.");
@@ -188,13 +190,13 @@ describe(flattenPartials, () => {
     it("throws when partial file does not exist", () => {
       const template = "{% render 'nonexistent' %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow();
+      expect(() => flattenPartials({ template, partialsDirs: [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]);
+      const result = flattenPartials({ template, partialsDirs: [emptyDir, PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, test.");
     });
@@ -203,13 +205,13 @@ describe(flattenPartials, () => {
   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);
+      expect(flattenPartials({ template, partialsDirs: [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]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("{% if show_identity %}");
       expect(result).toContain("{% endif %}");
@@ -219,12 +221,12 @@ describe(flattenPartials, () => {
     });
 
     it("returns empty string unchanged", () => {
-      expect(flattenPartials("", [PARTIALS_DIR])).toBe("");
+      expect(flattenPartials({ template: "", partialsDirs: [PARTIALS_DIR] })).toBe("");
     });
 
     it("returns whitespace-only template unchanged", () => {
       const ws = "   \n\n   ";
-      expect(flattenPartials(ws, [PARTIALS_DIR])).toBe(ws);
+      expect(flattenPartials({ template: ws, partialsDirs: [PARTIALS_DIR] })).toBe(ws);
     });
   });
 });