build(deps): bump actions/checkout from 4 to 6

.dockerignore

@@ -0,0 +1,18 @@
+.venv/
+.git/
+.pytest_cache/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.mypy_cache/
+.ruff_cache/
+*.png
+*.svg
+*.mp4
+*.apng
+*.mov
+misc/
+scripts/
+docs/
+examples/

.gitattributes

@@ -0,0 +1 @@
+*.mp4 filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -11,13 +11,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
 
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
@@ -36,3 +36,21 @@ jobs:
 
       - name: Test
         run: uv run pytest --cov=src --cov-report=xml
+
+  test-windows:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python 3.10
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Test
+        run: uv run pytest --cov=src --cov-report=xml

.github/workflows/pages.yml

@@ -0,0 +1,21 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Deploy
+        run: uvx --with mkdocs-material mkdocs gh-deploy --force

.github/workflows/publish.yml

@@ -9,10 +9,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v7
 
       - name: Build
         run: uv build

.gitignore

@@ -38,3 +38,5 @@ Thumbs.db
 NOTES.md
 TASKS.md
 tests/example_dirplot.png
+tests/animation/
+demo/

.pre-commit-config.yaml

@@ -15,3 +15,12 @@ repos:
       - id: ruff
         args: [--fix]
       - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src
+        language: system
+        pass_filenames: false
+        types: [python]

CONTRIBUTING.md

@@ -3,29 +3,66 @@
 ## Development Setup
 
 ```bash
-git clone https://github.com/deeplook/dirplot
+git clone -c credential.helper= https://github.com/deeplook/dirplot
 cd dirplot
-uv sync --all-extras
-uv run pre-commit install
+uv sync --all-extras   # install all dependencies including dev tools and extras
+uv run pre-commit install  # install git hooks for formatting/linting
+```
+
+## Running Tests
+
+```bash
+make test       # run the full test suite
+make coverage   # run with coverage report (target: 90% line coverage)
+```
+
+To run a specific test file or test:
+
+```bash
+uv run pytest tests/test_cli.py
+uv run pytest tests/test_drawing.py::test_cushion_shading -v
 ```
 
 ## Code Style
 
-This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy.readthedocs.io/) for type checking.
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy.readthedocs.io/) for type checking. Pre-commit hooks run these automatically on each commit.
 
 ```bash
 make format   # auto-format and fix lint issues
 make lint     # check only (no changes)
 ```
 
-## Testing
+## Code Organisation
 
-```bash
-make test       # run the test suite
-make coverage   # run with coverage report
 ```
+src/dirplot/
+  app.py            — Typer app entry point; imports all subcommands
+  main.py           — CLI entry point called by the `dirplot` script
+  commands/
+    treemap.py      — `dirplot map` command
+    diff.py         — `dirplot diff` command
+    vcs.py          — `dirplot git` and `dirplot hg` commands
+    watch.py        — `dirplot watch` command
+    replay.py       — `dirplot replay` command
+    misc.py         — `dirplot demo`, `dirplot termsize`, `dirplot read-meta`
+  render_png.py     — PNG treemap renderer (Pillow)
+  render_svg.py     — SVG treemap renderer
+  layout.py         — squarified treemap layout algorithm
+  scanner.py        — local filesystem scanner and metrics
+  display.py        — inline terminal display (iTerm2 / Kitty protocols)
+  terminal.py       — terminal size detection
+  github.py         — GitHub Git Trees API backend
+  ssh.py            — SSH backend (paramiko)
+  s3.py             — AWS S3 backend (boto3)
+  docker.py         — Docker backend (docker exec)
+  k8s.py            — Kubernetes backend (kubectl exec)
+  archive.py        — archive reading (zip, tar, 7z, rar, libarchive)
+  node.py           — Node dataclass (shared tree representation)
+```
+
+All remote backends return a `Node` tree using the same dataclass, so `create_treemap` and `create_treemap_svg` work identically regardless of source.
 
-Target: 90 % line coverage.
+To add a new command: create `src/dirplot/commands/mycommand.py` with a Typer app, then import and add it in `app.py`.
 
 ## Submitting Changes
 

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12.13-slim
+
+WORKDIR /app
+
+# Install build tools needed by some optional deps
+RUN pip install --no-cache-dir uv==0.11.3
+
+# Copy project metadata first for layer caching
+COPY pyproject.toml README.md ./
+
+# Copy source
+COPY src/ src/
+
+# Install dirplot with all extras (no dev tools in the runtime image)
+RUN uv pip install --system --no-cache ".[ssh,s3]"
+
+# Copy the rest (tests, docs, etc.) so the container is a useful scan target
+COPY . .
+
+# Run as non-root
+RUN useradd -m app && chown -R app /app
+USER app
+
+# Keep the container running so docker:// scanning works
+CMD ["python", "-c", "import time; time.sleep(1e9)"]

Makefile

@@ -1,38 +1,45 @@
-.PHONY: install lint format test coverage clean install-tool check-all publish-test publish
+.PHONY: install lint format test coverage clean install-tool check-all publish-test publish serve-docs help
 
-install:
-	uv sync --all-extras
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  %-14s %s\n", $$1, $$2}'
 
-lint:
-	uv run ruff check src tests
-	uv run --all-extras mypy src
+install:  ## Install all dependencies (including extras)
+	uv sync --all-extras
 
-format:
+format:  ## Auto-format and fix lint issues
 	uv run ruff format src tests
 	uv run ruff check --fix src tests
 
-test:
+lint:  ## Run ruff and mypy
+	uv run ruff check src tests
+	uv run --all-extras mypy src
+
+test:  ## Run the test suite
 	uv run --all-extras pytest
 
-coverage:
+coverage:  ## Run tests with HTML + terminal coverage report
 	uv run --all-extras pytest --cov=src --cov-report=html --cov-report=term
 
-clean:
+check-all: install format lint test clean  ## Run format, lint, test, and clean
+	@echo "All checks passed!"
+
+install-tool:  ## Install dirplot as a uv tool (reinstall)
+	uv tool install --reinstall .
+
+clean:  ## Remove build artifacts and caches
 	rm -rf dist build *.egg-info
 	rm -rf .pytest_cache .mypy_cache .ruff_cache
 	rm -rf htmlcov .coverage coverage.xml
 	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name .DS_Store -exec rm {} +
 
-install-tool:
-	uv tool install --reinstall .
-
-publish-test:
+publish-test:  ## Build and publish to TestPyPI
 	uv build
 	uv publish --index testpypi --token $(TEST_PYPI_TOKEN)
 
-publish:
+publish:  ## Build and publish to PyPI
 	uv build
 	uv publish --token $(PYPI_TOKEN)
 
-check-all: install format lint test clean
-	@echo "All checks passed!"
+serve-docs:  ## Serve the MkDocs documentation locally (http://localhost:8000)
+	uv run --with mkdocs-material mkdocs serve