If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/akavel/up shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 7 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live akavel/up repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/akavel/up.

What it runs against: a local clone of akavel/up — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in akavel/up | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 4 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 639 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of akavel/up. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/akavel/up.git
#   cd up
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of akavel/up and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "akavel/up(\\.git)?\\b" \\
  && ok "origin remote is akavel/up" \\
  || miss "origin remote is not akavel/up (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "up.go" \\
  && ok "up.go" \\
  || miss "missing critical file: up.go"
test -f "up_test.go" \\
  && ok "up_test.go" \\
  || miss "missing critical file: up_test.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 639 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~609d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/akavel/up"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Ultimate Plumber (up) is a terminal UI tool written in Go that lets you build and test Linux shell pipelines interactively with live preview. You pipe data into up, type pipeline commands (grep, cut, awk, etc.) in a top input box, and instantly see scrollable output below—making it fast to explore and build complex text-processing pipelines without running commands repeatedly. Simple monolithic structure: single entry point up.go contains the main logic, up_test.go has unit tests, minimal external structure. The tool reads stdin, spawns bash subprocesses for each pipeline command user types, captures output, and renders it via tcell terminal UI—all in one binary.

Linux system administrators, data analysts, and DevOps engineers who frequently work with text pipelines and want faster feedback loops when building complex grep/awk/sed/cut chains. Users who spend time trial-and-error testing pipes in the shell benefit from the instant preview.

Actively maintained but modest scale: single-maintainer project (akavel) with ~29KB of Go code, basic test coverage (up_test.go exists), Travis CI configured (.travis.yml), and recent releases available. Not heavily starred but stable and functional for its narrow, well-defined purpose—production-ready for interactive use, not a large ecosystem project.

Low dependency risk: only 5 direct dependencies (tcell for terminal UI, pflag for flags, go-isatty for TTY detection), all well-established libraries. Single maintainer creates long-term sustainability risk if maintainer disappears. No visible CI/CD failures in the structure, but small user base means fewer eyes catching edge cases. WARNING in README about dangerous commands (rm/dd) is honest but means users must be careful.

No active PR/issue data visible in provided files, but the stable state and focused scope suggest maintenance mode rather than heavy development. Latest releases are available on GitHub, and the tool appears to work stably for its core mission.

Clone and build: git clone https://github.com/akavel/up.git && cd up && go build -o up . && echo 'some text' | ./up — no external services or setup needed. Requires Go 1.14+ (from go.mod), gcc/build tools for tcell CGO dependencies.

Daily commands: Build: go build -o up . (creates binary up in current directory). Run: some-command | ./up (e.g., lshw |& ./up or cat file.txt | ./up). Exit with Ctrl-X to save pipeline to up1.sh, or Ctrl-C to discard.

• up.go — Main entry point and core UI loop—contains all interactive terminal handling, command execution, and live preview rendering logic.
• up_test.go — Test suite for the core pipeline processing—critical for understanding how commands are parsed, executed, and piped together.
• go.mod — Dependency manifest; tcell is the heavy lifting for terminal UI and must be understood for any UI modifications.
• README.md — Defines the tool's purpose, scope, and usage patterns—essential context for why the architecture exists as-is.

• Terminal UI Loop (tcell event loop in up.go) (tcell, Go channels) — Captures user input, renders editor and preview panes, updates screen on each keystroke.
  • Failure mode: Screen corruption, input loss, unresponsive preview; if tcell fails to initialize, app crashes with no fallback UI.
• Command Parser (in up.go) (Go strings, shell escaping (if any)) — Parses user-typed command line into shell-executable segments; builds the final pipe expression.
  • Failure mode: Malformed commands; potential shell injection if unescaped user input is passed; parser bugs cause incorrect previews.
• Shell Executor (os/exec in up.go) (os/exec, io.Pipe) — Spawns subprocess, pipes command segments, captures stdout and stderr.
  • Failure mode: Subprocess hangs or times out (no timeout logic visible); large output buffers memory; shell not found or permissions denied; killed if UI is interrupted.
• Live Preview Renderer (in up.go) (tcell screen, Go strings) — Displays command output in scrollable pane; truncates or paginates large results.
  • Failure mode: Large outputs cause lag or memory exhaustion; preview doesn't update if subprocess hangs; scrolling may be slow for millions of lines.

• User (terminal input) → Terminal UI event handler — Keyboard and mouse events captured by tcell.
• Terminal UI event handler → Command Parser — User-typed string accumulated and parsed into shell command segments.
• Command Parser → Shell Executor — Parsed command line passed to exec.Command as shell invocation.
• Shell Executor → stdout/stderr streams — Subprocess executes and outputs results to captured pipes.
• stdout/stderr streams → Live Preview Renderer — Command output buffered and formatted for display.
• Live Preview Renderer → Terminal UI screen — Preview pane drawn by tcell; user sees live results.
• User (press Enter) → Terminal stdout — Final command line echoed to parent shell or script.

Add a new text-processing filter or transformation step

