selftune 0.2.14 → 0.2.16

package/apps/local-dashboard/dist/index.html

@@ -5,10 +5,10 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>selftune — Dashboard</title>
     <link rel="icon" type="image/png" href="/favicon.png" />
-    <script type="module" crossorigin src="/assets/index-DIrdlu2_.js"></script>
+    <script type="module" crossorigin src="/assets/index-DOu3iLD9.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-Dw2cE7zH.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-CKkiCskZ.js">
-    <link rel="modulepreload" crossorigin href="/assets/vendor-ui-7xD7fNEU.js">
+    <link rel="modulepreload" crossorigin href="/assets/vendor-ui-DIwlrGlb.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-table-pHbDxq36.js">
     <link rel="stylesheet" crossorigin href="/assets/index-BMIS6uUh.css">
   </head>

package/bin/run-hook.cjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Hook runner — executes a TypeScript hook script via Bun.
+ *
+ * Usage: node run-hook.cjs <path-to-hook.ts>
+ *
+ * Stdin is piped through to the hook script (Claude Code sends JSON on stdin).
+ * Exit code is propagated from the hook. If bun is not found, exits 0
+ * (fail-open: hooks must never block Claude).
+ *
+ * Note: selftune hooks depend on Bun-specific APIs (Bun.stdin.text(),
+ * Bun.spawn()) and cannot run under tsx/node. The runner exists so that
+ * hook commands use `node run-hook.cjs` (universally available) as the
+ * entry point, avoiding a hard dependency on bun being in PATH for the
+ * shell that Claude Code invokes.
+ */
+
+const { execFileSync } = require("child_process");
+const hookScript = process.argv[2];
+
+if (!hookScript) {
+  // No script specified — fail-open
+  process.exit(0);
+}
+
+try {
+  execFileSync("bun", ["run", hookScript], { stdio: "inherit" });
+  process.exit(0);
+} catch (e) {
+  // Hook exited non-zero → propagate (e.g. exit 2 = block in PreToolUse)
+  if (e.status != null) {
+    process.exit(e.status);
+  }
+  // bun not found (ENOENT) — fail-open
+  process.exit(0);
+}

package/cli/selftune/analytics.ts

@@ -24,6 +24,7 @@ import { join } from "node:path";
 
 import { SELFTUNE_CONFIG_DIR, SELFTUNE_CONFIG_PATH } from "./constants.js";
 import type { SelftuneConfig } from "./types.js";
+import { CLIError } from "./utils/cli-error.js";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -280,11 +281,11 @@ https://github.com/selftune-dev/selftune#telemetry`);
       try {
         writeConfigField("analytics_disabled", true);
       } catch {
-        console.error(
-          "Failed to disable telemetry: cannot write ~/.selftune/config.json. " +
-            "Try checking file permissions, or set SELFTUNE_NO_ANALYTICS=1.",
+        throw new CLIError(
+          "Failed to disable telemetry: cannot write ~/.selftune/config.json",
+          "OPERATION_FAILED",
+          "Check file permissions, or set SELFTUNE_NO_ANALYTICS=1",
         );
-        process.exit(1);
       }
       console.log("Telemetry disabled. No anonymous usage data will be sent.");
       console.log("You can re-enable with: selftune telemetry enable");
@@ -294,11 +295,11 @@ https://github.com/selftune-dev/selftune#telemetry`);
       try {
         writeConfigField("analytics_disabled", false);
       } catch {
-        console.error(
-          "Failed to enable telemetry: cannot write ~/.selftune/config.json. " +
-            "Try checking file permissions.",
+        throw new CLIError(
+          "Failed to enable telemetry: cannot write ~/.selftune/config.json",
+          "OPERATION_FAILED",
+          "Check file permissions",
         );
-        process.exit(1);
       }
       console.log("Telemetry enabled. Anonymous usage data will be sent.");
       console.log("Disable anytime with: selftune telemetry disable");
@@ -331,10 +332,11 @@ https://github.com/selftune-dev/selftune#telemetry`);
       break;
     }
     default:
-      console.error(
-        `Unknown telemetry subcommand: ${sub}\nRun 'selftune telemetry --help' for usage.`,
+      throw new CLIError(
+        `Unknown telemetry subcommand: ${sub}`,
+        "INVALID_FLAG",
+        "selftune telemetry --help",
       );
-      process.exit(1);
   }
 }
 

