ttyscan 0.0.2__py3-none-any.whl

ttyscan-0.0.2.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: ttyscan
+Version: 0.0.2
+Summary: Queries a terminal emulator for its type, size and capabilities
+Project-URL: Homepage, https://github.com/jquast/ttyscan
+Author-email: Jeff Quast <contact@jeffquast.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: capability,colorterm,console,curses,query,serial,setupterm,ssh,telnet,terminal,terminfo,tty,xtgettcap
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Requires-Python: >=3.8
+Description-Content-Type: text/x-rst
+
+| |pypi_downloads| |codecov| |windows| |linux| |mac| |bsd|
+
+ttyscan
+=======
+
+*ttyscan* queries a terminal emulator for its type, size and capabilities, creating a
+curses-compatible `terminfo(5)`_ file entry if necessary, and exports any corrected values of
+``TERM``, ``COLORTERM``, ``LINES``, ``COLUMNS``, and optionally ``TERMCAP`` environment variables.
+
+Problem
+-------
+
+ncurses_ does not support XTGETTCAP, and so `terminfo(5)`_ files for some terminals must be
+deployed to remote systems by system operators in some circumstances.
+
+Curses programs fail to start until those files are deployed or an alternate ``TERM`` is exported.
+All kinds of errors and warnings may be raised until this is done, some examples::
+
+       $ tmux attach
+       missing or unsuitable terminal: xterm-kitty
+
+       $ irssi
+       setupterm() failed for TERM=xterm-kitty: 0
+       Can't initialize screen handling.
+
+       $ htop
+       Error opening terminal: xterm-kitty.
+
+       $ python -c 'import curses;curses.setupterm()'
+       Traceback (most recent call last):
+         File "<string>", line 1, in <module>
+       _curses.error: setupterm: could not find terminal
+
+       $ git log -p
+       WARNING: terminal is not fully functional
+       Press RETURN to continue 
+
+Solution
+--------
+
+*ttyscan* creates the missing `terminfo(5)` file using the ``XTGETTCAP`` (``DCS +q``) terminal query
+protocol when supported, and suggests a new ``TERMINFO`` environment value for export, allowing
+legacy calls to curses of `setupterm(3)`_ to succeed::
+
+       $ ttyscan -vft
+       ttyscan: probing terminal via XTGETTCAP ...
+       ttyscan: size via dual CPR: 28x100
+       ttyscan: XTGETTCAP supported, terminal: rio; received 204 caps (10 bool, 5 num, 185 str) in 1523ms
+       ttyscan: writing /home/jq/.config/ttyscan/terminfo/r/rio
+       export COLORTERM=truecolor
+       export TERM=rio
+       export LINES=28
+       export COLUMNS=100
+       export TERMINFO=/home/jq/.config/ttyscan/terminfo
+       export TERMCAP='rio|XTGETTCAP-discovered terminal::am::ut::hs::km::5i::mi::ms::NP::xn::Co#256::co#80::it#8::li#24::pa#32767::ac=``aaffggiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~::bl=^G::mb=\E[5m::md=\E[1m::vi=\E[?25l::cl=\E[H\E[2J::ve=\E[?12l\E[?25h::cr=\r::cs=\E[%i%p1%d;%p2%dr::le=\b::DO=\E[%p1%dB::do=\n::nd=\E[C::cm=\E[%i%p1%d;%p2%dH::up=\E[A::vs=\E[?12;25h::dC=\E[P::mh=\E[2m::dl=\E[M::ds=\E]2;^G::ec=\E[%p1%dX::cd=\E[J::ce=\E[K::cb=\E[1K::vb=\E[?5h$<100/>\E[?5l::fs=^G::ho=\E[H::ch=\E[%i%p1%dG::ta=\t::st=\EH::al=\E[L::sf=\n::mk=\E[8m::is=\E[!p\E[?3;4l\E[4l\E>::K2=\EOE::kb=^?::kB=\E[Z::kl=\EOD::kd=\EOB::kr=\EOC::ku=\EOA::kD=\E[3~::@7=\EOF::@8=\EOM::k1=\EOP::k0=\E[21~::F1=\E[23~::F2=\E[24~::k2=\EOQ::k3=\EOR::k4=\EOS::k5=\E[15~::k6=\E[17~::k7=\E[18~::k8=\E[19~::k9=\E[20~::kh=\EOH::kI=\E[2~::kH=\E[1;2B::kN=\E[6~::kP=\E[5~::op=\E[39;49m::rp=%p1%c\E[%p2%{1}%-%db::mr=\E[7m::sr=\EM::ZR=\E[23m::ae=\E(B::te=\E[?1049l\E[23;0;0t::ei=\E[4l::ke=\E[?1l\E>::se=\E[27m::ue=\E[24m::r1=\Ec\E]104^G::r2=\E[!p\E[?3;4l\E[4l\E>::sa=%?%p9%t\E(0%e\E(B%;\E[0%?%p6%t;1%;%?%p5%t;2%;%?%p2%t;4%;%?%p1%p3%|%t;7%;%?%p4%t;5%;%?%p7%t;8%;m::me=\E(B\E[m::ZH=\E[3m::as=\E(0::ti=\E[?1049h\E[22;0;0t::im=\E[4h::ks=\E[?1h\E=::so=\E[7m::us=\E[4m::ct=\E[3g::ts=\E]2;::cv=\E[%i%p1%dd:' 
+
+       $ eval `ttyscan`
+
+       $ echo $TERM, $TERMINFO
+       rio, /home/jquast/.config/ttyscan/terminfo
+
+       $ file -b /home/jquast/.config/ttyscan/terminfo/r/rio
+       Compiled terminfo entry "rio"
+
+       $ python -c 'import curses;curses.setupterm()'; echo $?
+       0
+
+CLI Arguments
+-------------
+
+::
+
+    usage: ttyscan [-h] [-v] [-f] [-t]
+
+    Export terminal capabilities discovered via XTGETTCAP
+
+    options:
+      -h, --help     show this help message and exit
+      -v, --verbose  Print diagnostic information to stderr
+      -f, --force    Force export of all values even if unchanged
+      -t, --termcap  Also export TERMCAP value
+
+*ttyscan* saves a `terminfo(5)`_ file to $XDG_CONFIG_HOME/ttyscan/terminfo or
+~/.config/ttyscan/terminfo, and does not re-query or re-create it when it already exists from
+previous executions, unless ``--force`` argument is used.
+
+Typical total execution time is 200ms.  The default timeout query can be changed by environment
+value TTYSCAN_QUERY_TIMEOUT=1.0 (float), in seconds. If timeout is reached, terminal response may
+"bleed" into subsequent programs, (like a shell prompt).
+
+Installation
+------------
+
+.. code-block:: shell
+
+   pip install ttyscan
+
+*ttyscan* requires Python3.8+.
+
+ttyscan.py_ is a stand-alone python file, it does not require pip to install, you can copy this
+single file directly from source and execute it from source, eg. ``python ~/bin/ttyscan.py``
+
+Motive
+------
+
+Naturally, transferring your ``$HOME/.terminfo`` folder to a remote machine is the best solution.
+
+However, enterprise systems, bastion hosts, cloud systems, web consoles, hypervisors, radio, and
+serial ports can be challenging places or protocol layers through which to deploy terminfo files.
+
+Some workarounds include exporting a generally-compatible ``TERM=xterm-256color`` or ``xterm`` with
+sometimes minor corruption of screen output, missed interpretation of keyboard input such as
+backspace or delete, or a small reduction of features such as italic or underlined text or number of
+colors.
+
+**And so this tool is not often needed** except for the **very serious** terminal connoisseur.
+
+It serves as a demonstration: that a full terminal capability database *can* be transferred using
+XTGETTCAP_ for many modern terminals, supporting modern `terminfo(5)`_ and legacy `termcap(5)`_.  It
+
+My hope is that `setupterm(3)`_ may negotiate with full XTGETTCAP_ support at some point in the
+future, and that this utility is not commonly used or required!
+
+Scope
+-----
+
+At time of this writing (May 2026), the ucs-detect_ dataset of 42 terminals shows three categories
+of support for ``XTGETTCAP``:
+
+- **Full** ``XTGETTCAP`` capability support: contour_, foot_, ghostty_, kitty_, rio, and wezterm
+  transmit their complete terminfo boolean, numeric, and string capabilities via XTGETTCAP_.
+
+  *ttyscan* produces terminfo files for only these terminals.  *ttyscan* may also discover a
+  preferred ``TERM`` from ``TN``, and ``COLORTERM=truecolor`` from ``RGB``.
+
+- **Partial** ``XTGETTCAP`` capability support: XTerm_, iterm2, mlterm, AbsoluteTelnet/SSH, GNOME
+  Terminal, LXTerminal, terminator, termit, and xfce4-terminal report only ``TN``, ``Co``, and
+  ``RGB``.
+
+  *ttyscan* may only discover preferred ``TERM`` from ``TN``, and ``COLORTERM=truecolor`` from
+  ``RGB``.
+
+  XTerm_ supports only keyboard sequences in addition to ``TN``, ``Co``, and ``RGB``. It does not
+  report *all* capabilities, and so a `terminfo(5)`_ entry cannot be built. However,
+  ``TERM=xterm-256color`` and ``TERM=xterm`` are the most ubiquitous terminal name, you should be
+  just fine.
+
+- **None**: alacritty (refuses: `alacritty/vte#98`_), bobcat, cmd.exe, ConEmu, cool-retro-term,
+  Extraterm, Hyper, Konsole (requested: `KDE#507017`_), linux fbdev, mintty, PuTTY, QTerminal,
+  rxvt-unicode, screen, securecrt, st, Tabby, Apple Terminal, Terminal.exe (planned:
+  `microsoft/terminal#17735`_), terminology, tmux (passthrough: `tmux/tmux#3755`_), libvterm, VS
+  Code (xterm.js, proposal: `xtermjs/xterm.js#4107`_), weston-terminal, and zutty.
+
+Architecture
+------------
+
+*ttyscan* uses the following,
+
+- ``XTGETTCAP`` field ``TN`` is used to correct ``TERM`` when unmatched.
+- ``XTGETTCAP`` field ``RGB`` is used to correct ``COLORTERM`` when unmatched.
+- all capability strings, keyboard and screen, when provided by ``XTGETTCAP``.
+- DEC Private Mode 2048 (In-Band Resize) to determine the window size
+- Or failing that, using Cursor Position Report sequence like done in XTerm's `resize.c
+  <https://github.com/joejulian/xterm/blob/master/resize.c>`_
+
+Details
+-------
+
+The difference of *Full* and *Partial* ``XTGETTCAP`` support is best described by foot_:
+
+  ``XTGETTCAP`` is an escape sequence initially introduced by XTerm_, and also implemented (and extended,
+  to some degree) by Kitty.
+ 
+  Applications using this feature do not need to use the classic, file-based, terminfo definition.
+ 
+  XTerm's implementation (as of XTerm-370) only supports querying key (as in keyboard keys)
+  capabilities, and three custom capabilities:
+  
+  ``TN`` - terminal name
+  ``Co`` - number of colors (alias for the colors capability)
+  ``RGB`` - number of bits per color channel (different semantics from the RGB capability in file-based
+  terminfo definitions!).
+ 
+  Kitty has extended this, and also supports querying all integer and string capabilities.
+ 
+  Foot supports this, and extends it even further, to also include boolean capabilities.
+  This means foot's entire terminfo can be queried via ``XTGETTCAP``.
+
+Further, all of ``TERM``, ``COLORTERM``, ``LINES``, or ``COLUMNS`` may not be transmitted by all
+software or protocols, some examples:
+
+- ssh does not forward ``COLORTERM`` unless configured using ``SendEnv`` in `ssh_config(5)`_ and
+  ``AcceptEnv`` in `sshd_config(5)`_.
+- serial does not forward any; ``TERM`` is defined by host `agetty(8)`_ configuration, for example.
+- rlogin can forward all but ``COLORTERM``.
+- telnet can forward all, but IAC NAWS and NEW-ENVIRON capability varies by software.
+- websocket cannot forward any without customization, often used in-browser.
+
+*ttyscan* detects when these variables are unset or do not match values and re-exports the corrected
+values when they differ.
+
+.. _`agetty(8)`: https://linux.die.net/man/8/agetty
+.. _`alacritty/vte#98`: https://github.com/alacritty/vte/issues/98
+.. _contour: https://github.com/contour-terminal/contour
+.. _foot: https://codeberg.org/dnkl/foot#xtgettcap
+.. _ghostty: https://mitchellh.com/writing/ghostty-devlog-004
+.. _`KDE#507017`: https://bugs.kde.org/show_bug.cgi?id=507017
+.. _kitty: https://sw.kovidgoyal.net/kitty/kittens/query_terminal/
+.. _`microsoft/terminal#17735`: https://github.com/microsoft/terminal/issues/17735
+.. _ncurses: https://invisible-island.net/ncurses/
+.. _`setupterm(3)`: https://linux.die.net/man/3/setupterm
+.. _`ssh_config(5)`: https://linux.die.net/man/5/ssh_config
+.. _`sshd_config(5)`: https://linux.die.net/man/5/sshd_config
+.. _`termcap(5)`: https://linux.die.net/man/5/termcap
+.. _`terminfo(5)`: https://linux.die.net/man/5/terminfo
+.. _`tmux/tmux#3755`: https://github.com/tmux/tmux/issues/3755
+.. _`ttyscan.py`: https://github.com/jquast/ttyscan/blob/master/ttyscan.py
+.. _ucs-detect: https://ucs-detect.readthedocs.io/results.html#terminal-capabilities
+.. _XTerm: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-Device-Control-functions:DCS-plus-q-Pt-ST.F95
+.. _`xtermjs/xterm.js#4107`: https://github.com/xtermjs/xterm.js/issues/4107
+.. _XTGETTCAP: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-Device-Control-functions:DCS-plus-q-Pt-ST.F95
+
+.. |pypi_downloads| image:: https://img.shields.io/pypi/dm/ttyscan.svg?logo=pypi
+    :alt: Downloads
+    :target: https://pypi.org/project/ttyscan/
+.. |codecov| image:: https://codecov.io/gh/jquast/ttyscan/branch/master/graph/badge.svg
+    :alt: codecov.io Code Coverage
+    :target: https://codecov.io/gh/jquast/ttyscan/
+.. |linux| image:: https://img.shields.io/badge/Linux-yes-success?logo=linux
+    :alt: Linux supported
+.. |windows| image:: https://img.shields.io/badge/Windows-yes-success?logo=windows
+    :alt: Windows supported
+.. |mac| image:: https://img.shields.io/badge/MacOS-yes-success?logo=apple
+    :alt: MacOS supported
+.. |bsd| image:: https://img.shields.io/badge/BSD-yes-success?logo=freebsd
+    :alt: BSD supported