1. Edit up.go to add a new pipeline segment parser in the main command execution loop. (up.go)
2. Add test cases in up_test.go to verify correct command chaining and output handling. (up_test.go)
3. Rebuild and test interactively by piping input through the new filter in the terminal UI. (up.go)

Modify terminal rendering or key bindings

1. Locate the tcell event handling and screen drawing code in up.go's main event loop. (up.go)
2. Add new key event handlers or screen region updates in the same section. (up.go)
3. Rebuild and test interactively in the terminal to verify visual and UX changes. (up.go)

Add a new command-line flag or configuration option

1. Add a pflag definition in up.go's init or main function. (up.go)
2. Thread the flag value through the command execution or UI rendering logic. (up.go)
3. Add test cases to up_test.go covering the flag's effect on pipeline behavior. (up_test.go)

• tcell — Provides portable, cross-platform terminal UI with colors, mouse support, and non-blocking event handling—essential for real-time, interactive text editor and live preview.
• Go / os/exec — Allows lightweight subprocess spawning and pipe orchestration without heavy dependencies; fast startup and responsive feedback loop critical for this tool's purpose.
• pflag — POSIX-style command-line flag parsing for configuration options like input sources and output formatting.
• golang.org/x/sys — Low-level terminal control (isatty detection, tty operations) for detecting piped input and raw mode handling.

• Monolithic up.go file with all UI, parsing, and execution logic in one place.

  • Why: Simplicity: small codebase (single file) is easier to understand and maintain for a focused tool; avoids over-engineering for a 10-file project.
  • Consequence: Limits modularity and code reuse; harder to unit-test individual components independently; becomes a bottleneck if adding substantial new features.

• Subprocess execution via shell (exec.Command) rather than direct AST parsing and execution.

  • Why: Allows seamless use of existing Linux utilities (grep, awk, sort, cut, etc.) without reimplementing them; user's familiar with standard pipes.
  • Consequence: Dependent on shell availability; shell injection risk if user input is not properly escaped (though user is typing interactively, so lower risk); slower than native Go implementations for some operations.

• Synchronous command execution with blocking preview updates.

  • Why: Simpler code and UX; preview results immediately after each keystroke.
  • Consequence: Long-running commands can freeze the UI; large outputs can cause lag; no timeout mechanism evident in codebase.

