ai-code-engineer 0.1.0__py3-none-any.whl

ai_code_engineer/host.py

@@ -0,0 +1,81 @@
+"""The seam between the two windows: four verbs, and the one question they must ask alike.
+
+Tk and the web window agree on nothing about presentation — one owns a `StringVar` and a
+`messagebox`, the other a snapshot dict and an SSE channel. What they must not be allowed to
+disagree about is *what a moment means*. Four verbs cover everything either window does to show
+itself, and the review that named them counted the drift in the old tree: setting a status
+(`self.status.set()` ×52 against `self.status =` ×72), adding a conversation row
+(`chat_message` ×15 against `_add` ×19), asking (`messagebox.*` ×6 against `self.confirm` ×6) and
+streaming (`events.put` ×7 against `_emit` ×13).
+
+Those four are the contract below, and both windows now carry them under these names. Being honest
+about how far that goes: the verbs are the sanctioned way out to the screen, and the count of raw
+primitives is ratcheted in `tests/test_host.py` rather than reduced to zero. Converting 88 status
+assignments in one pass is the rewrite this module exists to make unnecessary; what matters is that
+the number cannot grow, that a *decision* — the Apply dialog, the write warning, a sentence either
+window may have to say — goes through a verb, and that the names exist so a test can ask the other
+window the same question.
+
+The second half of this file is the part that had actually drifted, and the fix that made the
+contract worth having. Both windows assemble their own Apply dialog and had diverged in a way no
+test could see: the web window passed `repair.must_ask()`'s reason in and Tk dropped both the reason
+and the `warning` field the builder returned, so the same proposal warned about different things
+depending on which window happened to be open. Tk also called `must_ask(session)` without the
+prior-task half of the rule, leaving that branch unreachable there — and it has no Auto-Apply, so
+that difference is a feature gap, not drift, and is recorded as one.
+"""
+from __future__ import annotations
+
+
+class Host:
+    """What a window owes the code that runs behind it.
+
+    Deliberately not an ABC: `gui.AgentApp` already inherits from Tk, and forcing both
+    presentation layers under one base is the rewrite this module exists to make unnecessary.
+    The names are the contract, and `tests/test_host.py` holds both windows to them.
+    """
+
+    def say(self, text: str) -> None:
+        """Put one sentence on the window's status surface."""
+        raise NotImplementedError
+
+    def line(self, role: str, author: str, text: str) -> None:
+        """Add one row to the conversation."""
+        raise NotImplementedError
+
+    def ask(self, title: str, message: str, warning: str = "", ok_label: str = "Continue") -> bool:
+        """Ask the user something and block for the answer. `warning` is the part that must never
+        be dropped by the window that finds it inconvenient."""
+        raise NotImplementedError
+
+    def stream(self, event: dict) -> None:
+        """Forward one progress event to whatever is watching."""
+        raise NotImplementedError
+
+
+def apply_prompt(session: dict, notice: str = "", reason: str = "", again: str = "") -> dict:
+    """The Apply dialog as data: {title, message, warning, ok_label}.
+
+    `notice` is `repair.removal_notice()` — the files this proposal empties or deletes — and
+    `reason` is `repair.must_ask()`, the one case where writing needs saying twice because the
+    proposal would erase work. They overlap: an emptying proposal is also a must-ask one, so the
+    reason is appended only where it would otherwise be the only thing the user reads.
+
+    `again` is the repair loop's notice, which names a command that executes the project's own
+    code and so belongs in the same breath as the write it follows.
+    """
+    changes = (session or {}).get("changes", []) or []
+    root = (session or {}).get("root", "")
+    body = notice.rstrip("\n")
+    # A dialog that says "Write 2 file(s)" about a proposal that removes one of them is the card
+    # lying about the irreversible half, so the two verbs are counted apart.
+    removed = sum(1 for change in changes if change.get("delete"))
+    written = len(changes) - removed
+    lead = " and ".join(filter(None, [f"Write {written}" if written else "",
+                                      f"remove {removed}" if removed else ""])) or "Write 0"
+    message = ((body + "\n\n" if body else "") + lead + " file(s) to\n" + str(root) +
+               (again if again else "") +
+               (("\n\n" + reason) if reason and not body else "") +
+               "\n\nYou can roll back afterwards as long as the files are not edited later.")
+    return {"title": "Apply changes", "message": message, "warning": reason,
+            "ok_label": "Apply changes"}

