@weldr/runr 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-01-03
+
+**Case Files** — Every run leaves a machine-readable journal.
+
+### Added
+
+- **Case Files**: Auto-generated `journal.md` + `journal.json` for every run
+  - Schema v1.0 with immutable facts (timestamps, milestones, verification attempts)
+  - Living data (append-only notes)
+  - Secret redaction in error excerpts
+  - Warnings array captures all extraction issues
+- **CLI Commands**:
+  - `runr journal [run_id]` — Generate and display journal (defaults to latest)
+  - `runr note <message> [--run-id]` — Add timestamped note (defaults to latest)
+  - `runr open [run_id]` — Open journal in $EDITOR (defaults to latest)
+- **Auto-generation**: Journals written on run completion (stop or finish)
+- **Non-interactive safety**: `runr open` fails cleanly in CI or when $EDITOR unset
+
+### Fixed
+
+- **Package bloat**: Excluded test files from npm package (81 → 69 files)
+- **Deprecation warnings**: Replaced deprecated `getRunsRoot()` with `getRunrPaths().runs_dir`
+
 ## [0.3.0] - 2026-01-01
 
 **Renamed to Runr.** New identity, same reliability-first mission.

package/README.md

@@ -163,6 +163,9 @@ Available: `nextjs`, `react`, `drizzle`, `prisma`, `vitest`, `jest`, `playwright
 | `runr status [id]` | Show run state |
 | `runr follow [id]` | Tail run progress |
 | `runr report <id>` | Generate run report (includes next_action) |
+| `runr journal [id]` | Generate and display case file |
+| `runr note <message>` | Add timestamped note to run |
+| `runr open [id]` | Open journal in $EDITOR |
 | `runr gc` | Clean up old runs |
 | `runr doctor` | Check environment |
 
@@ -177,6 +180,57 @@ runr scry <id>               # status
 runr banish                  # gc
 ```
 
+## Case Files
+
+Every run automatically generates a **journal.md** case file in `.runr/runs/<run_id>/journal.md` containing:
+
+- **Run metadata** (timestamps, duration, stop reason)
+- **Task details** (goal, requirements, success criteria)
+- **Milestone progress** (attempted, verified, checkpoints)
+- **Verification history** (test attempts, pass/fail counts)
+- **Code changes** (files changed, diff stats, top files)
+- **Error excerpts** (last failure with redacted secrets)
+- **Next action** (suggested command to continue)
+- **Notes** (timestamped annotations)
+
+### Commands
+
+```bash
+# Generate and display journal for latest run
+runr journal
+
+# Generate journal for specific run
+runr journal <run_id>
+
+# Force regeneration even if up to date
+runr journal <run_id> --force
+
+# Add a timestamped note to latest run
+runr note "Debugging OAuth token refresh issue"
+
+# Add note to specific run
+runr note "Fixed token refresh" --run-id <run_id>
+
+# Open journal in $EDITOR (defaults to latest run)
+runr open
+runr open <run_id>
+```
+
+**Note**: If `<run_id>` is omitted, all commands default to the most recent run in the repository.
+
+### Auto-Generation
+
+Journals are automatically generated when runs complete (stop or finish). You can also:
+- Manually regenerate with `runr journal <run_id> --force`
+- Add timestamped notes during or after runs with `runr note` (stored in `.runr/runs/<run_id>/notes.jsonl`)
+- Open in your editor with `runr open` (uses `$EDITOR` or `vim`)
+
+**Use case**: Share run context with collaborators, document debugging sessions, track experiment results.
+
+**Files generated:**
+- `journal.md` - Human-readable case file
+- `notes.jsonl` - Timestamped notes (one JSON object per line)
+
 ## Task Files
 
 Tasks are markdown files:

package/dist/cli.js

@@ -18,6 +18,7 @@ import { metricsCommand } from './commands/metrics.js';
 import { versionCommand } from './commands/version.js';
 import { initCommand } from './commands/init.js';
 import { watchCommand } from './commands/watch.js';
+import { journalCommand, noteCommand, openCommand } from './commands/journal.js';
 const program = new Command();
 // Check if invoked as deprecated 'agent' command
 const invokedAs = process.argv[1]?.split('/').pop() || 'runr';
@@ -517,4 +518,44 @@ program
         olderThan: Number.parseInt(options.olderThan, 10)
     });
 });
+// journal - Generate case file from run
+program
+    .command('journal')
+    .description('Generate and display journal.md for a run')
+    .argument('[runId]', 'Run ID (defaults to latest)')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--output <file>', 'Output file path (defaults to runs/<id>/journal.md)')
+    .option('--force', 'Force regeneration even if up to date', false)
+    .action(async (runId, options) => {
+    await journalCommand({
+        repo: options.repo,
+        runId,
+        output: options.output,
+        force: options.force
+    });
+});
+// note - Add timestamped note to run
+program
+    .command('note <message>')
+    .description('Add a timestamped note to a run')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--run-id <id>', 'Run ID (defaults to latest)')
+    .action(async (message, options) => {
+    await noteCommand(message, {
+        repo: options.repo,
+        runId: options.runId
+    });
+});
+// open - Open journal.md in editor
+program
+    .command('open')
+    .description('Open journal.md in $EDITOR')
+    .argument('[runId]', 'Run ID (defaults to latest)')
+    .option('--repo <path>', 'Target repo path', '.')
+    .action(async (runId, options) => {
+    await openCommand({
+        repo: options.repo,
+        runId
+    });
+});
 program.parseAsync();

package/dist/commands/journal.js