• Does not provide a graphical UI (terminal-only).
• Does not handle Windows or macOS natively (Linux pipes-focused; see README mentions).
• Does not support custom shell languages beyond standard POSIX sh syntax.
• Does not persist command history or saved pipelines across sessions.
• Does not provide network execution or remote command piping.
• Does not implement authentication or privilege escalation (relies on user's shell permissions).

• Monolithic function with mixed concerns (Medium) — up.go main(): UI loop, command parsing, subprocess execution, and preview rendering all intertwined in a single large function; difficult to test, extend, or debug individual steps.
• Synchronous blocking command execution (High) — up.go (subprocess invocation in event loop): Command results fetched synchronously in the main UI thread; long-running commands freeze the terminal, preventing user input or cancellation.
• Unbounded output buffering (Medium) — up.go (preview pane population): No visible limits on output size stored in memory; very large pipeline results may exhaust RAM without warning or truncation strategy.
• No explicit error handling or recovery (Medium) — up.go (subprocess and I/O operations): Subprocess errors, broken pipes, and I/O failures may silently fail or crash the app; limited feedback to user on why a command failed.

• up.go (shell execution loop in event handler) (undefined) — Subprocess spawning and I/O on every keystroke; if command is slow (e.g., large file processing), UI becomes unresponsive

Bash is hardcoded as the shell (bash -c), so pipeline syntax must be bash-compatible—not POSIX sh. tcell may require CGO enabled and C libraries on some systems (build may fail if gcc/dev headers missing). Stdin must be piped in; up cannot read from terminal directly without a pipe. No config files or env vars—behavior is purely determined by command-line input and keyboard interaction.

• Terminal Control Sequences (ANSI/VT100) — tcell abstracts this, but understanding cursor positioning, color codes, and screen clearing is essential to debug terminal rendering issues in up's UI loop
• Subprocess I/O Redirection — up spawns bash subprocesses and captures their output via pipes; understanding os.Pipe, exec.Cmd.Stdout/Stderr, and io.Copy is core to how pipelines execute
• Event-Driven UI Architecture — up's responsiveness depends on non-blocking event polling (keyboard input) combined with screen updates; understanding tcell's event loop model is key to modifying the UI
• Bash Pipeline Syntax — Users type bash pipelines into up; understanding how bash parses and executes pipes (|, ||, &&) is necessary to design features or debug user-reported issues
• TTY Detection (isatty) — up uses go-isatty to detect if stdin is a terminal or pipe; this determines whether data can be read and how the tool behaves
• Shlemiel the Painter's Algorithm (incremental file naming) — up saves output to up1.sh, up2.sh, etc.; the README explicitly mentions this algorithm as the approach to avoid overwriting previous saves
• Scrollable View Management — up displays command output in a scrollable window that must handle output larger than screen height; understanding buffer management and viewport rendering prevents crashes with large datasets

• junegunn/fzf — Interactive fuzzy finder for terminal; similar live-preview philosophy but for searching/filtering rather than pipeline building
• BurntSushi/ripgrep — Fast grep replacement often used inside pipes with up; complementary text-processing tool
• jqlang/jq — JSON query language and processor; frequently piped into up for interactive JSON exploration
• mikefarah/yq — YAML equivalent of jq; another text-processing tool commonly used in pipelines with up
• glab-dev/glab — Interactive CLI for GitLab that demonstrates similar tcell-based terminal UI patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow to replace .travis.yml

The repo uses outdated .travis.yml for CI. GitHub Actions is now the standard for GitHub repos and provides better integration, faster feedback, and no external service dependencies. This would modernize the CI/CD pipeline and ensure the Go 1.14+ module builds correctly across Linux platforms.

• [ ] Create .github/workflows/ci.yml with Go build matrix (1.14, 1.15+, latest)
• [ ] Add steps to run 'go test ./...' and 'go build' for the up.go project
• [ ] Test on ubuntu-latest to validate cross-platform Linux compatibility
• [ ] Add workflow status badge to README.md
• [ ] Remove or deprecate .travis.yml after successful GitHub Actions validation

Expand up_test.go with table-driven tests for pipe parsing and preview rendering

The up_test.go file likely has minimal coverage for core functionality. Given that 'up' is a pipe-building tool, comprehensive tests for command parsing, execution, and output preview would catch regressions and make maintenance easier. Table-driven tests are idiomatic Go and would improve test clarity.

• [ ] Analyze existing tests in up_test.go and identify untested functions
• [ ] Add table-driven tests for pipe command parsing (e.g., handling 'grep | sort | cut')
• [ ] Add tests for safe command execution and output sanitization (security critical)
• [ ] Test edge cases: empty input, very large output, special characters in preview
• [ ] Run 'go test -cover' and aim for >70% code coverage of up.go

Add shell completion scripts (bash, zsh) with installation documentation

The repo uses spf13/pflag for CLI flags but lacks shell completion support. Adding bash/zsh completion scripts and documenting installation would significantly improve UX for terminal users, aligning with standard practice for CLI tools.

• [ ] Generate bash completion script using spf13/pflag completion helpers (e.g., 'up --completion bash')
• [ ] Generate zsh completion script with standard _up function
• [ ] Create completion/ directory to store scripts
• [ ] Add 'Installation' section to README.md with installation instructions for bash/zsh
• [ ] Document how users can install completions (e.g., 'cp completion/up.bash /etc/bash_completion.d/')

• Add support for shell selection (--shell flag) so users can use zsh, fish, or ksh instead of hardcoded bash—modify up.go to accept a flag and use it in the exec.Command call
• Write integration tests in up_test.go that spawn up as a subprocess and send simulated keyboard input (via tcell) to verify pipeline execution works end-to-end
• Add a --help flag that prints usage docs (currently none exists); use spf13/pflag which is already imported but unused in the codebase

The codebase shows moderate security concerns primarily around dependency management. The main risks are: (1) outdated Go version and dependencies from 2019-2020 that may contain unpatched vulnerabilities, (2) potential command injection risks given the nature of the tool (interactive Linux pipe builder), and (3) lack of security documentation. The tool itself appears to be relatively simple with limited attack surface based on visible file structure, but dependencies should be urgently updated. No hardcoded secrets or obvious injection vulnerabilities are apparent from the available information.

• Medium · Outdated Go Version — go.mod. The project specifies go 1.14, which was released in February 2020 and is no longer supported. This version may contain unpatched security vulnerabilities. Fix: Update to the latest stable Go version (1.21+) to ensure security patches and improvements are included.
• Medium · Outdated Dependencies with Potential Vulnerabilities — go.mod. The dependency 'github.com/gdamore/tcell v1.4.0' is from 2019 and may contain unpatched security vulnerabilities. The golang.org/x/sys and golang.org/x/text dependencies use very old versions (dated October 2020). Fix: Update all dependencies to their latest versions. Run 'go get -u ./...' and 'go mod tidy' to update dependencies. Review changelog for breaking changes.
• Low · Command Execution via User Input — up.go (inferred from description). Based on the README, this tool processes Linux pipe commands interactively. If user input is passed to shell execution without proper validation/escaping, it could lead to command injection vulnerabilities. Fix: Ensure all user-provided input is properly sanitized before passing to shell execution. Use shell argument arrays instead of string concatenation. Implement input validation and consider using exec.Command with argument arrays rather than shell interpretation.
• Low · Missing Security Headers in Documentation — Repository root. No security policy or responsible disclosure documentation found in the visible file structure (no SECURITY.md or similar). Fix: Add a SECURITY.md file documenting how users can report security vulnerabilities responsibly. Include contact information and expected response timelines.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.