@drewpayment/mink 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "src/**/*.ts",
     "dist/cli.js",
     "skills/**/*",
+    "agents/**/*",
     "dashboard/out"
   ],
   "publishConfig": {

package/src/cli.ts

@@ -143,6 +143,12 @@ switch (command) {
     break;
   }
 
+  case "agent": {
+    const { agent } = await import("./commands/agent");
+    await agent(cwd, process.argv.slice(3));
+    break;
+  }
+
   case "sync": {
     const { sync } = await import("./commands/sync");
     await sync(process.argv.slice(3));
@@ -213,6 +219,7 @@ switch (command) {
     console.log("  note list [filters]     List notes (--category, --tag, --recent)");
     console.log("  note search <term>      Full-text search across the vault");
     console.log("  skill install           Install /mink:note skill for Claude Code");
+    console.log("  agent                   Open a Claude Code session with the mink-agent persona");
     console.log();
     console.log("Devices & Sync:");
     console.log("  device                  Show current device info");
@@ -235,7 +242,7 @@ switch (command) {
     console.log();
     console.log("Automation & Analysis:");
     console.log("  dashboard [--port=N]    Open the real-time web dashboard");
-    console.log("  daemon <cmd>            Manage the background daemon (start|stop|restart|logs)");
+    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("  restore [backup]        Restore state from a backup");

package/src/commands/agent.ts

@@ -0,0 +1,245 @@
+import { join, resolve, dirname } from "path";
+import { homedir } from "os";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "fs";
+import { createHash } from "crypto";
+import { spawnSync } from "child_process";
+import { minkRoot } from "../core/paths";
+import { resolveVaultPath } from "../core/vault";
+
+const AGENT_NAME = "mink-agent";
+const TEMPLATE_FILE = `${AGENT_NAME}.md.tmpl`;
+const INSTALLED_FILE = `${AGENT_NAME}.md`;
+
+function getAgentTemplatePath(): string {
+  let dir = dirname(new URL(import.meta.url).pathname);
+  while (true) {
+    if (
+      existsSync(join(dir, "package.json")) &&
+      existsSync(join(dir, "agents", TEMPLATE_FILE))
+    ) {
+      return join(dir, "agents", TEMPLATE_FILE);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(
+    dirname(new URL(import.meta.url).pathname),
+    "../../agents",
+    TEMPLATE_FILE
+  );
+}
+
+function getMinkVersion(): string {
+  let dir = dirname(new URL(import.meta.url).pathname);
+  while (true) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (pkg.name && pkg.version) return pkg.version;
+      } catch {
+        // fall through
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "unknown";
+}
+
+function renderTemplate(template: string, vars: Record<string, string>): string {
+  let out = template;
+  for (const [key, value] of Object.entries(vars)) {
+    out = out.split(`{{${key}}}`).join(value);
+  }
+  return out;
+}
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+function claudeAgentsDir(): string {
+  return join(homedir(), ".claude", "agents");
+}
+
+function installedAgentPath(): string {
+  return join(claudeAgentsDir(), INSTALLED_FILE);
+}
+
+interface InstallResult {
+  action: "installed" | "updated" | "unchanged" | "skipped";
+  path: string;
+}
+
+function installAgentDefinition(opts: { force: boolean; skip: boolean }): InstallResult {
+  const templatePath = getAgentTemplatePath();
+  if (!existsSync(templatePath)) {
+    throw new Error(
+      `[mink agent] bundled agent template not found at ${templatePath}\n` +
+        "  This usually means the package was installed without bundled assets."
+    );
+  }
+
+  const installed = installedAgentPath();
+
+  if (opts.skip && existsSync(installed)) {
+    return { action: "skipped", path: installed };
+  }
+
+  const template = readFileSync(templatePath, "utf-8");
+  const rendered = renderTemplate(template, {
+    MINK_ROOT: minkRoot(),
+    VAULT_PATH: resolveVaultPath(),
+    MINK_VERSION: getMinkVersion(),
+  });
+
+  const exists = existsSync(installed);
+  if (!opts.force && exists) {
+    const current = readFileSync(installed, "utf-8");
+    if (sha256(current) === sha256(rendered)) {
+      return { action: "unchanged", path: installed };
+    }
+  }
+
+  mkdirSync(claudeAgentsDir(), { recursive: true });
+  writeFileSync(installed, rendered);
+  return {
+    action: exists ? "updated" : "installed",
+    path: installed,
+  };
+}
+
+function isClaudeOnPath(): boolean {
+  const result = spawnSync("claude", ["--version"], {
+    stdio: "ignore",
+  });
+  return !result.error && result.status === 0;
+}
+
+interface ParsedArgs {
+  noUpdate: boolean;
+  reinstall: boolean;
+  passthrough: string[];
+  showHelp: boolean;
+}
+
+function parseArgs(args: string[]): ParsedArgs {
+  const out: ParsedArgs = {
+    noUpdate: false,
+    reinstall: false,
+    passthrough: [],
+    showHelp: false,
+  };
+  let inPassthrough = false;
+  for (const arg of args) {
+    if (inPassthrough) {
+      out.passthrough.push(arg);
+      continue;
+    }
+    if (arg === "--") {
+      inPassthrough = true;
+      continue;
+    }
+    if (arg === "--no-update") {
+      out.noUpdate = true;
+      continue;
+    }
+    if (arg === "--reinstall") {
+      out.reinstall = true;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      out.showHelp = true;
+      continue;
+    }
+    out.passthrough.push(arg);
+  }
+  return out;
+}
+
+function printHelp(): void {
+  console.log("Usage: mink agent [options] [-- <claude args...>]");
+  console.log();
+  console.log("Open an interactive Claude Code session in your mink home with");
+  console.log("the mink-agent persona — a proactive note/wiki assistant.");
+  console.log();
+  console.log("Options:");
+  console.log("  --no-update    Don't refresh ~/.claude/agents/mink-agent.md if it exists");
+  console.log("  --reinstall    Force overwrite the installed agent definition");
+  console.log("  -- <args>      Forward remaining arguments to `claude`");
+  console.log();
+  console.log("Environment:");
+  console.log("  MINK_AGENT_NO_UPDATE=1   Equivalent to --no-update");
+  console.log();
+  console.log("The agent is bound to your mink root and resolved vault path. Changing");
+  console.log("`mink config wiki.path` triggers a refresh on the next launch.");
+}
+
+export async function agent(_cwd: string, rawArgs: string[]): Promise<void> {
+  const args = parseArgs(rawArgs);
+
+  if (args.showHelp) {
+    printHelp();
+    return;
+  }
+
+  const skipUpdate = args.noUpdate || process.env.MINK_AGENT_NO_UPDATE === "1";
+
+  const root = minkRoot();
+  if (!existsSync(root)) {
+    mkdirSync(root, { recursive: true });
+  }
+
+  let result: InstallResult;
+  try {
+    result = installAgentDefinition({
+      force: args.reinstall,
+      skip: skipUpdate && !args.reinstall,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(msg);
+    process.exit(1);
+  }
+
+  switch (result.action) {
+    case "installed":
+      console.log(`[mink] installed mink-agent definition (v${getMinkVersion()}) -> ${result.path}`);
+      break;
+    case "updated":
+      console.log(`[mink] updated mink-agent definition -> ${result.path}`);
+      break;
+    case "unchanged":
+    case "skipped":
+      // silent
+      break;
+  }
+
+  if (!isClaudeOnPath()) {
+    console.error("[mink agent] `claude` (Claude Code CLI) was not found on PATH.");
+    console.error("  Install Claude Code: https://claude.com/claude-code");
+    process.exit(1);
+  }
+
+  const claudeArgs = ["--agent", AGENT_NAME, ...args.passthrough];
+  const child = spawnSync("claude", claudeArgs, {
+    cwd: root,
+    stdio: "inherit",
+  });
+
+  if (child.error) {
+    console.error(`[mink agent] failed to launch claude: ${child.error.message}`);
+    process.exit(1);
+  }
+  if (typeof child.status === "number") {
+    process.exit(child.status);
+  }
+}

package/src/commands/daemon.ts

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync } from "fs";
 import { startDaemon, stopDaemon } from "../core/daemon";
+import { installService, uninstallService } from "../core/daemon-service";
 import { schedulerLogPath } from "../core/paths";
 
 export async function daemon(cwd: string, args: string[]): Promise<void> {
@@ -36,11 +37,21 @@ export async function daemon(cwd: string, args: string[]): Promise<void> {
       break;
     }
 
+    case "install":
+      installService({ force: args.includes("--force") });
+      break;
+
+    case "uninstall":
+      uninstallService();
+      break;
+
     default:
       console.error(
         `[mink] unknown daemon subcommand: ${subcommand ?? "(none)"}`
       );
-      console.error("Usage: mink daemon <start|stop|restart|logs>");
+      console.error(
+        "Usage: mink daemon <start|stop|restart|logs|install|uninstall>"
+      );
       process.exit(1);
   }
 }

package/src/commands/init.ts

@@ -106,6 +106,30 @@ function isMinkHook(entry: HookEntry | Record<string, unknown>): boolean {
   return false;
 }
 
+const MINK_RULE_CONTENT = `---
+description: Mink context management — automatic via hooks
+---
+
+This project uses **Mink** (\`@drewpayment/mink\`) for cross-session context management.
+
+## How it works
+- Mink runs automatically through Claude Code hooks configured in \`.claude/settings.json\` (SessionStart, PreToolUse, PostToolUse, Stop).
+- All state lives in \`~/.mink/\` on the user's machine — **not** in this repository. Do not create or write to any in-repo state directory (no \`.wolf/\`, \`.mink/\`, etc.).
+- Read intelligence, write enforcement, bug memory, and the token ledger are handled by the hooks. You do not need to manually read or update any state files.
+
+## When to act on Mink
+- If the user asks to "save a note", "remember this", "log this to my wiki", or similar, use the \`mink-note\` skill — it captures into the user's \`~/.mink/\` vault.
+- If a hook surfaces a learning, past bug, or repeat-read warning, treat that as authoritative project memory and follow it.
+- The \`mink dashboard\` and \`mink agent\` commands are user tools — do not invoke them on the user's behalf.
+`;
+
+export function writeMinkRule(cwd: string): string {
+  const rulePath = resolve(cwd, ".claude", "rules", "mink.md");
+  mkdirSync(dirname(rulePath), { recursive: true });
+  atomicWriteText(rulePath, MINK_RULE_CONTENT);
+  return rulePath;
+}
+
 export function mergeHooksIntoSettings(
   settingsPath: string,
   newHooks: HooksConfig
@@ -148,6 +172,7 @@ export async function init(cwd: string): Promise<void> {
   }
 
   mergeHooksIntoSettings(settingsPath, hooks);
+  const rulePath = writeMinkRule(cwd);
 
   mkdirSync(dir, { recursive: true });
 
@@ -173,12 +198,14 @@ export async function init(cwd: string): Promise<void> {
     console.log(`[mink] upgrade complete`);
     console.log(`  project:  ${projectId}`);
     console.log(`  hooks:    ${settingsPath}`);
+    console.log(`  rule:     ${rulePath}`);
   } else {
     console.log(`[mink] initialized`);
     console.log(`  project:  ${projectId}`);
     console.log(`  state:    ${dir}`);
     console.log(`  runtime:  ${runtime}`);
     console.log(`  hooks:    ${settingsPath}`);
+    console.log(`  rule:     ${rulePath}`);
   }
 
   // Run initial scan

package/src/core/daemon-service.ts

@@ -0,0 +1,227 @@
+import { execSync } from "child_process";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+import { resolveCliPath } from "../commands/init";
+
+export type ServicePlatform = "systemd" | "launchd";
+
+export interface ServiceInvocation {
+  /** Absolute path to the executable used in ExecStart / ProgramArguments[0]. */
+  executable: string;
+  /** Arguments following the executable (e.g. ["daemon", "start"] or ["<cli.js>", "daemon", "start"]). */
+  args: string[];
+  /** Directory that should be added to PATH for the service's environment. */
+  pathDir: string;
+}
+
+export interface ServicePaths {
+  unitFile: string;
+  unitDir: string;
+}
+
+export function detectPlatform(): ServicePlatform | null {
+  if (process.platform === "linux") return "systemd";
+  if (process.platform === "darwin") return "launchd";
+  return null;
+}
+
+/**
+ * Resolve how the service should invoke mink.
+ *
+ * Prefer argv[1] when it is a bin shim (no .js/.ts extension) — that is the
+ * stable, install-method-agnostic entry point (e.g. ~/.bun/bin/mink). Fall
+ * back to invoking the compiled bundle via the current interpreter when
+ * running from source or from a non-shim entry.
+ */
+export function resolveServiceInvocation(): ServiceInvocation {
+  const entry = process.argv[1];
+  if (entry && !/\.(js|ts|mjs|cjs)$/.test(entry) && existsSync(entry)) {
+    return {
+      executable: entry,
+      args: ["daemon", "start"],
+      pathDir: dirname(entry),
+    };
+  }
+
+  const cliPath = resolveCliPath();
+  const interpreter = process.execPath;
+  return {
+    executable: interpreter,
+    args: [cliPath, "daemon", "start"],
+    pathDir: dirname(interpreter),
+  };
+}
+
+export function servicePaths(platform: ServicePlatform): ServicePaths {
+  const home = homedir();
+  if (platform === "systemd") {
+    const unitDir = join(home, ".config", "systemd", "user");
+    return { unitDir, unitFile: join(unitDir, "mink-daemon.service") };
+  }
+  const unitDir = join(home, "Library", "LaunchAgents");
+  return { unitDir, unitFile: join(unitDir, "com.mink.daemon.plist") };
+}
+
+/** Build a systemd user unit file for the mink daemon. */
+export function renderSystemdUnit(inv: ServiceInvocation): string {
+  const execStart = [inv.executable, ...inv.args].join(" ");
+  const stopArgs = inv.args.map((a) => (a === "start" ? "stop" : a));
+  const execStop = [inv.executable, ...stopArgs].join(" ");
+  const pathEnv = `${inv.pathDir}:/usr/local/bin:/usr/bin:/bin`;
+
+  return [
+    "[Unit]",
+    "Description=Mink background daemon",
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=forking",
+    `ExecStart=${execStart}`,
+    `ExecStop=${execStop}`,
+    "Restart=on-failure",
+    "RestartSec=10",
+    `Environment="PATH=${pathEnv}"`,
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+}
+
+/** Build a launchd user agent plist for the mink daemon. */
+export function renderLaunchdPlist(inv: ServiceInvocation, logPath: string): string {
+  const programArgs = [inv.executable, ...inv.args]
+    .map((a) => `    <string>${escapeXml(a)}</string>`)
+    .join("\n");
+  const pathEnv = `${inv.pathDir}:/usr/local/bin:/usr/bin:/bin`;
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "  <key>Label</key>",
+    "  <string>com.mink.daemon</string>",
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    programArgs,
+    "  </array>",
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>KeepAlive</key>",
+    "  <dict>",
+    "    <key>SuccessfulExit</key>",
+    "    <false/>",
+    "  </dict>",
+    "  <key>EnvironmentVariables</key>",
+    "  <dict>",
+    "    <key>PATH</key>",
+    `    <string>${escapeXml(pathEnv)}</string>`,
+    "  </dict>",
+    "  <key>StandardOutPath</key>",
+    `  <string>${escapeXml(logPath)}</string>`,
+    "  <key>StandardErrorPath</key>",
+    `  <string>${escapeXml(logPath)}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export interface InstallOptions {
+  force?: boolean;
+}
+
+export function installService(options: InstallOptions = {}): void {
+  const platform = detectPlatform();
+  if (!platform) {
+    console.error(
+      `[mink] daemon install is not supported on ${process.platform} (supported: linux, darwin)`
+    );
+    process.exit(1);
+  }
+
+  const paths = servicePaths(platform);
+  if (existsSync(paths.unitFile) && !options.force) {
+    console.error(`[mink] unit file already exists: ${paths.unitFile}`);
+    console.error(
+      "       re-run with --force to overwrite, or run `mink daemon uninstall` first"
+    );
+    process.exit(1);
+  }
+
+  const inv = resolveServiceInvocation();
+  mkdirSync(paths.unitDir, { recursive: true });
+
+  if (platform === "systemd") {
+    writeFileSync(paths.unitFile, renderSystemdUnit(inv));
+    try {
+      execSync("systemctl --user daemon-reload", { stdio: "ignore" });
+    } catch {
+      // systemctl may be unavailable (e.g. CI, WSL1) — the file is still written.
+    }
+    console.log(`[mink] wrote ${paths.unitFile}`);
+    console.log("[mink] next steps:");
+    console.log("  systemctl --user enable --now mink-daemon.service");
+    console.log("  # To survive logout (one-time, requires sudo):");
+    console.log(`  sudo loginctl enable-linger ${process.env.USER ?? "$USER"}`);
+  } else {
+    const { schedulerLogPath } = require("./paths") as typeof import("./paths");
+    writeFileSync(paths.unitFile, renderLaunchdPlist(inv, schedulerLogPath()));
+    console.log(`[mink] wrote ${paths.unitFile}`);
+    console.log("[mink] next steps:");
+    console.log(`  launchctl load -w ${paths.unitFile}`);
+    console.log("  # Launch agents run automatically on login; no lingering needed.");
+  }
+}
+
+export function uninstallService(): void {
+  const platform = detectPlatform();
+  if (!platform) {
+    console.error(
+      `[mink] daemon uninstall is not supported on ${process.platform} (supported: linux, darwin)`
+    );
+    process.exit(1);
+  }
+
+  const paths = servicePaths(platform);
+  if (!existsSync(paths.unitFile)) {
+    console.log(`[mink] no unit file at ${paths.unitFile} — nothing to uninstall`);
+    return;
+  }
+
+  if (platform === "systemd") {
+    try {
+      execSync("systemctl --user disable --now mink-daemon.service", {
+        stdio: "ignore",
+      });
+    } catch {
+      // Service may not be enabled / running — proceed to file removal.
+    }
+    unlinkSync(paths.unitFile);
+    try {
+      execSync("systemctl --user daemon-reload", { stdio: "ignore" });
+    } catch {
+      // Ignore.
+    }
+    console.log(`[mink] removed ${paths.unitFile}`);
+  } else {
+    try {
+      execSync(`launchctl unload -w ${paths.unitFile}`, { stdio: "ignore" });
+    } catch {
+      // Ignore — may not be loaded.
+    }
+    unlinkSync(paths.unitFile);
+    console.log(`[mink] removed ${paths.unitFile}`);
+  }
+}