codex-autorunner 0.1.0__py3-none-any.whl

codex_autorunner/server.py

@@ -0,0 +1,23 @@
+from importlib import resources
+
+from .core.engine import Engine, LockError, clear_stale_lock, doctor
+from .web.app import create_app, create_hub_app
+from .web.middleware import BasePathRouterMiddleware
+from .web.static_assets import resolve_static_dir
+
+
+def _static_dir():
+    return resolve_static_dir()
+
+
+__all__ = [
+    "Engine",
+    "LockError",
+    "BasePathRouterMiddleware",
+    "clear_stale_lock",
+    "create_app",
+    "create_hub_app",
+    "doctor",
+    "resources",
+    "_static_dir",
+]

codex_autorunner/spec_ingest.py

@@ -0,0 +1,113 @@
+import re
+import subprocess
+from pathlib import Path
+from typing import Dict, Optional
+
+from .core.codex_runner import build_codex_command
+from .core.engine import Engine
+from .core.prompts import SPEC_INGEST_PROMPT
+from .core.utils import atomic_write
+
+
+class SpecIngestError(Exception):
+    """Raised when ingesting a SPEC fails."""
+
+
+def _extract_section(text: str, tag: str) -> Optional[str]:
+    pattern = re.compile(rf"<{tag}>\s*(.*?)\s*</{tag}>", re.DOTALL | re.IGNORECASE)
+    match = pattern.search(text)
+    if not match:
+        return None
+    return match.group(1).strip()
+
+
+def build_spec_ingest_prompt(spec: str, todo: str, progress: str, opinions: str) -> str:
+    return SPEC_INGEST_PROMPT.format(
+        spec=spec.strip(),
+        todo=todo.strip(),
+        progress=progress.strip(),
+        opinions=opinions.strip(),
+    )
+
+
+def parse_spec_ingest_output(text: str) -> Dict[str, str]:
+    todo = _extract_section(text, "TODO")
+    progress = _extract_section(text, "PROGRESS")
+    opinions = _extract_section(text, "OPINIONS")
+    if not todo or not progress or not opinions:
+        raise SpecIngestError(
+            "Failed to parse ingest output; missing TODO/PROGRESS/OPINIONS sections"
+        )
+    return {"todo": todo, "progress": progress, "opinions": opinions}
+
+
+def generate_docs_from_spec(
+    engine: Engine, spec_path: Optional[Path] = None
+) -> Dict[str, str]:
+    path = spec_path or engine.config.doc_path("spec")
+    if not path.exists():
+        raise SpecIngestError(f"SPEC not found at {path}")
+    spec_text = path.read_text(encoding="utf-8")
+    if not spec_text.strip():
+        raise SpecIngestError(f"SPEC at {path} is empty")
+
+    prompt = build_spec_ingest_prompt(
+        spec_text,
+        engine.docs.read_doc("todo"),
+        engine.docs.read_doc("progress"),
+        engine.docs.read_doc("opinions"),
+    )
+    cmd = build_codex_command(engine.config, prompt)
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=str(engine.repo_root),
+        )
+    except FileNotFoundError as exc:
+        raise SpecIngestError(
+            f"Codex binary not found: {engine.config.codex_binary}"
+        ) from exc
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() if result.stderr else ""
+        stdout_tail = (result.stdout or "").strip()[-400:]
+        raise SpecIngestError(
+            f"Codex ingest failed (code {result.returncode}). {stderr or stdout_tail}"
+        )
+
+    return parse_spec_ingest_output(result.stdout or "")
+
+
+def ensure_can_overwrite(engine: Engine, force: bool) -> None:
+    if force:
+        return
+    for key in ("todo", "progress", "opinions"):
+        existing = engine.docs.read_doc(key).strip()
+        if existing:
+            raise SpecIngestError(
+                "TODO/PROGRESS/OPINIONS already contain content; rerun with --force to overwrite"
+            )
+
+
+def write_ingested_docs(
+    engine: Engine, docs: Dict[str, str], force: bool = False
+) -> None:
+    ensure_can_overwrite(engine, force)
+    for key, content in docs.items():
+        target = engine.config.doc_path(key)
+        text = content if content.endswith("\n") else content + "\n"
+        atomic_write(target, text)
+
+
+def clear_work_docs(engine: Engine) -> Dict[str, str]:
+    defaults = {
+        "todo": "# TODO\n\n",
+        "progress": "# Progress\n\n",
+        "opinions": "# Opinions\n\n",
+    }
+    for key, content in defaults.items():
+        atomic_write(engine.config.doc_path(key), content)
+    # Read back to reflect actual on-disk content.
+    return {k: engine.docs.read_doc(k) for k in defaults.keys()}

