figure-viewer 1.0.0

package/.opencode/commands/figures.md

@@ -0,0 +1,17 @@
+---
+description: Open figure viewer for the current project
+agent: build
+---
+
+Run the figure viewer to check generated figures:
+
+!`figure-viewer --watch`
+
+This will:
+- Auto-discover the figures directory (outputs/figures/, figures/, or plots/)
+- Open a browser split below in cmux
+- Watch for changes in the background
+
+To stop the watcher when done:
+
+!`figure-viewer --kill`

package/README.md

@@ -0,0 +1,99 @@
+# Figure Viewer
+
+CLI tool for viewing and navigating scientific figures in a browser pane.
+
+**Note:** This project is not affiliated with or endorsed by OpenCode or cmux. It simply integrates with their tools.
+
+## Features
+
+- Auto-discovers figures directories (`outputs/figures`, `figures`, `plots`, etc.)
+- Interactive HTML viewer with grid layout
+- Freshness indicators (Active/Recent/Older)
+- Lightbox for full-size image viewing
+- File watching with auto-refresh
+- cmux browser integration (opens in split below)
+- Configurable via `.figure-viewer.json`
+- Multiple independent sessions support
+
+## Installation
+
+```bash
+npm install -g figure-viewer
+```
+
+Or link locally:
+```bash
+cd figure-viewer
+npm link
+```
+
+## Usage
+
+```bash
+# Basic - auto-discover figures directory
+figure-viewer --watch
+
+# With options
+figure-viewer --watch --refresh 60 --timeout 120
+
+# Kill watcher when done
+figure-viewer --kill
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --path <path>` | Explicit path to figures directory | auto-discover |
+| `-o, --output <path>` | Output HTML file path | `figure-viewer.html` |
+| `-w, --watch` | Watch for file changes | false |
+| `--no-open` | Don't open browser | false |
+| `-r, --refresh <seconds>` | Auto-refresh interval | 30 |
+| `-t, --timeout <minutes>` | Kill after inactivity | 60 |
+| `--kill` | Kill background watcher | - |
+| `--clear-history` | Clear figure history | - |
+
+## Configuration
+
+Create a `.figure-viewer.json` in your project or home directory:
+
+```json
+{
+  "figuresDirs": [
+    "outputs/figures",
+    "figures",
+    "plots",
+    "output/figures",
+    "output/plots"
+  ],
+  "refreshInterval": 30000,
+  "watcherTimeout": 3600000,
+  "openOnStartup": true
+}
+```
+
+## OpenCode Integration
+
+Add `/figures` command to OpenCode:
+
+```bash
+# Link the command
+ln -s /path/to/figure-viewer/.opencode/command/figures.md ~/.config/opencode/command/figures.md
+```
+
+Then use in OpenCode:
+```
+/figures
+```
+
+## How It Works
+
+1. Auto-discovers figures directory by walking up from current directory
+2. Generates interactive HTML with figure grid
+3. Opens in cmux browser split (or falls back to system browser)
+4. Watches for file changes in background
+5. Auto-kills after inactivity timeout (configurable)
+
+## License
+
+MIT

package/figure-viewer-spec.md