@@ -0,0 +1,167 @@
+/**
+ * Journal commands: journal, note, open
+ *
+ * Generate case files for agent runs with notes and markdown output.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { buildJournal } from '../journal/builder.js';
+import { renderJournal } from '../journal/renderer.js';
+import { getRunrPaths } from '../store/runs-root.js';
+/**
+ * Journal command: Generate and optionally display journal.md
+ *
+ * Usage:
+ *   runr journal [run_id] [--repo <path>] [--output <file>] [--force]
+ */
+export async function journalCommand(options) {
+    const repo = options.repo || process.cwd();
+    const runId = options.runId || findLatestRunId(repo);
+    if (!runId) {
+        console.error('ERROR: No runs found. Specify --run-id or create a run first.');
+        process.exit(1);
+    }
+    const runDir = path.join(getRunrPaths(repo).runs_dir, runId);
+    if (!fs.existsSync(runDir)) {
+        console.error(`ERROR: Run directory not found: ${runDir}`);
+        process.exit(1);
+    }
+    try {
+        // Build journal.json
+        const journal = await buildJournal(runId, repo);
+        // Render markdown
+        const markdown = renderJournal(journal);
+        // Determine output path
+        const outputPath = options.output || path.join(runDir, 'journal.md');
+        // Check if file exists and not forcing
+        if (fs.existsSync(outputPath) && !options.force) {
+            // Check if journal.json is newer than journal.md
+            const journalMtime = getMtime(path.join(runDir, 'journal.json'));
+            const markdownMtime = getMtime(outputPath);
+            if (journalMtime && markdownMtime && journalMtime <= markdownMtime) {
+                console.log(`✓ Journal is up to date: ${outputPath}`);
+                console.log(`\n${markdown}`);
+                return;
+            }
+        }
+        // Write markdown file
+        fs.writeFileSync(outputPath, markdown, 'utf-8');
+        console.log(`✓ Journal generated: ${outputPath}`);
+        console.log(`\n${markdown}`);
+    }
+    catch (err) {
+        console.error('ERROR:', err.message);
+        process.exit(1);
+    }
+}
+/**
+ * Note command: Append timestamped note to notes.jsonl
+ *
+ * Usage:
+ *   runr note <message> [--run-id <id>] [--repo <path>]
+ */
+export async function noteCommand(message, options) {
+    const repo = options.repo || process.cwd();
+    const runId = options.runId || findLatestRunId(repo);
+    if (!runId) {
+        console.error('ERROR: No runs found. Specify --run-id or create a run first.');
+        process.exit(1);
+    }
+    const runDir = path.join(getRunrPaths(repo).runs_dir, runId);
+    if (!fs.existsSync(runDir)) {
+        console.error(`ERROR: Run directory not found: ${runDir}`);
+        process.exit(1);
+    }
+    const notesPath = path.join(runDir, 'notes.jsonl');
+    // Append note
+    const note = {
+        timestamp: new Date().toISOString(),
+        message
+    };
+    try {
+        fs.appendFileSync(notesPath, JSON.stringify(note) + '\n', 'utf-8');
+        console.log(`✓ Note added to run ${runId}`);
+        console.log(`  "${message}"`);
+    }
+    catch (err) {
+        console.error('ERROR:', err.message);
+        process.exit(1);
+    }
+}
+/**
+ * Open command: Open journal.md in editor
+ *
+ * Usage:
+ *   runr open [run_id] [--repo <path>]
+ */
+export async function openCommand(options) {
+    const repo = options.repo || process.cwd();
+    const runId = options.runId || findLatestRunId(repo);
+    if (!runId) {
+        console.error('ERROR: No runs found. Specify --run-id or create a run first.');
+        process.exit(1);
+    }
+    const runDir = path.join(getRunrPaths(repo).runs_dir, runId);
+    const journalPath = path.join(runDir, 'journal.md');
+    if (!fs.existsSync(journalPath)) {
+        console.log(`Journal not found. Generating...`);
+        try {
+            const journal = await buildJournal(runId, repo);
+            const markdown = renderJournal(journal);
+            fs.writeFileSync(journalPath, markdown, 'utf-8');
+            console.log(`✓ Journal generated: ${journalPath}`);
+        }
+        catch (err) {
+            console.error('ERROR:', err.message);
+            process.exit(1);
+        }
+    }
+    // Open in editor (with non-interactive safety)
+    const editor = process.env.EDITOR;
+    // Check if running in non-interactive environment (CI, no TTY)
+    const isInteractive = process.stdout.isTTY && process.stdin.isTTY;
+    if (!isInteractive || !editor) {
+        // Non-interactive or no editor set: print path instead of hanging
+        console.log(`Journal: ${journalPath}`);
+        if (!editor) {
+            console.log('Tip: Set $EDITOR to open journals automatically');
+        }
+        return;
+    }
+    try {
+        execSync(`${editor} "${journalPath}"`, { stdio: 'inherit' });
+    }
+    catch (err) {
+        console.error(`ERROR: Failed to open editor: ${err.message}`);
+        process.exit(1);
+    }
+}
+/**
+ * Find the latest run ID in the runs directory
+ */
+function findLatestRunId(repo) {
+    const runsRoot = getRunrPaths(repo).runs_dir;
+    if (!fs.existsSync(runsRoot)) {
+        return null;
+    }
+    const entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+    const runDirs = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .filter((name) => /^\d{14}$/.test(name)) // Format: YYYYMMDDHHMMSS
+        .sort()
+        .reverse();
+    return runDirs[0] || null;
+}
+/**
+ * Get file modification time (returns null if file doesn't exist)
+ */
+function getMtime(filePath) {
+    try {
+        return fs.statSync(filePath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}