codex_autorunner/static/app.js

@@ -0,0 +1,95 @@
+import { detectContext, REPO_ID, HUB_BASE } from "./env.js";
+import { initHub } from "./hub.js";
+import { initTabs, registerTab } from "./tabs.js";
+import { initDashboard } from "./dashboard.js";
+import { initDocs } from "./docs.js";
+import { initLogs } from "./logs.js";
+import { initTerminal } from "./terminal.js";
+import { loadState } from "./state.js";
+import { initGitHub } from "./github.js";
+import { initMobileCompact } from "./mobileCompact.js";
+import { subscribe } from "./bus.js";
+
+function initRepoShell() {
+  // If this is a repo under a hub, show back button and repo name
+  if (REPO_ID) {
+    const navBar = document.querySelector(".nav-bar");
+    if (navBar) {
+      const backBtn = document.createElement("a");
+      backBtn.href = HUB_BASE || "/";
+      backBtn.className = "hub-back-btn";
+      backBtn.textContent = "← Hub";
+      backBtn.title = "Back to Hub";
+      navBar.insertBefore(backBtn, navBar.firstChild);
+    }
+    // Add repo name after the CAR brand (keep CAR visible)
+    const brand = document.querySelector(".nav-brand");
+    if (brand) {
+      const repoName = document.createElement("span");
+      repoName.className = "nav-repo-name";
+      repoName.textContent = REPO_ID;
+      brand.insertAdjacentElement("afterend", repoName);
+    }
+  }
+
+  registerTab("dashboard", "Dashboard");
+  registerTab("docs", "Docs");
+  registerTab("logs", "Logs");
+  registerTab("terminal", "Terminal");
+
+  const initializedTabs = new Set();
+  const lazyInit = (tabId) => {
+    if (initializedTabs.has(tabId)) return;
+    if (tabId === "docs") {
+      initDocs();
+    } else if (tabId === "logs") {
+      initLogs();
+    }
+    initializedTabs.add(tabId);
+  };
+
+  subscribe("tab:change", (tabId) => {
+    if (tabId === "terminal") {
+      initTerminal();
+    }
+    lazyInit(tabId);
+  });
+
+  initTabs();
+  const activePanel = document.querySelector(".panel.active");
+  if (activePanel?.id) {
+    lazyInit(activePanel.id);
+  }
+  const terminalPanel = document.getElementById("terminal");
+  terminalPanel?.addEventListener(
+    "pointerdown",
+    () => {
+      lazyInit("terminal");
+    },
+    { once: true }
+  );
+  initDashboard();
+  initGitHub();
+  initMobileCompact();
+
+  loadState();
+}
+
+async function bootstrap() {
+  const { mode } = await detectContext();
+  const hubShell = document.getElementById("hub-shell");
+  const repoShell = document.getElementById("repo-shell");
+
+  if (mode === "hub") {
+    if (hubShell) hubShell.classList.remove("hidden");
+    if (repoShell) repoShell.classList.add("hidden");
+    initHub();
+    return;
+  }
+
+  if (repoShell) repoShell.classList.remove("hidden");
+  if (hubShell) hubShell.classList.add("hidden");
+  initRepoShell();
+}
+
+bootstrap();

codex_autorunner/static/autoRefresh.js

