forgecommandline 0.8.0__py3-none-any.whl

forgecli/attach.py

@@ -0,0 +1,246 @@
+"""Files the user hands Forge by typing or pasting their path: any kind, not just images.
+
+A path in a message (or in an answer to one of Forge's questions) is found even with spaces, without
+quotes, or with words glued to its end ("C:\\clip.mp4continue"). Each file becomes an attachment note
+the model can't miss: what it is, how big, and what to do with it. Word documents, PDFs, slides and
+text files have their text pulled out right here, so the model never has to guess at a parser (the
+old way: `python3 -c "import docx"` failing four times in a row). Images still go to vision models
+through images.py."""
+from __future__ import annotations
+
+import pathlib
+import re
+import zipfile
+
+from . import images
+
+TEXT_EXTS = {".txt", ".md", ".csv", ".json", ".yaml", ".yml", ".toml", ".html", ".htm", ".css", ".js",
+             ".ts", ".tsx", ".jsx", ".py", ".rtf", ".xml", ".ini", ".log", ".sql", ".php", ".java", ".c",
+             ".cpp", ".h", ".go", ".rs", ".rb", ".sh", ".ps1", ".bat", ".svg", ".tex", ".bib"}
+VIDEO = {".mp4", ".webm", ".mov", ".mkv", ".avi", ".m4v"}
+AUDIO = {".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac"}
+FONTS = {".woff", ".woff2", ".ttf", ".otf"}
+ARCHIVES = {".zip", ".tar", ".gz", ".7z", ".rar"}
+MAX_TEXT = 8000          # characters of a document put into the conversation
+MAX_FILES = 8
+
+# Where a path can start: a drive, a UNC share, home, or ./ ../
+_START = re.compile(r"""(?:(?<=^)|(?<=[\s"'(\[<,;]))(?:[A-Za-z]:[\\/]|\\\\|~[\\/]|\.{1,2}[\\/]|/(?=[^\s/]))""")
+_QUOTED = re.compile(r""""([^"\n]{2,400})"|'([^'\n]{2,400})'""")
+
+
+def kind(path: pathlib.Path) -> str:
+    if path.is_dir():
+        return "folder"
+    ext = path.suffix.lower()
+    if ext in images.EXTS:
+        return "image"
+    if ext in VIDEO:
+        return "video"
+    if ext in AUDIO:
+        return "audio"
+    if ext in {".docx", ".pdf", ".pptx", ".odt", ".doc"}:
+        return "document"
+    if ext in {".xlsx", ".xls", ".ods"}:
+        return "spreadsheet"
+    if ext in FONTS:
+        return "font"
+    if ext in ARCHIVES:
+        return "archive"
+    if ext in TEXT_EXTS:
+        return "text"
+    return "file"
+
+
+def _exists(raw: str, root: pathlib.Path) -> pathlib.Path | None:
+    raw = raw.strip().rstrip(".,;:)]}>!?")
+    if not raw:
+        return None
+    p = pathlib.Path(raw).expanduser()
+    if not p.is_absolute():
+        p = root / p
+    try:
+        if p.exists():
+            return p.resolve()
+    except (OSError, ValueError):
+        return None
+    return None
+
+
+def _longest(text: str, start: int, root: pathlib.Path) -> tuple[pathlib.Path, int] | None:
+    """The longest existing path that starts at `start`, so spaces and glued words both work:
+    "C:\\a b\\clip.mp4continue" → C:\\a b\\clip.mp4. Files beat folders that are only a prefix."""
+    end = text.find("\n", start)
+    end = len(text) if end < 0 else end
+    chunk = text[start:min(end, start + 400)]
+    best = None
+    # Candidate cut points: every position after an extension-looking end, or a separator.
+    for i in range(len(chunk), 1, -1):
+        cand = chunk[:i]
+        if cand[-1] in " \t":
+            continue
+        nxt = chunk[i:i + 1]
+        is_file_end = bool(re.search(r"\.[A-Za-z0-9]{1,5}$", cand))
+        if not (is_file_end or nxt in ("", " ", "\t", '"', "'", ",", ";", ")") or cand[-1] in "\\/"):
+            continue
+        p = _exists(cand, root)
+        if p is not None:
+            if p.is_file():
+                return p, start + len(cand)
+            if best is None and nxt in ("", " ", "\t", '"', "'", ",", ";", ")"):
+                best = (p, start + len(cand))
+    return best
+
+
+def find(text: str, root: pathlib.Path | None = None) -> list[pathlib.Path]:
+    """Existing files and folders named in the text, in order, without repeats."""
+    root = pathlib.Path(root or pathlib.Path.cwd())
+    text = text or ""
+    found: list[pathlib.Path] = []
+
+    def add(p):
+        if p is not None and p not in found and str(p) != str(root.resolve()):
+            found.append(p)
+
+    for m in _QUOTED.finditer(text):
+        add(_exists(m.group(1) or m.group(2), root))
+    for m in _START.finditer(text):
+        hit = _longest(text, m.start(), root)
+        if hit:
+            add(hit[0])
+    # Bare relative names with an extension ("photo.jpg", "docs/cv.pdf").
+    for m in re.finditer(r"(?<![\w\\/:.-])([\w.-]+(?:[\\/][\w .-]+)*\.[A-Za-z0-9]{1,5})(?![\w\\/])", text):
+        add(_exists(m.group(1), root))
+    # Drop a folder when a file inside it was also named (the folder was just a prefix).
+    files = [p for p in found if p.is_file()]
+    found = [p for p in found if p.is_file() or not any(f.is_relative_to(p) for f in files)]
+    return found[:MAX_FILES]
+
+
+def strip_paths(text: str, root: pathlib.Path | None = None) -> str:
+    """The text with every existing path taken out: "C:\\clip.mp4continue" → "continue"."""
+    root = pathlib.Path(root or pathlib.Path.cwd())
+    text = text or ""
+    cuts = []
+    for m in _QUOTED.finditer(text):
+        if _exists(m.group(1) or m.group(2), root):
+            cuts.append((m.start(), m.end()))
+    for m in _START.finditer(text):
+        hit = _longest(text, m.start(), root)
+        if hit:
+            cuts.append((m.start(), hit[1]))
+    out, pos = [], 0
+    for a, b in sorted(cuts):
+        if a >= pos:
+            out.append(text[pos:a])
+            pos = b
+    out.append(text[pos:])
+    return " ".join("".join(out).split())
+
+
+def _size(p: pathlib.Path) -> str:
+    try:
+        n = p.stat().st_size
+    except OSError:
+        return "?"
+    for unit in ("bytes", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.0f} {unit}" if unit == "bytes" else f"{n:.1f} {unit}"
+        n /= 1024
+    return "?"
+
+
+def _xml_text(xml: str, para: str, run: str) -> str:
+    out = []
+    for p in re.findall(rf"<{para}[ >].*?</{para}>", xml, re.S):
+        t = "".join(re.findall(rf"<{run}(?: [^>]*)?>([^<]*)</{run}>", p))
+        if t.strip():
+            out.append(t)
+    return "\n".join(out)
+
+
+def _unescape(s: str) -> str:
+    return (s.replace("&lt;", "<").replace("&gt;", ">").replace("&quot;", '"')
+             .replace("&apos;", "'").replace("&amp;", "&"))
+
+
+def extract(p: pathlib.Path) -> str | None:
+    """Readable text of a document, or None when it can't be read here."""
+    ext = p.suffix.lower()
+    try:
+        if ext == ".docx":
+            with zipfile.ZipFile(p) as z:
+                xml = z.read("word/document.xml").decode("utf8", "replace")
+            return _unescape(_xml_text(xml, "w:p", "w:t"))
+        if ext == ".pptx":
+            with zipfile.ZipFile(p) as z:
+                names = sorted((n for n in z.namelist() if re.match(r"ppt/slides/slide\d+\.xml$", n)),
+                               key=lambda n: int(re.search(r"(\d+)", n.rsplit("/", 1)[1]).group(1)))
+                slides = [_unescape(_xml_text(z.read(n).decode("utf8", "replace"), "a:p", "a:t"))
+                          for n in names]
+            return "\n\n".join(f"[slide {i}]\n{s}" for i, s in enumerate(slides, 1) if s.strip())
+        if ext == ".odt":
+            with zipfile.ZipFile(p) as z:
+                xml = z.read("content.xml").decode("utf8", "replace")
+            return _unescape(re.sub(r"<[^>]+>", " ", re.sub(r"</text:p>", "\n", xml)))
+        if ext == ".pdf":
+            try:
+                from pypdf import PdfReader  # optional
+            except ImportError:
+                return None
+            return "\n".join((pg.extract_text() or "") for pg in PdfReader(str(p)).pages[:30])
+        if kind(p) == "text" and p.stat().st_size <= 2_000_000:
+            return p.read_text(encoding="utf8", errors="replace")
+    except (OSError, KeyError, ValueError, zipfile.BadZipFile, AttributeError):
+        return None
+    except Exception:  # a broken document must never break the turn
+        return None
+    return None
+
+
+_USE = {
+    "image": "an image the user wants used; to put it on a page copy it into the project (e.g. "
+             "assets/) and reference that copy, replacing any placeholder in the slot it fits",
+    "video": "a video the user wants used (e.g. a hero/background); copy it into the project and use a "
+             "<video autoplay muted loop playsinline> element pointing at the copy",
+    "audio": "an audio file; copy it into the project before referencing it",
+    "font": "a font; copy it into the project and load it with @font-face",
+    "folder": "a folder the user pointed at; list it before using what's inside",
+}
+
+
+def note(paths: list[pathlib.Path], root: pathlib.Path | None = None) -> str:
+    """The attachment block appended to the user's message."""
+    if not paths:
+        return ""
+    lines = ["[Forge: the user attached these — they are inputs to use, not questions to ask about. "
+             "Paths are exact; on Windows use `python`, not `python3`.]"]
+    bodies = []
+    for p in paths:
+        k = kind(p)
+        lines.append(f"- {p}  ({k}, {_size(p)})" + (f" — {_USE[k]}" if k in _USE else ""))
+        if k in ("document", "text", "spreadsheet"):
+            text = extract(p)
+            if text and text.strip():
+                text = re.sub(r"\n{3,}", "\n\n", text.strip())
+                cut = len(text) > MAX_TEXT
+                bodies.append(f"--- text of {p.name}{' (first part)' if cut else ''} ---\n"
+                              f"{text[:MAX_TEXT]}\n--- end of {p.name} ---")
+                lines[-1] += " — its text is below, use it directly"
+            elif k != "text":
+                lines[-1] += " — couldn't read it here; read it with a tool if you need its contents"
+    return "\n".join(lines + bodies)
+
+
+def user_message(text: str, root: pathlib.Path | None = None) -> dict:
+    """A user message with every attached file noted and images listed for vision models."""
+    msg = images.user_message(text, root)
+    paths = find(text, root)
+    if paths:
+        msg["content"] = (text or "") + "\n\n" + note(paths, root)
+        msg["attachments"] = [str(p) for p in paths]
+        imgs = [str(p) for p in paths if kind(p) == "image" and 0 < p.stat().st_size <= images.MAX_BYTES]
+        merged = list(dict.fromkeys((msg.get("images") or []) + imgs))[:4]
+        if merged:
+            msg["images"] = merged
+    return msg

