@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.4

package/tools/inbox_drain.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+r"""Drain UI inbox submissions, tracking which have been processed.
+
+Usage:
+    python inbox_drain.py pending         # List unprocessed inbox items
+    python inbox_drain.py mark <ISO-ts>   # Mark one timestamp as processed
+    python inbox_drain.py mark-all        # Mark all pending items as processed
+
+Purpose:
+    Makes inbox submissions (written by the aesop dashboard) survive sessions.
+    Maintains a processed-marker file that tracks which items have been actioned.
+    Enables /power and daemons to pick up queued work that arrived while no
+    session was running.
+
+Configuration:
+    - Reads aesop.config.json for inbox_path and inbox_seen_path (optional).
+    - Env vars override config: AESOP_INBOX_PATH, AESOP_INBOX_SEEN_PATH.
+    - Falls back to defaults: state/ui-inbox.md, state/.ui-inbox-seen.
+
+Format (ui-inbox.md):
+    - [ISO-TS] item text
+    - [ISO-TS] item text
+
+Subcommands:
+    pending:    Read inbox, compare against processed-marker, print unprocessed.
+                Exit 0. If none exist, print "NO PENDING" and exit 0.
+    mark <ts>:  Append ISO timestamp to seen-file. If already marked, noop.
+    mark-all:   Append ALL pending timestamps to seen-file in one write.
+
+Robustness:
+    - Missing inbox or seen files treated as empty (no crash).
+    - Timestamps are exact match (whitespace-preserved).
+    - Exit 0 always (never fails on missing files).
+
+Output:
+    pending: Each unprocessed item as "[TS] text" (one per line).
+    mark/mark-all: Prints "[i/total] marked" summary to stderr.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from datetime import datetime
+
+
+def load_config():
+    """Load aesop.config.json if present; return dict."""
+    try:
+        config_path = Path.cwd() / 'aesop.config.json'
+        if config_path.exists():
+            with open(config_path) as f:
+                return json.load(f)
+    except Exception:
+        pass
+    return {}
+
+
+def resolve_paths(config):
+    """Resolve paths with precedence: env var > config > default."""
+    aesop_root = Path.cwd()
+    state_root = Path(
+        os.environ.get(
+            'AESOP_STATE_ROOT',
+            config.get('state_root', str(aesop_root / 'state'))
+        )
+    ).expanduser()
+
+    # inbox_path: env AESOP_INBOX_PATH > config inbox_path > default state/ui-inbox.md
+    inbox_path = Path(
+        os.environ.get(
+            'AESOP_INBOX_PATH',
+            config.get('inbox_path', str(state_root / 'ui-inbox.md'))
+        )
+    ).expanduser()
+
+    # inbox_seen_path: env AESOP_INBOX_SEEN_PATH > config inbox_seen_path > default state/.ui-inbox-seen
+    inbox_seen_path = Path(
+        os.environ.get(
+            'AESOP_INBOX_SEEN_PATH',
+            config.get('inbox_seen_path', str(state_root / '.ui-inbox-seen'))
+        )
+    ).expanduser()
+
+    return inbox_path, inbox_seen_path
+
+
+config = load_config()
+INBOX_PATH, SEEN_PATH = resolve_paths(config)
+
+
+def read_inbox():
+    """Read inbox.md and return list of (timestamp, text) tuples.
+
+    Returns:
+        List of (ts, text) tuples; empty list if file missing/empty.
+    """
+    if not INBOX_PATH.exists():
+        return []
+
+    items = []
+    try:
+        # Try UTF-8 first, fall back to latin-1 for extended-ASCII files
+        try:
+            with open(INBOX_PATH, "r", encoding="utf-8") as f:
+                content = f.read()
+        except UnicodeDecodeError:
+            with open(INBOX_PATH, "r", encoding="latin-1") as f:
+                content = f.read()
+
+        for line in content.splitlines():
+            line = line.rstrip("\r\n")
+            if line.startswith("- [") and "]" in line:
+                # Parse "- [ISO-TS] text"
+                end_bracket = line.index("]")
+                ts = line[3:end_bracket]  # Extract ISO-TS from - [ISO-TS]
+                text = line[end_bracket + 2 :] if end_bracket + 2 < len(line) else ""
+                items.append((ts, text))
+    except Exception:
+        pass
+
+    return items
+
+
+def read_seen():
+    """Read seen-file and return set of marked timestamps.
+
+    Returns:
+        Set of already-processed ISO timestamps; empty set if file missing.
+    """
+    if not SEEN_PATH.exists():
+        return set()
+
+    seen = set()
+    try:
+        try:
+            with open(SEEN_PATH, "r", encoding="utf-8") as f:
+                content = f.read()
+        except UnicodeDecodeError:
+            with open(SEEN_PATH, "r", encoding="latin-1") as f:
+                content = f.read()
+
+        for line in content.splitlines():
+            ts = line.rstrip("\r\n")
+            if ts:
+                seen.add(ts)
+    except Exception:
+        pass
+
+    return seen
+
+
+def get_pending():
+    """Get list of unprocessed items.
+
+    Returns:
+        List of (ts, text) tuples that haven't been seen yet.
+    """
+    inbox = read_inbox()
+    seen = read_seen()
+    return [(ts, text) for ts, text in inbox if ts not in seen]
+
+
+def cmd_pending():
+    """List unprocessed inbox items. Exit 0."""
+    pending = get_pending()
+    if not pending:
+        print("NO PENDING")
+        return
+
+    for ts, text in pending:
+        print(f"[{ts}] {text}")
+
+
+def cmd_mark(timestamp):
+    """Mark one timestamp as processed.
+
+    Args:
+        timestamp: ISO timestamp string.
+    """
+    seen = read_seen()
+    if timestamp in seen:
+        print(f"[1/1] already marked", file=sys.stderr)
+        return
+
+    SEEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(SEEN_PATH, "a", encoding="utf-8") as f:
+        f.write(timestamp + "\n")
+
+    print(f"[1/1] marked", file=sys.stderr)
+
+
+def cmd_mark_all():
+    """Mark all pending items as processed in one write.
+
+    Prints [i/total] summary to stderr.
+    """
+    pending = get_pending()
+    if not pending:
+        print(f"[0/0] no pending items", file=sys.stderr)
+        return
+
+    seen = read_seen()
+    to_mark = [ts for ts, _ in pending if ts not in seen]
+    if not to_mark:
+        print(f"[0/{len(pending)}] no new items", file=sys.stderr)
+        return
+
+    SEEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(SEEN_PATH, "a", encoding="utf-8") as f:
+        for ts in to_mark:
+            f.write(ts + "\n")
+
+    print(f"[{len(to_mark)}/{len(pending)}] marked all", file=sys.stderr)
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Drain UI inbox submissions, tracking processed items.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Subcommand")
+
+    # pending subcommand
+    subparsers.add_parser("pending", help="List unprocessed inbox items")
+
+    # mark subcommand
+    mark_parser = subparsers.add_parser("mark", help="Mark one item as processed")
+    mark_parser.add_argument("timestamp", help="ISO timestamp to mark")
+
+    # mark-all subcommand
+    subparsers.add_parser("mark-all", help="Mark all pending items as processed")
+
+    args = parser.parse_args()
+
+    if args.command == "pending":
+        cmd_pending()
+    elif args.command == "mark":
+        cmd_mark(args.timestamp)
+    elif args.command == "mark-all":
+        cmd_mark_all()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

package/tools/launch_tui.py

@@ -22,6 +22,55 @@ import time
 from pathlib import Path
 
 
+def resolve_git_bash_path():
+    r"""
+    Resolve git-bash.exe path portably in priority order:
+    1. env var AESOP_GIT_BASH (if set and exists)
+    2. shutil.which('git-bash') (on PATH)
+    3. Derived from shutil.which('git') -> ../git-bash.exe on Windows
+    4. Hardcoded default: C:\Program Files\Git\git-bash.exe
+
+    Raises FileNotFoundError with clear message if none found.
+    """
+    attempted = []
+
+    # 1. Check env var
+    env_path = os.environ.get("AESOP_GIT_BASH")
+    if env_path:
+        attempted.append(f"AESOP_GIT_BASH={env_path}")
+        if os.path.exists(env_path):
+            return env_path
+
+    # 2. Check which('git-bash')
+    which_bash = shutil.which("git-bash")
+    if which_bash:
+        attempted.append(f"which('git-bash')={which_bash}")
+        if os.path.exists(which_bash):
+            return which_bash
+
+    # 3. Derive from which('git')
+    which_git = shutil.which("git")
+    if which_git:
+        # git is typically at C:\Program Files\Git\cmd\git.exe
+        # We want C:\Program Files\Git\git-bash.exe (two levels up, then git-bash.exe)
+        git_path = Path(which_git)
+        derived_bash = git_path.parent.parent / "git-bash.exe"
+        attempted.append(f"derived from git={derived_bash}")
+        if derived_bash.exists():
+            return str(derived_bash)
+
+    # 4. Hardcoded default
+    default_path = r"C:\Program Files\Git\git-bash.exe"
+    attempted.append(f"default={default_path}")
+    if os.path.exists(default_path):
+        return default_path
+
+    # None found
+    raise FileNotFoundError(
+        "git-bash.exe not found. Tried (in order): " + ", ".join(attempted)
+    )
+
+
 def find_terminal():
     """
     Locate a terminal executable.
