@funkai/cli 0.1.0

package/kidd.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "@kidd-cli/core";
+
+export default defineConfig({
+  build: { out: "./dist" },
+  commands: "./src/commands",
+  entry: "./src/index.ts",
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@funkai/cli",
+  "version": "0.1.0",
+  "private": false,
+  "description": "CLI for the funkai AI SDK framework",
+  "keywords": [
+    "ai",
+    "cli",
+    "codegen",
+    "funkai",
+    "prompts",
+    "typescript"
+  ],
+  "homepage": "https://github.com/joggrdocs/funkai/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/joggrdocs/funkai/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joggrdocs/funkai.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "funkai": "./bin/funkai.mjs"
+  },
+  "type": "module",
+  "dependencies": {
+    "@kidd-cli/core": "^0.4.0",
+    "liquidjs": "^10.25.0",
+    "ts-pattern": "^5.9.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6",
+    "@funkai/prompts": "0.1.0"
+  },
+  "devDependencies": {
+    "@kidd-cli/cli": "^0.2.0",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "tsdown": "^0.21.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "dev": "kidd dev",
+    "build": "kidd build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/commands/agents/validate.ts

@@ -0,0 +1,9 @@
+import { command } from "@kidd-cli/core";
+
+export default command({
+  description: "Validate agent configurations",
+  handler(ctx) {
+    ctx.logger.info("Agent validation is not yet available.");
+    ctx.logger.info("This command will validate agent configurations and tool schemas.");
+  },
+});

package/src/commands/generate.ts

@@ -0,0 +1,78 @@
+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";
+
+export default command({
+  description: "Run all code generation across the funkai SDK",
+  args: z.object({
+    out: z.string().describe("Output directory for generated files"),
+    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"),
+  }),
+  handler(ctx) {
+    const { out, roots, partials, silent } = ctx.args;
+
+    // --- Prompts codegen ---
+    if (!silent) {
+      ctx.logger.info("Running prompts code generation...");
+    }
+
+    const { discovered, lintResults, prompts } = runGeneratePipeline({ roots, out, partials });
+
+    if (!silent) {
+      ctx.logger.info(`Found ${discovered} prompt(s)`);
+    }
+
+    for (const prompt of prompts) {
+      if (!silent) {
+        const varCount = prompt.schema.length;
+        const varList = match(varCount > 0)
+          .with(true, () => ` (${prompt.schema.map((v) => v.name).join(", ")})`)
+          .otherwise(() => "");
+        ctx.logger.step(`${prompt.name}${varList}`);
+      }
+    }
+
+    for (const result of lintResults) {
+      for (const diag of result.diagnostics) {
+        if (diag.level === "error") {
+          ctx.logger.error(diag.message);
+        } else {
+          ctx.logger.warn(diag.message);
+        }
+      }
+    }
+
+    if (hasLintErrors([...lintResults])) {
+      ctx.fail("Lint errors found. Fix them before generating.");
+    }
+
+    const outDir = resolve(out);
+    // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: output directory from CLI config
+    mkdirSync(outDir, { recursive: true });
+
+    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");
+    }
+
+    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");
+
+    // --- Future: agents codegen ---
+
+    if (!silent) {
+      ctx.logger.success(`Generated ${prompts.length} prompt module(s) + registry → ${outDir}`);
+    }
+  },
+});

package/src/commands/prompts/create.ts

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { command } from "@kidd-cli/core";
+import { match, P } from "ts-pattern";
+import { z } from "zod";
+
+const TEMPLATE = (name: string) => `---
+name: ${name}
+---
+
+`;
+
+export default command({
+  description: "Create a new .prompt file",
+  args: z.object({
+    name: z.string().describe("Prompt name (kebab-case)"),
+    out: z.string().optional().describe("Output directory (defaults to cwd)"),
+    partial: z.boolean().default(false).describe("Create as a partial in .prompts/partials/"),
+  }),
+  handler(ctx) {
+    const { name, out, partial } = ctx.args;
+    const dir = match({ partial, out })
+      .with({ partial: true }, () => resolve(".prompts/partials"))
+      .with({ out: P.string }, ({ out: outDir }) => resolve(outDir))
+      .otherwise(() => process.cwd());
+    const filePath = resolve(dir, `${name}.prompt`);
+
+    // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: user-provided CLI argument for prompt file creation
+    if (existsSync(filePath)) {
+      ctx.fail(`File already exists: ${filePath}`);
+    }
+
+    // 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");
+
+    ctx.logger.success(`Created ${filePath}`);
+  },
+});

package/src/commands/prompts/generate.ts

@@ -0,0 +1,71 @@
+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";
+
+export default command({
+  description: "Generate TypeScript modules from .prompt files",
+  args: z.object({
+    out: z.string().describe("Output directory for generated files"),
+    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"),
+  }),
+  handler(ctx) {
+    const { out, roots, partials, silent } = ctx.args;
+
+    const { discovered, lintResults, prompts } = runGeneratePipeline({ roots, out, partials });
+
+    if (!silent) {
+      ctx.logger.info(`Found ${discovered} prompt(s)`);
+    }
+
+    if (!silent) {
+      prompts.forEach((prompt) => {
+        const varCount = prompt.schema.length;
+        const varList = match(varCount > 0)
+          .with(true, () => ` (${prompt.schema.map((v) => v.name).join(", ")})`)
+          .otherwise(() => "");
+        ctx.logger.step(`${prompt.name}${varList}`);
+      });
+    }
+
+    lintResults
+      .flatMap((result) => result.diagnostics)
+      .forEach((diag) => {
+        if (diag.level === "error") {
+          ctx.logger.error(diag.message);
+        } else {
+          ctx.logger.warn(diag.message);
+        }
+      });
+
+    if (hasLintErrors([...lintResults])) {
+      ctx.fail("Lint errors found. Fix them before generating.");
+    }
+
+    const outDir = resolve(out);
+    // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: output directory from CLI config
+    mkdirSync(outDir, { recursive: true });
+
+    prompts.forEach((prompt) => {
+      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");
+    });
+
+    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");
+
+    if (!silent) {
+      ctx.logger.success(`Generated ${prompts.length} prompt module(s) + registry → ${outDir}`);
+    }
+  },
+});

package/src/commands/prompts/lint.ts

@@ -0,0 +1,57 @@
+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";
+
+export default command({
+  description: "Validate .prompt files for schema/template mismatches",
+  args: 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"),
+  }),
+  handler(ctx) {
+    const { roots, partials, silent } = ctx.args;
+
+    const { discovered, results } = runLintPipeline({ roots, partials });
+
+    if (!silent) {
+      ctx.logger.info(`Linting ${discovered} prompt(s)...`);
+    }
+
+    const diagnostics = results.flatMap((result) => result.diagnostics);
+
+    diagnostics.forEach((diag) => {
+      if (diag.level === "error") {
+        ctx.logger.error(diag.message);
+      } else {
+        ctx.logger.warn(diag.message);
+      }
+    });
+
+    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`,
+        match(errorCount > 0)
+          .with(true, () => `${errorCount} error(s)`)
+          .otherwise(() => undefined),
+        match(warnCount > 0)
+          .with(true, () => `${warnCount} warning(s)`)
+          .otherwise(() => undefined),
+      ]
+        .filter(Boolean)
+        .join(", ");
+
+      ctx.logger.info(summary);
+    }
+
+    if (hasLintErrors([...results])) {
+      ctx.fail("Lint errors found.");
+    }
+  },
+});

package/src/commands/prompts/setup.ts

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { command } from "@kidd-cli/core";
+import { match } from "ts-pattern";
+
+const VSCODE_DIR = ".vscode";
+const SETTINGS_FILE = "settings.json";
+const EXTENSIONS_FILE = "extensions.json";
+const GITIGNORE_FILE = ".gitignore";
+const TSCONFIG_FILE = "tsconfig.json";
+const GITIGNORE_ENTRY = ".prompts/client/";
+const PROMPTS_ALIAS = "~prompts";
+const PROMPTS_ALIAS_PATH = "./.prompts/client/index.ts";
+
+export default command({
+  description: "Configure VSCode IDE settings for .prompt files",
+  async handler(ctx) {
+    ctx.logger.intro("Prompt SDK — Project Setup");
+
+    const shouldConfigure = await ctx.prompts.confirm({
+      message: "Configure VSCode to treat .prompt files as Markdown with Liquid syntax?",
+      initialValue: true,
+    });
+
+    if (shouldConfigure) {
+      const vscodeDir = resolve(VSCODE_DIR);
+      mkdirSync(vscodeDir, { recursive: true });
+
+      const settingsPath = resolve(vscodeDir, SETTINGS_FILE);
+      const settings = readJsonFile(settingsPath);
+
+      const updatedSettings = {
+        ...settings,
+        "files.associations": {
+          ...((settings["files.associations"] ?? {}) as Record<string, string>),
+          "*.prompt": "markdown",
+        },
+        "liquid.engine": "standard",
+      };
+
+      writeFileSync(settingsPath, JSON.stringify(updatedSettings, null, 2) + "\n", "utf-8");
+      ctx.logger.success(`Updated ${settingsPath}`);
+    }
+
+    const shouldRecommend = await ctx.prompts.confirm({
+      message: "Add Shopify Liquid extension to VSCode recommendations?",
+      initialValue: true,
+    });
+
+    if (shouldRecommend) {
+      const vscodeDir = resolve(VSCODE_DIR);
+      mkdirSync(vscodeDir, { recursive: true });
+
+      const extensionsPath = resolve(vscodeDir, EXTENSIONS_FILE);
+      const extensions = readJsonFile(extensionsPath);
+
+      const currentRecs = (extensions.recommendations ?? []) as string[];
+      const extensionId = "sissel.shopify-liquid";
+
+      const updatedExtensions = {
+        ...extensions,
+        recommendations: currentRecs.includes(extensionId)
+          ? currentRecs
+          : [...currentRecs, extensionId],
+      };
+
+      writeFileSync(extensionsPath, JSON.stringify(updatedExtensions, null, 2) + "\n", "utf-8");
+      ctx.logger.success(`Updated ${extensionsPath}`);
+    }
+
+    const shouldGitignore = await ctx.prompts.confirm({
+      message: "Add .prompts/client/ to .gitignore? (generated client should not be committed)",
+      initialValue: true,
+    });
+
+    if (shouldGitignore) {
+      const gitignorePath = resolve(GITIGNORE_FILE);
+      const existing = match(existsSync(gitignorePath))
+        .with(true, () => readFileSync(gitignorePath, "utf-8"))
+        .otherwise(() => "");
+
+      if (!existing.includes(GITIGNORE_ENTRY)) {
+        const separator = match(existing.length > 0 && !existing.endsWith("\n"))
+          .with(true, () => "\n")
+          .otherwise(() => "");
+        const block = `${separator}\n# Generated prompt client (created by \`funkai prompts generate\`)\n${GITIGNORE_ENTRY}\n`;
+        writeFileSync(gitignorePath, existing + block, "utf-8");
+        ctx.logger.success(`Added ${GITIGNORE_ENTRY} to ${gitignorePath}`);
+      } else {
+        ctx.logger.info(`${GITIGNORE_ENTRY} already in ${gitignorePath}`);
+      }
+    }
+
+    const shouldTsconfig = await ctx.prompts.confirm({
+      message: "Add ~prompts path alias to tsconfig.json?",
+      initialValue: true,
+    });
+
+    if (shouldTsconfig) {
+      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[]>;
+
+      // oxlint-disable-next-line security/detect-object-injection -- safe: PROMPTS_ALIAS is a known constant string
+      if (!existingPaths[PROMPTS_ALIAS]) {
+        const updatedTsconfig = {
+          ...tsconfig,
+          compilerOptions: {
+            ...compilerOptions,
+            paths: {
+              ...existingPaths,
+              // oxlint-disable-next-line security/detect-object-injection -- safe: PROMPTS_ALIAS is a known constant string
+              [PROMPTS_ALIAS]: [PROMPTS_ALIAS_PATH],
+            },
+          },
+        };
+
+        writeFileSync(tsconfigPath, JSON.stringify(updatedTsconfig, null, 2) + "\n", "utf-8");
+        ctx.logger.success(`Added ${PROMPTS_ALIAS} alias to ${tsconfigPath}`);
+      } else {
+        ctx.logger.info(`${PROMPTS_ALIAS} alias already in ${tsconfigPath}`);
+      }
+    }
+
+    ctx.logger.outro("Project setup complete.");
+  },
+});
+
+/**
+ * Read a JSON file, returning an empty object if it doesn't exist
+ * or contains invalid JSON.
+ */
+function readJsonFile(filePath: string): Record<string, unknown> {
+  // oxlint-disable-next-line security/detect-non-literal-fs-filename -- safe: tsconfig path from CLI discovery
+  if (!existsSync(filePath)) {
+    return {};
+  }
+
+  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 {};
+  }
+}

