TODO.md

This todo list describes ChrisAnt996's current intended roadmap for Clink's future. It is a living document and does not convey any guarantee about when or whether any item may be implemented.

IMPROVEMENTS

High Priority

Normal Priority

• Some way to push keys? (Push keys to Clink; not to other processes.)
• Some way for onbeginedit handler to short circuit and cause the edit line to return without showing a prompt or input, and either provide filtered input or go through onfilterinput (and maybe onendedit).
  • Ctrl+C/Break ideally would be able to interrupt a Lua script feedback loop where the script is using onbeginedit and onfilterinput to produce the effect of a looping script.

Low Priority

• Collecting words currently happens in update_internal, but probably it also belongs in alternative_matches and/or update_matches:
  • If a luafunc: macro first does anything that alters the line buffer, and then invokes a completion command, then the collected words will be inaccurate.
• Mouse input toggling is unreliable in Windows Terminal, and sometimes ends up disallowing mouse input.
• Once in a while raw mouse input sequences spuriously show up in the edit line; have only noticed it when the CMD window did not have focus at the time.
• Should coroutines really be able to make Readline redraw immediately? Should instead set a flag that the main coroutine responds to when it gains control again?

Follow Up

• Update other repos:
  • Add command and flag descriptions in clink-completions?
  • Push update to clink-completions repo.
  • Push update to z.lua repo.

Argmatcher syntax

• See the argmatcher_syntax branch.

INVESTIGATE

• Auto-update option, with configurable polling interval? (Though package managers like scoop can handle updates, if Clink was installed through one.)

APPENDICES

Manual Test Verifications

• Alt+Up to scroll up a line.
• git add in Cmder.
• git checkout Alt+= in Cmder.

Known Issues

• Readline 8.1 has slight bug in update_line; type c then l, and it now identifies 2 chars (cl) as needing to be displayed; seems like the diff routine has a bug with respect to the new faces capability; it used to only identify l as needing to be displayed.
• Cursor style may behave unexpectedly in a new console window launched from a Windows Terminal console, or in a console window that gets attached to Windows Terminal. This is because there's no reliable way for Clink to know whether it is running inside Windows Terminal.
• Perturbed PROMPT envvar is visible in child processes (e.g. piped shell in various file editors).
• #531 AV detects a trojan on download [This is likely because of the use of CreateRemoteThread and/or hooking OS APIs. There might be a way to obfuscate the fact that clink uses those, but ultimately this is kind of an inherent problem. Getting the binaries digitally signed might be the most effective solution, but that's financially expensive.]
• Terminal #10191 Microsoft Terminal does not allow a console application to know about or access the scrollback history, nor to scroll the screen. It blocks Clink's scrolling commands, and also the console.findline() function and everything else that relies on access to the scrollback history.

Mystery

• "qq": "QQ" in .inputrc, and then type qa --> infinite loop. [Was occurring in a 1.3.9 development build; but no longer repros in a later 1.3.9 build, and also does not repro in the 1.3.8 release build.]
• Windows 10.0.19042.630 seems to have problems when using WriteConsoleW with ANSI escape codes in a powerline prompt in a git repo. But Windows 10.0.19041.630 doesn't.
• Windows Terminal crashes on exit after clink inject. The current release version was crashing (1.6.10571.0). Older versions don't crash, and a locally built version from the terminal repo's HEAD doesn't crash. I think the crash is probably a bug in Windows Terminal, not related to Clink. And after I built it locally, then it stopped crashing with 1.6.10571.0 as well. Mysterious...

Punt

