@vreko/cli 3.0.1

package/scripts/check-banned-words.ts

@@ -0,0 +1,152 @@
+/**
+ * Banned Words Check
+ *
+ * Scans CLI source files for banned words in user-facing strings.
+ * Prevents brand terminology drift (snapback, daemon) in terminal output.
+ *
+ * Usage: node scripts/check-banned-words.ts
+ *
+ * @module scripts/check-banned-words
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliSrcDir = join(__dirname, "../src");
+
+// Banned words with their replacements
+const BANNED_WORDS = [
+	{ word: "snapback", replacement: "vreko", description: "Brand name" },
+	{ word: "daemon", replacement: "service", description: "Service terminology" },
+];
+
+// Patterns to exclude (internal code, not user-facing)
+const EXCLUDE_PATTERNS = [
+	// File paths (directory names, log files)
+	/\.vreko\/daemon/,
+	/daemon\.log/,
+	/join\(.*daemon/,
+	/homedir\(\).*daemon/,
+	// Variable names
+	/daemonResult/,
+	/getDaemonPid/,
+	/isDaemon/,
+	/connectToDaemon/,
+	/getDaemonClient/,
+	/registerWithDaemon/,
+	/tryAutoStartDaemon/,
+	// Object properties
+	/result\.daemon/,
+	/client\.daemon/,
+	/daemonIcon/,
+	/daemonMajor/,
+	/daemonError/,
+	// Command names (the actual CLI command - users type this)
+	/program\.command\("daemon"\)/,
+	/command\("daemon"\)/,
+	/"daemon",/,
+	/process\.argv.*daemon/,
+	/vreko daemon start/,
+	// API methods (internal protocol)
+	/"daemon\/status"/,
+	/"daemon\/ping"/,
+	/"daemon\/start"/,
+	/"daemon\/shutdown"/,
+	// Help table command names (the command itself, not description)
+	/\{ name: "daemon"/,
+	// Test files
+	/__tests__/,
+	// Comments
+	/\/\/.*daemon/,
+	/\/\/.*snapback/,
+];
+
+interface Violation {
+	file: string;
+	line: number;
+	word: string;
+	match: string;
+	replacement: string;
+}
+
+const violations: Violation[] = [];
+
+function scanFile(filePath: string): void {
+	const content = readFileSync(filePath, "utf-8");
+	const lines = content.split("\n");
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const lineNum = i + 1;
+
+		// Skip if line contains any exclude pattern
+		if (EXCLUDE_PATTERNS.some((pattern) => pattern.test(line))) {
+			continue;
+		}
+
+		// Check for banned words in string literals
+		for (const { word, replacement } of BANNED_WORDS) {
+			// Match word boundaries in string literals
+			const stringPattern = new RegExp(`["\`]\\b${word}\\b["\`]`, "gi");
+			const matches = line.match(stringPattern);
+
+			if (matches) {
+				for (const match of matches) {
+					violations.push({
+						file: filePath.replace(cliSrcDir, "src"),
+						line: lineNum,
+						word,
+						match,
+						replacement,
+					});
+				}
+			}
+		}
+	}
+}
+
+function scanDirectory(dir: string): void {
+	const entries = readdirSync(dir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const fullPath = join(dir, entry.name);
+
+		if (entry.isDirectory()) {
+			// Recursively scan subdirectories
+			scanDirectory(fullPath);
+		} else if (entry.isFile() && entry.name.endsWith(".ts")) {
+			// Scan TypeScript files
+			scanFile(fullPath);
+		}
+	}
+}
+
+// Scan relevant directories
+const targetDirs = ["commands", "ui", "services"];
+
+for (const targetDir of targetDirs) {
+	const dirPath = join(cliSrcDir, targetDir);
+	try {
+		scanDirectory(dirPath);
+	} catch (error) {
+		// Directory might not exist, skip
+		void error;
+	}
+}
+
+// Report results
+if (violations.length === 0) {
+	console.log("✅ No banned words found in user-facing strings");
+	process.exit(0);
+} else {
+	console.error(`❌ Found ${violations.length} banned word violation(s):\n`);
+
+	for (const violation of violations) {
+		console.error(`  ${violation.file}:${violation.line} - "${violation.match}" → use "${violation.replacement}"`);
+	}
+
+	console.error("\nFix these violations before committing.");
+	process.exit(1);
+}

package/scripts/hooks/posttooluse-file-notify.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# PostToolUse hook - file-notify IPC bridge
+# Fires after every Edit/Write/MultiEdit and notifies the vrekod daemon via
+# intelligence/file-modified IPC so fileIndex in workspace.json stays
+# current for Claude Code users.
+#
+# Hook contract:
+#   stdin  - JSON: { tool: { name, input: { file_path?, edits?, paths? } } }
+#   stdout - reserved (not written by this hook)
+#   stderr - surfaced to the model; kept silent on happy path
+#   exit 0 - always (PostToolUse hooks must never block)
+#
+# Degraded-state breadcrumb (R-FIX-3):
+#   The *success* path stays fire-and-forget for latency. But a missing
+#   dependency (jq/socat/nc) or an unreachable socket would otherwise make every
+#   agent edit vanish before reaching the daemon - silently - which is the
+#   phantom-action failure mode this platform exists to detect. So degraded
+#   conditions leave a breadcrumb at ~/.vreko/daemon/ingress-degraded that
+#   `vr status` reads and surfaces. Asserting on silence asserts on nothing.
+
+# ---- Degraded-state breadcrumb -------------------------------------------
+# Writes (or refreshes) a single-line marker describing why ingress degraded.
+# Best-effort: the breadcrumb itself must never block or fail the hook.
+DEGRADED_MARKER="$HOME/.vreko/daemon/ingress-degraded"
+write_degraded_breadcrumb() {
+  reason="$1"
+  marker_dir="$(dirname "$DEGRADED_MARKER")"
+  mkdir -p "$marker_dir" 2>/dev/null || return 0
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)"
+  printf 'ingress-degraded reason=%s at=%s\n' "$reason" "$ts" >"$DEGRADED_MARKER" 2>/dev/null || true
+}
+
+# ---- Gate: jq is required to parse the hook payload ----------------------
+# Without jq the payload cannot be parsed and the edit cannot be forwarded.
+# This is a degraded condition, not a no-op.
+if ! command -v jq >/dev/null 2>&1; then
+  write_degraded_breadcrumb "missing-dependency:jq"
+  exit 0
+fi
+
+# ---- Parse stdin ---------------------------------------------------------
+INPUT=$(cat)
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool.name // empty' 2>/dev/null || echo "")
+
+# ---- Gate: only act on file-modifying tools ------------------------------
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# ---- Extract target file -------------------------------------------------
+# MultiEdit: .tool.input.edits[0].file_path takes priority
+# Edit/Write: .tool.input.file_path
+# Fallback:   .tool.input.paths[0]
+TARGET_FILE=$(printf '%s' "$INPUT" | jq -r '
+  .tool.input.edits[0].file_path //
+  .tool.input.file_path //
+  .tool.input.paths[0] //
+  empty
+' 2>/dev/null || echo "")
+
+if [ -z "$TARGET_FILE" ]; then
+  exit 0
+fi
+
+# ---- Resolve workspace ---------------------------------------------------
+# CLAUDE_PROJECT_DIR is set by Claude Code to the current project root.
+WORKSPACE="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# ---- Build JSON-RPC payload ----------------------------------------------
+# NOTE: `aiTool` is the AI *client* identity, which the daemon's
+# intelligence/file-modified schema constrains to a fixed enum
+# (cursor|copilot|claude|windsurf|burst-pattern). This hook runs under Claude
+# Code, so the identity is "claude". The Claude Code *tool* name ($TOOL_NAME,
+# e.g. Edit/Write/MultiEdit) is NOT a valid `aiTool` value - sending it makes the
+# daemon reject the payload with -32602 and, because this hook is fire-and-forget,
+# the rejection would be silent. `aiAttributed:true` already marks the change as
+# AI-driven; `aiTool:"claude"` records which assistant.
+SOCK="$HOME/.vreko/service.sock"
+PAYLOAD=$(printf '{"jsonrpc":"2.0","method":"intelligence/file-modified","params":{"workspace":"%s","path":"%s","aiAttributed":true,"aiTool":"claude"},"id":1}\n' \
+  "$WORKSPACE" "$TARGET_FILE")
+
+# ---- Gate: a transport (socat or nc) is required -------------------------
+# Without either, the edit cannot reach the daemon - degraded, not silent.
+if ! command -v socat >/dev/null 2>&1 && ! command -v nc >/dev/null 2>&1; then
+  write_degraded_breadcrumb "missing-dependency:socat-or-nc"
+  exit 0
+fi
+
+# ---- Gate: the daemon socket must exist ----------------------------------
+# A missing socket means the daemon is unreachable. Detecting it here (cheap,
+# non-blocking) lets us leave a breadcrumb instead of firing into the void.
+if [ ! -S "$SOCK" ]; then
+  write_degraded_breadcrumb "socket-unreachable"
+  exit 0
+fi
+
+# ---- Fire-and-forget IPC (2s timeout, latency-preserving) ----------------
+# Deps present and socket exists: stay fire-and-forget on the success path.
+if command -v socat >/dev/null 2>&1; then
+  { printf '%s' "$PAYLOAD" | socat -t2 UNIX-CONNECT:"$SOCK" -; } &>/dev/null &
+  disown 2>/dev/null || true
+elif command -v nc >/dev/null 2>&1; then
+  { timeout 2 nc -U "$SOCK" <<< "$PAYLOAD" || true; } &>/dev/null &
+  disown 2>/dev/null || true
+fi
+
+exit 0

package/scripts/hooks/pretooluse-fragile-guard.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# PreToolUse hook  -  fragile-file guard
+# Reads stdin JSON, calls `vreko pulse`, emits stderr banner if target is fragile.
+# Exit 0 = allow (advisory); Exit 2 = block (blocking mode only).
+# Hook contract: stdout reserved for structured responses; stderr surfaces to model.
+
+set -euo pipefail
+
+# --- Parse stdin (Claude Code hook contract) -----------------------------
+INPUT=$(cat)
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool.name // empty' 2>/dev/null || echo "")
+TARGET_FILE=$(printf '%s' "$INPUT" | jq -r '.tool.input.file_path // empty' 2>/dev/null || echo "")
+
+# Only act on Edit/Write/MultiEdit operations
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Require a target file
+if [ -z "$TARGET_FILE" ]; then
+  exit 0
+fi
+
+# --- Daemon presence check (graceful degradation) ------------------------
+if ! vreko daemon status --quiet 2>/dev/null; then
+  exit 0
+fi
+
+# --- Pulse query (HOOK-T-03: bounded timeout) ----------------------------
+if command -v timeout >/dev/null 2>&1; then
+  PULSE=$(timeout 5 vreko pulse --format json --focus "$TARGET_FILE" 2>/dev/null || echo '{}')
+else
+  PULSE=$(vreko pulse --format json --focus "$TARGET_FILE" 2>/dev/null || echo '{}')
+fi
+
+# --- Determine fragility verdict ----------------------------------------
+# Since --focus already filters to the target file, a non-empty fragileFiles
+# array means the target IS fragile. Avoids path-matching ambiguity.
+IS_FRAGILE=$(printf '%s' "$PULSE" | jq -r '(.fragileFiles | length) > 0' \
+  2>/dev/null || echo "false")
+
+if [ "$IS_FRAGILE" != "true" ]; then
+  exit 0
+fi
+
+# --- Compute provenance fields (HOOK-04) --------------------------------
+if command -v shasum >/dev/null 2>&1; then
+  SHA=$(shasum -a 256 "$TARGET_FILE" 2>/dev/null | cut -c1-16 || echo "unknown")
+elif command -v openssl >/dev/null 2>&1; then
+  SHA=$(openssl sha256 -r "$TARGET_FILE" 2>/dev/null | cut -c1-16 || echo "unknown")
+else
+  SHA="unknown"
+fi
+
+CONFIDENCE=$(printf '%s' "$PULSE" | jq -r '.fragileFiles[0]?.fragility // 0' \
+  2>/dev/null || echo "0")
+
+HINT=$(printf '%s' "$PULSE" | jq -r '.llmHint // empty' 2>/dev/null || echo "")
+
+# --- Mode resolution (HOOK-T-04: case literal compare, no eval) ---------
+MODE=$(vreko config get hooks.claude-code.mode 2>/dev/null || echo "advisory")
+case "$MODE" in
+  blocking) MODE="blocking" ;;
+  advisory|"") MODE="advisory" ;;
+  *) MODE="advisory" ;;
+esac
+
+# --- Emit user-visible output to stderr ---------------------------------
+{
+  printf '⚠ Vreko: %s is flagged fragile.\n' "$TARGET_FILE"
+  printf '  SHA: %s  Confidence: %s\n' "$SHA" "$CONFIDENCE"
+  if [ -n "$HINT" ]; then
+    printf '%s\n' "$HINT"
+  fi
+} >&2
+
+# --- Exit code ----------------------------------------------------------
+if [ "$MODE" = "blocking" ]; then
+  exit 2
+fi
+exit 0

package/scripts/post-install-notice.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install notice for CLI binary name change
+ *
+ * Informs users about the snap → vr migration
+ */
+
+const chalk = require("chalk");
+
+console.log(chalk.cyan.bold("\n📦 Vreko CLI Installed!\n"));
+console.log(chalk.yellow("⚠️  IMPORTANT: Command name change"));
+console.log(chalk.gray("   Old: snap <command>"));
+console.log(chalk.green("   New: vr <command>  (recommended)"));
+console.log(chalk.gray("   Or:  vreko <command>"));
+console.log();
+console.log(chalk.dim('The "snap" command still works but will be removed in v4.0.0'));
+console.log(chalk.dim("Update your scripts and aliases now to avoid disruption."));
+console.log();
+console.log(chalk.cyan("Quick start:"));
+console.log(chalk.gray("  vr init          # Initialize workspace"));
+console.log(chalk.gray("  vr --help        # View all commands"));
+console.log();
+console.log(chalk.dim("Migration guide: https://docs.vreko.dev/cli/migration\n"));

