@drewpayment/mink 0.3.0 → 0.5.0

package/package.json

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

@@ -89,6 +89,12 @@ switch (command) {
     break;
   }
 
+  case "channel": {
+    const { channel } = await import("./commands/channel");
+    await channel(process.argv.slice(3));
+    break;
+  }
+
   case "config": {
     const { config } = await import("./commands/config");
     await config(process.argv.slice(3));
@@ -143,6 +149,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 +214,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)");
@@ -211,6 +226,13 @@ switch (command) {
     console.log("  sync pause / resume     Temporarily disable/enable auto-sync");
     console.log("  sync disconnect         Remove git tracking (data preserved)");
     console.log();
+    console.log("Channels (conversational companion):");
+    console.log("  channel setup discord --token <t>  Configure Discord bot token");
+    console.log("  channel start [platform]           Launch a Claude Code session with --channels in the vault");
+    console.log("  channel stop                       Stop the channel session");
+    console.log("  channel status                     Show channel status");
+    console.log("  channel logs                       Tail channel log");
+    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)");

package/src/commands/channel.ts

@@ -0,0 +1,252 @@
+import { resolveConfigValue, setConfigValue } from "../core/global-config";
+import { resolveVaultPath, isVaultInitialized } from "../core/vault";
+import { writeCompanionClaudeMd } from "../core/channel-templates";
+import {
+  startChannelProcess,
+  stopChannelProcess,
+  getChannelStatus,
+  getChannelLogs,
+  attachChannel,
+} from "../core/channel-process";
+import type { ChannelPlatform } from "../types/channel";
+
+const SUPPORTED_PLATFORMS: ChannelPlatform[] = ["discord", "telegram"];
+
+function parsePlatform(value: string | undefined): ChannelPlatform | null {
+  if (!value) return null;
+  if (SUPPORTED_PLATFORMS.includes(value as ChannelPlatform)) {
+    return value as ChannelPlatform;
+  }
+  return null;
+}
+
+function extractFlag(args: string[], flag: string): string | undefined {
+  const idx = args.findIndex((a) => a === flag || a.startsWith(flag + "="));
+  if (idx === -1) return undefined;
+  const arg = args[idx];
+  if (arg.includes("=")) {
+    return arg.slice(arg.indexOf("=") + 1);
+  }
+  return args[idx + 1];
+}
+
+export async function channel(args: string[]): Promise<void> {
+  const subcommand = args[0];
+  const rest = args.slice(1);
+
+  switch (subcommand) {
+    case "setup":
+      setupChannel(rest);
+      break;
+    case "start":
+      await startChannel(rest);
+      break;
+    case "stop":
+      await stopChannel();
+      break;
+    case "status":
+      showStatus();
+      break;
+    case "logs":
+      showLogs();
+      break;
+    case "attach":
+      doAttach();
+      break;
+    default:
+      printUsage();
+      process.exit(1);
+  }
+}
+
+function setupChannel(args: string[]): void {
+  const platform = parsePlatform(args[0]);
+  if (!platform) {
+    console.error("[mink] missing or invalid platform");
+    console.error("Usage: mink channel setup <discord|telegram> --token <token>");
+    process.exit(1);
+  }
+
+  if (platform === "telegram") {
+    console.error("[mink] telegram setup is not yet supported");
+    process.exit(1);
+  }
+
+  const token = extractFlag(args, "--token");
+
+  if (!token) {
+    console.log("[mink] Discord Channel Setup");
+    console.log("");
+    console.log("In the Discord Developer Portal (https://discord.com/developers/applications):");
+    console.log("");
+    console.log("  1. New Application > give it a name");
+    console.log("  2. Bot > Reset Token > copy the token");
+    console.log("  3. Bot > scroll to Privileged Gateway Intents:");
+    console.log("     - Enable MESSAGE CONTENT INTENT (required)");
+    console.log("  4. OAuth2 > URL Generator:");
+    console.log("     - Integration Type: Guild Install (NOT User Install)");
+    console.log("     - Scopes: bot");
+    console.log("     - Bot Permissions: View Channels, Send Messages,");
+    console.log("       Send Messages in Threads, Read Message History,");
+    console.log("       Attach Files, Add Reactions");
+    console.log("  5. Open the generated URL to invite the bot to a server");
+    console.log("     (create a personal server if you just want to DM the bot)");
+    console.log("");
+    console.log("Then install the channel plugin once inside Claude Code:");
+    console.log("  claude");
+    console.log("  /plugin install discord@claude-plugins-official");
+    console.log("  (exit Claude Code)");
+    console.log("");
+    console.log("Finally, save your token:");
+    console.log("  mink channel setup discord --token <your-token>");
+    console.log("");
+    console.log("Your token is stored locally in ~/.mink/config.local");
+    console.log("and is NOT synced across machines.");
+    return;
+  }
+
+  if (!/^[\w.-]{30,}$/.test(token)) {
+    console.error("[mink] token format looks invalid — expected a long token string");
+    process.exit(1);
+  }
+
+  setConfigValue("channel.discord.bot-token", token);
+  setConfigValue("channel.discord.enabled", "true");
+  setConfigValue("channel.default-platform", "discord");
+
+  console.log("[mink] Discord bot token saved to config.local");
+  console.log("[mink] channel.discord.enabled = true");
+  console.log("[mink] channel.default-platform = discord");
+  console.log("");
+  console.log("Next: mink channel start");
+}
+
+async function startChannel(args: string[]): Promise<void> {
+  if (!isVaultInitialized()) {
+    console.error("[mink] wiki vault is not initialized");
+    console.error("Run: mink wiki init");
+    process.exit(1);
+  }
+
+  const requested = parsePlatform(args[0]);
+  const platform =
+    requested ??
+    parsePlatform(resolveConfigValue("channel.default-platform").value) ??
+    "discord";
+
+  if (platform === "telegram") {
+    console.error("[mink] telegram is not yet supported");
+    process.exit(1);
+  }
+
+  const token = resolveConfigValue("channel.discord.bot-token").value;
+  if (!token) {
+    console.error("[mink] no Discord bot token configured");
+    console.error("Run: mink channel setup discord --token <your-token>");
+    process.exit(1);
+  }
+
+  const vaultPath = resolveVaultPath();
+  const wrote = writeCompanionClaudeMd(vaultPath, false);
+  if (wrote) {
+    console.log(`[mink] created companion CLAUDE.md at ${vaultPath}`);
+  }
+
+  const skipPermissions =
+    resolveConfigValue("channel.skip-permissions").value === "true";
+
+  let result;
+  try {
+    result = await startChannelProcess({ vaultPath, platform, token, skipPermissions });
+  } catch (err) {
+    console.error("[mink] failed to start channel:");
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+
+  if (result.alreadyRunning) {
+    console.log(`[mink] channel is already running (screen session: ${result.session})`);
+    return;
+  }
+
+  console.log(`[mink] channel started`);
+  console.log(`[mink] platform:  ${platform}`);
+  console.log(`[mink] vault:     ${vaultPath}`);
+  console.log(`[mink] session:   ${result.session} (GNU screen)`);
+  console.log("");
+  console.log("Next:");
+  console.log("  1. DM your bot on Discord — it replies with a pairing code");
+  console.log("  2. Attach to the Claude Code session: mink channel attach");
+  console.log("  3. Inside the session, run: /discord:access pair <code>");
+  console.log("  4. Then lock down access:   /discord:access policy allowlist");
+  console.log("  5. Detach with Ctrl-a d");
+  console.log("");
+  console.log("See activity:  mink channel logs");
+}
+
+async function stopChannel(): Promise<void> {
+  const result = await stopChannelProcess();
+  switch (result) {
+    case "not-running":
+      console.log("[mink] channel is not running");
+      break;
+    case "stopped":
+      console.log("[mink] channel stopped");
+      break;
+  }
+}
+
+function showStatus(): void {
+  const status = getChannelStatus();
+  if (!status) {
+    console.log("[mink] channel is not running");
+    return;
+  }
+  console.log(`running:   yes`);
+  console.log(`session:   ${status.session}`);
+  console.log(`platform:  ${status.platform}`);
+  console.log(`vault:     ${status.vaultPath}`);
+  console.log(`started:   ${status.startedAt}`);
+  console.log(`uptime:    ${formatUptime(status.uptime)}`);
+  console.log("");
+  console.log("Attach:    mink channel attach");
+}
+
+function formatUptime(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+  const mins = Math.floor(seconds / 60);
+  if (mins < 60) return `${mins}m ${seconds % 60}s`;
+  const hrs = Math.floor(mins / 60);
+  return `${hrs}h ${mins % 60}m`;
+}
+
+function showLogs(): void {
+  const content = getChannelLogs();
+  if (content == null) {
+    console.log("[mink] channel is not running (no logs to show)");
+    return;
+  }
+  // Strip trailing empty lines for readability
+  console.log(content.replace(/\n+$/, ""));
+}
+
+function doAttach(): void {
+  const result = attachChannel();
+  if (result === "not-running") {
+    console.log("[mink] channel is not running");
+    console.log("Start it with: mink channel start");
+  }
+}
+
+function printUsage(): void {
+  console.error("Usage: mink channel <subcommand>");
+  console.error("");
+  console.error("Subcommands:");
+  console.error("  setup <platform> --token <token>   Configure a channel (discord|telegram)");
+  console.error("  start [platform]                   Launch channel session (in GNU screen)");
+  console.error("  stop                               Stop channel session");
+  console.error("  status                             Show channel status");
+  console.error("  logs                               Show recent channel output");
+  console.error("  attach                             Attach to the channel's Claude Code session");
+  console.error("                                     (detach with Ctrl-a then d)");
+}

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/channel-process.ts

@@ -0,0 +1,274 @@
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, existsSync } from "fs";
+import { dirname, join } from "path";
+import { spawnSync } from "child_process";
+import { channelPidPath, minkRoot } from "./paths";
+import type { ChannelPidFile, ChannelStatus, ChannelPlatform } from "../types/channel";
+
+// ── PID File Operations ─────────────────────────────────────────────────────
+
+export function readChannelPidFile(): ChannelPidFile | null {
+  try {
+    const raw = readFileSync(channelPidPath(), "utf-8");
+    const data = JSON.parse(raw);
+    if (
+      data &&
+      typeof data.session === "string" &&
+      typeof data.platform === "string" &&
+      typeof data.startedAt === "string" &&
+      typeof data.vaultPath === "string"
+    ) {
+      return data as ChannelPidFile;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeChannelPidFile(data: ChannelPidFile): void {
+  const pidPath = channelPidPath();
+  mkdirSync(dirname(pidPath), { recursive: true });
+  writeFileSync(pidPath, JSON.stringify(data, null, 2));
+}
+
+export function removeChannelPidFile(): void {
+  try {
+    unlinkSync(channelPidPath());
+  } catch {
+    // Already removed
+  }
+}
+
+// ── Screen Session Management ───────────────────────────────────────────────
+
+const SESSION_PREFIX = "mink-channel-";
+
+function sessionName(platform: ChannelPlatform): string {
+  return `${SESSION_PREFIX}${platform}`;
+}
+
+function isScreenInstalled(): boolean {
+  const result = spawnSync("screen", ["-ls"], { stdio: "ignore" });
+  return !result.error;
+}
+
+function screenSessionExists(session: string): boolean {
+  const result = spawnSync("screen", ["-ls", session], {
+    stdio: ["ignore", "pipe", "ignore"],
+    encoding: "utf-8",
+  });
+  const output = typeof result.stdout === "string" ? result.stdout : "";
+  return new RegExp(`\\d+\\.${session}\\b`).test(output);
+}
+
+function shellEscape(s: string): string {
+  if (/^[a-zA-Z0-9_@%+=:,./\-]+$/.test(s)) return s;
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+// ── Channel Lifecycle ───────────────────────────────────────────────────────
+
+const PLUGIN_SPECS: Record<ChannelPlatform, string> = {
+  discord: "plugin:discord@claude-plugins-official",
+  telegram: "plugin:telegram@claude-plugins-official",
+};
+
+const TOKEN_ENV_VARS: Record<ChannelPlatform, string> = {
+  discord: "DISCORD_BOT_TOKEN",
+  telegram: "TELEGRAM_BOT_TOKEN",
+};
+
+export interface StartChannelOptions {
+  vaultPath: string;
+  platform: ChannelPlatform;
+  token?: string;
+  claudeCommand?: string;
+  skipPermissions?: boolean;
+}
+
+export interface StartChannelResult {
+  session: string;
+  alreadyRunning: boolean;
+}
+
+export async function startChannelProcess(opts: StartChannelOptions): Promise<StartChannelResult> {
+  if (!isScreenInstalled()) {
+    throw new Error(
+      "GNU screen is required but was not found on PATH.\n" +
+        "macOS: screen is pre-installed — check your shell environment.\n" +
+        "Linux: install with `sudo apt install screen` (or your package manager)."
+    );
+  }
+
+  const session = sessionName(opts.platform);
+
+  if (screenSessionExists(session)) {
+    writeChannelPidFile({
+      session,
+      platform: opts.platform,
+      startedAt: new Date().toISOString(),
+      vaultPath: opts.vaultPath,
+    });
+    return { session, alreadyRunning: true };
+  }
+
+  const claudeCmd = opts.claudeCommand ?? "claude";
+  const pluginSpec = PLUGIN_SPECS[opts.platform];
+  const tokenEnvVar = TOKEN_ENV_VARS[opts.platform];
+
+  const claudeFlags = ["--channels", shellEscape(pluginSpec)];
+  if (opts.skipPermissions) {
+    claudeFlags.push("--dangerously-skip-permissions");
+  }
+
+  const parts: string[] = [];
+  parts.push(`cd ${shellEscape(opts.vaultPath)}`);
+  if (opts.token) {
+    parts.push(`export ${tokenEnvVar}=${shellEscape(opts.token)}`);
+  }
+  parts.push(`exec ${shellEscape(claudeCmd)} ${claudeFlags.join(" ")}`);
+  const innerCmd = parts.join("; ");
+
+  const result = spawnSync(
+    "screen",
+    // -T screen-256color: advertise 256-color terminal to inner programs.
+    // Default screen TERM is `screen` (8 colors) and makes Claude Code render washed-out.
+    ["-T", "screen-256color", "-dmS", session, "bash", "-c", innerCmd],
+    { stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }
+  );
+
+  if (result.status !== 0) {
+    const stderr = typeof result.stderr === "string" ? result.stderr : "";
+    throw new Error(
+      `screen failed to create session (exit ${result.status}): ${stderr || "(no output)"}`
+    );
+  }
+
+  // Give screen/claude a moment to start; verify the session is still alive
+  await new Promise((r) => setTimeout(r, 700));
+
+  if (!screenSessionExists(session)) {
+    throw new Error(
+      "channel session died immediately after starting. " +
+        "This usually means `claude` failed to launch. Check:\n" +
+        "  • Is `claude` on your PATH? Run `which claude`.\n" +
+        "  • Have you installed the plugin? Run `claude` then `/plugin install discord@claude-plugins-official`.\n" +
+        "  • Try running the command manually to see the error:\n" +
+        `    cd ${opts.vaultPath} && claude --channels ${pluginSpec}`
+    );
+  }
+
+  writeChannelPidFile({
+    session,
+    platform: opts.platform,
+    startedAt: new Date().toISOString(),
+    vaultPath: opts.vaultPath,
+  });
+
+  return { session, alreadyRunning: false };
+}
+
+export async function stopChannelProcess(): Promise<"stopped" | "not-running"> {
+  const pidData = readChannelPidFile();
+  if (!pidData) {
+    return "not-running";
+  }
+
+  if (!screenSessionExists(pidData.session)) {
+    removeChannelPidFile();
+    return "not-running";
+  }
+
+  spawnSync("screen", ["-S", pidData.session, "-X", "quit"], { stdio: "ignore" });
+
+  for (let i = 0; i < 30; i++) {
+    if (!screenSessionExists(pidData.session)) {
+      removeChannelPidFile();
+      return "stopped";
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+
+  // Session lingered — force clean up our tracking file
+  removeChannelPidFile();
+  return "stopped";
+}
+
+export function isChannelRunning(): boolean {
+  const pidData = readChannelPidFile();
+  if (!pidData) return false;
+  if (!screenSessionExists(pidData.session)) {
+    removeChannelPidFile();
+    return false;
+  }
+  return true;
+}
+
+export function getChannelStatus(): ChannelStatus | null {
+  const pidData = readChannelPidFile();
+  if (!pidData) return null;
+  if (!screenSessionExists(pidData.session)) {
+    removeChannelPidFile();
+    return null;
+  }
+  const startedMs = Date.parse(pidData.startedAt);
+  const uptimeSec = Number.isFinite(startedMs)
+    ? Math.max(0, Math.floor((Date.now() - startedMs) / 1000))
+    : 0;
+  return {
+    session: pidData.session,
+    platform: pidData.platform,
+    startedAt: pidData.startedAt,
+    vaultPath: pidData.vaultPath,
+    uptime: uptimeSec,
+  };
+}
+
+export function getChannelLogs(): string | null {
+  const pidData = readChannelPidFile();
+  if (!pidData) return null;
+  if (!screenSessionExists(pidData.session)) return null;
+
+  const tmpPath = join(minkRoot(), `.channel-capture-${Date.now()}-${process.pid}.txt`);
+
+  const result = spawnSync(
+    "screen",
+    ["-S", pidData.session, "-X", "hardcopy", "-h", tmpPath],
+    { stdio: "ignore" }
+  );
+
+  if (result.status !== 0) return null;
+
+  // screen writes asynchronously; give it a brief moment
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(tmpPath)) break;
+    const delayUntil = Date.now() + 50;
+    while (Date.now() < delayUntil) {
+      /* busy wait — 50ms */
+    }
+  }
+
+  try {
+    const content = readFileSync(tmpPath, "utf-8");
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+export function attachChannel(): "attached" | "not-running" {
+  const pidData = readChannelPidFile();
+  if (!pidData) return "not-running";
+  if (!screenSessionExists(pidData.session)) {
+    removeChannelPidFile();
+    return "not-running";
+  }
+  // Hand terminal to screen. Returns when user detaches (Ctrl-a then d).
+  spawnSync("screen", ["-r", pidData.session], { stdio: "inherit" });
+  return "attached";
+}