ai_code_engineer/ignore.py

@@ -0,0 +1,269 @@
+"""One owner for the question "is this path worth looking at".
+
+Three lists used to answer it — `workspace.BLOCKED_PARTS`, `runner.PROJECT_SKIP`,
+`controller.SKIP_DIRS` — copied from each other by hand, so they drifted: the build directories the
+planner refused were hidden in the picker for a different reason, and nothing in any of them knew that
+this tool writes its own chat transcripts and its own preview folder into the workspace it is asked to
+index. Measured on this repository before the split was closed: 400 of 591 files the map walked were
+`.agent-webview/`, `.agent-chats/` and `.design-preview/`, and the repository map came back at 12 206
+characters against a 12 000 budget — the model's view of this project was mostly this project's own
+output.
+
+The three questions are genuinely different, so this module keeps three compositions over one set of
+names. What was wrong was not the difference; it was that a name had to be edited in three places to
+have an effect in one.
+
+Nothing here is a security boundary on its own. `refused_dir` is the predicate the read and write gates
+use, and it must stay a **superset** of what `BLOCKED_PARTS` held, so moving a build directory from the
+policy list to the tidiness list cannot quietly make it readable.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# Credentials, VCS internals, and the surfaces an agent could leave a hook on. Refusing these is a
+# policy decision, not a tidiness one, and it does not change because a repository asked.
+PROTECTED_DIRS = {
+    ".git", ".env", ".ssh", ".aws", ".azure", ".gnupg", ".codex", ".agents", ".agent-runs",
+    ".agent-projects.json", ".agent-modes.json", ".agent-plans", ".agent-memory",
+    # The signed rows and the key that signs them. The signature is what actually refuses a row a model
+    # wrote, but a file the operator set with their own hands is not the model's to rewrite either.
+    ".agent-overrides.json", ".agent-overrides.key",
+    ".venv", "venv", ".gradle", ".m2",
+    ".idea",
+}
+# Matches files that *are* credentials, not source that merely names one — `token.json` yes,
+# `JwtTokenProvider.java` no. The pattern is the one `workspace.py` always used, moved rather than
+# copied so the read gate and the walk cannot disagree about what `.env` means.
+SECRET_NAME = re.compile(
+    r"(^\.env($|\.)|(^|[-_.])(credentials?|secrets?|passwords?|tokens?|keys?|private[-_]?key)s?($|[-_.]))",
+    re.I)
+# NTFS keeps an 8.3 alias for every name it had to shorten, and the alias opens the same bytes.
+# "TOKEN~1.JSON" would otherwise be a shape the checks above never saw, so it is refused by pattern.
+SHORT_NAME = re.compile(r"~\d{1,2}(?:\.[^.]+)?$", re.I)
+
+# Built, vendored, or written by this tool itself. Out of the walk, because a map full of them is how a
+# real source file gets truncated out of the model's context. Not out of reach: a caller that names one
+# explicitly can still read it — these are noise, not secrets.
+GENERATED_DIRS = {
+    "node_modules", "target", "build", "dist", "site-packages", "eggs", "bower_components",
+    "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox", ".next", ".nuxt",
+    ".turbo", ".sass-cache", "coverage", "htmlcov", ".terraform",
+    # The tool's own output. `.agent-runs` is protected above; these three were in no list at all.
+    ".agent-webview", ".agent-chats", ".design-preview",
+}
+# A directory whose name says it holds generated code: Maven's `generated-sources`, protobuf's `gen`,
+# a hand-rolled `src/generated`. Matched against the whole segment, so `chargeback-api` is safe.
+GENERATED_SEGMENT = re.compile(r"^(gen|generated|generated[-_].*|.*[-_]generated)$", re.I)
+# Files that are a minified or compiled form of something else. Matched against the whole name, so
+# `app.min.js` goes and `admin.js` stays.
+GENERATED_SUFFIXES = (".min.js", ".min.css", ".bundle.js", ".lock", ".map", ".iml", ".g.cs",
+                      ".g.i.cs", ".designer.cs", ".generated.cs", "_pb2.py", "_pb2_grpc.py")
+
+# "Could a build be run in this folder?" is a different question, with one extra honest answer: a .NET
+# tree keeps output in `bin`, a Rails app keeps executables there too, so those names are a reason not
+# to *offer* a folder and not a reason to refuse a file the operator named.
+PROJECT_EXTRA_DIRS = {"out", "bin", "obj", "vendor", "packages", "deps", "_build", ".direnv", ".mvn"}
+# The folder picker walks a drive root, so it needs a second reason to hide a folder: it is the
+# machine, not the workspace. These are `controller.SKIP_DIRS` verbatim.
+OS_TREES = {"program files", "windows", "system32", "appdata", "downloads", "$recycle.bin",
+            "programdata", "perflogs", "recovery", "windowsapps", "drvstore"}
+
+
+def protected_dir(part: str) -> bool:
+    return str(part).casefold() in PROTECTED_DIRS
+
+
+def credential(part: str) -> bool:
+    return bool(SECRET_NAME.search(str(part)))
+
+
+def alias(part: str) -> bool:
+    return bool(SHORT_NAME.search(str(part)))
+
+
+def generated_dir(part: str) -> bool:
+    folded = str(part).casefold()
+    return folded in GENERATED_DIRS or bool(GENERATED_SEGMENT.match(folded))
+
+
+def generated_file(name: str) -> bool:
+    return str(name).casefold().endswith(GENERATED_SUFFIXES)
+
+
+def refused_dir(part: str) -> bool:
+    """A directory the walk never enters and the path gate never resolves through."""
+    return protected_dir(part) or generated_dir(part) or credential(part) or alias(part)
+
+
+def project_dir(part: str) -> bool:
+    """`refused_dir` plus the output names that only disqualify a folder as a project root."""
+    return refused_dir(part) or str(part).casefold() in PROJECT_EXTRA_DIRS
+
+
+def picker_dir(part: str) -> bool:
+    """`refused_dir` plus the operating system's own trees."""
+    return refused_dir(part) or str(part).casefold() in OS_TREES
+
+
+def _segment(pattern: str) -> str:
+    """One path segment of a gitignore pattern to regex: `*` and `?` stop at a slash."""
+    out = []
+    index = 0
+    while index < len(pattern):
+        char = pattern[index]
+        if char == "*":
+            out.append("[^/]*")
+        elif char == "?":
+            out.append("[^/]")
+        elif char == "[":
+            close = pattern.find("]", index + 1)
+            if close < 0:
+                out.append(re.escape(char))
+            else:
+                inner = pattern[index + 1:close]
+                if inner.startswith("!"):
+                    inner = "^" + inner[1:]
+                out.append("[" + inner + "]")
+                index = close
+        else:
+            out.append(re.escape(char))
+        index += 1
+    return "".join(out)
+
+
+class Rules:
+    """A parsed `.gitignore`: last match wins, and an ignored directory takes its children with it.
+
+    Implemented is git's syntax as it is actually used — `*` and `?` that stop at a slash, `**` that
+    crosses one, a trailing `/` for directories only, a leading or inner `/` to anchor, `[abc]` and
+    `[!abc]` classes, `#` comments, and `!` to put something back — plus a nested `.gitignore` for every
+    directory the walk reaches. Not implemented: git's own escapes and character-class edge cases,
+    `.git/info/exclude`, and the global `core.excludesFile`, all of which live outside the folder this
+    tool was handed and would make a granted folder's map depend on this machine's configuration.
+
+    Git is never consulted. `git_program()` may return `None` and a granted folder is often not a
+    repository at all, so the parser is the rule rather than the fallback — which is the difference
+    between a map that is stable and one that changes when a checkout of git appears.
+    """
+
+    def __init__(self, rows: list[tuple[bool, re.Pattern, bool]] | None = None,
+                 origin: str = "") -> None:
+        self.rows = rows or []
+        self.origin = origin
+
+    def __bool__(self) -> bool:
+        return bool(self.rows)
+
+    def child(self, text: str) -> "Rules":
+        """These rules plus one directory's own file, which refines them.
+
+        A nested `.gitignore` wins over the one above it, and git decides that by trying patterns last
+        first, so the child's lines go on the end of the list. The parent's rows are kept whole rather
+        than mutated, which is also what makes a subdirectory's rules stop applying when the walk leaves
+        it: each directory carries only the chain that reaches it.
+        """
+        return Rules(self.rows + self.parse(text), self.origin)
+
+    @staticmethod
+    def compile_pattern(pattern: str) -> re.Pattern | None:
+        body = pattern.lstrip("/")
+        # An inner slash anchors the pattern to the directory the file sat in; without one it may
+        # match at any depth. `logs/` alone has no inner slash, so it matches every `logs` directory.
+        anchored = "/" in body.rstrip("/")
+        pieces: list[str] = []
+        segments = body.split("/")
+        for position, segment in enumerate(segments):
+            last = position == len(segments) - 1
+            if not segment:
+                continue
+            if segment == "**":
+                # `**/x` reaches any depth, `x/**` takes everything below, `a/**/b` also matches `a/b`.
+                pieces.append(".*" if last else "(?:[^/]*/)*")
+                continue
+            pieces.append(_segment(segment))
+            if not last:
+                pieces.append("/")
+        stem = "".join(pieces)
+        if not stem:
+            return None
+        return re.compile(("" if anchored else "^(?:[^/]*/)*") + stem + "$")
+
+    @classmethod
+    def parse(cls, text: str) -> list[tuple[bool, re.Pattern, bool]]:
+        rows = []
+        for line in str(text or "").splitlines():
+            pattern = line.rstrip("\r")
+            if not pattern.strip() or pattern.lstrip().startswith("#"):
+                continue
+            pattern = pattern.strip()
+            negate = pattern.startswith("!")
+            if negate:
+                pattern = pattern[1:].strip()
+            directory_only = pattern.endswith("/")
+            pattern = pattern.rstrip("/")
+            if not pattern:
+                continue
+            compiled = cls.compile_pattern(pattern)
+            if compiled is not None:
+                rows.append((negate, compiled, directory_only))
+        return rows
+
+    @classmethod
+    def load(cls, root: Path, limit_bytes: int = 64 * 1024) -> "Rules":
+        """The root rules, or none at all: a file that cannot be read is no rules, not a failed task."""
+        try:
+            path = Path(root) / ".gitignore"
+            if not path.is_file() or path.stat().st_size > limit_bytes:
+                return cls()
+            return cls(cls.parse(path.read_text(encoding="utf-8", errors="replace")), ".gitignore")
+        except OSError:
+            return cls()
+
+    def _matched(self, path: str, is_dir: bool) -> bool:
+        """One path, all the rules, last match wins — which is git's whole precedence model."""
+        decided = False
+        for negate, pattern, directory_only in self.rows:
+            if directory_only and not is_dir:
+                continue
+            if pattern.match(path):
+                decided = not negate
+        return decided
+
+    def ignores(self, relative: str, is_dir: bool) -> bool:
+        """Whether git would call this path uninteresting.
+
+        An excluded directory takes everything under it, and no `!` line inside it can put a file back:
+        git says so explicitly ("It is not possible to re-include a file if a parent directory of that
+        file is excluded"), and a tool that disagreed with that would list files a person cannot add to
+        a commit. So the ancestors are decided first, and only a path whose whole chain survived gets
+        its own last-match answer.
+        """
+        parts = [p for p in str(relative).replace("\\", "/").split("/") if p]
+        for depth in range(1, len(parts)):
+            if self._matched("/".join(parts[:depth]), True):
+                return True
+        return self._matched("/".join(parts), is_dir)
+
+
+def walk_prune(dirs, rules: Rules) -> tuple[list[str], int, int]:
+    """The directories to descend into, and how many were left out for which reason.
+
+    Shared by every caller that walks a project, so the map, the search and the count the composer
+    prints cannot each disagree about what a folder holds. The counts travel out with the decision
+    because they are the only way a reader can tell "there is nothing here" from "something was hidden"
+    — a silent filter turns a missing file into a wrong answer from a model that believes the map.
+    """
+    kept, generated, ignored = [], 0, 0
+    for name in dirs:
+        if generated_dir(name):
+            generated += 1
+            continue
+        if rules and rules.ignores(name, True):
+            ignored += 1
+            continue
+        if protected_dir(name) or credential(name) or alias(name):
+            continue
+        kept.append(name)
+    return sorted(kept), generated, ignored