package/scripts/postinstall.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for @vreko/cli
+ * Runs after npm install to:
+ *   1. Emit the cli_installed analytics event (idempotent, once per machine).
+ *   2. Install the OS supervisor so the daemon auto-restarts on crash.
+ *
+ * CLI-EVENTS-02: Emits the `cli_installed` pioneer event idempotently.
+ * Uses a ~/.vreko/installed flag file to ensure the event fires only once
+ * per machine, regardless of how many times the package is installed.
+ *
+ * RULES: This script must ALWAYS exit 0. A postinstall failure breaks
+ * `npm install -g` entirely. Every code path must end with success.
+ * No telemetry is added beyond the existing cli_installed event.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+
+// Idempotent cli_installed emit  -  fire once, then never again on this machine.
+try {
+	const globalDir = join(homedir(), ".vreko");
+	const flagFile = join(globalDir, "installed");
+
+	if (!existsSync(flagFile)) {
+		// Ensure ~/.vreko/ exists
+		mkdirSync(globalDir, { recursive: true });
+		// Write timestamp flag before emitting so a crash/timeout doesn't re-emit
+		writeFileSync(flagFile, new Date().toISOString(), "utf8");
+
+		// Fire-and-forget POST  -  never await, never throw
+		const endpoint = process.env.VREKO_API_URL ?? "https://api.vreko.dev";
+		fetch(`${endpoint}/v1/analytics/events`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ event: "cli_installed" }),
+		}).catch(() => {
+			// Silently discard  -  postinstall must never fail due to analytics
+		});
+	}
+} catch {
+	// Non-fatal: postinstall must always succeed regardless of analytics errors
+}
+
+// Supervisor install  -  runs after the analytics section.
+// Always exits 0. Never throws. Never fails the install.
+try {
+	const currentPlatform = platform();
+
+	if (currentPlatform === "win32") {
+		// Windows is preview-only; supervisor install is manual.
+		process.stdout.write("vreko: Windows is preview; run `vreko service install` manually\n");
+	} else if (currentPlatform === "darwin" || currentPlatform === "linux") {
+		// Refuse to run supervisor install as root  -  launchd agents must be
+		// installed as the user who will own them, not as root.
+		const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+		if (isRoot) {
+			const user = process.env.SUDO_USER || process.env.USER || "your-user";
+			process.stdout.write(
+				`vreko: installed as root. Skipping supervisor install.\n` +
+					`  Run: sudo -u ${user} vreko service install\n`,
+			);
+		} else {
+			// npm creates bin symlinks before running postinstall, so `vreko` is on PATH.
+			// Use "pipe" so subprocess output doesn't interleave with our one-line status.
+			const result = spawnSync("vreko", ["service", "install"], {
+				stdio: "pipe",
+				shell: false,
+			});
+			if (result.status !== 0 || result.error) {
+				// Non-fatal: log one line, do not propagate error.
+				process.stderr.write("vreko: supervisor install failed; run `vreko service install` manually\n");
+			} else {
+				process.stdout.write("vreko: supervisor installed\n");
+			}
+		}
+	}
+} catch {
+	// Any unexpected error is non-fatal  -  postinstall must always succeed.
+	process.stderr.write("vreko: supervisor install failed; run `vreko service install` manually\n");
+}

