ideadump 0.0.2__py3-none-any.whl

ideadump/__init__.py

@@ -0,0 +1,51 @@
+"""ideadump: a place to dump ideas, research them a little, and find them again.
+
+Capture an idea in the owner's own words, attach research notes (a light pass at
+capture, a deep one when it looks promising), tag and link ideas, and ask which ideas
+relate to a query or to a page describing recent work. Ideas live in a ``dol`` store,
+by default a local folder, optionally a checkout of a private git repository.
+
+>>> from ideadump import add, find
+>>> files = {}
+>>> _ = add("Offline speech to text on the phone", tags="audio", files=files)
+>>> find("speech recognition", files=files)["hits"][0]["tags"]
+['audio']
+
+The command line (``ideadump --help``) and the agent skill shipped in
+``ideadump/data/skills/ideadump`` drive the same verbs.
+"""
+
+from ideadump.base import IdeadumpError
+from ideadump.store import data_dir, text_files
+from ideadump.sync import sync, sync_init, sync_status
+from ideadump.tools import (
+    TOOLS,
+    add,
+    find,
+    link,
+    ls,
+    note,
+    reindex,
+    show,
+    update,
+    where,
+)
+
+__all__ = [
+    "IdeadumpError",
+    "TOOLS",
+    "add",
+    "data_dir",
+    "find",
+    "link",
+    "ls",
+    "note",
+    "reindex",
+    "show",
+    "sync",
+    "sync_init",
+    "sync_status",
+    "text_files",
+    "update",
+    "where",
+]

ideadump/__main__.py