package/src/commands/setup.ts

@@ -0,0 +1,12 @@
+import { command } from "@kidd-cli/core";
+
+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.");
+  },
+});

package/src/commands/validate.ts

@@ -0,0 +1,47 @@
+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";
+
+export default command({
+  description: "Run all validations across the funkai SDK",
+  args: 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"),
+  }),
+  handler(ctx) {
+    const { roots, partials, silent } = ctx.args;
+
+    // --- Prompts validation ---
+    if (!silent) {
+      ctx.logger.info("Running prompts validation...");
+    }
+
+    const { discovered, results } = runLintPipeline({ roots, partials });
+
+    if (!silent) {
+      ctx.logger.info(`Found ${discovered} prompt(s)`);
+    }
+
+    const diagnostics = results.flatMap((result) => result.diagnostics);
+
+    for (const diag of diagnostics) {
+      match(diag.level)
+        .with("error", () => ctx.logger.error(diag.message))
+        .otherwise(() => ctx.logger.warn(diag.message));
+    }
+
+    // --- Future: agents validation ---
+
+    if (hasLintErrors([...results])) {
+      ctx.fail("Validation errors found.");
+    }
+
+    if (!silent) {
+      ctx.logger.success("All validations passed.");
+    }
+  },
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+import { cli } from "@kidd-cli/core";
+
+await cli({
+  description: "CLI for the funkai AI SDK framework",
+  name: "funkai",
+  version: "0.4.0",
+});

