dig-burrow 1.2.0

package/.claude/burrow/lib/render.cjs

@@ -0,0 +1,330 @@
+'use strict';
+
+// --- Constants ---
+
+const HR = '\u2500'.repeat(40);
+const CHECKMARK = '\u2713';
+const CROSSMARK = '\u2717';
+const BRANCH = '\u251c\u2500';
+const CORNER = '\u2514\u2500';
+const PIPE = '\u2502';
+const DOT = '\u2022';
+const ARROW = '\u2192';
+const BREADCRUMB_SEP = ' \u203a ';
+const BODY_TRUNCATE_LENGTH = 200;
+const DIFF_TRUNCATE_LENGTH = 40;
+// Minimum terminal width floor: 2 (margin) + 2 (branch) + 1 (space) + 10 (id bracket) + 1 (space) + 15 (min title) + 2 (padding) + 7 (age) = 40
+const MIN_TERM_WIDTH = 40;
+
+// --- Internal Helpers ---
+
+/**
+ * Produce a relative age string from an ISO date string.
+ * @param {string} isoString
+ * @returns {string}
+ */
+function formatAge(isoString) {
+  if (typeof isoString !== 'string') return '???';
+  if (!isoString) return '???';
+  const now = Date.now();
+  const then = new Date(isoString).getTime();
+  if (isNaN(then)) return '???';
+  const diffMs = Math.max(0, now - then);
+  const diffSec = Math.floor(diffMs / 1000);
+
+  if (diffSec < 60) return 'just now';
+  const diffMin = Math.floor(diffSec / 60);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHours = Math.floor(diffMin / 60);
+  if (diffHours < 24) return `${diffHours}h ago`;
+  const diffDays = Math.floor(diffHours / 24);
+  if (diffDays < 7) return `${diffDays}d ago`;
+  const diffWeeks = Math.floor(diffDays / 7);
+  if (diffWeeks < 52) return `${diffWeeks}w ago`;
+  const diffYears = Math.floor(diffWeeks / 52);
+  return `${diffYears}y ago`;
+}
+
+/**
+ * Format created date: "YYYY-MM-DD (Xd ago)"
+ * @param {string} isoString
+ * @returns {string}
+ */
+function formatCreatedDate(isoString) {
+  if (!isoString) return `??? (???)`;
+  const date = new Date(isoString);
+  if (isNaN(date.getTime())) return `??? (???)`;
+  const yyyy = date.getUTCFullYear();
+  const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(date.getUTCDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd} (${formatAge(isoString)})`;
+}
+
+/**
+ * Format breadcrumb: "burrow > ancestors > card name"
+ * @param {Array<{id, title}>} ancestors - Ancestor breadcrumbs (not including card)
+ * @param {string} cardTitle
+ * @param {string} [context] - Optional context string after dot separator
+ * @returns {string}
+ */
+function formatBreadcrumb(ancestors, cardTitle, context) {
+  const safeCardTitle = (cardTitle && cardTitle.trim()) ? cardTitle : '(untitled)';
+  const parts = ['burrow'];
+  for (const a of ancestors) {
+    parts.push(a.title);
+  }
+  parts.push(safeCardTitle);
+  let result = parts.join(BREADCRUMB_SEP);
+  if (context) {
+    result += ` \u00b7 ${context}`;
+  }
+  return result;
+}
+
+/**
+ * Truncate string with ellipsis if over maxLen.
+ * @param {string} str
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + '\u2026';
+}
+
+
+/**
+ * Format a single card line for tree listing.
+ * @param {object} card - {id, title, created, archived, body, children, hasBody, descendantCount}
+ * @param {string} prefix - Box-drawing prefix (branch or corner)
+ * @param {number} termWidth - Terminal width
+ * @returns {string}
+ */
+function formatCardLine(card, prefix, termWidth) {
+  const tw = Math.max(MIN_TERM_WIDTH, termWidth || 80);
+  const id = `[${card.id}]`;
+  const hasBody = card.hasBody !== undefined ? card.hasBody : !!(card.body && card.body.trim());
+  const bodyMarker = hasBody ? ' +' : '';
+  const age = formatAge(card.created);
+  const descCount = card.descendantCount || 0;
+  const countStr = descCount > 0 ? ` (${descCount})` : '';
+  const archivedLabel = card.archived ? ' [archived]' : '';
+  const safeTitle = (card.title && card.title.trim()) ? card.title : '(untitled)';
+
+  // Left side without title: prefix + space + id + space
+  const leftFixedParts = `  ${prefix} ${id} `;
+  // Right side: just age
+  const rightSide = age;
+  // Indicators after title
+  const indicators = `${countStr}${bodyMarker}${archivedLabel}`;
+
+  // Available space for title
+  const availableForTitle = tw - leftFixedParts.length - indicators.length - 2 - rightSide.length;
+  const title = availableForTitle > 0 ? truncate(safeTitle, availableForTitle) : truncate(safeTitle, 1);
+
+  // Pad middle to right-align age
+  const leftContent = `${leftFixedParts}${title}${indicators}`;
+  const padding = Math.max(1, tw - leftContent.length - rightSide.length);
+
+  return `${leftContent}${' '.repeat(padding)}${rightSide}`;
+}
+
+/**
+ * Recursively render tree lines with proper indentation.
+ * @param {Array} children - Array of card objects (may have nested children)
+ * @param {number} depth - Current nesting depth (0 = top-level children)
+ * @param {string} indent - Accumulated indent prefix for this level
+ * @param {number} tw - Terminal width
+ * @returns {string[]} Array of formatted lines
+ */
+function renderTreeLines(children, depth, indent, tw) {
+  const result = [];
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    const isLast = i === children.length - 1;
+    const prefix = indent + (isLast ? CORNER : BRANCH);
+    result.push(formatCardLine(child, prefix, tw));
+
+    if (child.children && child.children.length > 0) {
+      const nextIndent = indent + (isLast ? '    ' : `${PIPE}   `);
+      const subLines = renderTreeLines(child.children, depth + 1, nextIndent, tw);
+      for (const sl of subLines) {
+        result.push(sl);
+      }
+    }
+  }
+  return result;
+}
+
+// --- Exported Functions ---
+
+/**
+ * Render a card in full detail format.
+ * @param {object} card - Full card object
+ * @param {Array<{id, title}>} breadcrumbs - Ancestor breadcrumbs
+ * @param {object} opts - {full, termWidth, archiveFilter}
+ * @returns {string}
+ */
+function renderCard(card, breadcrumbs, opts) {
+  const { full, termWidth } = opts || {};
+  const tw = Math.max(MIN_TERM_WIDTH, termWidth || 80);
+  const lines = [];
+  const safeTitle = (card.title && card.title.trim()) ? card.title : '(untitled)';
+
+  // Breadcrumb header
+  if (card.id === '(root)') {
+    lines.push('burrow');
+  } else {
+    lines.push(formatBreadcrumb(breadcrumbs || [], safeTitle));
+  }
+  lines.push('');
+
+  // Title section
+  lines.push(HR);
+  lines.push(safeTitle);
+  lines.push(HR);
+
+  // Metadata
+  lines.push(`id:       ${card.id}`);
+  lines.push(`created:  ${formatCreatedDate(card.created)}`);
+  lines.push(`archived: ${card.archived ? 'yes' : 'no'}`);
+  lines.push(HR);
+
+  // Children section — pre-filtered by renderTree, trust the data
+  const children = card.children || [];
+
+  if (children.length === 0) {
+    lines.push('children: (none)');
+  } else {
+    const activeCount = children.length;
+    const totalDescendants = children.reduce(
+      (sum, c) => sum + 1 + (c.descendantCount || 0), 0
+    );
+    lines.push(`children: ${activeCount} cards (${totalDescendants} total)`);
+    const treeLines = renderTreeLines(children, 0, '', tw);
+    for (const tl of treeLines) {
+      lines.push(tl);
+    }
+  }
+  lines.push(HR);
+
+  // Body section
+  const body = card.body || '';
+  if (!body.trim()) {
+    lines.push('body:     (empty)');
+  } else {
+    lines.push('body:');
+    let displayBody = body;
+    if (!full && displayBody.length > BODY_TRUNCATE_LENGTH) {
+      displayBody = displayBody.slice(0, BODY_TRUNCATE_LENGTH) +
+        '\u2026(truncated \u2014 use --full for complete body)';
+    }
+    const bodyLines = displayBody.split('\n');
+    for (const bl of bodyLines) {
+      lines.push(`  ${bl}`);
+    }
+  }
+  lines.push(HR);
+
+  return lines.join('\n');
+}
+
+/**
+ * Render mutation output.
+ * @param {string} type - 'add'|'edit'|'remove'|'move'|'archive'|'unarchive'
+ * @param {object} result - Command result
+ * @param {object} opts - {breadcrumbs, card, oldTitle, oldBody, fromParentTitle, termWidth}
+ * @returns {string}
+ */
+function renderMutation(type, result, opts) {
+  const { breadcrumbs, card, oldTitle, oldBody, fromParentTitle, toParentTitle, termWidth } = opts || {};
+
+  switch (type) {
+    case 'add': {
+      const cardToRender = card || result;
+      const detail = renderCard(cardToRender, breadcrumbs || [], { termWidth });
+      return `${CHECKMARK} Added card\n\n${detail}`;
+    }
+
+    case 'edit': {
+      const cardToRender = card || result;
+      const diffLines = [];
+
+      if (oldTitle !== undefined && oldTitle !== cardToRender.title) {
+        diffLines.push(
+          `  title: ${truncate(oldTitle, DIFF_TRUNCATE_LENGTH)} ${ARROW} ${truncate(cardToRender.title, DIFF_TRUNCATE_LENGTH)}`
+        );
+      }
+
+      if (oldBody !== undefined && oldBody !== cardToRender.body) {
+        const oldBodyClean = oldBody.replace(/\n/g, ' ');
+        const newBodyClean = (cardToRender.body || '').replace(/\n/g, ' ');
+        diffLines.push(
+          `  body: ${truncate(oldBodyClean, DIFF_TRUNCATE_LENGTH)} ${ARROW} ${truncate(newBodyClean, DIFF_TRUNCATE_LENGTH)}`
+        );
+      }
+
+      const detail = renderCard(cardToRender, breadcrumbs || [], { termWidth });
+      const diffSection = diffLines.length > 0 ? '\n' + diffLines.join('\n') + '\n' : '';
+      return `${CHECKMARK} Edited card${diffSection}\n${detail}`;
+    }
+
+    case 'remove': {
+      const childPart = result.descendantCount > 0
+        ? ` (and ${result.descendantCount} children)`
+        : '';
+      return `${CHECKMARK} Removed "${result.title}" [${result.id}]${childPart}`;
+    }
+
+    case 'move': {
+      const from = fromParentTitle || 'root';
+      const to = toParentTitle || 'root';
+      return `${CHECKMARK} Moved "${result.title}" [${result.id}]: ${from} ${ARROW} ${to}`;
+    }
+
+    case 'archive': {
+      const childPart = result.descendantCount > 0
+        ? ` (and ${result.descendantCount} children)`
+        : '';
+      return `${CHECKMARK} Archived "${result.title}" [${result.id}]${childPart}`;
+    }
+
+    case 'unarchive': {
+      const childPart = result.descendantCount > 0
+        ? ` (and ${result.descendantCount} children)`
+        : '';
+      return `${CHECKMARK} Unarchived "${result.title}" [${result.id}]${childPart}`;
+    }
+
+    default:
+      return `${CHECKMARK} ${type} completed`;
+  }
+}
+
+/**
+ * Render a breadcrumb path string.
+ * @param {Array<{id, title}>} pathArray - From root to target
+ * @returns {string}
+ */
+function renderPath(pathArray) {
+  if (!pathArray || pathArray.length === 0) return 'burrow';
+  const parts = ['burrow'];
+  for (const entry of pathArray) {
+    parts.push(entry.title);
+  }
+  const lastEntry = pathArray[pathArray.length - 1];
+  // Replace last part with "title [id]"
+  parts[parts.length - 1] = `${lastEntry.title} [${lastEntry.id}]`;
+  return parts.join(BREADCRUMB_SEP);
+}
+
+/**
+ * Render an error message.
+ * @param {string} message
+ * @returns {string}
+ */
+function renderError(message) {
+  return `${CROSSMARK} ${message}`;
+}
+
+module.exports = { renderCard, renderMutation, renderPath, renderError };

package/.claude/burrow/lib/version.cjs

@@ -0,0 +1,137 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const https = require('node:https');
+
+// Cache file path relative to targetDir
+const UPDATE_CACHE_FILE = '.planning/burrow/.update-check';
+
+// 24 hours in milliseconds
+const CACHE_TTL_MS = 86400000;
+
+/**
+ * Read the VERSION file from targetDir/.claude/burrow/VERSION.
+ * @param {string} targetDir - Root of the target (installed) project
+ * @returns {string|null} Trimmed version string or null on missing/error
+ */
+function getInstalledVersion(targetDir) {
+  try {
+    const versionPath = path.join(targetDir, '.claude', 'burrow', 'VERSION');
+    return fs.readFileSync(versionPath, 'utf-8').trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Compare two semver strings numerically.
+ * null is treated as "0.0.0" (always behind any real version).
+ *
+ * @param {string|null} a
+ * @param {string|null} b
+ * @returns {-1|0|1} -1 if a < b, 0 if a == b, 1 if a > b
+ */
+function compareSemver(a, b) {
+  const parse = (v) => (v ? v.split('.').map((n) => parseInt(n, 10) || 0) : [0, 0, 0]);
+  const [aMaj, aMin, aPatch] = parse(a);
+  const [bMaj, bMin, bPatch] = parse(b);
+
+  if (aMaj !== bMaj) return aMaj < bMaj ? -1 : 1;
+  if (aMin !== bMin) return aMin < bMin ? -1 : 1;
+  if (aPatch !== bPatch) return aPatch < bPatch ? -1 : 1;
+  return 0;
+}
+
+/**
+ * Fetch the latest version of the create-burrow package from the npm registry.
+ * Returns null on network error or parse failure — never throws.
+ *
+ * @returns {Promise<string|null>}
+ */
+function fetchLatestVersion() {
+  return new Promise((resolve) => {
+    const req = https.get('https://registry.npmjs.org/create-burrow/latest', {
+      headers: { 'Accept': 'application/json' },
+      timeout: 5000,
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const pkg = JSON.parse(data);
+          resolve(pkg.version || null);
+        } catch (_) {
+          resolve(null);
+        }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+/**
+ * Check if an update is available by comparing the installed version against
+ * the latest version published on npm.
+ *
+ * Uses a 24h cache stored at cwd/.planning/burrow/.update-check to avoid
+ * hitting the registry on every CLI invocation.
+ *
+ * Returns null if:
+ *   - The cache is fresh (< 24h old)
+ *   - Any error occurs (network failure, file I/O, etc.)
+ *
+ * Returns { outdated: boolean, latestVersion: string|null, installedVersion: string|null }
+ *   after performing a fresh check.
+ *
+ * @param {string} cwd - Root of the target (installed) project
+ * @returns {Promise<{ outdated: boolean, latestVersion: string|null, installedVersion: string|null }|null>}
+ */
+async function checkForUpdate(cwd) {
+  try {
+    const cachePath = path.join(cwd, UPDATE_CACHE_FILE);
+
+    // Check if cache is fresh
+    if (fs.existsSync(cachePath)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+        if (cache.lastCheck && Date.now() - Date.parse(cache.lastCheck) < CACHE_TTL_MS) {
+          return null; // Cache is still valid — skip check
+        }
+      } catch (_) {
+        // Corrupt cache — proceed with fresh check
+      }
+    }
+
+    const latestVersion = await fetchLatestVersion();
+    const installedVersion = getInstalledVersion(cwd);
+    const outdated = compareSemver(installedVersion, latestVersion) < 0;
+
+    // Write cache
+    try {
+      const cacheDir = path.dirname(cachePath);
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+      fs.writeFileSync(
+        cachePath,
+        JSON.stringify({ lastCheck: new Date().toISOString(), latestVersion, installedVersion })
+      );
+    } catch (_) {
+      // Cache write failure is non-fatal
+    }
+
+    return { outdated, latestVersion, installedVersion };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = {
+  getInstalledVersion,
+  compareSemver,
+  checkForUpdate,
+  fetchLatestVersion,
+  UPDATE_CACHE_FILE,
+};

package/.claude/burrow/lib/warren.cjs

@@ -0,0 +1,168 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ensureDataDir } = require('./core.cjs');
+
+const DATA_FILE = 'cards.json';
+const BACKUP_EXT = '.bak';
+const TMP_EXT = '.tmp';
+
+/**
+ * Resolve the path to cards.json within the given working directory.
+ * @param {string} cwd
+ * @returns {string}
+ */
+function dataPath(cwd) {
+  return path.join(cwd, '.planning', 'burrow', DATA_FILE);
+}
+
+/**
+ * Recursively migrate a single card from v1 to v2 format.
+ * - Renames notes -> body
+ * - Deletes position
+ * - Flattens children from {ordering, cards/items: []} to plain []
+ * @param {object} card
+ */
+function migrateCard(card) {
+  // Rename notes -> body
+  if (card.notes !== undefined) {
+    card.body = card.notes;
+    delete card.notes;
+  }
+  if (card.body === undefined) {
+    card.body = '';
+  }
+
+  // Delete position
+  delete card.position;
+
+  // Flatten children
+  if (card.children && !Array.isArray(card.children)) {
+    // v1 children: {ordering, cards: [...]} or {ordering, items: [...]}
+    const childArray = card.children.cards || card.children.items || [];
+    card.children = childArray;
+  }
+  if (!card.children) {
+    card.children = [];
+  }
+
+  // Recurse into children
+  for (const child of card.children) {
+    migrateCard(child);
+  }
+}
+
+/**
+ * Migrate data from v1 to v2 format. Idempotent on v2 data.
+ * - Root: items -> cards, delete ordering
+ * - Cards: notes -> body, delete position, flatten children
+ * - Set version: 2
+ * @param {object} data
+ * @returns {object} Migrated data (mutated in place)
+ */
+function migrate(data) {
+  if (data.version >= 2) return data;
+
+  // Root: items -> cards
+  if (data.items && !data.cards) {
+    data.cards = data.items;
+    delete data.items;
+  }
+
+  // Delete root ordering
+  delete data.ordering;
+
+  // Migrate each card
+  if (data.cards) {
+    for (const card of data.cards) {
+      migrateCard(card);
+    }
+  } else {
+    data.cards = [];
+  }
+
+  data.version = 2;
+  return data;
+}
+
+/**
+ * Validate the schema of parsed cards.json data.
+ * Throws a human-readable Error if the data is structurally invalid.
+ * @param {*} data - Parsed JSON value
+ */
+function validateSchema(data) {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error('Burrow: invalid cards.json — expected a JSON object, got ' + (data === null ? 'null' : Array.isArray(data) ? 'array' : typeof data));
+  }
+
+  // Support v1 (items) and v2 (cards) root arrays
+  const rootArray = data.cards !== undefined ? data.cards : data.items;
+
+  if (rootArray === undefined) {
+    throw new Error("Burrow: invalid cards.json — missing 'cards' array");
+  }
+
+  if (!Array.isArray(rootArray)) {
+    throw new Error("Burrow: invalid cards.json — expected 'cards' to be an array, got " + typeof rootArray);
+  }
+
+  // Spot-check: first element must have a string id (if present)
+  if (rootArray.length > 0 && typeof rootArray[0].id !== 'string') {
+    throw new Error("Burrow: invalid cards.json — expected card 'id' to be a string, got " + typeof rootArray[0].id);
+  }
+}
+
+/**
+ * Load the burrow data from cards.json.
+ * Returns default empty v2 structure if the file does not exist.
+ * Automatically migrates v1 data to v2 format.
+ * @param {string} cwd - Working directory
+ * @returns {object} Parsed data in v2 format
+ */
+function load(cwd) {
+  const filePath = dataPath(cwd);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw);
+    validateSchema(data);
+    // Skip migrate() entirely for already-v2 data (PERF-09)
+    if (data.version < 2) {
+      return migrate(data);
+    }
+    return data;
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { version: 2, cards: [] };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Save the burrow data to cards.json with atomic write and backup.
+ * 1. Ensure data directory exists
+ * 2. If cards.json exists, copy to cards.json.bak
+ * 3. Write to cards.json.tmp
+ * 4. Rename tmp to cards.json
+ * @param {string} cwd - Working directory
+ * @param {object} data - Data to save
+ */
+function save(cwd, data) {
+  ensureDataDir(cwd);
+  const filePath = dataPath(cwd);
+  const backupPath = filePath + BACKUP_EXT;
+  const tmpPath = filePath + TMP_EXT;
+
+  // Backup existing file
+  if (fs.existsSync(filePath)) {
+    fs.copyFileSync(filePath, backupPath);
+  }
+
+  // Atomic write: tmp then rename
+  const content = JSON.stringify(data, null, 2) + '\n';
+  fs.writeFileSync(tmpPath, content, 'utf-8');
+  fs.renameSync(tmpPath, filePath);
+}
+
+module.exports = { load, save, migrate };