sandtable 0.3.1 → 1.0.1

package/harness/install-hooks.sh

@@ -1,17 +1,53 @@
 #!/bin/sh
 # Install sandtable git hooks into the current repo
-# Usage: sh harness/install-hooks.sh [project-root]
+# Usage: sh harness/install-hooks.sh [project-root] [--force]
+
+ROOT=""
+FORCE=0
+for arg in "$@"; do
+  case "$arg" in
+    --force) FORCE=1 ;;
+    *) ROOT="$arg" ;;
+  esac
+done
+ROOT="${ROOT:-$(pwd)}"
 
-ROOT="${1:-$(pwd)}"
 HOOKS_DIR="$ROOT/.git/hooks"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 if [ ! -d "$HOOKS_DIR" ]; then
   echo "Error: not a git repository (no .git/hooks)"
   exit 1
 fi
 
-cp harness/post-commit "$HOOKS_DIR/post-commit.sandtable"
-cp harness/post-merge "$HOOKS_DIR/post-merge.sandtable"
+# ---- Conflict detection: check for existing non-sandtable hooks ----
+CONFLICTS=""
+for hook in post-commit post-merge; do
+  HOOK_PATH="$HOOKS_DIR/$hook"
+  if [ -f "$HOOK_PATH" ] && ! grep -q "sandtable" "$HOOK_PATH" 2>/dev/null; then
+    CONFLICTS="$CONFLICTS $hook"
+  fi
+done
+
+if [ -n "$CONFLICTS" ] && [ "$FORCE" != "1" ]; then
+  echo "Error: 已有非 sandtable hook 存在:$CONFLICTS"
+  echo ""
+  echo "sandtable 不会覆盖已有 hook，以免破坏其他工具链。选项："
+  echo "  1. 手动合并: 在现有 hook 末尾添加以下行："
+  echo "     sh .git/hooks/<hook>.sandtable"
+  echo "  2. 强制覆盖: sh $(basename "$0") --force"
+  echo ""
+  echo "已有 hook 内容预览:"
+  for hook in $CONFLICTS; do
+    echo "  --- $hook ---"
+    sed 's/^/  | /' "$HOOKS_DIR/$hook"
+    echo "  -------------"
+  done
+  exit 1
+fi
+
+cp "$SCRIPT_DIR/post-commit" "$HOOKS_DIR/post-commit.sandtable"
+cp "$SCRIPT_DIR/post-merge" "$HOOKS_DIR/post-merge.sandtable"
 chmod +x "$HOOKS_DIR/post-commit.sandtable"
 chmod +x "$HOOKS_DIR/post-merge.sandtable"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandtable",