• Include wildmatch() and an fnmatch() wrapper for it. But should first update it to support UTF8. [Not worth the effort; and recursive match generation doesn't make much sense anyway. Could potentially be useful in globbing purposes other than match generation, though.]
• There's no straightforward way to let Lua scripts change the current directory and have CMD pick up the changed state. CMD maintains internal private state about what directory to use when running commands and programs. Running cd is the only way to alter CMD's internal private state.
• Explore adjusting default colors to have better contrast with white/light backgrounds? [No, it is tilting at windmills. Never mind about Clink; nothing else will work reasonably in light themes, either, at least not the way they're currently defined in Windows Terminal. If Windows Terminal fixes its themes, then it will become possible to have a single set of color definitions in Clink that work well in both light and dark themes. Until then, it doesn't make sense to make complicated attempts to overcome the broader external problems.]
• Recognizer and argmatcher lookup should support @ syntax; collecting words should support @ command syntax. [Not worth the effort; using @ at the command prompt has no effect anyway.]
• Make clink-show-help call out prefix key sequences, since they can behave in a confusing manner? [Complex present in a non-confusing way, and very rare to actually occur. Not worth the investment at this time.]
• Maybe deal with timeouts in keyboard input? Could differentiate Esc versus Esc,Esc but is very dangerous because it makes input processing unpredictable depending on the CPU availability. [Too dangerous. And turned out to not be the issue.]
• Ability to rearrange and edit popup list items? [Can't realistically rearrange or edit history, due to how the history file format works.]
• Using a thread to run globbers could let suggestions uses matches even with UNC paths. [But ONLY globbers would be safe; if anything else inside match generators tries to access the UNC path then it could hang. So it's not really safe enough.]
• Make scrolling key bindings work at the pager prompt. Note that it would need to revise how the scroll routines identify the bottom line (currently they use Readline's bottom line, but the pager displays output past that point). [Low value; also, Windows Terminal has scrolling hotkeys that supersede Clink, and it can scroll regardless whether prompting for input. Further, Windows Terminal is deprecating the ability for an app to scroll the screen anyway.]
• Is it a problem that update_internal() gets called once per char in a key sequence? Maybe it should only happen after a key that finishes a key binding? [Doesn't cause any noticeable issues.]
• Provide API to show an input box? But make it fail if used from outside a "luafunc:" macro. [Questionable usage pattern; just make the "luafunc:" macro invoke a standalone program (or even standalone Lua script) that can accept input however it likes.]
• Classify queued input lines? [Low value, high cost; the module layer knows about coloring, but queued lines are handled by the host layer without ever reaching the module layer. Also, the queued input lines ("More?") do not adhere to the current parsing assumptions; it would become necessary to carry argmatcher state across lines. Also, argmatchers do not currently understand ( or ).]
• Support this quirk, or not? Esc in conhost clears the line but does not reset the history index, but in Clink it resets the history index. Affects F1, F2, F3, F5, F8. [Defer until someone explains why it's important to them.]
• Additional ANSI escape codes.
  • ESC[?47h and ESC[?47l (save and restore screen) -- not widely supported, so I can't use it, and it's not worth emulating. Which makes me very sad; no save + show popup + restore. 😭
  • ESC[?1049h and ESC[?1049l (enable and disable alternative buffer) -- not worth using or emulating; there's no way to copying between screens, so it can't help for save/popup/restore.
• Marking mode in-app is not realistic:
  • Windows Terminal is essentially dropping support for console APIs that read/write the screen buffer, particularly the scrollback buffer.
  • Different terminal hosts have different capabilities and limitations, so building a marking mode that behaves reasonably across all/most terminal hosts isn't feasible.
  • One of the big opportunities for terminal hosts is to provide enhancements to marking and copy/paste.
  • So it seems best to leave marking and copy/paste as something for terminal hosts to provide.
• Lua API to copy text to clipboard (plain text or HTML) is not realistic, for the same technical reasons as for marking mode.
• Would be nice to complete "%ENVVAR%*" by internally expanding ENVVAR for collecting matches, but not expanding it in the editing line. However, it's difficult to make that work reasonably in conjunction with path normalization.
• ConsoleZ sometimes draws the prompt in the wrong color: scroll up, then type => the prompt is drawn in the input color instead of in the default color. It doesn't happen in conhost or ConEmu or Windows Terminal. Debugging indicates Clink is not redrawing the prompt, so it's entirely an internal issue inside ConsoleZ.
• Max input line length:
  • CMD has a max input buffer size of 8192 WCHARs including the NUL terminator.
  • ReadConsole does not allow more input than can fit in the input buffer size.
  • Readline allows infinite input size, and has no way to limit it.
  • There is a truncation problem here that does not exist without Clink.
  • However, even CMD itself silently fails to run an inputted command over 8100 characters, despite allowing 8191 characters to be input.
  • So I'm comfortable punting this for now.
• A way to disable/enable clink once injected. [Why?]
• #486 Ctrl+C doesn't always work properly [Unrelated to Clink; the exact same behavior occurs with plain cmd.exe]

---

Chris Antos - [email protected]