@@ -0,0 +1,209 @@
+/**
+ * Auto-refresh utility for managing periodic data fetching.
+ *
+ * Features:
+ * - Pauses when page is hidden (respects Page Visibility API)
+ * - Only refreshes active tab's components
+ * - Configurable intervals per component
+ * - Immediate refresh on tab activation
+ * - Debounces rapid activations
+ */
+
+import { subscribe } from "./bus.js";
+import { CONSTANTS } from "./constants.js";
+
+// Track registered refreshers: { id: { callback, interval, tabId, timerId, lastRefresh } }
+const refreshers = new Map();
+
+// Track current active tab
+let activeTab = null;
+
+// Track page visibility
+let pageVisible = true;
+
+/**
+ * Register a component for auto-refresh.
+ *
+ * @param {string} id - Unique identifier for this refresher
+ * @param {Object} options
+ * @param {Function} options.callback - Async function to call for refresh
+ * @param {string} options.tabId - Tab this refresher belongs to (null for global)
+ * @param {number} [options.interval] - Refresh interval in ms (default: AUTO_REFRESH_INTERVAL)
+ * @param {boolean} [options.refreshOnActivation=true] - Refresh when tab becomes active
+ * @param {boolean} [options.immediate=false] - Refresh immediately on registration
+ * @returns {Function} Unregister function
+ */
+export function registerAutoRefresh(id, options) {
+  const {
+    callback,
+    tabId = null,
+    interval = CONSTANTS.UI.AUTO_REFRESH_INTERVAL,
+    refreshOnActivation = true,
+    immediate = false,
+  } = options;
+
+  const refresher = {
+    callback,
+    tabId,
+    interval,
+    refreshOnActivation,
+    timerId: null,
+    lastRefresh: 0,
+    isRefreshing: false,
+  };
+
+  refreshers.set(id, refresher);
+
+  // Start timer if applicable
+  maybeStartTimer(id, refresher);
+
+  // Immediate refresh if requested
+  if (immediate) {
+    doRefresh(id, refresher);
+  }
+
+  return () => unregisterAutoRefresh(id);
+}
+
+/**
+ * Unregister a refresher.
+ */
+export function unregisterAutoRefresh(id) {
+  const refresher = refreshers.get(id);
+  if (refresher) {
+    if (refresher.timerId) {
+      clearInterval(refresher.timerId);
+    }
+    refreshers.delete(id);
+  }
+}
+
+/**
+ * Trigger an immediate refresh for a specific refresher.
+ */
+export function triggerRefresh(id) {
+  const refresher = refreshers.get(id);
+  if (refresher) {
+    doRefresh(id, refresher);
+  }
+}
+
+/**
+ * Check if conditions allow refresh for this refresher.
+ */
+function canRefresh(refresher) {
+  // Don't refresh if page is hidden
+  if (!pageVisible) return false;
+
+  // Don't refresh if already refreshing
+  if (refresher.isRefreshing) return false;
+
+  // If refresher is tab-specific, only refresh when that tab is active
+  if (refresher.tabId && refresher.tabId !== activeTab) return false;
+
+  return true;
+}
+
+/**
+ * Perform the actual refresh.
+ */
+async function doRefresh(id, refresher) {
+  if (!canRefresh(refresher)) return;
+
+  refresher.isRefreshing = true;
+  refresher.lastRefresh = Date.now();
+
+  try {
+    await refresher.callback();
+  } catch (err) {
+    console.error(`Auto-refresh error for '${id}':`, err);
+  } finally {
+    refresher.isRefreshing = false;
+  }
+}
+
+/**
+ * Start or restart the interval timer for a refresher.
+ */
+function maybeStartTimer(id, refresher) {
+  // Clear existing timer
+  if (refresher.timerId) {
+    clearInterval(refresher.timerId);
+    refresher.timerId = null;
+  }
+
+  // Only start timer if page is visible and tab is active (or global)
+  if (!pageVisible) return;
+  if (refresher.tabId && refresher.tabId !== activeTab) return;
+
+  refresher.timerId = setInterval(() => {
+    doRefresh(id, refresher);
+  }, refresher.interval);
+}
+
+/**
+ * Handle tab change - refresh components on the new tab and manage timers.
+ */
+function handleTabChange(tabId) {
+  activeTab = tabId;
+
+  refreshers.forEach((refresher, id) => {
+    // Stop timers for inactive tabs
+    if (refresher.tabId && refresher.tabId !== tabId) {
+      if (refresher.timerId) {
+        clearInterval(refresher.timerId);
+        refresher.timerId = null;
+      }
+      return;
+    }
+
+    // Start/restart timers for active tab
+    maybeStartTimer(id, refresher);
+
+    // Refresh on activation if enabled (with debounce)
+    if (refresher.refreshOnActivation) {
+      const timeSinceLastRefresh = Date.now() - refresher.lastRefresh;
+      // Only refresh if it's been at least 5 seconds since last refresh
+      if (timeSinceLastRefresh > 5000) {
+        doRefresh(id, refresher);
+      }
+    }
+  });
+}
+
+/**
+ * Handle page visibility change.
+ */
+function handleVisibilityChange() {
+  pageVisible = !document.hidden;
+
+  if (pageVisible) {
+    // Page became visible - restart timers and optionally refresh
+    refreshers.forEach((refresher, id) => {
+      maybeStartTimer(id, refresher);
+
+      // Refresh if it's been a while since last refresh
+      const timeSinceLastRefresh = Date.now() - refresher.lastRefresh;
+      if (timeSinceLastRefresh > refresher.interval) {
+        doRefresh(id, refresher);
+      }
+    });
+  } else {
+    // Page hidden - stop all timers
+    refreshers.forEach((refresher) => {
+      if (refresher.timerId) {
+        clearInterval(refresher.timerId);
+        refresher.timerId = null;
+      }
+    });
+  }
+}
+
+// Initialize event listeners
+subscribe("tab:change", handleTabChange);
+
+// Only set up visibility listener if in browser environment
+if (typeof document !== "undefined" && document.addEventListener) {
+  document.addEventListener("visibilitychange", handleVisibilityChange);
+}
+

