sknext 0.1.0__tar.gz

sknext-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.3
+Name: sknext
+Version: 0.1.0
+Summary: Task status viewer for speckit projects
+Keywords: task,project-management,cli,speckit,development-tools
+Author: Ken Hiatt
+Author-email: Ken Hiatt <ken.hiatt@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/kenhia/sknext
+Project-URL: Repository, https://github.com/kenhia/sknext
+Project-URL: Issues, https://github.com/kenhia/sknext/issues
+Project-URL: Changelog, https://github.com/kenhia/sknext/releases
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# sknext
+
+Task status viewer for speckit projects - a CLI tool to quickly view and track tasks from your project's tasks.md file.
+
+## Features
+
+- 🚀 **Fast**: View next tasks in <2 seconds
+- 🔍 **Multiple Views**: 6 different viewing modes for different workflows
+- 📊 **Auto-Discovery**: Automatically finds latest tasks.md in specs/###-*/ directories
+- 🎨 **Rich Formatting**: Color-coded output with priority and story tag highlighting
+- ✅ **Type Safe**: 100% type-checked with mypy in strict mode
+- 🧪 **Well Tested**: 97 tests with 94% coverage
+
+## Installation
+
+### From PyPI (Recommended)
+
+Once published, install directly from PyPI:
+
+```bash
+pip install sknext
+```
+
+Or with uv:
+
+```bash
+uv pip install sknext
+```
+
+### From Source
+
+For development or to use the latest unreleased version:
+
+```bash
+# Install uv if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and install
+git clone https://github.com/kenhia/sknext.git
+cd sknext
+uv sync
+```
+
+## Usage
+
+### Auto-Discovery from Any Directory
+
+**sknext** automatically detects your project's repository root and finds the latest `tasks.md` file:
+
+```bash
+# Run from any subdirectory in your project
+cd src/mymodule
+sknext
+
+# Run from repository root
+cd /path/to/project
+sknext
+
+# Run from a feature subdirectory
+cd specs/001-my-feature
+sknext
+```
+
+**How it works:**
+1. **Git Detection**: Uses `git rev-parse --show-toplevel` to find repository root (fastest)
+2. **VCS Markers**: Falls back to searching for `.git`, `.hg`, or `.svn` directories (up to 10 levels)
+3. **Specs Fallback**: If no VCS found, searches for `specs/` directory (for non-git projects)
+4. **Latest Discovery**: Finds the highest numbered `specs/###-*/tasks.md` file
+
+This means you can work deep in your codebase and quickly check task status without navigating to the project root!
+
+### Quick Status Check (Default)
+
+Show the next 10 uncompleted tasks with full context:
+
+```bash
+sknext
+# or
+sknext path/to/tasks.md
+```
+
+### Custom Task Count
+
+Show a specific number of tasks:
+
+```bash
+sknext -n 5          # Show next 5 tasks
+sknext -n 25         # Show next 25 tasks
+sknext -n 0          # Show header only (no tasks)
+```
+
+### Phase Overview
+
+Show only phases with uncompleted work (no sections or tasks):
+
+```bash
+sknext --phases-only
+```
+
+Perfect for quick status updates or understanding high-level progress.
+
+### Structure View
+
+Show phases and sections with uncompleted work (no individual tasks):
+
+```bash
+sknext --structure
+```
+
+Useful for sprint planning and understanding work distribution across sections.
+
+### Combined View
+
+Show all incomplete phases followed by N tasks:
+
+```bash
+sknext --all-phases -n 10
+```
+
+Combines strategic overview with tactical next steps - perfect for standups!
+
+### Task-Only View
+
+Show only task lines without any headings:
+
+```bash
+sknext --tasks-only -n 15
+```
+
+Great for copy-pasting into status reports or automated processing.
+
+### All Remaining Tasks
+
+Show every uncompleted task with full context:
+
+```bash
+sknext --all
+```
+
+Perfect for final sprint planning or comprehensive project reviews.
+
+## Troubleshooting
+
+### No tasks.md found
+
+If you get "Error: No Git repository or speckit project detected":
+
+1. **Run from within a project**: Make sure you're inside a git repository or directory with a `specs/` folder
+2. **Check your location**: sknext searches up to 10 parent directories for repository markers
+3. **Verify project structure**: Ensure you have either:
+   - A `.git` directory (git repository)
+   - A `specs/###-feature-name/tasks.md` file structure
+4. **Explicit path**: You can always specify the path directly: `sknext path/to/tasks.md`
+
+### Project Detection
+
+sknext uses a three-tier approach to find your project:
+
+1. **Git command** (`git rev-parse --show-toplevel`) - preferred method
+2. **VCS markers** (`.git`, `.hg`, `.svn` directories) - works in nested repos
+3. **Specs directory** - fallback for non-git projects with specs/ folder
+
+### Empty output
+
+If sknext shows no tasks:
+
+- ✅ All your tasks are complete! Great job!
+- Check if tasks are marked with `- [X]` instead of `- [ ]`
+
+### Performance issues
+
+If sknext is slow:
+
+- Check file size - files with >1000 tasks may take longer
+- Expected: <2s for default view, <3s for files with 500 tasks
+- Auto-discovery adds <200ms overhead for repository detection
+- Report performance issues with file size and timing
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone and setup
+git clone <repository-url>
+cd sknext
+uv sync
+
+# Install pre-commit hooks (optional)
+uv run pre-commit install
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=src/sknext --cov-report=html
+
+# Run specific test
+uv run pytest tests/unit/test_parser.py -xvs
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run ruff format .
+
+# Lint code
+uv run ruff check .
+
+# Type check
+uv run mypy src/sknext
+```
+
+## Architecture
+
+```
+src/sknext/
+├── __init__.py       # Package initialization
+├── __main__.py       # Entry point for python -m sknext
+├── cli.py            # Typer CLI interface
+├── constants.py      # Regex patterns and defaults
+├── models.py         # Frozen dataclasses (Task, Section, Phase)
+├── parser.py         # Line-by-line state machine parser
+├── discovery.py      # Auto-discover tasks.md in specs/
+└── formatter.py      # Rich console output formatters
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass and coverage stays >90%
+5. Run ruff format and mypy
+6. Submit a pull request
+
+## License
+
+[Add your license here]
+
+```bash
+uv run ruff check --fix .
+```
+
+### Type Check
+
+```bash
+uv run mypy src/
+```
+
+## License
+
+MIT

