@drewpayment/mink 0.13.0-beta.4 → 0.13.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.13.0-beta.4",
+  "version": "0.13.0-beta.5",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -16,8 +16,24 @@ switch (command) {
     break;
 
   case "init": {
-    const { init } = await import("./commands/init");
-    await init(cwd);
+    const { init, resolveTargetsFromFlag } = await import("./commands/init");
+    const args = process.argv.slice(3);
+    const agentFlagIndex = args.findIndex(
+      (a) => a === "--agent" || a.startsWith("--agent=")
+    );
+    let agentValue: string | undefined;
+    if (agentFlagIndex !== -1) {
+      const a = args[agentFlagIndex];
+      agentValue = a.includes("=") ? a.split("=").slice(1).join("=") : args[agentFlagIndex + 1];
+    }
+    const yes = args.includes("--yes") || args.includes("-y");
+    const targets = agentValue ? resolveTargetsFromFlag(agentValue) : undefined;
+    if (agentValue && (!targets || targets.length === 0)) {
+      console.error(`[mink] unknown --agent value: ${agentValue}`);
+      console.error("  Valid: claude, pi, all (or a comma-separated list)");
+      process.exit(1);
+    }
+    await init(cwd, { targets, interactive: !yes });
     break;
   }
 
@@ -59,6 +75,12 @@ switch (command) {
     break;
   }
 
+  case "refresh-hooks": {
+    const { refreshHooks } = await import("./commands/refresh-hooks");
+    refreshHooks(cwd, process.argv.slice(3));
+    break;
+  }
+
   case "pre-write": {
     const { preWrite } = await import("./commands/pre-write");
     await preWrite(cwd);
@@ -233,7 +255,9 @@ switch (command) {
     console.log("Usage: mink <command> [options]");
     console.log();
     console.log("Commands:");
-    console.log("  init                    Initialize Mink in the current project");
+    console.log("  init [--agent X] [--yes] Initialize Mink in the current project");
+    console.log("                          --agent claude|pi|all (default: detect & prompt)");
+    console.log("  refresh-hooks [--all]   Regenerate hook wiring after an upgrade (--all: every project)");
     console.log("  status                  Display project health at a glance");
     console.log("  scan [--check]          Force a full file index rescan");
     console.log("  config [key] [value]    Manage global user settings");
@@ -275,7 +299,7 @@ switch (command) {
     console.log("  restore [backup]        Restore state from a backup");
     console.log("  bug search <term>       Search the bug log");
     console.log("  detect-waste            Detect and flag wasteful patterns");
-    console.log("  retrieve <token>        Return a compressed tool output's original (spec 21)");
+    console.log("  retrieve <token>        Return a compressed tool output's original (spec 22)");
     console.log("  reflect                 Generate learning memory reflections");
     console.log("  designqc [target]       Capture design screenshots (spec 13)");
     console.log("  framework-advisor       Generate framework advisor knowledge file (spec 14)");
@@ -285,7 +309,7 @@ switch (command) {
     console.log("  session-stop            Finalize session and log data");
     console.log("  pre-read / post-read    File read hooks");
     console.log("  pre-write / post-write  File write hooks");
-    console.log("  post-tool               Tool-output compression hook (Bash/Grep/MCP, spec 21)");
+    console.log("  post-tool               Tool-output compression hook (Bash/Grep/MCP, spec 22)");
     break;
 
   default:

package/src/commands/init.ts

@@ -12,6 +12,23 @@ import {
   isInsideVault,
   vaultProjects,
 } from "../core/vault";
+import {
+  type AgentId,
+  AGENTS,
+  detectAgents,
+  resolveTargetsFromFlag,
+} from "../core/agent-detect";
+import { installPi } from "../core/agent-pi";
+import { ask, stdinIsInteractive } from "../core/prompt";
+
+export { resolveTargetsFromFlag };
+
+export interface InitOptions {
+  /** Explicit set of hosts to wire. When omitted, Mink detects and/or prompts. */
+  targets?: AgentId[];
+  /** Allow an interactive agent-selection prompt when stdin is a TTY. */
+  interactive?: boolean;
+}
 
 interface HookCommand {
   type: "command";
@@ -91,7 +108,7 @@ export function buildHooksConfig(cliPath: string): HooksConfig {
       { matcher: "Read", hooks: hook(`${prefix} post-read`) },
       { matcher: "Edit", hooks: hook(`${prefix} post-write`) },
       { matcher: "Write", hooks: hook(`${prefix} post-write`) },
-      // Tool-output compression (spec 21) — a no-op until enabled via config.
+      // Tool-output compression (spec 22) — on by default; a no-op when disabled via config.
       { matcher: "Bash", hooks: hook(`${prefix} post-tool`) },
       { matcher: "Grep", hooks: hook(`${prefix} post-tool`) },
     ],
@@ -172,17 +189,80 @@ export function mergeHooksIntoSettings(
   atomicWriteJson(settingsPath, existing);
 }
 
+/** Wire Mink into Claude Code: settings.json hooks + the project rule file. */
+export function installClaude(
+  cwd: string,
+  cliPath: string
+): { settingsPath: string; rulePath: string } {
+  const settingsPath = resolve(cwd, ".claude", "settings.json");
+  mergeHooksIntoSettings(settingsPath, buildHooksConfig(cliPath));
+  const rulePath = writeMinkRule(cwd);
+  return { settingsPath, rulePath };
+}
+
+/**
+ * Decide which hosts to wire. Explicit `targets` win; otherwise Mink detects
+ * installed hosts and — only when running interactively at a TTY — asks the
+ * user to confirm. Non-interactive runs fall back to the detected set, and to
+ * Claude Code when nothing is detected (preserving Mink's original behavior).
+ */
+export async function resolveTargets(
+  cwd: string,
+  opts: InitOptions
+): Promise<AgentId[]> {
+  if (opts.targets && opts.targets.length > 0) return opts.targets;
+
+  const detected = detectAgents(cwd);
+  const detectedIds = detected.filter((a) => a.detected).map((a) => a.id);
+
+  if (opts.interactive && stdinIsInteractive()) {
+    return promptForAgents(detected, detectedIds);
+  }
+
+  return detectedIds.length > 0 ? detectedIds : ["claude"];
+}
+
+async function promptForAgents(
+  detected: ReturnType<typeof detectAgents>,
+  defaults: AgentId[]
+): Promise<AgentId[]> {
+  const fallback: AgentId[] = defaults.length > 0 ? defaults : ["claude"];
+
+  console.log("Which assistant(s) should Mink work with?");
+  detected.forEach((a, i) => {
+    const tag = a.detected ? `  (detected — ${a.signals.join(", ")})` : "";
+    console.log(`  ${i + 1}) ${a.label}${tag}`);
+  });
+
+  const answer = (
+    await ask(
+      `Enter numbers (comma-separated), 'a' for all [default: ${fallback.join(", ")}]: `
+    )
+  )
+    .trim()
+    .toLowerCase();
+
+  if (answer === "") return fallback;
+  if (answer === "a" || answer === "all") return AGENTS.map((a) => a.id);
+
+  const picked = answer
+    .split(",")
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => Number.isInteger(n) && n >= 1 && n <= detected.length)
+    .map((n) => detected[n - 1].id);
+
+  return picked.length > 0 ? picked : fallback;
+}
+
 function isExistingInstallation(cwd: string): boolean {
   const dir = projectDir(cwd);
   if (!existsSync(dir)) return false;
   return existsSync(join(dir, "file-index.json"));
 }
 
-export async function init(cwd: string): Promise<void> {
+export async function init(cwd: string, opts: InitOptions = {}): Promise<void> {
   const runtime = detectRuntime();
   const cliPath = resolveCliPath();
-  const hooks = buildHooksConfig(cliPath);
-  const settingsPath = resolve(cwd, ".claude", "settings.json");
   const dir = projectDir(cwd);
   const upgrading = isExistingInstallation(cwd);
 
@@ -193,8 +273,25 @@ export async function init(cwd: string): Promise<void> {
     console.log(`  backup: ${backupName}`);
   }
 
-  mergeHooksIntoSettings(settingsPath, hooks);
-  const rulePath = writeMinkRule(cwd);
+  const targets = await resolveTargets(cwd, opts);
+
+  // Wire each selected host. Each installer is idempotent — re-running replaces
+  // Mink's prior entries rather than duplicating them — and touches only that
+  // host's configuration.
+  const wired: Record<string, string[]> = {};
+  for (const target of targets) {
+    if (target === "claude") {
+      const { settingsPath, rulePath } = installClaude(cwd, cliPath);
+      wired.claude = [`hooks: ${settingsPath}`, `rule:  ${rulePath}`];
+    } else if (target === "pi") {
+      const r = installPi(cwd, cliPath);
+      wired.pi = [
+        `extension: ${r.extensionPath}`,
+        `guidance:  ${r.guidancePath}`,
+        ...(r.notePath ? [`note skill: ${r.notePath}`] : []),
+      ];
+    }
+  }
 
   mkdirSync(dir, { recursive: true });
 
@@ -217,28 +314,53 @@ export async function init(cwd: string): Promise<void> {
     !Array.isArray(existingMeta.pathsByDevice)
       ? (existingMeta.pathsByDevice as Record<string, string>)
       : {};
+  // Record the set of wired hosts as the authoritative source of truth, unioned
+  // with any previously wired host so a single-target re-init never silently
+  // unwires the other.
+  const priorAgents = Array.isArray(existingMeta?.agents)
+    ? (existingMeta!.agents as string[])
+    : [];
+  const agents = Array.from(new Set([...priorAgents, ...targets]));
+  // Stamp the Mink version that generated these hooks so session-start (and
+  // `mink refresh-hooks`) can self-heal stale wiring after an upgrade.
+  let hooksVersion = "0.0.0";
+  try {
+    hooksVersion = require("../core/self-update").getInstallInfo().currentVersion;
+  } catch {
+    // Fall through with a sentinel; a missing/old stamp just forces one refresh.
+  }
   atomicWriteJson(metaPath, {
     ...(existingMeta ?? {}),
     cwd,
     name: basename(cwd),
     initTimestamp: existingMeta?.initTimestamp ?? new Date().toISOString(),
     version: "0.1.0",
+    hooksVersion,
     pathsByDevice: { ...existingPathsByDevice, [deviceId]: cwd },
+    agents,
     ...(isNotesProject ? { projectType: "notes" } : {}),
   });
 
+  const printWiring = () => {
+    for (const id of Object.keys(wired)) {
+      const label = AGENTS.find((a) => a.id === id)?.label ?? id;
+      console.log(`  ${label}:`);
+      for (const line of wired[id]) console.log(`    ${line}`);
+    }
+  };
+
   if (upgrading) {
     console.log(`[mink] upgrade complete`);
     console.log(`  project:  ${projectId}`);
-    console.log(`  hooks:    ${settingsPath}`);
-    console.log(`  rule:     ${rulePath}`);
+    console.log(`  agents:   ${agents.join(", ")}`);
+    printWiring();
   } else {
     console.log(`[mink] initialized`);
     console.log(`  project:  ${projectId} (${identity.source})`);
     console.log(`  state:    ${dir}`);
     console.log(`  runtime:  ${runtime}`);
-    console.log(`  hooks:    ${settingsPath}`);
-    console.log(`  rule:     ${rulePath}`);
+    console.log(`  agents:   ${agents.join(", ")}`);
+    printWiring();
   }
 
   // Surface a one-time hint when the project is in a git repo with no remote

package/src/commands/post-read.ts

@@ -205,7 +205,7 @@ export async function postRead(cwd: string): Promise<void> {
     // Persist state
     atomicWriteJson(sessionPath(cwd), state);
 
-    // Tool-output compression (spec 21). Substitute a compact, reversible
+    // Tool-output compression (spec 22). Substitute a compact, reversible
     // summary for a large whole-file read. Skipped for ranged reads (their
     // output is only a slice) and a no-op unless compression is enabled. Uses
     // the on-disk content as the canonical original so signature extraction

package/src/commands/post-tool.ts

@@ -1,4 +1,4 @@
-// Generic PostToolUse compression hook (spec 21) for tools that produce large,
+// Generic PostToolUse compression hook (spec 22) for tools that produce large,
 // non-file output — Bash, Grep/Glob, and MCP tools. The Read tool is handled by
 // post-read (which has the on-disk content and ranged-read awareness); this hook
 // compresses the payload text directly.

package/src/commands/refresh-hooks.ts

@@ -0,0 +1,42 @@
+// `mink refresh-hooks [--all]` — regenerate Mink's generated hook wiring after an
+// upgrade so it matches the installed version's templates.
+//
+//   (default)  Refresh the current project.
+//   --all      Refresh every registered project that exists on this device.
+//
+// `--all` is what `runSelfUpgrade` spawns (as the freshly-installed binary) right
+// after a successful upgrade, so every project is refreshed eagerly rather than
+// waiting for its next session-start.
+
+import { existsSync } from "fs";
+import { refreshProjectHooks } from "../core/hook-refresh";
+
+export function refreshHooks(cwd: string, args: string[]): void {
+  const all = args.includes("--all");
+
+  if (!all) {
+    const r = refreshProjectHooks(cwd, { force: true });
+    console.log(
+      r.refreshed
+        ? `[mink] refreshed hooks (${r.agents.join(", ")}) → ${r.version}`
+        : "[mink] nothing to refresh — run `mink init` first."
+    );
+    return;
+  }
+
+  const { listRegisteredProjects } = require("../core/project-registry");
+  const { getOrCreateDeviceId } = require("../core/device");
+  const deviceId = getOrCreateDeviceId();
+
+  let refreshed = 0;
+  for (const p of listRegisteredProjects()) {
+    const local = p.pathsByDevice?.[deviceId] ?? p.cwd;
+    if (!local || !existsSync(local)) continue; // not present on this device
+    const r = refreshProjectHooks(local, { force: true });
+    if (r.refreshed) {
+      refreshed++;
+      console.log(`  ${p.name} (${r.agents.join(", ")})`);
+    }
+  }
+  console.log(`[mink] refreshed hooks for ${refreshed} project(s) → installed version.`);
+}

package/src/commands/retrieve.ts

@@ -1,5 +1,5 @@
 // `mink retrieve <token>` — return the byte-exact original of a previously
-// compressed tool output (spec 21 §Reversibility). Prints the original to
+// compressed tool output (spec 22 §Reversibility). Prints the original to
 // stdout on a hit; on a miss (unknown or expired token) it prints a short,
 // non-fatal notice to stderr and exits 0 so the assistant is never stranded by
 // an error.

package/src/commands/session-start.ts

@@ -41,6 +41,17 @@ export function sessionStart(cwd: string): void {
     // Migration is best-effort; never block session-start
   }
 
+  // Self-heal stale hook wiring after a Mink upgrade. Regenerates this project's
+  // configured hooks (Claude settings, Pi extension) when the generating version
+  // changed, so a `mink upgrade` never leaves the user re-running `mink init`.
+  // Idempotent, version-gated, and silent — never blocks session-start.
+  try {
+    const { refreshHooksIfStale } = require("../core/hook-refresh");
+    refreshHooksIfStale(cwd);
+  } catch {
+    // Never crash hooks
+  }
+
   // Sync pull before session begins (if enabled)
   try {
     const { isSyncInitialized, syncPull } = require("../core/sync");

package/src/core/agent-detect.ts

@@ -0,0 +1,88 @@
+import { execSync } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// Supported host coding assistants Mink can attach to. Adding a new host is a
+// matter of appending an entry here plus an installer in init.ts.
+export type AgentId = "claude" | "pi";
+
+export interface AgentMeta {
+  id: AgentId;
+  label: string;
+  /** Project-local config directory that signals the host is used here. */
+  projectDir: string;
+  /** Per-user global config directory that signals the host is installed. */
+  globalDir: string;
+  /** Executable name to probe on PATH. */
+  bin: string;
+}
+
+export const AGENTS: AgentMeta[] = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    projectDir: ".claude",
+    globalDir: join(homedir(), ".claude"),
+    bin: "claude",
+  },
+  {
+    id: "pi",
+    label: "Pi",
+    projectDir: ".pi",
+    globalDir: join(homedir(), ".pi"),
+    bin: "pi",
+  },
+];
+
+export interface AgentInfo extends AgentMeta {
+  detected: boolean;
+  /** Human-readable reasons the host was (or was not) detected. */
+  signals: string[];
+}
+
+function commandExists(bin: string): boolean {
+  try {
+    const probe = process.platform === "win32" ? `where ${bin}` : `command -v ${bin}`;
+    execSync(probe, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Inspect a single host's footprint relative to `cwd`. Detection is best-effort
+ * and layered, strongest signal first: a project-local config directory is the
+ * clearest sign the host is actually used here; a global config directory or a
+ * binary on PATH only prove the host is installed somewhere.
+ */
+export function detectAgent(meta: AgentMeta, cwd: string): AgentInfo {
+  const signals: string[] = [];
+  if (existsSync(join(cwd, meta.projectDir))) {
+    signals.push(`project config (${meta.projectDir}/)`);
+  }
+  if (existsSync(meta.globalDir)) {
+    signals.push("global config");
+  }
+  if (commandExists(meta.bin)) {
+    signals.push("on PATH");
+  }
+  return { ...meta, detected: signals.length > 0, signals };
+}
+
+export function detectAgents(cwd: string): AgentInfo[] {
+  return AGENTS.map((m) => detectAgent(m, cwd));
+}
+
+export function resolveTargetsFromFlag(flag: string): AgentId[] {
+  const normalized = flag.trim().toLowerCase();
+  if (normalized === "all") return AGENTS.map((a) => a.id);
+  const ids = normalized
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const valid = AGENTS.map((a) => a.id) as string[];
+  const resolved = ids.filter((id): id is AgentId => valid.includes(id));
+  return resolved;
+}