codex_autorunner/static/bootstrap.js

@@ -0,0 +1,105 @@
+(() => {
+  const AUTH_TOKEN_KEY = "car_auth_token";
+  const url = new URL(window.location.href);
+  const params = url.searchParams;
+  let token = params.get("token");
+  if (token) {
+    window.__CAR_AUTH_TOKEN = token;
+    try {
+      sessionStorage.setItem(AUTH_TOKEN_KEY, token);
+    } catch (_err) {
+      // Ignore storage errors; token can still be used for this load.
+    }
+    params.delete("token");
+    if (typeof history !== "undefined" && history.replaceState) {
+      history.replaceState(null, "", url.toString());
+    }
+  } else {
+    try {
+      token = sessionStorage.getItem(AUTH_TOKEN_KEY);
+      if (token) window.__CAR_AUTH_TOKEN = token;
+    } catch (_err) {
+      // Ignore storage errors; token may still be in memory.
+    }
+  }
+
+  const normalizeBase = (base) => {
+    if (!base || base === "/") return "";
+    let normalized = base.startsWith("/") ? base : `/${base}`;
+    while (normalized.endsWith("/") && normalized.length > 1) {
+      normalized = normalized.slice(0, -1);
+    }
+    return normalized === "/" ? "" : normalized;
+  };
+  const detectBasePrefix = (path) => {
+    const prefixes = ["/repos/", "/hub/", "/api/", "/static/", "/cat/"];
+    let idx = -1;
+    for (const prefix of prefixes) {
+      const found = path.indexOf(prefix);
+      if (found === 0) return "";
+      if (found > 0 && (idx === -1 || found < idx)) idx = found;
+    }
+    if (idx > 0) return normalizeBase(path.slice(0, idx));
+    const parts = path.split("/").filter(Boolean);
+    if (parts.length) return normalizeBase(`/${parts[0]}`);
+    return "";
+  };
+
+  const pathname = window.location.pathname || "/";
+  const basePrefix = detectBasePrefix(pathname);
+  const repoMatch = pathname.match(/\/repos\/([^/]+)/);
+  const repoId = repoMatch && repoMatch[1] ? repoMatch[1] : null;
+
+  window.__CAR_BASE_PREFIX = basePrefix || "";
+  window.__CAR_REPO_ID = repoId;
+  window.__CAR_BASE_PATH = repoId ? `${basePrefix}/repos/${repoId}` : basePrefix;
+  window.__AUTH_TOKEN_PRESENT = Boolean(window.__CAR_AUTH_TOKEN);
+
+  const base = basePrefix || "/";
+  const baseTag = document.createElement("base");
+  baseTag.href = base.endsWith("/") ? base : `${base}/`;
+  document.head.appendChild(baseTag);
+
+  const readAssetVersion = () => {
+    const queryVersion = new URLSearchParams(window.location.search).get("v");
+    if (queryVersion) return queryVersion;
+    const bootstrapScript =
+      document.currentScript ||
+      document.querySelector('script[data-car-bootstrap]');
+    if (bootstrapScript && bootstrapScript.src) {
+      try {
+        const scriptUrl = new URL(bootstrapScript.src, window.location.href);
+        return scriptUrl.searchParams.get("v") || "";
+      } catch (_err) {
+        return "";
+      }
+    }
+    return "";
+  };
+
+  const version = readAssetVersion();
+  const suffix = version ? `?v=${encodeURIComponent(version)}` : "";
+  window.__assetSuffix = suffix;
+
+  const addStylesheet = (href) => {
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = `${href}${suffix}`;
+    document.head.appendChild(link);
+  };
+
+  addStylesheet("static/styles.css");
+  addStylesheet("static/vendor/xterm.css");
+
+  fetch("api/version", { cache: "no-store" })
+    .then((res) => (res.ok ? res.json() : null))
+    .then((data) => {
+      const assetVersion = data && data.asset_version;
+      if (assetVersion && assetVersion !== version) {
+        const next = new URL(window.location.href);
+        next.searchParams.set("v", assetVersion);
+        window.location.replace(next.toString());
+      }
+    })
+    .catch(() => {});
+})();

codex_autorunner/static/bus.js

