tui-plugins

tmui와 stui를 위한 플러그인. 오픈소스(MIT)입니다. 다른 CLI의 출력을 도구의 표로 보여 주고, 그 명령을 키와 명령 줄에 붙입니다.

플러그인은 다른 CLI를 tmui나 stui로 들여옵니다. 그 출력을 도구의 표로 보여 주고, 그 명령을 키와 : 줄에 붙입니다. 플러그인은 plugin.json 파일 하나이고, 파일에 적히지 않은 것은 아무것도 실행하지 않습니다. tmui와 stui는 같은 파일을 읽습니다. 플러그인과 형식(SPEC.md, plugin.json v 1), 검사 도구는 sophonz-labs/tui-plugins(MIT)에 있습니다.

설치하기

tmui ext install gh-prs       # 저장소의 main 브랜치에서
tmui ext install ./my-plugin  # plugin.json이 든 디렉터리, 또는 그 파일의 경로나 URL
tmui ext list                 # 플러그인 목록과, 각각에서 빠진 것
tmui ext remove gh-prs

stui도 같은 명령을 받습니다: stui ext install gh-prs. 두 도구 모두 ext인 것은 stui plugin이 이미 다른 일, 즉 코딩 에이전트에게 stui의 오케스트레이션 스킬을 설치하는 일을 하기 때문입니다.

install은 아무것도 쓰기 전에 파일을 명세에 비춰 검사하고, 플러그인이 실행할 명령을 모두 보여 준 뒤 y/N으로 묻습니다(-y면 묻지 않습니다). 설치되는 곳은 도구 자신의 디렉터리 ~/.config/<도구>/plugins/<이름>/입니다. ~/.config/tui-plugins/<이름>/에 손으로 둔 플러그인은 두 도구가 함께 읽고, 두 디렉터리에 같은 이름이 있으면 도구 자신의 것이 이깁니다.

도구 안에서는 :ext가 플러그인과 각각이 더한 것, 빠진 것을 보여 주고 ?가 키를 보여 줍니다. 플러그인 화면은 :<이름>으로 엽니다(예: :prs). stui에서는 플러그인이 pane에 붙인 키가 agents 화면에서도 됩니다.

지금 있는 플러그인

플러그인	필요한 것	더하는 것
`gh-prs`	`gh`	`:prs`, pane이 있는 저장소의 pull request(pane이나 윈도우에서 `P`): `o` 브라우저, `d` diff, `c` 체크, `C` 체크아웃
`gh-runs`	`gh`	`:gh-runs`, 그 저장소의 GitHub Actions 런(pane이나 윈도우에서 `A`): `w` 팝업으로 지켜보기, `o` 브라우저, `L` 실패 로그, `r` 실패한 것 다시 실행
`docker-ps`	`docker`	`:containers`: `L` 로그, `e` 셸, `i` inspect, `S` 멈추기
`kubectl-pods`	`kubectl`	지금 컨텍스트의 `:pods`: `L` 로그, `d` describe, `e` 셸, `D` 지우기
`git-status`	`git`	pane 디렉터리의 `:git-status`(pane이나 윈도우에서 `S`): `d` diff, `a` 스테이지, `u` 스테이지 취소
`lazygit`	`lazygit`	세션, 윈도우, pane에서 `L`과 `:lazygit`. pane의 디렉터리에서 엽니다

필요한 프로그램이 PATH에 없어도 플러그인은 불러오고, :ext가 무엇이 없는지 알려 줍니다.

직접 만들기

플러그인에는 v, name과 함께 views, actions, commands 중 하나 이상이 있어야 합니다. 아래 플러그인은 pane 디렉터리의 파일을 보여 주고 고른 파일을 less로 엽니다.

{
  "v": 1,
  "name": "files",
  "description": "Files in the pane's directory.",
  "views": [
    {
      "name": "files",
      "run": ["ls", "-1"],
      "format": "lines",
      "cwd": "pane"
    }
  ],
  "actions": [
    { "key": "F", "title": "files", "scopes": ["panes", "windows"], "open": "files" },
    { "key": "v", "title": "view", "scopes": ["files"], "run": ["less", "{line}"], "mode": "foreground" }
  ]
}

views는 명령을 실행해 그 출력을 표로 보여 줍니다. 형식은 json(배열, 또는 줄마다 객체 하나), 머리 줄이 있는 tsv, lines입니다. 커서가 있는 줄의 필드가 자리표시자가 되고(여기서는 {line}), {session}, {window}, {pane}, {pane_cwd}, {pane_command}도 씁니다.
actions는 몇몇 화면의 키로, 명령을 실행하거나 화면을 엽니다. commands는 :<이름> [인자]입니다.
run은 셸 없이 실행되는 argv입니다. 자리표시자는 인자 하나의 일부를 채울 뿐 인자를 쪼개지 않으므로, x; rm -rf ~가 든 필드도 아무것도 실행하지 않습니다.
mode는 background(기본), foreground(명령이 터미널을 받습니다), popup(tmux 팝업)입니다. confirm은 먼저 y/N으로 묻습니다.
모르는 필드는 오류입니다. 그래서 "confirm"을 잘못 써도 묻지 않고 그냥 실행되는 일이 없습니다.

어떤 화면에서든 예약된 키가 있고, 그 키를 쓰는 파일은 잘못된 것입니다: j k g G h l q / : ? enter esc ctrl-b ctrl-f ctrl-r ctrl-c ctrl-e y Y와 숫자. y는 줄의 값을(플러그인 화면에서는 url 필드가 있으면 그것, 없으면 id), Y는 줄 전체를 복사합니다. 도구가 자기 화면에 쓰는 키나 다른 플러그인이 그 화면에서 먼저 가져간 키는 빠지고 :ext에 나옵니다. 도구 자신의 키가 늘 이깁니다.

그 밖의 것(새로 읽는 간격, 시간 제한, JSON의 안쪽 필드, 글자 그대로의 중괄호)은 SPEC.md에 있습니다.

만든 플러그인은 그 디렉터리에서 바로 설치해 봅니다.

tmui ext install ./my-plugin

tui-plugins를 클론한 곳에서 go run ./check .를 실행하면 저장소의 CI와 같은 방식으로 모든 plugins/<이름>/plugin.json을 검사합니다. 명세, 각 액션이 가리키는 화면, 두 플러그인이 같은 : 이름을 가져가지 않는지, README에 각각의 줄이 있는지를 봅니다.

저장소에 보내기

pull request로 plugins/ 아래에 플러그인 디렉터리를 더하고 README 표에 한 줄을 넣습니다. 보내는 법은 CONTRIBUTING.md에 있습니다.