@@ -0,0 +1,293 @@
+# Figure Viewer — Specification
+
+## Overview
+
+A CLI tool for viewing and navigating scientific figures generated during agentic data analysis workflows. Designed for macOS + cmux + OpenCode. Renders figures in a browser pane within cmux for perfect image quality.
+
+## Problem
+
+When AI coding agents (OpenCode) generate figures during data analysis:
+- Opening figures requires context-switching to Finder/Preview
+- No good TUI-native solution for image preview on macOS
+- Hard to track which figures are new vs. iterations
+- Want to view figures inside cmux without leaving the terminal
+
+## Solution
+
+- CLI tool: `figure-viewer`
+- Generates interactive HTML from figures directory
+- HTML opened in cmux browser split
+- Auto-discovery of figures folder from working directory
+- Freshness tracking for iteration awareness
+
+---
+
+## CLI Interface
+
+### Commands
+
+```bash
+# Basic usage — auto-discover figures from cwd
+figure-viewer
+
+# Explicit path
+figure-viewer ./outputs/figures
+figure-viewer /path/to/project/analysis/outputs/figures
+
+# Watch mode (default on)
+figure-viewer --watch
+figure-viewer --watch ./figures
+
+# Disable auto-open in browser
+figure-viewer --no-open
+
+# Specify output HTML path
+figure-viewer --output viewer.html
+
+# Help
+figure-viewer --help
+```
+
+### Auto-Discovery Logic
+
+1. If path provided, use it
+2. Else, start at `pwd`
+3. Walk up directories looking for:
+   - `outputs/figures/`
+   - `figures/`
+   - `plots/`
+   - `output/figures/`
+4. If not found, error with suggestion to pass explicit path
+
+---
+
+## HTML Viewer
+
+### Layout
+
+```
+┌─────────────────────────────────────────────────────┐
+│  🔄 Figure Viewer                    [Refresh]    │
+├─────────────────────────────────────────────────────┤
+│  Filter: [________________]  Sort: [Newest ▼]       │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐          │
+│  │ img  │  │ img  │  │ img  │  │ img  │          │
+│  │  1   │  │  2   │  │  3   │  │  4   │          │
+│  │ 🔴   │  │ ⚪   │  │ ⚪   │  │ 🟡   │          │
+│  └──────┘  └──────┘  └──────┘  └──────┘          │
+│                                                     │
+│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐          │
+│  │ img  │  │ img  │  │ img  │  │ img  │          │
+│  │  5   │  │  6   │  │  7   │  │  8   │          │
+│  │ ⚪   │  │ ⚪   │  │ 🔴   │  │ ⚪   │          │
+│  └──────┘  └──────┘  └──────┘  └──────┘          │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+### Grid
+
+- Responsive grid: auto-fit, min 200px per image
+- Each card shows:
+  - Thumbnail (aspect-ratio preserved)
+  - Filename (truncated if long)
+  - Timestamp (relative: "2 min ago", "1 hour ago")
+  - Freshness indicator (color border)
+
+### Freshness Indicators
+
+| Status | Color | Time Window |
+|--------|-------|-------------|
+| 🔴 Active | Red border | < 5 minutes |
+| 🟡 Recent | Yellow border | 5 min – 1 hour |
+| ⚪ Older | Gray border | > 1 hour |
+
+### Lightbox
+
+On click:
+- Full-size image in modal overlay
+- Dark background (rgba(0,0,0,0.9))
+- Close: ESC key or click outside
+- Navigation: ← → arrows or keyboard
+- Shows metadata: filename, dimensions, file size, full path
+
+### Auto-Refresh
+
+- Meta refresh every 5 seconds: `<meta http-equiv="refresh" content="5">`
+- Or JavaScript polling (less intrusive)
+- Manual refresh button always available
+
+---
+
+## Freshness Tracking
+
+### Storage
+
+`~/.figure-viewer/history.json`:
+
+```json
+{
+  "/path/to/project/outputs/figures": {
+    "figure_1.png": {
+      "mtime": 1709324400000,
+      "version": 1
+    },
+    "figure_1.png": {
+      "mtime": 1709324500000,
+      "version": 2
+    }
+  }
+}
+```
+
+### Version Detection
+
+If same filename appears with newer mtime:
+- Increment version counter
+- Track version history
+- Display "v1", "v2", etc. on card
+
+---
+
+## cmux Integration
+
+### Opening the Viewer
+
+```bash
+# Generate HTML
+figure-viewer --output /tmp/figure-viewer.html
+
+# Open in cmux browser (verify exact command)
+cmux browser open file:///tmp/figure-viewer.html
+```
+
+### Watch + Open
+
+```bash
+# Watch and auto-open on first run
+figure-viewer --watch --open
+```
+
+On watch detect new/modified figure:
+1. Regenerate HTML
+2. Refresh browser (cmux command TBD or manual)
+
+### Fallback
+
+If cmux not available or browser split fails:
+- Open in default browser: `open file:///path/to/viewer.html`
+- Print instruction to user
+
+---
+
+## OpenCode Integration
+
+### Custom Command
+
+Create `.opencode/commands/figures.md`:
+
+```yaml
+---
+description: Open figure viewer
+agent: build
+---
+
+Run the figure viewer to check generated figures:
+
+!`figure-viewer --open`
+```
+
+### Usage
+
+In OpenCode:
+```
+/figures
+```
+
+Or in conversation:
+```
+"Can you run /figures to check the plots we generated?"
+```
+
+---
+
+## File Structure
+
+```
+figure-viewer/
+├── figure-viewer.js      # Main CLI entry point
+├── lib/
+│   ├── discover.js       # Find figures directory
+│   ├── html.js           # Generate HTML
+│   ├── history.js        # Track freshness/versions
+│   └── watcher.js        # File system watch (fswatch)
+├── templates/
+│   └── viewer.html       # HTML template (inline in js or separate)
+├── package.json
+└── README.md
+```
+
+---
+
+## Dependencies
+
+- Node.js (or could be Go/Bash)
+- `chokidar` or `fswatch` for file watching
+- Optional: `open` CLI (macOS) for fallback browser open
+
+---
+
+## Edge Cases
+
+1. **No figures directory found**
+   - Error message: "No figures directory found. Pass explicit path or create one of: outputs/figures/, figures/, plots/"
+
+2. **Empty figures directory**
+   - Show message: "No figures yet. Run your analysis to generate figures."
+
+3. **Very large images**
+   - Generate thumbnails for grid? Or lazy load
+   - Full size in lightbox
+
+4. **Non-image files in folder**
+   - Filter to: .png, .jpg, .jpeg, .pdf, .svg
+   - Ignore everything else
+
+5. **Path with spaces/special chars**
+   - Proper escaping in HTML file:// URLs
+
+6. **Multiple projects**
+   - History stored per directory path
+   - Can clear history: `figure-viewer --clear-history`
+
+7. **Watch mode permissions**
+   - Handle ENOENT if directory deleted while watching
+
+---
+
+## Future Enhancements
+
+- [ ] Version comparison: side-by-side v1 vs v2
+- [ ] Annotations: add notes to figures
+- [ ] Export: download all figures as zip
+- [ ] Zoom: pinch-zoom in lightbox
+- [ ] Slideshow: auto-advance mode
+- [ ] AI captioning: generate descriptions with vision model
+- [ ] Share: copy image URL or embed
+
+---
+
+## Acceptance Criteria
+
+1. ✅ `figure-viewer` runs from CLI with no arguments and auto-discovers figures
+2. ✅ Generated HTML displays grid of images with thumbnails
+3. ✅ Freshness indicators show correct colors based on mtime
+4. ✅ Click on image opens lightbox with full-size view
+5. ✅ Lightbox supports keyboard navigation (ESC to close, arrows to navigate)
+6. ✅ Watch mode detects new files and regenerates HTML
+7. ✅ Opens in cmux browser split (or fallback to system browser)
+8. ✅ Custom command `/figures` works in OpenCode
+9. ✅ Works with nested directory structures (project/analysis/outputs/figures)
+10. ✅ Handles empty directory gracefully with helpful message