forgecli/brief.py

@@ -0,0 +1,215 @@
+"""The pinned brief: what the user asked for and already decided, kept in front of the model.
+
+Long builds overflow the context, and trimming used to drop the very things the model needed most:
+the real request (when the newest message was only "continue") and the answers to its own
+questions. With those gone it interviewed the user again, invented details ("product designer"),
+and re-read the same reference files. The brief is rebuilt from the full saved conversation before
+every request and joined to the system message, so trimming can never remove it.
+
+It also powers two guards on ask_user: a question on a topic the user already answered gets that
+answer back instead of reaching the user, and an interview is capped at a few questions."""
+from __future__ import annotations
+
+import functools
+import json
+import re
+
+ATTACH_MARK = "\n\n[Forge: the user attached"
+ANSWER_PREFIX = "The user answered: "
+MAX_QUESTIONS = 4          # ask_user calls per request before Forge says "build with what you have"
+
+_CONTINUE = re.compile(
+    r"^\s*(?:ok(?:ay)?|yes|yep|yeah|sure|go|go on|go ahead|continue|keep going|carry on|proceed|resume|"
+    r"next|do it|please continue|continue please|keep building|finish(?: it)?|carry on please)"
+    r"[\s.!,]*$", re.I)
+
+# Questions are compared by topic, not wording: "Which Hallmark theme resonates most?" and
+# "Which visual style appeals to you?" are the same question.
+TOPICS = {
+    "style": ("theme", "style", "visual", "look", "aesthetic", "vibe", "palette", "colour", "color",
+              "mood", "design direction", "feel"),
+    "goal": ("goal", "purpose", "aim", "objective", "visitors", "what do you want", "primary"),
+    "identity": ("your name", "who are you", "what do you do", "your role", "job title", "profession",
+                 "describe yourself", "occupation"),
+    "content": ("case stud", "projects", "work should", "show", "screenshots", "materials", "gallery",
+                "portfolio include", "content"),
+    "pages": ("one page", "multi-page", "multi page", "single page", "how many pages", "separate pages",
+              "sections"),
+    "audience": ("audience", "who is it for", "target", "who will"),
+    "stack": ("framework", "react", "plain html", "tech stack", "which language", "library"),
+}
+
+
+def topic(question: str) -> str | None:
+    q = (question or "").lower()
+    scores = {name: sum(1 for w in words if w in q) for name, words in TOPICS.items()}
+    best = max(scores, key=scores.get)
+    return best if scores[best] else None
+
+
+def _words(s: str) -> set[str]:
+    return {w for w in re.findall(r"[a-z]{4,}", (s or "").lower())}
+
+
+def similar(a: str, b: str) -> bool:
+    ta, tb = topic(a), topic(b)
+    if ta and ta == tb:
+        return True
+    wa, wb = _words(a), _words(b)
+    return bool(wa and wb) and len(wa & wb) / len(wa | wb) >= 0.5
+
+
+@functools.lru_cache(maxsize=512)
+def _continuation(text: str) -> bool:
+    from . import attach
+    if _CONTINUE.match(text):
+        return True
+    return len(text) < 600 and bool(_CONTINUE.match(attach.strip_paths(text)))
+
+
+def is_continuation(text) -> bool:
+    """'continue', 'yes', 'go on' … — also after attached paths are taken out of the text."""
+    return _continuation(own_text(text).strip())
+
+
+def own_text(content) -> str:
+    """The words the user typed, without Forge's attachment note."""
+    if isinstance(content, list):
+        content = " ".join(p.get("text", "") for p in content if isinstance(p, dict))
+    text = str(content or "")
+    return text.split(ATTACH_MARK, 1)[0]
+
+
+def _is_forge(text: str) -> bool:
+    return text.lstrip().startswith("[Forge")
+
+
+def requests(messages: list[dict]) -> list[str]:
+    """The user's own messages, oldest first, without Forge's injected notes."""
+    out = []
+    for m in messages:
+        if m.get("role") != "user":
+            continue
+        text = own_text(m.get("content")).strip()
+        if text and not _is_forge(text):
+            out.append(text)
+    return out
+
+
+def current_request(messages: list[dict]) -> str:
+    """The newest real request: 'continue' and friends point back to the one before."""
+    reqs = requests(messages)
+    for text in reversed(reqs):
+        if not is_continuation(text):
+            return text
+    return reqs[-1] if reqs else ""
+
+
+def answers(messages: list[dict]) -> list[tuple[str, str]]:
+    """Every (question, answer) pair from ask_user, oldest first."""
+    asked = {}
+    out = []
+    for m in messages:
+        if m.get("role") == "assistant":
+            for c in m.get("tool_calls") or []:
+                fn = c.get("function") or {}
+                if fn.get("name") == "ask_user":
+                    try:
+                        q = json.loads(fn.get("arguments") or "{}").get("question", "")
+                    except (ValueError, AttributeError):
+                        q = ""
+                    asked[c.get("id")] = str(q)
+        elif m.get("role") == "tool" and m.get("tool_call_id") in asked:
+            content = str(m.get("content") or "")
+            if content.startswith(ANSWER_PREFIX):
+                a = own_text(content[len(ANSWER_PREFIX):]).strip()
+                out.append((asked[m["tool_call_id"]], a))
+            elif content.startswith("Already answered"):
+                pass
+    return out
+
+
+def asked_since_request(messages: list[dict]) -> int:
+    """ask_user calls since the user's newest real (non-continuation) request."""
+    start = 0
+    for i, m in enumerate(messages):
+        if m.get("role") == "user":
+            text = own_text(m.get("content")).strip()
+            if text and not _is_forge(text) and not is_continuation(text):
+                start = i
+    n = 0
+    for m in messages[start:]:
+        for c in m.get("tool_calls") or [] if m.get("role") == "assistant" else []:
+            if (c.get("function") or {}).get("name") == "ask_user":
+                n += 1
+    return n
+
+
+def attachments(messages: list[dict]) -> list[str]:
+    """Attached paths, from user messages and from answers to ask_user."""
+    seen = []
+    for m in messages:
+        found = list(m.get("attachments") or [])
+        content = m.get("content")
+        if m.get("role") == "tool" and isinstance(content, str) and ATTACH_MARK in content:
+            note = content.split(ATTACH_MARK, 1)[1]
+            found += re.findall(r"^- (.+?)  \(", note, re.M)
+        for p in found:
+            if p not in seen:
+                seen.append(p)
+    return seen
+
+
+def _clip(s: str, n: int) -> str:
+    s = re.sub(r"\s+", " ", s).strip()
+    return s if len(s) <= n else s[:n - 1] + "…"
+
+
+def build(messages: list[dict], todo: list[dict] | None = None) -> str:
+    """The brief text, or '' when there is nothing worth pinning yet."""
+    reqs = requests(messages)
+    qa = answers(messages)
+    files = attachments(messages)
+    if len(reqs) < 2 and not qa and not files and not todo:
+        return ""   # a one-message conversation is fully visible anyway
+    lines = ["[Pinned brief: the user's own words and decisions, always current even when older "
+             "messages were trimmed. Never ask again about anything answered here and never invent "
+             "details that contradict it; build from it.]"]
+    current = current_request(messages)
+    earlier = [r for r in reqs if r != current and not is_continuation(r)][-5:]
+    if earlier:
+        lines.append("Earlier requests (oldest first):")
+        lines += [f"- {_clip(r, 300)}" for r in earlier]
+    if current:
+        lines.append(f"Current request: {_clip(current, 900)}")
+    if reqs and is_continuation(reqs[-1]) and current != reqs[-1]:
+        lines.append(f"The user's newest message was \"{_clip(own_text(reqs[-1]), 60)}\": keep working "
+                     "on the current request from where it stopped. Don't start over, don't re-read "
+                     "references you already used, and don't interview again.")
+    if qa:
+        lines.append("Answers the user already gave (final; do not ask these again):")
+        lines += [f"- Q: {_clip(q, 160)} → A: {_clip(a, 300)}" for q, a in qa[-12:]]
+    if files:
+        lines.append("Files the user attached (use them; exact paths):")
+        lines += [f"- {p}" for p in files[-10:]]
+    if todo:
+        open_items = [i.get("task", "") for i in todo if i.get("status") != "done"]
+        done_items = [i.get("task", "") for i in todo if i.get("status") == "done"]
+        if open_items:
+            lines.append("Plan, still open: " + "; ".join(_clip(t, 80) for t in open_items[:10]))
+        if done_items:
+            lines.append("Plan, done: " + "; ".join(_clip(t, 60) for t in done_items[:10]))
+    return "\n".join(lines)
+
+
+def reuse(messages: list[dict], question: str) -> str | None:
+    """A tool result for an ask_user that shouldn't reach the user, or None to ask it."""
+    for q, a in reversed(answers(messages)):
+        if similar(question, q):
+            return (f"Already answered — the user said: {a!r} (to: {_clip(q, 120)!r}). Don't ask again; "
+                    "use that answer.")
+    if asked_since_request(messages) > MAX_QUESTIONS:
+        return (f"You've already asked {MAX_QUESTIONS} questions for this request. Stop interviewing: "
+                "build now with the answers in the pinned brief, pick sensible defaults for anything "
+                "still open, and say which defaults you chose.")
+    return None