@@ -30,7 +79,7 @@ def find_terminal():
     command_builder_fn(script_path, title) returns command list to spawn.
     is_wt_bool: True if using wt.exe (needs bash process tracking); False if git-bash (stable pid).
     """
-    git_bash = r"C:\Program Files\Git\git-bash.exe"
+    git_bash = resolve_git_bash_path()
     wt_exe = shutil.which("wt.exe")
     bash_exe = r"C:\Program Files\Git\bin\bash.exe"
 
@@ -56,8 +105,7 @@ def find_terminal():
         return wt_exe, wt_cmd, True
 
     raise FileNotFoundError(
-        "Terminal not found. Tried: Git Bash at "
-        f"{git_bash}, Windows Terminal (wt.exe) with bash at {bash_exe}"
+        "Terminal not found. Tried: Git Bash, Windows Terminal (wt.exe) with bash at {bash_exe}"
     )
 
 

package/tools/lock.mjs

@@ -0,0 +1,211 @@
+/**
+ * lock.mjs — Fail-closed atomic lock acquisition for PROPOSALS.md
+ *
+ * Provides atomic lock operations (mkdir-based) with:
+ * - Exponential backoff (configurable base delay, default 10ms)
+ * - Configurable timeout (env var AESOP_LOCK_TIMEOUT_MS or config, default 30s)
+ * - Stale lock detection and breaking (locks older than 10min are stale)
+ * - Fail-closed: throws on timeout instead of proceeding unlocked
+ *
+ * Usage:
+ *   import { acquireLock, releaseLock } from './lock.mjs';
+ *   const lock = acquireLock(proposalsFile);
+ *   try { ... } finally { releaseLock(lock); }
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Configuration: precedence env > default
+const LOCK_BASE_DELAY_MS = parseInt(process.env.AESOP_LOCK_BASE_DELAY_MS || '10', 10);
+const LOCK_TIMEOUT_MS = parseInt(process.env.AESOP_LOCK_TIMEOUT_MS || '30000', 10); // 30s default
+const STALE_LOCK_THRESHOLD = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Check whether a pid is a live process, cross-platform (Windows + POSIX).
+ *
+ * A stale lock marker's timestamp alone is not trustworthy: a process with
+ * write access to state/ could forge an old timestamp to force-break a
+ * LEGITIMATE live lock (data loss on PROPOSALS.md). Signal-0 delivery via
+ * process.kill() lets us verify the recorded owner is actually gone before
+ * we ever remove its lock directory.
+ *
+ * @param {number} pid
+ * @returns {boolean} true if the pid is alive (or owned by another user —
+ *   EPERM means a process with that pid exists but we can't signal it, which
+ *   still counts as alive for staleness purposes), false if no such process.
+ */
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    // Signal 0 does not actually send a signal; it only checks existence/permission.
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    if (e.code === 'ESRCH') {
+      return false; // No such process — definitely dead.
+    }
+    if (e.code === 'EPERM') {
+      return true; // Process exists but we lack permission to signal it — alive.
+    }
+    // Unknown error (e.g. platform quirk): fail closed and assume alive so we
+    // never break a lock we can't actually prove is dead.
+    return true;
+  }
+}
+
+/**
+ * Acquire an atomic lock directory for a file.
+ * Implements exponential backoff + stale lock breaking.
+ *
+ * @param {string} filePath - Path to the file to lock (lock dir is {filePath}.lock)
+ * @param {Object} opts - Optional: { timeoutMs: number }
+ * @returns {string} Lock directory path
+ * @throws {Error} On timeout (fail-closed; never returns null/undefined on success)
+ */
+export function acquireLock(filePath, opts = {}) {
+  const lockDir = filePath + '.lock';
+  const lockMarkerFile = path.join(lockDir, 'pid-timestamp.txt');
+  const timeoutMs = opts.timeoutMs !== undefined ? opts.timeoutMs : LOCK_TIMEOUT_MS;
+  const startTime = Date.now();
+
+  let attempt = 0;
+
+  while (true) {
+    const elapsedMs = Date.now() - startTime;
+    if (elapsedMs >= timeoutMs) {
+      // Timeout exceeded; throw with diagnostics
+      let diagnostic = '';
+      try {
+        if (fs.existsSync(lockDir)) {
+          const markerPath = path.join(lockDir, 'pid-timestamp.txt');
+          const content = fs.readFileSync(markerPath, 'utf8').trim();
+          const lines = content.split('\n');
+          if (lines.length >= 2) {
+            const holderPid = lines[0];
+            const holderAge = Date.now() - parseInt(lines[1], 10) * 1000;
+            diagnostic = ` (holder pid: ${holderPid}, lock age: ${Math.round(holderAge / 1000)}s)`;
+          }
+        }
+      } catch {
+        // Ignore diagnostics errors
+      }
+      throw new Error(
+        `Failed to acquire ${path.basename(filePath)}.lock after ${timeoutMs}ms${diagnostic}`
+      );
+    }
+
+    try {
+      fs.mkdirSync(lockDir, { exclusive: true });
+      // Lock acquired; write pid+timestamp for staleness detection
+      const lockMarker = `${process.pid}\n${Math.floor(Date.now() / 1000)}\n`;
+      try {
+        fs.writeFileSync(lockMarkerFile, lockMarker, 'utf8');
+      } catch {
+        // Marker write failed, but lock is held; continue
+      }
+      return lockDir;
+    } catch (e) {
+      if (e.code === 'EEXIST') {
+        // Lock exists; check if it's stale
+        try {
+          const markerPath = path.join(lockDir, 'pid-timestamp.txt');
+          const markerContent = fs.readFileSync(markerPath, 'utf8').trim();
+          const lines = markerContent.split('\n');
+          if (lines.length >= 2) {
+            const lockEpoch = parseInt(lines[1], 10);
+            const lockAge = Date.now() - lockEpoch * 1000;
+            if (lockAge > STALE_LOCK_THRESHOLD) {
+              // Timestamp alone is not trustworthy: a process with write
+              // access to state/ could forge an old timestamp to break a
+              // LEGITIMATE live lock (data loss on PROPOSALS.md). Verify the
+              // recorded owner pid is actually dead before reclaiming.
+              const pidField = lines[0];
+              const holderPid = parseInt(pidField, 10);
+              const pidValid = Number.isInteger(holderPid) && holderPid > 0 && String(holderPid) === pidField.trim();
+
+              let ownerDead;
+              if (!pidValid) {
+                console.error(
+                  `Warning: Stale lock marker for ${path.basename(filePath)} has missing/unparseable pid ("${pidField}"); treating as stale-eligible`
+                );
+                ownerDead = true;
+              } else {
+                ownerDead = !isPidAlive(holderPid);
+              }
+
+              if (ownerDead) {
+                // Stale lock detected; warn and reclaim it
+                console.error(
+                  `Warning: Stale lock detected for ${path.basename(filePath)} (age: ${Math.round(lockAge / 1000)}s, pid: ${pidValid ? holderPid : 'unknown'}); breaking lock`
+                );
+                try {
+                  fs.rmSync(lockDir, { recursive: true, force: true });
+                } catch {
+                  // Cleanup failed; will retry or timeout
+                }
+                // Retry immediately after cleanup
+                attempt++;
+                continue;
+              }
+              // Timestamp is stale but the recorded owner process is still
+              // alive — do not break a live holder's lock. Fall through to
+              // the backoff/retry below; fail-closed timeout still applies
+              // if the holder never releases.
+            }
+          }
+        } catch {
+          // Could not read marker; assume lock is active
+        }
+
+        // Lock is held; wait and retry with exponential backoff
+        attempt++;
+        const delayMs = LOCK_BASE_DELAY_MS * Math.pow(2, Math.min(attempt - 1, 5)); // Cap exponential growth at 2^5 = 32x
+        const start = Date.now();
+        while (Date.now() - start < delayMs && Date.now() - startTime < timeoutMs) {
+          // Busy-wait for calculated backoff delay
+        }
+      } else {
+        throw e;
+      }
+    }
+  }
+}
+
+/**
+ * Release an atomic lock directory (must be owned by this process).
+ * Verifies pid ownership before deletion (fail-safe: won't delete locks from other processes).
+ *
+ * @param {string|null} lockDir - Lock directory path (safe to pass null)
+ */
+export function releaseLock(lockDir) {
+  if (!lockDir) {
+    return;
+  }
+
+  try {
+    const markerFile = path.join(lockDir, 'pid-timestamp.txt');
+    let shouldDelete = false;
+
+    try {
+      const markerContent = fs.readFileSync(markerFile, 'utf8').trim();
+      const lines = markerContent.split('\n');
+      if (lines.length >= 1) {
+        const lockPid = lines[0];
+        if (lockPid === String(process.pid)) {
+          shouldDelete = true;
+        }
+      }
+    } catch {
+      // If we can't read the marker, don't delete (fail-safe)
+    }
+
+    if (shouldDelete) {
+      fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+  } catch {
+    // Ignore cleanup errors
+  }
+}