kandown 0.1.3 → 0.2.0

package/bin/kandown.js

@@ -25,6 +25,16 @@
  * @exports none
  */
 /* eslint-disable no-console */
+// 📖 DEV=false prevents Ink from loading react-devtools-core (CJS-only, breaks ESM).
+// Must be set BEFORE any imports because ESM hoists all import statements.
+process.env.DEV = 'false';
+// 📖 Polyfill browser globals that some bundled modules expect.
+if (typeof globalThis.self === 'undefined') Object.defineProperty(globalThis, 'self', { value: globalThis });
+if (typeof globalThis.window === 'undefined') Object.defineProperty(globalThis, 'window', { value: globalThis });
+// 📖 Make require() available in this ESM module so bundled __require() shims work.
+// tsup's __require checks `typeof require !== "undefined"` — this makes it truthy.
+import { createRequire } from 'node:module';
+globalThis.require = createRequire(import.meta.url);
 
 import { fileURLToPath } from 'node:url';
 import { createServer } from 'node:http';
@@ -47,6 +57,51 @@ const PKG_ROOT = resolve(__dirname, '..');
 const DEFAULT_SERVE_PORT = 2048;
 const MAX_SERVE_PORT = 2060;
 
+// 📖 Get current CLI version from package.json at PKG_ROOT
+function getCurrentVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+    return pkg.version;
+  } catch { return null; }
+}
+
+// 📖 Check npm for a newer version and auto-update if outdated.
+// Runs in background — does not block startup. Only activates when running from
+// an installed npm package (not local dev source, where src/ exists).
+// 📖 Uses npm install -g to self-upgrade, then re-spawns with the same arguments.
+async function checkForUpdate(argv = process.argv) {
+  if (existsSync(join(PKG_ROOT, 'src'))) return; // local dev — skip
+  const current = getCurrentVersion();
+  if (!current) return;
+  try {
+    const { execSync } = await import('node:child_process');
+    const latest = String(execSync('npm view kandown version --json 2>/dev/null', {
+      timeout: 8000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    })).trim().replace(/^"|"$/g, '');
+    if (!latest || latest === current) return;
+
+    log(`${c.yellow}⚡ Auto-updating kandown ${c.reset}${c.dim}${current}${c.reset} ${c.yellow}→${c.reset} ${c.green}${latest}${c.reset}…`);
+    try {
+      execSync('npm install -g kandown 2>/dev/null', {
+        timeout: 30000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const newVersion = String(execSync('npm view kandown version 2>/dev/null', {
+        timeout: 5000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+      })).trim().replace(/^"|"$/g, '');
+      if (newVersion === latest) {
+        log(`${c.green}✓ Updated to v${newVersion}${c.reset} — restarting…`);
+        const child = spawn(process.argv[0], ['--experimental-vm-modules', ...argv.slice(1)], {
+          detached: true, stdio: 'ignore', env: { ...process.env } });
+        child.unref();
+        process.exit(0);
+      }
+    } catch {
+      log(`${c.yellow}⚠ Auto-update failed — will retry on next run${c.reset}`);
+      log(`  Run ${c.cyan}npm install -g kandown${c.reset} to upgrade manually`);
+    }
+  } catch { /* offline or npm slow — silently skip */ }
+}
+
 const c = {
   reset: '\x1b[0m',
   bold: '\x1b[1m',
@@ -65,8 +120,10 @@ const warn = (msg) => log(`${c.yellow}⚠${c.reset} ${msg}`);
 const err = (msg) => log(`${c.red}✗${c.reset} ${msg}`);
 
 function help() {
+  const v = getCurrentVersion() ?? '?';
   log(`
 ${c.bold}kandown${c.reset} ${c.dim}· file-based kanban backed by markdown${c.reset}
+${c.dim}v${v}${c.reset}
 
 ${c.bold}Usage:${c.reset}
   npx kandown [command]
@@ -130,7 +187,7 @@ function appendAgentReference(cwd, agentsFile, kandownPath) {
 ${marker}
 ## Task management
 
-**IMPORTANT:** Before touching any task files, you MUST read \`AGENT_KANDOWN.md\`.
+**IMPORTANT:** Before touching any task files, you MUST read \`${kandownPath}/AGENT_KANDOWN.md\`.
 
 This project uses a file-based kanban:
 - **Tasks live in \`${kandownPath}/tasks/t-xxx.md\`** — each task file owns its status
@@ -174,35 +231,40 @@ function parseArgs(argv) {
   return args;
 }
 
-function cmdInit(rawArgs) {
+/**
+ * @returns {{ kandownDir: string, alreadyExisted: boolean }} — resolves the
+ * kandown directory and auto-inits it if it doesn't exist (no prompt, silent init).
+ */
+function ensureKandownDir(rawArgs) {
   const args = parseArgs(rawArgs);
   const cwd = process.cwd();
+  const explicitPath = rawArgs.includes('--path') || rawArgs.includes('-p');
   const kandownDir = resolve(cwd, args.path);
-  const kandownPath = args.path;
 
-  log('');
-  info(`Installing kandown in ${c.bold}${kandownPath}/${c.reset}`);
-  log('');
+  if (existsSync(kandownDir)) return { kandownDir, alreadyExisted: true };
 
-  if (existsSync(kandownDir) && !args.force) {
-    err(`Directory ${c.bold}${kandownPath}/${c.reset} already exists.`);
-    log(`  Use ${c.cyan}--force${c.reset} to overwrite or ${c.cyan}--path <dir>${c.reset} for another location.`);
-    process.exit(1);
-  }
+  log('');
+  info(`No .kandown/ found — auto-installing...`);
+  doInit(args, cwd, args.path, kandownDir);
+  return { kandownDir, alreadyExisted: false };
+}
 
+/**
+ * Performs the actual init work. Returns on error (does not exit).
+ * @returns {boolean} true if init succeeded, false otherwise.
+ */
+function doInit(args, cwd, kandownPath, kandownDir) {
   mkdirSync(kandownDir, { recursive: true });
 
-  // Copy kandown.html from dist
   const htmlSrc = join(PKG_ROOT, 'dist', 'index.html');
   const htmlDest = join(kandownDir, 'kandown.html');
   if (!existsSync(htmlSrc)) {
     err(`Missing build output at ${htmlSrc}. Did you run 'npm run build'?`);
-    process.exit(1);
+    return false;
   }
   copyFileSync(htmlSrc, htmlDest);
   success('kandown.html');
 
-  // Copy templates
   const templatesDir = join(PKG_ROOT, 'templates');
   if (!existsSync(join(kandownDir, 'AGENT.md'))) {
     copyFileSync(join(templatesDir, 'AGENT.md'), join(kandownDir, 'AGENT.md'));
@@ -222,7 +284,6 @@ function cmdInit(rawArgs) {
     info('tasks/ already exists (kept)');
   }
 
-  // 📖 Copy kandown.json config file (project preferences for UI, agent, fields)
   if (!existsSync(join(kandownDir, 'kandown.json'))) {
     copyFileSync(join(templatesDir, 'kandown.json'), join(kandownDir, 'kandown.json'));
     success('kandown.json');
@@ -230,25 +291,15 @@ function cmdInit(rawArgs) {
     info('kandown.json already exists (kept)');
   }
 
-  // Copy AGENT_KANDOWN.md to project root (not inside .kandown/)
   const agentKandownSrc = join(templatesDir, 'AGENT_KANDOWN.md');
-  const agentKandownDest = join(cwd, 'AGENT_KANDOWN.md');
+  const agentKandownDest = join(kandownDir, 'AGENT_KANDOWN.md');
   if (!existsSync(agentKandownDest)) {
     copyFileSync(agentKandownSrc, agentKandownDest);
-    success('AGENT_KANDOWN.md (at project root)');
+    success('AGENT_KANDOWN.md');
   } else {
-    info('AGENT_KANDOWN.md already exists at project root (kept)');
+    info('AGENT_KANDOWN.md already exists (kept)');
   }
 
-  // 📖 Copy the compact agent doc — used by the CLI board launcher for system prompt injection
-  const compactSrc = join(templatesDir, 'AGENT_KANDOWN_COMPACT.md');
-  const compactDest = join(cwd, 'AGENT_KANDOWN_COMPACT.md');
-  if (existsSync(compactSrc) && !existsSync(compactDest)) {
-    copyFileSync(compactSrc, compactDest);
-    success('AGENT_KANDOWN_COMPACT.md (at project root)');
-  }
-
-  // Integrate with AGENTS.md / CLAUDE.md
   if (!args.noAgents) {
     log('');
     const existingAgents = findAgentsFile(cwd);
@@ -261,6 +312,27 @@ function cmdInit(rawArgs) {
     }
   }
 
+  return true;
+}
+
+function cmdInit(rawArgs) {
+  const args = parseArgs(rawArgs);
+  const cwd = process.cwd();
+  const kandownPath = args.path;
+  const kandownDir = resolve(cwd, kandownPath);
+
+  log('');
+  info(`Installing kandown in ${c.bold}${kandownPath}/${c.reset}`);
+  log('');
+
+  if (existsSync(kandownDir) && !args.force) {
+    err(`Directory ${c.bold}${kandownPath}/${c.reset} already exists.`);
+    log(`  Use ${c.cyan}--force${c.reset} to overwrite or ${c.cyan}--path <dir>${c.reset} for another location.`);
+    process.exit(1);
+  }
+
+  if (!doInit(args, cwd, kandownPath, kandownDir)) process.exit(1);
+
   log('');
   log(`${c.green}${c.bold}Done.${c.reset}`);
   log('');
@@ -410,21 +482,9 @@ async function listenOnAvailablePort(kandownDir, preferredPort) {
  * the browser can keep talking to localhost while the terminal board is active.
  */
 async function cmdServe(rawArgs) {
-  const args = parseArgs(rawArgs);
-  const cwd = process.cwd();
-  const hasExplicitPath = rawArgs.includes('--path') || rawArgs.includes('-p');
-  const explicitKandownDir = resolve(cwd, args.path);
-  const kandownDir = hasExplicitPath || existsSync(explicitKandownDir)
-    ? explicitKandownDir
-    : findKandownDir(cwd);
-  if (!kandownDir || !existsSync(kandownDir)) {
-    const missingPath = hasExplicitPath ? args.path : '.kandown/';
-    err(`No ${c.bold}${missingPath}${c.reset} directory found.`);
-    log(`  Run ${c.cyan}npx kandown init${c.reset} to set up kandown in this project.`);
-    process.exit(1);
-  }
+  const { kandownDir } = ensureKandownDir(rawArgs);
 
-  const preferredPort = parsePort(args.port);
+  const preferredPort = parsePort(parseArgs(rawArgs).port);
   const { server, port } = await listenOnAvailablePort(kandownDir, preferredPort);
   const url = `http://localhost:${port}`;
 
@@ -438,8 +498,7 @@ async function cmdServe(rawArgs) {
   info(`Project: ${kandownDir}`);
   openInBrowser(url);
   try {
-    const tuiArgs = kandownDir === explicitKandownDir ? rawArgs : ['--path', kandownDir, ...rawArgs];
-    await cmdTui('board', tuiArgs);
+    await cmdTui('board', rawArgs);
   } finally {
     server.close();
   }
@@ -477,28 +536,31 @@ function findKandownDir(cwd) {
 
 // 📖 Launches the fullscreen TUI for a given screen (settings, board, etc.)
 async function cmdTui(screen, rawArgs) {
-  const args = parseArgs(rawArgs);
-  const cwd = process.cwd();
-  const kandownDir = resolve(cwd, args.path);
-
-  if (!existsSync(kandownDir)) {
-    err(`No ${c.bold}${args.path}/${c.reset} directory found.`);
-    log(`  Run ${c.cyan}npx kandown init${c.reset} first.`);
-    process.exit(1);
-  }
+  const { kandownDir } = ensureKandownDir(rawArgs);
+  const version = getCurrentVersion();
 
   try {
     const { run } = await import(new URL('./tui.js', import.meta.url).href);
-    await run(screen, kandownDir);
+    await run(screen, kandownDir, version);
   } catch (e) {
     err(`Failed to launch TUI: ${e.message}`);
-    log(`  Make sure the CLI is built: ${c.cyan}pnpm build:cli${c.reset}`);
     process.exit(1);
   }
 }
 
 const [cmd, ...rest] = process.argv.slice(2);
 
+// 📖 Handle --version / -v before any command logic
+if (cmd === '--version' || cmd === '-v') {
+  const v = getCurrentVersion() ?? 'unknown';
+  log(`kandown v${v}`);
+  process.exit(0);
+}
+
+// 📖 Auto-update check runs before EVERY command (except --version).
+// Uses a short timeout so startup is not noticeably slower.
+await checkForUpdate(rest);
+
 switch (cmd) {
   case 'init':
     cmdInit(rest);