kandown 0.27.1 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.28.1 — 2026-07-20 — "Robust Global Auto-Updater"
+
+- **Fixed**: **Global package manager auto-update commands** — updated `checkForUpdate()` and `cmdUpdate()` to run `pnpm add -g kandown@latest` (instead of `pnpm install -g kandown`), with fallback chain across `pnpm`, `npm`, `yarn`, and `bun`.
+- **Fixed**: **`kandown update` command behavior** — `kandown update` now queries the npm registry for the latest release, updates the global CLI package using the active package manager, and refreshes project `.kandown/kandown.html` files.
+- **Fixed**: **Terminal & tmux auto-update compatibility** — fixed `checkForUpdate()` invocation so interactive terminal sessions (including tmux and iTerm) automatically detect and offer updates.
+
+## 0.28.0 — 2026-07-20 — "Agent Instruction Modes & CLI Reference"
+
+- **Added**: **3 Base Agent Rule Modes (Verbose, Optimized, Caveman)** — redesigned the Agent instructions settings into 3 distinct rule density modes. Users can choose between **Verbose** (full reference guide), **Optimized** (concise, high-density structured rules tailored for LLMs), and **Caveman** (ultra-compact minimal token rules).
+- **Added**: **Quick CLI Commands Reference in Agent Rules** — added a concise CLI cheatsheet table (`kandown work`, `kandown list`, `kandown show`, `kandown create`, `kandown move`, `kandown assign`, `kandown commit`) right at the top of base rules across all modes so AI agents immediately know the native CLI commands available to interact with the board.
+- **Added**: **3-Step Numbered Layout for Agent Settings** — reorganized the Agent Instructions settings page into 3 clear numbered step cards: Step 1 (Base Rules mode & density), Step 2 (Project Guidelines stored in `.kandown/instructions.md`), and Step 3 (Live Board State data filters).
+- **Added**: **Quick Preset Instruction Chips** — added 1-click template insertion chips (`📦 pnpm`, `🧪 Test rule`, `🌳 Git rule`, `⚡ Task log`) below the project instructions editor for adding repository rules instantly.
+- **Added**: **Terminal-Style Sticky Live Preview Panel** — added an independent sticky preview panel on the right with window dot indicators, token estimation badge, layer legend badges (🟢 Step 1, 🟡 Step 2, 🔵 Step 3), 1-click Copy button, and real-time interactive color highlighting when hovering over options.
+
 ## 0.27.1 — 2026-07-20 — "Auto-Updater & Daemon Process Upgrade"
 
 - **Fixed**: **Environment inheritance during background auto-update** — cleaned inherited `npm_config_*` and `npm_*` environment variables when spawning `npm install -g kandown` in `checkForUpdate()`. Previously, if Kandown was run via `npx` or `npm run`, inherited local prefix overrides could cause global background updates to fail or target a temporary cache.

package/bin/kandown.js

