@drewpayment/mink 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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

@@ -107,6 +107,12 @@ switch (command) {
     break;
   }
 
+  case "upgrade": {
+    const { upgrade } = await import("./commands/upgrade");
+    await upgrade(cwd, process.argv.slice(3));
+    break;
+  }
+
   case "restore": {
     const { restore } = await import("./commands/restore");
     restore(cwd, process.argv.slice(3));
@@ -244,7 +250,8 @@ switch (command) {
     console.log("  dashboard [--port=N]    Open the real-time web dashboard");
     console.log("  daemon <cmd>            Manage the background daemon (start|stop|restart|logs|install|uninstall)");
     console.log("  cron <cmd> [id]         Manage scheduled tasks (list|run|retry)");
-    console.log("  update [options]        Update Mink across registered projects");
+    console.log("  update [options]        Update Mink hooks across registered projects");
+    console.log("  upgrade [options]       Self-upgrade the mink CLI from npm (--check|--dry-run|--force)");
     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");

package/src/commands/init.ts

@@ -53,18 +53,13 @@ export function resolveCliPath(): string {
   return resolve(selfDir, "../cli.ts");
 }
 
-export function buildHooksConfig(
-  runtime: "bun" | "node",
-  cliPath: string
-): HooksConfig {
-  // If using compiled JS, always use node (universally available)
-  // If using .ts source, must use bun
+export function buildHooksConfig(cliPath: string): HooksConfig {
+  // For installed packages emit the `mink` bin shim so the resulting
+  // .claude/settings.json is portable across machines, users, and runtimes
+  // when committed to git (issue #55). For source-dev mode (cli.ts) the shim
+  // isn't on PATH, so fall back to `bun run <abs path>`.
   const isTsSource = cliPath.endsWith(".ts");
-  const prefix = isTsSource
-    ? `bun run ${cliPath}`
-    : runtime === "bun"
-      ? `bun run ${cliPath}`
-      : `node ${cliPath}`;
+  const prefix = isTsSource ? `bun run ${cliPath}` : "mink";
   const hook = (cmd: string): HookCommand[] => [{ type: "command", command: cmd }];
   return {
     SessionStart: [{ matcher: "", hooks: hook(`${prefix} session-start`) }],
@@ -83,15 +78,20 @@ export function buildHooksConfig(
 }
 
 function isMinkCommand(cmd: string): boolean {
-  return (
-    cmd.includes("cli") &&
-    (cmd.includes("session-start") ||
-      cmd.includes("session-stop") ||
-      cmd.includes("pre-read") ||
-      cmd.includes("post-read") ||
-      cmd.includes("pre-write") ||
-      cmd.includes("post-write"))
-  );
+  const hasMinkSubcommand =
+    cmd.includes("session-start") ||
+    cmd.includes("session-stop") ||
+    cmd.includes("pre-read") ||
+    cmd.includes("post-read") ||
+    cmd.includes("pre-write") ||
+    cmd.includes("post-write");
+  if (!hasMinkSubcommand) return false;
+  // Match the new bin-shim format (`mink <subcmd>` or `/abs/path/to/mink <subcmd>`)
+  // as well as legacy formats (`bun run .../cli.js ...`, `node .../cli.js ...`,
+  // `bun run .../cli.ts ...`) so re-init replaces stale entries instead of
+  // duplicating them.
+  if (/(^|\/|\s)mink\s/.test(cmd)) return true;
+  return cmd.includes("cli.js") || cmd.includes("cli.ts");
 }
 
 function isMinkHook(entry: HookEntry | Record<string, unknown>): boolean {
@@ -159,7 +159,7 @@ function isExistingInstallation(cwd: string): boolean {
 export async function init(cwd: string): Promise<void> {
   const runtime = detectRuntime();
   const cliPath = resolveCliPath();
-  const hooks = buildHooksConfig(runtime, cliPath);
+  const hooks = buildHooksConfig(cliPath);
   const settingsPath = resolve(cwd, ".claude", "settings.json");
   const dir = projectDir(cwd);
   const upgrading = isExistingInstallation(cwd);

package/src/commands/update.ts

@@ -1,10 +1,9 @@
-import { resolve, dirname, basename } from "path";
-import { existsSync } from "fs";
+import { resolve } from "path";
 import { listRegisteredProjects } from "../core/project-registry";
 import { createBackup } from "../core/backup";
 import { projectMetaPath } from "../core/paths";
 import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
-import { buildHooksConfig, detectRuntime, mergeHooksIntoSettings } from "./init";
+import { buildHooksConfig, mergeHooksIntoSettings, resolveCliPath } from "./init";
 
 function parseArgs(args: string[]): {
   dryRun: boolean;
@@ -78,12 +77,8 @@ export async function update(cwd: string, args: string[]): Promise<void> {
     return;
   }
 
-  const runtime = detectRuntime();
-  const cliPath = resolve(
-    dirname(new URL(import.meta.url).pathname),
-    "../cli.ts"
-  );
-  const newHooks = buildHooksConfig(runtime, cliPath);
+  const cliPath = resolveCliPath();
+  const newHooks = buildHooksConfig(cliPath);
 
   for (const target of targets) {
     console.log(`[mink] updating: ${target.name} (${target.id})`);

package/src/commands/upgrade.ts

@@ -0,0 +1,128 @@
+import { runSelfUpgrade, PACKAGE_NAME, type UpgradeResult } from "../core/self-update";
+
+interface UpgradeArgs {
+  check: boolean;
+  dryRun: boolean;
+  force: boolean;
+  yes: boolean;
+  help: boolean;
+}
+
+function parseArgs(args: string[]): UpgradeArgs {
+  const out: UpgradeArgs = {
+    check: false,
+    dryRun: false,
+    force: false,
+    yes: false,
+    help: false,
+  };
+  for (const arg of args) {
+    switch (arg) {
+      case "--check":
+        out.check = true;
+        break;
+      case "--dry-run":
+        out.dryRun = true;
+        break;
+      case "--force":
+        out.force = true;
+        break;
+      case "--yes":
+      case "-y":
+        out.yes = true;
+        break;
+      case "--help":
+      case "-h":
+        out.help = true;
+        break;
+    }
+  }
+  return out;
+}
+
+function printHelp(): void {
+  console.log("Usage: mink upgrade [options]");
+  console.log("");
+  console.log("Check the npm registry for a newer mink release and install it.");
+  console.log(`Tracks the 'latest' dist-tag of ${PACKAGE_NAME}.`);
+  console.log("");
+  console.log("Options:");
+  console.log("  --check     Report whether an upgrade is available; do not install");
+  console.log("  --dry-run   Resolve everything but do not run the install command");
+  console.log("  --force     Install the latest version even if it is not strictly newer");
+  console.log("  --yes, -y   Skip the interactive confirmation prompt");
+  console.log("  --help, -h  Show this help");
+  console.log("");
+  console.log("Auto-update on a schedule:");
+  console.log("  mink config set cli.auto-update true");
+  console.log("  mink config set cli.auto-update-schedule \"0 4 * * *\"");
+}
+
+function describeResult(r: UpgradeResult): string {
+  switch (r.status) {
+    case "up-to-date":
+      return `Already up-to-date — ${r.current} matches latest.`;
+    case "update-available":
+      return `Update available: ${r.current} → ${r.latest}` +
+        (r.packageManager ? ` (would install via ${r.packageManager})` : "");
+    case "would-upgrade":
+      return `Would upgrade: ${r.current} → ${r.latest}\n  command: ${r.command}`;
+    case "upgraded":
+      return `Upgraded ${r.from} → ${r.to} (via ${r.packageManager}).`;
+    case "skipped":
+      return `Skipped: ${r.reason}`;
+    case "error":
+      return `Error: ${r.reason}`;
+  }
+}
+
+async function confirm(prompt: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false;
+  process.stdout.write(prompt);
+  return new Promise<boolean>((resolveConfirm) => {
+    process.stdin.setEncoding("utf-8");
+    process.stdin.once("data", (chunk) => {
+      const answer = String(chunk).trim().toLowerCase();
+      resolveConfirm(answer === "y" || answer === "yes");
+    });
+  });
+}
+
+export async function upgrade(_cwd: string, args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  // For interactive runs without --yes/--check/--dry-run/--force, do a check
+  // first and ask for confirmation before mutating the global install.
+  const isCheckLike = parsed.check || parsed.dryRun;
+  if (!isCheckLike && !parsed.yes && process.stdin.isTTY) {
+    const probe = await runSelfUpgrade({ source: "manual", checkOnly: true, force: parsed.force });
+    console.log(describeResult(probe));
+    if (probe.status !== "update-available" && !parsed.force) {
+      return;
+    }
+    const ok = await confirm("Proceed with install? [y/N] ");
+    if (!ok) {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  const result = await runSelfUpgrade({
+    source: "manual",
+    checkOnly: parsed.check,
+    dryRun: parsed.dryRun,
+    force: parsed.force,
+    interactive: true,
+  });
+
+  console.log(describeResult(result));
+
+  if (result.status === "error") {
+    process.exit(1);
+  }
+}

package/src/core/self-update.ts

@@ -0,0 +1,363 @@
+import { spawnSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { resolveConfigValue } from "./global-config";
+import { minkRoot } from "./paths";
+import { safeAppendText, atomicWriteText } from "./fs-utils";
+import { join } from "path";
+
+export const PACKAGE_NAME = "@drewpayment/mink";
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const NETWORK_TIMEOUT_MS = 5_000;
+const INSTALL_TIMEOUT_MS = 10 * 60_000;
+const LOG_MAX_LINES = 1000;
+
+export type UpgradeSource = "manual" | "scheduler";
+export type PackageManager = "npm" | "bun";
+
+export type UpgradeResult =
+  | { status: "up-to-date"; current: string; latest: string }
+  | { status: "update-available"; current: string; latest: string; packageManager?: PackageManager }
+  | { status: "would-upgrade"; current: string; latest: string; packageManager: PackageManager; command: string }
+  | { status: "upgraded"; from: string; to: string; packageManager: PackageManager }
+  | { status: "skipped"; reason: string }
+  | { status: "error"; reason: string; transient: boolean };
+
+export interface UpgradeOptions {
+  source: UpgradeSource;
+  /** Skip the install step; only report whether an upgrade is available. */
+  checkOnly?: boolean;
+  /** Don't run the install command, but resolve everything else and report what would run. */
+  dryRun?: boolean;
+  /** Install even if the latest version is not strictly newer. */
+  force?: boolean;
+  /** Stream the install command's stdio to the parent terminal. False for scheduler runs. */
+  interactive?: boolean;
+  /** Override the registry URL (for tests). */
+  registryUrlOverride?: string;
+}
+
+// ── Version compare ─────────────────────────────────────────────────────────
+
+interface ParsedVersion {
+  numbers: number[];
+  prerelease: string | null;
+}
+
+export function parseSemver(input: string): ParsedVersion | null {
+  const trimmed = input.trim().replace(/^v/, "");
+  if (!trimmed) return null;
+  const [versionPart, ...prereleaseParts] = trimmed.split("-");
+  const numbers = versionPart.split(".").map((s) => Number.parseInt(s, 10));
+  if (numbers.some((n) => Number.isNaN(n))) return null;
+  return {
+    numbers,
+    prerelease: prereleaseParts.length ? prereleaseParts.join("-") : null,
+  };
+}
+
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ * A version with a prerelease tag is considered older than the same version without one
+ * (e.g. 1.0.0-rc.1 < 1.0.0). Prerelease vs prerelease falls back to lexicographic compare.
+ */
+export function compareSemver(a: string, b: string): number {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa && !pb) return 0;
+  if (!pa) return -1;
+  if (!pb) return 1;
+
+  const len = Math.max(pa.numbers.length, pb.numbers.length);
+  for (let i = 0; i < len; i++) {
+    const ai = pa.numbers[i] ?? 0;
+    const bi = pb.numbers[i] ?? 0;
+    if (ai > bi) return 1;
+    if (ai < bi) return -1;
+  }
+
+  if (pa.prerelease === pb.prerelease) return 0;
+  if (pa.prerelease === null) return 1;
+  if (pb.prerelease === null) return -1;
+  if (pa.prerelease > pb.prerelease) return 1;
+  if (pa.prerelease < pb.prerelease) return -1;
+  return 0;
+}
+
+// ── CLI install path resolution ─────────────────────────────────────────────
+
+export interface CliInstallInfo {
+  /** Absolute path to the running cli.js (or src/cli.ts in dev mode). */
+  cliPath: string;
+  /** Absolute path to the package.json that owns the running CLI. */
+  packageJsonPath: string;
+  /** Version reported by that package.json. */
+  currentVersion: string;
+  /** True when running under src/cli.ts via bun/tsx. */
+  isDevMode: boolean;
+}
+
+/**
+ * Resolve the install location of the *running* CLI by walking up from
+ * `import.meta.url` until we find a package.json. We treat anything ending
+ * in `.ts` or living inside the working source tree as dev mode.
+ */
+export function getInstallInfo(): CliInstallInfo {
+  const selfPath = new URL(import.meta.url).pathname;
+  const isDevMode = selfPath.endsWith(".ts");
+
+  // Walk up directories until we find package.json
+  let dir = dirname(selfPath);
+  let packageJsonPath: string | null = null;
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      packageJsonPath = candidate;
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  if (!packageJsonPath) {
+    throw new Error("Unable to locate package.json for the running mink CLI");
+  }
+
+  let currentVersion = "0.0.0";
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    if (typeof pkg.version === "string") currentVersion = pkg.version;
+  } catch {
+    // fall through with 0.0.0
+  }
+
+  return {
+    cliPath: selfPath,
+    packageJsonPath,
+    currentVersion,
+    isDevMode,
+  };
+}
+
+// ── Registry fetch ──────────────────────────────────────────────────────────
+
+async function fetchLatestVersion(
+  url: string,
+  currentVersion: string
+): Promise<string> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": `mink-self-update/${currentVersion}`,
+        Accept: "application/json",
+      },
+    });
+    if (!res.ok) {
+      throw new Error(`registry returned ${res.status}`);
+    }
+    const body = (await res.json()) as { version?: unknown };
+    if (typeof body.version !== "string") {
+      throw new Error("registry response missing version field");
+    }
+    return body.version;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── Package manager detection ───────────────────────────────────────────────
+
+function isOnPath(bin: string): boolean {
+  const result = spawnSync(bin, ["--version"], { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+export function detectPackageManager(cliPath: string): PackageManager | null {
+  // Honor explicit user override first.
+  const configured = resolveConfigValue("cli.auto-update-package-manager").value;
+  if (configured === "bun" && isOnPath("bun")) return "bun";
+  if (configured === "npm" && isOnPath("npm")) return "npm";
+
+  // Auto-detect: prefer bun if the install path looks bun-ish (e.g. ~/.bun/install).
+  const looksLikeBun = /[\\/]\.bun[\\/]/.test(cliPath);
+  if (looksLikeBun && isOnPath("bun")) return "bun";
+
+  if (isOnPath("npm")) return "npm";
+  if (isOnPath("bun")) return "bun";
+  return null;
+}
+
+function buildInstallCommand(pm: PackageManager, version: string): string[] {
+  const ref = `${PACKAGE_NAME}@${version}`;
+  if (pm === "bun") return ["bun", "add", "-g", ref];
+  return ["npm", "install", "-g", ref];
+}
+
+// ── Logging ─────────────────────────────────────────────────────────────────
+
+export function selfUpdateLogPath(): string {
+  return join(minkRoot(), "self-update.log");
+}
+
+function appendLogEntry(entry: Record<string, unknown>): void {
+  const path = selfUpdateLogPath();
+  const line = JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + "\n";
+  try {
+    safeAppendText(path, line);
+    rotateLogIfNeeded(path);
+  } catch {
+    // Logging failures must not crash the upgrade flow.
+  }
+}
+
+function rotateLogIfNeeded(path: string): void {
+  try {
+    const content = readFileSync(path, "utf-8");
+    const lines = content.split("\n");
+    if (lines.length <= LOG_MAX_LINES + 1) return;
+    const trimmed = lines.slice(lines.length - LOG_MAX_LINES - 1).join("\n");
+    atomicWriteText(path, trimmed);
+  } catch {
+    // ignore — best effort
+  }
+}
+
+// ── Main entry point ────────────────────────────────────────────────────────
+
+export async function runSelfUpgrade(opts: UpgradeOptions): Promise<UpgradeResult> {
+  const result = await runSelfUpgradeInner(opts);
+  appendLogEntry({ source: opts.source, ...result });
+  return result;
+}
+
+async function runSelfUpgradeInner(opts: UpgradeOptions): Promise<UpgradeResult> {
+  // 1. Hard kill switch.
+  if (process.env.MINK_DISABLE_AUTO_UPDATE === "1" && opts.source === "scheduler") {
+    return { status: "skipped", reason: "MINK_DISABLE_AUTO_UPDATE=1" };
+  }
+
+  // 2. Scheduler runs respect the cli.auto-update flag; manual runs do not.
+  if (opts.source === "scheduler") {
+    const enabled = resolveConfigValue("cli.auto-update").value;
+    if (enabled !== "true") {
+      return { status: "skipped", reason: "cli.auto-update is disabled" };
+    }
+  }
+
+  // 3. Resolve install info.
+  let info: CliInstallInfo;
+  try {
+    info = getInstallInfo();
+  } catch (err) {
+    return {
+      status: "error",
+      reason: err instanceof Error ? err.message : String(err),
+      transient: false,
+    };
+  }
+
+  // 4. Dev-mode guard — never auto-mutate the working source tree.
+  if (info.isDevMode) {
+    return {
+      status: "skipped",
+      reason: "running from source tree; refuse to self-upgrade in dev mode",
+    };
+  }
+
+  // 5. Fetch latest from registry.
+  let latest: string;
+  try {
+    latest = await fetchLatestVersion(
+      opts.registryUrlOverride ?? NPM_REGISTRY_URL,
+      info.currentVersion
+    );
+  } catch (err) {
+    return {
+      status: "error",
+      reason:
+        "failed to fetch latest version: " +
+        (err instanceof Error ? err.message : String(err)),
+      transient: true,
+    };
+  }
+
+  // 6. Compare versions.
+  const cmp = compareSemver(latest, info.currentVersion);
+  if (cmp <= 0 && !opts.force) {
+    return { status: "up-to-date", current: info.currentVersion, latest };
+  }
+
+  // 7. Resolve package manager (needed even for dry-run output).
+  const pm = detectPackageManager(info.cliPath);
+  if (!pm) {
+    return {
+      status: "error",
+      reason: "no package manager (npm or bun) available on PATH",
+      transient: false,
+    };
+  }
+
+  const cmd = buildInstallCommand(pm, latest);
+
+  if (opts.checkOnly) {
+    return {
+      status: "update-available",
+      current: info.currentVersion,
+      latest,
+      packageManager: pm,
+    };
+  }
+
+  if (opts.dryRun) {
+    return {
+      status: "would-upgrade",
+      current: info.currentVersion,
+      latest,
+      packageManager: pm,
+      command: cmd.join(" "),
+    };
+  }
+
+  // 8. Run install.
+  const stdio = opts.interactive ? "inherit" : "pipe";
+  const spawned = spawnSync(cmd[0], cmd.slice(1), {
+    stdio,
+    timeout: INSTALL_TIMEOUT_MS,
+  });
+  if (spawned.error) {
+    return {
+      status: "error",
+      reason: `install command failed to spawn: ${spawned.error.message}`,
+      transient: true,
+    };
+  }
+  if (spawned.status !== 0) {
+    const stderr = spawned.stderr ? spawned.stderr.toString().trim() : "";
+    return {
+      status: "error",
+      reason: `${cmd.join(" ")} exited with code ${spawned.status}${stderr ? ": " + stderr.slice(0, 500) : ""}`,
+      transient: true,
+    };
+  }
+
+  // 9. Verify post-install version by re-reading the on-disk package.json.
+  let verifiedVersion = latest;
+  try {
+    const pkg = JSON.parse(readFileSync(info.packageJsonPath, "utf-8"));
+    if (typeof pkg.version === "string") verifiedVersion = pkg.version;
+  } catch {
+    // package may have been replaced and the path may be stale; trust latest
+  }
+
+  return {
+    status: "upgraded",
+    from: info.currentVersion,
+    to: verifiedVersion,
+    packageManager: pm,
+  };
+}