ttyscan-0.0.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+ttyscan.py,sha256=YAtuy0ARA1_KCmm9WjAdbnouUaATqOjPy0xyTIDRVRE,27884
+ttyscan-0.0.2.dist-info/METADATA,sha256=YeDQyD7YfzjhSMP_GoOEE9LZu6Tkswr254fRxpPRqjc,12768
+ttyscan-0.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ttyscan-0.0.2.dist-info/entry_points.txt,sha256=D3_mvwKz7kJJ4cTivulSnFf_njTLHNuoAEFyUeIOTs8,41
+ttyscan-0.0.2.dist-info/licenses/LICENSE,sha256=s66usgtPL2otKLK6u_6HLrUKkIz4mEMUNkNf3-uItds,1067
+ttyscan-0.0.2.dist-info/RECORD,,

ttyscan-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ttyscan-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ttyscan = ttyscan:main

ttyscan-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Quast
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ttyscan.py

@@ -0,0 +1,805 @@
+#!/usr/bin/env python3
+
+import argparse
+import array
+import os
+import re
+import select
+import struct
+import sys
+import time
+from pathlib import Path
+
+try:
+    import fcntl
+    import termios
+    import tty
+except ImportError as exc:
+    sys.exit(f"ttyscan: unsupported platform (missing required module: {exc})")
+
+__version__ = "0.0.2"
+
+
+def warn(msg):
+    print(f"ttyscan: {msg}", file=sys.stderr)
+
+
+try:
+    _TTYSCAN_QUERY_TIMEOUT = float(os.environ.get('TTYSCAN_QUERY_TIMEOUT', '1.0'))
+except ValueError:
+    warn(f"TTYSCAN_QUERY_TIMEOUT value "
+         f"{os.environ['TTYSCAN_QUERY_TIMEOUT']!r} "
+         f"is not a valid float, using default 1.0")
+    _TTYSCAN_QUERY_TIMEOUT = 1.0
+
+_CANONICAL_BOOL_CAPS = [
+    "bw", "am", "xsb", "xhp", "xenl", "eo", "gn", "hc", "km", "hs",
+    "in", "da", "db", "mir", "msgr", "os", "eslok", "xt", "hz", "ul",
+    "xon", "nxon", "mc5i", "chts", "nrrmc", "npc", "ndscr", "ccc", "bce",
+    "hls", "xhpa", "crxm", "daisy", "xvpa", "sam", "cpix", "lpix",
+    "OTbs", "OTns", "OTnc", "OTMT", "OTNL", "OTpt", "OTxr",
+]
+
+_CANONICAL_NUM_CAPS = [
+    "cols", "it", "lines", "lm", "xmc", "pb", "vt", "wsl", "nlab",
+    "lh", "lw", "ma", "wnum", "colors", "pairs", "ncv", "bufsz",
+    "spinv", "spinh", "maddr", "mjump", "mcs", "mls", "npins",
+    "orc", "orl", "orhi", "orvi", "cps", "widcs", "btns",
+    "bitwin", "bitype", "OTug", "OTdC", "OTdN", "OTdB", "OTdT", "OTkn",
+]
+
+_CANONICAL_STR_CAPS = [
+    "cbt", "bel", "cr", "csr", "tbc", "clear", "el", "ed", "hpa",
+    "cmdch", "cup", "cud1", "home", "civis", "cub1", "mrcup", "cnorm",
+    "cuf1", "ll", "cuu1", "cvvis", "dch1", "dl1", "dsl", "hd", "smacs",
+    "blink", "bold", "smcup", "smdc", "dim", "smir", "invis", "prot",
+    "rev", "smso", "smul", "ech", "rmacs", "sgr0", "rmcup", "rmdc",
+    "rmir", "rmso", "rmul", "flash", "ff", "fsl", "is1", "is2", "is3",
+    "if", "ich1", "il1", "ip", "kbs", "ktbc", "kclr", "kctab", "kdch1",
+    "kdl1", "kcud1", "krmir", "kel", "ked", "kf0", "kf1", "kf10", "kf2",
+    "kf3", "kf4", "kf5", "kf6", "kf7", "kf8", "kf9", "khome", "kich1",
+    "kil1", "kcub1", "kll", "knp", "kpp", "kcuf1", "kind", "kri", "khts",
+    "kcuu1", "rmkx", "smkx", "lf0", "lf1", "lf10", "lf2", "lf3", "lf4",
+    "lf5", "lf6", "lf7", "lf8", "lf9", "rmm", "smm", "nel", "pad", "dch",
+    "dl", "cud", "ich", "indn", "il", "cub", "cuf", "rin", "cuu", "pfkey",
+    "pfloc", "pfx", "mc0", "mc4", "mc5", "rep", "rs1", "rs2", "rs3", "rf",
+    "rc", "vpa", "sc", "ind", "ri", "sgr", "hts", "wind", "ht", "tsl",
+    "uc", "hu", "iprog", "ka1", "ka3", "kb2", "kc1", "kc3", "mc5p", "rmp",
+    "acsc", "pln", "kcbt", "smxon", "rmxon", "smam", "rmam", "xonc",
+    "xoffc", "enacs", "smln", "rmln", "kbeg", "kcan", "kclo", "kcmd",
+    "kcpy", "kcrt", "kend", "kent", "kext", "kfnd", "khlp", "kmrk",
+    "kmsg", "kmov", "knxt", "kopn", "kopt", "kprv", "kprt", "krdo",
+    "kref", "krfr", "krpl", "krst", "kres", "ksav", "kspd", "kund",
+    "kBEG", "kCAN", "kCMD", "kCPY", "kCRT", "kDC", "kDL", "kslt", "kEND",
+    "kEOL", "kEXT", "kFND", "kHLP", "kHOM", "kIC", "kLFT", "kMSG", "kMOV",
+    "kNXT", "kOPT", "kPRV", "kPRT", "kRDO", "kRPL", "kRIT", "kRES",
+    "kSAV", "kSPD", "kUND", "rfi", "kf11", "kf12", "kf13", "kf14", "kf15",
+    "kf16", "kf17", "kf18", "kf19", "kf20", "kf21", "kf22", "kf23",
+    "kf24", "kf25", "kf26", "kf27", "kf28", "kf29", "kf30", "kf31",
+    "kf32", "kf33", "kf34", "kf35", "kf36", "kf37", "kf38", "kf39",
+    "kf40", "kf41", "kf42", "kf43", "kf44", "kf45", "kf46", "kf47",
+    "kf48", "kf49", "kf50", "kf51", "kf52", "kf53", "kf54", "kf55",
+    "kf56", "kf57", "kf58", "kf59", "kf60", "kf61", "kf62", "kf63",
+    "el1", "mgc", "smgl", "smgr", "fln", "sclk", "dclk", "rmclk", "cwin",
+    "wingo", "hup", "dial", "qdial", "tone", "pulse", "hook", "pause",
+    "wait", "u0", "u1", "u2", "u3", "u4", "u5", "u6", "u7", "u8", "u9",
+    "op", "oc", "initc", "initp", "scp", "setf", "setb", "cpi", "lpi",
+    "chr", "cvr", "defc", "swidm", "sdrfq", "sitm", "slm", "smicm",
+    "snlq", "snrmq", "sshm", "ssubm", "ssupm", "sum", "rwidm", "ritm",
+    "rlm", "rmicm", "rshm", "rsubm", "rsupm", "rum", "mhpa", "mcud1",
+    "mcub1", "mcuf1", "mvpa", "mcuu1", "porder", "mcud", "mcub", "mcuf",
+    "mcuu", "scs", "smgb", "smgbp", "smglp", "smgrp", "smgt", "smgtp",
+    "sbim", "scsd", "rbim", "rcsd", "subcs", "supcs", "docr", "zerom",
+    "csnm", "kmous", "minfo", "reqmp", "getm", "setaf", "setab", "pfxl",
+    "devt", "csin", "s0ds", "s1ds", "s2ds", "s3ds", "smglr", "smgtb",
+    "birep", "binel", "bicr", "colornm", "defbi", "endbi", "setcolor",
+    "slines", "dispc", "smpch", "rmpch", "smsc", "rmsc", "pctrm", "scesc",
+    "scesa", "ehhlm", "elhlm", "elohlm", "erhlm", "ethlm", "evhlm",
+    "sgr1", "slength", "OTi2", "OTrs", "OTnl", "OTbc", "OTko", "OTma",
+    "OTG2", "OTG3", "OTG1", "OTG4", "OTGR", "OTGL", "OTGU", "OTGD",
+    "OTGH", "OTGV", "OTGC", "meml", "memu", "box1",
+]
+
+_INIT_XTGETTCAP_CAPS = frozenset((
+    'TN', 'RGB', 'colors', 'blink', 'sitm', 'ritm', 'cvvis', 'Smulx', 'Setulc', 'Ms'
+))
+
+_FULL_XTGETTCAP_CAPS = tuple(
+    sorted(set(_CANONICAL_BOOL_CAPS) | set(_CANONICAL_NUM_CAPS) | set(_CANONICAL_STR_CAPS))
+)
+
+_BOOL_SET = frozenset(_CANONICAL_BOOL_CAPS)
+_NUM_SET = frozenset(_CANONICAL_NUM_CAPS)
+_STR_SET = frozenset(_CANONICAL_STR_CAPS)
+
+_RE_XTGETTCAP_RESPONSE = re.compile(
+    r'\x1bP([01])\+r([0-9a-fA-F]+)(?:=([0-9a-fA-F]*))?\x1b\\')
+_RE_CPR = re.compile(r'\x1b\[(\d+);(\d+)R')
+_RE_CPR_BOUNDARY = re.compile(r'\x1b\[[0-9]+;[0-9]+R')
+_RE_DECRPM = re.compile(r'\x1b\[\?(\d+);([0-4])\$y')
+_RE_RESIZE = re.compile(r'\x1b\[48;(\d+);(\d+);(\d+);(\d+)t')
+
+_TERMINFO_MAGIC = 0o432
+_TERMINFO_MAGIC2 = 0o1036
+_SENTINEL_ABSENT = -1
+
+_BOOL_INDEX = {name: idx for idx, name in enumerate(_CANONICAL_BOOL_CAPS)}
+_NUM_INDEX = {name: idx for idx, name in enumerate(_CANONICAL_NUM_CAPS)}
+_STR_INDEX = {name: idx for idx, name in enumerate(_CANONICAL_STR_CAPS)}
+
+_TERMINFO_ESCAPE = {
+    'E': '\x1b', 'e': '\x1b',
+    'n': '\n', 't': '\t', 'r': '\r',
+    'b': '\b', 'f': '\f', 's': ' ',
+    '\\': '\\', '^': '^', ':': ':',
+}
+
+_TERMINFO_TO_TERMCAP_BOOL = {
+    "am": "am", "bce": "ut", "km": "km", "mc5i": "5i",
+    "mir": "mi", "msgr": "ms", "npc": "NP", "xenl": "xn",
+    "hs": "hs", "in": "in", "da": "da", "db": "db",
+    "eo": "eo", "eslok": "es", "gn": "gn", "hc": "hc",
+    "hz": "hz", "lpix": "YB", "ndscr": "ND", "nrrmc": "NR",
+    "os": "os", "sam": "SA", "ul": "ul", "xb": "xb",
+    "xn": "xn", "xt": "xt",
+}
+
+_TERMINFO_TO_TERMCAP_NUM = {
+    "colors": "Co", "cols": "co", "lines": "li", "it": "it",
+    "pairs": "pa", "btns": "BT", "bufsz": "Ya", "lm": "lm",
+    "lh": "lh", "lw": "lw", "ma": "ma", "mw": "mw",
+    "ncv": "NC", "nlab": "Nl", "pb": "pb", "sg": "sg",
+    "ug": "ug", "vt": "vt", "ws": "ws", "wnum": "dw",
+    "wsl": "ws",
+}
+
+_TERMINFO_TO_TERMCAP_STR = {
+    "acsc": "ac", "bel": "bl", "blink": "mb", "bold": "md",
+    "cbt": "bt", "civis": "vi", "clear": "cl", "cnorm": "ve",
+    "cr": "cr", "csr": "cs", "cub1": "le", "cud": "DO",
+    "cud1": "do", "cuf1": "nd", "cup": "cm", "cuu1": "up",
+    "cvvis": "vs", "dch1": "dC", "dim": "mh", "dl1": "dl",
+    "dsl": "ds", "ech": "ec", "ed": "cd", "el": "ce",
+    "el1": "cb", "flash": "vb", "fsl": "fs", "home": "ho",
+    "hpa": "ch", "hts": "st", "ht": "ta", "ich1": "ic",
+    "il1": "al", "ind": "sf", "invis": "mk", "iprog": "iP",
+    "is1": "i1", "is2": "is", "is3": "i3", "kb2": "K2",
+    "kbs": "kb", "kcbt": "kB", "kcub1": "kl", "kcud1": "kd",
+    "kcuf1": "kr", "kcuu1": "ku", "kdch1": "kD", "kend": "@7",
+    "kent": "@8", "kf1": "k1", "kf2": "k2", "kf3": "k3",
+    "kf4": "k4", "kf5": "k5", "kf6": "k6", "kf7": "k7",
+    "kf8": "k8", "kf9": "k9", "kf10": "k0", "kf11": "F1",
+    "kf12": "F2", "kfnd": "kF", "khlp": "%1", "khome": "kh",
+    "kich1": "kI", "kind": "kH", "knp": "kN", "kpp": "kP",
+    "kprv": "kR", "kspd": "@9", "ktbc": "ka", "mc0": "ps",
+    "mc4": "pf", "mc5": "po", "mc5p": "pO", "nel": "nw",
+    "op": "op", "pad": "pc", "pln": "pn", "prot": "mp",
+    "rep": "rp", "rev": "mr", "ri": "sr", "rmacs": "ae",
+    "rmcup": "te", "rmdc": "ed", "rmir": "ei", "rmkx": "ke",
+    "rmso": "se", "rmul": "ue", "rs1": "r1", "rs2": "r2",
+    "rs3": "r3", "sgr": "sa", "sgr0": "me", "sitm": "ZH",
+    "ritm": "ZR", "smacs": "as", "smcup": "ti", "smdc": "dm",
+    "smir": "im", "smkx": "ks", "smso": "so", "smul": "us",
+    "tbc": "ct", "tsl": "ts", "vpa": "cv", "wind": "wi",
+    "wingo": "WS",
+}
+
+
+def verbose(msg, enabled):
+    if enabled:
+        print(f"ttyscan: {msg}", file=sys.stderr)
+
+
+def hex_encode(s):
+    return s.encode('ascii').hex()
+
+
+def hex_decode(h):
+    try:
+        return bytes.fromhex(h).decode('ascii', errors='strict')
+    except ValueError:
+        return ''
+
+
+def unescape_terminfo(value):
+    result = []
+    idx = 0
+    while idx < len(value):
+        cur = value[idx]
+        if cur == '\\' and idx + 1 < len(value):
+            nxt = value[idx + 1]
+            esc = _TERMINFO_ESCAPE.get(nxt)
+            if esc is not None:
+                result.append(esc)
+                idx += 2
+                continue
+            if nxt in '01234567':
+                end = idx + 1
+                while end < len(value) and value[end] in '01234567':
+                    end += 1
+                result.append(chr(int(value[idx + 1:end], 8)))
+                idx = end
+                continue
+        elif cur == '^' and idx + 1 < len(value):
+            nxt = value[idx + 1]
+            if 'A' <= nxt <= '_':
+                result.append(chr(ord(nxt) - ord('A') + 1))
+                idx += 2
+                continue
+            if nxt == '?':
+                result.append('\x7f')
+                idx += 2
+                continue
+        result.append(cur)
+        idx += 1
+    return ''.join(result)
+
+
+def open_tty():
+    try:
+        r_fd = os.open('/dev/tty', os.O_RDONLY | os.O_NOCTTY)
+        w_fd = os.open('/dev/tty', os.O_WRONLY | os.O_NOCTTY)
+        return r_fd, w_fd
+    except OSError as exc:
+        warn(f"cannot open /dev/tty: {exc}")
+        return None, None
+
+
+def get_winsize(fd):
+    try:
+        buf = array.array('H', [0, 0, 0, 0])
+        fcntl.ioctl(fd, termios.TIOCGWINSZ, buf)
+        return buf[1] or 80, buf[0] or 24
+    except OSError:
+        return 80, 24
+
+
+def set_cbreak(fd):
+    if fd is None:
+        return None
+    try:
+        saved = termios.tcgetattr(fd)
+        tty.setcbreak(fd)
+        return saved
+    except termios.error as exc:
+        warn(f"cannot set cbreak mode: {exc}")
+        return None
+
+
+def restore_termios(fd, saved):
+    if fd is None or saved is None:
+        return
+    try:
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+    except termios.error as exc:
+        warn(f"cannot restore terminal mode: {exc}")
+
+
+def write_all(fd, data):
+    if fd is None:
+        return
+    if isinstance(data, str):
+        data = data.encode('ascii', errors='replace')
+    remaining = data
+    while remaining:
+        try:
+            n = os.write(fd, remaining)
+            remaining = remaining[n:]
+        except OSError as exc:
+            warn(f"write error: {exc}")
+            break
+
+
+def read_available(r_fd, timeout):
+    buf = bytearray()
+    stime = time.monotonic()
+    max_size = 131072
+    while True:
+        timeleft = 0.0 if buf else timeout - (time.monotonic() - stime)
+        if not buf and timeleft <= 0:
+            break
+        try:
+            ready, _, _ = select.select([r_fd], [], [], timeleft)
+        except OSError as exc:
+            warn(f"select error: {exc}")
+            break
+        if not ready:
+            break
+        try:
+            chunk = os.read(r_fd, 4096)
+        except OSError as exc:
+            warn(f"read error: {exc}")
+            break
+        if not chunk:
+            break
+        buf.extend(chunk)
+        if len(buf) > max_size:
+            break
+    return bytes(buf)
+
+
+def read_until(r_fd, w_fd, queries, pattern, timeout):
+    for q in queries:
+        write_all(w_fd, q)
+    write_all(w_fd, b'\x1b[6n')
+    stime = time.monotonic()
+    buf = ''
+    max_size = 131072
+    while True:
+        timeleft = timeout - (time.monotonic() - stime)
+        if timeleft <= 0:
+            break
+        raw = read_available(r_fd, timeleft)
+        if not raw:
+            break
+        buf += raw.decode('latin-1', errors='replace')
+        if (match := re.search(pattern, buf)) is not None:
+            return match, buf
+        if len(buf) > max_size:
+            break
+    return None, buf
+
+
+def xtgettcap_query(r_fd, w_fd, caps, timeout):
+    if not caps:
+        return {}
+    queries = [f'\x1bP+q{hex_encode(c)}\x1b\\' for c in caps]
+    match, data = read_until(r_fd, w_fd, queries, _RE_CPR_BOUNDARY.pattern, timeout)
+    if match is None:
+        return {}
+    data = data[:match.start()] + data[match.end():]
+    capabilities = {}
+    for m in _RE_XTGETTCAP_RESPONSE.finditer(data):
+        if m.group(1) == '1':
+            name = hex_decode(m.group(2))
+            val_hex = m.group(3)
+            if val_hex is not None:
+                value = unescape_terminfo(hex_decode(val_hex))
+            else:
+                value = ''
+            capabilities[name] = value
+    return capabilities
+
+
+def decrqm_query(r_fd, w_fd, mode, timeout):
+    result = read_until(r_fd, w_fd,
+                        [f'\x1b[?{mode}$p'],
+                        _RE_CPR_BOUNDARY.pattern, timeout)
+    if (match := result[0]) is None:
+        return None
+    data = result[1][:match.start()] + result[1][match.end():]
+    for m in _RE_DECRPM.finditer(data):
+        if int(m.group(1)) == mode:
+            return int(m.group(2))
+    return None
+
+
+def detect_size(r_fd, w_fd, verbose_enabled):
+    has_inband = (decrpm := decrqm_query(r_fd, w_fd, 2048, 0.25)) is not None and decrpm == 2
+
+    if has_inband:
+        write_all(w_fd, '\x1b[?2048h')
+        raw = read_available(r_fd, 0.25).decode('latin-1', errors='replace')
+        if (resize_match := _RE_RESIZE.search(raw)):
+            rows = int(resize_match.group(1))
+            cols = int(resize_match.group(2))
+            verbose(f"size via Mode 2048 in-band: {rows}x{cols}", verbose_enabled)
+            write_all(w_fd, '\x1b[?2048l')
+            return rows, cols, 'inband'
+
+    cpr1_match, data = read_until(r_fd, w_fd, [], _RE_CPR.pattern, 0.25)
+    orig_y = orig_x = None
+    if cpr1_match:
+        orig_y = int(cpr1_match.group(1))
+        orig_x = int(cpr1_match.group(2))
+
+    write_all(w_fd, '\x1b[1000;1000H')
+    cpr2_match, _ = read_until(r_fd, w_fd, [], _RE_CPR.pattern, 0.25)
+
+    if has_inband:
+        write_all(w_fd, '\x1b[?2048l')
+
+    if orig_y is not None:
+        write_all(w_fd, f'\x1b[{orig_y};{orig_x}H')
+
+    if cpr2_match:
+        rows = int(cpr2_match.group(1))
+        cols = int(cpr2_match.group(2))
+        if rows == 999 or cols == 999:
+            verbose(f"rejecting bogus CPR size {rows}x{cols}", verbose_enabled)
+            return None
+        verbose(f"size via dual CPR: {rows}x{cols}", verbose_enabled)
+        return rows, cols, 'cpr'
+
+    verbose("CPR size detection", verbose_enabled)
+    write_all(w_fd, '\x1b[1000;1000H')
+    fb_match, _ = read_until(r_fd, w_fd, [], _RE_CPR.pattern, 0.25)
+    if fb_match:
+        rows = int(fb_match.group(1))
+        cols = int(fb_match.group(2))
+        if rows != 999 and cols != 999:
+            verbose(f"size via CPR: {rows}x{cols}", verbose_enabled)
+            return rows, cols, 'fallback_cpr'
+
+    verbose("size detection failed", verbose_enabled)
+    return None
+
+
+def classify_caps(capabilities):
+    bool_caps = set()
+    num_caps = {}
+    str_caps = {}
+    for name, value in capabilities.items():
+        if name == 'RGB':
+            continue
+        if not value:
+            if name in _BOOL_SET:
+                bool_caps.add(name)
+        elif name in _NUM_SET:
+            if value.isdigit():
+                num_caps[name] = int(value)
+        elif name in _STR_SET:
+            str_caps[name] = value
+    return {'bool_caps': bool_caps, 'num_caps': num_caps, 'str_caps': str_caps}
+
+
+def pack_short_le(buf, offset, value):
+    packed = struct.pack("<h", value)
+    buf[offset:offset + 2] = packed
+
+
+def build_terminfo_binary(term, str_caps, num_caps, bool_caps):
+    names = f"{term}|XTGETTCAP-discovered terminal"
+    names_bytes = names.encode("ascii", errors="replace") + b"\x00"
+    name_size = len(names_bytes)
+    bool_indices = [_BOOL_INDEX[cap] for cap in bool_caps if cap in _BOOL_INDEX]
+    bool_max = max(bool_indices) + 1 if bool_indices else 0
+    bool_data = bytearray(bool_max)
+    for idx in bool_indices:
+        bool_data[idx] = 1
+    num_entries = [(_NUM_INDEX[cap], val) for cap, val in num_caps.items()
+                   if cap in _NUM_INDEX]
+    num_max = max(idx for idx, _ in num_entries) + 1 if num_entries else 0
+    use_32bit = any(val > 32767 or val < -32768 for _, val in num_entries)
+    num_entry_size = 4 if use_32bit else 2
+    magic = _TERMINFO_MAGIC2 if use_32bit else _TERMINFO_MAGIC
+    num_data = bytearray(num_max * num_entry_size)
+    for idx, val in num_entries:
+        if use_32bit:
+            struct.pack_into("<i", num_data, idx * 4, val)
+        else:
+            pack_short_le(num_data, idx * 2, val)
+    num_used = set(idx for idx, _ in num_entries)
+    for i in range(num_max):
+        if i not in num_used:
+            if use_32bit:
+                struct.pack_into("<i", num_data, i * 4, _SENTINEL_ABSENT)
+            else:
+                pack_short_le(num_data, i * 2, _SENTINEL_ABSENT)
+    str_entries = [(_STR_INDEX[cap], val.encode("utf-8", errors="replace"))
+                   for cap, val in str_caps.items() if cap in _STR_INDEX]
+    str_max = max(idx for idx, _ in str_entries) + 1 if str_entries else 0
+    str_table_parts = []
+    offsets = {}
+    for idx, raw in sorted(str_entries):
+        offsets[idx] = len(b"".join(str_table_parts))
+        str_table_parts.append(raw + b"\x00")
+    str_table = b"".join(str_table_parts)
+    offset_data = bytearray(str_max * 2)
+    for i in range(str_max):
+        if i in offsets:
+            pack_short_le(offset_data, i * 2, offsets[i])
+        else:
+            pack_short_le(offset_data, i * 2, _SENTINEL_ABSENT)
+    header = bytearray(12)
+    pack_short_le(header, 0, magic)
+    pack_short_le(header, 2, name_size)
+    pack_short_le(header, 4, bool_max)
+    pack_short_le(header, 6, num_max)
+    pack_short_le(header, 8, str_max)
+    pack_short_le(header, 10, len(str_table))
+    parts = [bytes(header), names_bytes, bytes(bool_data)]
+    if (name_size + bool_max) % 2 != 0:
+        parts.append(b"\x00")
+    parts.append(bytes(num_data))
+    parts.append(bytes(offset_data))
+    parts.append(str_table)
+    return b"".join(parts)
+
+
+def sanitize_term_name(name):
+    cleaned = re.sub(r'[^a-zA-Z0-9._-]', '', name)
+    cleaned = cleaned.lstrip('.')
+    return cleaned if cleaned else 'unknown'
+
+
+def terminfo_file_path(term, base_dir):
+    return base_dir / term[0] / term
+
+
+def terminfo_installed_at(term, base_dir):
+    return terminfo_file_path(term, base_dir).exists()
+
+
+def ttyscan_terminfo_dir():
+    xdg = os.environ.get(
+        "XDG_CONFIG_HOME",
+        os.path.join(os.path.expanduser("~"), ".config"),
+    )
+    return Path(xdg) / "ttyscan" / "terminfo"
+
+
+def has_terminfo(term):
+    try:
+        import curses
+        curses.setupterm(term)
+        return bool(curses.tigetstr("clear"))
+    except Exception:
+        return False
+
+
+def write_terminfo(term, str_caps, num_caps, bool_caps, dest_dir):
+    safe_term = sanitize_term_name(term)
+    data = build_terminfo_binary(safe_term, str_caps, num_caps, bool_caps)
+    file_path = terminfo_file_path(safe_term, dest_dir)
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_bytes(data)
+    return True
+
+
+def escape_value(value, terminfo=False):
+    simple = {
+        "\x1b": "\\E", "\n": "\\n", "\t": "\\t", "\r": "\\r",
+        "\b": "\\b", "\f": "\\f", "\\": "\\\\", "^": "\\^",
+    }
+    if terminfo:
+        simple[" "] = "\\s"
+        simple[":"] = "\\:"
+    result = []
+    for ch in value:
+        if ch in simple:
+            result.append(simple[ch])
+            continue
+        code = ord(ch)
+        if code < 32:
+            result.append(f"^{chr(code + 64)}")
+        elif code == 127:
+            result.append("^?")
+        else:
+            result.append(ch)
+    return "".join(result)
+
+
+def shell_escape(value):
+    if not value:
+        return "''"
+    escaped = value.replace("'", "'\\''")
+    return f"'{escaped}'"
+
+
+def build_termcap_entry(term, str_caps, num_caps, bool_caps):
+    parts = [f"{term}|XTGETTCAP-discovered terminal:"]
+    for cap in sorted(bool_caps):
+        tc_name = _TERMINFO_TO_TERMCAP_BOOL.get(cap)
+        if tc_name:
+            parts.append(f":{tc_name}:")
+    for cap in sorted(num_caps):
+        tc_name = _TERMINFO_TO_TERMCAP_NUM.get(cap)
+        if tc_name:
+            parts.append(f":{tc_name}#{num_caps[cap]}:")
+    for cap in sorted(str_caps):
+        tc_name = _TERMINFO_TO_TERMCAP_STR.get(cap)
+        if tc_name:
+            value = escape_value(str_caps[cap])
+            parts.append(f":{tc_name}={value}:")
+    return "".join(parts)
+
+
+def normalize_terminal_name(raw):
+    if raw == "WezTerm":
+        return "wezterm"
+    return raw
+
+
+def has_meaningful_caps(str_caps, num_caps, bool_caps):
+    screen_str_caps = {k for k in str_caps if not k.startswith('k')}
+    if screen_str_caps:
+        return True
+    if bool_caps:
+        return True
+    meaningful_nums = {k for k in num_caps if k not in ('colors', 'Co')}
+    if meaningful_nums:
+        return True
+    return False
+
+
+def check_colorterm(caps, force):
+    rgb = caps.get("RGB", "")
+    try:
+        if rgb and int(rgb.split("/", 1)[0]) == 8:
+            if force or os.environ.get("COLORTERM") != "truecolor":
+                return "export COLORTERM=truecolor"
+    except ValueError:
+        pass
+    return None
+
+
+def check_term(caps, force):
+    tn = caps.get("TN")
+    if tn:
+        tn = normalize_terminal_name(tn)
+        if force or tn != os.environ.get("TERM"):
+            return f"export TERM={tn}"
+    return None
+
+
+def check_lines_columns(rows, cols, winsize, force):
+    term_cols, term_rows = winsize
+    if not force and (rows, cols) == (term_rows, term_cols):
+        if ((env_lines := os.environ.get("LINES")) is None or env_lines == str(rows)) and \
+           ((env_cols := os.environ.get("COLUMNS")) is None or env_cols == str(cols)):
+            return None
+    exports = []
+    env_lines = os.environ.get("LINES")
+    env_cols = os.environ.get("COLUMNS")
+    if force or env_lines != str(rows):
+        exports.append(f"export LINES={rows}")
+    if force or env_cols != str(cols):
+        exports.append(f"export COLUMNS={cols}")
+    return exports or None
+
+
+def generate_exports(verbose_enabled=False, force=False, termcap=False):
+    verbose("probing terminal via XTGETTCAP ...", verbose_enabled)
+
+    r_fd, w_fd = open_tty()
+    if r_fd is None or w_fd is None:
+        verbose("no terminal available", verbose_enabled)
+        return []
+
+    saved = set_cbreak(r_fd)
+    try:
+        winsize = get_winsize(r_fd)
+
+        init_caps = xtgettcap_query(r_fd, w_fd, _INIT_XTGETTCAP_CAPS,
+                                    timeout=_TTYSCAN_QUERY_TIMEOUT)
+        if not init_caps:
+            verbose("XTGETTCAP not supported by this terminal", verbose_enabled)
+            return []
+
+        tn_raw = init_caps.get("TN")
+        if not tn_raw:
+            verbose("no TN (terminal name) capability, cannot export further",
+                    verbose_enabled)
+            return []
+
+        tn = normalize_terminal_name(tn_raw)
+
+        exports = []
+
+        ct_export = check_colorterm(init_caps, force)
+        if ct_export:
+            exports.append(ct_export)
+
+        term_export = check_term(init_caps, force)
+        if term_export:
+            exports.append(term_export)
+
+        size = detect_size(r_fd, w_fd, verbose_enabled)
+        if size:
+            rows, cols, source = size
+            term_cols, term_rows = winsize
+            if source != 'inband' and (
+                rows == 999 or cols == 999
+                or rows < term_rows or cols < term_cols
+            ):
+                verbose(
+                    f"rejecting CPR size {rows}x{cols} "
+                    f"(term reports {term_rows}x{term_cols})",
+                    verbose_enabled,
+                )
+            else:
+                lc = check_lines_columns(rows, cols, winsize, force)
+                if lc:
+                    exports.extend(lc)
+
+        if not force and not termcap and has_terminfo(tn):
+            verbose(f"XTGETTCAP supported, terminal: {tn}", verbose_enabled)
+            verbose("terminfo already available in system database", verbose_enabled)
+            return exports
+
+        remaining_caps = [c for c in _FULL_XTGETTCAP_CAPS
+                          if c not in _INIT_XTGETTCAP_CAPS]
+        t0 = time.monotonic()
+        full_caps = xtgettcap_query(r_fd, w_fd, remaining_caps,
+                                    timeout=_TTYSCAN_QUERY_TIMEOUT)
+        elapsed_ms = int((time.monotonic() - t0) * 1000)
+
+        full_caps.update(init_caps)
+        classified = classify_caps(full_caps)
+        str_caps = classified['str_caps']
+        num_caps = classified['num_caps']
+        bool_caps = classified['bool_caps']
+
+        n_caps = len(full_caps)
+        verbose(
+            f"XTGETTCAP supported, terminal: {tn}; "
+            f"received {n_caps} caps "
+            f"({len(bool_caps)} bool, {len(num_caps)} num, {len(str_caps)} str) "
+            f"in {elapsed_ms}ms",
+            verbose_enabled,
+        )
+
+        if not has_meaningful_caps(str_caps, num_caps, bool_caps):
+            verbose(
+                "only bare-minimum capabilities (TN/colors/RGB), "
+                "skipping TERMINFO/TERMCAP export",
+                verbose_enabled,
+            )
+            return exports
+
+        terminfo_dir = ttyscan_terminfo_dir()
+        safe_term = sanitize_term_name(tn)
+
+        if not has_terminfo(tn) or force:
+            write_terminfo(tn, str_caps, num_caps, bool_caps, terminfo_dir)
+            verbose(f"writing {terminfo_file_path(safe_term, terminfo_dir)}",
+                    verbose_enabled)
+            terminfo_value = str(terminfo_dir)
+            current_terminfo = os.environ.get("TERMINFO")
+            if force or current_terminfo != terminfo_value:
+                exports.append(f"export TERMINFO={terminfo_value}")
+        else:
+            verbose("terminfo already available in system database", verbose_enabled)
+
+        if termcap:
+            entry = build_termcap_entry(tn, str_caps, num_caps, bool_caps)
+            if entry and (force or os.environ.get("TERMCAP") != entry):
+                exports.append(f"export TERMCAP={shell_escape(entry)}")
+
+        return exports
+
+    finally:
+        restore_termios(r_fd, saved)
+        if r_fd is not None:
+            try:
+                os.close(r_fd)
+            except OSError:
+                pass
+        if w_fd is not None:
+            try:
+                os.close(w_fd)
+            except OSError:
+                pass
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="ttyscan",
+        description="Export terminal capabilities discovered via XTGETTCAP",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true",
+        help="Print diagnostic information to stderr",
+    )
+    parser.add_argument(
+        "-f", "--force", action="store_true",
+        help="Force export of all values even if unchanged",
+    )
+    parser.add_argument(
+        "-t", "--termcap", action="store_true",
+        help="Also export TERMCAP value",
+    )
+    args = parser.parse_args(argv)
+
+    exports = generate_exports(
+        verbose_enabled=args.verbose,
+        force=args.force,
+        termcap=args.termcap,
+    )
+    for line in exports:
+        print(line)
+
+
+if __name__ == '__main__':
+    main()