package/figure-viewer.config.json

@@ -0,0 +1,12 @@
+{
+  "figuresDirs": [
+    "outputs/figures",
+    "figures",
+    "plots",
+    "output/figures",
+    "output/plots"
+  ],
+  "refreshInterval": 30000,
+  "watcherTimeout": 3600000,
+  "openOnStartup": true
+}

package/figure-viewer.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const fs = require('fs');
+const path = require('path');
+
+const { discoverFiguresDirectory, getErrorMessage } = require('./lib/discover');
+const { generateHtml, getImages } = require('./lib/html');
+const { updateHistory, getHistoryForDir, clearHistory: clearHistoryFn } = require('./lib/history');
+const { createWatcher, closeWatcher } = require('./lib/watcher');
+const { getConfig } = require('./lib/config');
+
+const program = new Command();
+
+const PID_FILE = '.figure-viewer.pid';
+
+program
+  .name('figure-viewer')
+  .description('CLI tool for viewing and navigating scientific figures in a browser pane')
+  .version('1.0.0')
+  .option('-p, --path <path>', 'Explicit path to figures directory')
+  .option('-o, --output <path>', 'Output HTML file path', 'figure-viewer.html')
+  .option('-w, --watch', 'Watch for file changes and auto-refresh', false)
+  .option('--no-open', 'Do not open browser automatically')
+  .option('-r, --refresh <seconds>', 'Auto-refresh interval in seconds (default: 30)', parseInt)
+  .option('-t, --timeout <minutes>', 'Kill watcher after N minutes of inactivity (default: 60)', parseInt)
+  .option('--clear-history', 'Clear figure history')
+  .option('--kill', 'Kill the background watcher process');
+
+program.parse(process.argv);
+
+const options = program.opts();
+
+function generateAndSave(figuresDir, outputPath) {
+  const config = getConfig();
+  // CLI options override config
+  if (options.refresh) {
+    config.refreshInterval = options.refresh * 1000;
+  }
+  if (options.timeout) {
+    config.watcherTimeout = options.timeout * 60 * 1000;
+  }
+  const images = getImages(figuresDir);
+  const history = updateHistory(figuresDir, images);
+  const html = generateHtml(figuresDir, { history, config });
+  
+  fs.writeFileSync(outputPath, html);
+  console.log(`Generated: ${outputPath} (${images.length} figures)`);
+  
+  return outputPath;
+}
+
+function openInBrowser(filePath) {
+  // Try cmux first, fallback to system browser
+  const fileUrl = 'file://' + filePath;
+  
+  // Check if cmux socket exists (cmux sets CMUX_SOCKET_PATH or we can check default)
+  const cmuxSocket = process.env.CMUX_SOCKET_PATH || '/tmp/cmux.sock';
+  const hasCmux = fs.existsSync(cmuxSocket) || process.env.CMUX_WORKSPACE_ID;
+  
+  if (hasCmux) {
+    console.log('Detected cmux session - opening in cmux browser...');
+    try {
+      const { execSync } = require('child_process');
+      // Try cmux browser open command
+      // Use new-pane with direction for cmux
+      execSync(`cmux new-pane --type browser --direction down --url "${fileUrl}"`, { stdio: 'inherit' });
+      console.log('Opened in cmux browser');
+      return;
+    } catch (e) {
+      console.log('cmux command failed, falling back to system browser:', e.message);
+    }
+  }
+  
+  // Fallback: use system open command
+  const { exec } = require('child_process');
+  exec(`open "${fileUrl}"`, (err) => {
+    if (err) {
+      console.error('Failed to open browser:', err.message);
+    } else {
+      console.log('Opened in default browser');
+    }
+  });
+}
+
+async function main() {
+  // Handle kill option
+  if (options.kill) {
+    const pidPath = path.join(process.cwd(), PID_FILE);
+    if (fs.existsSync(pidPath)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(pidPath, 'utf8'));
+        const pid = data.pid;
+        process.kill(pid, 'SIGTERM');
+        console.log(`Killed watcher process (PID: ${pid})`);
+      } catch (e) {
+        console.log('Watcher process already stopped or invalid PID file.');
+      }
+      // Clean up PID file
+      try { fs.unlinkSync(pidPath); } catch {}
+    } else {
+      console.log('No watcher process found in current directory.');
+    }
+    return;
+  }
+
+  // Handle clear history
+  if (options.clearHistory) {
+    clearHistoryFn();
+    console.log('History cleared.');
+    return;
+  }
+
+  // Discover figures directory
+  let figuresDir;
+  try {
+    figuresDir = discoverFiguresDirectory(options.path);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  if (!figuresDir) {
+    console.error(getErrorMessage(FIGURE_DIRS));
+    process.exit(1);
+  }
+
+  console.log(`Figures directory: ${figuresDir}`);
+
+  // Generate HTML
+  const outputPath = path.resolve(options.output);
+  generateAndSave(figuresDir, outputPath);
+
+  // Check if watcher already running
+  const pidPath = path.join(process.cwd(), PID_FILE);
+  const watcherAlreadyRunning = fs.existsSync(pidPath);
+
+  // Watch mode - run as background process
+  if (options.watch) {
+    if (watcherAlreadyRunning) {
+      console.log('Watcher already running in this directory.');
+    } else {
+      const { spawn } = require('child_process');
+      
+      // Get config for refresh and timeout
+      const config = getConfig();
+      const refreshMs = options.refresh ? options.refresh * 1000 : config.refreshInterval;
+      const timeoutMs = options.timeout ? options.timeout * 60 * 1000 : config.watcherTimeout;
+      
+      // Pass the output directory as first arg (projectRoot)
+      const child = spawn(
+        process.execPath, 
+        [
+          path.join(__dirname, 'lib/watcher-daemon.js'), 
+          path.dirname(outputPath), 
+          figuresDir, 
+          outputPath,
+          refreshMs.toString(),
+          timeoutMs.toString()
+        ], 
+        {
+          cwd: __dirname,
+          detached: true,
+          stdio: 'ignore'
+        }
+      );
+      
+      child.unref();
+      
+      console.log('Watching for changes in background...');
+      console.log(`Auto-refresh every ${refreshMs/1000}s, timeout after ${Math.round(timeoutMs/60000)}min`);
+    }
+  }
+
+  // Open in browser (only if not already watching and not explicitly disabled)
+  if (options.open !== false && !watcherAlreadyRunning) {
+    openInBrowser(outputPath);
+  } else if (watcherAlreadyRunning) {
+    console.log('Browser already open. Use --no-open to skip browser entirely.');
+  } else if (!options.watch) {
+    // Only show URL for non-watch mode
+    console.log(`\nOpen this URL in your browser:\nfile://${outputPath}`);
+  }
+}
+
+main().catch(console.error);

