@weldr/runr 0.4.0 → 0.7.2

package/dist/ux/safe-commands.js

@@ -0,0 +1,133 @@
+/**
+ * Safe command parsing and validation for auto-fix execution.
+ *
+ * This module ensures that only "boringly safe" commands are auto-executed
+ * by the continue command. It rejects shell pipelines, redirects, and
+ * anything that could be an injection surface.
+ */
+/**
+ * Dangerous patterns that indicate shell injection or unsafe behavior.
+ * If any of these are present, the command is rejected.
+ */
+const DANGEROUS_PATTERNS = [
+    '|', // pipe
+    '>', // redirect stdout
+    '<', // redirect stdin
+    '&&', // chain commands
+    ';', // command separator
+    '$(', // command substitution
+    '`', // backtick command substitution
+    '"', // double quotes (could hide injection)
+    "'", // single quotes (could hide injection)
+    '\n', // newlines (multiple commands)
+    '\\', // escape sequences
+];
+const SAFE_PATTERNS = [
+    // Node package managers - test/typecheck/lint only
+    { binary: 'npm', allowedSubcommands: ['test', 'run'], allowedScripts: ['test', 'typecheck', 'lint', 'type-check', 'types'] },
+    { binary: 'pnpm', allowedSubcommands: ['test', 'run'], allowedScripts: ['test', 'typecheck', 'lint', 'type-check', 'types'] },
+    { binary: 'yarn', allowedSubcommands: ['test', 'run'], allowedScripts: ['test', 'typecheck', 'lint', 'type-check', 'types'] },
+    // Direct TypeScript/linting tools
+    { binary: 'tsc' },
+    { binary: 'eslint' },
+    { binary: 'prettier', allowedSubcommands: ['--check'] },
+    // Python tools
+    { binary: 'pytest' },
+    { binary: 'python', allowedSubcommands: ['-m'], allowedScripts: ['pytest', 'mypy', 'ruff'] },
+    { binary: 'ruff' },
+    { binary: 'mypy' },
+    // Go tools
+    { binary: 'go', allowedSubcommands: ['test'] },
+    // Rust tools
+    { binary: 'cargo', allowedSubcommands: ['test', 'check', 'clippy'] },
+];
+/**
+ * Parse a raw command string into a canonical form.
+ * Returns null if the command contains dangerous patterns or is unparseable.
+ */
+export function canonicalizeCommand(raw) {
+    // Trim whitespace
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    // Check for dangerous patterns
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (trimmed.includes(pattern)) {
+            return null;
+        }
+    }
+    // Split on whitespace (simple tokenization)
+    const parts = trimmed.split(/\s+/);
+    if (parts.length === 0 || !parts[0]) {
+        return null;
+    }
+    const binary = parts[0];
+    const args = parts.slice(1);
+    return {
+        binary,
+        args,
+        raw: trimmed,
+    };
+}
+/**
+ * Check if a canonical command is allowed for auto-fix execution.
+ */
+export function isAutoFixCommandAllowed(cmd) {
+    const pattern = SAFE_PATTERNS.find(p => p.binary === cmd.binary);
+    if (!pattern) {
+        return false;
+    }
+    // If no subcommand restrictions, binary alone is safe
+    if (!pattern.allowedSubcommands) {
+        return true;
+    }
+    // Check first arg against allowed subcommands
+    const firstArg = cmd.args[0];
+    if (!firstArg || !pattern.allowedSubcommands.includes(firstArg)) {
+        return false;
+    }
+    // Special handling for 'run' subcommand - check script name
+    if (firstArg === 'run' && pattern.allowedScripts) {
+        const scriptName = cmd.args[1];
+        if (!scriptName || !pattern.allowedScripts.includes(scriptName)) {
+            return false;
+        }
+    }
+    // Special handling for python -m
+    if (cmd.binary === 'python' && firstArg === '-m' && pattern.allowedScripts) {
+        const moduleName = cmd.args[1];
+        if (!moduleName || !pattern.allowedScripts.includes(moduleName)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Parse a raw command and check if it's allowed in one step.
+ * Returns the canonical command if allowed, null otherwise.
+ */
+export function parseAndValidateCommand(raw) {
+    const cmd = canonicalizeCommand(raw);
+    if (!cmd) {
+        return null;
+    }
+    if (!isAutoFixCommandAllowed(cmd)) {
+        return null;
+    }
+    return cmd;
+}
+/**
+ * Extract safe commands from a list of suggested commands.
+ * Filters out any commands that are not in the safe allowlist.
+ */
+export function filterSafeCommands(commands) {
+    const result = [];
+    for (const raw of commands) {
+        const cmd = parseAndValidateCommand(raw);
+        if (cmd) {
+            result.push(cmd);
+        }
+    }
+    return result;
+}

package/dist/ux/state.js

@@ -0,0 +1,193 @@
+/**
+ * Repo state resolution for the UX layer.
+ *
+ * This module gathers signals from the filesystem to determine the current
+ * state of the repository: what's running, what's stopped, what orchestration
+ * is in progress, etc.
+ *
+ * All functions here do I/O. The brain module is pure and consumes this data.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunsRoot } from '../store/runs-root.js';
+import { findLatestRunId, listRecentRunIds } from '../store/run-utils.js';
+import { getCurrentMode } from '../commands/mode.js';
+import { findLatestOrchestrationId, loadOrchestratorState } from '../orchestrator/state-machine.js';
+import { git } from '../repo/git.js';
+/**
+ * Read minimal run info from state.json.
+ * Returns null if file doesn't exist or is unparseable.
+ */
+function readRunInfo(runDir, runId) {
+    const statePath = path.join(runDir, 'state.json');
+    if (!fs.existsSync(statePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(statePath, 'utf-8');
+        const state = JSON.parse(content);
+        return {
+            runId,
+            phase: state.phase ?? 'unknown',
+            stopReason: state.stop_reason ?? null,
+            taskPath: null, // Could read from config.snapshot.json if needed
+            startedAt: state.started_at ?? null,
+            updatedAt: state.updated_at ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read task path from config snapshot.
+ */
+function readTaskPath(runDir) {
+    const snapshotPath = path.join(runDir, 'config.snapshot.json');
+    if (!fs.existsSync(snapshotPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(snapshotPath, 'utf-8');
+        const snapshot = JSON.parse(content);
+        return snapshot.task_path ?? snapshot.taskPath ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find the most recent stopped run.
+ * Scans runs newest→oldest, returns first with phase=STOPPED.
+ */
+export function findLatestStoppedRun(repoPath) {
+    const runsRoot = getRunsRoot(repoPath);
+    const runIds = listRecentRunIds(repoPath, 20); // Check last 20 runs
+    for (const runId of runIds) {
+        const runDir = path.join(runsRoot, runId);
+        const info = readRunInfo(runDir, runId);
+        if (info && info.phase === 'STOPPED' && info.stopReason) {
+            // Check for stop.json
+            const stopJsonPath = path.join(runDir, 'handoffs', 'stop.json');
+            const diagnosticsPath = path.join(runDir, 'stop_diagnostics.json');
+            return {
+                ...info,
+                stopReason: info.stopReason,
+                taskPath: readTaskPath(runDir),
+                stopJsonPath: fs.existsSync(stopJsonPath) ? stopJsonPath : null,
+                diagnosticsPath: fs.existsSync(diagnosticsPath) ? diagnosticsPath : null,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Find any currently running run.
+ * A run is "running" if phase is not STOPPED.
+ */
+export function findActiveRun(repoPath) {
+    const runsRoot = getRunsRoot(repoPath);
+    const runIds = listRecentRunIds(repoPath, 10); // Check last 10 runs
+    for (const runId of runIds) {
+        const runDir = path.join(runsRoot, runId);
+        const info = readRunInfo(runDir, runId);
+        if (info && info.phase !== 'STOPPED') {
+            return {
+                ...info,
+                taskPath: readTaskPath(runDir),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Get orchestration cursor if one exists and is not complete.
+ */
+export function getOrchestrationCursor(repoPath) {
+    const orchId = findLatestOrchestrationId(repoPath);
+    if (!orchId) {
+        return null;
+    }
+    const state = loadOrchestratorState(orchId, repoPath);
+    if (!state) {
+        return null;
+    }
+    // Only return cursor if orchestration is still running or has stopped tasks
+    if (state.status === 'complete') {
+        return null;
+    }
+    const complete = state.tracks.filter(t => t.status === 'complete').length;
+    const stopped = state.tracks.filter(t => t.status === 'stopped' || t.status === 'failed').length;
+    return {
+        orchestratorId: orchId,
+        status: state.status,
+        tracksTotal: state.tracks.length,
+        tracksComplete: complete,
+        tracksStopped: stopped,
+        configPath: null, // Could be read from state if stored
+    };
+}
+/**
+ * Check if working tree is clean.
+ */
+export async function getTreeStatus(repoPath) {
+    try {
+        const result = await git(['status', '--porcelain'], repoPath);
+        const lines = result.stdout.trim().split('\n').filter(l => l.trim());
+        return lines.length === 0 ? 'clean' : 'dirty';
+    }
+    catch {
+        // If git fails, assume clean (conservative)
+        return 'clean';
+    }
+}
+/**
+ * Resolve complete repo state.
+ * This is the main entry point for the UX layer.
+ */
+export async function resolveRepoState(repoPath = process.cwd()) {
+    // Find active run first (takes priority)
+    const activeRun = findActiveRun(repoPath);
+    // Find latest run (any state)
+    const latestRunId = findLatestRunId(repoPath);
+    let latestRun = null;
+    if (latestRunId) {
+        const runDir = path.join(getRunsRoot(repoPath), latestRunId);
+        latestRun = readRunInfo(runDir, latestRunId);
+        if (latestRun) {
+            latestRun.taskPath = readTaskPath(runDir);
+        }
+    }
+    // Find latest stopped run (for continue)
+    const latestStopped = findLatestStoppedRun(repoPath);
+    // Get orchestration cursor
+    const orchestration = getOrchestrationCursor(repoPath);
+    // Get tree status
+    const treeStatus = await getTreeStatus(repoPath);
+    // Get workflow mode
+    const mode = getCurrentMode(repoPath);
+    return {
+        activeRun,
+        latestRun,
+        latestStopped,
+        orchestration,
+        treeStatus,
+        mode,
+        repoPath,
+    };
+}
+/**
+ * Derive display status from repo state.
+ */
+export function deriveDisplayStatus(state) {
+    if (state.activeRun) {
+        return 'running';
+    }
+    if (state.latestStopped) {
+        return 'stopped';
+    }
+    if (state.orchestration && state.orchestration.status !== 'complete') {
+        return 'orch_ready';
+    }
+    return 'clean';
+}

package/dist/ux/telemetry.js

@@ -0,0 +1,110 @@
+/**
+ * UX Telemetry - Breadcrumb tracking for debugging UX flows.
+ *
+ * Writes events to:
+ * - Run's timeline.jsonl if a run is in-scope
+ * - .runr/ux-breadcrumbs.jsonl otherwise
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunsRoot } from '../store/runs-root.js';
+/**
+ * Write a UX breadcrumb event.
+ *
+ * If runId is provided, writes to the run's timeline.
+ * Otherwise writes to a general breadcrumb file.
+ */
+export function writeBreadcrumb(repoPath, event) {
+    const fullEvent = {
+        ...event,
+        timestamp: new Date().toISOString(),
+    };
+    try {
+        if (event.runId) {
+            // Write to run's timeline
+            const runsRoot = getRunsRoot(repoPath);
+            const timelinePath = path.join(runsRoot, event.runId, 'timeline.jsonl');
+            if (fs.existsSync(path.dirname(timelinePath))) {
+                fs.appendFileSync(timelinePath, JSON.stringify(fullEvent) + '\n');
+                return;
+            }
+        }
+        // Fallback: write to general breadcrumb file
+        const breadcrumbPath = path.join(getRunsRoot(repoPath), 'ux-breadcrumbs.jsonl');
+        fs.appendFileSync(breadcrumbPath, JSON.stringify(fullEvent) + '\n');
+    }
+    catch {
+        // Silent fail - telemetry should never break the workflow
+    }
+}
+/**
+ * Record front door display.
+ */
+export function recordFrontDoor(repoPath, runId) {
+    writeBreadcrumb(repoPath, {
+        type: 'front_door_shown',
+        runId,
+    });
+}
+/**
+ * Record continue command attempt.
+ * Includes analysis fields for debugging "why did continue not run?" scenarios.
+ */
+export function recordContinueAttempt(repoPath, runId, strategy, analysis) {
+    writeBreadcrumb(repoPath, {
+        type: 'continue_attempted',
+        runId,
+        payload: {
+            strategyType: strategy.type,
+            ...(strategy.type === 'auto_fix' && { commandCount: strategy.commands.length }),
+            ...(strategy.type === 'manual' && { blockedReason: strategy.blockedReason }),
+            ...(strategy.type === 'continue_orch' && { orchestratorId: strategy.orchestratorId }),
+            // Include analysis fields for debugging
+            ...(analysis && {
+                autoFixAvailable: analysis.autoFixAvailable,
+                autoFixPermitted: analysis.autoFixPermitted,
+                treeDirty: analysis.treeDirty,
+                mode: analysis.mode,
+                blockReason: analysis.blockReason,
+            }),
+        },
+    });
+}
+/**
+ * Record auto-fix step execution.
+ */
+export function recordAutoFixStep(repoPath, runId, stepIndex, command, exitCode) {
+    writeBreadcrumb(repoPath, {
+        type: 'continue_auto_fix_step',
+        runId,
+        payload: {
+            stepIndex,
+            command,
+            exitCode,
+            success: exitCode === 0,
+        },
+    });
+}
+/**
+ * Record continue command failure.
+ */
+export function recordContinueFailed(repoPath, runId, reason, stepIndex) {
+    writeBreadcrumb(repoPath, {
+        type: 'continue_failed',
+        runId,
+        payload: {
+            reason,
+            ...(stepIndex !== undefined && { failedAtStep: stepIndex }),
+        },
+    });
+}
+/**
+ * Record continue command success.
+ */
+export function recordContinueSuccess(repoPath, runId, strategyType) {
+    writeBreadcrumb(repoPath, {
+        type: 'continue_success',
+        runId,
+        payload: { strategyType },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weldr/runr",
-  "version": "0.4.0",
+  "version": "0.7.2",
   "description": "Phase-gated orchestration for agent tasks",
   "type": "module",
   "bin": {
@@ -11,6 +11,8 @@
     "dist/",
     "!dist/**/__tests__/",
     "!dist/**/*.test.js",
+    "packs/",
+    "!packs/_schema/",
     "templates/prompts/",
     "README.md",
     "LICENSE",

package/packs/pr/pack.json

@@ -0,0 +1,50 @@
+{
+  "pack_version": 1,
+  "name": "pr",
+  "display_name": "Pull Request Workflow (feature → main via PR)",
+  "description": "Feature branch workflow with verified checkpoints, reviewable proof packets, and optional PR integration.",
+  "defaults": {
+    "profile": "pr",
+    "integration_branch": "main",
+    "release_branch": "main",
+    "submit_strategy": "cherry-pick",
+    "require_clean_tree": true,
+    "require_verification": true,
+    "protected_branches": ["main"]
+  },
+  "templates": {
+    "AGENTS.md": "templates/AGENTS.md.tmpl",
+    "CLAUDE.md": "templates/CLAUDE.md.tmpl",
+    "bundle.md": "templates/bundle.md.tmpl"
+  },
+  "init_actions": [
+    {
+      "type": "ensure_gitignore_entry",
+      "path": ".gitignore",
+      "line": ".runr/runs/"
+    },
+    {
+      "type": "ensure_gitignore_entry",
+      "path": ".gitignore",
+      "line": ".runr-worktrees/"
+    },
+    {
+      "type": "ensure_gitignore_entry",
+      "path": ".gitignore",
+      "line": ".runr/orchestrations/"
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": "AGENTS.md",
+      "template": "AGENTS.md",
+      "mode": "0644"
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": "CLAUDE.md",
+      "template": "CLAUDE.md",
+      "mode": "0644",
+      "when": { "flag": "with_claude" }
+    }
+  ]
+}

package/packs/pr/templates/AGENTS.md.tmpl

@@ -0,0 +1,120 @@
+# Agent Guidelines
+
+This repo uses **Runr** for reliable agent-driven development with PR workflow.
+
+## Workflow: Feature Branches + Pull Requests
+
+### How it works
+
+1. **Create feature branch** before starting work
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Run verified task** with Runr
+   ```bash
+   runr run --task task.md
+   ```
+
+3. **Runr creates checkpoints** as it progresses
+   - Each checkpoint is a git commit with full audit trail
+   - Only verified checkpoints are marked as "good"
+
+4. **Generate proof packet** when verified
+   ```bash
+   runr bundle <run_id>
+   ```
+   This creates a reviewable evidence packet showing:
+   - What changed (diff)
+   - Why it changed (task + plan)
+   - How it was verified (test results, checks)
+
+5. **Create PR** with proof packet
+   ```bash
+   # Push your feature branch
+   git push -u origin feature/your-feature-name
+
+   # Create PR (manual or via gh cli)
+   gh pr create --title "Feature: X" --body-file .runr/runs/<run_id>/bundle.md
+   ```
+
+6. **Review proof packet** instead of reading all code
+   - Reviewer sees: task → plan → implementation → verification
+   - Focus on "did it solve the right problem correctly?"
+
+7. **Merge when approved**
+   - PR merges feature branch to main
+   - Clean, verified commits only
+
+### Why this workflow?
+
+**Social artifacts:** PRs provide:
+- Review ritual (even for solo developers)
+- Discussion thread attached to change
+- Historical context ("why did we do this?")
+
+**Proof packets:** Bundle provides:
+- Complete audit trail in one document
+- Verification evidence upfront
+- Faster review (don't need to reconstruct context)
+
+**Branch isolation:** Feature branches keep:
+- Experimental work separate from main
+- Multiple tasks in parallel
+- Easy to abandon failed experiments
+
+## Key Commands
+
+```bash
+# Start new task on feature branch
+git checkout -b feature/add-x
+runr run --task task.md
+
+# Generate reviewable proof packet
+runr bundle <run_id>
+
+# Push + create PR with proof packet
+git push -u origin feature/add-x
+gh pr create --title "Add X" --body-file .runr/runs/<run_id>/bundle.md
+
+# Resume if interrupted
+runr run --resume
+```
+
+## Configuration
+
+See `runr.config.json`:
+- `integration_branch`: `main` (where PRs merge to)
+- `release_branch`: `main` (same as integration for PR workflow)
+- `require_verification`: `true` (only verified checkpoints are "good")
+- `protected_branches`: `["main"]` (prevent accidental direct pushes)
+
+## Directory Structure
+
+```
+.runr/
+├── runs/
+│   └── <run_id>/
+│       ├── bundle.md          # Proof packet for PR body
+│       ├── final_patch.diff   # Complete change
+│       └── timeline.jsonl     # Full audit trail
+└── checkpoints/
+    └── <sha>.json             # Checkpoint metadata
+```
+
+## Tips
+
+1. **One feature per branch** - Keep PRs focused and reviewable
+2. **Use bundle as PR description** - Reviewers get full context upfront
+3. **Verify before pushing** - Only push verified checkpoints
+4. **Small, frequent PRs** - Easier to review than giant changes
+5. **Archive proof packets** - `.runr/runs/` is your audit trail
+
+## Future: PR Integration (v2)
+
+Later versions may add:
+- `runr submit --pr` to auto-create PR with proof packet
+- PR status updates when verification completes
+- Auto-merge when verified + approved
+
+For now: manual PR creation with bundle.md as description works great.