package/cli/selftune/badge/badge.ts

@@ -24,6 +24,7 @@ import type {
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../types.js";
+import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import type { BadgeFormat } from "./badge-data.js";
 import { findSkillBadgeData } from "./badge-data.js";
 import { formatBadgeOutput } from "./badge-svg.js";
@@ -58,15 +59,15 @@ export async function cliMain(): Promise<void> {
   }
 
   if (!values.skill) {
-    console.error("Error: --skill is required\n");
-    console.error(HELP);
-    process.exit(1);
+    throw new CLIError("--skill is required", "MISSING_FLAG", "selftune badge --skill <name>");
   }
 
   if (values.format && !VALID_FORMATS.has(values.format as BadgeFormat)) {
-    console.error(`Error: invalid format '${values.format}'. Must be one of: svg, markdown, url\n`);
-    console.error(HELP);
-    process.exit(1);
+    throw new CLIError(
+      `Invalid format '${values.format}'. Must be one of: svg, markdown, url`,
+      "INVALID_FLAG",
+      "selftune badge --skill <name> --format svg",
+    );
   }
 
   const format: BadgeFormat =
@@ -90,8 +91,11 @@ export async function cliMain(): Promise<void> {
   // Find skill badge data
   const badgeData = findSkillBadgeData(result, values.skill);
   if (!badgeData) {
-    console.error(`Skill not found: ${values.skill}`);
-    process.exit(1);
+    throw new CLIError(
+      `Skill not found: ${values.skill}`,
+      "MISSING_DATA",
+      "selftune status --json  # list available skill names",
+    );
   }
 
   // Generate output
@@ -106,5 +110,5 @@ export async function cliMain(): Promise<void> {
 }
 
 if (import.meta.main) {
-  cliMain();
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/canonical-export.ts

@@ -26,13 +26,14 @@ import {
   readCanonicalRecords,
   serializeCanonicalRecords,
 } from "./utils/canonical-log.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
 
 function exitWithUsage(message?: string): never {
-  if (message) console.error(`[ERROR] ${message}`);
-  console.error(
-    `Usage: selftune export-canonical [--out FILE] [--platform NAME] [--record-kind KIND] [--pretty] [--log FILE] [--projects-dir PATH] [--push-payload]`,
+  throw new CLIError(
+    message ?? "Invalid usage.",
+    "INVALID_FLAG",
+    "Usage: selftune export-canonical [--out FILE] [--platform NAME] [--record-kind KIND] [--pretty] [--log FILE] [--projects-dir PATH] [--push-payload]",
   );
-  process.exit(1);
 }
 
 function validatePlatform(value: string | undefined): CanonicalPlatform | undefined {
@@ -195,7 +196,6 @@ if (import.meta.main) {
   try {
     cliMain();
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    exitWithUsage(message);
+    handleCLIError(error);
   }
 }

package/cli/selftune/contribute/contribute.ts

@@ -12,6 +12,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 
 import { CONTRIBUTIONS_DIR } from "../constants.js";
+import { handleCLIError } from "../utils/cli-error.js";
 import { assembleBundle } from "./bundle.js";
 import { sanitizeBundle } from "./sanitize.js";
 
@@ -211,5 +212,5 @@ function submitToGitHub(json: string, outputPath: string): boolean {
 }
 
 if (import.meta.main) {
-  await cliMain();
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/cron/setup.ts

@@ -18,6 +18,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 
+import { handleCLIError } from "../utils/cli-error.js";
+
 // ---------------------------------------------------------------------------
 // Types & constants
 // ---------------------------------------------------------------------------
@@ -262,5 +264,5 @@ Subcommands:
 }
 
 if (import.meta.main) {
-  await cliMain();
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/dashboard-contract.ts

@@ -242,4 +242,14 @@ export interface SkillReportResponse extends SkillReportPayload {
   };
   prompt_samples: PromptSample[];
   session_metadata: SessionMeta[];
+  description_quality?: {
+    composite: number;
+    criteria: {
+      length: number;
+      trigger_context: number;
+      vagueness: number;
+      specificity: number;
+      not_just_name: number;
+    };
+  } | null;
 }

package/cli/selftune/dashboard.ts

@@ -7,6 +7,8 @@
  *   selftune dashboard --serve      — Deprecated alias for the default behavior
  */
 
+import { CLIError } from "./utils/cli-error.js";
+
 export async function cliMain(): Promise<void> {
   const args = process.argv.slice(2);
 
@@ -22,11 +24,11 @@ Usage:
   }
 
   if (args.includes("--export") || args.includes("--out")) {
-    console.error("Legacy dashboard export was removed.");
-    console.error(
+    throw new CLIError(
+      "Legacy dashboard export was removed.",
+      "INVALID_FLAG",
       "Use `selftune dashboard` to run the SPA locally, then share a route or screenshot instead.",
     );
-    process.exit(1);
   }
 
   const portIdx = args.indexOf("--port");
@@ -34,8 +36,11 @@ Usage:
   if (portIdx !== -1) {
     const parsed = Number.parseInt(args[portIdx + 1], 10);
     if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
-      console.error(`Invalid port "${args[portIdx + 1]}": must be an integer between 1 and 65535.`);
-      process.exit(1);
+      throw new CLIError(
+        `Invalid port "${args[portIdx + 1]}": must be an integer between 1 and 65535.`,
+        "INVALID_FLAG",
+        "Provide a port number between 1 and 65535 (e.g., --port 3141).",
+      );
     }
     port = parsed;
   }

package/cli/selftune/eval/baseline.ts

@@ -11,6 +11,7 @@
 import { parseArgs } from "node:util";
 
 import type { BaselineResult, EvalEntry } from "../types.js";
+import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import { callLlm } from "../utils/llm-call.js";
 import { buildTriggerCheckPrompt, parseTriggerResponse } from "../utils/trigger-check.js";
 
@@ -166,8 +167,11 @@ Options:
   }
 
   if (!values.skill || !values["skill-path"]) {
-    console.error("[ERROR] --skill and --skill-path are required");
-    process.exit(1);
+    throw new CLIError(
+      "--skill and --skill-path are required",
+      "MISSING_FLAG",
+      "selftune grade baseline --skill <name> --skill-path <path>",
+    );
   }
 
   const { existsSync, readFileSync } = await import("node:fs");
@@ -175,8 +179,11 @@ Options:
   // Read skill description
   const skillPath = values["skill-path"];
   if (!existsSync(skillPath)) {
-    console.error(`[ERROR] SKILL.md not found at ${skillPath}`);
-    process.exit(1);
+    throw new CLIError(
+      `SKILL.md not found at ${skillPath}`,
+      "FILE_NOT_FOUND",
+      "Provide a valid --skill-path pointing to SKILL.md",
+    );
   }
   const skillDescription = readFileSync(skillPath, "utf-8");
 
@@ -204,27 +211,19 @@ Options:
   const { detectAgent } = await import("../utils/llm-call.js");
   const requestedAgent = values.agent;
   if (requestedAgent && !Bun.which(requestedAgent)) {
-    console.error(
-      JSON.stringify({
-        level: "error",
-        code: "agent_not_in_path",
-        message: `Agent CLI '${requestedAgent}' not found in PATH.`,
-        action: "Install it or omit --agent to use auto-detection.",
-      }),
+    throw new CLIError(
+      `Agent CLI '${requestedAgent}' not found in PATH`,
+      "AGENT_NOT_FOUND",
+      "Install it or omit --agent to use auto-detection",
     );
-    process.exit(1);
   }
   const agent = requestedAgent ?? detectAgent();
   if (!agent) {
-    console.error(
-      JSON.stringify({
-        level: "error",
-        code: "agent_not_found",
-        message: "No agent CLI (claude/codex/opencode) found in PATH.",
-        action: "Install Claude Code, Codex, or OpenCode.",
-      }),
+    throw new CLIError(
+      "No agent CLI (claude/codex/opencode) found in PATH",
+      "AGENT_NOT_FOUND",
+      "Install Claude Code, Codex, or OpenCode",
     );
-    process.exit(1);
   }
 
   const result = await measureBaseline({
@@ -239,14 +238,5 @@ Options:
 }
 
 if (import.meta.main) {
-  cliMain().catch((err) => {
-    console.error(
-      JSON.stringify({
-        level: "fatal",
-        message: err instanceof Error ? err.message : String(err),
-        stack: err instanceof Error ? err.stack : undefined,
-      }),
-    );
-    process.exit(1);
-  });
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/eval/hooks-to-evals.ts

@@ -36,6 +36,7 @@ import type {
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../types.js";
+import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import { detectAgent } from "../utils/llm-call.js";
 import {
   filterActionableQueryRecords,
@@ -409,18 +410,27 @@ export async function cliMain(): Promise<void> {
   // --- Synthetic mode: generate evals from SKILL.md via LLM ---
   if (values.synthetic) {
     if (!values.skill) {
-      console.error("[ERROR] --skill required with --synthetic");
-      process.exit(1);
+      throw new CLIError(
+        "--skill required with --synthetic",
+        "MISSING_FLAG",
+        "selftune evals --synthetic --skill <name> --skill-path <path>",
+      );
     }
     if (!values["skill-path"]) {
-      console.error("[ERROR] --skill-path required with --synthetic");
-      process.exit(1);
+      throw new CLIError(
+        "--skill-path required with --synthetic",
+        "MISSING_FLAG",
+        "selftune evals --synthetic --skill <name> --skill-path <path>",
+      );
     }
 
     const agent = detectAgent();
     if (!agent) {
-      console.error("[ERROR] No agent CLI found (claude/codex/opencode). Install one first.");
-      process.exit(1);
+      throw new CLIError(
+        "No agent CLI found (claude/codex/opencode)",
+        "AGENT_NOT_FOUND",
+        "Install one of the supported agent CLIs",
+      );
     }
 
     const maxPerSide = Number.parseInt(values.max ?? "50", 10);
@@ -479,8 +489,11 @@ export async function cliMain(): Promise<void> {
   }
 
   if (!values.skill) {
-    console.error("[ERROR] --skill required (or use --list-skills)");
-    process.exit(1);
+    throw new CLIError(
+      "--skill required (or use --list-skills)",
+      "MISSING_FLAG",
+      "selftune evals --skill <name> or selftune evals --list-skills",
+    );
   }
 
   if (values.stats) {
@@ -508,8 +521,5 @@ export async function cliMain(): Promise<void> {
 }
 
 if (import.meta.main) {
-  cliMain().catch((err) => {
-    console.error(err);
-    process.exit(1);
-  });
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/eval/import-skillsbench.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 
 import type { EvalEntry, SkillsBenchTask } from "../types.js";
+import { CLIError, handleCLIError } from "../utils/cli-error.js";
 
 // ---------------------------------------------------------------------------
 // Minimal TOML parser (handles the subset used by SkillsBench task.toml files)
@@ -175,13 +176,19 @@ export function cliMain(): void {
   });
 
   if (!values.dir) {
-    console.error("[ERROR] --dir required (path to SkillsBench corpus directory)");
-    process.exit(1);
+    throw new CLIError(
+      "--dir required (path to SkillsBench corpus directory)",
+      "MISSING_FLAG",
+      "selftune import-skillsbench --dir <path> --skill <name>",
+    );
   }
 
   if (!values.skill) {
-    console.error("[ERROR] --skill required (target skill name)");
-    process.exit(1);
+    throw new CLIError(
+      "--skill required (target skill name)",
+      "MISSING_FLAG",
+      "selftune import-skillsbench --dir <path> --skill <name>",
+    );
   }
 
   const matchStrategy = values["match-strategy"] === "fuzzy" ? "fuzzy" : "exact";
@@ -189,9 +196,11 @@ export function cliMain(): void {
   const tasks = parseSkillsBenchDir(values.dir);
 
   if (tasks.length === 0) {
-    console.error(`[WARN] No tasks found in ${values.dir}/tasks/`);
-    console.error("Expected structure: <dir>/tasks/<task-id>/instruction.md");
-    process.exit(1);
+    throw new CLIError(
+      `No tasks found in ${values.dir}/tasks/`,
+      "MISSING_DATA",
+      "Expected structure: <dir>/tasks/<task-id>/instruction.md",
+    );
   }
 
   console.log(`Parsed ${tasks.length} tasks from ${values.dir}`);
@@ -218,5 +227,9 @@ export function cliMain(): void {
 }
 
 if (import.meta.main) {
-  cliMain();
+  try {
+    cliMain();
+  } catch (err) {
+    handleCLIError(err);
+  }
 }

package/cli/selftune/eval/unit-test-cli.ts

@@ -19,6 +19,7 @@ import { parseArgs } from "node:util";
 
 import { SELFTUNE_CONFIG_DIR } from "../constants.js";
 import type { EvalEntry } from "../types.js";
+import { CLIError } from "../utils/cli-error.js";
 import { callLlm, detectAgent } from "../utils/llm-call.js";
 import { generateUnitTests } from "./generate-unit-tests.js";
 import type { AgentRunner } from "./unit-test.js";
@@ -43,8 +44,11 @@ export async function cliMain(): Promise<void> {
   });
 
   if (!values.skill) {
-    console.error("[ERROR] --skill <name> is required.");
-    process.exit(1);
+    throw new CLIError(
+      "--skill <name> is required",
+      "MISSING_FLAG",
+      "selftune eval unit-test --skill <name>",
+    );
   }
 
   const skillName = values.skill;
@@ -56,8 +60,11 @@ export async function cliMain(): Promise<void> {
   if (values.generate) {
     const agent = detectAgent();
     if (!agent) {
-      console.error("[ERROR] No agent CLI found (claude/codex/opencode). Cannot generate tests.");
-      process.exit(1);
+      throw new CLIError(
+        "No agent CLI found (claude/codex/opencode). Cannot generate tests",
+        "AGENT_NOT_FOUND",
+        "Install one of the supported agent CLIs",
+      );
     }
 
     let skillContent = `Skill: ${skillName}`;
@@ -86,8 +93,7 @@ export async function cliMain(): Promise<void> {
     const tests = await generateUnitTests(skillName, skillContent, evalFailures, llmCaller);
 
     if (tests.length === 0) {
-      console.error("[ERROR] No tests generated. Check agent/LLM availability.");
-      process.exit(1);
+      throw new CLIError("No tests generated", "OPERATION_FAILED", "Check agent/LLM availability");
     }
 
     // Ensure output directory exists
@@ -100,9 +106,11 @@ export async function cliMain(): Promise<void> {
   // Load and run tests
   const tests = loadUnitTests(testsPath);
   if (tests.length === 0) {
-    console.error(`[ERROR] No tests found at ${testsPath}`);
-    console.error("  Use --generate to create tests, or provide --tests <path>.");
-    process.exit(1);
+    throw new CLIError(
+      `No tests found at ${testsPath}`,
+      "FILE_NOT_FOUND",
+      "Use --generate to create tests, or provide --tests <path>",
+    );
   }
 
   console.log(`Loaded ${tests.length} unit tests for skill '${skillName}'`);
@@ -112,8 +120,11 @@ export async function cliMain(): Promise<void> {
   if (values["run-agent"]) {
     const agent = detectAgent();
     if (!agent) {
-      console.error("[ERROR] No agent CLI found. Cannot run agent-based tests.");
-      process.exit(1);
+      throw new CLIError(
+        "No agent CLI found. Cannot run agent-based tests",
+        "AGENT_NOT_FOUND",
+        "Install one of the supported agent CLIs",
+      );
     }
     const modelFlag = values.model;
     agentRunner = async (query: string): Promise<string> => {