@drewpayment/mink 0.1.0 → 0.2.0

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {
-    "mink": "./src/cli.ts"
+    "mink": "./dist/cli.js"
   },
   "scripts": {
+    "build": "bun build src/cli.ts --outfile dist/cli.js --target node --format esm && node -e \"const f=require('fs');let c=f.readFileSync('dist/cli.js','utf8');c=c.replace(/^#!.*\\n/,'');f.writeFileSync('dist/cli.js','#!/usr/bin/env node\\n'+c);f.chmodSync('dist/cli.js',0o755)\"",
+    "postinstall": "bun run build 2>/dev/null || true",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
     "test:watch": "bun test --watch",
@@ -14,7 +16,9 @@
     "dashboard:build": "cd dashboard && bun run build"
   },
   "files": [
-    "src/**/*.ts"
+    "src/**/*.ts",
+    "dist/cli.js",
+    "skills/**/*"
   ],
   "publishConfig": {
     "access": "public"

package/skills/mink-note/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: mink-note
+description: Capture and organize notes in your Mink knowledge vault. Use when the user wants to save a note, log a thought, record a meeting, or capture any knowledge.
+---
+
+# /mink:note — Intelligent Note Capture
+
+You are an intelligent note-taking assistant powered by [Mink](https://github.com/drewpayment/mink). When this skill is invoked, you help the user capture, categorize, and connect notes in their Mink wiki vault.
+
+## Prerequisites
+
+Mink must be installed and a vault must be initialized:
+
+```bash
+# Install Mink
+bun add -g @drewpayment/mink
+
+# Initialize the vault (once)
+mink wiki init
+```
+
+## Your Role
+
+You are the **smart orchestrator**. The `mink note` CLI is a dumb writer — it takes explicit flags and writes files. Your job is to:
+
+1. Understand what the user wants to capture
+2. Analyze the vault context to make smart decisions
+3. Call `mink note` with the right flags
+4. Optionally update related notes with backlinks
+
+## Workflow
+
+### Step 1: Understand the Note
+
+If the user provided text after `/mink:note`, use that as the note content. Otherwise, ask what they'd like to capture.
+
+### Step 2: Gather Vault Context
+
+Run these commands to understand the current vault state:
+
+```bash
+mink note list --recent 10
+mink wiki status
+```
+
+Also read the vault index for tag vocabulary:
+
+```bash
+cat "$(mink config wiki.path)/.mink-index.json" 2>/dev/null | head -100
+```
+
+### Step 3: Analyze and Categorize
+
+Based on the note content and vault context, determine:
+
+- **Title**: A clear, descriptive title (not the raw text)
+- **Category**: One of `inbox`, `projects`, `areas`, `resources`, `archives`
+  - `projects` — Has a deadline, milestone, or deliverable. Use `--project <slug>` if it relates to a known Mink project.
+  - `areas` — Ongoing responsibility, standard, or recurring concern
+  - `resources` — Reference material, how-to, guide, or knowledge to look up later
+  - `archives` — Completed work, historical record
+  - `inbox` — Only if genuinely unclear
+- **Tags**: 1-5 relevant tags from the existing tag vocabulary when possible, new tags when necessary. Use lowercase, hyphenated format.
+- **Wikilinks**: If the note mentions people, projects, or concepts that exist as notes in the vault, include `[[wikilinks]]` in the body text.
+
+### Step 4: Create the Note
+
+Run the `mink note` command with all determined flags:
+
+```bash
+mink note --title "Title Here" \
+  --body "Note body with [[wikilinks]] to related notes..." \
+  --category <category> \
+  --tags "tag1,tag2,tag3" \
+  --project <project-slug>  # only if project-linked
+```
+
+### Step 5: Report Back
+
+Tell the user:
+- Where the note was saved
+- What category and tags were applied
+- Any wikilinks that were added
+- Suggest related notes they might want to update
+
+## Special Modes
+
+### Daily Note
+If the user says something like "add to my daily" or "daily note":
+```bash
+mink note --daily "The content to append"
+```
+
+### Meeting Note
+If the user describes a meeting:
+```bash
+mink note --template meeting --title "Meeting: Topic" --body "..." --category areas --tags "meeting,..."
+```
+
+### File Ingestion
+If the user wants to add an existing file to the vault:
+```bash
+mink note --file ./path/to/file.md --category resources --tags "..."
+```
+
+## CLI Reference
+
+```bash
+mink note "Quick thought"                              # Quick capture to inbox
+mink note --title "Title" --body "Content"             # Structured note
+mink note --title "T" --body "B" --category areas      # Explicit category
+mink note --title "T" --body "B" --tags "a,b,c"        # With tags
+mink note --project my-api --title "T" --body "B"      # Project-linked
+mink note --daily "Today's insight"                     # Append to daily note
+mink note --daily                                       # Create today's daily
+mink note --template meeting --title "Sprint Planning"  # From template
+mink note --file ./scratch.md                           # Ingest external file
+mink note list [--category X] [--tag X] [--recent N]   # List notes
+mink note search <term>                                 # Full-text search
+mink wiki status                                        # Vault statistics
+mink wiki rebuild-index                                 # Rescan vault
+```
+
+## Guidelines
+
+- Always prefer existing tags over inventing new ones (check the vault index)
+- Use `[[wikilinks]]` for any person, project, or concept that has a note in the vault
+- Keep titles concise but descriptive — they become filenames
+- When in doubt about category, use `inbox` — the user can recategorize later
+- If the note relates to the current working directory's Mink project, use `--project`
+- Don't over-tag. 2-3 tags is usually right.

package/src/cli.ts

@@ -119,6 +119,24 @@ switch (command) {
     break;
   }
 
+  case "wiki": {
+    const { wiki } = await import("./commands/wiki");
+    await wiki(cwd, process.argv.slice(3));
+    break;
+  }
+
+  case "note": {
+    const { note } = await import("./commands/note");
+    await note(cwd, process.argv.slice(3));
+    break;
+  }
+
+  case "skill": {
+    const { skill } = await import("./commands/skill");
+    await skill(process.argv.slice(3));
+    break;
+  }
+
   case "bug-search": {
     const { bugSearch } = await import("./commands/bug-search");
     bugSearch(cwd, process.argv.slice(3).join(" "));
@@ -139,6 +157,24 @@ switch (command) {
     break;
   }
 
+  case "version":
+  case "--version":
+  case "-v": {
+    const { resolve, dirname } = await import("path");
+    const cliPath = resolve(dirname(new URL(import.meta.url).pathname));
+    const { readFileSync } = await import("fs");
+    try {
+      const pkg = JSON.parse(
+        readFileSync(resolve(cliPath, "../package.json"), "utf-8")
+      );
+      console.log(`mink ${pkg.version}`);
+    } catch {
+      console.log("mink (unknown version)");
+    }
+    console.log(`  location: ${cliPath}`);
+    break;
+  }
+
   case "help":
   case "--help":
   case "-h":
@@ -151,6 +187,16 @@ switch (command) {
     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");
+    console.log();
+    console.log("Notes & Wiki:");
+    console.log("  wiki <cmd>              Manage the notes/wiki vault (init|status|rebuild-index|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)");
+    console.log("  note search <term>      Full-text search across the vault");
+    console.log("  skill install           Install /mink:note skill for Claude Code");
+    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("  cron <cmd> [id]         Manage scheduled tasks (list|run|retry)");

package/src/commands/init.ts

@@ -3,7 +3,13 @@ import { mkdirSync, existsSync } from "fs";
 import { resolve, dirname, basename, join } from "path";
 import { projectDir, projectMetaPath } from "../core/paths";
 import { generateProjectId } from "../core/project-id";
-import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
+import { atomicWriteJson, atomicWriteText, safeReadJson } from "../core/fs-utils";
+import {
+  isWikiEnabled,
+  isVaultInitialized,
+  isInsideVault,
+  vaultProjects,
+} from "../core/vault";
 
 interface HookCommand {
   type: "command";
@@ -26,11 +32,39 @@ export function detectRuntime(): "bun" | "node" {
   }
 }
 
+export function resolveCliPath(): string {
+  // When running from the compiled bundle, import.meta.url points to dist/cli.js
+  // When running from source, it points to src/commands/init.ts
+  const selfPath = new URL(import.meta.url).pathname;
+  const selfDir = dirname(selfPath);
+
+  // If we're running from dist/cli.js, use that directly
+  if (selfPath.endsWith("dist/cli.js")) {
+    return selfPath;
+  }
+
+  // Check for compiled dist/cli.js relative to project root
+  // From src/commands/ go up two levels to project root
+  const projectRoot = resolve(selfDir, "../..");
+  const distPath = join(projectRoot, "dist", "cli.js");
+  if (existsSync(distPath)) return distPath;
+
+  // Fall back to src/cli.ts (requires bun)
+  return resolve(selfDir, "../cli.ts");
+}
+
 export function buildHooksConfig(
   runtime: "bun" | "node",
   cliPath: string
 ): HooksConfig {
-  const prefix = runtime === "bun" ? `bun run ${cliPath}` : `node ${cliPath}`;
+  // If using compiled JS, always use node (universally available)
+  // If using .ts source, must use bun
+  const isTsSource = cliPath.endsWith(".ts");
+  const prefix = isTsSource
+    ? `bun run ${cliPath}`
+    : runtime === "bun"
+      ? `bun run ${cliPath}`
+      : `node ${cliPath}`;
   const hook = (cmd: string): HookCommand[] => [{ type: "command", command: cmd }];
   return {
     SessionStart: [{ matcher: "", hooks: hook(`${prefix} session-start`) }],
@@ -100,7 +134,7 @@ function isExistingInstallation(cwd: string): boolean {
 
 export async function init(cwd: string): Promise<void> {
   const runtime = detectRuntime();
-  const cliPath = resolve(dirname(new URL(import.meta.url).pathname), "../cli.ts");
+  const cliPath = resolveCliPath();
   const hooks = buildHooksConfig(runtime, cliPath);
   const settingsPath = resolve(cwd, ".claude", "settings.json");
   const dir = projectDir(cwd);
@@ -119,6 +153,10 @@ export async function init(cwd: string): Promise<void> {
 
   const projectId = generateProjectId(cwd);
 
+  // Detect notes project type
+  const isNotesProject =
+    isWikiEnabled() && isVaultInitialized() && isInsideVault(cwd);
+
   // Write project metadata
   const metaPath = projectMetaPath(cwd);
   const existingMeta = safeReadJson(metaPath) as Record<string, unknown> | null;
@@ -128,6 +166,7 @@ export async function init(cwd: string): Promise<void> {
     name: basename(cwd),
     initTimestamp: existingMeta?.initTimestamp ?? new Date().toISOString(),
     version: "0.1.0",
+    ...(isNotesProject ? { projectType: "notes" } : {}),
   });
 
   if (upgrading) {
@@ -152,8 +191,42 @@ export async function init(cwd: string): Promise<void> {
   if (!existsSync(memPath)) {
     const { seedLearningMemory } = await import("../core/seed");
     const { serializeLearningMemory } = await import("../core/learning-memory");
-    const { atomicWriteText } = await import("../core/fs-utils");
     const mem = seedLearningMemory(cwd);
     atomicWriteText(memPath, serializeLearningMemory(mem));
   }
+
+  // Create wiki project overview if wiki is enabled
+  if (isWikiEnabled() && isVaultInitialized() && !isNotesProject) {
+    try {
+      const projectSlug = basename(cwd);
+      const overviewPath = join(vaultProjects(projectSlug), "overview.md");
+      if (!existsSync(overviewPath)) {
+        const now = new Date().toISOString();
+        const overview = [
+          `---`,
+          `created: "${now}"`,
+          `updated: "${now}"`,
+          `tags: [project, ${projectSlug}]`,
+          `category: projects`,
+          `---`,
+          ``,
+          `# ${projectSlug}`,
+          ``,
+          `**Path**: \`${cwd}\``,
+          `**Initialized**: ${now.split("T")[0]}`,
+          ``,
+          `## Overview`,
+          ``,
+          `## Key Decisions`,
+          ``,
+          `## Links`,
+          ``,
+        ].join("\n");
+        atomicWriteText(overviewPath, overview);
+        console.log(`  wiki:     ${overviewPath}`);
+      }
+    } catch {
+      // Non-critical — don't fail init
+    }
+  }
 }

package/src/commands/note.ts

@@ -0,0 +1,267 @@
+import { resolve } from "path";
+import { existsSync, readFileSync } from "fs";
+import {
+  isVaultInitialized,
+  isWikiEnabled,
+  resolveVaultPath,
+} from "../core/vault";
+import { resolveConfigValue } from "../core/global-config";
+import { generateProjectId } from "../core/project-id";
+import {
+  createNote,
+  appendToDaily,
+  ingestFile,
+  slugifyTitle,
+} from "../core/note-writer";
+import {
+  updateVaultIndexForFile,
+  searchVaultIndex,
+  getRecentNotes,
+  loadVaultIndex,
+} from "../core/note-index";
+import { updateMasterIndex } from "../core/note-linker";
+import type { NoteCategory, NoteMetadata } from "../types/note";
+
+export async function note(
+  cwd: string,
+  args: string[]
+): Promise<void> {
+  if (!isWikiEnabled()) {
+    console.error("[mink] wiki feature is disabled");
+    console.error("  Enable with: mink config wiki.enabled true");
+    process.exit(1);
+  }
+
+  if (!isVaultInitialized()) {
+    console.error("[mink] vault not initialized");
+    console.error("  Run 'mink wiki init' first.");
+    process.exit(1);
+  }
+
+  // Handle subcommands
+  if (args[0] === "list") {
+    noteList(args.slice(1));
+    return;
+  }
+  if (args[0] === "search") {
+    noteSearch(args.slice(1).join(" "));
+    return;
+  }
+
+  // Parse flags
+  const parsed = parseNoteArgs(args);
+
+  // Handle daily note
+  if (parsed.daily) {
+    const date = new Date().toISOString().split("T")[0];
+    const content = parsed.positional || parsed.body || "";
+    const filePath = appendToDaily(date, content);
+    updateVaultIndexForFile(
+      filePath,
+      readFileSync(filePath, "utf-8")
+    );
+    console.log(`[mink] daily note: ${filePath}`);
+    return;
+  }
+
+  // Handle file ingestion
+  if (parsed.file) {
+    const sourcePath = resolve(cwd, parsed.file);
+    if (!existsSync(sourcePath)) {
+      console.error(`[mink] file not found: ${sourcePath}`);
+      process.exit(1);
+    }
+    const result = ingestFile(sourcePath, {
+      category: parsed.category,
+      tags: parsed.tags,
+      projectSlug: parsed.project,
+      sourceProject: detectSourceProject(cwd),
+    });
+    updateVaultIndexForFile(result.filePath, result.content);
+    console.log(`[mink] ingested: ${result.filePath}`);
+    return;
+  }
+
+  // Regular note creation
+  const title =
+    parsed.title ||
+    (parsed.positional
+      ? parsed.positional.split("\n")[0].slice(0, 80)
+      : `note-${Date.now()}`);
+
+  const body = parsed.body || parsed.positional || "";
+
+  const meta: NoteMetadata = {
+    title,
+    category: parsed.category,
+    tags: parsed.tags,
+    created: new Date().toISOString(),
+    updated: new Date().toISOString(),
+    template: parsed.template,
+    projectSlug: parsed.project,
+    sourceProject: detectSourceProject(cwd),
+    body,
+  };
+
+  const result = createNote(meta);
+  updateVaultIndexForFile(result.filePath, result.content);
+  updateMasterIndex(resolveVaultPath());
+
+  const tagsStr =
+    meta.tags.length > 0 ? ` [${meta.tags.join(", ")}]` : "";
+  console.log(
+    `[mink] note saved: ${result.filePath}${tagsStr}`
+  );
+}
+
+interface ParsedNoteArgs {
+  title: string;
+  body: string;
+  category: NoteCategory;
+  tags: string[];
+  project: string;
+  template: string;
+  daily: boolean;
+  file: string;
+  positional: string;
+}
+
+function parseNoteArgs(args: string[]): ParsedNoteArgs {
+  const result: ParsedNoteArgs = {
+    title: "",
+    body: "",
+    category: resolveConfigValue("notes.default-category").value as NoteCategory,
+    tags: [],
+    project: "",
+    template: "",
+    daily: false,
+    file: "",
+    positional: "",
+  };
+
+  const positionalParts: string[] = [];
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === "--title" && i + 1 < args.length) {
+      result.title = args[++i];
+    } else if (arg === "--body" && i + 1 < args.length) {
+      result.body = args[++i];
+    } else if (arg === "--category" && i + 1 < args.length) {
+      result.category = args[++i] as NoteCategory;
+    } else if (arg === "--tags" && i + 1 < args.length) {
+      result.tags = args[++i].split(",").map((t) => t.trim()).filter(Boolean);
+    } else if (arg === "--project" && i + 1 < args.length) {
+      result.project = args[++i];
+      if (result.category === "inbox") {
+        result.category = "projects";
+      }
+    } else if (arg === "--template" && i + 1 < args.length) {
+      result.template = args[++i];
+    } else if (arg === "--daily") {
+      result.daily = true;
+    } else if (arg === "--file" && i + 1 < args.length) {
+      result.file = args[++i];
+    } else if (!arg.startsWith("--")) {
+      positionalParts.push(arg);
+    }
+
+    i++;
+  }
+
+  result.positional = positionalParts.join(" ");
+  return result;
+}
+
+function detectSourceProject(cwd: string): string | undefined {
+  try {
+    const vaultPath = resolveVaultPath();
+    // Don't mark notes created from within the vault itself
+    if (cwd.startsWith(vaultPath)) return undefined;
+    return generateProjectId(cwd);
+  } catch {
+    return undefined;
+  }
+}
+
+function noteList(args: string[]): void {
+  const index = loadVaultIndex();
+  let entries = Object.values(index.entries);
+
+  // Parse filters
+  let categoryFilter = "";
+  let tagFilter = "";
+  let recent = 20;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--category" && i + 1 < args.length) {
+      categoryFilter = args[++i];
+    } else if (args[i] === "--tag" && i + 1 < args.length) {
+      tagFilter = args[++i];
+    } else if (args[i] === "--recent" && i + 1 < args.length) {
+      recent = parseInt(args[++i], 10) || 20;
+    }
+  }
+
+  if (categoryFilter) {
+    entries = entries.filter((e) => e.category === categoryFilter);
+  }
+  if (tagFilter) {
+    entries = entries.filter((e) =>
+      e.tags.some((t) => t.toLowerCase().includes(tagFilter.toLowerCase()))
+    );
+  }
+
+  // Sort by last modified, most recent first
+  entries.sort((a, b) => b.lastModified.localeCompare(a.lastModified));
+  entries = entries.slice(0, recent);
+
+  if (entries.length === 0) {
+    console.log("[mink] no notes found");
+    return;
+  }
+
+  console.log(`[mink] ${entries.length} notes:`);
+  console.log();
+
+  for (const entry of entries) {
+    const tags =
+      entry.tags.length > 0 ? ` [${entry.tags.join(", ")}]` : "";
+    console.log(`  ${entry.category.padEnd(10)} ${entry.title}${tags}`);
+    console.log(`             ${entry.filePath}`);
+  }
+}
+
+function noteSearch(term: string): void {
+  if (!term.trim()) {
+    console.error("Usage: mink note search <term>");
+    process.exit(1);
+  }
+
+  const results = searchVaultIndex(term);
+
+  if (results.length === 0) {
+    console.log(`[mink] no notes matching "${term}"`);
+    return;
+  }
+
+  console.log(`[mink] ${results.length} notes matching "${term}":`);
+  console.log();
+
+  for (const entry of results.slice(0, 20)) {
+    const tags =
+      entry.tags.length > 0 ? ` [${entry.tags.join(", ")}]` : "";
+    console.log(`  ${entry.category.padEnd(10)} ${entry.title}${tags}`);
+    if (entry.description) {
+      console.log(`             ${entry.description}`);
+    }
+    console.log(`             ${entry.filePath}`);
+  }
+
+  if (results.length > 20) {
+    console.log();
+    console.log(`  ... and ${results.length - 20} more results`);
+  }
+}

package/src/commands/session-start.ts

@@ -3,6 +3,8 @@ import { createSessionState } from "../core/session";
 import { projectDir, sessionPath, actionLogPath } from "../core/paths";
 import { atomicWriteJson } from "../core/fs-utils";
 import { createActionLogWriter } from "../core/action-log";
+import { isWikiEnabled, isVaultInitialized, isInsideVault } from "../core/vault";
+import { loadVaultIndex } from "../core/note-index";
 
 export function sessionStart(cwd: string): void {
   const dir = projectDir(cwd);
@@ -18,4 +20,28 @@ export function sessionStart(cwd: string): void {
   } catch {
     // Never crash hooks
   }
+
+  // Emit vault context if wiki is enabled
+  try {
+    if (isWikiEnabled() && isVaultInitialized()) {
+      const index = loadVaultIndex();
+      const inboxCount = Object.values(index.entries).filter(
+        (e) => e.category === "inbox"
+      ).length;
+
+      if (inboxCount > 0) {
+        console.error(
+          `[mink] vault: ${inboxCount} notes in inbox need categorization`
+        );
+      }
+
+      if (isInsideVault(cwd)) {
+        console.error(
+          `[mink] notes project detected — vault has ${index.totalNotes} notes`
+        );
+      }
+    }
+  } catch {
+    // Never crash hooks
+  }
 }