ai_code_engineer/intent.py

@@ -0,0 +1,222 @@
+"""The write-intent axis: three positions, and what each one refuses.
+
+`Chat` answers in prose and reads the folder as context. `Read-only` does the same but promises the
+stronger thing: nothing is proposed, nothing is written, and a project command runs only after a clear
+yes for that command. `Change` proposes a diff for review — and the per-folder Auto-Apply switch sits
+on top of it, which is why the switch is not a fourth position here.
+
+Both windows ask this module instead of each holding its own rule. Every sentence is written once, in
+two languages: the last time two surfaces worded "this conversation cannot write" separately, one of
+them was refusing a different thing than the other.
+"""
+from __future__ import annotations
+
+from .labels import say
+
+CHAT, READ, CHANGE = "chat", "read", "change"
+MODES = (CHAT, READ, CHANGE)
+
+# What the badge and the picker call each position.
+LABELS = {CHAT: "Chat", READ: "Read-only", CHANGE: "Change"}
+
+
+def normalise(value) -> str:
+    """The mode this value names, or chat for anything unrecognised.
+
+    A stored preference from an older version, or a payload with a typo, cannot leave a window in a
+    state where neither promise holds. Chat is the safe reading: it writes nothing.
+    """
+    text = str(value or "").strip().lower()
+    return text if text in MODES else CHAT
+
+
+def read_only(mode) -> bool:
+    return normalise(mode) == READ
+
+
+def label(mode) -> str:
+    return LABELS[normalise(mode)]
+
+
+# What the header line of each window prints for the position: the name, then the promise it keeps.
+PROMISE = {CHAT: "reads as context", READ: "writes nothing", CHANGE: "reviewed diff"}
+
+
+def subtitle(mode) -> str:
+    """`chat · reads as context` — the mode in the header, in the mode's own words."""
+    mode = normalise(mode)
+    return LABELS[mode].lower() + " · " + PROMISE[mode]
+
+
+def needs_folder(mode, *, arabic: bool = False) -> str:
+    """Why two of the three positions cannot be chosen over an empty window."""
+    mode = normalise(mode)
+    if mode == CHANGE:
+        return say(arabic,
+                   en="Choose a project in the sidebar before asking for reviewed changes.",
+                   ar="اختر مشروعا في الشريط الجانبي قبل طلب فروق تراجعها.")
+    return say(arabic,
+               en="Choose a project in the sidebar before asking for a read-only analysis.",
+               ar="اختر مشروعا في الشريط الجانبي قبل طلب فحص للقراءة فقط.")
+
+
+# ------------------------------------------------------------------ the refusals
+
+def switched(mode, *, arabic: bool = False, project: str = "") -> str:
+    """What choosing this position means, said as the window's own next line."""
+    suffix = f" ({project})" if project else ""
+    mode = normalise(mode)
+    if mode == READ:
+        return say(arabic,
+                   en=("Read-only: I read this folder, search it, map it and explain what I find. I create "
+                       "no proposal and write nothing, and your project's own command runs only when you "
+                       "say yes to that one command." + suffix),
+                   ar=("وضع القراءة فقط: أقرأ هذا المجلد وأفتشه وأبني خريطته وأشرح ما أجد فيه. لا أنشئ أي "
+                       "اقتراح ولا أكتب أي شيء، وأمر المشروع نفسه لا يعمل إلا عندما توافق على ذلك الأمر "
+                       "بعينه." + suffix))
+    if mode == CHANGE:
+        return say(arabic,
+                   en="Change mode: Send proposes a diff you review before any file is written." + suffix,
+                   ar="وضع التعديل: الإرسال يقترح فروقا تراجعها قبل كتابة أي ملف." + suffix)
+    return say(arabic,
+               en="Chat mode: Send answers in prose and cannot write files.",
+               ar="وضع الدردشة: الإرسال يجيب بالنص ولا يكتب ملفات.")
+
+
+def unchecked(*, arabic: bool = False) -> str:
+    """Read-only switched back off, in the window that holds it as a switch rather than a badge."""
+    return say(arabic,
+               en="Read-only is off. Send proposes a diff you review before any file is written.",
+               ar="وضع القراءة فقط مطفأ. الإرسال يقترح فروقا تراجعها قبل كتابة أي ملف.")
+
+
+def answered(*, arabic: bool = False) -> str:
+    """Where a read-only answer ends. Both windows close an analysis with this, because the sentence
+    before it told the operator to switch modes after every single question."""
+    return say(arabic,
+               en="Answered in Read-only mode. Nothing was written.",
+               ar="أجبت في وضع القراءة فقط. لم يُكتب شيء.")
+
+
+def no_proposal(*, arabic: bool = False) -> str:
+    """Why a message that asks for a change gets an explanation instead of a diff."""
+    return say(arabic,
+               en=("This conversation is in Read-only mode, so there is no proposal to build. Ask what is "
+                   "wrong, where it is, and what a fix would touch — and switch the badge to Change when you "
+                   "want a diff to review."),
+               ar=("هذه المحادثة في وضع القراءة فقط، لذلك لا يُبنى أي اقتراح. اسألني ما الخطأ وأين وماذا "
+                   "سيلمس الإصلاح، وحوّل الشارة إلى وضع التعديل عندما تريد فروقا تراجعها."))
+
+
+def no_write(what: str = "Apply", *, arabic: bool = False) -> str:
+    """Apply and Roll back both change files, so both stop here."""
+    return say(arabic,
+               en=(f"{what} writes to the folder, and this conversation is in Read-only mode. Switch to "
+                   "Change mode to review and write the diff."),
+               ar=(f"{what} يكتب في المجلد، والمحادثة في وضع القراءة فقط. حوّلها إلى وضع التعديل لترى "
+                   "الفروق وتكتبها."))
+
+
+def no_fix_round(*, arabic: bool = False) -> str:
+    """"Run & fix" spends a round on a proposal, which is the one thing this mode will not make."""
+    return say(arabic,
+               en=("Read-only runs the command when you say yes, but it does not run a fix round: the output "
+                   "of a round is a proposal. The failure and its whole output are above — ask what they mean."),
+               ar=("وضع القراءة فقط يشغّل الأمر عندما توافق، لكنه لا ينفّذ جولة إصلاح، لأن ناتج الجولة "
+                   "اقتراح. رسالة الفشل ومخرجها الكامل بالأعلى؛ اسأل عن معناهما."))
+
+
+def no_auto_apply(*, arabic: bool = False) -> str:
+    return say(arabic,
+               en=("A read-only conversation cannot arm Auto-Apply: the switch writes what the model "
+                   "proposes without a click. Turn it on while the folder is in Change mode."),
+               ar=("لا تستطيع محادثة في وضع القراءة فقط أن تفعّل الكتابة التلقائية: المفتاح يكتب ما "
+                   "يقترحه النموذج دون نقرة. فعّله والمجلد في وضع التعديل."))
+
+
+# ------------------------------------------------------------------ the one permission
+
+def run_ask(command: str, *, arabic: bool = False, project: str = "") -> str:
+    """The explicit yes this mode requires before a project's own code executes.
+
+    Named by command, because "run something?" is not a choice anyone can predict the outcome of, and
+    this is the sentence an operator reads before a build starts inside a production checkout.
+    """
+    where = f" في {project}" if project else ""
+    return say(arabic,
+               en=("This folder is in Read-only mode, which runs nothing until asked. Running this executes "
+                   f"the project's own code with your permissions{f' in {project}' if project else ''}:\n\n"
+                   f"  {command}\n\nIt cannot write to your files — that stays refused — but it can read "
+                   "them, and a build runs whatever its scripts do."),
+               ar=("هذا المجلد في وضع القراءة فقط، أي أنه لا يشغّل شيئا قبل أن يُسأل. التشغيل هنا ينفّذ كود "
+                   f"المشروع نفسه بصلاحياتك{where}:\n\n  {command}\n\nلن يكتب في ملفاتك، هذا يبقى مرفوضا، "
+                   "لكنه قد يقرأها، والبناء ينفّذ أي شيء تفعله سكربتاته."))
+
+
+def run_declined(*, arabic: bool = False) -> str:
+    return say(arabic,
+               en="Nothing ran. Read-only starts no command until you say yes to that one.",
+               ar="لم يُنفَّذ شيء. وضع القراءة فقط لا يشغّل أمرا إلا بموافقتك عليه.")
+
+
+# ------------------------------------------------------------------ the durable declaration
+
+# Which surface wrote the declaration. Stored as a code, spoken in either language, because a row that
+# reads "the command line" in an Arabic window is half a sentence.
+SOURCES = {"web": ("the web window", "نافذة الويب"),
+           "gui": ("the desktop window", "نافذة سطح المكتب"),
+           "cli": ("the command line", "سطر الأوامر"),
+           "saved": ("a window before this one", "نافذة قبل هذه")}
+
+
+def source(code: str, *, arabic: bool = False) -> str:
+    """Who set this folder, in the language the rest of the line is in."""
+    pair = SOURCES.get(str(code or ""))
+    return (pair[1] if arabic else pair[0]) if pair else str(code or "")
+
+
+def declared(by: str = "", at: str = "", *, arabic: bool = False, project: str = "") -> str:
+    """Why the write stopped at a fact about the folder rather than at this window's badge.
+
+    Names the surface and the minute, because "refused" without a who and a when reads like a bug, and
+    the operator's next move is to find whoever set it.
+    """
+    who, when = source(by, arabic=arabic), str(at or "")
+    bits = [part for part in (who, when) if part]
+    tail = " (" + " · ".join(bits) + ")" if bits else ""
+    where = f" ({project})" if project else ""
+    if arabic:
+        return ("المجلد" + where + " معلَن أنه للقراءة فقط" + tail +
+                ". لا سطح من سطوح هذه الأداة يكتب فيه طالما الإعلان قائم: لا اقتراح، ولا تنفيذ ولا "
+                "تراجع، ولا جولة إصلاح، ولا فرع أو استرجاع في git.")
+    return ("This folder" + where + " is declared Read-only" + tail +
+            ". No surface of this tool writes it while that stands: not a proposal, not Apply or Roll "
+            "back, not a fix round, and not a git branch or a restore.")
+
+
+def lift(folder: str, *, arabic: bool = False) -> str:
+    """How to end the declaration, said as the exact line to type.
+
+    A refusal that does not name its own remedy teaches the operator to go looking in a config file for
+    a switch that is not there, and the next one gets set by accident.
+    """
+    return say(arabic,
+               en=("To lift it, run:  agent read-only --off \"" + str(folder) + "\"  — or set the badge "
+                   "to Change in a window. Lifting is asked for by name on purpose: nothing here lifts "
+                   "itself."),
+               ar=("للرفع، شغّل:  agent read-only --off \"" + str(folder) +
+                   "\"  أو حوّل الشارة إلى وضع التعديل من أي نافذة. الرفع يُطلب بالاسم عمدًا، ولا شيء "
+                   "هنا يرفع نفسه."))
+
+
+def followed(by: str = "", at: str = "", *, arabic: bool = False) -> str:
+    """The line a window prints when the folder it is showing was declared elsewhere after it opened."""
+    who = source(by, arabic=arabic)
+    tail = (" (" + who + " · " + str(at or "") + ")") if at else (" (" + who + ")" if who else "")
+    return say(arabic,
+               en=("The badge follows the declaration, not the other way round: this folder was set "
+                   "Read-only" + tail + " after this window opened it. Every write is refused from here "
+                   "on, and choosing Change is what lifts the declaration."),
+               ar=("الشارة تتبع الإعلان وليس العكس: المجلد أُعلِن أنه للقراءة فقط" + tail +
+                   " بعد أن فتحته هذه النافذة. كل كتابة مرفوضة من هنا فصاعدًا، واختيار وضع التعديل هو "
+                   "ما يرفع الإعلان."))