selftune 0.2.21 → 0.2.22

package/cli/selftune/hooks-shared/git-metadata.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared git metadata extraction for hooks.
+ *
+ * Extracted from duplicated logic in session-stop.ts (branch/remote extraction)
+ * and commit-track.ts (commit detection, remote scrubbing, branch fallback).
+ *
+ * All functions are fail-open: git errors return undefined/null, never throw.
+ */
+
+import { execSync } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Git metadata extracted from a working directory. */
+export interface GitMetadata {
+  branch?: string;
+  repoRemote?: string;
+}
+
+/** Parsed commit information from git output. */
+export interface ParsedCommit {
+  sha?: string;
+  title?: string;
+  branch?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Pre-compiled regex patterns
+// ---------------------------------------------------------------------------
+
+/** Matches git commands that produce commits: commit, merge, cherry-pick, revert. */
+const GIT_COMMIT_CMD_RE = /\bgit\s+(commit|merge|cherry-pick|revert)\b/;
+
+/**
+ * Matches standard git commit output: [branch SHA] title
+ * Supports optional parenthetical like (root-commit).
+ * Branch names can contain word chars, slashes, dots, hyphens, plus signs.
+ */
+const COMMIT_OUTPUT_RE = /\[([\w/.+-]+)(?:\s+\([^)]+\))?\s+([a-f0-9]{7,40})\]\s+(.+)/;
+
+// ---------------------------------------------------------------------------
+// Git metadata extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract git branch and remote URL from a working directory.
+ *
+ * Uses short-timeout execSync calls. Returns partial results if one
+ * command fails (e.g., branch succeeds but remote is not configured).
+ * Returns empty object if cwd is not a git repo.
+ *
+ * @param cwd  Working directory to inspect
+ */
+export function extractGitMetadata(cwd: string): GitMetadata {
+  if (!cwd) return {};
+
+  const result: GitMetadata = {};
+
+  try {
+    result.branch =
+      execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .toString()
+        .trim() || undefined;
+  } catch {
+    /* not a git repo or git not available */
+  }
+
+  try {
+    const rawRemote =
+      execSync("git remote get-url origin", {
+        cwd,
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .toString()
+        .trim() || undefined;
+    if (rawRemote) {
+      result.repoRemote = scrubRemoteUrl(rawRemote);
+    }
+  } catch {
+    /* no remote configured */
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// URL scrubbing
+// ---------------------------------------------------------------------------
+
+/**
+ * Scrub credentials from a git remote URL.
+ *
+ * HTTP(S) URLs have username/password stripped. SSH URLs and other formats
+ * are returned as-is (they don't embed credentials in the URL structure).
+ *
+ * @param rawUrl  Raw remote URL from `git remote get-url`
+ * @returns       Scrubbed URL, or undefined for empty input
+ */
+export function scrubRemoteUrl(rawUrl: string): string | undefined {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    parsed.username = "";
+    parsed.password = "";
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    // SSH or non-URL format -- safe as-is
+    return rawUrl;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Commit detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a command string contains a git commit-producing operation.
+ * Detects: git commit, git merge, git cherry-pick, git revert.
+ */
+export function containsGitCommitCommand(command: string): boolean {
+  return GIT_COMMIT_CMD_RE.test(command);
+}
+
+/**
+ * Parse commit metadata from git's standard output format.
+ *
+ * Expects output like: `[main abc1234] Fix the bug`
+ * or with root-commit: `[main (root-commit) abc1234] Initial commit`
+ *
+ * @param stdout  The stdout from a git commit/merge/cherry-pick/revert command
+ * @returns       Parsed commit info, or null if output doesn't match
+ */
+export function parseCommitFromOutput(stdout: string): ParsedCommit | null {
+  const match = stdout.match(COMMIT_OUTPUT_RE);
+  if (!match) return null;
+
+  return {
+    branch: match[1],
+    sha: match[2],
+    title: match[3].trim(),
+  };
+}

package/cli/selftune/hooks-shared/hook-output.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared output helpers for platform-agnostic hook responses.
+ *
+ * Hooks communicate with their host agent through stdout (context injection),
+ * stderr (advisory messages), and exit codes (allow/block decisions). The
+ * exact format varies by platform — this module abstracts those differences.
+ *
+ * Claude Code conventions (the primary platform):
+ *   - stdout JSON with hookSpecificOutput.additionalContext for context injection
+ *   - stderr for advisory suggestions
+ *   - exit 0 = allow, exit 2 = block with message
+ */
+
+import type { HookPlatform, HookResponse } from "./types.js";
+
+/**
+ * Format a HookResponse for a specific platform's expected output format.
+ *
+ * For Claude Code: produces JSON with hookSpecificOutput wrapper.
+ * For other platforms: produces a simplified JSON response.
+ *
+ * @param response  The platform-agnostic hook response
+ * @param platform  The target platform
+ * @returns         Formatted string ready to write to stdout
+ */
+export function formatResponseForPlatform(response: HookResponse, platform: HookPlatform): string {
+  if (platform === "claude-code" || platform === "codex") {
+    // Claude Code / Codex use hookSpecificOutput wrapper
+    const output: Record<string, unknown> = {};
+
+    if (response.context) {
+      output.hookSpecificOutput = {
+        additionalContext: response.context,
+      };
+    }
+
+    if (response.updated_input) {
+      output.updatedInput = response.updated_input;
+    }
+
+    if (response.decision) {
+      output.decision = response.decision;
+    }
+
+    return JSON.stringify(output);
+  }
+
+  // Generic JSON format for other platforms
+  return JSON.stringify({
+    modified: response.modified,
+    decision: response.decision,
+    message: response.message,
+    context: response.context,
+    updated_input: response.updated_input,
+  });
+}
+
+/**
+ * Write an advisory suggestion to stderr.
+ *
+ * Stderr messages appear as system messages to the host agent in Claude Code.
+ * Other platforms may handle stderr differently, but writing to stderr is
+ * universally safe (it never affects the hook's exit code or stdout response).
+ *
+ * @param message  The suggestion text to display
+ */
+export function writeSuggestion(message: string): void {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Write context injection to stdout.
+ *
+ * For Claude Code, this injects content into Claude's context via the
+ * hookSpecificOutput.additionalContext mechanism. The output is JSON-formatted
+ * to match Claude Code's expected hook output schema.
+ *
+ * @param context  The context string to inject
+ */
+export function writeContext(context: string): void {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        additionalContext: context,
+      },
+    }),
+  );
+}
+
+/**
+ * Exit with a platform-appropriate exit code for allow/block decisions.
+ *
+ * Claude Code convention:
+ *   - exit 0 = allow the tool call
+ *   - exit 2 = block the tool call (with stderr message)
+ *
+ * Other platforms use the same convention unless they specify otherwise.
+ *
+ * @param decision  "allow" or "block"
+ * @param _platform  The target platform (reserved for future per-platform codes)
+ */
+export function exitWithDecision(decision: "allow" | "block", _platform: HookPlatform): never {
+  const code = decision === "block" ? 2 : 0;
+  process.exit(code);
+}

package/cli/selftune/hooks-shared/normalize.ts

@@ -0,0 +1,196 @@
+/**
+ * Normalizers that convert platform-specific hook payloads to UnifiedHookEvent.
+ *
+ * Each platform adapter maps its native payload shape and event names
+ * to the shared UnifiedHookEvent interface. The normalizers are intentionally
+ * lenient — unknown fields are ignored, missing fields become undefined.
+ *
+ * Fail-open: any parsing error returns a minimal event with what we have.
+ */
+
+import type { HookEventType, HookPlatform, UnifiedHookEvent } from "./types.js";
+import { PLATFORM_EVENT_MAP } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Reverse lookup: native event name -> HookEventType
+// ---------------------------------------------------------------------------
+
+/** Build a reverse map from native event string to HookEventType for a platform. */
+function buildReverseLookup(platform: HookPlatform): Map<string, HookEventType> {
+  const forward = PLATFORM_EVENT_MAP[platform];
+  const reverse = new Map<string, HookEventType>();
+  for (const [hookType, nativeName] of Object.entries(forward)) {
+    if (nativeName) {
+      reverse.set(nativeName, hookType as HookEventType);
+    }
+  }
+  return reverse;
+}
+
+const reverseLookups = new Map<HookPlatform, Map<string, HookEventType>>();
+
+/** Resolve a native event type string to the normalized HookEventType. */
+function resolveEventType(
+  platform: HookPlatform,
+  nativeEventType: string,
+): HookEventType | undefined {
+  let lookup = reverseLookups.get(platform);
+  if (!lookup) {
+    lookup = buildReverseLookup(platform);
+    reverseLookups.set(platform, lookup);
+  }
+  return lookup.get(nativeEventType);
+}
+
+// ---------------------------------------------------------------------------
+// Shared field extraction helpers
+// ---------------------------------------------------------------------------
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+function obj(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null ? (v as Record<string, unknown>) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Per-platform field extraction config
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes how to extract prompt and last_message fields from a platform's
+ * payload. Most platforms use the same field names; Claude Code has a
+ * user_prompt fallback, and some use last_assistant_message vs last_message.
+ */
+interface PlatformFieldConfig {
+  /** Default event_type when resolution fails */
+  fallbackEvent: HookEventType;
+  /** Fields to try for prompt (in order, first non-undefined wins) */
+  promptFields: string[];
+  /** Field name for session-end last message */
+  lastMessageField: string;
+  /** Field name for post_tool_use output (e.g., "tool_response" or "tool_output") */
+  toolOutputField: string;
+}
+
+const FIELD_CONFIG: Record<HookPlatform, PlatformFieldConfig> = {
+  "claude-code": {
+    fallbackEvent: "prompt_submit",
+    promptFields: ["prompt", "user_prompt"],
+    lastMessageField: "last_assistant_message",
+    toolOutputField: "tool_response",
+  },
+  codex: {
+    fallbackEvent: "prompt_submit",
+    promptFields: ["prompt"],
+    lastMessageField: "last_assistant_message",
+    toolOutputField: "tool_response",
+  },
+  opencode: {
+    fallbackEvent: "session_end",
+    promptFields: ["prompt"],
+    lastMessageField: "last_message",
+    toolOutputField: "tool_output",
+  },
+  cline: {
+    fallbackEvent: "session_end",
+    promptFields: ["prompt"],
+    lastMessageField: "last_message",
+    toolOutputField: "tool_output",
+  },
+  pi: {
+    fallbackEvent: "session_end",
+    promptFields: ["prompt"],
+    lastMessageField: "last_message",
+    toolOutputField: "tool_output",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Unified normalizer
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a platform-specific hook payload to UnifiedHookEvent.
+ *
+ * This single function replaces per-platform normalizers by using
+ * FIELD_CONFIG to handle platform-specific field names.
+ */
+function normalizeForPlatform(
+  platform: HookPlatform,
+  payload: unknown,
+  eventType: string,
+): UnifiedHookEvent {
+  const raw = obj(payload) ?? {};
+  const config = FIELD_CONFIG[platform];
+  const resolved = resolveEventType(platform, eventType);
+
+  const base: UnifiedHookEvent = {
+    platform,
+    event_type: resolved ?? config.fallbackEvent,
+    session_id: str(raw.session_id) ?? "unknown",
+    cwd: str(raw.cwd),
+    transcript_path: str(raw.transcript_path),
+    raw_payload: payload,
+  };
+
+  if (resolved === "pre_tool_use" || resolved === "post_tool_use") {
+    base.tool_name = str(raw.tool_name);
+    base.tool_input = obj(raw.tool_input);
+    if (resolved === "post_tool_use") {
+      base.tool_output = obj(raw[config.toolOutputField]);
+    }
+  } else if (resolved === "prompt_submit") {
+    for (const field of config.promptFields) {
+      const v = str(raw[field]);
+      if (v) {
+        base.prompt = v;
+        break;
+      }
+    }
+  } else if (resolved === "session_end") {
+    base.last_message = str(raw[config.lastMessageField]);
+  }
+
+  return base;
+}
+
+// ---------------------------------------------------------------------------
+// Public API — named exports for backward compatibility + unified entry point
+// ---------------------------------------------------------------------------
+
+export function normalizeClaudeCode(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("claude-code", payload, eventType);
+}
+
+export function normalizeCodex(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("codex", payload, eventType);
+}
+
+export function normalizeOpenCode(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("opencode", payload, eventType);
+}
+
+export function normalizeCline(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("cline", payload, eventType);
+}
+
+export function normalizePi(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("pi", payload, eventType);
+}
+
+/**
+ * Auto-detect platform and normalize a hook payload to UnifiedHookEvent.
+ *
+ * @param payload          Raw payload (typically parsed from stdin JSON)
+ * @param platform         The host platform
+ * @param nativeEventType  The platform-native event type string
+ */
+export function normalizeHookEvent(
+  payload: unknown,
+  platform: HookPlatform,
+  nativeEventType: string,
+): UnifiedHookEvent {
+  return normalizeForPlatform(platform, payload, nativeEventType);
+}

package/cli/selftune/hooks-shared/session-state.ts

@@ -0,0 +1,76 @@
+/**
+ * Generic session state persistence for hooks.
+ *
+ * Extracted from the duplicate patterns in auto-activate.ts (loadSessionState/saveSessionState)
+ * and skill-change-guard.ts (loadGuardState/saveGuardState). Both follow the same pattern:
+ *
+ *   1. Read a JSON file keyed by session_id
+ *   2. If session_id matches, return persisted state; otherwise return defaults
+ *   3. Write state back after updates
+ *
+ * This module generalizes that pattern with a type-safe generic interface.
+ * Fail-open: corrupt or missing files return fresh defaults.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { SessionState } from "./types.js";
+
+/**
+ * Load session state from a JSON file.
+ *
+ * The file is located at `{dir}/{prefix}-{sessionId}.json`. If the file does not
+ * exist, is corrupt, or belongs to a different session, fresh defaults are returned.
+ *
+ * @param dir        Directory to store state files (e.g., SELFTUNE_CONFIG_DIR)
+ * @param prefix     Filename prefix (e.g., "session-state", "guard-state")
+ * @param sessionId  Current session ID — state is invalidated when it changes
+ * @param defaults   Factory function returning fresh default state data
+ */
+export function loadSessionState<T extends Record<string, unknown>>(
+  dir: string,
+  prefix: string,
+  sessionId: string,
+  defaults: () => T,
+): SessionState<T> {
+  const safeName = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const filePath = join(dir, `${prefix}-${safeName}.json`);
+
+  try {
+    const raw = JSON.parse(readFileSync(filePath, "utf-8")) as SessionState<T>;
+    if (raw.session_id === sessionId && typeof raw.data === "object" && raw.data !== null) {
+      return raw;
+    }
+  } catch {
+    // ENOENT (missing) or corrupt JSON -- return fresh defaults
+  }
+
+  return {
+    session_id: sessionId,
+    created_at: new Date().toISOString(),
+    data: defaults(),
+  };
+}
+
+/**
+ * Save session state to a JSON file.
+ *
+ * The file is written to `{dir}/{prefix}-{state.session_id}.json`.
+ * The directory is created if it does not exist.
+ *
+ * @param dir     Directory to store state files
+ * @param prefix  Filename prefix (must match what was used in loadSessionState)
+ * @param state   The session state to persist
+ */
+export function saveSessionState<T extends Record<string, unknown>>(
+  dir: string,
+  prefix: string,
+  state: SessionState<T>,
+): void {
+  const safeName = state.session_id.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const filePath = join(dir, `${prefix}-${safeName}.json`);
+
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(state, null, 2), "utf-8");
+}

package/cli/selftune/hooks-shared/skill-paths.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared skill name and path extraction utilities for hooks.
+ *
+ * Extracted from duplicated logic in:
+ *   - skill-eval.ts: extractSkillName (checks SKILL.MD basename)
+ *   - skill-change-guard.ts: isSkillMdWrite, extractSkillNameFromPath
+ *   - evolution-guard.ts: isSkillMdWrite, extractSkillName (identical copies)
+ *
+ * All three files independently implement the same SKILL.md detection pattern.
+ * This module provides a single source of truth.
+ */
+
+import { basename, dirname } from "node:path";
+
+/**
+ * Extract the skill folder name from a file path that ends in SKILL.md.
+ *
+ * The convention is that skill definitions live at `<skill-name>/SKILL.md`,
+ * so the parent directory name is the skill name.
+ *
+ * @param filePath  Absolute or relative path to check
+ * @returns         Skill folder name, or null if the path does not end in SKILL.md
+ */
+export function extractSkillName(filePath: string): string | null {
+  if (!isSkillMdFile(filePath)) return null;
+  return basename(dirname(filePath)) || "unknown";
+}
+
+/**
+ * Check if a file path points to a SKILL.md file (case-insensitive).
+ *
+ * @param filePath  Path to check
+ */
+export function isSkillMdFile(filePath: string): boolean {
+  return basename(filePath).toUpperCase() === "SKILL.MD";
+}
+
+/**
+ * Check if a tool call is a Write or Edit operation targeting a SKILL.md file.
+ *
+ * Used by guard hooks (skill-change-guard, evolution-guard) to detect
+ * when an agent is about to modify a skill definition.
+ *
+ * @param toolName  The tool being called (e.g., "Write", "Edit", "Read")
+ * @param filePath  The file_path from tool_input
+ */
+export function isSkillMdWrite(toolName: string, filePath: string): boolean {
+  if (toolName !== "Write" && toolName !== "Edit") return false;
+  return isSkillMdFile(filePath);
+}

package/cli/selftune/hooks-shared/stdin-dispatch.ts

@@ -0,0 +1,59 @@
+/**
+ * Generalized stdin preview and keyword filtering for hooks.
+ *
+ * Hooks receive payloads via stdin. Most hooks only care about specific
+ * event types (e.g., skill-eval only handles PostToolUse). The existing
+ * stdin-preview.ts provides a fast-path optimization: read stdin once,
+ * check a preview slice for keywords, and skip JSON.parse entirely when
+ * the keyword is absent.
+ *
+ * This module wraps that pattern into a single readAndFilter call that
+ * combines the preview check with JSON parsing, returning null when
+ * the payload is irrelevant (caller should exit 0 immediately).
+ *
+ * Re-exports readStdinWithPreview for backward compatibility.
+ */
+
+export { readStdinWithPreview } from "../hooks/stdin-preview.js";
+
+/** Default preview size in characters (covers envelope fields). */
+const DEFAULT_PREVIEW_BYTES = 4096;
+
+/**
+ * Read stdin with fast-path keyword filtering.
+ *
+ * Reads all of stdin, checks the leading preview slice for the presence of
+ * ALL required keywords. If any keyword is missing, returns null (the caller
+ * should exit early). Otherwise, parses the full payload as JSON and returns it.
+ *
+ * This is the recommended way to read hook payloads when you know which
+ * keywords must appear in the envelope (e.g., event name, tool name).
+ *
+ * @param requiredKeywords  Strings that must ALL appear in the preview slice.
+ *                          Typically quoted JSON values like '"PostToolUse"'.
+ * @param previewBytes      Number of leading characters to check (default 4096).
+ * @returns                 Parsed payload and raw string, or null if keywords don't match.
+ *
+ * @example
+ * ```ts
+ * const result = await readAndFilter<PostToolUsePayload>(['"PostToolUse"', '"Read"']);
+ * if (!result) process.exit(0);
+ * const { payload } = result;
+ * ```
+ */
+export async function readAndFilter<T = unknown>(
+  requiredKeywords: string[],
+  previewBytes: number = DEFAULT_PREVIEW_BYTES,
+): Promise<{ payload: T; raw: string } | null> {
+  const raw = await Bun.stdin.text();
+  const preview = raw.slice(0, previewBytes);
+
+  for (const keyword of requiredKeywords) {
+    if (!preview.includes(keyword)) {
+      return null;
+    }
+  }
+
+  const payload = JSON.parse(raw) as T;
+  return { payload, raw };
+}