forgecli/browsercheck.py

@@ -0,0 +1,99 @@
+"""Looking at a local web page the way a person would: a headless browser loads it, collects errors
+and takes a screenshot. Playwright is used when installed (it also catches console and page errors);
+otherwise Microsoft Edge or Chrome, which most computers already have, take the screenshot from the
+command line. Only localhost pages are checked (tools.t_browser_check enforces that)."""
+from __future__ import annotations
+
+import os
+import pathlib
+import shutil
+import subprocess
+import tempfile
+import time
+
+WIDTH, HEIGHT = 1280, 860
+
+
+def shot_path(root: pathlib.Path) -> pathlib.Path:
+    """Screenshots go in Forge's own folder, never the user's project."""
+    d = pathlib.Path(os.environ.get("FORGE_HOME", pathlib.Path.home() / ".forge")) / "screenshots"
+    d.mkdir(parents=True, exist_ok=True)
+    olds = sorted(d.glob("page-*.png"))
+    for old in olds[:-20]:            # keep the last 20
+        try:
+            old.unlink()
+        except OSError:
+            pass
+    return d / f"page-{time.strftime('%Y%m%d-%H%M%S')}-{os.getpid() % 1000}.png"
+
+
+def playwright_check(url: str, shot: pathlib.Path) -> str | None:
+    """Status, title, errors and a full-page screenshot; None when Playwright isn't installed."""
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        return None
+    console_errors, page_errors = [], []
+    status = title = None
+    try:
+        with sync_playwright() as pw:
+            browser = pw.chromium.launch(headless=True)
+            try:
+                page = browser.new_page(viewport={"width": WIDTH, "height": HEIGHT})
+                page.on("console", lambda m: console_errors.append(m.text) if m.type == "error" else None)
+                page.on("pageerror", lambda e: page_errors.append(str(e)))
+                resp = page.goto(url, wait_until="networkidle", timeout=20_000)
+                status = resp.status if resp else "no response"
+                title = page.title()
+                try:
+                    page.screenshot(path=str(shot), full_page=True, timeout=10_000)
+                except Exception:
+                    pass
+            finally:
+                browser.close()
+    except Exception as exc:
+        return f"Browser check failed: {type(exc).__name__}: {exc}"
+    lines = [f"HTTP {status}", f"title: {title or '(empty)'}",
+             f"console errors: {len(console_errors)}", f"page errors: {len(page_errors)}"]
+    lines += [f"console: {e[:300]}" for e in console_errors[:5]]
+    lines += [f"page error: {e[:300]}" for e in page_errors[:5]]
+    return "\n".join(lines)
+
+
+def find_browser() -> str | None:
+    env = os.environ.get("FORGE_BROWSER")
+    if env and pathlib.Path(env).exists():
+        return env
+    for name in ("msedge", "chrome", "google-chrome", "chromium", "chromium-browser"):
+        p = shutil.which(name)
+        if p:
+            return p
+    pf = [os.environ.get(k) for k in ("ProgramFiles(x86)", "ProgramFiles", "LOCALAPPDATA")]
+    rel = [r"Microsoft\Edge\Application\msedge.exe", r"Google\Chrome\Application\chrome.exe"]
+    for base in filter(None, pf):
+        for r in rel:
+            p = pathlib.Path(base) / r
+            if p.exists():
+                return str(p)
+    mac = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    return mac if pathlib.Path(mac).exists() else None
+
+
+def cli_screenshot(url: str, shot: pathlib.Path) -> str:
+    """Screenshot with Edge/Chrome's own headless mode (no console errors this way)."""
+    exe = find_browser()
+    if not exe:
+        return ("Skipped: no Playwright and no Edge/Chrome found to take a screenshot. "
+                "Install Playwright (pip install playwright; playwright install chromium) for full checks.")
+    with tempfile.TemporaryDirectory(prefix="forge-browser-") as prof:
+        cmd = [exe, "--headless=new", "--disable-gpu", "--no-first-run", "--no-default-browser-check",
+               "--hide-scrollbars", f"--user-data-dir={prof}", f"--window-size={WIDTH},{HEIGHT}",
+               "--virtual-time-budget=4000", f"--screenshot={shot}", url]
+        try:
+            subprocess.run(cmd, capture_output=True, timeout=45)
+        except Exception as exc:
+            return f"Browser check failed: {type(exc).__name__}: {exc}"
+    if shot.exists() and shot.stat().st_size > 0:
+        return (f"Loaded {url} in headless {pathlib.Path(exe).stem} (Playwright not installed, so console "
+                "errors were not collected).")
+    return f"Browser check failed: {pathlib.Path(exe).stem} did not produce a screenshot of {url}."

