@drewpayment/mink 0.3.0 → 0.5.0

package/src/core/channel-templates.ts

@@ -0,0 +1,156 @@
+import { join } from "path";
+import { existsSync, writeFileSync, mkdirSync } from "fs";
+
+export const COMPANION_CLAUDE_MD = `# Mink Knowledge Companion
+
+You are **Mink**, a personal knowledge companion. You help capture, organize, search, and retrieve notes across all the user's projects through conversational messages (Discord, Telegram, or iMessage via Claude Code Channels).
+
+Your home is this wiki vault — the directory you're running in. Notes live as markdown files organized by PARA (Projects / Areas / Resources / Archives / Inbox).
+
+## Your Role
+
+You are the **smart orchestrator**. The \`mink\` CLI is the dumb writer — it takes explicit flags and writes files. Your job:
+
+1. Understand what the user wants (capture, search, organize, summarize)
+2. Gather vault context when useful
+3. Call the right \`mink\` command with good flags
+4. Reply briefly — the user is likely on mobile
+
+## Conversational Style
+
+- **Brief.** One or two sentences. The user is in a chat app, not a terminal.
+- **Confirm what happened.** "Saved to \`projects/auth/blocker.md\` with tags \`compliance, blocker\`." — short, specific.
+- **Suggest, don't interrogate.** If you're unsure about a tag, pick a reasonable default and mention it. Don't ask 3 questions before saving a note.
+- **Surface related work.** After saving, mention related notes found ("2 related notes about auth-migration") when useful.
+
+## Capturing Notes
+
+When the user's message sounds like a note ("save this...", "log that...", or just describes something factual), **capture it**. Don't ask permission.
+
+### Flow
+
+1. **Read the message.** Extract: what's this about? Is it project-specific?
+2. **Gather context briefly.** Run these when needed (not every time):
+   - \`mink note list --recent 10\` — recent notes for continuity
+   - \`mink wiki status\` — vault overview
+   - Check \`.mink-index.json\` for existing tag vocabulary
+3. **Decide metadata:**
+   - **Title** — clear, descriptive (becomes the filename). Not the raw text.
+   - **Category** — one of:
+     - \`projects\` — has a deadline, milestone, or deliverable. Use \`--project <slug>\` if it maps to a known Mink project.
+     - \`areas\` — ongoing responsibility or recurring concern
+     - \`resources\` — reference material, how-to, guide
+     - \`archives\` — completed or historical
+     - \`inbox\` — genuinely unclear (user will sort later)
+   - **Tags** — 2–3 is usually right. **Prefer existing tags** from the vocabulary over inventing new ones. Lowercase, hyphenated.
+   - **Wikilinks** — wrap people, projects, and concepts in \`[[double-brackets]]\` inside the body when they match existing notes.
+4. **Call \`mink note\`** with the flags:
+   \`\`\`bash
+   mink note --title "Title" --body "Body with [[wikilinks]]" --category <cat> --tags "a,b,c"
+   # Add --project <slug> if project-linked
+   \`\`\`
+5. **Reply.** One line: where it landed, category, tags. Optionally: related notes.
+
+### Daily Notes
+
+If the user says "add to my daily" or "daily" or "today":
+\`\`\`bash
+mink note --daily "Content to append"
+\`\`\`
+
+### Meeting Notes
+
+If the user describes a meeting (attendees, topic, discussion):
+\`\`\`bash
+mink note --template meeting --title "Meeting: Topic" --body "..." --category areas --tags "meeting,..."
+\`\`\`
+
+## Searching and Retrieving
+
+When the user asks about past work — "what did I write about X?", "show me notes from last week", "find my notes on auth" — use:
+
+- \`mink note search <term>\` — full-text search (title, description, tags, path)
+- \`mink note list --recent N\` — recent notes
+- \`mink note list --category projects\` — filter by category
+- \`mink note list --tag auth\` — filter by tag
+
+**Return results briefly.** Top 3–5 matches with one-line summaries. If there are more, say so.
+
+Example reply:
+> Found 3 notes about auth-migration:
+> • \`projects/auth/compliance-blocker.md\` (today) — blocked on session token storage
+> • \`projects/auth/architecture.md\` (Apr 10) — middleware rewrite plan
+> • \`areas/daily/2026-04-12.md\` — standup update
+
+## Organization
+
+If the user says "move this to projects", "tag this with X", or "categorize my inbox":
+
+- For a single note: read it, rewrite it in the new category with \`mink note --file\` (ingestion). The CLI doesn't have a move command — you move by rewriting.
+- For inbox triage: list with \`mink note list --category inbox\`, propose categorization, execute on confirmation.
+
+## Daily Summaries
+
+If the user asks "what did I work on today?" or "give me a summary":
+
+1. Read today's daily note: \`mink note list --tag daily --recent 1\` → read the file
+2. Check recent notes: \`mink note list --recent 20\`
+3. Synthesize a short summary (3–5 bullets)
+
+## Cross-Project Awareness
+
+Notes may be linked to projects via \`source_project\` in frontmatter. To find notes for a specific project:
+\`\`\`bash
+mink note list --category projects
+mink note search <project-slug>
+\`\`\`
+
+Use wikilinks generously: \`[[project-name]]\`, \`[[person-name]]\`, \`[[concept]]\`. If the target note doesn't exist, the wikilink still works as a placeholder.
+
+## Session Kickoff
+
+At the start of a fresh conversation (first user message), it's fine to silently run:
+\`\`\`bash
+mink wiki status
+mink note list --recent 5
+\`\`\`
+
+Don't announce this. Just have the context.
+
+## What NOT to Do
+
+- Don't ask "what category should this be?" — pick one, move on.
+- Don't paste long output. Summarize.
+- Don't invent tags that exist with slight variations. Check vocabulary first.
+- Don't open files or directories unrelated to the vault. Stay focused on notes and wiki operations.
+- Don't edit source code in this vault — this is a knowledge repo, not a codebase.
+
+## CLI Reference (Cheat Sheet)
+
+\`\`\`bash
+# Capture
+mink note "quick thought"                                # inbox capture
+mink note --title T --body B --category areas --tags a,b
+mink note --daily "content"                              # daily note
+mink note --template meeting --title "..." --body "..."
+mink note --file ./external.md --category resources
+
+# Search / list
+mink note search <term>
+mink note list [--category X] [--tag Y] [--recent N]
+
+# Vault
+mink wiki status
+mink wiki rebuild-index
+\`\`\`
+`;
+
+export function writeCompanionClaudeMd(vaultPath: string, overwrite = false): boolean {
+  mkdirSync(vaultPath, { recursive: true });
+  const claudeMdPath = join(vaultPath, "CLAUDE.md");
+  if (existsSync(claudeMdPath) && !overwrite) {
+    return false;
+  }
+  writeFileSync(claudeMdPath, COMPANION_CLAUDE_MD);
+  return true;
+}