@@ -313,40 +313,14 @@ async function checkForUpdate(argv = process.argv) {
 
   // 📖 Step 3: Run the update via npm or pnpm with animated progress.
   tuiProgress(`Updating to ${latest}…`, 25);
-
-  const updateOk = await new Promise((resolve) => {
-    const tryInstall = (cmd) => {
-      return new Promise((res) => {
-        const cleanEnv = { ...process.env };
-        for (const k of Object.keys(cleanEnv)) {
-          if (k.startsWith('npm_config_') || k.startsWith('npm_') || k === 'INIT_CWD') {
-            delete cleanEnv[k];
-          }
-        }
-        const child = spawn(cmd, ['install', '-g', 'kandown'], {
-          timeout: 60000,
-          stdio: ['pipe', 'pipe', 'pipe'],
-          env: cleanEnv,
-          detached: false,
-        });
-        child.stderr.on('data', () => {}); // silence npm noise
-        child.stdout.on('data', () => {});
-        child.on('error', () => res(false));
-        child.on('close', (code) => res(code === 0));
-      });
-    };
-    tryInstall('npm').then((ok) => {
-      if (ok) resolve(true);
-      else tryInstall('pnpm').then(resolve);
-    });
-  });
+  const updateOk = await performGlobalPackageUpdate(`kandown@${latest}`);
 
   // 📖 Clean up lock file regardless of outcome.
   try { if (existsSync(lockFile)) unlinkSync(lockFile); } catch { /* ignore */ }
 
   if (!updateOk) {
     tuiDone('✗', `${c.yellow}Auto-update failed${c.reset} — continuing with current version`);
-    log(`  Run ${c.cyan}npm install -g kandown${c.reset} to upgrade manually`);
+    log(`  Run ${c.cyan}pnpm add -g kandown@latest${c.reset} or ${c.cyan}npm install -g kandown@latest${c.reset} to upgrade manually`);
     log('');
     return;
   }
@@ -1018,29 +992,55 @@ function cmdInit(rawArgs) {
   log('');
 }
 
-function cmdUpdate(rawArgs) {
+async function cmdUpdate(rawArgs) {
   const current = getCurrentVersion();
   log(`${c.bold}kandown update${c.reset} ${c.dim}— v${current}${c.reset}`);
-  printVersionChangelog(current);
+
+  // 📖 Step 1: Check latest version on npm registry
+  const latest = await new Promise((resolve) => {
+    const child = spawn('npm', ['view', 'kandown', 'version'], {
+      timeout: 6000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
+      detached: false,
+    });
+    let stdout = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', () => {});
+    child.on('error', () => resolve(null));
+    child.on('close', (code) => {
+      if (code !== 0) return resolve(null);
+      const v = stdout.trim().replace(/^"|"$/g, '');
+      resolve(v || null);
+    });
+  });
+
+  if (latest && semverGt(latest, current) > 0) {
+    tuiProgress(`Updating kandown package v${current} → v${latest}…`, 30);
+    const updateOk = await performGlobalPackageUpdate(`kandown@${latest}`);
+    if (updateOk) {
+      tuiDone('✓', `${c.green}Successfully upgraded kandown to v${latest}${c.reset}`);
+      printVersionChangelog(latest);
+    } else {
+      tuiDone('✗', `${c.yellow}Global CLI update failed${c.reset} — try running: ${c.cyan}pnpm add -g kandown@latest${c.reset} or ${c.cyan}npm install -g kandown@latest${c.reset}`);
+    }
+  } else {
+    printVersionChangelog(current);
+    info(`kandown CLI is already up to date (v${current}).`);
+  }
 
   const args = parseArgs(rawArgs);
   const cwd = process.cwd();
   const kandownDir = resolve(cwd, args.path);
   const htmlDest = join(kandownDir, 'kandown.html');
 
-  if (!existsSync(htmlDest)) {
-    err(`No kandown.html found at ${c.bold}${htmlDest}${c.reset}`);
-    log(`  Run ${c.cyan}npx kandown init${c.reset} first.`);
-    process.exit(1);
-  }
-
-  const htmlSrc = join(PKG_ROOT, 'dist', 'index.html');
-  if (!existsSync(htmlSrc)) {
-    err(`Missing build output. Did you run 'npm run build'?`);
-    process.exit(1);
+  if (existsSync(htmlDest)) {
+    const htmlSrc = join(PKG_ROOT, 'dist', 'index.html');
+    if (existsSync(htmlSrc)) {
+      copyFileSync(htmlSrc, htmlDest);
+      success(`Refreshed ${args.path}/kandown.html`);
+    }
   }
-  copyFileSync(htmlSrc, htmlDest);
-  success(`Updated ${args.path}/kandown.html`);
 }
 
 /* ═════════════ One-shot task commands ═════════════ */
@@ -1575,18 +1575,32 @@ function priorityRank(p) {
 }
 
 const WORK_OUTPUT_SECTION_IDS = ['baseRules', 'projectInstructions', 'boardDigest'];
-const CONCISE_AGENT_RULES = `# Kandown agent rules — concise
+const OPTIMIZED_AGENT_RULES = `# Kandown agent rules
 
+## CLI Commands
+- \`kandown list\` (list tasks) · \`kandown show <id>\` (view task)
+- \`kandown create "<title>"\` (create task) · \`kandown move <id> <status>\` (move task column)
+- \`kandown assign <id> <user>\` · \`kandown commit\` (commit board to git)
+
+## Rules
 - Task state lives in project-root \`tasks/*.md\`; do not maintain a separate board index.
 - Before work, read the relevant task file and keep it updated while you progress.
 - Move tasks by editing frontmatter \`status:\`; complete work by setting \`status: Done\` and adding a markdown \`report:\` summary.
 - Update subtasks in-place: \`- [ ]\` → \`- [x]\`, with a short \`report:\` line for meaningful progress.
 - Board columns live in \`.kandown/kandown.json\` under \`board.columns\`; project instructions live in \`.kandown/instructions.md\`.
 - Never put Kandown task data inside \`.kandown/\`; tasks belong in \`./tasks/\`.`;
+
+const CAVEMAN_AGENT_RULES = `# Kandown agent rules
+
+CLI: kandown list | kandown show <id> | kandown create "<title>" | kandown move <id> <status> | kandown assign <id> <user> | kandown commit
+RULES: TASKS IN ./tasks/*.md. READ TASK BEFORE WORK. UPDATE SUBTASKS - [ ] -> - [x] + REPORT. MOVE: EDIT status:. DONE: status: Done + report:.`;
+
+const CONCISE_AGENT_RULES = OPTIMIZED_AGENT_RULES;
+
 const DEFAULT_WORK_OUTPUT = {
   mode: 'blocks',
   includeBaseRules: true,
-  baseRulesMode: 'full',
+  baseRulesMode: 'verbose',
   includeProjectInstructions: true,
   includeBoardDigest: true,
   sectionOrder: WORK_OUTPUT_SECTION_IDS,
@@ -1612,11 +1626,13 @@ function normalizeWorkOutputConfig(config) {
     ? raw.sectionOrder.filter(id => WORK_OUTPUT_SECTION_IDS.includes(id))
     : DEFAULT_WORK_OUTPUT.sectionOrder;
   const order = sectionOrder.length > 0 ? sectionOrder : DEFAULT_WORK_OUTPUT.sectionOrder;
+  const validBaseModes = ['verbose', 'optimized', 'caveman', 'full', 'concise'];
+  const baseMode = validBaseModes.includes(raw.baseRulesMode) ? raw.baseRulesMode : DEFAULT_WORK_OUTPUT.baseRulesMode;
   return {
     ...DEFAULT_WORK_OUTPUT,
     ...raw,
     mode: raw.mode === 'raw' ? 'raw' : 'blocks',
-    baseRulesMode: raw.baseRulesMode === 'concise' ? 'concise' : 'full',
+    baseRulesMode: baseMode,
     sectionOrder: order,
     rawTemplate: typeof raw.rawTemplate === 'string' && raw.rawTemplate.trim()
       ? raw.rawTemplate
@@ -1625,8 +1641,9 @@ function normalizeWorkOutputConfig(config) {
   };
 }
 
-function readBaseAgentRules(mode = 'full') {
-  if (mode === 'concise') return CONCISE_AGENT_RULES;
+function readBaseAgentRules(mode = 'verbose') {
+  if (mode === 'caveman') return CAVEMAN_AGENT_RULES;
+  if (mode === 'optimized' || mode === 'concise') return OPTIMIZED_AGENT_RULES;
   try {
     return readFileSync(join(PKG_ROOT, 'templates', 'AGENT_KANDOWN.md'), 'utf8').trim();
   } catch (e) {
@@ -3391,7 +3408,7 @@ switch (cmd) {
     break;
 
   case 'update':
-    cmdUpdate(rest);
+    await cmdUpdate(rest);
     break;
 
   // 📖 One-shot task commands — top-level, no "shell" wrapper. These are the