@ictechgy/lterm 1.0.8 → 1.0.10

package/README.ko.md

@@ -1,6 +1,6 @@
 # Light Terminal (`lterm`)
 
-한국어 | [English](README.md)
+한국어 | [English](README.md) | 🌐 [브라우저용 HTML 가이드](https://ictechgy.github.io/light_terminal/)
 
 ## TL;DR
 
@@ -29,8 +29,9 @@ agent가 보통 필요로 하는 더 작은 표면에 집중합니다.
   CLI, OpenCode, GitHub Copilot CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp, Crush, Kimi, Qwen, Gemini CLI, OMX/OMC 같은 terminal-first tooling이 쓰는 tmux command
   subset을 구현합니다.
 - **Raw attach, safe reports** — attach된 PTY stream은 TUI/interactive shell을
-  위해 raw로 유지하고, `logs`, `capture`, `list`, `doctor` 같은 report surface는
-  출력 전에 terminal control sequence를 sanitize합니다.
+  위해 raw로 유지합니다. 대신 `logs`, `capture`, `compose`, `doctor`,
+  `diagnose`, `notify` fallback 경로 같은 report surface는 terminal
+  control을 제거하면서도 한국어, CJK, emoji 같은 UTF-8 text는 보존합니다.
 - **cmux-friendly 설계** — notification과 tmux shim call이 generic desktop
   multiplexer보다 cmux/agent pane orchestration에 맞춰져 있습니다.
 - **내장 관측성** — `doctor` / `status`, bounded `logs --start/--end`,
@@ -75,7 +76,7 @@ GitHub에서 Cargo로 설치할 때는 release tag를 고정하세요. 아래
 README 릴리스 기준이며, 더 최신 tag가 있는지는 Releases 페이지에서 확인하세요:
 
 ```bash
-cargo install --locked --git https://github.com/ictechgy/light_terminal --tag v1.0.8
+cargo install --locked --git https://github.com/ictechgy/light_terminal --tag v1.0.10
 ```
 
 저장소를 클론한 뒤 직접 빌드하려면 Rust 1.85 이상이 필요합니다.
@@ -137,6 +138,7 @@ lterm -a api
 | 세션 status theme 설정 | `lterm status-theme api green` | `theme` |
 | 정제된 scrollback 읽기 | `lterm logs api --start=-80 --end=-1` | `capture` |
 | 디버깅용 raw PTY 출력 기록 | `lterm trace api --duration 5s --output trace.jsonl` | `record` |
+| 신뢰하는 raw PTY trace 재생 | `lterm trace-replay trace.jsonl` | `replay-trace` |
 | 정제된 scrollback 위에 입력 컴포저 열기 | `lterm compose api` | `mobile` |
 | 세션 출력 또는 종료 대기 | `lterm wait api --contains READY --timeout 30s --json` | 없음 |
 | 세션을 감시하고 완료 시 알림 | `lterm watch api --exit --notify` | 없음 |
@@ -191,11 +193,23 @@ escape 처리가 여기에 포함됩니다. 직접 `ssh`하듯 신뢰할 수 있
 
 `lterm doctor`(호환 이름: `lterm status`)는 client/daemon version, protocol 호환성, runtime/data/socket/shim path, shim directory가 `PATH`에 있는지 등을 보고합니다. 이 명령은 daemon을 시작하지 않습니다. 현재 socket에서 호환 daemon이 응답하지 않으면 `daemon_reachable=no` / `false`로 표시됩니다. 일반 client 동작 중 접근 가능한 daemon이 다른 lterm 또는 protocol version을 보고하면 stderr에 경고를 출력하며, 보통 binary upgrade 뒤 예전 daemon이 살아 있는 상황을 뜻합니다.
 
-`lterm logs <target>`은 `--start` / `-S`와 `--end` / `-E` line offset을 받습니다. 0 이상의 값은 absolute scrollback line index이고, 음수 값은 현재 scrollback line count에서 뒤로 셉니다. `--end`는 inclusive라 `lterm logs api -S0 -E0`은 첫 번째 줄만 capture합니다. Capture 출력은 계속 정제된 text이며, attach된 PTY stream은 raw 그대로 유지됩니다.
+`lterm logs <target>`은 `--start` / `-S`와 `--end` / `-E` line offset을 받습니다. 0 이상의 값은 absolute scrollback line index이고, 음수 값은 현재 scrollback line count에서 뒤로 셉니다. `--end`는 inclusive라 `lterm logs api -S0 -E0`은 첫 번째 줄만 capture합니다. Capture 출력은 계속 정제된 text입니다. 즉 terminal control은 제거하고 한국어, CJK, emoji 같은 UTF-8 text는 보존합니다. attach된 PTY stream은 raw 그대로 유지됩니다.
+
+`lterm trace <target> --duration 5s --output trace.jsonl`은 timestamp와
+hex-encoded bytes를 담은 private local JSONL 파일로 raw PTY 출력 chunk를
+기록합니다. 간헐적인 render 문제를 opt-in으로 디버깅하기 위한 기능이며,
+recorder는 JSONL artifact만 쓰고 raw capture는 `--max-bytes`(기본 16 MiB)
+한도 안에서 멈춥니다. 기존 trace file은 `--force` 없이는 덮어쓰지 않습니다.
+재생은 신뢰할 수 있는 trace에만 `lterm trace-replay <file>`로 수행하세요.
+`trace-replay`는 raw terminal bytes를 출력하기 전에 JSONL 전체를 먼저
+검증하고, 기본 trace capture 크기와 trace당 chunk 수 한도를 적용합니다.
 
 `lterm wait <target> --exit / --contains <text>`는 세션이 종료되거나 정제된 scrollback에 marker가 나타날 때까지 block합니다. 자동화용 health check에는 `--timeout 250ms|2s|5m|1h`, `--tail N`, `--json`을 함께 쓰세요. Timeout 시 `wait` / `watch`는 exit code `124`를 반환하고 JSON에는 `timed_out: true`가 들어갑니다. `lterm watch`는 같은 조건을 쓰며, `--notify`를 더하면 attach된 PTY bytes는 건드리지 않고 cmux-friendly 완료 알림을 보냅니다. `--json`을 함께 쓸 때는 notification fallback이 필요해도 stdout을 machine-readable JSON으로 유지합니다.
+지나치게 큰 `--contains` needle은 명시적 오류로 거부되며, daemon은 동시에
+block 중인 `wait` / `watch` check 수를 제한해 자동화가 무제한 waiter를
+만들지 못하게 합니다.
 
-`LTERM_STATUS_STYLE=full` 또는 `LTERM_STATUS_STYLE=minimal` 로 시각 스타일을 선택할 수 있습니다. `full`(로컬 터미널 기본값)은 색이 있는 bar를 그리고, `minimal`은 SGR 색을 모두 생략한 plain text로 동작합니다. SSH 세션(`SSH_CONNECTION` / `SSH_CLIENT` / `SSH_TTY` 감지)에서는 자동으로 `minimal`이 적용되어 Termius 같은 모바일 SSH 클라이언트의 색 충돌을 줄이지만, 세션 또는 환경 theme을 명시하면 색이 유지됩니다.
+`LTERM_STATUS_STYLE=full` 또는 `LTERM_STATUS_STYLE=minimal` 로 시각 스타일을 선택할 수 있습니다. `full`(로컬 터미널 기본값)은 색이 있는 bar를 그리고, `minimal`은 SGR 색을 모두 생략한 plain text로 동작합니다. SSH 세션(`SSH_CONNECTION` / `SSH_CLIENT` / `SSH_TTY` 감지)과 Termius 계열 클라이언트(터미널 식별 환경 변수 감지)에서는 자동으로 `minimal`이 적용되어 모바일 색상 매핑 문제를 줄이지만, 세션 또는 환경 theme을 명시하면 색이 유지됩니다.
 
 `LTERM_STATUS_THEME=blue|green|magenta|cyan|amber|red|gray|plain` 으로 attach client의 기본 status bar 색을 바꿀 수 있습니다. 세션별 override가 환경값보다 우선합니다: `lterm start --status-theme amber -n api -- npm run dev`, `lterm run --status-color cyan -- cargo test`, `lterm status-theme api plain`. 이 변수를 shell startup 파일에서 export하면 SSH attach도 colored status bar로 opt-in됩니다. 모바일 SSH client에서 plain text가 필요하면 unset하거나 `LTERM_STATUS_STYLE=minimal`을 설정하세요. Theme 이름은 고정 allowlist에서만 파싱되며, lterm은 사용자 입력 escape sequence를 status row에 임의 삽입하지 않습니다.
 
@@ -403,7 +417,7 @@ tmux `-f` filter는 조용히 무시하지 않고 의도적으로 거부합니
 
 1. worker 명령을 위한 새 `lterm` PTY 세션을 시작합니다.
 2. cmux에 native split 생성을 요청합니다 (`cmux new-split right/down`).
-3. `LTERM_BIN`이 `resume`을 모르는 구버전 `lterm`을 가리켜도 cmux pane이 계속 동작하도록, 생성된 split에는 호환 명령인 `lterm attach <pane>`을 보냅니다.
+3. 생성된 split에는 호환 명령인 `lterm attach <pane>`을 보냅니다. 안전한 absolute executable이 `LTERM_BIN`으로 지정되어 있으면 그 값을 사용하고, 아니면 현재 executable로 fallback합니다. 이 호환 명령 덕분에 `resume`을 모르는 구버전 build에서도 cmux pane이 계속 동작합니다.
 
 이렇게 하면 실제 pane은 cmux가 그리고, scrollback capture와 `send-keys` 호환은 `lterm`이 유지합니다.
 
@@ -447,12 +461,19 @@ lterm ssh devbox main -- -p 2222 -i ~/.ssh/id_ed25519
 
 **터미널 출력은 그대로 전달됩니다.** `lterm resume`(호환 이름: `lterm attach`)은 full-screen 터미널 프로그램과 cmux/OSC 알림이 정상 동작하도록 PTY byte를 그대로 통과시킵니다. 로컬 상태 바는 클라이언트 쪽 표시 요소일 뿐이며, 완전한 raw 모드 터미널이 필요하면 `--no-status`를 사용하세요. 신뢰할 수 없는 child 프로그램은 tmux/screen에서와 마찬가지로 attach된 터미널에 escape sequence를 출력할 수 있습니다. **`lterm`을 escape-sequence sanitizer나 sandbox로 사용하지 마세요.**
 
-**Capture 출력은 표시/로깅 전에 terminal control sequence를 제거합니다.** `lterm logs`(호환 이름: `lterm capture`), `lterm compose`(alias: `lterm mobile`), `tmux capture-pane`은 captured scrollback을 출력할 때 일반적인 터미널 제어 시퀀스를 제거합니다. 그래도 scrollback text는 신뢰할 수 없는 프로그램 출력일 수 있으므로 사람이나 agent에게 넘기기 전에 확인하세요. `compose`는 attach가 아닌 view에서 기존 input/send 경로로 텍스트를 commit하며, raw attached PTY stream을 변환하지 않습니다.
+**Capture 출력은 표시/로깅 전에 terminal control sequence를 제거합니다.** `lterm logs`(호환 이름: `lterm capture`), `lterm compose`(alias: `lterm mobile`), `tmux capture-pane`은 captured scrollback을 출력할 때 raw 또는 UTF-8 encoded C1 control을 포함한 터미널 제어 시퀀스를 제거합니다. 정상 UTF-8 text인 한국어, CJK, emoji는 보존합니다. 그래도 scrollback text는 신뢰할 수 없는 프로그램 출력일 수 있으므로 사람이나 agent에게 넘기기 전에 확인하세요. `compose`는 attach가 아닌 view에서 기존 input/send 경로로 텍스트를 commit하며, raw attached PTY stream을 변환하지 않습니다.
 
 **프로세스 가시성.** `lterm processes [session]`(호환 이름: `lterm ps [session]`)은 process-group id와 함께 각 세션 child 아래의 process tree를 보여 줍니다. `--orphans`를 추가하면 기록된 session root의 descendant가 아니지만 같은 process group에 남아 있는 row도 함께 보여 주므로, Codex/OMX/MCP subprocess가 누적되어 메모리 누수처럼 커지기 전에 확인할 수 있습니다. 시스템 `ps`는 절대 경로로 호출하며, 형식이 잘못된 process row는 추측하지 않고 건너뜁니다.
 
 **Socket 위치.** 커스텀 `LTERM_SOCKET` 경로는 소유자 전용 디렉터리 안에 있어야 합니다. 격리된 socket 위치가 필요할 때는 `LTERM_RUNTIME_DIR`를 우선 사용하세요.
 
+**Binary override.** `LTERM_BIN`은 cmux split attach command처럼 child
+`lterm`을 다시 호출할 때 쓰는 신뢰된 개발자용 override입니다. Absolute
+path이고, control character가 없고, 실행 가능한 regular file일 때만
+override로 인정합니다. 유효하지 않은 값은 무시하고 현재 executable 또는
+`PATH`의 `lterm`으로 fallback합니다. 신뢰할 수 없는 environment data에서
+`LTERM_BIN`을 설정하지 마세요.
+
 **Popup 명령.** `tmux-compat display-popup`은 tmux와 비슷한 동작을 위해 요청된 명령을 사용자 shell로 실행합니다. **신뢰할 수 없는 popup 명령을 전달하지 마세요.**
 
 **빌드 재현성.** 릴리스 빌드는 커밋된 lockfile을 사용하세요: `cargo build --release --locked`. 현재 lockfile은 `serde_json 1.0.149`와 registry dependency인 `zmij 1.0.21`을 고정합니다. 둘 다 Cargo가 lockfile에 따라 resolve하는 crate이며, 로컬에 vendor된 crate가 아닙니다. `cargo tree --locked -p serde_json`으로 의존성 집합을 확인할 수 있습니다.
@@ -483,6 +504,20 @@ LTERM_RUNTIME_DIR="$TMP/run" LTERM_DATA_DIR="$TMP/data" cargo run -- logs test -
 LTERM_RUNTIME_DIR="$TMP/run" LTERM_DATA_DIR="$TMP/data" cargo run -- shutdown
 ```
 
+릴리스/계약 preflight 헬퍼:
+
+```bash
+scripts/release-preflight.sh --contract-only
+scripts/release-preflight.sh --allow-occupied-skip --skip-audit
+scripts/dependency-minor-dry-run.sh
+```
+
+`scripts/release-preflight.sh`의 `--run-soak`은 manual release-gate soak
+profile에서만 사용하세요. Tagging 또는 publishing 전에 release, audit,
+contract, dependency, soak evidence를 남길 때는
+[`docs/release-evidence-template.md`](docs/release-evidence-template.md)를
+사용하세요.
+
 ## 라이선스
 
 다음 두 라이선스 중 하나를 선택해 사용할 수 있습니다.

package/README.md

@@ -1,6 +1,6 @@
 # Light Terminal (`lterm`)
 
-[한국어](README.ko.md) | English
+[한국어](README.ko.md) | English | 🌐 [Browser-friendly HTML guide](https://ictechgy.github.io/light_terminal/)
 
 ## TL;DR
 
@@ -30,8 +30,9 @@ need:
   CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp,
   Crush, Kimi, Qwen, Gemini CLI, OMX/OMC, and similar terminal-first tooling.
 - **Raw attach, safe reports** — attached PTY streams remain raw for TUIs and
-  interactive shells, while `logs`, `capture`, `list`, `doctor`, and other
-  report surfaces sanitize terminal control sequences before printing.
+  interactive shells, while `logs`, `capture`, `compose`, `doctor`,
+  `diagnose`, the `notify` fallback path, and other report surfaces strip
+  terminal controls while preserving UTF-8 text such as Korean, CJK, and emoji.
 - **cmux-friendly by design** — notifications and tmux shim calls are shaped for
   cmux/agent pane orchestration instead of generic desktop multiplexing.
 - **Built-in observability** — `doctor` / `status`, bounded `logs --start/--end`,
@@ -78,7 +79,7 @@ With Cargo from GitHub, pin a release tag. The example below uses the current
 README release; check the Releases page for newer tags:
 
 ```bash
-cargo install --locked --git https://github.com/ictechgy/light_terminal --tag v1.0.8
+cargo install --locked --git https://github.com/ictechgy/light_terminal --tag v1.0.10
 ```
 
 Building from this checkout requires Rust 1.85 or newer:
@@ -142,6 +143,7 @@ lterm -a api
 | Set a session status theme | `lterm status-theme api green` | `theme` |
 | Read sanitized scrollback | `lterm logs api --start=-80 --end=-1` | `capture` |
 | Record raw PTY output for debugging | `lterm trace api --duration 5s --output trace.jsonl` | `record` |
+| Replay a trusted raw PTY trace | `lterm trace-replay trace.jsonl` | `replay-trace` |
 | Open a sanitized scrollback composer for input | `lterm compose api` | `mobile` |
 | Wait for session output or exit | `lterm wait api --contains READY --timeout 30s --json` | None |
 | Watch a session and notify on completion | `lterm watch api --exit --notify` | None |
@@ -201,17 +203,24 @@ flags, and — only when an existing daemon is reachable — session metadata pl
 process rows. It does not start the daemon and does not include raw PTY bytes or
 scrollback by default.
 
-`lterm logs <target>` accepts `--start` / `-S` and `--end` / `-E` line offsets. Non-negative values are absolute scrollback line indexes; negative values count back from the current scrollback line count. `--end` is inclusive, so `lterm logs api -S0 -E0` captures only the first line. Capture output remains sanitized text; attached PTY streams remain raw.
+`lterm logs <target>` accepts `--start` / `-S` and `--end` / `-E` line offsets. Non-negative values are absolute scrollback line indexes; negative values count back from the current scrollback line count. `--end` is inclusive, so `lterm logs api -S0 -E0` captures only the first line. Capture output remains sanitized text: terminal controls are removed, while UTF-8 text such as Korean, CJK, and emoji is preserved. Attached PTY streams remain raw.
 
 `lterm trace <target> --duration 5s --output trace.jsonl` records raw PTY
 output chunks to a private local JSONL file with timestamps and hex-encoded
-bytes. It is for opt-in debugging of intermittent render issues; it does not
-replay bytes to stdout, caps raw capture at `--max-bytes` (default 16 MiB), and
-refuses to overwrite existing trace files unless `--force` is passed.
+bytes. It is for opt-in debugging of intermittent render issues; the recorder
+only writes the JSONL artifact, caps raw capture at `--max-bytes` (default
+16 MiB), and refuses to overwrite existing trace files unless `--force` is
+passed. To replay, use `lterm trace-replay <file>` only with traces you trust:
+it validates the whole JSONL file before emitting any raw terminal bytes and
+caps replay at the default trace capture size plus a per-trace chunk-count
+limit.
 
 `lterm wait <target> --exit / --contains <text>` blocks until a session exits or its sanitized scrollback contains a marker. Add `--timeout 250ms|2s|5m|1h`, `--tail N`, and `--json` for automation-friendly health checks. On timeout, `wait` / `watch` return exit code `124` and JSON reports `timed_out: true`. `lterm watch` uses the same conditions and can add `--notify` to emit a cmux-friendly completion notification without altering attached PTY bytes; with `--json`, stdout stays machine-readable even when notification fallback is needed.
+Oversized `--contains` needles are rejected with an explicit error, and the
+daemon caps concurrent blocking `wait` / `watch` checks so automation cannot fan
+out unbounded waiters.
 
-Set `LTERM_STATUS_STYLE=full` or `LTERM_STATUS_STYLE=minimal` to choose the visual style. `full` (default for local terminals) draws a colored bar; `minimal` drops all SGR colors in favor of plain text. SSH sessions (detected via `SSH_CONNECTION`, `SSH_CLIENT`, or `SSH_TTY`) default to `minimal` to avoid color-mapping issues on mobile SSH clients like Termius, unless a session or environment theme is explicitly set.
+Set `LTERM_STATUS_STYLE=full` or `LTERM_STATUS_STYLE=minimal` to choose the visual style. `full` (default for local terminals) draws a colored bar; `minimal` drops all SGR colors in favor of plain text. SSH sessions (detected via `SSH_CONNECTION`, `SSH_CLIENT`, or `SSH_TTY`) and Termius-style clients (detected via terminal identity variables) default to `minimal` to avoid mobile color-mapping issues, unless a session or environment theme is explicitly set.
 
 Set `LTERM_STATUS_THEME=blue|green|magenta|cyan|amber|red|gray|plain` to change the default colored status bar for the attaching client. Per-session overrides win over the environment: `lterm start --status-theme amber -n api -- npm run dev`, `lterm run --status-color cyan -- cargo test`, or `lterm status-theme api plain`. If you export this variable from shell startup files, it also opts SSH attaches into colored status bars; leave it unset or set `LTERM_STATUS_STYLE=minimal` on mobile SSH clients that need plain text. Theme names are parsed from a fixed allowlist; lterm never injects arbitrary user-provided terminal escape sequences into the status row.
 
@@ -416,7 +425,7 @@ When `lterm tmux-compat split-window` detects cmux (via `CMUX_WORKSPACE_ID`, `CM
 
 1. Starts a new `lterm` PTY session for the worker command.
 2. Asks cmux to create a native split (`cmux new-split right/down`).
-3. Sends the compatibility command `lterm attach <pane>` into that split, so cmux panes still work if `LTERM_BIN` points at an older `lterm` build that predates `resume`.
+3. Sends the compatibility command `lterm attach <pane>` into that split. If a safe absolute executable is supplied through `LTERM_BIN`, lterm uses it; otherwise it falls back to the current executable. The compatibility command keeps cmux panes working even with older builds that predate `resume`.
 
 This gives cmux a real pane to decorate while `lterm` retains scrollback capture and `send-keys` compatibility.
 
@@ -460,12 +469,18 @@ the old code until they are stopped.
 
 **Terminal output is forwarded as-is.** `lterm resume` (compatibility name: `lterm attach`) passes PTY bytes through so full-screen terminal programs and cmux/OSC notifications keep working. The local status bar is purely a client-side decoration; use `--no-status` for a fully raw terminal surface. Untrusted child programs can still emit terminal escape sequences to an attached terminal — exactly as under tmux/screen. **Do not use `lterm` as an escape-sequence sanitizer or sandbox.**
 
-**Capture output is terminal-control-sanitized before display/logging.** `lterm logs` (compatibility name: `lterm capture`), `lterm compose` (alias: `lterm mobile`), and `tmux capture-pane` strip common terminal control sequences before printing scrollback. Scrollback text can still be untrusted program output, so review it before feeding it to humans or agents. `compose` is a non-attached view that commits text through the existing input/send path; it does not transform raw attached PTY streams.
+**Capture output is terminal-control-sanitized before display/logging.** `lterm logs` (compatibility name: `lterm capture`), `lterm compose` (alias: `lterm mobile`), and `tmux capture-pane` strip terminal control sequences, including raw or UTF-8-encoded C1 controls, before printing scrollback. Valid UTF-8 text such as Korean, CJK, and emoji is preserved. Scrollback text can still be untrusted program output, so review it before feeding it to humans or agents. `compose` is a non-attached view that commits text through the existing input/send path; it does not transform raw attached PTY streams.
 
 **Process visibility.** `lterm processes [session]` (or compatibility name `lterm ps [session]`) shows the process tree rooted at each session child, including process-group ids. Add `--orphans` to also include same-process-group rows that are no longer descendants of the recorded session root, so long-running Codex/OMX/MCP subprocess buildup stays visible before it becomes a memory-leak surprise. The system `ps` is invoked by absolute path, and malformed process rows are skipped rather than guessed at.
 
 **Socket location.** Custom `LTERM_SOCKET` paths must live in an owner-only directory. Prefer `LTERM_RUNTIME_DIR` when you need an isolated socket location.
 
+**Binary override.** `LTERM_BIN` is a trusted developer override for child
+`lterm` invocations such as cmux split attach commands. Overrides are accepted
+only when they are absolute paths to executable regular files and contain no
+control characters; invalid values are ignored in favor of the current
+executable or `lterm` on `PATH`. Do not set it from untrusted environment data.
+
 **Popup commands.** `tmux-compat display-popup` runs the requested command through the user's shell to preserve tmux-like behavior. **Do not pass untrusted popup commands.**
 
 **Build reproducibility.** Use the committed lockfile for release builds: `cargo build --release --locked`. The current lockfile pins `serde_json 1.0.149` and its registry dependency `zmij 1.0.21`; both are resolved by Cargo from the lockfile, not vendored locally. Verify the dependency set with `cargo tree --locked -p serde_json`.

package/bin/lterm.js

@@ -15,6 +15,9 @@ const SUPPORTED = new Map([
 
 function isExecutable(file) {
   try {
+    if (!fs.statSync(file).isFile()) {
+      return false;
+    }
     fs.accessSync(file, fs.constants.X_OK);
     return true;
   } catch (_) {
@@ -22,6 +25,21 @@ function isExecutable(file) {
   }
 }
 
+function hasControlChars(value) {
+  return /[\x00-\x1f\x7f-\x9f]/.test(value);
+}
+
+function overrideBinary(value) {
+  if (hasControlChars(value)) {
+    throw new Error('LTERM_BIN must not contain control characters.');
+  }
+  const resolved = path.resolve(value);
+  if (!isExecutable(resolved)) {
+    throw new Error(`LTERM_BIN is not executable: ${resolved}`);
+  }
+  return resolved;
+}
+
 function packageBinary(packageName) {
   try {
     const packageJson = require.resolve(`${packageName}/package.json`, {
@@ -39,7 +57,7 @@ function repoFallbackBinary() {
 
 function resolveBinary() {
   if (process.env.LTERM_BIN) {
-    return process.env.LTERM_BIN;
+    return overrideBinary(process.env.LTERM_BIN);
   }
 
   const key = `${process.platform}:${process.arch}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/lterm",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Lightweight tmux-compatible terminal session daemon with cmux-friendly notifications.",
   "license": "MIT OR Apache-2.0",
   "homepage": "https://github.com/ictechgy/light_terminal#readme",
@@ -21,6 +21,10 @@
   "bin": {
     "lterm": "bin/lterm.js"
   },
+  "scripts": {
+    "prepublishOnly": "node scripts/validate_npm_packages.mjs",
+    "validate:npm-packages": "node scripts/validate_npm_packages.mjs"
+  },
   "files": [
     "bin/lterm.js",
     "docs/assets/lterm-demo.svg",
@@ -28,13 +32,14 @@
     "README.ko.md",
     "LICENSE",
     "LICENSE-APACHE",
-    "LICENSE-MIT"
+    "LICENSE-MIT",
+    "scripts/validate_npm_packages.mjs"
   ],
   "optionalDependencies": {
-    "lterm-darwin-arm64": "1.0.8",
-    "lterm-darwin-x64": "1.0.8",
-    "lterm-linux-arm64": "1.0.8",
-    "lterm-linux-x64": "1.0.8"
+    "lterm-darwin-arm64": "1.0.10",
+    "lterm-darwin-x64": "1.0.10",
+    "lterm-linux-arm64": "1.0.10",
+    "lterm-linux-x64": "1.0.10"
   },
   "engines": {
     "node": ">=16"

package/scripts/validate_npm_packages.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+'use strict';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const requireBinaries = process.argv.includes('--require-binaries');
+const platforms = [
+  {
+    name: 'lterm-darwin-arm64',
+    dir: 'npm/platforms/lterm-darwin-arm64',
+    os: 'darwin',
+    cpu: 'arm64',
+  },
+  {
+    name: 'lterm-darwin-x64',
+    dir: 'npm/platforms/lterm-darwin-x64',
+    os: 'darwin',
+    cpu: 'x64',
+  },
+  {
+    name: 'lterm-linux-arm64',
+    dir: 'npm/platforms/lterm-linux-arm64',
+    os: 'linux',
+    cpu: 'arm64',
+  },
+  {
+    name: 'lterm-linux-x64',
+    dir: 'npm/platforms/lterm-linux-x64',
+    os: 'linux',
+    cpu: 'x64',
+  },
+];
+const rootScripts = {
+  prepublishOnly: 'node scripts/validate_npm_packages.mjs',
+  'validate:npm-packages': 'node scripts/validate_npm_packages.mjs',
+};
+const forbiddenPlatformFields = [
+  'scripts',
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+  'bundledDependencies',
+  'bundleDependencies',
+];
+
+function readJson(relativePath) {
+  return JSON.parse(fs.readFileSync(path.join(root, relativePath), 'utf8'));
+}
+
+function fail(message) {
+  console.error(`npm package validation failed: ${message}`);
+  process.exitCode = 1;
+}
+
+function sameArray(actual, expected) {
+  return (
+    Array.isArray(actual) &&
+    actual.length === expected.length &&
+    expected.every((value, index) => actual[index] === value)
+  );
+}
+
+function sameObject(actual, expected) {
+  return JSON.stringify(actual || {}) === JSON.stringify(expected);
+}
+
+const rootPackage = readJson('package.json');
+const version = rootPackage.version;
+const optionalDeps = rootPackage.optionalDependencies || {};
+const expectedOptionalDeps = Object.fromEntries(platforms.map((platform) => [platform.name, version]));
+
+if (!sameObject(rootPackage.scripts, rootScripts)) {
+  fail(`root scripts ${JSON.stringify(rootPackage.scripts || {})} do not match expected publish guards`);
+}
+
+const actualKeys = Object.keys(optionalDeps).sort();
+const expectedKeys = Object.keys(expectedOptionalDeps).sort();
+if (JSON.stringify(actualKeys) !== JSON.stringify(expectedKeys)) {
+  fail(`root optionalDependencies keys ${JSON.stringify(actualKeys)} do not match ${JSON.stringify(expectedKeys)}`);
+}
+for (const [name, expectedVersion] of Object.entries(expectedOptionalDeps)) {
+  if (optionalDeps[name] !== expectedVersion) {
+    fail(`root optionalDependency ${name}@${optionalDeps[name]} does not match root version ${expectedVersion}`);
+  }
+}
+
+for (const platform of platforms) {
+  const pkg = readJson(`${platform.dir}/package.json`);
+  if (pkg.name !== platform.name) {
+    fail(`${platform.dir} package name ${pkg.name} does not match ${platform.name}`);
+  }
+  if (pkg.version !== version) {
+    fail(`${platform.name} version ${pkg.version} does not match root version ${version}`);
+  }
+  if (!sameArray(pkg.os, [platform.os])) {
+    fail(`${platform.name} os ${JSON.stringify(pkg.os)} does not match [${platform.os}]`);
+  }
+  if (!sameArray(pkg.cpu, [platform.cpu])) {
+    fail(`${platform.name} cpu ${JSON.stringify(pkg.cpu)} does not match [${platform.cpu}]`);
+  }
+  if (!sameArray(pkg.files, ['bin/lterm'])) {
+    fail(`${platform.name} files ${JSON.stringify(pkg.files)} does not exactly publish bin/lterm`);
+  }
+  for (const field of forbiddenPlatformFields) {
+    if (Object.prototype.hasOwnProperty.call(pkg, field)) {
+      fail(`${platform.name} must not declare ${field}`);
+    }
+  }
+  if (requireBinaries) {
+    const binary = path.join(root, platform.dir, 'bin', 'lterm');
+    try {
+      fs.accessSync(binary, fs.constants.X_OK);
+    } catch (_) {
+      fail(`${platform.name} missing executable ${path.relative(root, binary)}`);
+    }
+  }
+}
+
+if (process.exitCode) {
+  process.exit(process.exitCode);
+}
+console.log(`npm package metadata ok for ${rootPackage.name}@${version}`);