sknext-0.1.0/README.md

@@ -0,0 +1,258 @@
+# sknext
+
+Task status viewer for speckit projects - a CLI tool to quickly view and track tasks from your project's tasks.md file.
+
+## Features
+
+- 🚀 **Fast**: View next tasks in <2 seconds
+- 🔍 **Multiple Views**: 6 different viewing modes for different workflows
+- 📊 **Auto-Discovery**: Automatically finds latest tasks.md in specs/###-*/ directories
+- 🎨 **Rich Formatting**: Color-coded output with priority and story tag highlighting
+- ✅ **Type Safe**: 100% type-checked with mypy in strict mode
+- 🧪 **Well Tested**: 97 tests with 94% coverage
+
+## Installation
+
+### From PyPI (Recommended)
+
+Once published, install directly from PyPI:
+
+```bash
+pip install sknext
+```
+
+Or with uv:
+
+```bash
+uv pip install sknext
+```
+
+### From Source
+
+For development or to use the latest unreleased version:
+
+```bash
+# Install uv if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and install
+git clone https://github.com/kenhia/sknext.git
+cd sknext
+uv sync
+```
+
+## Usage
+
+### Auto-Discovery from Any Directory
+
+**sknext** automatically detects your project's repository root and finds the latest `tasks.md` file:
+
+```bash
+# Run from any subdirectory in your project
+cd src/mymodule
+sknext
+
+# Run from repository root
+cd /path/to/project
+sknext
+
+# Run from a feature subdirectory
+cd specs/001-my-feature
+sknext
+```
+
+**How it works:**
+1. **Git Detection**: Uses `git rev-parse --show-toplevel` to find repository root (fastest)
+2. **VCS Markers**: Falls back to searching for `.git`, `.hg`, or `.svn` directories (up to 10 levels)
+3. **Specs Fallback**: If no VCS found, searches for `specs/` directory (for non-git projects)
+4. **Latest Discovery**: Finds the highest numbered `specs/###-*/tasks.md` file
+
+This means you can work deep in your codebase and quickly check task status without navigating to the project root!
+
+### Quick Status Check (Default)
+
+Show the next 10 uncompleted tasks with full context:
+
+```bash
+sknext
+# or
+sknext path/to/tasks.md
+```
+
+### Custom Task Count
+
+Show a specific number of tasks:
+
+```bash
+sknext -n 5          # Show next 5 tasks
+sknext -n 25         # Show next 25 tasks
+sknext -n 0          # Show header only (no tasks)
+```
+
+### Phase Overview
+
+Show only phases with uncompleted work (no sections or tasks):
+
+```bash
+sknext --phases-only
+```
+
+Perfect for quick status updates or understanding high-level progress.
+
+### Structure View
+
+Show phases and sections with uncompleted work (no individual tasks):
+
+```bash
+sknext --structure
+```
+
+Useful for sprint planning and understanding work distribution across sections.
+
+### Combined View
+
+Show all incomplete phases followed by N tasks:
+
+```bash
+sknext --all-phases -n 10
+```
+
+Combines strategic overview with tactical next steps - perfect for standups!
+
+### Task-Only View
+
+Show only task lines without any headings:
+
+```bash
+sknext --tasks-only -n 15
+```
+
+Great for copy-pasting into status reports or automated processing.
+
+### All Remaining Tasks
+
+Show every uncompleted task with full context:
+
+```bash
+sknext --all
+```
+
+Perfect for final sprint planning or comprehensive project reviews.
+
+## Troubleshooting
+
+### No tasks.md found
+
+If you get "Error: No Git repository or speckit project detected":
+
+1. **Run from within a project**: Make sure you're inside a git repository or directory with a `specs/` folder
+2. **Check your location**: sknext searches up to 10 parent directories for repository markers
+3. **Verify project structure**: Ensure you have either:
+   - A `.git` directory (git repository)
+   - A `specs/###-feature-name/tasks.md` file structure
+4. **Explicit path**: You can always specify the path directly: `sknext path/to/tasks.md`
+
+### Project Detection
+
+sknext uses a three-tier approach to find your project:
+
+1. **Git command** (`git rev-parse --show-toplevel`) - preferred method
+2. **VCS markers** (`.git`, `.hg`, `.svn` directories) - works in nested repos
+3. **Specs directory** - fallback for non-git projects with specs/ folder
+
+### Empty output
+
+If sknext shows no tasks:
+
+- ✅ All your tasks are complete! Great job!
+- Check if tasks are marked with `- [X]` instead of `- [ ]`
+
+### Performance issues
+
+If sknext is slow:
+
+- Check file size - files with >1000 tasks may take longer
+- Expected: <2s for default view, <3s for files with 500 tasks
+- Auto-discovery adds <200ms overhead for repository detection
+- Report performance issues with file size and timing
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone and setup
+git clone <repository-url>
+cd sknext
+uv sync
+
+# Install pre-commit hooks (optional)
+uv run pre-commit install
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=src/sknext --cov-report=html
+
+# Run specific test
+uv run pytest tests/unit/test_parser.py -xvs
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run ruff format .
+
+# Lint code
+uv run ruff check .
+
+# Type check
+uv run mypy src/sknext
+```
+
+## Architecture
+
+```
+src/sknext/
+├── __init__.py       # Package initialization
+├── __main__.py       # Entry point for python -m sknext
+├── cli.py            # Typer CLI interface
+├── constants.py      # Regex patterns and defaults
+├── models.py         # Frozen dataclasses (Task, Section, Phase)
+├── parser.py         # Line-by-line state machine parser
+├── discovery.py      # Auto-discover tasks.md in specs/
+└── formatter.py      # Rich console output formatters
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass and coverage stays >90%
+5. Run ruff format and mypy
+6. Submit a pull request
+
+## License
+
+[Add your license here]
+
+```bash
+uv run ruff check --fix .
+```
+
+### Type Check
+
+```bash
+uv run mypy src/
+```
+
+## License
+
+MIT

sknext-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "sknext"
+version = "0.1.0"
+description = "Task status viewer for speckit projects"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Ken Hiatt", email = "ken.hiatt@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["task", "project-management", "cli", "speckit", "development-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/kenhia/sknext"
+Repository = "https://github.com/kenhia/sknext"
+Issues = "https://github.com/kenhia/sknext/issues"
+Changelog = "https://github.com/kenhia/sknext/releases"
+
+[project.scripts]
+sknext = "sknext.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--cov=src/sknext",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.0",
+]

sknext-0.1.0/src/sknext/__init__.py

@@ -0,0 +1,7 @@
+"""sknext - Task status viewer for speckit projects.
+
+A CLI tool that reads speckit tasks.md files and displays uncompleted tasks
+with flexible viewing options.
+"""
+
+__version__ = "0.1.0"

sknext-0.1.0/src/sknext/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m sknext."""
+
+from sknext.cli import app
+
+if __name__ == "__main__":
+    app()