package/lib/config.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CONFIG = {
+  figuresDirs: [
+    'outputs/figures',
+    'figures',
+    'plots',
+    'output/figures',
+    'output/plots'
+  ],
+  refreshInterval: 30000,
+  watcherTimeout: 3600000,
+  openOnStartup: true
+};
+
+function getConfig(dir = process.cwd()) {
+  // Check for config in current directory first
+  const localConfig = path.join(dir, '.figure-viewer.json');
+  if (fs.existsSync(localConfig)) {
+    try {
+      return { ...DEFAULT_CONFIG, ...JSON.parse(fs.readFileSync(localConfig, 'utf8')) };
+    } catch (e) {
+      console.warn('Invalid config file, using defaults');
+    }
+  }
+  
+  // Check in home directory
+  const homeConfig = path.join(process.env.HOME || process.env.USERPROFILE, '.figure-viewer.json');
+  if (fs.existsSync(homeConfig)) {
+    try {
+      return { ...DEFAULT_CONFIG, ...JSON.parse(fs.readFileSync(homeConfig, 'utf8')) };
+    } catch (e) {
+      // ignore
+    }
+  }
+  
+  return DEFAULT_CONFIG;
+}
+
+module.exports = {
+  getConfig,
+  DEFAULT_CONFIG
+};