forgecli/checkpoints.py

@@ -0,0 +1,81 @@
+"""In-memory file snapshots used by /undo."""
+from __future__ import annotations
+
+import os
+import pathlib
+import stat
+import tempfile
+from dataclasses import dataclass
+
+
+@dataclass
+class FileState:
+    path: pathlib.Path
+    existed: bool
+    content: bytes = b""
+    mode: int | None = None
+
+
+@dataclass
+class Checkpoint:
+    files: list[FileState]
+    message_index: int | None
+
+
+class Checkpoints:
+    def __init__(self, limit: int = 50):
+        self.limit = limit
+        self.entries: list[Checkpoint] = []
+        self.message_index: int | None = None
+
+    def capture(self, paths: list[pathlib.Path]) -> Checkpoint:
+        files = []
+        for path in dict.fromkeys(paths):
+            exists = path.exists()
+            if exists and not path.is_file():
+                raise OSError(f"cannot checkpoint non-file path: {path}")
+            content = path.read_bytes() if exists else b""
+            mode = stat.S_IMODE(path.stat().st_mode) if exists else None
+            files.append(FileState(path, exists, content, mode))
+        return Checkpoint(files, self.message_index)
+
+    def add(self, checkpoint: Checkpoint) -> None:
+        if (checkpoint.message_index is not None and self.entries and
+                self.entries[-1].message_index == checkpoint.message_index):
+            previous = self.entries[-1]
+            known = {state.path for state in previous.files}
+            previous.files.extend(state for state in checkpoint.files if state.path not in known)
+        else:
+            self.entries.append(checkpoint)
+        del self.entries[:-self.limit]
+        self.message_index = None
+
+    def clear(self) -> None:
+        self.entries.clear()
+        self.message_index = None
+
+    def restore(self, checkpoint: Checkpoint) -> None:
+        for state in reversed(checkpoint.files):
+            if not state.existed:
+                state.path.unlink(missing_ok=True)
+                continue
+            fd, tmp_name = tempfile.mkstemp(prefix=f".{state.path.name}.forge-undo-",
+                                            dir=state.path.parent)
+            tmp = pathlib.Path(tmp_name)
+            try:
+                with os.fdopen(fd, "wb") as stream:
+                    stream.write(state.content)
+                if state.mode is not None:
+                    os.chmod(tmp, state.mode)
+                os.replace(tmp, state.path)
+            finally:
+                if tmp.exists():
+                    tmp.unlink()
+
+    def undo(self) -> Checkpoint:
+        if not self.entries:
+            raise LookupError("there are no file changes to undo")
+        checkpoint = self.entries[-1]
+        self.restore(checkpoint)
+        self.entries.pop()
+        return checkpoint