tan-cli 0.7.0__py3-none-any.whl

tan/core/consent.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The one implementation of `GlobalArgs::can_prompt()` — the gate every
+command must pass before it prompts a human or mutates the host.
+
+Ported from the Rust oracle's `GlobalArgs::can_prompt()`, whose own
+`--non-interactive` help text states the rule the port must honour verbatim:
+
+    Never prompt. A command with a documented default takes it (`tan init`
+    scaffolds `zephyr-app` into `.`); one without fails instead of asking
+    (`tan scaffold` needs `--name`). **The same rule applies unasked when
+    stdin or stderr is not a terminal — piped, redirected, or a CI runner.**
+
+That last sentence is the half a re-derivation keeps dropping, and dropping it
+is not cosmetic. Before this module existed the check was written out by hand
+in four places and **one of them was wrong**: `doctor --fix` (tan-cli#91)
+tested only `not non_interactive and not ci and not json_mode` and omitted both
+`isatty()` calls, so a CI runner that redirected its output but did not happen
+to pass `--ci` got **unattended host mutation** — demonstrated live with fully
+captured pipes, where `tan doctor --fix` spawned four real `winget install`
+runs (`Git.Git`, `Kitware.CMake`, `Python.Python.3.12`, `Ninja-build.Ninja`)
+with nobody watching. A redirected stdio stream is the single most common shape
+of an automated run, so the omitted condition was the one that mattered most.
+
+Hence one function, imported. Duplicating a consent gate means every future
+copy is another chance to drop the clause that makes it a consent gate at all.
+
+**Why BOTH `stdin` and `stderr`, not just `stdin`.** A prompt is a
+question-and-answer pair and each half needs its own real terminal: `stdin`
+carries the answer, and `stderr` — never `stdout`, which belongs to the
+envelope — carries the question. `tan doctor --fix < /dev/null` has no way to
+receive consent; `tan doctor --fix 2>log` has no way to ask for it, and would
+block on a question the user never saw. Requiring both is what makes "the user
+actually agreed to this" true rather than merely likely.
+
+**Not `stdout`.** Under `--format json` stdout is a single parsed envelope, and
+`| jq` is a normal, fully-interactive way to run tan. Testing `stdout.isatty()`
+would refuse consent in a session where the human is sitting right there. The
+`json_mode` flag already covers the case that actually matters.
+"""
+from __future__ import annotations
+
+from tan.env import stderr_is_tty, stdin_is_tty
+
+
+def can_prompt(*, non_interactive: bool, ci: bool, json_mode: bool) -> bool:
+    """Whether this invocation may prompt the user, or take any other action
+    that needs a human's live consent (installing a toolchain, overwriting a
+    file, relocating a checkout).
+
+    All five conditions must hold. The three flags are the caller's explicit
+    "do not ask me" signals; the two `isatty()` calls are the same rule applied
+    **unasked**, for the automated runs that never thought to pass a flag.
+
+    A command with a documented default takes it when this returns `False`; one
+    without a default fails instead of asking.
+
+    tan-cli#488: `sys.stdin` itself, not just the result of calling `.isatty()`
+    on it, can be `None` -- a process launched with its standard handles
+    detached (a GUI launcher, `pythonw`-style spawn, or a shell that closed fd
+    0 before exec, `0<&-`) leaves `sys.stdin` unbound rather than merely
+    non-interactive, and a bare `sys.stdin.isatty()` then raises
+    `AttributeError: 'NoneType' object has no attribute 'isatty'`. This is the
+    ONE place that guard belongs: every caller of `can_prompt` (`doctor_cmd`,
+    `scaffold_cmd`) reaches this line before any caller-side guard could run,
+    so duplicating the `is not None` check downstream (as doctor_cmd.py's
+    `fix_suppressed_issue` still does, for its own separate per-condition
+    explanation) does not help -- this call is the one that crashes first.
+
+    tan-cli#488 round 5: the SAME detachment guards ONLY `sys.stdin`, not
+    `sys.stderr` -- the very next operand of this same `and` chain, and just
+    as reachable: the identical detached-process shape can leave `sys.stdin`
+    live (redirected to a real, non-tty file) while `sys.stderr` alone is
+    unbound, since each handle is detached independently by whatever spawned
+    the process. Verified against the real binary, not a mock: a `pty.fork()`
+    child with a genuine tty on stdin (`isatty() is True`, so the chain
+    reaches this line) and `stderr` closed before `exec` crashed
+    `tan doctor --fix` with exactly this `AttributeError` -- `sys.stdin is not
+    None` alone does not protect the `sys.stderr.isatty()` call one line
+    below it.
+
+    tan-cli#488 round 6: `is not None` was never the whole guard either --
+    it stops a detached (`None`) handle from crashing `.isatty()`, but not a
+    handle that EXISTS and simply has no `.isatty()` method, which is
+    exactly what `sys.stderr` becomes under `tan --format json`
+    (`tan.cli.main` tees it through `_TeeStderr`: `write`/`flush`/
+    `getvalue` only). This function's own `not json_mode` operand happens to
+    short-circuit ahead of the `sys.stderr` checks before that shape is ever
+    reached today, so `can_prompt` itself was never observed to crash on
+    it -- but `tan.commands.build_cmd._dispatch` hand-rolled the identical
+    `is not None and .isatty()` pair with no `json_mode` operand in front of
+    it at all, and DID crash, on a real `tan run --format json`
+    (`AttributeError: '_TeeStderr' object has no attribute 'isatty'`,
+    measured). Both operands now route through `tan.env.stdin_is_tty`/
+    `stderr_is_tty` -- the one shared probe (tan-cli#288) that already
+    wraps both exception classes -- rather than leaving this copy's safety
+    resting on an operand order a future edit could reshuffle.
+    """
+    return (
+        not non_interactive
+        and not ci
+        and not json_mode
+        and stdin_is_tty()
+        and stderr_is_tty()
+    )

tan/core/console_filter.py

@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`colors`: the default console filter for `tan monitor` (tan-cli#1315).
+
+A serial console shows bytes from a device nobody vouches for. Passing them
+straight to the user's terminal lets that device write the clipboard (OSC 52),
+retitle the window, and move or erase the screen. miniterm's own `default`
+filter is safe but prints Zephyr's colours as literal `ESC[1;32m` text. This
+filter keeps colours and nothing else, as an ALLOWLIST (a denylist of known
+bad sequences loses to the next terminal quirk):
+
+* a character is output only if it is printable (`unicodedata` category not
+  in Cc, Cf, Cs, Co, Cn, Zl, Zp, which also removes bidi/format controls and
+  DEL) or one of `\\r \\n \\t \\b`;
+* the ONLY escape ever output is an SGR sequence the filter builds itself,
+  `ESC [ <codes> m`, re-emitted canonically from the parsed codes and never
+  passed through as received. Allowed codes: 0 1 2 3 4 22 23 24 27 30-37 39
+  40-47 49 90-97 100-107, and 38/48 with `;5;n` or `;2;r;g;b` (0-255). Any
+  other code (conceal 8, blink 5/6, ...) is dropped and the rest kept; a
+  malformed 38/48 drops the remainder. The colon form (`38:2::1:2:3`) is not
+  recognised, so that sequence is neutralised whole;
+* every other ESC sequence (non-SGR CSI, OSC, DCS, APC, PM, SOS, charset
+  selects, lone ESC), every C1 control (U+0080-U+009F; U+009B/9D/90/98/9E/9F
+  start a sequence exactly like their 7-bit forms), CAN, SUB, DEL and every
+  other control character becomes one visible placeholder. CAN and SUB abort
+  a sequence in progress, as ECMA-48 terminals do;
+* the placeholder is `·`, or `?` when the output stream cannot encode it; a
+  `\\r \\n \\t \\b` following a dropped escape is still honoured;
+* it is stream-safe (a sequence split across reads is buffered) and bounded:
+  an over-long or unterminated sequence emits a placeholder and resyncs to
+  ground state without printing the buffered payload.
+
+Accepted residuals (not filterable without breaking colour output): text drawn
+with foreground equal to background is invisible; `\\b` and `\\r` let a device
+overwrite text already on the line; some printable-category characters
+(unassigned-looking Lo/Mn combining marks, zero-width letters) render as
+nothing. A character the output stream's encoding cannot represent (e.g. `世`
+on cp437) is replaced by the placeholder too, so it cannot raise in miniterm's
+reader thread.
+
+Because the only escape that can reach the terminal is one the filter
+generated, the terminal is always in ground state when it sees it, which
+removes the filter-vs-terminal parser differential.
+
+The class is defined by exec'ing `SOURCE`, so the same text can also be run
+inside a spawned `python -c` (`BOOTSTRAP`) where `tan` is not importable
+(frozen builds), and the in-process and subprocess consoles cannot drift.
+"""
+
+from __future__ import annotations
+
+SOURCE = r'''
+import sys as _sys
+import unicodedata as _ud
+
+
+def _placeholder():
+    enc = getattr(_sys.stdout, "encoding", None) or "ascii"
+    try:
+        "·".encode(enc)
+        return "·"
+    except (UnicodeError, LookupError):
+        return "?"
+
+
+class ColorsFilter:
+    PLACEHOLDER = "·"  # instances pick `?` when stdout cannot encode it
+    _KEEP = "\r\n\t\b"
+    _BAD_CATEGORIES = frozenset(["Cc", "Cf", "Cs", "Co", "Cn", "Zl", "Zp"])
+    _SGR_SIMPLE = frozenset(
+        [0, 1, 2, 3, 4, 22, 23, 24, 27, 39, 49,
+         *range(30, 38), *range(40, 48), *range(90, 98), *range(100, 108)]
+    )
+    _MAX_PARAMS = 32
+    _MAX_CSI = 64
+    _MAX_STR = 4096
+    _MAX_INTER = 16
+
+    def __init__(self):
+        self.PLACEHOLDER = _placeholder()
+        self._enc = getattr(_sys.stdout, "encoding", None) or "ascii"
+        self._enc_ok = {}
+        self._state = "ground"  # ground|esc|inter|csi|str|stresc
+        self._buf = ""
+
+    def tx(self, text):
+        return text
+
+    def echo(self, text):
+        return text
+
+    def rx(self, text):
+        out = []
+        for ch in text:
+            self._step(ch, out)
+        return "".join(out)
+
+    def _reset(self):
+        self._state = "ground"
+        self._buf = ""
+
+    def _drop(self, out):
+        out.append(self.PLACEHOLDER)
+        self._reset()
+
+    def _encodable(self, ch):
+        ok = self._enc_ok.get(ch)
+        if ok is None:
+            try:
+                ch.encode(self._enc)
+                ok = True
+            except (UnicodeError, LookupError):
+                ok = False
+            if len(self._enc_ok) < 4096:
+                self._enc_ok[ch] = ok
+        return ok
+
+    def _printable(self, ch):
+        if ch in self._KEEP:
+            return True
+        return _ud.category(ch) not in self._BAD_CATEGORIES and self._encodable(ch)
+
+    def _sgr(self, params):
+        # `params` is already known to match ^[0-9;]{0,32}$
+        if params == "":
+            return "\x1b[0m"
+        vals = [int(p) if p else 0 for p in params.split(";")]
+        kept, i = [], 0
+        while i < len(vals):
+            v = vals[i]
+            if v in (38, 48):
+                mode = vals[i + 1] if i + 1 < len(vals) else None
+                if mode == 5 and i + 2 < len(vals) and vals[i + 2] <= 255:
+                    kept += [v, 5, vals[i + 2]]
+                    i += 3
+                    continue
+                if mode == 2 and i + 4 < len(vals) and max(vals[i + 2:i + 5]) <= 255:
+                    kept += [v, 2, *vals[i + 2:i + 5]]
+                    i += 5
+                    continue
+                break  # malformed extended colour: drop the remainder
+            if v in self._SGR_SIMPLE:
+                kept.append(v)
+            i += 1
+        if not kept:
+            return ""
+        return "\x1b[" + ";".join(str(k) for k in kept) + "m"
+
+    def _step(self, ch, out):
+        st = self._state
+        o = ord(ch)
+        if st == "ground":
+            if ch == "\x1b":
+                self._state = "esc"
+            elif o == 0x9B:
+                self._state, self._buf = "csi", ""
+            elif o in (0x90, 0x98, 0x9D, 0x9E, 0x9F):
+                self._state, self._buf = "str", ""
+            elif self._printable(ch):
+                out.append(ch)
+            else:
+                out.append(self.PLACEHOLDER)  # C0, C1, DEL, CAN, SUB, format, ...
+            return
+        if ch in "\x18\x1a":  # CAN / SUB abort any sequence in progress
+            self._drop(out)
+            return
+        if st == "esc":
+            if ch == "[":
+                self._state, self._buf = "csi", ""
+            elif ch in "]PX^_":
+                self._state, self._buf = "str", ""
+            elif 0x20 <= o <= 0x2F:
+                self._state, self._buf = "inter", ""
+            elif ch == "\x1b":
+                out.append(self.PLACEHOLDER)  # ESC ESC: still in esc
+            elif 0x30 <= o <= 0x7E:
+                self._drop(out)  # two-byte sequence (ESC c, ESC =, ...)
+            else:
+                self._drop(out)
+                self._step(ch, out)  # honour newline etc.; C1 starts its own sequence
+        elif st == "inter":
+            if 0x20 <= o <= 0x2F:
+                self._buf += ch
+                if len(self._buf) > self._MAX_INTER:
+                    self._drop(out)
+            elif 0x30 <= o <= 0x7E:
+                self._drop(out)  # ESC ( B etc.
+            elif ch == "\x1b":
+                self._drop(out)
+                self._state = "esc"
+            else:
+                self._drop(out)
+                self._step(ch, out)
+        elif st == "csi":
+            if 0x20 <= o <= 0x3F:
+                self._buf += ch
+                if len(self._buf) > self._MAX_CSI:
+                    self._drop(out)
+            elif 0x40 <= o <= 0x7E:
+                params = self._buf
+                if (
+                    ch == "m"
+                    and len(params) <= self._MAX_PARAMS
+                    and all(c in "0123456789;" for c in params)
+                ):
+                    out.append(self._sgr(params))
+                    self._reset()
+                else:
+                    self._drop(out)
+            elif ch == "\x1b":
+                self._drop(out)
+                self._state = "esc"
+            else:
+                self._drop(out)  # any other control or non-ASCII aborts it
+                self._step(ch, out)
+        elif st == "str":
+            if ch == "\x07" or o == 0x9C:
+                self._drop(out)
+            elif ch == "\x1b":
+                self._state = "stresc"
+            else:
+                self._buf += ch
+                if len(self._buf) > self._MAX_STR:
+                    self._drop(out)
+        elif st == "stresc":
+            if ch == "\\":
+                self._drop(out)  # ESC \ = ST
+            else:
+                self._drop(out)  # anything else aborts the string...
+                self._state = "esc"  # ...and the ESC starts a new sequence
+                if ch != "\x1b":
+                    self._step(ch, out)
+'''
+
+#: Run by `python -c` for the spawned console: define the filter, register it
+#: in miniterm's own table, hand over to miniterm's `main()` (argv follows).
+BOOTSTRAP = (
+    SOURCE
+    + "\nfrom serial.tools import miniterm as _m\n"
+    + "_m.TRANSFORMATIONS['colors'] = ColorsFilter\n"
+    + "_m.main()\n"
+)
+
+_ns: dict = {}
+exec(compile(SOURCE, "<tan.core.console_filter.SOURCE>", "exec"), _ns)  # noqa: S102
+ColorsFilter = _ns["ColorsFilter"]