quick-status 0.6.0__tar.gz

quick_status-0.6.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+One sentence explaining what this PR does.
+
+Follow this format by default, but you can deviate if that makes the PR
+clearer, for example for an unusually large PR.
+
+## Related:
+Optional. Use only if truly needed. Link related issues, docs, PRs, or
+discussion.
+- ...
+
+## Changes:
+What changed in the final state of the PR. Describe the current behavior the
+reader needs to know. Do not narrate the whole implementation history of the PR.
+Be concise.
+- ...
+- ...
+
+## Why:
+What problem this solves and why the changes were needed.
+Be concise.
+- ...
+- ...
+
+## Details:
+Optional. Use only if truly needed. Use this for important details or gotchas
+that would clutter the changes section.
+- ...
+
+## How To Try It:
+Optional. Use only if truly needed. Use this when a reviewer would benefit
+from commands, paths, task ids, or links to inspect the change directly. Do
+not repeat generic CI or test output.
+- ...

quick_status-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,141 @@
+name: Checks
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    name: Ruff
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install Ruff
+        run: python -m pip install ruff==0.15.9
+
+      - name: Ruff format
+        run: python -m ruff format --check --diff .
+
+      - name: Ruff lint
+        run: python -m ruff check --output-format=full .
+
+  python-checks:
+    name: Ruff + Mypy + Pytest
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Ruff format
+        run: python -m ruff format --check --diff .
+
+      - name: Ruff lint
+        run: python -m ruff check --output-format=full .
+
+      - name: Mypy static type checks
+        run: python -m mypy
+
+      - name: Pytest tests
+        run: python -m pytest
+
+  package-pip:
+    name: Package Build (pip)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Build package
+        run: python -m build
+
+      - name: Install built wheel
+        run: python -m pip install --force-reinstall dist/*.whl
+
+      - name: Smoke test installed package
+        run: |
+          python -c "import quick_status; print(quick_status.__version__)"
+          quick-status --version
+
+  package-uv:
+    name: Package Build (uv)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install Python dependencies
+        run: uv sync --extra dev --locked
+
+      - name: Build package
+        run: uv build
+
+      - name: Install built wheel
+        run: uv pip install --force-reinstall dist/*.whl
+
+      - name: Smoke test installed package
+        run: |
+          uv run --no-sync python -c "import quick_status; print(quick_status.__version__)"
+          uv run --no-sync quick-status --version

quick_status-0.6.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+          python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quick_status-0.6.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.Python
+.venv/
+venv/
+env/
+ENV/
+
+build/
+dist/
+*.egg-info/
+.eggs/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.env
+.env.*
+
+.DS_Store
+.idea/
+.vscode/

quick_status-0.6.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff
+      - id: ruff-format
+        args: ["--check"]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-symlinks
+      - id: destroyed-symlinks
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-added-large-files
+        args: ["--maxkb=2000"]
+      - id: check-shebang-scripts-are-executable
+      - id: detect-private-key
+      - id: debug-statements
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal

quick_status-0.6.0/.python-version

@@ -0,0 +1 @@
+3.11

quick_status-0.6.0/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+Repo-specific instructions for agents working with the `quick-status` package.
+
+## Package Conventions
+
+- Keep importable package code under `src/quick_status/`.
+- Put CLI entrypoint behavior in `src/quick_status/cli.py`.
+
+## Validation
+
+- Run checks relevant to the files changed.
+- For README/docs-only changes, run formatting and pre-commit hygiene.
+- For Python or packaging changes, also run Ruff, mypy, pytest, and build
+  checks.
+
+## Pull Requests
+
+- Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions.
+- Do not commit secrets, credentials, local runtime config, or scratch notes.
+- Keep `AGENTS.md` updated when recurring agent instructions become
+  repo-specific.

quick_status-0.6.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: quick-status
+Version: 0.6.0
+Summary: Quick local status snapshots for developer workspaces.
+Project-URL: Homepage, https://github.com/alik-git/quick-status
+Project-URL: Repository, https://github.com/alik-git/quick-status
+Project-URL: Issues, https://github.com/alik-git/quick-status/issues
+Author-email: Ali K <alikgithb@gmail.com>
+Maintainer-email: Ali K <alikgithb@gmail.com>
+Keywords: cli,developer-tools,git,status
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# quick-status
+
+Quick local status snapshots for developer workspaces.
+
+## Installation
+
+Recommended with `uv`:
+
+```bash
+uv sync --extra dev
+```
+
+Standard Python fallback:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+quick-status
+quick-status repo
+quick-status repo --json
+quick-status repo --github
+quick-status repo --cwd /path/to/repo
+quick-status repo --verbose
+quick-status repo --plain
+quick-status repo --non-compact
+quick-status repo --worktrees
+quick-status repo --stashes --stash-limit 5
+quick-status repo --color=always
+quick-status env
+quick-status env --cwd /path/to/project
+quick-status env --json
+quick-status ci
+quick-status ci --json
+quick-status ci --cwd /path/to/repo
+quick-status ci --log-tail 40
+quick-status --version
+```
+
+`quick-status` is an alias for `quick-status repo`. By default it performs a fast local
+Git snapshot only. It does not fetch, push, pull, run tests, run builds, or call
+network services.
+
+Example human output:
+
+```text
+REPO quick-status /home/ali/Projects/quick-status
+BRANCH main 6acc81f origin/main synced ahead=0 behind=0
+STATE clean staged=0 unstaged=0 untracked=0 conflicts=0 stash=0
+REMOTE origin git@github.com:alik-git/quick-status.git
+SUBMODULES none
+PR not-requested
+CI not-requested
+```
+
+Repo output is compact by default. Use `--non-compact` when you want the
+sectioned human summary.
+
+Use `--worktrees` when you want the linked worktree map for the current repo
+family:
+
+```bash
+quick-status repo --worktrees
+```
+
+Use `--stashes` when you need bounded stash details in addition to the normal
+stash count:
+
+```bash
+quick-status repo --stashes
+quick-status repo --stashes --stash-limit 10
+```
+
+These are read-only inventory flags. They do not create, prune, apply, drop, or
+repair anything.
+
+Use `--json` when another tool or agent should consume the snapshot:
+
+```bash
+quick-status repo --json
+```
+
+Use `--github` only when you want read-only GitHub context through the `gh` CLI:
+
+```bash
+quick-status repo --github
+quick-status repo --json --github
+```
+
+GitHub mode reports PR, CI/check, and package-release facts when available. If
+`gh` is missing, unauthenticated, offline, or rate-limited, the local snapshot
+still succeeds and the GitHub section is marked unavailable.
+
+For human output, `--github` prints and flushes the local Git facts before
+running GitHub checks, then appends PR, CI, and release facts when they are
+ready. JSON output remains a single complete object printed at the end.
+
+`quick-status` reports facts and neutral summaries only. It intentionally does not
+decide whether a repo is ready to commit, push, merge, or release.
+
+## CI Snapshots
+
+Use `quick-status ci` when you need the deeper GitHub CI facts behind a branch or
+PR:
+
+```bash
+quick-status ci
+quick-status ci --cwd ~/Projects/worksets/devpy_work/devpy-runner
+quick-status ci --json
+quick-status ci --verbose
+quick-status ci --log-tail 40
+```
+
+`quick-status ci` is read-only. It does not fetch, push, rerun workflows, cancel
+runs, or open a browser. It reports local `HEAD`, worktree cleanliness, the
+current PR when one exists, expected SHA, current/stale/absent CI evidence,
+check buckets, workflow run URLs, and failed job URLs.
+
+Example no-PR output:
+
+```text
+CI quick-status alik-git/quick-status
+BRANCH main local=4955870 upstream=origin/main synced
+STATE clean staged=0 unstaged=0 untracked=0 conflicts=0
+PR none
+CURRENT current expected=4955870 checked=4955870 source=run-list-commit reason=run-exists-for-expected-sha
+RUNS success total=1 pass=1 fail=0 pending=0 running=0 skipped=0 cancel=0 unknown=0 applies_to_head=yes
+RUN Checks success id=26352434014 sha=4955870 currentness=current url=https://github.com/alik-git/quick-status/actions/runs/26352434014
+```
+
+`--log-tail N` is intentionally simple and opt-in. For failed current GitHub
+Actions runs, it prints the last `N` non-empty lines from `gh run view
+--log-failed`. If log fetching is unavailable, the snapshot still succeeds and
+prints `LOG unavailable`.
+
+Human output uses color automatically when stdout is an interactive terminal.
+Machine-readable JSON is never colorized. To control ANSI color explicitly:
+
+```bash
+quick-status repo --plain        # no ANSI color
+quick-status repo --color=never  # no ANSI color
+quick-status repo --color=always # force ANSI color
+```
+
+`--plain` overrides `--color`. Automatic color also honors the standard
+`NO_COLOR` environment variable and disables color when `TERM=dumb`.
+
+## Environment Snapshots
+
+Use `quick-status env` to inspect Python, conda, venv, devpy, uv, and py_runner facts
+without activating or modifying anything:
+
+```bash
+quick-status env
+quick-status env --cwd ~/Projects/motion_data_processing_worktree1
+quick-status env --show-all
+quick-status env --show-tools --show-hints
+quick-status env --abs-paths
+quick-status env --compact
+quick-status env --json
+quick-status env --verbose
+```
+
+Example for a normal Python project:
+
+```text
+SHELL
+  cwd  ~/Projects/quick-status
+  kind=neutral  conda=none  venv=none
+PYTHON
+  runtime  ~/.local/share/uv/tools/quick-status/bin/python3
+  python   missing
+  python3  /usr/bin/python3
+  version=3.14.4  venv_like=yes
+PROJECT
+  root  ~/Projects/quick-status
+  pyproject=ok  uv.lock=yes  devpy=no  .venv=yes
+```
+
+Example for a `devpy`-backed worktree:
+
+```text
+PROJECT
+  root  ~/Projects/motion_data_processing_worktree1
+  name=motion-data-processing  pyproject=ok  uv.lock=yes  devpy=yes  .venv=yes
+DEVPY
+  venv  ~/Projects/motion_data_processing_worktree1/.venv
+  base=mdp_shared  status=ok  venv_python=yes  editables=3
+```
+
+Use `--show-all`, `--show-tools`, `--show-hints`, or `--show-home` when you need
+those extra sections:
+
+```text
+TOOLS
+  uv  ~/.local/bin/uv
+  conda  ~/miniconda3/condabin/conda
+  devpy  ~/.local/bin/devpy
+  py_runner  ~/.agent_files/py_runner/run
+HINTS devpy_python=devpy python
+      py_runner_overlay:
+        ~/.agent_files/py_runner/run \
+          --env mdp_shared \
+          --python .venv/bin/python
+```
+
+`quick-status env` treats tools like `python`, `python3`, `pip`, `conda`, `devpy`,
+`uv`, and `py_runner` as optional facts. Missing tools are reported as missing
+instead of crashing the command. Human output compacts home-relative paths with
+`~`; pass `--abs-paths` when exact absolute paths are more useful. Default env
+collection is path-based and avoids slow `--version` subprocesses; use
+`--verbose` when you want those command records and version probes. `quick-status
+repo` still requires `git`, but reports a missing Git executable directly
+instead of confusing it with a non-repository path.
+
+## Development
+
+Read these docs first when changing the package:
+
+- [Repo Overview](docs/repo_overview.md): mental model, public surface, module
+  ownership, and design rules
+- [API](docs/api.md): command surface, JSON schemas, exit codes, GitHub mode,
+  and env snapshot behavior
+
+Run the standard checks before opening a PR:
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+If you are using standard Python tools instead of uv:
+
+```bash
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy
+python -m pytest
+python -m build
+```
+
+## Publishing
+
+This repo publishes to PyPI through GitHub Actions Trusted Publishing. The
+release workflow is [`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+Use these values in PyPI's pending trusted publisher form:
+
+```text
+PyPI project name: quick-status
+Owner: alik-git
+Repository name: quick-status
+Workflow name: release.yml
+Environment name: pypi
+```
+
+The workflow filename is `release.yml`; the display name inside that file is
+`Release`, but PyPI wants the filename. The `pypi` environment should also exist
+under the GitHub repository's environment settings.
+
+Publishing is release-driven: normal pushes and pull requests build and test the
+package, but publishing happens when a GitHub Release is published or the release
+workflow is manually dispatched.