package/src/core/daemon.ts

@@ -3,6 +3,16 @@ import { mkdirSync } from "fs";
 import { dirname, resolve } from "path";
 import { schedulerPidPath, schedulerLogPath } from "./paths";
 import type { PidFileData } from "../types/scheduler";
+import { resolveConfigValue } from "./global-config";
+import { resolveVaultPath, isVaultInitialized } from "./vault";
+import { writeCompanionClaudeMd } from "./channel-templates";
+import {
+  startChannelProcess,
+  stopChannelProcess,
+  getChannelStatus,
+  isChannelRunning,
+} from "./channel-process";
+import type { ChannelPlatform, ChannelStatus } from "../types/channel";
 
 // ── PID File Operations ─────────────────────────────────────────────────────
 
@@ -91,9 +101,49 @@ export function startDaemon(cwd: string): void {
 
   console.log(`[mink] scheduler started (PID: ${proc.pid})`);
   console.log(`[mink] log: ${logPath}`);
+
+  // Fire and forget — channel startup has its own verification loop.
+  maybeStartChannel().catch((err) => {
+    console.error(`[mink] failed to start channel: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}
+
+async function maybeStartChannel(): Promise<void> {
+  const enabled = resolveConfigValue("channel.discord.enabled").value === "true";
+  if (!enabled) return;
+
+  if (!isVaultInitialized()) {
+    console.log("[mink] channel enabled but vault not initialized — skipping channel start");
+    return;
+  }
+
+  const token = resolveConfigValue("channel.discord.bot-token").value;
+  if (!token) {
+    console.log("[mink] channel enabled but no Discord bot token configured — skipping channel start");
+    return;
+  }
+
+  if (isChannelRunning()) {
+    return;
+  }
+
+  const platform =
+    (resolveConfigValue("channel.default-platform").value as ChannelPlatform) ||
+    "discord";
+  const skipPermissions =
+    resolveConfigValue("channel.skip-permissions").value === "true";
+  const vaultPath = resolveVaultPath();
+  writeCompanionClaudeMd(vaultPath, false);
+
+  const result = await startChannelProcess({ vaultPath, platform, token, skipPermissions });
+  if (!result.alreadyRunning) {
+    console.log(`[mink] channel started (session: ${result.session}, platform: ${platform})`);
+  }
 }
 
 export async function stopDaemon(): Promise<void> {
+  await stopChannelIfRunning();
+
   const pidData = readPidFile();
   if (!pidData) {
     console.log("[mink] scheduler is not running (no PID file)");
@@ -130,24 +180,35 @@ export async function stopDaemon(): Promise<void> {
   console.log("[mink] scheduler force-stopped (SIGKILL)");
 }
 
+async function stopChannelIfRunning(): Promise<void> {
+  if (!isChannelRunning()) return;
+  const result = await stopChannelProcess();
+  if (result === "stopped") {
+    console.log("[mink] channel stopped");
+  }
+}
+
 export function getDaemonStatus(cwd: string): {
   running: boolean;
   pid?: number;
   startedAt?: string;
   projectCwd?: string;
+  channel: ChannelStatus | null;
 } {
+  const channel = getChannelStatus();
   const pidData = readPidFile();
   if (!pidData) {
-    return { running: false };
+    return { running: false, channel };
   }
   if (!isProcessAlive(pidData.pid)) {
     removePidFile();
-    return { running: false };
+    return { running: false, channel };
   }
   return {
     running: true,
     pid: pidData.pid,
     startedAt: pidData.startedAt,
     projectCwd: pidData.projectCwd,
+    channel,
   };
 }

package/src/core/device.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { hostname, platform } from "os";
+import { randomUUID } from "crypto";
+import { deviceIdPath, deviceRegistryPath } from "./paths";
+import { safeReadJson, atomicWriteJson } from "./fs-utils";
+import type { DeviceInfo, DeviceRegistry } from "../types/config";
+
+export function getOrCreateDeviceId(): string {
+  const idPath = deviceIdPath();
+  if (existsSync(idPath)) {
+    return readFileSync(idPath, "utf-8").trim();
+  }
+  const id = randomUUID();
+  mkdirSync(dirname(idPath), { recursive: true });
+  writeFileSync(idPath, id + "\n");
+  return id;
+}
+
+export function loadDeviceRegistry(): DeviceRegistry {
+  const raw = safeReadJson(deviceRegistryPath());
+  if (raw !== null && typeof raw === "object" && !Array.isArray(raw) && "devices" in (raw as object)) {
+    return raw as DeviceRegistry;
+  }
+  return { devices: {} };
+}
+
+export function saveDeviceRegistry(registry: DeviceRegistry): void {
+  atomicWriteJson(deviceRegistryPath(), registry);
+}
+
+export function updateDeviceHeartbeat(): void {
+  const id = getOrCreateDeviceId();
+  const registry = loadDeviceRegistry();
+  const now = new Date().toISOString();
+  const existing = registry.devices[id];
+
+  registry.devices[id] = {
+    name: existing?.name ?? hostname(),
+    hostname: hostname(),
+    platform: platform(),
+    firstSeen: existing?.firstSeen ?? now,
+    lastSeen: now,
+  };
+
+  saveDeviceRegistry(registry);
+}
+
+export function listDevices(): Array<DeviceInfo & { id: string }> {
+  const registry = loadDeviceRegistry();
+  return Object.entries(registry.devices).map(([id, info]) => ({
+    id,
+    ...info,
+  }));
+}
+
+export function setDeviceName(name: string): void {
+  const id = getOrCreateDeviceId();
+  const registry = loadDeviceRegistry();
+  const now = new Date().toISOString();
+  const existing = registry.devices[id];
+
+  registry.devices[id] = {
+    name,
+    hostname: hostname(),
+    platform: platform(),
+    firstSeen: existing?.firstSeen ?? now,
+    lastSeen: now,
+  };
+
+  saveDeviceRegistry(registry);
+}

package/src/core/global-config.ts

@@ -1,4 +1,4 @@
-import { globalConfigPath } from "./paths";
+import { globalConfigPath, localConfigPath } from "./paths";
 import { safeReadJson, atomicWriteJson } from "./fs-utils";
 import {
   CONFIG_KEYS,
@@ -6,31 +6,57 @@ import {
   getConfigKeyMeta,
   type GlobalConfig,
   type ConfigKey,
+  type ConfigScope,
 } from "../types/config";
 
-export function loadGlobalConfig(): GlobalConfig {
-  const raw = safeReadJson(globalConfigPath());
+function loadConfigFile(path: string): GlobalConfig {
+  const raw = safeReadJson(path);
   if (raw === null) return {};
   if (typeof raw !== "object" || Array.isArray(raw)) {
-    console.warn("[mink] warning: corrupt config file at " + globalConfigPath());
+    console.warn("[mink] warning: corrupt config file at " + path);
     return {};
   }
   return raw as GlobalConfig;
 }
 
+export function loadGlobalConfig(): GlobalConfig {
+  return loadConfigFile(globalConfigPath());
+}
+
 export function saveGlobalConfig(config: GlobalConfig): void {
   atomicWriteJson(globalConfigPath(), config);
 }
 
+export function loadLocalConfig(): GlobalConfig {
+  return loadConfigFile(localConfigPath());
+}
+
+export function saveLocalConfig(config: GlobalConfig): void {
+  atomicWriteJson(localConfigPath(), config);
+}
+
+function loadConfigForScope(scope: ConfigScope): GlobalConfig {
+  return scope === "local" ? loadLocalConfig() : loadGlobalConfig();
+}
+
+function saveConfigForScope(scope: ConfigScope, config: GlobalConfig): void {
+  if (scope === "local") {
+    saveLocalConfig(config);
+  } else {
+    saveGlobalConfig(config);
+  }
+}
+
 export interface ResolvedValue {
   value: string;
   source: "default" | "config file" | "environment variable";
+  scope: ConfigScope;
   configFileValue?: string;
 }
 
 export function resolveConfigValue(key: ConfigKey): ResolvedValue {
   const meta = getConfigKeyMeta(key);
-  const config = loadGlobalConfig();
+  const config = loadConfigForScope(meta.scope);
 
   const envValue = process.env[meta.envVar];
   const fileValue = config[key];
@@ -39,15 +65,16 @@ export function resolveConfigValue(key: ConfigKey): ResolvedValue {
     return {
       value: envValue,
       source: "environment variable",
+      scope: meta.scope,
       configFileValue: fileValue,
     };
   }
 
   if (fileValue !== undefined) {
-    return { value: fileValue, source: "config file" };
+    return { value: fileValue, source: "config file", scope: meta.scope };
   }
 
-  return { value: meta.default, source: "default" };
+  return { value: meta.default, source: "default", scope: meta.scope };
 }
 
 export function resolveAllConfig(): Array<ResolvedValue & { key: ConfigKey }> {
@@ -58,17 +85,51 @@ export function resolveAllConfig(): Array<ResolvedValue & { key: ConfigKey }> {
 }
 
 export function setConfigValue(key: ConfigKey, value: string): void {
-  const config = loadGlobalConfig();
+  const meta = getConfigKeyMeta(key);
+  const config = loadConfigForScope(meta.scope);
   config[key] = value;
-  saveGlobalConfig(config);
+  saveConfigForScope(meta.scope, config);
 }
 
 export function resetConfigKey(key: ConfigKey): void {
-  const config = loadGlobalConfig();
+  const meta = getConfigKeyMeta(key);
+  const config = loadConfigForScope(meta.scope);
   delete config[key];
-  saveGlobalConfig(config);
+  saveConfigForScope(meta.scope, config);
 }
 
 export function resetAllConfig(): void {
   saveGlobalConfig({});
+  saveLocalConfig({});
+}
+
+// ── Migration ─────────────────────────────────────────────────────────────
+
+let migrationRan = false;
+
+export function migrateConfigIfNeeded(): void {
+  if (migrationRan) return;
+  migrationRan = true;
+
+  const { existsSync } = require("fs");
+  if (existsSync(localConfigPath())) return;
+
+  const shared = loadGlobalConfig();
+  const localKeys = CONFIG_KEYS.filter((k) => k.scope === "local");
+  const localConfig: GlobalConfig = {};
+  let hasLocal = false;
+
+  for (const meta of localKeys) {
+    const val = shared[meta.key];
+    if (val !== undefined) {
+      localConfig[meta.key] = val;
+      delete shared[meta.key];
+      hasLocal = true;
+    }
+  }
+
+  if (hasLocal) {
+    saveLocalConfig(localConfig);
+    saveGlobalConfig(shared);
+  }
 }

package/src/core/paths.ts

@@ -57,10 +57,30 @@ export function schedulerManifestPath(cwd: string): string {
   return join(projectDir(cwd), "scheduler-manifest.json");
 }
 
+export function channelPidPath(): string {
+  return join(MINK_ROOT, "channel.pid");
+}
+
+export function channelLogPath(): string {
+  return join(MINK_ROOT, "channel.log");
+}
+
 export function globalConfigPath(): string {
   return join(MINK_ROOT, "config");
 }
 
+export function localConfigPath(): string {
+  return join(MINK_ROOT, "config.local");
+}
+
+export function deviceIdPath(): string {
+  return join(MINK_ROOT, "device-id");
+}
+
+export function deviceRegistryPath(): string {
+  return join(MINK_ROOT, "devices.json");
+}
+
 export function projectMetaPath(cwd: string): string {
   return join(projectDir(cwd), "project-meta.json");
 }

package/src/core/sync.ts

@@ -3,6 +3,7 @@ import { join } from "path";
 import { execSync } from "child_process";
 import { minkRoot } from "./paths";
 import { resolveConfigValue, setConfigValue } from "./global-config";
+import { updateDeviceHeartbeat } from "./device";
 
 // ── Constants ──────────────────────────────────────────────────────────────
 
@@ -14,6 +15,10 @@ const GITIGNORE_CONTENTS = `# Runtime state — machine-specific
 scheduler.pid
 scheduler.log
 
+# Device identity and local config — machine-specific
+device-id
+config.local
+
 # Local backups — machine-specific snapshots
 projects/*/backups/
 `;
@@ -171,6 +176,8 @@ export function syncPull(
 ): void {
   if (!isSyncInitialized()) return;
 
+  ensureGitignore();
+
   const root = minkRoot();
 
   try {
@@ -218,6 +225,8 @@ export function syncPull(
     }
 
     setConfigValue("sync.last-pull", new Date().toISOString());
+
+    try { updateDeviceHeartbeat(); } catch { /* never crash hooks */ }
   } catch (err) {
     onMessage(
       `[mink] sync pull error: ${err instanceof Error ? err.message : String(err)}`
@@ -230,6 +239,9 @@ export function syncPush(
 ): void {
   if (!isSyncInitialized()) return;
 
+  ensureGitignore();
+  try { updateDeviceHeartbeat(); } catch { /* never crash hooks */ }
+
   const root = minkRoot();
 
   try {

package/src/types/channel.ts

@@ -0,0 +1,16 @@
+export type ChannelPlatform = "discord" | "telegram";
+
+export interface ChannelPidFile {
+  session: string;
+  platform: ChannelPlatform;
+  startedAt: string;
+  vaultPath: string;
+}
+
+export interface ChannelStatus {
+  session: string;
+  platform: ChannelPlatform;
+  startedAt: string;
+  vaultPath: string;
+  uptime: number;
+}