@@ -0,0 +1,73 @@
+# PYTHON_ARGCOMPLETE_OK
+"""``ideadump`` on the command line: every verb of :data:`ideadump.tools.TOOLS`.
+
+    ideadump add "the owner's words, verbatim" --title "Short title" --tags "a, b" --source my-session
+    ideadump note <id> --file research.md --depth light
+    ideadump find "offline speech to text"          # or --file recent-work.md
+    ideadump ls --status promising
+    ideadump show <id>
+    ideadump sync
+
+``--json`` as the last argument prints the whole result instead of its text. Exit status is 0 on
+success and 1 on an error, whose message says what to do next.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import sys
+
+import cw
+
+from ideadump import tools
+from ideadump.base import IdeadumpError
+
+
+def _command(func):
+    func = tools.without(func)
+
+    @functools.wraps(func)
+    def command(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except IdeadumpError as error:
+            raise cw.CommandError(str(error)) from error
+
+    return command
+
+
+def _egress(as_json):
+    def egress(result, *, out, err):
+        if as_json or not isinstance(result, dict):
+            print(
+                json.dumps(result, indent=2, ensure_ascii=False, default=str), file=out
+            )
+        else:
+            print(result.get("text", ""), file=out)
+        return 0
+
+    return egress
+
+
+def main(argv=None):
+    """Run the command line. The ``ideadump`` console script."""
+    for stream in (sys.stdout, sys.stderr):
+        getattr(stream, "reconfigure", lambda **_: None)(errors="backslashreplace")
+    argv = list(sys.argv[1:] if argv is None else argv)
+    as_json = bool(argv) and argv[-1] == "--json"
+    if as_json:
+        argv = argv[:-1]
+    commands = {f.__name__.replace("_", "-"): _command(f) for f in tools.TOOLS}
+    code = cw.dispatch(
+        commands,
+        argv,
+        prog="ideadump",
+        convention=cw.MODERN,
+        egress=_egress(as_json),
+    )
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()

ideadump/base.py

@@ -0,0 +1,38 @@
+"""Errors and constants shared across ideadump.
+
+An idea is one folder in the store, ``ideas/<id>/``, holding its record
+(``idea.json``, the single source of truth), a rendered ``README.md`` that a person
+reads on GitHub or a phone, and its research notes under ``research/``. Nothing here
+depends on any other module.
+"""
+
+from __future__ import annotations
+
+APP_NAME = "ideadump"
+DATA_DIR_ENVVAR = "IDEADUMP_DATA_DIR"
+
+IDEAS_DIR = "ideas"
+RECORD_FILE = "idea.json"
+README_FILE = "README.md"
+RESEARCH_DIR = "research"
+
+#: Where an idea stands. ``new`` on capture; the owner (or an agent relaying the
+#: owner's words) moves it on. ``promising`` is the cue for a deeper research pass.
+STATUSES = ("new", "promising", "parked", "pursued", "dropped")
+
+#: How deep a research note went. ``light`` is the pass made at capture (minutes, a
+#: few sources); ``deep`` is a full ``do-research``-style report.
+DEPTHS = ("light", "deep")
+
+
+class IdeadumpError(Exception):
+    """An error whose message says what to do next."""
+
+
+def record_key(idea_id: str) -> str:
+    """The store key of an idea's record.
+
+    >>> record_key("2026-11-14-an-idea")
+    'ideas/2026-11-14-an-idea/idea.json'
+    """
+    return f"{IDEAS_DIR}/{idea_id}/{RECORD_FILE}"

ideadump/data/skills/ideadump/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ideadump
+description: Capture an idea the owner tells you, in their own words, research it a little (more if it looks promising), tag and link it, and find it again later, with the ideadump command. Use whenever the owner shares an idea unrelated to the current task or asks you to keep one ("I have an idea", "idea:", "jot this down", "dump this idea", "note this idea for later", "remind me of this idea"), asks about their ideas ("what ideas do I have about X", "list my ideas", "show the idea about Y", "research that idea deeper", "that one is promising", "park that idea"), or asks whether anything they have been working on relates to their ideas ("is any of my recent work related to my ideas", "anything in my ideas worth doing now"), typically during spare token budget. Ideas are stored in a local folder or a private git repository, never in the current project.
+license: MIT
+metadata:
+  audience: users
+---
+
+# ideadump: a place to dump ideas, and find them again
+
+The owner tells you an idea in passing, often in a session that has nothing to do with it, often dictated. Your job: keep it **in their words**, make it findable, give it a first look, and get out of the way. One command captures it; everything else is optional and cheap.
+
+**First, is it for the current task?** An idea about the work in front of you ("I have an idea: do X this way") is an instruction: act on it, do not dump it. Dump only ideas meant for later or for something else, or when the owner says to keep it.
+
+Ideas live in ideadump's data folder (`ideadump where`), never in the project you are working in. If that folder is a checkout of a private repository, `ideadump sync` pushes; otherwise it is local only, which is fine.
+
+## Capture (always)
+
+```bash
+ideadump add "<the owner's words, verbatim>" --title "<short title>" --summary "<your clean reading>" --tags "<tag>, <tag>" --source "<this session's name>"
+```
+
+- **Words verbatim**, dictation slips included. Never "fix" them in `words`; put your reading in `--summary`, and when you resolved a slip say so there ("'attic system' read as 'agentic system'"). If a slip changes the meaning and you cannot tell, ask one short question.
+- **Title**: five words or fewer, the thing itself ("Idea dump tool", not "An idea about ideas").
+- **Tags**: two to four, lowercase, reused from existing ones where they fit: `ideadump ls` shows the tags in use. Prefer the domain (`audio`, `fleet`, `writing`) and the kind (`tool`, `essay`, `research-question`, `business`).
+- Then `ideadump find "<title and summary>"` (the new idea is among the hits; ignore its own id): if an earlier idea is the same or close, `ideadump link <id> <other> --why "<one line>"` (or tell the owner it is a duplicate and ask whether to merge).
+- Reply to the owner in two lines at most: the id and title, and that a light look follows (or what it found).
+
+**In a session that must keep its context small** (a lookout or switchboard session, or the middle of an unrelated task): run the `add` yourself, then hand the light research to a subagent with the id and these instructions, and carry on with what you were doing.
+
+## Light research (at capture, a few minutes)
+
+Search with the field's generic terms, not the owner's sentences: their words stay in the store, and outside search services see only queries.
+
+Answer four questions, with sources, in a short Markdown note:
+
+1. **What is this called?** The standard name for the idea or its field, if there is one.
+2. **What exists already?** Prior art: tools, libraries, papers, products; one line each with a link. If you can search the owner's own packages and skills (in their fleet: `ir discover packages "<two phrasings>"`, `ir discover skills ...`), say what they already have.
+3. **What is the crux?** The one thing that would make it hard, or the one thing that makes it easy.
+4. **Verdict**: `promising`, `worth a deeper look`, `exists already (use X)`, or `park`, with one sentence of why.
+
+References Vancouver style (`[1]`, `[2]` with a REFERENCES list, `[name](url)` links). Then:
+
+```bash
+ideadump note <id> --file <note.md> --depth light
+ideadump update <id> --status promising     # only if the verdict says so; parked/dropped likewise
+ideadump sync
+```
+
+Write the note in a temporary folder, not in the current project.
+
+## Deep research (on request, or when the owner agrees an idea is promising)
+
+Load the `do-research` skill and run it on the idea at deep depth (its report shape, its Vancouver references). Store the report with `ideadump note <id> --file <report.md> --depth deep`, then `ideadump sync`. The report is as private as the idea. If the owner reads on a phone, give them a link only to a destination that is private and access-controlled (in their fleet, `annals publish`, whose links are private; or the idea's page in the private data repository). Never publish it anywhere public.
+
+## Finding ideas
+
+```bash
+ideadump ls                                 # newest first; --tag, --status, --limit
+ideadump show <id or part of it>            # the idea's page: words, summary, research, links
+ideadump find "offline speech recognition"  # ranked, with the words each hit shares with the query
+```
+
+The data folder is browsable as it is: `README.md` at its root is the index (newest first, then by tag), and each `ideas/<id>/README.md` is an idea's page, so on GitHub the owner can read it from a phone.
+
+## "Is anything I have been working on related to my ideas?"
+
+1. Gather a page of text describing recent work into a temporary file: what the owner's sessions did lately (in their fleet: `crowsnest ledger` for the per-session ledgers, `ol` for open loops), recent issue and PR titles, recent commit subjects (`git log --since=7.days --format=%s` in the active repositories). A few hundred lines is fine.
+2. `ideadump find --file <that file> --limit 15`.
+3. The ranking is lexical, so **judge it**: read the top hits' pages (`ideadump show`), keep only those that really relate, and tell the owner, for each, which idea, which work, and the one thing the work could do for the idea (or the idea for the work). Say plainly when nothing relates.
+4. Record a real connection: `ideadump update <id> --add-tags <project>` or a line in a research note.
+
+## Other verbs
+
+`ideadump update <id> --title/--summary/--tags/--add-tags/--status`, `ideadump link <a> <b> --why ...`, `ideadump reindex` (regenerate the pages), `ideadump sync-status`, `ideadump sync-init <owner>/<name>` (make the data folder a checkout of a private repository, created private if missing; an existing ideas folder is adopted). `--json` as the last argument of any verb prints the full result. Statuses: `new`, `promising`, `parked`, `pursued`, `dropped`.
+
+## Never
+
+- Never edit `words`; never delete an idea or a note the owner did not ask you to delete.
+- Never put idea text in the current project, an issue, or anywhere public. If ideadump refuses because the data folder is inside another git work tree, tell the owner; never set `IDEADUMP_ALLOW_INSIDE_WORK_TREE` yourself.
+- Never run deep research unasked on every idea: a light look at capture, deeper only on request or agreement.

ideadump/render.py

@@ -0,0 +1,125 @@
+"""Markdown views of the records: one ``README.md`` per idea and an index at the root.
+
+The records (``idea.json``) are the source of truth; these pages are regenerated from
+them on every write, so a person browsing the store on GitHub (or a phone) sees each
+idea's folder open on its page, and the root opens on the index.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from collections.abc import Iterable
+from datetime import datetime, timezone
+
+from ideadump.base import IDEAS_DIR, README_FILE
+
+__all__ = ["idea_page", "index_page", "research_depth", "created_at"]
+
+
+def research_depth(record: dict) -> str:
+    """How far an idea has been researched: ``deep``, ``light`` or ``-``."""
+    depths = {note.get("depth") for note in record.get("research", [])}
+    return "deep" if "deep" in depths else "light" if depths else "-"
+
+
+def created_at(record: dict) -> datetime:
+    """When an idea was captured, comparable across machines in different time zones.
+
+    >>> a = {"created": "2026-11-14T23:30:00+01:00"}
+    >>> b = {"created": "2026-11-14T22:45:00+00:00"}
+    >>> created_at(a) < created_at(b)
+    True
+    """
+    try:
+        moment = datetime.fromisoformat(record.get("created", ""))
+    except ValueError:
+        return datetime.min.replace(tzinfo=timezone.utc)
+    return moment if moment.tzinfo else moment.replace(tzinfo=timezone.utc)
+
+
+def _text(value: str) -> str:
+    """A title safe inside a Markdown table cell and link label."""
+    return re.sub(r"([|\[\]])", r"\\\1", value.replace("\n", " "))
+
+
+def _tags(record: dict) -> str:
+    return ", ".join(f"`{t}`" for t in record.get("tags", [])) or "-"
+
+
+def idea_page(record: dict, *, titles: dict[str, str] | None = None) -> str:
+    """The page of one idea: the owner's words, the summary, research and links.
+
+    >>> page = idea_page({"id": "x", "title": "T", "words": "w", "created": "2026-11-14"})
+    >>> page.splitlines()[0]
+    '# T'
+    """
+    titles = titles or {}
+    lines = [
+        f"# {record['title']}",
+        "",
+        f"`{record['id']}` · {record.get('status', 'new')} · captured {record.get('created', '')[:10]}"
+        + (f" from {record['source']}" if record.get("source") else "")
+        + f" · research: {research_depth(record)}",
+        "",
+        f"Tags: {_tags(record)}",
+        "",
+    ]
+    if record.get("summary"):
+        lines += ["## Summary", "", record["summary"].strip(), ""]
+    lines += ["## In the owner's words", ""]
+    lines += [
+        f"> {line}" if line else ">" for line in record["words"].strip().splitlines()
+    ]
+    lines.append("")
+    if record.get("research"):
+        lines += ["## Research", ""]
+        for note in record["research"]:
+            lines.append(
+                f"- [{note.get('title') or note['file']}]({note['file']}) ({note['depth']}, {note['date'][:10]})"
+            )
+        lines.append("")
+    if record.get("links"):
+        lines += ["## Related ideas", ""]
+        for link in record["links"]:
+            other = link["id"]
+            label = titles.get(other, other)
+            why = f": {link['why']}" if link.get("why") else ""
+            lines.append(f"- [{_text(label)}](../{other}/{README_FILE}){why}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def index_page(records: Iterable[dict]) -> str:
+    """The root index: every idea, newest first, then the ideas under each tag.
+
+    >>> print(index_page([]).splitlines()[0])
+    # Ideas
+    """
+    records = sorted(records, key=created_at, reverse=True)
+
+    def link(r):
+        return f"[{_text(r['title'])}]({IDEAS_DIR}/{r['id']}/{README_FILE})"
+
+    lines = [
+        "# Ideas",
+        "",
+        f"{len(records)} ideas. Generated by ideadump from the `idea.json` records; do not edit by hand.",
+        "",
+        "| Captured | Idea | Status | Research | Tags |",
+        "|---|---|---|---|---|",
+    ]
+    for r in records:
+        lines.append(
+            f"| {r.get('created', '')[:10]} | {link(r)} | {r.get('status', 'new')} | {research_depth(r)} | {_tags(r)} |"
+        )
+    by_tag = defaultdict(list)
+    for r in records:
+        for tag in r.get("tags", []):
+            by_tag[tag].append(r)
+    if by_tag:
+        lines += ["", "## By tag", ""]
+        for tag in sorted(by_tag):
+            lines.append(f"- **{tag}**: " + ", ".join(link(r) for r in by_tag[tag]))
+    lines.append("")
+    return "\n".join(lines)

ideadump/search.py

@@ -0,0 +1,99 @@
+"""Rank ideas against a query: BM25 over words, standard library only.
+
+The query can be a few words ("offline speech to text") or a page of text describing
+recent work (ledgers, issue titles, commit messages): long queries are the "is
+anything I've been working on related to my ideas?" case. The scorer is a seam: any
+``score(query, docs) -> list[float]`` can be passed to :func:`rank`, for instance a
+semantic scorer backed by the fleet's ``ir`` search.
+
+>>> docs = {"a": "offline speech to text on a phone", "b": "a recipe for bread"}
+>>> [hit["id"] for hit in rank("speech recognition offline", docs)]
+['a']
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from collections.abc import Callable, Mapping, Sequence
+
+__all__ = ["tokens", "bm25", "rank"]
+
+_WORD = re.compile(r"[a-z0-9][a-z0-9+#.-]*[a-z0-9+#]|[a-z0-9]", re.IGNORECASE)
+
+# Function words carry no topic; dropping them keeps a page-long query from matching
+# every idea on "the" and "with".
+_STOPWORDS = frozenset(
+    """a about above after again all also am an and any are as at be because been
+    before being below between both but by can could did do does doing down during
+    each few for from further had has have having he her here hers him his how i if
+    in into is it its itself just let like make me more most my no nor not now of off
+    on once only or other our out over own same she should so some such than that the
+    their them then there these they this those through to too under until up very
+    was we were what when where which while who whom why will with would you your
+    yours maybe really thing things want wanna gonna get got way use using one also""".split()
+)
+
+
+def tokens(text: str) -> list[str]:
+    """Lowercased content words of ``text``, with a light plural fold.
+
+    >>> tokens("The ideas, and an Idea!")
+    ['idea', 'idea']
+    """
+    out = []
+    for word in _WORD.findall(text.lower()):
+        if word in _STOPWORDS or len(word) < 2:
+            continue
+        if len(word) > 3 and word.endswith("s") and not word.endswith("ss"):
+            word = word[:-1]
+        out.append(word)
+    return out
+
+
+def bm25(
+    query: str, docs: Sequence[str], *, k1: float = 1.5, b: float = 0.75
+) -> list[float]:
+    """BM25 score of each document for ``query`` (query terms counted once each)."""
+    doc_tokens = [tokens(d) for d in docs]
+    n = len(doc_tokens)
+    if not n:
+        return []
+    avg_len = sum(map(len, doc_tokens)) / n or 1.0
+    df = Counter(t for toks in doc_tokens for t in set(toks))
+    terms = set(tokens(query))
+    scores = []
+    for toks in doc_tokens:
+        tf = Counter(toks)
+        norm = k1 * (1 - b + b * len(toks) / avg_len)
+        score = 0.0
+        for t in terms & tf.keys():
+            idf = math.log(1 + (n - df[t] + 0.5) / (df[t] + 0.5))
+            score += idf * tf[t] * (k1 + 1) / (tf[t] + norm)
+        scores.append(score)
+    return scores
+
+
+def rank(
+    query: str,
+    docs: Mapping[str, str],
+    *,
+    limit: int = 10,
+    score: Callable[[str, Sequence[str]], list[float]] = bm25,
+) -> list[dict]:
+    """The ids of ``docs`` that match ``query``, best first, with score and shared terms."""
+    ids = list(docs)
+    scores = score(query, [docs[i] for i in ids])
+    query_terms = set(tokens(query))
+    hits = [
+        {
+            "id": i,
+            "score": round(s, 3),
+            "terms": sorted(query_terms & set(tokens(docs[i])))[:12],
+        }
+        for i, s in zip(ids, scores)
+        if s > 0
+    ]
+    hits.sort(key=lambda h: -h["score"])
+    return hits[:limit]

ideadump/store.py

@@ -0,0 +1,148 @@
+"""Where ideas live: a ``MutableMapping`` of ``/``-separated path to text.
+
+Every verb takes a ``files`` store, so the default local folder can be swapped for any
+other ``dol`` store (or a plain ``dict`` in tests) without touching the rest. The
+default is a folder, the data root:
+
+1. the ``data_dir`` argument, else
+2. ``$IDEADUMP_DATA_DIR``, else
+3. ``~/.local/share/ideadump`` (``$XDG_DATA_HOME`` and ``%LOCALAPPDATA%`` honoured).
+
+To keep ideas in a private git repository, make the data root a checkout of it with
+``ideadump sync-init <owner>/<name>`` (see :mod:`ideadump.sync`); the store
+itself does not change.
+
+>>> data_dir("somewhere").is_absolute()
+True
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Iterator, MutableMapping
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from ideadump.base import APP_NAME, DATA_DIR_ENVVAR, IdeadumpError
+
+__all__ = ["data_dir", "text_files", "resolve_files", "writing"]
+
+
+def data_dir(data_dir: str | os.PathLike | None = None) -> Path:
+    """The data root: the argument, else ``$IDEADUMP_DATA_DIR``, else the user data folder."""
+    if data_dir:
+        return Path(os.path.abspath(os.path.expanduser(str(data_dir))))
+    configured = os.environ.get(DATA_DIR_ENVVAR)
+    if configured:
+        path = Path(os.path.expanduser(configured))
+        if not path.is_absolute():
+            raise IdeadumpError(
+                f"${DATA_DIR_ENVVAR} must be an absolute path, got {configured!r}"
+            )
+        return path
+    if os.name == "nt":  # pragma: no cover - exercised on Windows CI only
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        return Path(base) / APP_NAME
+    base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(base) / APP_NAME
+
+
+def text_files(root: str | os.PathLike) -> MutableMapping[str, str]:
+    """A ``dol`` files store under ``root``: ``/``-separated keys, UTF-8 text values.
+
+    Folders are made on write and never on read; a delete is permanent.
+    """
+    from dol import Files, mk_dirs_if_missing, wrap_kvs
+
+    root = str(root)
+    os.makedirs(root, exist_ok=True)
+    files = mk_dirs_if_missing(Files(root, delete_func=os.remove))
+    return wrap_kvs(
+        files,
+        key_of_id=lambda k: k.replace(os.sep, "/"),
+        id_of_key=lambda k: k.replace("/", os.sep),
+        obj_of_data=lambda b: b.decode("utf-8", errors="replace"),
+        data_of_obj=lambda s: s.encode("utf-8"),
+    )
+
+
+def resolve_files(
+    files: MutableMapping[str, str] | None = None, *, data_dir_: Any = None
+) -> MutableMapping[str, str]:
+    """``files`` if given, else the text store over the data root."""
+    return text_files(data_dir(data_dir_)) if files is None else files
+
+
+_LOCK_FILE = ".ideadump.lock"
+_LOCK_TIMEOUT = 30.0  # seconds to wait for another writer
+_LOCK_STALE = 120.0  # a lock older than this was left by a crashed process
+_LOCK_POLL = 0.05
+
+
+ALLOW_WORK_TREE_ENVVAR = "IDEADUMP_ALLOW_INSIDE_WORK_TREE"
+
+
+def enclosing_work_tree(root: Path) -> Path | None:
+    """The git work tree ``root`` sits inside, when it is not a checkout of its own."""
+    if (root / ".git").exists():
+        return None
+    return next((p for p in root.parents if (p / ".git").exists()), None)
+
+
+def _refuse_foreign_work_tree(root: Path) -> None:
+    enclosing = enclosing_work_tree(root)
+    if enclosing and not os.environ.get(ALLOW_WORK_TREE_ENVVAR):
+        raise IdeadumpError(
+            f"the data folder {root} is inside the git work tree {enclosing}, so a commit "
+            "there would carry the ideas. Point $IDEADUMP_DATA_DIR elsewhere, or, if that "
+            f"repository is private and meant for them, set ${ALLOW_WORK_TREE_ENVVAR}=1"
+        )
+
+
+@contextmanager
+def writing(
+    files: MutableMapping[str, str] | None = None,
+    *,
+    data_dir_: Any = None,
+    timeout: float = _LOCK_TIMEOUT,
+) -> Iterator[MutableMapping[str, str]]:
+    """The store, held exclusively while a verb reads, changes and rewrites it.
+
+    Several sessions may capture ideas at the same moment; each write verb reads every
+    record, picks a free id, and rewrites the index, so two of them interleaving would
+    lose an idea. For the default folder store this takes a lock file in the data root
+    (created exclusively, so it works on every platform); a store passed in by the
+    caller is the caller's to serialise.
+    """
+    if files is not None:
+        yield files
+        return
+    root = data_dir(data_dir_)
+    _refuse_foreign_work_tree(root)
+    root.mkdir(parents=True, exist_ok=True)
+    lock = root / _LOCK_FILE
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.write(fd, str(os.getpid()).encode())
+            os.close(fd)
+            break
+        except FileExistsError:
+            try:
+                if time.time() - lock.stat().st_mtime > _LOCK_STALE:
+                    lock.unlink(missing_ok=True)
+                    continue
+            except FileNotFoundError:
+                continue
+            if time.monotonic() > deadline:
+                raise IdeadumpError(
+                    f"another ideadump write holds {lock}; if no other ideadump is running, delete that file"
+                ) from None
+            time.sleep(_LOCK_POLL)
+    try:
+        yield text_files(root)
+    finally:
+        lock.unlink(missing_ok=True)