Development

Setting Up uv

This project is set up to use uv to manage Python and dependencies. First, be sure you have uv installed.

Then fork the jlevy/kash-shell repo (having your own fork will make it easier to contribute) and clone it.

Basic Developer Workflows

The Makefile simply offers shortcuts to uv commands for developer convenience. (For clarity, GitHub Actions don’t use the Makefile and just call uv directly.)

# Apply the supply-chain cool-off to direct uv commands below. The Makefile sets
# the same default for its recipes; override the variable explicitly if needed.
export UV_EXCLUDE_NEWER="14 days"

# First, install all dependencies and set up your virtual environment.
# This runs `uv sync --all-extras --all-groups` to install runtime, development,
# optional, and locked build dependencies.
make install

# Run uv sync, lint, and test:
make

# Build wheel:
make build

# Linting (auto-fixes formatting and lint issues):
make lint

# Linting in check-only mode, matching CI (fails on issues, does not modify files):
make lint-check

# Run tests:
make test

# Delete all the build artifacts:
make clean

# Upgrade dependencies to compatible versions:
make upgrade

# To run tests by hand:
uv run pytest   # all tests
uv run pytest -s src/module/some_file.py  # one test, showing outputs

# Build and install current dev executables, to let you use your dev copies
# as local tools:
uv tool install --editable .

# Dependency management directly with uv:
# Add a new dependency:
uv add package_name
# Add a development dependency:
uv add --dev package_name
# Update to latest compatible versions (including dependencies on git repos):
uv sync --upgrade
# Update a specific package:
uv lock --upgrade-package package_name

# Run a shell within the Python environment:
uv venv
source .venv/bin/activate

See uv docs for details.

IDE setup

If you use VSCode or a fork like Cursor or Windsurf, you can install the following extensions:

• Python

• Based Pyright for type checking. Note that this extension works with non-Microsoft VSCode forks like Cursor.

Supply Chain Hardening

Dependencies are an attack surface. Before adding or upgrading any dependency, follow supply-chain-hardening, a concise cross-ecosystem guide on installing dependencies safely. Its key defaults:

• Cool-off period: Don’t install or upgrade to a release less than 14 days old (absent a documented exception); most malicious publishes are caught within days. For uv, set UV_EXCLUDE_NEWER to a cool-off window (recent uv accepts a relative duration like "14 days"); this project sets it in pyproject.toml, CI, and the Makefile so direct commands and standard workflows default to the same policy. Override it explicitly for a stricter window, such as UV_EXCLUDE_NEWER="30 days" make upgrade. A reviewed emergency exception must be equally explicit, using UV_EXCLUDE_NEWER="0 days" only for that invocation and recording why the normal gate was bypassed.

• Vet before adding: Confirm the package is actually needed and its name is spelled correctly (typosquats are common), and prefer a little first-party code over a new dependency.

• Pin, lock, and audit: Commit your uv.lock, pin GitHub Actions to a commit SHA or immutable tag, and run a vulnerability audit (e.g. pip-audit) after changes.

Publishing Releases

See publishing.md for instructions on publishing to PyPI.

Documentation

• uv docs

• basedpyright docs

---

This file was built with simple-modern-uv.