@drewpayment/mink 0.3.0 → 0.4.0

package/package.json

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

@@ -143,6 +143,12 @@ switch (command) {
     break;
   }
 
+  case "device": {
+    const { device } = await import("./commands/device");
+    device(process.argv.slice(3));
+    break;
+  }
+
   case "bug-search": {
     const { bugSearch } = await import("./commands/bug-search");
     bugSearch(cwd, process.argv.slice(3).join(" "));
@@ -202,7 +208,10 @@ switch (command) {
     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("Sync:");
+    console.log("Devices & Sync:");
+    console.log("  device                  Show current device info");
+    console.log("  device list             List all registered devices");
+    console.log("  device rename <name>    Set a friendly name for this device");
     console.log("  sync                    Full manual sync (pull then push)");
     console.log("  sync init <remote-url>  Connect ~/.mink to a git remote for cross-device sync");
     console.log("  sync status             Show sync state (remote, last sync, pending changes)");

package/src/commands/config.ts

@@ -69,7 +69,7 @@ export async function config(args: string[]): Promise<void> {
     const all = resolveAllConfig();
     console.log("[mink] configuration:");
     for (const entry of all) {
-      let line = `  ${entry.key} = ${entry.value} (source: ${entry.source})`;
+      let line = `  ${entry.key} = ${entry.value} (${entry.scope}, source: ${entry.source})`;
       if (
         entry.source === "environment variable" &&
         entry.configFileValue !== undefined

package/src/commands/device.ts

@@ -0,0 +1,65 @@
+import {
+  getOrCreateDeviceId,
+  listDevices,
+  setDeviceName,
+} from "../core/device";
+import { hostname, platform } from "os";
+
+export function device(args: string[]): void {
+  const sub = args[0] ?? "status";
+
+  switch (sub) {
+    case "status": {
+      const id = getOrCreateDeviceId();
+      const devices = listDevices();
+      const current = devices.find((d) => d.id === id);
+      console.log("[mink] device info:");
+      console.log(`  id:        ${id}`);
+      console.log(`  name:      ${current?.name ?? hostname()}`);
+      console.log(`  hostname:  ${hostname()}`);
+      console.log(`  platform:  ${platform()}`);
+      if (current?.firstSeen) {
+        console.log(`  first seen: ${current.firstSeen}`);
+      }
+      if (current?.lastSeen) {
+        console.log(`  last seen:  ${current.lastSeen}`);
+      }
+      break;
+    }
+
+    case "list": {
+      const devices = listDevices();
+      const currentId = getOrCreateDeviceId();
+      if (devices.length === 0) {
+        console.log("[mink] no devices registered yet");
+        return;
+      }
+      console.log("[mink] registered devices:");
+      for (const d of devices) {
+        const marker = d.id === currentId ? " (this device)" : "";
+        console.log(`  ${d.name}${marker}`);
+        console.log(`    id:       ${d.id}`);
+        console.log(`    hostname: ${d.hostname}`);
+        console.log(`    platform: ${d.platform}`);
+        console.log(`    last seen: ${d.lastSeen}`);
+      }
+      break;
+    }
+
+    case "rename": {
+      const name = args.slice(1).join(" ");
+      if (!name) {
+        console.error("Usage: mink device rename <name>");
+        process.exit(1);
+      }
+      setDeviceName(name);
+      console.log(`[mink] device renamed to "${name}"`);
+      break;
+    }
+
+    default:
+      console.error(`[mink] unknown device subcommand: ${sub}`);
+      console.error("Usage: mink device [status|list|rename <name>]");
+      process.exit(1);
+  }
+}

package/src/commands/session-start.ts

@@ -7,6 +7,22 @@ import { isWikiEnabled, isVaultInitialized, isInsideVault } from "../core/vault"
 import { loadVaultIndex } from "../core/note-index";
 
 export function sessionStart(cwd: string): void {
+  // Migrate config to shared/local split if needed (before sync pull)
+  try {
+    const { migrateConfigIfNeeded } = require("../core/global-config");
+    migrateConfigIfNeeded();
+  } catch {
+    // Never crash hooks
+  }
+
+  // Register/update this device in the registry
+  try {
+    const { updateDeviceHeartbeat } = require("../core/device");
+    updateDeviceHeartbeat();
+  } catch {
+    // Never crash hooks
+  }
+
   // Sync pull before session begins (if enabled)
   try {
     const { isSyncInitialized, syncPull } = require("../core/sync");

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

@@ -61,6 +61,18 @@ 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/config.ts

@@ -13,11 +13,26 @@ export interface GlobalConfig {
 
 export type ConfigKey = keyof GlobalConfig & string;
 
+export type ConfigScope = "shared" | "local";
+
 export interface ConfigKeyMeta {
   key: ConfigKey;
   default: string;
   envVar: string;
   description: string;
+  scope: ConfigScope;
+}
+
+export interface DeviceInfo {
+  name: string;
+  hostname: string;
+  platform: string;
+  firstSeen: string;
+  lastSeen: string;
+}
+
+export interface DeviceRegistry {
+  devices: Record<string, DeviceInfo>;
 }
 
 export const CONFIG_KEYS: ConfigKeyMeta[] = [
@@ -26,60 +41,70 @@ export const CONFIG_KEYS: ConfigKeyMeta[] = [
     default: "~/.mink/wiki/",
     envVar: "MINK_WIKI_PATH",
     description: "Wiki vault location",
+    scope: "local",
   },
   {
     key: "wiki.enabled",
     default: "true",
     envVar: "MINK_WIKI_ENABLED",
     description: "Enable/disable the wiki feature",
+    scope: "shared",
   },
   {
     key: "wiki.sync-mode",
     default: "immediate",
     envVar: "MINK_WIKI_SYNC_MODE",
     description: "Sync mode: immediate or batched",
+    scope: "shared",
   },
   {
     key: "wiki.git-backup",
     default: "false",
     envVar: "MINK_WIKI_GIT_BACKUP",
     description: "Deprecated: use sync.enabled instead",
+    scope: "shared",
   },
   {
     key: "wiki.git-remote",
     default: "origin",
     envVar: "MINK_WIKI_GIT_REMOTE",
     description: "Deprecated: use sync.remote-url instead",
+    scope: "shared",
   },
   {
     key: "notes.default-category",
     default: "inbox",
     envVar: "MINK_NOTES_DEFAULT_CATEGORY",
     description: "Default category for notes captured via CLI",
+    scope: "shared",
   },
   {
     key: "sync.enabled",
     default: "false",
     envVar: "MINK_SYNC_ENABLED",
     description: "Enable/disable automatic git sync of ~/.mink",
+    scope: "shared",
   },
   {
     key: "sync.remote-url",
     default: "",
     envVar: "MINK_SYNC_REMOTE_URL",
     description: "Git remote URL for ~/.mink sync",
+    scope: "shared",
   },
   {
     key: "sync.last-push",
     default: "",
     envVar: "MINK_SYNC_LAST_PUSH",
     description: "ISO timestamp of last successful sync push",
+    scope: "local",
   },
   {
     key: "sync.last-pull",
     default: "",
     envVar: "MINK_SYNC_LAST_PULL",
     description: "ISO timestamp of last successful sync pull",
+    scope: "local",
   },
 ];