@drewpayment/mink 0.9.1 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "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));
@@ -213,7 +219,7 @@ switch (command) {
     console.log("  config [key] [value]    Manage global user settings");
     console.log();
     console.log("Notes & Wiki:");
-    console.log("  wiki <cmd>              Manage the notes/wiki vault (init|status|link|unlink|links|rebuild-index|organize)");
+    console.log("  wiki <cmd>              Manage the notes/wiki vault (init|status|link|unlink|links|rebuild-index|scan|organize)");
     console.log("  note \"text\"             Capture a note to the vault");
     console.log("  note --daily [text]     Create or append to today's daily note");
     console.log("  note list [filters]     List notes (--category, --tag, --recent)");
@@ -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/scan.ts

@@ -1,8 +1,13 @@
 import { readFileSync } from "fs";
-import { join } from "path";
+import { join, relative } from "path";
 import { fileIndexPath, configPath } from "../core/paths";
 import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
-import { scanProject, loadConfig, getExcludes } from "../core/scanner";
+import {
+  scanProject,
+  scanProjectWithStats,
+  loadConfig,
+  getExcludes,
+} from "../core/scanner";
 import { extractDescription } from "../core/description";
 import { estimateTokens } from "../core/token-estimate";
 import {
@@ -13,6 +18,11 @@ import {
 } from "../core/index-store";
 import type { FileIndex, FileIndexEntry } from "../types/file-index";
 
+function configRelativePath(cfgPath: string, cwd: string): string {
+  const rel = relative(cwd, cfgPath);
+  return rel.startsWith("..") ? cfgPath : rel;
+}
+
 function loadExistingIndex(indexPath: string): FileIndex {
   const raw = safeReadJson(indexPath);
   if (isFileIndex(raw)) return raw;
@@ -64,7 +74,8 @@ export function scan(cwd: string, options: { check: boolean }): void {
   const start = Date.now();
   const index = loadExistingIndex(idxPath);
 
-  const scanned = scanProject(cwd, excludes, maxFiles);
+  const stats = scanProjectWithStats(cwd, excludes, maxFiles);
+  const scanned = stats.files;
 
   // Build new entries, preserving lifetime counters
   const newIndex = createEmptyIndex();
@@ -95,7 +106,19 @@ export function scan(cwd: string, options: { check: boolean }): void {
   atomicWriteJson(idxPath, newIndex);
 
   const elapsed = Date.now() - start;
-  console.log(
-    `[mink] indexed ${newIndex.header.totalFiles} files in ${elapsed}ms`
-  );
+  if (stats.truncated > 0) {
+    console.log(
+      `[mink] scanned ${stats.totalScanned} files; indexed ${newIndex.header.totalFiles} most recent in ${elapsed}ms`
+    );
+    console.log(
+      `  ${stats.truncated} files past maxFiles=${maxFiles} were not indexed`
+    );
+    console.log(
+      `  raise the cap by setting "maxFiles" in ${configRelativePath(cfgPath, cwd)}`
+    );
+  } else {
+    console.log(
+      `[mink] indexed ${newIndex.header.totalFiles} files in ${elapsed}ms`
+    );
+  }
 }

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/commands/wiki.ts

@@ -14,7 +14,11 @@ import {
 import { atomicWriteJson } from "../core/fs-utils";
 import { setConfigValue } from "../core/global-config";
 import { seedTemplates } from "../core/vault-templates";
-import { rebuildVaultIndex, loadVaultIndex } from "../core/note-index";
+import {
+  rebuildVaultIndex,
+  loadVaultIndex,
+  vaultIndexStaleness,
+} from "../core/note-index";
 import { updateMasterIndex } from "../core/note-linker";
 import type { VaultManifest, NoteCategory } from "../types/note";
 
@@ -32,6 +36,7 @@ export async function wiki(
       wikiStatus();
       break;
     case "rebuild-index":
+    case "scan":
       wikiRebuildIndex();
       break;
     case "organize":
@@ -51,7 +56,8 @@ export async function wiki(
       console.log();
       console.log("  init                Initialize the notes/wiki vault");
       console.log("  status              Show vault statistics");
-      console.log("  rebuild-index       Full rescan and reindex of vault");
+      console.log("  rebuild-index       Full rescan and reindex of vault (alias: scan)");
+      console.log("  scan                Alias for rebuild-index");
       console.log("  organize            List inbox notes needing categorization");
       console.log("  link <path> [name]  Symlink external notes into the vault");
       console.log("  unlink <name>       Remove a symlinked directory from the vault");
@@ -174,6 +180,13 @@ function wikiStatus(): void {
   }
 
   const vaultPath = resolveVaultPath();
+  const staleness = vaultIndexStaleness();
+  if (staleness.isStale) {
+    console.log(
+      `[mink] vault index is stale (${staleness.reason}) — rebuilding...`
+    );
+    rebuildVaultIndex();
+  }
   const index = loadVaultIndex();
 
   const categoryCounts: Record<string, number> = {
@@ -200,7 +213,10 @@ function wikiStatus(): void {
   }
   console.log();
   console.log(
-    `  last indexed: ${index.lastScanTimestamp || "never"}`
+    `  last full scan: ${index.lastFullScanTimestamp || "never"}`
+  );
+  console.log(
+    `  last update:    ${index.lastScanTimestamp || "never"}`
   );
 
   const links = listLinks();

package/src/core/note-index.ts

@@ -7,6 +7,7 @@ import type { VaultIndex, VaultIndexEntry, NoteCategory } from "../types/note";
 export function createEmptyVaultIndex(): VaultIndex {
   return {
     lastScanTimestamp: "",
+    lastFullScanTimestamp: "",
     totalNotes: 0,
     entries: {},
   };
@@ -182,7 +183,9 @@ export function rebuildVaultIndex(): VaultIndex {
     }
   }
 
-  index.lastScanTimestamp = new Date().toISOString();
+  const now = new Date().toISOString();
+  index.lastScanTimestamp = now;
+  index.lastFullScanTimestamp = now;
   saveVaultIndex(index);
   return index;
 }
@@ -219,6 +222,52 @@ export function getRecentNotes(n: number): VaultIndexEntry[] {
     .slice(0, n);
 }
 
+export interface VaultStaleness {
+  isStale: boolean;
+  reason: string | null;
+  diskCount: number;
+  indexCount: number;
+  lastFullScan: string | null;
+}
+
+export function vaultIndexStaleness(): VaultStaleness {
+  const index = loadVaultIndex();
+  const root = resolveVaultPath();
+  const diskCount = collectAllMarkdown(root).length;
+  const indexCount = Object.keys(index.entries).length;
+  const lastFullScan = index.lastFullScanTimestamp || null;
+
+  if (!lastFullScan) {
+    return {
+      isStale: true,
+      reason: "no full scan on record",
+      diskCount,
+      indexCount,
+      lastFullScan: null,
+    };
+  }
+
+  const delta = Math.abs(diskCount - indexCount);
+  const threshold = Math.max(5, Math.floor(diskCount * 0.05));
+  if (delta >= threshold) {
+    return {
+      isStale: true,
+      reason: `${diskCount} files on disk but ${indexCount} in index`,
+      diskCount,
+      indexCount,
+      lastFullScan,
+    };
+  }
+
+  return {
+    isStale: false,
+    reason: null,
+    diskCount,
+    indexCount,
+    lastFullScan,
+  };
+}
+
 interface ScannedMarkdown {
   absolutePath: string;
   relativePath: string;

package/src/core/scanner.ts

@@ -87,13 +87,29 @@ export function getExcludes(config: ProjectConfig): string[] {
   return [...DEFAULT_EXCLUDES, ...(config.excludePatterns ?? [])];
 }
 
-export function scanProject(
+export interface ScanStats {
+  files: ScannedFile[];
+  totalScanned: number;
+  truncated: number;
+}
+
+export function scanProjectWithStats(
   projectRoot: string,
   excludes: string[],
   maxFiles: number = DEFAULT_MAX_FILES
-): ScannedFile[] {
+): ScanStats {
   const results: ScannedFile[] = [];
   walkDirectory(projectRoot, projectRoot, excludes, results);
   results.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return results.slice(0, maxFiles);
+  const totalScanned = results.length;
+  const files = results.slice(0, maxFiles);
+  return { files, totalScanned, truncated: totalScanned - files.length };
+}
+
+export function scanProject(
+  projectRoot: string,
+  excludes: string[],
+  maxFiles: number = DEFAULT_MAX_FILES
+): ScannedFile[] {
+  return scanProjectWithStats(projectRoot, excludes, maxFiles).files;
 }