npm package: @kyungyeol.baek/pouch
Description: Session-first GNU Screen manager with a focused terminal UI for macOS and Linux.
Latest version: 0.1.2

# Pouch

Simple GNU Screen session manager with a session-first TUI.

Pouch opens as a focused session board first, then falls back to familiar CLI commands when you need scripting. It keeps managed sessions restartable, leaves external Screen sessions visible, and makes the first attach flow obvious.

![Pouch preview](docs/assets/pouch-preview.svg)

## Why Pouch

- Open `pouch` and see every session immediately.
- Create the first managed session with one key: `n`.
- Filter sessions with `/` and clone a managed session with `c`.
- Reattach with `Enter`, then confirm `stop` and `restart` before Pouch changes a live session.
- Keep unmanaged Screen sessions visible without taking them over.
- Run `pouch doctor` when the environment is wrong instead of guessing.

## Install

### npm (recommended)

```bash
npm install -g @kyungyeol.baek/pouch
pouch --version
pouch doctor
```

The npm package downloads a prebuilt `pouch` binary from GitHub Releases during install. Supported prebuilt targets:

- macOS Apple Silicon
- macOS Intel
- Linux x64

If the release download is unavailable or your platform is not listed above, build Pouch from source with Cargo instead.

If `doctor` reports that Screen is missing, install GNU Screen first and rerun it.

### Requirements

- macOS or Linux
- GNU Screen installed and available in `PATH`
- Node.js `18+` for npm installation

### From Source

```bash
rustup toolchain install 1.93.0
cargo build --release
./target/release/pouch doctor
```

Current dependencies need `rustc 1.88+`. This repository pins stable `1.93.0` through `rust-toolchain.toml`, so `cargo` will automatically use it after `rustup` is installed.

## 60-Second Quick Start

```bash
# 1. Check the environment
pouch doctor

# 2. Start the TUI
pouch
```

Inside the TUI:

- Press `n` to create your first managed session
- Leave `Command` empty to start your default shell
- Press `Enter` to start it
- Press `Enter` again on the selected session to attach
- Read the detach reminder, then use default `Ctrl-A d` to leave `screen`
- Press `/` to filter by session name or command
- Press `c` to clone a managed session into a prefilled form
- Press `s` or `r`, then confirm with `Enter` or `y`
- Press `?` or `h` at any time to open help

## Managed vs Unmanaged

Pouch shows two kinds of sessions:

- Managed sessions: created by Pouch, store the original command and working directory, and can be restarted from the TUI or CLI.
- Unmanaged sessions: existing GNU Screen sessions that Pouch did not create. They stay visible and attachable, but restart is disabled.

## CLI Examples

```bash
# Start a managed session directly
pouch run demo -- sleep 300

# List all sessions
pouch ls

# Attach by managed name
pouch attach demo

# When attached, leave screen without stopping it
# default: Ctrl-A d

# Restart a managed session
pouch restart demo

# Stop a session
pouch stop demo
```

## TUI Keys

```text
↑/↓   Move selection
Enter Attach selected session
/     Filter by name or command
n     New managed session
c     Clone selected managed session
s     Stop selected session after confirmation
r     Restart selected managed session after confirmation
g     Refresh sessions
? / h Toggle help
q     Quit
```

## Troubleshooting

### `cargo` cannot build the project

This project uses Rust 2024 edition and current dependencies require a newer toolchain than older system `cargo` installs. Use:

```bash
rustup toolchain install 1.93.0
cargo +1.93.0 test
```

### `screen` is missing or broken

Run:

```bash
pouch doctor
```

Pouch will check platform support, the Screen executable, Screen listing, and session metadata health.

It also reports whether `screen-256color` terminfo is available and whether any managed sessions were started before Pouch's UTF-8 screen profile was introduced.

### I only see external sessions

That means Pouch found existing GNU Screen sessions but does not own them. You can still attach, but restart is available only for sessions created through Pouch.

### The HUD or glyphs look broken inside `screen`

Pouch now starts managed sessions with `screen -U` and prefers `screen-256color` when terminfo is installed. If you still see broken separators or icons:

```bash
pouch doctor
```

If `doctor` warns about legacy managed sessions, recreate them with:

```bash
pouch restart <name>
```

For shells or sessions started outside Pouch, add this to `~/.screenrc`:

```screen
defutf8 on
term screen-256color
```

Attaching to an already-running legacy session may still look wrong until it is restarted.

### I do not remember how to leave `screen`

Pouch now shows a detach reminder before every interactive attach. The default GNU Screen detach key is:

```text
Ctrl-A d
```

If you changed Screen's escape prefix, use your custom prefix followed by `d` instead.

### Stop or restart feels safer now

That is intentional. TUI stop and restart actions now open a confirmation prompt so you do not kill or recycle a live session by accident. Confirm with `Enter` or `y`, cancel with `Esc` or `n`.

## Release

Maintainers publish in two steps:

1. Push a `vX.Y.Z` tag to build binaries, run checks, and create a draft GitHub Release.
2. Configure npm Trusted Publisher for this GitHub repository, review the draft, then run the `publish-release` GitHub Actions workflow to publish the release and `npm` package together.

Trusted Publisher requirements for this repo:

- npm package scope stays `@kyungyeol.baek/pouch`
- npm package settings must trust `zpdldhkdl/pouch`
- GitHub Actions `publish-release` uses GitHub OIDC instead of `NPM_TOKEN`

## Support

- Use the help overlay in the TUI with `?`
- Run `pouch doctor` before filing a bug
- Open an issue with the failing command, `doctor` output, and your OS/toolchain details

## Contributing

Small, focused improvements are preferred. UX polish, clearer onboarding, and better diagnostics are especially useful for this MVP stage.