@funkai/cli 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funkai/cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "private": false,
   "description": "CLI for the funkai AI SDK framework",
   "keywords": [
@@ -25,19 +25,23 @@
     "funkai": "./bin/funkai.mjs"
   },
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "@kidd-cli/core": "^0.8.2",
+    "@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.5",
+    "@kidd-cli/cli": "^0.4.9",
     "@types/node": "^25.5.0",
     "@vitest/coverage-v8": "^4.1.0",
-    "tsdown": "^0.21.3",
+    "tsdown": "^0.21.4",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   },

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,7 +5,8 @@ import { command } from "@kidd-cli/core";
 import { match, P } from "ts-pattern";
 import { z } from "zod";
 
-const TEMPLATE = (name: string) => `---
+/** @private */
+const createTemplate = (name: string) => `---
 name: ${name}
 ---
 
@@ -34,7 +35,7 @@ export default command({
     // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: directory derived from user CLI path argument
     mkdirSync(dir, { recursive: true });
     // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: file path derived from user CLI path argument
-    writeFileSync(filePath, TEMPLATE(name), "utf-8");
+    writeFileSync(filePath, createTemplate(name), "utf8");
 
     ctx.logger.success(`Created ${filePath}`);
   },

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,20 +56,20 @@ export function handleGenerate(
 
   if (!silent) {
     for (const prompt of prompts) {
-      const varList =
-        prompt.schema.length > 0 ? ` (${prompt.schema.map((v) => v.name).join(", ")})` : "";
+      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)) {
@@ -77,22 +83,30 @@ export function handleGenerate(
   for (const prompt of prompts) {
     const content = generatePromptModule(prompt);
     // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: writing generated module to output directory
-    writeFileSync(resolve(outDir, `${prompt.name}.ts`), content, "utf-8");
+    writeFileSync(resolve(outDir, `${prompt.name}.ts`), content, "utf8");
   }
 
   const registryContent = generateRegistry(prompts);
   // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: writing generated registry to output directory
-  writeFileSync(resolve(outDir, "index.ts"), registryContent, "utf-8");
+  writeFileSync(resolve(outDir, "index.ts"), registryContent, "utf8");
 
   if (!silent) {
     logger.success(`Generated ${prompts.length} prompt module(s) + registry → ${outDir}`);
   }
 }
 
+/** @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,24 +49,24 @@ 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;
   const warnCount = diagnostics.filter((d) => d.level !== "error").length;
 
   if (!silent) {
-    const summary = [
-      `${discovered} prompt(s) linted`,
-      errorCount > 0 ? `${errorCount} error(s)` : undefined,
-      warnCount > 0 ? `${warnCount} warning(s)` : undefined,
-    ]
-      .filter(Boolean)
-      .join(", ");
+    const summaryParts: string[] = [`${discovered} prompt(s) linted`];
+    if (errorCount > 0) {
+      summaryParts.push(`${errorCount} error(s)`);
+    }
+    if (warnCount > 0) {
+      summaryParts.push(`${warnCount} warning(s)`);
+    }
+    const summary = summaryParts.join(", ");
 
     logger.info(summary);
   }
@@ -70,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

@@ -38,7 +38,7 @@ export default command({
         "liquid.engine": "standard",
       };
 
-      writeFileSync(settingsPath, JSON.stringify(updatedSettings, null, 2) + "\n", "utf-8");
+      writeFileSync(settingsPath, `${JSON.stringify(updatedSettings, null, 2)}\n`, "utf8");
       ctx.logger.success(`Updated ${settingsPath}`);
     }
 
@@ -57,14 +57,13 @@ export default command({
       const currentRecs = (extensions.recommendations ?? []) as string[];
       const extensionId = "sissel.shopify-liquid";
 
+      const recommendations = ensureRecommendation(currentRecs, extensionId);
       const updatedExtensions = {
         ...extensions,
-        recommendations: currentRecs.includes(extensionId)
-          ? currentRecs
-          : [...currentRecs, extensionId],
+        recommendations,
       };
 
-      writeFileSync(extensionsPath, JSON.stringify(updatedExtensions, null, 2) + "\n", "utf-8");
+      writeFileSync(extensionsPath, `${JSON.stringify(updatedExtensions, null, 2)}\n`, "utf8");
       ctx.logger.success(`Updated ${extensionsPath}`);
     }
 
@@ -75,15 +74,15 @@ export default command({
 
     if (shouldGitignore) {
       const gitignorePath = resolve(GITIGNORE_FILE);
-      const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+      const existing = readFileOrEmpty(gitignorePath);
 
-      if (!existing.includes(GITIGNORE_ENTRY)) {
-        const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+      if (existing.includes(GITIGNORE_ENTRY)) {
+        ctx.logger.info(`${GITIGNORE_ENTRY} already in ${gitignorePath}`);
+      } else {
+        const separator = trailingSeparator(existing);
         const block = `${separator}\n# Generated prompt client (created by \`funkai prompts generate\`)\n${GITIGNORE_ENTRY}\n`;
-        writeFileSync(gitignorePath, existing + block, "utf-8");
+        writeFileSync(gitignorePath, `${existing}${block}`, "utf8");
         ctx.logger.success(`Added ${GITIGNORE_ENTRY} to ${gitignorePath}`);
-      } else {
-        ctx.logger.info(`${GITIGNORE_ENTRY} already in ${gitignorePath}`);
       }
     }
 
@@ -100,7 +99,9 @@ export default command({
       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]) {
+      if (existingPaths[PROMPTS_ALIAS]) {
+        ctx.logger.info(`${PROMPTS_ALIAS} alias already in ${tsconfigPath}`);
+      } else {
         const updatedTsconfig = {
           ...tsconfig,
           compilerOptions: {
@@ -113,10 +114,8 @@ export default command({
           },
         };
 
-        writeFileSync(tsconfigPath, JSON.stringify(updatedTsconfig, null, 2) + "\n", "utf-8");
+        writeFileSync(tsconfigPath, `${JSON.stringify(updatedTsconfig, null, 2)}\n`, "utf8");
         ctx.logger.success(`Added ${PROMPTS_ALIAS} alias to ${tsconfigPath}`);
-      } else {
-        ctx.logger.info(`${PROMPTS_ALIAS} alias already in ${tsconfigPath}`);
       }
     }
 
@@ -124,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
@@ -134,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, "utf-8");
     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__/extract-variables.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import { extractVariables } from "@/lib/prompts/extract-variables.js";
 
-describe("extractVariables", () => {
+describe(extractVariables, () => {
   it("extracts simple variables", () => {
     expect(extractVariables("{{ name }}")).toEqual(["name"]);
   });