draftwatch 0.2.0__tar.gz → 0.2.2__tar.gz

{draftwatch-0.2.0 → draftwatch-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwatch
-Version: 0.2.0
+Version: 0.2.2
 Summary: Review an AI agent's edits to your writing files as a real git word-diff — keep or revert changes hunk by hunk, then commit.
 Author: Mike Konczal
 License: MIT
@@ -22,13 +22,19 @@ Dynamic: license-file
 
 # Draftwatch
 
-Draftwatch is a lightweight IDE for writers. You can use it to create and format new Markdown documents from scratch, or use it to review an AI agent's edits to your writing exactly the way a developer reviews a pull request.
+![Draftwatch reviewing an agent's edits: your working text on the left in a real editor, the word diff against your baseline on the right. Click any change to revert it.](https://raw.githubusercontent.com/mtkonczal/Draftwatch/main/assets/draftwatch_screenshot.png)
+
+It’s difficult for writers to have AI act as an editor, because it’s never clear exactly what it changed. You can’t trust eyeballing it, but making the changes manually yourself means you don’t save much time. So you either ignore this potentially powerful writing helper, or you trust it at the risk that it does far more than you asked.
+
+Enter Draftwatch. Draftwatch is a lightweight editing tool for writers. You can use it to create and format new Markdown documents from scratch, but its more powerful use is reviewing an AI agent's edits to your writing, down to the exact word. Changes are managed by git, the way a developer reviews changes to their code, but formatted for writers who need to see each exact word change to feel comfortable.
 
 When reviewing AI edits, instead of guessing what an LLM changed in your document, Draftwatch shows you the exact, git-backed word-diff. You can step through, keep or revert each change individually, and commit when you're done.
 
-Crucially, the diff comes from your local git—not from the AI vendor and not from a JavaScript approximation. You get absolute, independent verification of what the agent or script actually did.
+The diff comes from your local git, not from the AI vendor and not from a JavaScript approximation. You get independent verification of what the agent or script actually did.
 
-Python 3.9+ and git are the only requirements. The front-end libraries (CodeMirror 6, marked, DOMPurify, Turndown, xterm.js) are vendored and served locally, so Draftwatch works completely offline and binds to localhost only.
+Why this vibe-coded app? I designed it to be an Integrated Development Environment (IDE) for writers. Most IDEs show `git diff` at the line level, which is appropriate for coders (where each statement is generally its own line) but terrible for writers, who work at the paragraph level. This IDE is built around displaying `git diff --word-diff=porcelain`, which lets writers see the specific words being edited. Even the IDEs that do show this make it harder for writers to track edits, and they carry coding features and visual baggage that writers won’t need.
+
+Python 3.9+ and git are the only requirements. If you are a writer, AI itself can help you install these widely used tools. The front-end libraries (CodeMirror 6, marked, DOMPurify, Turndown, xterm.js) are vendored and served locally, so Draftwatch works completely offline and binds to your local computer.
 
 ## Install
 
@@ -59,36 +65,17 @@ Or to start with a specific file:
 draftwatch draft.md
 ```
 
-You can also run it outside any git repository. Draftwatch starts in
-**write-only mode** — the editor, preview, and saving all work, but the review
-loop (diffs, revert, commit) is off because there's no git to compare against.
-The right panel offers a one-click **initialize git here** to turn the folder
-into a repo and switch on the full review loop.
+You can also run it outside any git repository. Draftwatch starts in **write-only mode**: the editor, preview, and saving all work, but the review loop (diffs, revert, commit) is off because there's no git to compare against. The right panel offers a one-click **initialize git here** to turn the folder into a repo and switch on the full review loop.
 
-Starting a second instance while one is already running just works: if the
-default port is busy, Draftwatch picks a free one and prints the URL.
+Starting a second instance while one is already running just works: if the default port is busy, Draftwatch picks a free one and prints the URL.
 
 Draftwatch opens a two-panel review window: your source on the left (a real editor with markdown highlighting, search, and a live preview), the diff against your baseline on the right. Review the changes, revert the ones you don't want, apply, then commit. Committing advances the baseline, so the next agent pass starts clean.
 
 Start without a file (`draftwatch`) to pick one in the window.
 
-### Options
-
-```
-draftwatch [target] [--port 8787] [--no-open] [--no-terminal] [--app | --no-app]
-```
-
-- `target`: file to watch. Optional; omit it to pick one in the UI.
-- `--port`: default `8787`. If omitted and the default is busy, Draftwatch
-  picks a free port automatically; pass `--port` to pin an exact one (it then
-  fails loudly if that port is taken).
-- `--no-open`: don't auto-open a window (useful headless or over SSH).
-- `--no-terminal`: disable the embedded terminal panel entirely (its routes are removed from the server, not just hidden in the UI).
-- `--app` / `--no-app`: force or disable the native window. It is on by default when pywebview is installed and falls back to the browser otherwise.
-
 ## The terminal panel
 
-Click **terminal** in the toolbar to open a third panel running a real shell in your repo (macOS/Linux). Launch `claude`, `codex`, or any command there: when the agent edits the file you're watching, the diff panel lights up live — prompt on the right, review in the middle, write on the left. **hide** collapses the panel and leaves the shell running (an agent mid-task keeps working); **end session** kills the shell and everything it started. No snapshots are taken when you run commands — edits accumulate against whatever baseline you've selected, and you review them on your schedule. On Windows the panel is unavailable and Draftwatch simply runs without it.
+Click **terminal** in the toolbar to open a third panel running a real shell in your repo (macOS/Linux). Launch `claude`, `codex`, or any command there: when the agent edits the file you're watching, the diff panel lights up live: prompt on the right, review in the middle, write on the left. **hide** collapses the panel and leaves the shell running (an agent mid-task keeps working); **end session** kills the shell and everything it started. No snapshots are taken when you run commands; edits accumulate against whatever baseline you've selected, and you review them on your schedule. On Windows the panel is unavailable and Draftwatch runs without it.
 
 ## Features
 
@@ -101,26 +88,23 @@ Click **terminal** in the toolbar to open a third panel running a real shell in
 - Embedded terminal panel (macOS/Linux): run your agent next to the diff without leaving the window.
 - Resizable panels: drag the dividers to change the split (double-click to reset).
 
-## Security
-
-Draftwatch binds `127.0.0.1` only — there is deliberately no option to bind another interface, so the tool is never exposed on your network. Every request carries a per-session token, the Host and Origin headers are validated to defeat DNS-rebinding, and the markdown preview is sanitized with DOMPurify before rendering. The tool never talks to any LLM.
-
-The terminal panel is a real shell, so it gets extra care: its input routes accept the session token **only** as a request header (keystrokes never appear in URLs, browser history, or logs), the server pipes bytes to the PTY without ever parsing them, ending a session kills the shell's whole process group, and no shell outlives Draftwatch. `--no-terminal` removes the feature from the server entirely.
-
-## Tests
+### Options
 
-```bash
-python3 testing/test_reconstruct.py   # reconstruction invariants
-python3 testing/test_acceptance.py    # end-to-end server tests
+```
+draftwatch [target] [--port 8787] [--no-open] [--no-terminal] [--app | --no-app]
 ```
 
-## Development
-
-The front-end libraries are vendored into `draftwatch/assets/` and committed, so end users never need Node. To rebuild them: `npm install && npm run build:vendor`.
+- `target`: file to watch. Optional; omit it to pick one in the UI.
+- `--port`: default `8787`. If omitted and the default is busy, Draftwatch
+  picks a free port automatically; pass `--port` to pin an exact one (it then
+  fails loudly if that port is taken).
+- `--no-open`: don't auto-open a window (useful headless or over SSH).
+- `--no-terminal`: disable the embedded terminal panel entirely (its routes are removed from the server, not just hidden in the UI).
+- `--app` / `--no-app`: force or disable the native window. It is on by default when pywebview is installed and falls back to the browser otherwise.
 
 ## Author
 
-Built by Mike Konczal. Vibe-coded with Fable 5.
+Built by Mike Konczal. You can find out more about me at my webpage [here](https://www.mikekonczal.com/). Vibe-coded with Fable 5.
 
 ## License
 

draftwatch-0.2.2/README.md

@@ -0,0 +1,89 @@
+# Draftwatch
+
+![Draftwatch reviewing an agent's edits: your working text on the left in a real editor, the word diff against your baseline on the right. Click any change to revert it.](https://raw.githubusercontent.com/mtkonczal/Draftwatch/main/assets/draftwatch_screenshot.png)
+
+It’s difficult for writers to have AI act as an editor, because it’s never clear exactly what it changed. You can’t trust eyeballing it, but making the changes manually yourself means you don’t save much time. So you either ignore this potentially powerful writing helper, or you trust it at the risk that it does far more than you asked.
+
+Enter Draftwatch. Draftwatch is a lightweight editing tool for writers. You can use it to create and format new Markdown documents from scratch, but its more powerful use is reviewing an AI agent's edits to your writing, down to the exact word. Changes are managed by git, the way a developer reviews changes to their code, but formatted for writers who need to see each exact word change to feel comfortable.
+
+When reviewing AI edits, instead of guessing what an LLM changed in your document, Draftwatch shows you the exact, git-backed word-diff. You can step through, keep or revert each change individually, and commit when you're done.
+
+The diff comes from your local git, not from the AI vendor and not from a JavaScript approximation. You get independent verification of what the agent or script actually did.
+
+Why this vibe-coded app? I designed it to be an Integrated Development Environment (IDE) for writers. Most IDEs show `git diff` at the line level, which is appropriate for coders (where each statement is generally its own line) but terrible for writers, who work at the paragraph level. This IDE is built around displaying `git diff --word-diff=porcelain`, which lets writers see the specific words being edited. Even the IDEs that do show this make it harder for writers to track edits, and they carry coding features and visual baggage that writers won’t need.
+
+Python 3.9+ and git are the only requirements. If you are a writer, AI itself can help you install these widely used tools. The front-end libraries (CodeMirror 6, marked, DOMPurify, Turndown, xterm.js) are vendored and served locally, so Draftwatch works completely offline and binds to your local computer.
+
+## Install
+
+Draftwatch is available on PyPI. You can install or run it using your preferred Python package manager:
+
+```bash
+# pipx
+pipx install draftwatch
+
+# uv 
+uv tool install draftwatch
+
+# standard pip
+pip install draftwatch
+```
+
+## Usage
+
+Run it from inside a git repository you write in:
+
+```bash
+draftwatch
+```
+
+Or to start with a specific file:
+
+```bash
+draftwatch draft.md
+```
+
+You can also run it outside any git repository. Draftwatch starts in **write-only mode**: the editor, preview, and saving all work, but the review loop (diffs, revert, commit) is off because there's no git to compare against. The right panel offers a one-click **initialize git here** to turn the folder into a repo and switch on the full review loop.
+
+Starting a second instance while one is already running just works: if the default port is busy, Draftwatch picks a free one and prints the URL.
+
+Draftwatch opens a two-panel review window: your source on the left (a real editor with markdown highlighting, search, and a live preview), the diff against your baseline on the right. Review the changes, revert the ones you don't want, apply, then commit. Committing advances the baseline, so the next agent pass starts clean.
+
+Start without a file (`draftwatch`) to pick one in the window.
+
+## The terminal panel
+
+Click **terminal** in the toolbar to open a third panel running a real shell in your repo (macOS/Linux). Launch `claude`, `codex`, or any command there: when the agent edits the file you're watching, the diff panel lights up live: prompt on the right, review in the middle, write on the left. **hide** collapses the panel and leaves the shell running (an agent mid-task keeps working); **end session** kills the shell and everything it started. No snapshots are taken when you run commands; edits accumulate against whatever baseline you've selected, and you review them on your schedule. On Windows the panel is unavailable and Draftwatch runs without it.
+
+## Features
+
+- Real git word-diffs, so what you see is exactly what git sees.
+- Keep or revert changes one hunk at a time, or all at once, then commit from the UI.
+- Switchable baseline: last push, HEAD, or an earlier commit.
+- Jump between changes or collapse to a changes-only view for long documents.
+- Editable markdown preview alongside the raw source.
+- You and the agent can both edit; your unsaved work is never clobbered when the file changes on disk.
+- Embedded terminal panel (macOS/Linux): run your agent next to the diff without leaving the window.
+- Resizable panels: drag the dividers to change the split (double-click to reset).
+
+### Options
+
+```
+draftwatch [target] [--port 8787] [--no-open] [--no-terminal] [--app | --no-app]
+```
+
+- `target`: file to watch. Optional; omit it to pick one in the UI.
+- `--port`: default `8787`. If omitted and the default is busy, Draftwatch
+  picks a free port automatically; pass `--port` to pin an exact one (it then
+  fails loudly if that port is taken).
+- `--no-open`: don't auto-open a window (useful headless or over SSH).
+- `--no-terminal`: disable the embedded terminal panel entirely (its routes are removed from the server, not just hidden in the UI).
+- `--app` / `--no-app`: force or disable the native window. It is on by default when pywebview is installed and falls back to the browser otherwise.
+
+## Author
+
+Built by Mike Konczal. You can find out more about me at my webpage [here](https://www.mikekonczal.com/). Vibe-coded with Fable 5.
+
+## License
+
+MIT. See `LICENSE`.

{draftwatch-0.2.0 → draftwatch-0.2.2}/draftwatch/app.py

@@ -40,8 +40,8 @@ TERM_SUPPORTED = _term is not None
 # Single source of truth for the version and the date of the latest release.
 # __init__.py re-exports __version__; the About panel shows both (injected into
 # the served page from these constants).
-__version__ = "0.2.0"
-RELEASE_DATE = "2026-07-06"
+__version__ = "0.2.2"
+RELEASE_DATE = "2026-09-23"
 
 # Preferred port. When --port is not given, Draftwatch tries this first and
 # falls back to a free port if it is busy (so a second instance can start while
@@ -145,6 +145,21 @@ def push_ref(root):
     return None, None, None
 
 
+def verify_commit_ref(root, ref):
+    """True only if `ref` names an existing commit object in `root`.
+
+    Two guards: reject anything not a plain string or beginning with '-' (so a
+    ref can never be parsed by a later `git diff <ref>` as an option — e.g.
+    `--output=FILE` would make git write to an arbitrary path), then confirm the
+    ref actually resolves to a commit with `rev-parse --verify`. The client only
+    ever sends full SHAs from the commit dropdown; this hardens the API against a
+    hand-crafted request (which still needs the session token to arrive)."""
+    if not isinstance(ref, str) or not ref or ref.startswith("-"):
+        return False
+    rc, _, _ = run_git(["rev-parse", "--verify", "--quiet", ref + "^{commit}"], root)
+    return rc == 0
+
+
 def git_diff_text(root, baseline, relpath, abspath):
     """Run the appropriate word-diff command. Returns diff text ('' if no diff).
 
@@ -229,6 +244,53 @@ def resolve_new_file(root, path):
     return cand
 
 
+# Local images the preview may load: extension -> MIME type. The image route
+# serves only these, only from inside the repo root, and only up to the size
+# cap, so it can't be used to read arbitrary files (source, .env, keys).
+IMAGE_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+}
+MAX_IMAGE_BYTES = 25 * 1024 * 1024
+
+
+def resolve_image(root, relpath, src):
+    """Resolve an <img src> from the markdown to (abspath, mime), or raise ValueError.
+
+    `src` is the raw attribute value, resolved relative to the open file's
+    directory (the repo root when no file is open), the way a markdown renderer
+    on disk would. URLs, absolute paths, and anything resolving outside the repo
+    or to a non-image type are refused.
+    """
+    from urllib.parse import unquote
+    s = (src or "").split("#", 1)[0].split("?", 1)[0].strip()
+    s = unquote(s)
+    if not s:
+        raise ValueError("no image path given")
+    if ":" in s.split("/", 1)[0] or s.startswith("/") or os.path.isabs(s):
+        raise ValueError("only relative image paths are served")
+    base = os.path.join(root, os.path.dirname(relpath)) if relpath else root
+    cand = os.path.realpath(os.path.join(base, s))
+    root_prefix = root.rstrip(os.sep) + os.sep
+    if not cand.startswith(root_prefix):
+        raise ValueError("refusing an image outside the repository")
+    mime = IMAGE_TYPES.get(os.path.splitext(cand)[1].lower())
+    if mime is None:
+        raise ValueError("not an image type the preview serves")
+    if not os.path.isfile(cand):
+        raise ValueError("image not found")
+    if os.path.getsize(cand) > MAX_IMAGE_BYTES:
+        raise ValueError("image too large")
+    return cand, mime
+
+
 def list_repo_files(root, has_repo=True, limit=5000):
     """Files for the picker. In a git repo: tracked + non-ignored untracked,
     sorted, deduped. In write-only mode (no repo), fall back to a filesystem
@@ -860,6 +922,31 @@ class Handler(BaseHTTPRequestHandler):
         self.send_header("Content-Type", ctype)
         self.send_header("Content-Length", str(len(body)))
         self.send_header("Cache-Control", "no-store")
+        # Defense-in-depth headers. The preview already runs agent-authored
+        # markdown through DOMPurify; these add a second layer and, crucially,
+        # keep the session token from leaking off-origin:
+        #   Referrer-Policy   — the token rides in the launch URL; never send a
+        #                       Referer carrying it to any resource the page loads.
+        #   CSP               — scripts/styles/fetch are same-origin only, so a
+        #                       sanitizer bypass still can't call out or exfiltrate
+        #                       (connect-src 'self'). base/form/frame are locked
+        #                       down. img-src stays permissive (data:/https:) so a
+        #                       writer's legitimate external images still render;
+        #                       with connect-src+Referrer-Policy above, a stray
+        #                       image beacon carries no token and no document data.
+        #                       blob: is for local images, fetched with the token
+        #                       from /api/image and shown via object URLs.
+        #   nosniff           — don't let a response be reinterpreted as another type.
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header(
+            "Content-Security-Policy",
+            "default-src 'self'; "
+            "script-src 'self' 'unsafe-inline'; "
+            "style-src 'self' 'unsafe-inline'; "
+            "img-src 'self' data: blob: https:; "
+            "connect-src 'self'; "
+            "base-uri 'none'; form-action 'none'; frame-ancestors 'none'")
         self.end_headers()
         try:
             self.wfile.write(body)
@@ -901,6 +988,8 @@ class Handler(BaseHTTPRequestHandler):
             self._api_baselines()
         elif path == "/api/files":
             self._api_files()
+        elif path == "/api/image":
+            self._api_image()
         else:
             self._send(404, "not found", "text/plain")
 
@@ -993,6 +1082,22 @@ class Handler(BaseHTTPRequestHandler):
         self._json({"files": list_repo_files(st.root, has_repo),
                     "current": current, "repo": has_repo})
 
+    def _api_image(self):
+        """A local image referenced by the open file, for the preview. Token-gated
+        like the rest of /api/* (the client fetches it with the header and shows
+        it as a blob: URL), so file contents never load without the session."""
+        st = self.state
+        with st.lock:
+            relpath = st.relpath
+        vals = self._query().get("src")
+        try:
+            abspath, mime = resolve_image(st.root, relpath, vals[0] if vals else "")
+            with open(abspath, "rb") as fh:
+                data = fh.read()
+        except (ValueError, OSError) as e:
+            return self._send(404, str(e), "text/plain")
+        self._send(200, data, mime)
+
     # ---- POST ----
     def do_POST(self):
         path = self.path.split("?", 1)[0]
@@ -1170,6 +1275,8 @@ class Handler(BaseHTTPRequestHandler):
                 ref = body.get("ref")
                 if not ref:
                     return self._json({"error": "missing ref"}, 400)
+                if not verify_commit_ref(st.root, ref):
+                    return self._json({"error": "invalid or unknown commit ref"}, 400)
                 label = body.get("label", ref)
                 with st.lock:
                     st.baseline = {"kind": "commit", "ref": ref, "label": label}
@@ -1352,6 +1459,7 @@ INDEX_HTML = r"""<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Draftwatch</title>
 <script src="/static/codemirror.js"></script>
@@ -1639,8 +1747,13 @@ INDEX_HTML = r"""<!DOCTYPE html>
   .panel.term h2 button {
     text-transform: none; letter-spacing: normal; font-weight: 400;
   }
-  #term-host { flex: 1; min-height: 0; padding: 6px 2px 2px 8px; }
-  #term-host .terminal { height: 100%; }
+  /* Padding lives on the xterm element, not #term-host: the fit addon sizes
+     the terminal from the parent's computed width/height (which, with the
+     global border-box rule, includes the parent's padding) minus the
+     terminal element's own padding. Padding the host makes fit() run one
+     column wide, pushing text under the viewport scrollbar. */
+  #term-host { flex: 1; min-height: 0; }
+  #term-host .terminal { height: 100%; padding: 6px 2px 2px 8px; }
   .panel h2 {
     margin: 0;
     padding: 6px 12px;
@@ -1681,30 +1794,42 @@ INDEX_HTML = r"""<!DOCTYPE html>
     background: rgba(127, 127, 127, .28);
   }
   #editor-host .cm-placeholder { color: var(--muted); font-style: italic; }
-  /* CM search panel, themed with the app variables (light/dark for free) */
-  .cm-panels {
-    background: var(--panel) !important;
-    color: var(--text) !important;
-    border-color: var(--border) !important;
+  /* CM search panel, themed with the app variables (light/dark for free).
+     Scoped under #editor-host on purpose: CodeMirror's base theme injects
+     two-class rules (e.g. `.ͼ2 .cm-textfield`, `.ͼ2 .cm-button`) that outrank a
+     bare `.cm-panels input`, and since no dark theme is registered with CM it
+     always applies its LIGHT palette (white input, pale gradient buttons, 70%
+     font). Unscoped, that left near-white dark-mode text on a white field. */
+  #editor-host .cm-panels {
+    background: var(--panel);
+    color: var(--text);
+    border-color: var(--border);
   }
-  .cm-panels input, .cm-panels button, .cm-panels label {
+  #editor-host .cm-panels input, #editor-host .cm-panels button, #editor-host .cm-panels label {
     font-family: var(--mono);
     font-size: 12px;
     color: var(--text);
   }
-  .cm-panels input {
+  #editor-host .cm-panels input[type="checkbox"] { accent-color: var(--accent); }
+  #editor-host .cm-panels .cm-textfield {
     background: var(--bg);
     border: 1px solid var(--border);
     border-radius: 4px;
   }
-  .cm-panels button {
+  #editor-host .cm-panels .cm-textfield:focus { outline: none; border-color: var(--accent); }
+  #editor-host .cm-panels .cm-button {
     background: var(--bg);
-    border: 1px solid var(--border) !important;
+    background-image: none;
+    border: 1px solid var(--border);
     border-radius: 4px;
     cursor: pointer;
   }
-  .cm-searchMatch { background: var(--warn-bg); outline: 1px solid var(--warn-border); }
-  .cm-searchMatch-selected { background: var(--warn-border); }
+  #editor-host .cm-panels .cm-button:hover { border-color: var(--accent); }
+  #editor-host .cm-panels .cm-button:active { background-image: none; }
+  #editor-host .cm-searchMatch { background: var(--warn-bg); outline: 1px solid var(--warn-border); }
+  #editor-host .cm-searchMatch-selected { background: var(--warn-border); }
+  /* highlightSelectionMatches: CM's default is a bright translucent green */
+  #editor-host .cm-selectionMatch { background: rgba(127, 127, 127, .22); }
 
   /* rendered markdown preview: reading typography, sanitized content only */
   #preview {
@@ -1744,6 +1869,8 @@ INDEX_HTML = r"""<!DOCTYPE html>
     color: var(--muted);
   }
   #preview img { max-width: 100%; }
+  /* a local image the server could not serve: the alt text shows in its place */
+  #preview img.img-missing { outline: 1px dashed var(--del-fg); outline-offset: 2px; color: var(--muted); }
   #preview hr { border: none; border-top: 1px solid var(--border); }
   #preview table { border-collapse: collapse; }
   #preview th, #preview td { border: 1px solid var(--border); padding: 4px 9px; }
@@ -2083,9 +2210,21 @@ INDEX_HTML = r"""<!DOCTYPE html>
   }
 
   // ---- session token (from the URL draftwatch printed/opened) ----
+  // Read it once, then keep it in sessionStorage and strip it out of the
+  // visible URL. This keeps the token out of the address bar, browser history,
+  // and any screen-share, while a reload still authenticates (sessionStorage
+  // survives reloads within the tab). Note: this does NOT remove the token from
+  // the browser process's command line on a shared host — see the README
+  // security notes; prefer the native window (--app) there.
   var TOKEN = (function () {
+    var t = "";
     var m = /(?:\?|&)t=([^&]+)/.exec(window.location.search);
-    return m ? decodeURIComponent(m[1]) : "";
+    if (m) t = decodeURIComponent(m[1]);
+    try {
+      if (t) sessionStorage.setItem("draftwatch-token", t);
+      else t = sessionStorage.getItem("draftwatch-token") || "";
+    } catch (e) {}
+    return t;
   })();
 
   // ---- launch surface (native window vs browser) ----
@@ -2096,6 +2235,17 @@ INDEX_HTML = r"""<!DOCTYPE html>
   var APP_FALLBACK = /(?:\?|&)appfallback=1(?:&|$)/.test(window.location.search);
   if (APP_MODE) document.body.classList.add("app-mode");
 
+  // Now that the token and launch flags have been read, drop `t` from the
+  // address bar (other params are preserved). The token still lives in the JS
+  // var and sessionStorage, so requests and reloads keep working.
+  try {
+    var _u = new URL(window.location.href);
+    if (_u.searchParams.has("t")) {
+      _u.searchParams.delete("t");
+      window.history.replaceState({}, "", _u.pathname + _u.search + _u.hash);
+    }
+  } catch (e) {}
+
   // ---- server notification of client state (turn-based contract) ----
   function postJSON(url, obj, cb) {
     fetch(url, {
@@ -2864,6 +3014,61 @@ INDEX_HTML = r"""<!DOCTYPE html>
     strongDelimiter: "**",
     linkStyle: "inlined"
   });
+
+  // Local images (e.g. ![](figs/chart.png)). A relative src would resolve to a
+  // bare path on this server and 404, so the sanitizer moves it to data-md-src
+  // (no request fires from the markup), and loadLocalImages fetches it through
+  // the token-gated /api/image route and shows it as a blob: URL. data-md-src
+  // keeps the markdown's own path, which Turndown writes back on preview edits
+  // (never the blob: URL; its default rule would also drop a src-less image).
+  function isLocalSrc(s) {
+    return !!s && !/^([a-z][a-z0-9+.-]*:|\/|#)/i.test(s);
+  }
+  DOMPurify.addHook("afterSanitizeAttributes", function (node) {
+    if (node.nodeName !== "IMG") return;
+    var src = node.getAttribute("src");
+    if (!isLocalSrc(src)) return;
+    node.setAttribute("data-md-src", src);
+    node.removeAttribute("src");
+  });
+  TURN.addRule("localImage", {
+    filter: function (node) {
+      return node.nodeName === "IMG" && node.hasAttribute("data-md-src");
+    },
+    replacement: function (content, node) {
+      var clean = function (a) { return (a || "").replace(/(\n+\s*)+/g, "\n"); };
+      var title = clean(node.getAttribute("title"));
+      return "![" + clean(node.getAttribute("alt")) + "](" +
+        node.getAttribute("data-md-src") + (title ? ' "' + title + '"' : "") + ")";
+    }
+  });
+  var imageCache = {};   // "<file>|<src>" -> Promise of a blob: URL, or null
+  function clearImageCache() {
+    Object.keys(imageCache).forEach(function (k) {
+      imageCache[k].then(function (u) { if (u) URL.revokeObjectURL(u); });
+    });
+    imageCache = {};
+  }
+  function loadLocalImages(root) {
+    root.querySelectorAll("img[data-md-src]").forEach(function (img) {
+      var src = img.getAttribute("data-md-src");
+      var key = (currentFile || "") + "|" + src;
+      if (!imageCache[key]) {
+        imageCache[key] = fetch("/api/image?src=" + encodeURIComponent(src),
+                                { headers: { "X-Draftwatch-Token": TOKEN } })
+          .then(function (r) { return r.ok ? r.blob() : null; })
+          .then(function (b) { return b ? URL.createObjectURL(b) : null; })
+          .catch(function () { return null; });
+        // don't cache a miss: the image may be added to disk later
+        imageCache[key].then(function (u) { if (!u) delete imageCache[key]; });
+      }
+      imageCache[key].then(function (u) {
+        if (u) { img.src = u; img.classList.remove("img-missing"); }
+        else img.classList.add("img-missing");
+      });
+    });
+  }
+
   function renderPreview() {
     var out = "";
     try {
@@ -2876,6 +3081,7 @@ INDEX_HTML = r"""<!DOCTYPE html>
     // (innerHTML assignment does not fire 'input', but keep the intent explicit)
     $("preview").innerHTML = out ||
       '<p class="empty">nothing to preview</p>';
+    loadLocalImages($("preview"));
   }
 
   // Convert the edited rendered HTML back to markdown and push it into the
@@ -2906,7 +3112,8 @@ INDEX_HTML = r"""<!DOCTYPE html>
     $("preview").setAttribute("contenteditable", on ? "true" : "false");
     // the format buttons + save stay available in preview — you can write here too
     $("view-toggle").textContent = on ? "source" : "preview";
-    if (on) renderPreview();
+    // re-read local images each time preview opens, so a regenerated chart shows
+    if (on) { clearImageCache(); renderPreview(); }
   }
   $("view-toggle").addEventListener("click", function () { setPreviewMode(!previewMode); });
 

{draftwatch-0.2.0 → draftwatch-0.2.2}/draftwatch.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwatch
-Version: 0.2.0
+Version: 0.2.2
 Summary: Review an AI agent's edits to your writing files as a real git word-diff — keep or revert changes hunk by hunk, then commit.
 Author: Mike Konczal
 License: MIT
@@ -22,13 +22,19 @@ Dynamic: license-file
 
 # Draftwatch
 
-Draftwatch is a lightweight IDE for writers. You can use it to create and format new Markdown documents from scratch, or use it to review an AI agent's edits to your writing exactly the way a developer reviews a pull request.
+![Draftwatch reviewing an agent's edits: your working text on the left in a real editor, the word diff against your baseline on the right. Click any change to revert it.](https://raw.githubusercontent.com/mtkonczal/Draftwatch/main/assets/draftwatch_screenshot.png)
+
+It’s difficult for writers to have AI act as an editor, because it’s never clear exactly what it changed. You can’t trust eyeballing it, but making the changes manually yourself means you don’t save much time. So you either ignore this potentially powerful writing helper, or you trust it at the risk that it does far more than you asked.
+
+Enter Draftwatch. Draftwatch is a lightweight editing tool for writers. You can use it to create and format new Markdown documents from scratch, but its more powerful use is reviewing an AI agent's edits to your writing, down to the exact word. Changes are managed by git, the way a developer reviews changes to their code, but formatted for writers who need to see each exact word change to feel comfortable.
 
 When reviewing AI edits, instead of guessing what an LLM changed in your document, Draftwatch shows you the exact, git-backed word-diff. You can step through, keep or revert each change individually, and commit when you're done.
 
-Crucially, the diff comes from your local git—not from the AI vendor and not from a JavaScript approximation. You get absolute, independent verification of what the agent or script actually did.
+The diff comes from your local git, not from the AI vendor and not from a JavaScript approximation. You get independent verification of what the agent or script actually did.
 
-Python 3.9+ and git are the only requirements. The front-end libraries (CodeMirror 6, marked, DOMPurify, Turndown, xterm.js) are vendored and served locally, so Draftwatch works completely offline and binds to localhost only.
+Why this vibe-coded app? I designed it to be an Integrated Development Environment (IDE) for writers. Most IDEs show `git diff` at the line level, which is appropriate for coders (where each statement is generally its own line) but terrible for writers, who work at the paragraph level. This IDE is built around displaying `git diff --word-diff=porcelain`, which lets writers see the specific words being edited. Even the IDEs that do show this make it harder for writers to track edits, and they carry coding features and visual baggage that writers won’t need.
+
+Python 3.9+ and git are the only requirements. If you are a writer, AI itself can help you install these widely used tools. The front-end libraries (CodeMirror 6, marked, DOMPurify, Turndown, xterm.js) are vendored and served locally, so Draftwatch works completely offline and binds to your local computer.
 
 ## Install
 
@@ -59,36 +65,17 @@ Or to start with a specific file:
 draftwatch draft.md
 ```
 
-You can also run it outside any git repository. Draftwatch starts in
-**write-only mode** — the editor, preview, and saving all work, but the review
-loop (diffs, revert, commit) is off because there's no git to compare against.
-The right panel offers a one-click **initialize git here** to turn the folder
-into a repo and switch on the full review loop.
+You can also run it outside any git repository. Draftwatch starts in **write-only mode**: the editor, preview, and saving all work, but the review loop (diffs, revert, commit) is off because there's no git to compare against. The right panel offers a one-click **initialize git here** to turn the folder into a repo and switch on the full review loop.
 
-Starting a second instance while one is already running just works: if the
-default port is busy, Draftwatch picks a free one and prints the URL.
+Starting a second instance while one is already running just works: if the default port is busy, Draftwatch picks a free one and prints the URL.
 
 Draftwatch opens a two-panel review window: your source on the left (a real editor with markdown highlighting, search, and a live preview), the diff against your baseline on the right. Review the changes, revert the ones you don't want, apply, then commit. Committing advances the baseline, so the next agent pass starts clean.
 
 Start without a file (`draftwatch`) to pick one in the window.
 
-### Options
-
-```
-draftwatch [target] [--port 8787] [--no-open] [--no-terminal] [--app | --no-app]
-```
-
-- `target`: file to watch. Optional; omit it to pick one in the UI.
-- `--port`: default `8787`. If omitted and the default is busy, Draftwatch
-  picks a free port automatically; pass `--port` to pin an exact one (it then
-  fails loudly if that port is taken).
-- `--no-open`: don't auto-open a window (useful headless or over SSH).
-- `--no-terminal`: disable the embedded terminal panel entirely (its routes are removed from the server, not just hidden in the UI).
-- `--app` / `--no-app`: force or disable the native window. It is on by default when pywebview is installed and falls back to the browser otherwise.
-
 ## The terminal panel
 
-Click **terminal** in the toolbar to open a third panel running a real shell in your repo (macOS/Linux). Launch `claude`, `codex`, or any command there: when the agent edits the file you're watching, the diff panel lights up live — prompt on the right, review in the middle, write on the left. **hide** collapses the panel and leaves the shell running (an agent mid-task keeps working); **end session** kills the shell and everything it started. No snapshots are taken when you run commands — edits accumulate against whatever baseline you've selected, and you review them on your schedule. On Windows the panel is unavailable and Draftwatch simply runs without it.
+Click **terminal** in the toolbar to open a third panel running a real shell in your repo (macOS/Linux). Launch `claude`, `codex`, or any command there: when the agent edits the file you're watching, the diff panel lights up live: prompt on the right, review in the middle, write on the left. **hide** collapses the panel and leaves the shell running (an agent mid-task keeps working); **end session** kills the shell and everything it started. No snapshots are taken when you run commands; edits accumulate against whatever baseline you've selected, and you review them on your schedule. On Windows the panel is unavailable and Draftwatch runs without it.
 
 ## Features
 
@@ -101,26 +88,23 @@ Click **terminal** in the toolbar to open a third panel running a real shell in
 - Embedded terminal panel (macOS/Linux): run your agent next to the diff without leaving the window.
 - Resizable panels: drag the dividers to change the split (double-click to reset).
 
-## Security
-
-Draftwatch binds `127.0.0.1` only — there is deliberately no option to bind another interface, so the tool is never exposed on your network. Every request carries a per-session token, the Host and Origin headers are validated to defeat DNS-rebinding, and the markdown preview is sanitized with DOMPurify before rendering. The tool never talks to any LLM.
-
-The terminal panel is a real shell, so it gets extra care: its input routes accept the session token **only** as a request header (keystrokes never appear in URLs, browser history, or logs), the server pipes bytes to the PTY without ever parsing them, ending a session kills the shell's whole process group, and no shell outlives Draftwatch. `--no-terminal` removes the feature from the server entirely.
-
-## Tests
+### Options
 
-```bash
-python3 testing/test_reconstruct.py   # reconstruction invariants
-python3 testing/test_acceptance.py    # end-to-end server tests
+```
+draftwatch [target] [--port 8787] [--no-open] [--no-terminal] [--app | --no-app]
 ```
 
-## Development
-
-The front-end libraries are vendored into `draftwatch/assets/` and committed, so end users never need Node. To rebuild them: `npm install && npm run build:vendor`.
+- `target`: file to watch. Optional; omit it to pick one in the UI.
+- `--port`: default `8787`. If omitted and the default is busy, Draftwatch
+  picks a free port automatically; pass `--port` to pin an exact one (it then
+  fails loudly if that port is taken).
+- `--no-open`: don't auto-open a window (useful headless or over SSH).
+- `--no-terminal`: disable the embedded terminal panel entirely (its routes are removed from the server, not just hidden in the UI).
+- `--app` / `--no-app`: force or disable the native window. It is on by default when pywebview is installed and falls back to the browser otherwise.
 
 ## Author
 
-Built by Mike Konczal. Vibe-coded with Fable 5.
+Built by Mike Konczal. You can find out more about me at my webpage [here](https://www.mikekonczal.com/). Vibe-coded with Fable 5.
 
 ## License
 

{draftwatch-0.2.0 → draftwatch-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "draftwatch"
-version = "0.2.0"
+version = "0.2.2"
 description = "Review an AI agent's edits to your writing files as a real git word-diff — keep or revert changes hunk by hunk, then commit."
 readme = "README.md"
 requires-python = ">=3.9"

draftwatch-0.2.0/README.md

@@ -1,105 +0,0 @@
-# Draftwatch
-
-Draftwatch is a lightweight IDE for writers. You can use it to create and format new Markdown documents from scratch, or use it to review an AI agent's edits to your writing exactly the way a developer reviews a pull request.
-
-When reviewing AI edits, instead of guessing what an LLM changed in your document, Draftwatch shows you the exact, git-backed word-diff. You can step through, keep or revert each change individually, and commit when you're done.
-
-Crucially, the diff comes from your local git—not from the AI vendor and not from a JavaScript approximation. You get absolute, independent verification of what the agent or script actually did.
-
-Python 3.9+ and git are the only requirements. The front-end libraries (CodeMirror 6, marked, DOMPurify, Turndown, xterm.js) are vendored and served locally, so Draftwatch works completely offline and binds to localhost only.
-
-## Install
-
-Draftwatch is available on PyPI. You can install or run it using your preferred Python package manager:
-
-```bash
-# pipx
-pipx install draftwatch
-
-# uv 
-uv tool install draftwatch
-
-# standard pip
-pip install draftwatch
-```
-
-## Usage
-
-Run it from inside a git repository you write in:
-
-```bash
-draftwatch
-```
-
-Or to start with a specific file:
-
-```bash
-draftwatch draft.md
-```
-
-You can also run it outside any git repository. Draftwatch starts in
-**write-only mode** — the editor, preview, and saving all work, but the review
-loop (diffs, revert, commit) is off because there's no git to compare against.
-The right panel offers a one-click **initialize git here** to turn the folder
-into a repo and switch on the full review loop.
-
-Starting a second instance while one is already running just works: if the
-default port is busy, Draftwatch picks a free one and prints the URL.
-
-Draftwatch opens a two-panel review window: your source on the left (a real editor with markdown highlighting, search, and a live preview), the diff against your baseline on the right. Review the changes, revert the ones you don't want, apply, then commit. Committing advances the baseline, so the next agent pass starts clean.
-
-Start without a file (`draftwatch`) to pick one in the window.
-
-### Options
-
-```
-draftwatch [target] [--port 8787] [--no-open] [--no-terminal] [--app | --no-app]
-```
-
-- `target`: file to watch. Optional; omit it to pick one in the UI.
-- `--port`: default `8787`. If omitted and the default is busy, Draftwatch
-  picks a free port automatically; pass `--port` to pin an exact one (it then
-  fails loudly if that port is taken).
-- `--no-open`: don't auto-open a window (useful headless or over SSH).
-- `--no-terminal`: disable the embedded terminal panel entirely (its routes are removed from the server, not just hidden in the UI).
-- `--app` / `--no-app`: force or disable the native window. It is on by default when pywebview is installed and falls back to the browser otherwise.
-
-## The terminal panel
-
-Click **terminal** in the toolbar to open a third panel running a real shell in your repo (macOS/Linux). Launch `claude`, `codex`, or any command there: when the agent edits the file you're watching, the diff panel lights up live — prompt on the right, review in the middle, write on the left. **hide** collapses the panel and leaves the shell running (an agent mid-task keeps working); **end session** kills the shell and everything it started. No snapshots are taken when you run commands — edits accumulate against whatever baseline you've selected, and you review them on your schedule. On Windows the panel is unavailable and Draftwatch simply runs without it.
-
-## Features
-
-- Real git word-diffs, so what you see is exactly what git sees.
-- Keep or revert changes one hunk at a time, or all at once, then commit from the UI.
-- Switchable baseline: last push, HEAD, or an earlier commit.
-- Jump between changes or collapse to a changes-only view for long documents.
-- Editable markdown preview alongside the raw source.
-- You and the agent can both edit; your unsaved work is never clobbered when the file changes on disk.
-- Embedded terminal panel (macOS/Linux): run your agent next to the diff without leaving the window.
-- Resizable panels: drag the dividers to change the split (double-click to reset).
-
-## Security
-
-Draftwatch binds `127.0.0.1` only — there is deliberately no option to bind another interface, so the tool is never exposed on your network. Every request carries a per-session token, the Host and Origin headers are validated to defeat DNS-rebinding, and the markdown preview is sanitized with DOMPurify before rendering. The tool never talks to any LLM.
-
-The terminal panel is a real shell, so it gets extra care: its input routes accept the session token **only** as a request header (keystrokes never appear in URLs, browser history, or logs), the server pipes bytes to the PTY without ever parsing them, ending a session kills the shell's whole process group, and no shell outlives Draftwatch. `--no-terminal` removes the feature from the server entirely.
-
-## Tests
-
-```bash
-python3 testing/test_reconstruct.py   # reconstruction invariants
-python3 testing/test_acceptance.py    # end-to-end server tests
-```
-
-## Development
-
-The front-end libraries are vendored into `draftwatch/assets/` and committed, so end users never need Node. To rebuild them: `npm install && npm run build:vendor`.
-
-## Author
-
-Built by Mike Konczal. Vibe-coded with Fable 5.
-
-## License
-
-MIT. See `LICENSE`.