package/lib/discover.js

@@ -0,0 +1,54 @@
+const fs = require('fs');
+const path = require('path');
+const { getConfig, DEFAULT_CONFIG } = require('./config');
+
+function discoverFiguresDirectory(startPath, config = null) {
+  // If explicit path provided, validate it
+  if (startPath) {
+    const resolvedPath = path.resolve(startPath);
+    if (!fs.existsSync(resolvedPath)) {
+      throw new Error(`Directory not found: ${resolvedPath}`);
+    }
+    const stats = fs.statSync(resolvedPath);
+    if (!stats.isDirectory()) {
+      throw new Error(`Not a directory: ${resolvedPath}`);
+    }
+    return resolvedPath;
+  }
+
+  const cfg = config || getConfig();
+  const figureDirs = cfg.figuresDirs || DEFAULT_CONFIG.figuresDirs;
+
+  // Start at current working directory
+  let currentDir = process.cwd();
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    for (const figureDir of figureDirs) {
+      const candidatePath = path.join(currentDir, figureDir);
+      if (fs.existsSync(candidatePath) && fs.statSync(candidatePath).isDirectory()) {
+        return candidatePath;
+      }
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  // Check root level as well
+  for (const figureDir of figureDirs) {
+    const candidatePath = path.join(root, figureDir);
+    if (fs.existsSync(candidatePath) && fs.statSync(candidatePath).isDirectory()) {
+      return candidatePath;
+    }
+  }
+
+  return null;
+}
+
+function getErrorMessage(suggestedDirs) {
+  return `No figures directory found. Pass explicit path or create one of: ${suggestedDirs.join(', ')}`;
+}
+
+module.exports = {
+  discoverFiguresDirectory,
+  getErrorMessage
+};