@@ -0,0 +1,23 @@
+const listeners = new Map();
+
+export function subscribe(event, handler) {
+  if (!listeners.has(event)) {
+    listeners.set(event, new Set());
+  }
+  const set = listeners.get(event);
+  set.add(handler);
+  return () => set.delete(handler);
+}
+
+export function publish(event, payload) {
+  const set = listeners.get(event);
+  if (!set) return;
+  for (const handler of Array.from(set)) {
+    try {
+      handler(payload);
+    } catch (err) {
+      // Keep a misbehaving subscriber from breaking others
+      console.error(`Error in '${event}' subscriber`, err);
+    }
+  }
+}

codex_autorunner/static/cache.js

@@ -0,0 +1,52 @@
+import { BASE_PATH, REPO_ID } from "./env.js";
+
+function cachePrefix() {
+  const scope = REPO_ID ? `repo:${REPO_ID}` : `base:${BASE_PATH || ""}`;
+  return `car:${encodeURIComponent(scope)}:`;
+}
+
+function scopedKey(key) {
+  return cachePrefix() + key;
+}
+
+/**
+ * Save data to localStorage with error handling.
+ * @param {string} key - The key to store the data under (will be scoped per repo/base path)
+ * @param {any} data - The data to store (will be JSON stringified)
+ */
+export function saveToCache(key, data) {
+  try {
+    const json = JSON.stringify(data);
+    localStorage.setItem(scopedKey(key), json);
+  } catch (err) {
+    console.warn("Failed to save to cache", key, err);
+  }
+}
+
+/**
+ * Load data from localStorage with error handling.
+ * @param {string} key - The key to retrieve data from (will be scoped per repo/base path)
+ * @returns {any|null} The parsed data, or null if not found or invalid
+ */
+export function loadFromCache(key) {
+  try {
+    const json = localStorage.getItem(scopedKey(key));
+    if (!json) return null;
+    return JSON.parse(json);
+  } catch (err) {
+    console.warn("Failed to load from cache", key, err);
+    return null;
+  }
+}
+
+/**
+ * Remove data from localStorage.
+ * @param {string} key - The key to remove (will be scoped per repo/base path)
+ */
+export function clearCache(key) {
+  try {
+    localStorage.removeItem(scopedKey(key));
+  } catch (err) {
+    console.warn("Failed to clear cache", key, err);
+  }
+}

codex_autorunner/static/constants.js

@@ -0,0 +1,48 @@
+export const CONSTANTS = {
+  UI: {
+    TOAST_DURATION: 2200,
+    POLLING_INTERVAL: 15000,
+    LOG_SCROLL_THRESHOLD: 50,
+    MAX_LOG_LINES_IN_DOM: 2000, // Limit DOM nodes for performance
+    MAX_LOG_LINES_IN_MEMORY: 10000, // Cap memory usage for long-running logs
+    LOG_PAGE_SIZE: 500,
+    // Auto-refresh intervals (in ms)
+    AUTO_REFRESH_INTERVAL: 30000, // 30 seconds for periodic refresh
+    AUTO_REFRESH_USAGE_INTERVAL: 60000, // 60 seconds for usage data (less critical)
+  },
+  THEME: {
+    XTERM: {
+      background: '#0a0c12',
+      foreground: '#e5ecff',
+      cursor: '#6cf5d8',
+      selectionBackground: 'rgba(108, 245, 216, 0.3)',
+      black: '#000000',
+      red: '#ff5566',
+      green: '#6cf5d8',
+      yellow: '#f1fa8c',
+      blue: '#6ca8ff',
+      magenta: '#bd93f9',
+      cyan: '#8be9fd',
+      white: '#e5ecff',
+      brightBlack: '#6272a4',
+      brightRed: '#ff6e6e',
+      brightGreen: '#69ff94',
+      brightYellow: '#ffffa5',
+      brightBlue: '#d6acff',
+      brightMagenta: '#ff92df',
+      brightCyan: '#a4ffff',
+      brightWhite: '#ffffff',
+    }
+  },
+  PROMPTS: {
+    VOICE_TRANSCRIPT_DISCLAIMER:
+      "Note: transcribed from user voice. If confusing or possibly inaccurate and you cannot infer the intention please clarify before proceeding.",
+  },
+  API: {
+    STATE_ENDPOINT: "/api/state",
+    LOGS_ENDPOINT: "/api/logs",
+    DOCS_ENDPOINT: "/api/docs",
+    TERMINAL_ENDPOINT: "/api/terminal",
+    TERMINAL_IMAGE_ENDPOINT: "/api/terminal/image",
+  }
+};