package/src/lib/prompts/__tests__/extract-variables.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { extractVariables } from "@/lib/prompts/extract-variables.js";
+
+describe("extractVariables", () => {
+  it("extracts simple variables", () => {
+    expect(extractVariables("{{ name }}")).toEqual(["name"]);
+  });
+
+  it("extracts multiple variables sorted alphabetically", () => {
+    expect(extractVariables("{{ b }} {{ a }}")).toEqual(["a", "b"]);
+  });
+
+  it("extracts the root name from filtered variables", () => {
+    const result = extractVariables("{{ name | upcase }}");
+    expect(result).toEqual(["name"]);
+  });
+
+  it("extracts the root name from nested property access", () => {
+    const result = extractVariables("{{ user.name }}");
+    expect(result).toEqual(["user"]);
+  });
+
+  it("deduplicates repeated variables", () => {
+    expect(extractVariables("{{ x }} {{ x }}")).toEqual(["x"]);
+  });
+
+  it("extracts variables from for loops", () => {
+    const result = extractVariables("{% for item in items %}{{ item }}{% endfor %}");
+    expect(result).toContain("items");
+  });
+
+  it("throws on dangerous variable names", () => {
+    expect(() => extractVariables("{{ __proto__ }}")).toThrow("Dangerous variable name");
+    expect(() => extractVariables("{{ constructor }}")).toThrow("Dangerous variable name");
+    expect(() => extractVariables("{{ prototype }}")).toThrow("Dangerous variable name");
+  });
+
+  it("returns empty array for templates with no variables", () => {
+    expect(extractVariables("Hello world")).toEqual([]);
+  });
+
+  it("extracts variables from conditional blocks", () => {
+    const result = extractVariables("{% if show_header %}Header{% endif %}");
+    expect(result).toContain("show_header");
+  });
+});