package/scripts/preuninstall.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-uninstall script for @vreko/cli
+ * Runs before npm uninstall to remove the OS supervisor agent/unit.
+ *
+ * RULES: This script must ALWAYS exit 0. A preuninstall failure blocks
+ * `npm uninstall -g`. Every code path must end with success.
+ */
+
+import { spawnSync } from "node:child_process";
+import { platform } from "node:os";
+
+try {
+	const currentPlatform = platform();
+
+	if (currentPlatform === "win32") {
+		// Windows preview: no supervisor to uninstall.
+	} else if (currentPlatform === "darwin" || currentPlatform === "linux") {
+		const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+		if (!isRoot) {
+			const result = spawnSync("vreko", ["service", "uninstall"], {
+				stdio: "inherit",
+				shell: false,
+			});
+			if (result.status !== 0 || result.error) {
+				process.stderr.write("vreko: supervisor uninstall failed; run `vreko service uninstall` manually\n");
+			}
+		}
+	}
+} catch {
+	// Any unexpected error is non-fatal.
+	process.stderr.write("vreko: supervisor uninstall failed; run `vreko service uninstall` manually\n");
+}

package/scripts/verify-jsx-transform.mjs

@@ -0,0 +1,55 @@
+/**
+ * Post-build guard: asserts the CLI dist is using the automatic JSX transform.
+ *
+ * WHY THIS EXISTS:
+ * When tsconfig.base.json has "emitDecoratorMetadata": true, tsup switches from
+ * esbuild to SWC for transpilation. SWC's default JSX transform is classic
+ * (React.createElement) WITHOUT injecting "import React from 'react'". Combined
+ * with splitting:true, this produces ESM chunks where React is referenced but
+ * never imported → ReferenceError: React is not defined at runtime.
+ *
+ * The fix lives in tsup.config.ts: swc.jsc.transform.react.runtime = "automatic"
+ * This script verifies the fix is in effect after every build.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distIndex = join(__dirname, "../dist/index.js");
+const distDir = join(__dirname, "../dist");
+
+if (!existsSync(distIndex)) {
+	process.exit(1);
+}
+
+const { readdirSync } = await import("node:fs");
+const jsFiles = readdirSync(distDir).filter((f) => f.endsWith(".js"));
+const fileContents = jsFiles.map((file) => ({
+	file,
+	content: readFileSync(join(distDir, file), "utf-8"),
+}));
+
+// In split bundles, the automatic runtime import can live in a chunk rather than index.js.
+const hasAutomaticJsxRuntime = fileContents.some(({ content }) => content.includes("react/jsx-runtime"));
+if (!hasAutomaticJsxRuntime) {
+	process.exit(1);
+}
+
+// Guard against classic JSX output without React in scope.
+for (const { content } of fileContents) {
+	const hasClassicJsx = content.includes("React.createElement");
+	const hasReactImport =
+		content.includes("import React") ||
+		content.includes('from "react"') ||
+		content.includes("from 'react'") ||
+		content.includes('import("react")') ||
+		content.includes("import('react')") ||
+		content.includes('require("react")') ||
+		content.includes("require('react')");
+
+	if (hasClassicJsx && !hasReactImport) {
+		process.exit(1);
+	}
+}