shist 0.1.0__tar.gz

shist-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # setuptools_scm needs tag history to compute a version
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install ".[dev]"
+      - run: pytest -q

shist-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install ".[dev]"
+      - run: pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC) -- no API token needed
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # setuptools_scm derives the version from the pushed tag
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

shist-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.pytest_cache/
+.DS_Store

shist-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matplo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shist-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: shist
+Version: 0.1.0
+Summary: TUI to pick commands from your shell history and copy them to the clipboard
+Author-email: matplo <noksolp@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/matplo/shist
+Project-URL: Repository, https://github.com/matplo/shist
+Project-URL: Issues, https://github.com/matplo/shist/issues
+Keywords: shell,history,tui,clipboard,bash,zsh
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.60
+Requires-Dist: pyperclip>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: license-file
+
+# shist
+
+A small TUI for picking commands out of your shell history and copying them
+to the clipboard. Targets bash primarily; zsh is supported the same way.
+
+## How it works
+
+- **In bash/zsh, after sourcing the shell integration** (recommended): `shist`
+  is a shell function that pipes your shell's own `history` builtin into the
+  tool. That's the *live*, in-memory history of the current session,
+  including anything you typed that hasn't been flushed to a history file
+  yet.
+- **Standalone** (no shell integration, or in a shell without a `history`
+  builtin): running `shist` directly reads a history file instead —
+  `--file PATH`, or `$HISTFILE`, or `~/.bash_history` / `~/.zsh_history`
+  depending on `--shell`/`$SHELL`. This can miss very recent commands the
+  live shell hasn't written to disk yet.
+
+## Install
+
+Dependencies are installed into the `dev` henv environment rather than a
+project-local venv:
+
+```sh
+henv -n dev --run pip install -e /Users/ploskon/devel/shist
+```
+
+Then add the shell integration to your `.bashrc` and/or `.zshrc`:
+
+```sh
+source /Users/ploskon/devel/shist/shell/shist.sh
+```
+
+Open a new shell (or `source` your rc file) and run `shist`.
+
+## Using it
+
+There are three panels; `Tab` cycles through them: **search** → **history**
+→ **selection** → back to **search**. This keeps typing fully separate from
+the single-key list commands — `c`, `d`, `-`, `[`, `]` are always literal
+query text while you're in the search panel, and only act as commands once
+you've tabbed into history or selection.
+
+**Search** (active on start):
+- Type to filter (fuzzy substring match); `Backspace` edits it.
+- `↑`/`↓` (`Ctrl+P`/`Ctrl+N`) still browse the history list live;
+  `Shift+↑`/`Shift+↓` page through it.
+- `Tab` moves to the history panel.
+
+**History panel** (browse & add):
+- `↑`/`↓` move the highlight, not wrapping past either end;
+  `Shift+↑`/`Shift+↓` move a page at a time.
+- `c` adds the highlighted command to the selection, at the end.
+- `Tab` moves to the selection panel.
+
+**Selection panel** (the running list of what you've added, in order):
+- `↑`/`↓` move the highlight, not wrapping past either end;
+  `Shift+↑`/`Shift+↓` move a page at a time.
+- `d` or `-` removes the highlighted entry.
+- `[` / `]` move the highlighted entry earlier/later.
+- `Tab` moves back to search.
+
+**Any panel:**
+- `Enter` confirms: copies the selection, newline-joined in order; with
+  nothing added, copies just the highlighted history entry.
+- `Esc` / `Ctrl+C` cancels without copying anything.
+
+## Known limitations
+
+- A custom `HISTTIMEFORMAT` in bash gets treated as part of the command text
+  when reading piped `history` output — not specially parsed out.
+- Plain POSIX `sh`/`dash` has no `history` builtin, so there's no live-history
+  mode for it; only the standalone/file-fallback mode applies.

shist-0.1.0/README.md

@@ -0,0 +1,73 @@
+# shist
+
+A small TUI for picking commands out of your shell history and copying them
+to the clipboard. Targets bash primarily; zsh is supported the same way.
+
+## How it works
+
+- **In bash/zsh, after sourcing the shell integration** (recommended): `shist`
+  is a shell function that pipes your shell's own `history` builtin into the
+  tool. That's the *live*, in-memory history of the current session,
+  including anything you typed that hasn't been flushed to a history file
+  yet.
+- **Standalone** (no shell integration, or in a shell without a `history`
+  builtin): running `shist` directly reads a history file instead —
+  `--file PATH`, or `$HISTFILE`, or `~/.bash_history` / `~/.zsh_history`
+  depending on `--shell`/`$SHELL`. This can miss very recent commands the
+  live shell hasn't written to disk yet.
+
+## Install
+
+Dependencies are installed into the `dev` henv environment rather than a
+project-local venv:
+
+```sh
+henv -n dev --run pip install -e /Users/ploskon/devel/shist
+```
+
+Then add the shell integration to your `.bashrc` and/or `.zshrc`:
+
+```sh
+source /Users/ploskon/devel/shist/shell/shist.sh
+```
+
+Open a new shell (or `source` your rc file) and run `shist`.
+
+## Using it
+
+There are three panels; `Tab` cycles through them: **search** → **history**
+→ **selection** → back to **search**. This keeps typing fully separate from
+the single-key list commands — `c`, `d`, `-`, `[`, `]` are always literal
+query text while you're in the search panel, and only act as commands once
+you've tabbed into history or selection.
+
+**Search** (active on start):
+- Type to filter (fuzzy substring match); `Backspace` edits it.
+- `↑`/`↓` (`Ctrl+P`/`Ctrl+N`) still browse the history list live;
+  `Shift+↑`/`Shift+↓` page through it.
+- `Tab` moves to the history panel.
+
+**History panel** (browse & add):
+- `↑`/`↓` move the highlight, not wrapping past either end;
+  `Shift+↑`/`Shift+↓` move a page at a time.
+- `c` adds the highlighted command to the selection, at the end.
+- `Tab` moves to the selection panel.
+
+**Selection panel** (the running list of what you've added, in order):
+- `↑`/`↓` move the highlight, not wrapping past either end;
+  `Shift+↑`/`Shift+↓` move a page at a time.
+- `d` or `-` removes the highlighted entry.
+- `[` / `]` move the highlighted entry earlier/later.
+- `Tab` moves back to search.
+
+**Any panel:**
+- `Enter` confirms: copies the selection, newline-joined in order; with
+  nothing added, copies just the highlighted history entry.
+- `Esc` / `Ctrl+C` cancels without copying anything.
+
+## Known limitations
+
+- A custom `HISTTIMEFORMAT` in bash gets treated as part of the command text
+  when reading piped `history` output — not specially parsed out.
+- Plain POSIX `sh`/`dash` has no `history` builtin, so there's no live-history
+  mode for it; only the standalone/file-fallback mode applies.

shist-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "shist"
+dynamic = ["version"]
+description = "TUI to pick commands from your shell history and copy them to the clipboard"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "matplo", email = "noksolp@gmail.com" },
+]
+keywords = ["shell", "history", "tui", "clipboard", "bash", "zsh"]
+classifiers = [
+    "Environment :: Console",
+    "Environment :: Console :: Curses",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=0.60",
+    "pyperclip>=1.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/matplo/shist"
+Repository = "https://github.com/matplo/shist"
+Issues = "https://github.com/matplo/shist/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]
+
+[project.scripts]
+shist = "shist.__main__:main"
+
+[build-system]
+requires = ["setuptools>=68", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+# Version is derived from git tags (e.g. tag "v0.1.0" -> version "0.1.0"),
+# which is what lets the publish workflow just be "push a tag".
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

shist-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shist-0.1.0/shell/shist.sh

@@ -0,0 +1,14 @@
+# shist shell integration — works in both bash and zsh, since both provide
+# a `history` builtin with the same output shape and support this function
+# syntax.
+#
+# Source this from your .bashrc / .zshrc, e.g.:
+#   source /Users/ploskon/devel/shist/shell/shist.sh
+#
+# Then just run `shist` in either shell to pick a command from its live
+# history (including anything typed this session, not yet written to disk)
+# and copy it to the clipboard.
+
+shist() {
+  history | henv -n dev --run shist "$@"
+}

shist-0.1.0/src/shist/__init__.py

@@ -0,0 +1,11 @@
+"""shist — TUI shell-history picker with clipboard copy."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("shist")
+except PackageNotFoundError:
+    # Not installed (e.g. running straight from a source checkout without
+    # `pip install -e .`) -- version comes from setuptools_scm/git tags at
+    # build time, so there's nothing meaningful to report here.
+    __version__ = "0.0.0+unknown"

shist-0.1.0/src/shist/__main__.py

@@ -0,0 +1,112 @@
+"""CLI entry point: figures out where history comes from, hands it to the
+TUI, and copies the result to the clipboard."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import clipboard
+from .history_source import parse_history_output, read_history
+
+
+def _read_piped_history() -> list[str]:
+    """Consume the piped `history` output. Stdin is left as-is here — the
+    real terminal isn't reclaimed until we know there's something to show
+    (see `_reclaim_terminal`), so an empty/no-history case never has to
+    touch `/dev/tty` at all.
+    """
+    raw = sys.stdin.read()
+    return parse_history_output(raw)
+
+
+def _reclaim_terminal() -> bool:
+    """Hand the controlling terminal back to fd 0 so the TUI can read
+    keystrokes from it.
+
+    `shist` is normally invoked as `history | shist`, which makes stdin the
+    *data* channel rather than the keyboard. Once that data's been read, we
+    reopen stdin from the controlling terminal — the same trick tools like
+    fzf use to stay interactive while accepting piped input. Returns False
+    (instead of raising) when there's no controlling terminal to reclaim,
+    e.g. running with no tty at all.
+
+    Textual's driver reads the terminal fd off `sys.__stdin__` specifically,
+    not `sys.stdin` — so both names have to be repointed at the reopened
+    file, or the driver keeps holding the old, now-closed pipe object and
+    raises "I/O operation on closed file".
+    """
+    sys.stdin.close()
+    try:
+        tty = open("/dev/tty")
+    except OSError as exc:
+        print(f"shist: no controlling terminal available ({exc})", file=sys.stderr)
+        return False
+    sys.stdin = tty
+    sys.__stdin__ = tty
+    return True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    from . import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="shist",
+        description="Pick a command from shell history and copy it to the clipboard.",
+    )
+    parser.add_argument(
+        "-V", "--version", action="version", version=f"shist {__version__}"
+    )
+    parser.add_argument(
+        "query", nargs="?", default="", help="initial filter text"
+    )
+    parser.add_argument(
+        "--shell",
+        choices=["bash", "zsh"],
+        default=None,
+        help="which shell's history file to read from, when not given piped history "
+        "(default: guessed from $SHELL)",
+    )
+    parser.add_argument(
+        "--file",
+        type=Path,
+        default=None,
+        help="explicit history file to read from, when not given piped history",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    piped = not sys.stdin.isatty()
+    if piped:
+        commands = _read_piped_history()
+    else:
+        commands = read_history(shell=args.shell, file=args.file)
+
+    if not commands:
+        print("shist: no history found", file=sys.stderr)
+        return 1
+
+    if piped and not _reclaim_terminal():
+        return 1
+
+    # Imported lazily: constructing the Textual App touches the terminal, so
+    # this only happens once we know there's something to show.
+    from .app import run_picker
+
+    result = run_picker(commands, initial_query=args.query)
+    if result is None:
+        return 1
+
+    clipboard.copy(result)
+    count = result.count("\n") + 1
+    plural = "s" if count != 1 else ""
+    print(f"shist: copied {count} command{plural} to clipboard", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())