-  "version": "0.3.1",
+  "version": "1.0.1",
   "description": "AI 编程项目可视化指挥面板 — 双视图 dashboard，多源数据融合",
   "main": "src/cli/sandtable.js",
   "bin": {

package/server.js

@@ -5,6 +5,26 @@ const path = require('path');
 const ROOT = path.resolve(__dirname);
 const PORT = parseInt(process.env.PORT || process.argv[2], 10) || 5199;
 
+// Parse --host and --token from CLI args (safe by default: 127.0.0.1)
+let HOST = '127.0.0.1';
+let TOKEN = '';
+for (let i = 0; i < process.argv.length; i++) {
+  if (process.argv[i] === '--host' && process.argv[i + 1] && !process.argv[i + 1].startsWith('--')) {
+    HOST = process.argv[i + 1];
+    i++;
+  } else if (process.argv[i] === '--token') {
+    if (process.argv[i + 1] && !process.argv[i + 1].startsWith('--')) {
+      TOKEN = process.argv[i + 1];
+      i++;
+    } else {
+      TOKEN = require('crypto').randomBytes(16).toString('hex');
+    }
+  }
+}
+if ((HOST === '0.0.0.0' || HOST === '::') && !TOKEN) {
+  TOKEN = require('crypto').randomBytes(16).toString('hex');
+}
+
 const MIME = {
   '.html': 'text/html; charset=utf-8',
   '.css': 'text/css; charset=utf-8',
@@ -16,21 +36,51 @@ const MIME = {
   '.svg': 'image/svg+xml',
 };
 
-// Only serve from these two directories — project sources are not exposed
+// Only serve from these directories — project sources are not exposed
 const ALLOWED_PREFIXES = [
   path.join(ROOT, 'dashboard'),
   path.join(ROOT, 'data'),
+  path.join(ROOT, 'docs'),
 ];
 
+// Root-level files that are safe to serve (documentation, config)
+const ROOT_ALLOWED = new Set([
+  'AGENTS.md', 'CLAUDE.md', 'README.md', 'INSTALL.md',
+  'CHANGELOG.md', 'CONTRIBUTING.md',
+]);
+
 function isAllowed(filePath) {
   if (!filePath.startsWith(ROOT)) return false;
   for (const prefix of ALLOWED_PREFIXES) {
     if (filePath.startsWith(prefix)) return true;
   }
+  // Allow specific root-level documentation files
+  if (ROOT_ALLOWED.has(path.relative(ROOT, filePath))) return true;
   return false;
 }
 
 http.createServer((req, res) => {
+  // Token authentication (when binding to public interface)
+  if (TOKEN) {
+    let qIdx = req.url.indexOf('?');
+    let hasToken = false;
+    if (qIdx !== -1) {
+      let qs = req.url.substring(qIdx + 1);
+      let pairs = qs.split('&');
+      for (let pi = 0; pi < pairs.length; pi++) {
+        let kv = pairs[pi].split('=');
+        if (decodeURIComponent(kv[0]) === 'token' && kv[1] === TOKEN) {
+          hasToken = true;
+          break;
+        }
+      }
+    }
+    if (!hasToken) {
+      res.writeHead(401, { 'Content-Type': 'text/plain; charset=utf-8' });
+      return res.end('401 Unauthorized — 请在 URL 后添加 ?token=' + TOKEN);
+    }
+  }
+
   let url = req.url === '/' ? '/dashboard/dashboard.html' : req.url;
   url = url.replace(/^\/(css|js)\//, '/dashboard/$1/');
 
@@ -54,7 +104,8 @@ http.createServer((req, res) => {
     res.writeHead(500, { 'Content-Type': 'text/plain' });
     res.end('500: ' + e.message);
   }
-}).listen(PORT, () => {
-  console.log('Sandtable: http://localhost:' + PORT);
+}).listen(PORT, HOST, () => {
+  console.log('Sandtable: http://' + HOST + ':' + PORT);
+  if (TOKEN) console.log('Token: ' + TOKEN + '  (访问需携带 ?token=' + TOKEN + ')');
   console.log('Project:', ROOT);
 });

package/src/builder/build.js

@@ -3,7 +3,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { scan, loadConfig, normalizeCategory, DISPLAY_CATEGORIES, PRIMARY_CATEGORIES } = require('../scanner/scan');
+const { scan } = require('../scanner/scan');
+const { buildTracks } = require('../progress/parser');
+const { loadContract } = require('../contract/loader');
 
 // ---- Markdown Table Parser (unchanged from v1) ----
 function parseMarkdownTables(content) {
@@ -30,201 +32,45 @@ function parseMarkdownTables(content) {
   return results;
 }
 
-// ---- Primary Tree Builder ----
-function buildPrimaryTree(planFiles, allFiles, projectRoot) {
+// ---- Tracks to Elements (converts parser output to timeline element format) ----
+function tracksToElements(tracks) {
   const elements = [];
-
-  // Collect task rows from task-board-like files
-  const taskRows = [];
-  for (const pf of planFiles) {
-    const fp = path.join(projectRoot, pf.path);
-    if (!fs.existsSync(fp)) continue;
-    const content = fs.readFileSync(fp, 'utf-8');
-    const tables = parseMarkdownTables(content);
-    const hasTaskCols = tables.length > 0 &&
-      (Object.keys(tables[0]).some(k => /任务|task|#/.test(k)));
-    if (hasTaskCols) {
-      for (const row of tables) {
-        taskRows.push({ ...row, _source: pf.path });
-      }
-    }
-  }
-
-  // Build phases from milestone/plan files with markdown tables
-  const milestoneFiles = planFiles.filter(f =>
-    f.elementType === 'milestone' ||
-    (f.summary && f.summary.type === 'milestone')
-  );
-
-  for (const mf of milestoneFiles) {
-    const fp = path.join(projectRoot, mf.path);
-    if (!fs.existsSync(fp)) continue;
-    const content = fs.readFileSync(fp, 'utf-8');
-    const rows = parseMarkdownTables(content);
-
-    const milestones = rows.map((row, i) => {
-      const keys = Object.keys(row);
-      const milestoneName = row[keys[0]] || '';
-      const version = row[keys[1]] || '';
-      const signal = row[keys[2]] || '';
-      const statusRaw = (row[keys[3]] || 'pending').toLowerCase();
-      const status = statusRaw.includes('in_progress') ? 'in_progress'
-        : statusRaw.includes('complete') ? 'completed'
-        : statusRaw.includes('block') ? 'blocked'
-        : 'pending';
-
-      // Match subtasks from task board
-      const subtasks = taskRows
-        .filter(tr => {
-          const taskName = tr[Object.keys(tr)[1]] || tr[Object.keys(tr)[0]] || '';
-          return taskName.includes(milestoneName) ||
-            milestoneName.includes(taskName.substring(0, 6));
-        })
-        .slice(0, 3)
-        .map(tr => {
-          const tKeys = Object.keys(tr);
-          const statusKey = tKeys.find(k => /状态|status/i.test(k));
-          const statusCol = statusKey ? tr[statusKey] : (tr[tKeys[4]] || tr[tKeys[3]] || '');
-          const isCompleted = /✅|\[x\]|completed|complete/i.test(statusCol);
-          const isInProgress = /⏳|\[\s*\]|in.progress/i.test(statusCol);
-          const typeKey = tKeys.find(k => /类型|type/i.test(k));
-          const typeCol = typeKey ? tr[typeKey] : (tr[tKeys[3]] || tr[tKeys[2]] || '');
-          return {
-            id: tr[tKeys[0]] || '',
-            name: tr[tKeys[1]] || tr[tKeys[0]] || '',
-            status: isCompleted ? 'completed' : isInProgress ? 'in_progress' : 'pending',
-            kind: 'primary',
-            elementType: 'subtask',
-            timeGroup: 'current',
-            timeLabel: '',
-            date: null,
-            source: { file: tr._source || mf.path, title: mf.title },
-            summary: '',
-            tags: [],
-            related: [],
-            children: [],
-          };
-        });
-
-      return {
-        id: 'ms-' + (milestoneName.replace(/^M/, '').substring(0, 10) || `M${i + 1}`),
-        kind: 'primary',
-        elementType: 'milestone',
-        category: 'roadmap',
-        name: version ? `${milestoneName} (${version})` : milestoneName,
-        status,
-        timeGroup: 'current',
-        timeLabel: signal,
-        date: mf.date || null,
-        source: { file: mf.path, title: mf.title },
-        summary: '',
-        tags: [],
-        related: [],
-        children: subtasks,
-        order: i + 1,
-      };
-    });
-
-    elements.push({
-      id: 'phase-' + (elements.length + 1),
-      kind: 'primary',
-      elementType: 'phase',
-      category: 'roadmap',
-      name: mf.summary ? mf.summary.summary : mf.title,
-      status: mf.summary ? mf.summary.status : 'in_progress',
-      timeGroup: 'current',
-      timeLabel: '',
-      date: mf.date || null,
-      source: { file: mf.path, title: mf.title },
-      summary: mf.summary ? (mf.summary.summary || '') : '',
-      tags: mf.summary ? (mf.summary.tags || []) : [],
-      related: mf.summary ? (mf.summary.related || []) : [],
-      children: milestones,
-      order: elements.length + 1,
-    });
-  }
-
-  // Fallback: default phase from any plan-category files with summaries
-  if (elements.length === 0 && planFiles.length > 0) {
-    const tasks = planFiles
-      .filter(f => f.summary)
-      .map(f => ({
-        id: 'task-' + f.path.replace(/[/.]/g, '-'),
-        kind: 'primary',
-        elementType: 'task',
-        category: 'roadmap',
-        name: f.summary.summary,
-        status: f.summary.status || 'pending',
-        timeGroup: 'current',
-        timeLabel: '',
-        date: f.date || null,
-        source: { file: f.path, title: f.title },
-        summary: f.summary.summary || '',
-        tags: f.summary.tags || [],
-        related: f.summary.related || [],
-        children: [],
-      }));
-
-    elements.push({
-      id: 'phase-default',
-      kind: 'primary',
-      elementType: 'phase',
-      category: 'roadmap',
-      name: '当前阶段',
-      status: 'in_progress',
-      timeGroup: 'current',
-      timeLabel: '',
-      date: null,
-      source: { file: '', title: '' },
-      summary: '',
-      tags: [],
-      related: [],
-      children: [{
-        id: 'ms-current',
+  for (const track of tracks) {
+    for (const phase of track.phases) {
+      elements.push({
+        id: 'ms-' + track.id + '-' + phase.id.replace(/[^a-zA-Z0-9]/g, '-'),
         kind: 'primary',
         elementType: 'milestone',
         category: 'roadmap',
-        name: '进行中',
-        status: 'in_progress',
+        name: phase.name,
+        status: phase.status,
         timeGroup: 'current',
-        timeLabel: '',
-        date: null,
-        source: { file: '', title: '' },
+        timeLabel: phase.batch || '',
+        date: phase.date || null,
+        source: { file: track.source, title: phase.name },
         summary: '',
-        tags: [],
+        tags: [track.id],
         related: [],
-        children: tasks,
-        order: 1,
-      }],
-      order: 1,
-    });
-  }
-
-  // Extract conclusion elements from files with type=conclusion
-  const conclusionFiles = allFiles.filter(f =>
-    f.elementType === 'conclusion' ||
-    (f.summary && f.summary.type === 'conclusion')
-  );
-  for (const cf of conclusionFiles) {
-    elements.push({
-      id: 'conclusion-' + cf.path.replace(/[/.]/g, '-'),
-      kind: 'primary',
-      elementType: 'conclusion',
-      category: 'roadmap',
-      name: cf.title,
-      status: cf.summary ? (cf.summary.status || 'completed') : 'completed',
-      timeGroup: 'past',
-      timeLabel: cf.date || '',
-      date: cf.date || null,
-      source: { file: cf.path, title: cf.title },
-      summary: cf.summary ? (cf.summary.summary || '') : '',
-      tags: cf.summary ? (cf.summary.tags || []) : [],
-      related: cf.summary ? (cf.summary.related || []) : [],
-      children: [],
-      order: 0,
-    });
+        children: (phase.tasks || []).map(t => ({
+          id: 'task-' + t.id.replace(/[^a-zA-Z0-9]/g, '-'),
+          kind: 'primary',
+          elementType: 'subtask',
+          category: 'roadmap',
+          name: t.title,
+          status: t.status,
+          timeGroup: 'current',
+          timeLabel: '',
+          date: null,
+          source: { file: track.source, title: t.title },
+          summary: '',
+          tags: [track.id, t.actor].filter(Boolean),
+          related: [],
+          children: [],
+        })),
+        order: elements.length + 1,
+      });
+    }
   }
-
   return elements;
 }
 
@@ -278,25 +124,29 @@ function classifyTimeGroup(element, timeRules, today) {
 
 // ---- Filter Type Manifest Builder ----
 function buildFilterTypes(files, secondaryTypesDefaultOff) {
-  const secondaryFiles = files.filter(f => f.kind === 'secondary');
-  const catCounts = {};
-
-  for (const f of secondaryFiles) {
-    const cat = normalizeCategory(f.elementType);
-    catCounts[cat] = (catCounts[cat] || 0) + 1;
-  }
-
-  const result = [];
-  for (const [cat, def] of Object.entries(DISPLAY_CATEGORIES)) {
-    // Skip primary-only categories (all their elementTypes are kind=primary, no secondary files)
-    if (PRIMARY_CATEGORIES && PRIMARY_CATEGORIES.has(cat)) continue;
-    const count = catCounts[cat] || 0;
-    if (count > 0) {
-      result.push({ type: cat, label: def.label, count, defaultEnabled: !secondaryTypesDefaultOff });
+  // Derive filter types from actual file data instead of hardcoded constants
+  const filterTypes = [];
+  const seen = new Set();
+  for (const f of files) {
+    const key = f.category + ':' + f.elementType;
+    if (!seen.has(key)) {
+      seen.add(key);
+      filterTypes.push({
+        category: f.category,
+        type: f.elementType,
+        label: (f.category || 'unknown') + ' › ' + (f.elementType || 'unknown'),
+        count: 0,
+        defaultEnabled: !secondaryTypesDefaultOff
+      });
     }
   }
-
-  return result;
+  // Count occurrences
+  for (const f of files) {
+    const key = f.category + ':' + f.elementType;
+    const ft = filterTypes.find(ft => (ft.category + ':' + ft.type) === key);
+    if (ft) ft.count++;
+  }
+  return filterTypes;
 }
 
 // ---- Conventions Builder (auto-extract from docs/conventions/) ----
@@ -768,21 +618,20 @@ function buildTimeline(files, projectRoot, config) {
   const displayCfg = (config && config.display) ? config.display : {};
   const maxBriefLength = displayCfg.maxBriefLength || 200;
 
-  // Step 1: Build primary tree from roadmap-category files
-  const planFiles = files.filter(f =>
-    f.kind === 'primary' && (f.category === 'roadmap' || f.elementType === 'phase' ||
-      f.elementType === 'milestone' || f.elementType === 'roadmap' || f.elementType === 'task' || f.elementType === 'subtask')
-  );
+  // Step 1: Build tracks from progressSources (replaces buildPrimaryTree)
+  const progressSources = (config && config._progressSources) ? config._progressSources : [];
+  const { tracks, currentNode } = buildTracks(progressSources, projectRoot);
+
+  // Convert tracks to elements format for backward compatibility
+  const primaryTree = tracksToElements(tracks);
 
   // Also include decision/refactor/conclusion type primary files
   const otherPrimary = files.filter(f =>
-    f.kind === 'primary' && !planFiles.includes(f) &&
+    f.kind === 'primary' &&
     (f.elementType === 'decision' || f.elementType === 'conclusion' ||
      f.elementType === 'refactor' || f.category === 'decision')
   );
 
-  const primaryTree = buildPrimaryTree(planFiles, files, projectRoot);
-
   // Build primary flat list for non-plan primary files
   const primaryFlat = otherPrimary
     .filter(f => f.hasSummary || f.elementType !== 'unknown')
@@ -844,6 +693,8 @@ function buildTimeline(files, projectRoot, config) {
     elements: allElements,
     events,
     filterTypes,
+    tracks,
+    currentNode,
     display: {
       secondaryTypesDefaultOff: displayCfg.secondaryTypesDefaultOff !== false,
       conventionsManualOnly: displayCfg.conventionsManualOnly !== false,
@@ -854,34 +705,73 @@ function buildTimeline(files, projectRoot, config) {
 
 // ---- Backward Compatibility: timeline → roadmap.json ----
 function timelineToRoadmapCompat(timeline) {
-  const phases = [];
-  for (const el of timeline.elements) {
+  var phases = [];
+
+  // New: source phases from tracks when available
+  if (timeline.tracks && timeline.tracks.length > 0) {
+    for (var ti = 0; ti < timeline.tracks.length; ti++) {
+      var track = timeline.tracks[ti];
+      for (var pi = 0; pi < track.phases.length; pi++) {
+        var phase = track.phases[pi];
+        phases.push({
+          id: 'phase-' + track.id + '-' + phase.id.replace(/[^a-zA-Z0-9]/g, '-'),
+          name: phase.name,
+          status: phase.status,
+          order: phases.length + 1,
+          trackId: track.id,
+          milestones: [{
+            id: 'ms-' + track.id + '-' + phase.id.replace(/[^a-zA-Z0-9]/g, '-'),
+            name: phase.name,
+            status: phase.status,
+            owner: phase.batch || '',
+            subtasks: (phase.tasks || []).map(function(t) {
+              return {
+                id: 'task-' + t.id.replace(/[^a-zA-Z0-9]/g, '-'),
+                name: t.title,
+                status: t.status,
+                type: t.actor || 'hand',
+              };
+            }),
+          }],
+        });
+      }
+    }
+  }
+
+  // Fallback: old phase-based filtering (for non-track elements)
+  for (var i = 0; i < timeline.elements.length; i++) {
+    var el = timeline.elements[i];
     if (el.kind === 'primary' && el.elementType === 'phase') {
       phases.push({
         id: el.id,
         name: el.name,
         status: el.status,
         order: el.order || phases.length + 1,
-        milestones: (el.children || []).map(ch => ({
-          id: ch.id,
-          name: ch.name,
-          status: ch.status,
-          owner: ch.source ? ch.source.file : '',
-          subtasks: (ch.children || []).map(st => ({
-            id: st.id,
-            name: st.name,
-            status: st.status,
-            type: st.elementType || 'hand',
-          })),
-        })),
+        milestones: [{
+          id: el.id,
+          name: el.name,
+          status: el.status,
+          owner: el.source ? el.source.file : '',
+          subtasks: (el.children || []).map(function(st) {
+            return {
+              id: st.id,
+              name: st.name,
+              status: st.status,
+              type: st.elementType || 'hand',
+            };
+          }),
+        }],
       });
     }
   }
+
   return {
     project: timeline.project,
     updated: timeline.updated,
     brief: timeline.brief,
-    phases,
+    tracks: timeline.tracks || [],
+    currentNode: timeline.currentNode || null,
+    phases: phases,
   };
 }
 
@@ -947,7 +837,7 @@ function buildTokenSummary(projectRoot, config) {
 function build(projectRoot) {
   const scanResult = scan(projectRoot);
   const { files } = scanResult;
-  const config = loadConfig(projectRoot);
+  const { config } = loadContract(projectRoot);
 
   const timeline = buildTimeline(files, projectRoot, config);
   const conventions = buildConventions(files, projectRoot);
@@ -1006,10 +896,11 @@ function build(projectRoot) {
 }
 
 module.exports = {
-  build, buildTimeline, buildPrimaryTree, buildSecondaryList,
+  build, buildTimeline, buildSecondaryList,
   classifyTimeGroup, buildFilterTypes, buildConventions,
   buildAgents, timelineToRoadmapCompat, timelineToJournalCompat,
   EVENT_TYPES, classifyEventPriority, buildTokenSummary,
+  buildTracks, tracksToElements,
 };
 
 if (require.main === module) {