cue-ai 0.4.0 → 0.5.0

package/src/commands/ai-score.e2e.test.ts

@@ -0,0 +1,113 @@
+/**
+ * E2e tests for `cue ai` and `cue score`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+const CUE_BIN = join(import.meta.dir, "../index.ts");
+
+function cue(args: string[]): { status: number; stdout: string; stderr: string } {
+  const res = spawnSync("bun", ["run", CUE_BIN, ...args], {
+    encoding: "utf8",
+    timeout: 15000,
+  });
+  return { status: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+describe("cue ai", () => {
+  test("matches python-api for python/fastapi description", () => {
+    const res = cue(["ai", "python fastapi sqlalchemy"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("python-api");
+  });
+
+  test("matches rust for rust/cargo description", () => {
+    const res = cue(["ai", "rust cargo async cli tool"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("rust");
+  });
+
+  test("matches frontend for react/tailwind description", () => {
+    const res = cue(["ai", "react tailwind vite frontend"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("frontend");
+  });
+
+  test("matches nextjs for next.js description", () => {
+    const res = cue(["ai", "next.js app router server components"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("nextjs");
+  });
+
+  test("matches go-api for golang description", () => {
+    const res = cue(["ai", "golang gin api"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("go-api");
+  });
+
+  test("matches video for ffmpeg/video description", () => {
+    const res = cue(["ai", "video ffmpeg frames"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("video");
+  });
+
+  test("shows help with no args", () => {
+    const res = cue(["ai"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("Usage");
+  });
+
+  test("handles no-match gracefully", () => {
+    const res = cue(["ai", "xyznonexistent"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("No matching");
+  });
+});
+
+describe("cue score", () => {
+  test("scores a specific profile", () => {
+    const res = cue(["score", "--profile", "core"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("core");
+    expect(res.stdout).toContain("/100");
+  });
+
+  test("--all shows all profiles ranked", () => {
+    const res = cue(["score", "--all"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("Profile Scores");
+    expect(res.stdout).toContain("core");
+    expect(res.stdout).toContain("backend");
+  });
+
+  test("--json returns valid JSON", () => {
+    const res = cue(["score", "--profile", "rust", "--json"]);
+    expect(res.status).toBe(0);
+    const data = JSON.parse(res.stdout);
+    expect(data.profile).toBe("rust");
+    expect(data.grade).toMatch(/^[A-F][+-]?$/);
+    expect(data.score).toBeGreaterThanOrEqual(0);
+    expect(data.score).toBeLessThanOrEqual(100);
+    expect(data.tokens).toBeGreaterThan(0);
+  });
+
+  test("--markdown outputs shields.io badge", () => {
+    const res = cue(["score", "--profile", "backend", "--markdown"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("img.shields.io/badge/cue_score");
+  });
+
+  test("--badge generates SVG file", () => {
+    const res = cue(["score", "--profile", "core", "--badge", "/tmp/cue-test-badge.svg"]);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toContain("Badge saved");
+
+    const { readFileSync, unlinkSync } = require("node:fs");
+    const svg = readFileSync("/tmp/cue-test-badge.svg", "utf8");
+    expect(svg).toContain("<svg");
+    expect(svg).toContain("core");
+    unlinkSync("/tmp/cue-test-badge.svg");
+  });
+});

package/src/commands/ai.ts

@@ -0,0 +1,179 @@
+/**
+ * `cue ai <description>` — create a profile from natural language.
+ *
+ * Matches the description against known profiles and skills in the registry,
+ * then generates a profile.yaml. No external API needed — uses local matching.
+ *
+ * Examples:
+ *   cue ai "fastapi app with postgres and redis"
+ *   cue ai "react frontend with tailwind"
+ *   cue ai "rust cli tool"
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+import { listProfiles } from "../lib/profile-loader";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PROFILES_DIR = join(REPO_ROOT, "profiles");
+const REGISTRY_PATH = join(REPO_ROOT, "docs", "registry", "index.json");
+
+interface MatchedProfile {
+  name: string;
+  score: number;
+  description: string;
+}
+
+// Keywords → profile mapping
+const PROFILE_KEYWORDS: Record<string, string[]> = {
+  "nextjs": ["next", "nextjs", "next.js", "vercel", "app router", "server components", "react ssr"],
+  "frontend": ["react", "vue", "svelte", "frontend", "ui", "tailwind", "vite", "css", "component"],
+  "backend": ["api", "express", "fastify", "hono", "webhook", "rest", "graphql", "node server", "prisma", "drizzle"],
+  "python-api": ["python", "fastapi", "django", "flask", "sqlalchemy", "alembic", "uvicorn", "pytest", "pip"],
+  "rust": ["rust", "cargo", "tokio", "async rust", "cli tool", "systems", "wasm"],
+  "go-api": ["go", "golang", "gin", "echo", "chi", "gorm", "goroutine"],
+  "medusa-dev": ["medusa", "ecommerce", "storefront", "shop", "cart", "checkout"],
+  "cybersecurity": ["security", "pentest", "forensics", "dfir", "red team", "blue team", "vulnerability"],
+  "creative-media": ["image", "video", "design", "brand", "visual", "photoshoot", "asset"],
+  "video": ["video", "ffmpeg", "gif", "frames", "transcription", "whisper"],
+  "docs-writer": ["docs", "documentation", "markdown", "obsidian", "writing", "blog"],
+  "readme-writer": ["readme", "svg", "badge", "github profile"],
+  "research": ["research", "paper", "literature", "citation", "academic"],
+  "threejs": ["three.js", "threejs", "3d", "webgl", "shader", "scene"],
+  "coolify": ["coolify", "deploy", "self-host", "vps"],
+  "hostinger": ["hostinger", "dns", "domain", "hosting"],
+  "marketing": ["marketing", "seo", "copywriting", "growth", "conversion", "brand"],
+  "fleet-control": ["multi-agent", "colony", "parallel", "orchestration"],
+  "nvidia": ["nvidia", "gpu", "cuda", "cuopt", "routing", "optimization"],
+  "affiliate": ["affiliate", "link", "commission", "tracking"],
+};
+
+function matchProfiles(description: string): MatchedProfile[] {
+  const desc = description.toLowerCase();
+  const results: MatchedProfile[] = [];
+
+  for (const [profile, keywords] of Object.entries(PROFILE_KEYWORDS)) {
+    let score = 0;
+    for (const kw of keywords) {
+      if (desc.includes(kw)) score += kw.split(" ").length; // multi-word matches score higher
+    }
+    if (score > 0) {
+      // Load profile description
+      let profileDesc = "";
+      try {
+        const yaml = readFileSync(join(PROFILES_DIR, profile, "profile.yaml"), "utf8");
+        const parsed = parseYaml(yaml);
+        profileDesc = parsed.description ?? "";
+      } catch {}
+      results.push({ name: profile, score, description: profileDesc });
+    }
+  }
+
+  return results.sort((a, b) => b.score - a.score);
+}
+
+export async function run(args: string[]): Promise<number> {
+  if (args.includes("-h") || args.includes("--help") || args.length === 0) {
+    process.stdout.write(`cue ai — create a profile from natural language description
+
+Usage:
+  cue ai "fastapi app with postgres and redis"
+  cue ai "react frontend with tailwind and testing"
+  cue ai "rust cli tool with async"
+
+Options:
+  --name <name>    Profile name (auto-generated if not set)
+  --apply          Create the profile and pin it immediately
+`);
+    return 0;
+  }
+
+  const apply = args.includes("--apply");
+  const nameIdx = args.indexOf("--name");
+  const customName = nameIdx >= 0 ? args[nameIdx + 1] : null;
+  const description = args.filter(a => !a.startsWith("-") && a !== customName).join(" ");
+
+  if (!description) {
+    process.stderr.write("Provide a description: cue ai \"your stack description\"\n");
+    return 1;
+  }
+
+  const bold = (s: string) => `\x1b[1m${s}\x1b[0m`;
+  const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+  const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+
+  // Match against known profiles
+  const matches = matchProfiles(description);
+
+  if (matches.length === 0) {
+    process.stdout.write(`No matching profiles for: "${description}"\n`);
+    process.stdout.write(`Try: cue list  to see available profiles\n`);
+    return 0;
+  }
+
+  const best = matches[0]!;
+
+  // If exact match with high confidence, suggest using it directly
+  if (matches.length === 1 || best.score >= 3) {
+    process.stdout.write(`\n  ${green("✓")} Best match: ${bold(best.name)}\n`);
+    process.stdout.write(`    ${dim(best.description)}\n\n`);
+
+    if (matches.length > 1) {
+      process.stdout.write(`  Also considered:\n`);
+      for (const m of matches.slice(1, 4)) {
+        process.stdout.write(`    ${m.name} ${dim(`(${m.description.slice(0, 60)}...)`)}\n`);
+      }
+      process.stdout.write("\n");
+    }
+
+    if (apply) {
+      writeFileSync(join(process.cwd(), ".cue-profile"), best.name + "\n");
+      process.stdout.write(`  ${green("✓")} Pinned ${bold(best.name)} to this directory.\n\n`);
+    } else {
+      process.stdout.write(`  Use it:  ${bold(`cue use ${best.name}`)}\n`);
+      process.stdout.write(`  Or:      ${bold(`cue ai "${description}" --apply`)}\n\n`);
+    }
+    return 0;
+  }
+
+  // Multiple weak matches — generate a composite profile
+  const profileName = customName ?? description.replace(/[^a-z0-9]+/gi, "-").toLowerCase().slice(0, 30);
+
+  process.stdout.write(`\n  Generating profile ${bold(profileName)} from:\n`);
+  for (const m of matches.slice(0, 3)) {
+    process.stdout.write(`    • ${m.name} ${dim(`(score: ${m.score})`)}\n`);
+  }
+
+  // Use the highest-scoring match as the base (inherits from it)
+  const inheritsFrom = best.name;
+
+  const profileYaml = {
+    name: profileName,
+    icon: "🤖",
+    description: description,
+    inherits: inheritsFrom,
+    skills: { local: [] as string[] },
+    mcps: [] as string[],
+  };
+
+  const output = stringifyYaml(profileYaml);
+
+  if (apply) {
+    const profileDir = join(PROFILES_DIR, profileName);
+    mkdirSync(profileDir, { recursive: true });
+    writeFileSync(join(profileDir, "profile.yaml"), output);
+    writeFileSync(join(process.cwd(), ".cue-profile"), profileName + "\n");
+    process.stdout.write(`\n  ${green("✓")} Created ${bold(profileName)} (inherits from ${inheritsFrom})\n`);
+    process.stdout.write(`  ${green("✓")} Pinned to this directory.\n`);
+    process.stdout.write(`  Edit: profiles/${profileName}/profile.yaml\n\n`);
+  } else {
+    process.stdout.write(`\n  Generated profile.yaml:\n\n`);
+    process.stdout.write(output.split("\n").map(l => `    ${l}`).join("\n") + "\n\n");
+    process.stdout.write(`  Create it: ${bold(`cue ai "${description}" --apply`)}\n\n`);
+  }
+
+  return 0;
+}

package/src/commands/benchmark.ts

@@ -0,0 +1,258 @@
+/**
+ * `cue benchmark` — measure profile efficiency: token usage, skill coverage,
+ * and tool selection accuracy from session transcripts.
+ *
+ * Usage:
+ *   cue benchmark                    # benchmark active profile
+ *   cue benchmark --profile backend  # benchmark specific profile
+ *   cue benchmark --all              # compare all profiles
+ *   cue benchmark --json             # machine-readable output
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+
+import { resolveProfileForCwd } from "../lib/cwd-resolver";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+interface BenchmarkResult {
+  profile: string;
+  sessions: number;
+  totalTokensIn: number;
+  totalTokensOut: number;
+  avgTokensPerSession: number;
+  skillHits: number;
+  skillMisses: number;
+  hitRate: number;
+  topSkills: { name: string; count: number }[];
+  unusedSkills: string[];
+  estimatedCost: number;
+}
+
+function scanSessions(profileName: string): BenchmarkResult {
+  const projectsDir = join(homedir(), ".claude", "projects");
+  const result: BenchmarkResult = {
+    profile: profileName,
+    sessions: 0,
+    totalTokensIn: 0,
+    totalTokensOut: 0,
+    avgTokensPerSession: 0,
+    skillHits: 0,
+    skillMisses: 0,
+    hitRate: 0,
+    topSkills: [],
+    unusedSkills: [],
+    estimatedCost: 0,
+  };
+
+  if (!existsSync(projectsDir)) return result;
+
+  const skillUsage = new Map<string, number>();
+  const toolCalls = new Map<string, number>();
+
+  // Scan all session files
+  const projectDirs = readdirSync(projectsDir).filter(d => {
+    const p = join(projectsDir, d);
+    try { return statSync(p).isDirectory(); } catch { return false; }
+  });
+
+  for (const dir of projectDirs) {
+    const fullDir = join(projectsDir, dir);
+    const sessions = readdirSync(fullDir).filter(f => f.endsWith(".jsonl"));
+
+    for (const sess of sessions.slice(-10)) { // only last 10 sessions per project
+      const sessPath = join(fullDir, sess);
+      let content: string;
+      try {
+        // Read only first 20KB — enough for profile stamp + token usage lines
+        const fd = require("node:fs").openSync(sessPath, "r");
+        const buf = Buffer.alloc(20_000);
+        const n = require("node:fs").readSync(fd, buf, 0, 20_000, 0);
+        require("node:fs").closeSync(fd);
+        content = buf.toString("utf8", 0, n);
+      } catch { continue; }
+
+      const lines = content.split("\n").filter(Boolean);
+
+      let hasProfile = false;
+      let sessionTokensIn = 0;
+      let sessionTokensOut = 0;
+
+      for (const line of lines) {
+        try {
+          const msg = JSON.parse(line);
+
+          // Check if this session used our profile
+          if (msg.type === "system" && msg.message?.content) {
+            const content = typeof msg.message.content === "string"
+              ? msg.message.content
+              : JSON.stringify(msg.message.content);
+            if (content.includes(`profile=${profileName}`)) hasProfile = true;
+          }
+
+          // Count tokens
+          if (msg.usage) {
+            sessionTokensIn += msg.usage.input_tokens ?? 0;
+            sessionTokensOut += msg.usage.output_tokens ?? 0;
+          }
+
+          // Track tool usage
+          if (msg.type === "assistant" && msg.message?.content) {
+            const content = Array.isArray(msg.message.content) ? msg.message.content : [];
+            for (const block of content) {
+              if (block.type === "tool_use") {
+                const name = block.name ?? "unknown";
+                toolCalls.set(name, (toolCalls.get(name) ?? 0) + 1);
+              }
+            }
+          }
+
+          // Track skill references
+          if (msg.type === "assistant" || msg.type === "user") {
+            const text = typeof msg.message?.content === "string"
+              ? msg.message.content
+              : JSON.stringify(msg.message?.content ?? "");
+            const skillRefs = text.match(/skills\/[a-z][a-z0-9-]*\/SKILL\.md/g);
+            if (skillRefs) {
+              for (const ref of skillRefs) {
+                const name = ref.replace("skills/", "").replace("/SKILL.md", "");
+                skillUsage.set(name, (skillUsage.get(name) ?? 0) + 1);
+              }
+            }
+          }
+        } catch {}
+      }
+
+      if (hasProfile || profileName === "__all") {
+        result.sessions++;
+        result.totalTokensIn += sessionTokensIn;
+        result.totalTokensOut += sessionTokensOut;
+      }
+    }
+  }
+
+  // Compute metrics
+  result.avgTokensPerSession = result.sessions > 0
+    ? Math.round((result.totalTokensIn + result.totalTokensOut) / result.sessions)
+    : 0;
+
+  // Sonnet pricing: $3/M input, $15/M output
+  result.estimatedCost = (result.totalTokensIn * 3 + result.totalTokensOut * 15) / 1_000_000;
+
+  // Skill hit rate
+  result.topSkills = [...skillUsage.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([name, count]) => ({ name, count }));
+
+  result.skillHits = [...skillUsage.values()].reduce((a, b) => a + b, 0);
+
+  // Load profile to find unused skills
+  try {
+    const profilePath = join(REPO_ROOT, "profiles", profileName, "profile.yaml");
+    if (existsSync(profilePath)) {
+      const prof = parseYaml(readFileSync(profilePath, "utf8"));
+      const declared = (prof.skills?.local ?? []).map((s: string | { id: string }) =>
+        typeof s === "string" ? s.split("/").pop() : s.id.split("/").pop()
+      );
+      result.unusedSkills = declared.filter((s: string) => !skillUsage.has(s));
+    }
+  } catch {}
+
+  return result;
+}
+
+function formatResult(r: BenchmarkResult): string {
+  const lines: string[] = [];
+  lines.push(`\x1b[1m${r.profile}\x1b[0m`);
+  lines.push(`  Sessions analyzed: ${r.sessions}`);
+  lines.push(`  Tokens: ${(r.totalTokensIn / 1000).toFixed(1)}k in / ${(r.totalTokensOut / 1000).toFixed(1)}k out`);
+  lines.push(`  Avg per session: ${(r.avgTokensPerSession / 1000).toFixed(1)}k tokens`);
+  lines.push(`  Estimated cost: $${r.estimatedCost.toFixed(2)}`);
+
+  if (r.topSkills.length > 0) {
+    lines.push(`  Top skills:`);
+    for (const s of r.topSkills.slice(0, 5)) {
+      lines.push(`    ${s.name} (${s.count}×)`);
+    }
+  }
+
+  if (r.unusedSkills.length > 0) {
+    lines.push(`  Unused skills (${r.unusedSkills.length}): ${r.unusedSkills.slice(0, 5).join(", ")}${r.unusedSkills.length > 5 ? " ..." : ""}`);
+  }
+
+  if (r.sessions === 0) {
+    lines.push(`  ⚠️  No sessions found for this profile. Use it first, then benchmark.`);
+  }
+
+  return lines.join("\n");
+}
+
+export async function run(args: string[]): Promise<number> {
+  if (args.includes("-h") || args.includes("--help")) {
+    process.stdout.write(`cue benchmark — measure profile efficiency from session transcripts
+
+Usage:
+  cue benchmark                    Benchmark active profile
+  cue benchmark --profile <name>   Benchmark specific profile
+  cue benchmark --all              Compare all profiles
+  cue benchmark --json             Machine-readable output
+
+Metrics:
+  - Token usage (input/output per session)
+  - Skill hit rate (which skills are actually used)
+  - Unused skills (loaded but never triggered)
+  - Estimated API cost (Sonnet pricing)
+`);
+    return 0;
+  }
+
+  const json = args.includes("--json");
+  const all = args.includes("--all");
+  const profileIdx = args.indexOf("--profile");
+  let profileName: string | null = profileIdx >= 0 ? args[profileIdx + 1] ?? null : null;
+
+  if (!profileName && !all) {
+    try { profileName = await resolveProfileForCwd(process.cwd()); } catch {}
+    if (!profileName) {
+      process.stderr.write("No active profile. Use --profile <name> or --all.\n");
+      return 1;
+    }
+  }
+
+  if (all) {
+    const profilesDir = join(REPO_ROOT, "profiles");
+    const profiles = readdirSync(profilesDir)
+      .filter(d => !d.startsWith("_") && existsSync(join(profilesDir, d, "profile.yaml")));
+
+    const results = profiles.map(p => scanSessions(p)).filter(r => r.sessions > 0);
+    results.sort((a, b) => a.avgTokensPerSession - b.avgTokensPerSession);
+
+    if (json) {
+      process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+    } else {
+      process.stdout.write("🏁 Profile Benchmark (sorted by efficiency)\n\n");
+      for (const r of results) {
+        process.stdout.write(formatResult(r) + "\n\n");
+      }
+      if (results.length === 0) {
+        process.stdout.write("No session data found. Use profiles first, then benchmark.\n");
+      }
+    }
+  } else {
+    const result = scanSessions(profileName!);
+    if (json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      process.stdout.write("🏁 Profile Benchmark\n\n");
+      process.stdout.write(formatResult(result) + "\n");
+    }
+  }
+
+  return 0;
+}

package/src/commands/clean.ts

@@ -0,0 +1,109 @@
+/**
+ * `cue clean` — prune stale runtimes, old cache entries, orphaned symlinks.
+ */
+
+import { existsSync, readdirSync, rmSync, statSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+import { listProfiles } from "../lib/profile-loader";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const RUNTIME_ROOT = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cue", "runtime");
+const CACHE_ROOT = join(REPO_ROOT, "profiles", "_cache", "npx");
+
+export async function run(args: string[]): Promise<number> {
+  if (args.includes("-h") || args.includes("--help")) {
+    process.stdout.write(`cue clean — prune stale runtimes and cache
+
+Usage:
+  cue clean              Show what would be cleaned (dry run)
+  cue clean --force      Actually delete stale entries
+`);
+    return 0;
+  }
+
+  const force = args.includes("--force");
+  const profiles = new Set(await listProfiles());
+  let totalBytes = 0;
+  let totalEntries = 0;
+
+  // 1. Stale runtimes (profiles that no longer exist)
+  if (existsSync(RUNTIME_ROOT)) {
+    for (const dir of readdirSync(RUNTIME_ROOT)) {
+      if (!profiles.has(dir)) {
+        const path = join(RUNTIME_ROOT, dir);
+        const size = getDirSize(path);
+        totalBytes += size;
+        totalEntries++;
+        process.stdout.write(`  ${force ? "🗑️" : "⚠️"}  stale runtime: ${dir} (${formatSize(size)})\n`);
+        if (force) rmSync(path, { recursive: true, force: true });
+      }
+    }
+  }
+
+  // 2. Old cache entries (beyond LRU limit)
+  if (existsSync(CACHE_ROOT)) {
+    const entries = readdirSync(CACHE_ROOT)
+      .map(name => ({ name, mtime: statSync(join(CACHE_ROOT, name)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+
+    const stale = entries.slice(20); // keep 20 most recent
+    for (const entry of stale) {
+      const path = join(CACHE_ROOT, entry.name);
+      const size = getDirSize(path);
+      totalBytes += size;
+      totalEntries++;
+      process.stdout.write(`  ${force ? "🗑️" : "⚠️"}  old cache: ${entry.name.slice(0, 12)}… (${formatSize(size)})\n`);
+      if (force) rmSync(path, { recursive: true, force: true });
+    }
+  }
+
+  // 3. Analytics file size check
+  const analyticsPath = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cue", "analytics.jsonl");
+  if (existsSync(analyticsPath)) {
+    const size = statSync(analyticsPath).size;
+    if (size > 5_000_000) { // > 5MB
+      totalBytes += size - 1_000_000;
+      totalEntries++;
+      process.stdout.write(`  ${force ? "🗑️" : "⚠️"}  large analytics: ${formatSize(size)} (will trim to 1MB)\n`);
+      if (force) {
+        const content = readFileSync(analyticsPath, "utf8");
+        const lines = content.split("\n");
+        const trimmed = lines.slice(-10000).join("\n"); // keep last 10k events
+        require("node:fs").writeFileSync(analyticsPath, trimmed);
+      }
+    }
+  }
+
+  if (totalEntries === 0) {
+    process.stdout.write("  ✅ Nothing to clean. All good.\n");
+  } else if (!force) {
+    process.stdout.write(`\n  ${totalEntries} entries, ~${formatSize(totalBytes)} reclaimable.\n`);
+    process.stdout.write(`  Run: cue clean --force\n`);
+  } else {
+    process.stdout.write(`\n  ✅ Cleaned ${totalEntries} entries, freed ~${formatSize(totalBytes)}.\n`);
+  }
+
+  return 0;
+}
+
+function getDirSize(path: string): number {
+  try {
+    let size = 0;
+    const entries = readdirSync(path, { withFileTypes: true });
+    for (const e of entries) {
+      const p = join(path, e.name);
+      if (e.isDirectory()) size += getDirSize(p);
+      else try { size += statSync(p).size; } catch {}
+    }
+    return size;
+  } catch { return 0; }
+}
+
+function formatSize(bytes: number): string {
+  if (bytes > 1_000_000) return (bytes / 1_000_000).toFixed(1) + " MB";
+  if (bytes > 1_000) return (bytes / 1_000).toFixed(0) + " KB";
+  return bytes + " B";
+}

package/src/commands/completions.ts

@@ -96,6 +96,10 @@ _cue "$@"
 `;
 }
 
+export function completionScript(shell: "bash" | "zsh"): string {
+  return shell === "zsh" ? zshCompletion() : bashCompletion();
+}
+
 export async function run(args: string[]): Promise<number> {
   const shell = args[0] ?? (process.env.SHELL?.includes("zsh") ? "zsh" : "bash");