From 81e8af4d6ba360d9c6ad9b7c6cc54ce208a794b5 Mon Sep 17 00:00:00 2001 From: "A. F. Dudley" Date: Tue, 20 Jan 2026 04:46:24 -0500 Subject: [PATCH] Add development tooling and project configuration Introduce pre-commit hooks, Claude Code guidance, TODO tracking, and pyproject.toml to modernize development workflow. Co-Authored-By: Claude Opus 4.5 --- .pre-commit-config.yaml | 10 ++++ CLAUDE.md | 50 ++++++++++++++++++ TODO.md | 10 ++++ pyproject.toml | 111 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 181 insertions(+) create mode 100644 .pre-commit-config.yaml create mode 100644 CLAUDE.md create mode 100644 TODO.md create mode 100644 pyproject.toml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..2a3c1f8b --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,10 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-json + - id: check-merge-conflict + - id: check-added-large-files diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..65b27524 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,50 @@ +# CLAUDE.md + +This file provides guidance to Claude Code when working with the stack-orchestrator project. + +## Some rules to follow +NEVER speculate about the cause of something +NEVER assume your hypotheses are true without evidence + +ALWAYS clearly state when something is a hypothesis +ALWAYS use evidence from the systems your interacting with to support your claims and hypotheses + +## Key Principles + +### Development Guidelines +- **Single responsibility** - Each component has one clear purpose +- **Fail fast** - Let errors propagate, don't hide failures +- **DRY/KISS** - Minimize duplication and complexity + +## Development Philosophy: Conversational Literate Programming + +### Approach +This project follows principles inspired by literate programming, where development happens through explanatory conversation rather than code-first implementation. + +### Core Principles +- **Documentation-First**: All changes begin with discussion of intent and reasoning +- **Narrative-Driven**: Complex systems are explained through conversational exploration +- **Justification Required**: Every coding task must have a corresponding TODO.md item explaining the "why" +- **Iterative Understanding**: Architecture and implementation evolve through dialogue + +### Working Method +1. **Explore and Understand**: Read existing code to understand current state +2. **Discuss Architecture**: Workshop complex design decisions through conversation +3. **Document Intent**: Update TODO.md with clear justification before coding +4. **Explain Changes**: Each modification includes reasoning and context +5. **Maintain Narrative**: Conversations serve as living documentation of design evolution + +### Implementation Guidelines +- Treat conversations as primary documentation +- Explain architectural decisions before implementing +- Use TODO.md as the "literate document" that justifies all work +- Maintain clear narrative threads across sessions +- Workshop complex ideas before coding + +This approach treats the human-AI collaboration as a form of **conversational literate programming** where understanding emerges through dialogue before code implementation. + +## Insights and Observations + +### Design Principles +- **When something times out that doesn't mean it needs a longer timeout it means something that was expected never happened, not that we need to wait longer for it.** +- **NEVER change a timeout because you believe something truncated, you don't understand timeouts, don't edit them unless told to explicitly by user.** diff --git a/TODO.md b/TODO.md new file mode 100644 index 00000000..8ceb988f --- /dev/null +++ b/TODO.md @@ -0,0 +1,10 @@ +# Stack Orchestrator TODO + +## Pending Features + +### k8s cluster management + +- [ ] Add command to remove unused/empty laconic-* kind clusters + - Should detect clusters with no deployments running + - Command: `laconic-so deploy k8s delete cluster` or similar + - Safety: prompt for confirmation before deletion diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..3d1d2fc0 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,111 @@ +[build-system] +requires = ["setuptools>=61.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "laconic-stack-orchestrator" +version = "1.1.0" +description = "Orchestrates deployment of the Laconic stack" +readme = "README.md" +license = {text = "GNU Affero General Public License"} +authors = [ + {name = "Cerc", email = "info@cerc.io"} +] +requires-python = ">=3.8" +classifiers = [ + "Programming Language :: Python :: 3.8", + "Operating System :: OS Independent", +] +dependencies = [ + "python-decouple>=3.8", + "python-dotenv==1.0.0", + "GitPython>=3.1.32", + "tqdm>=4.65.0", + "python-on-whales>=0.64.0", + "click>=8.1.6", + "PyYAML>=6.0.1", + "ruamel.yaml>=0.17.32", + "pydantic==1.10.9", + "tomli==2.0.1", + "validators==0.22.0", + "kubernetes>=28.1.0", + "humanfriendly>=10.0", + "python-gnupg>=0.5.2", + "requests>=2.3.2", +] + +[project.optional-dependencies] +dev = [ + "pytest>=7.0.0", + "pytest-cov>=4.0.0", + "black>=22.0.0", + "flake8>=5.0.0", + "pyright>=1.1.0", + "ansible-lint>=6.0.0", + "yamllint>=1.28.0", + "pre-commit>=3.0.0", +] + +[project.scripts] +laconic-so = "stack_orchestrator.main:cli" + +[project.urls] +Homepage = "https://git.vdb.to/cerc-io/stack-orchestrator" + +[tool.setuptools.packages.find] +where = ["."] + +[tool.setuptools.package-data] +"*" = ["data/**"] + +[tool.black] +line-length = 88 +target-version = ['py38'] + +[tool.flake8] +max-line-length = 88 +extend-ignore = ["E203", "W503"] + +[tool.pyright] +pythonVersion = "3.9" +typeCheckingMode = "basic" +reportMissingImports = "none" +reportMissingModuleSource = "none" +reportUnusedImport = "error" +include = ["stack_orchestrator/**/*.py", "tests/**/*.py"] +exclude = ["**/build/**", "**/__pycache__/**"] + +[tool.mypy] +python_version = "3.8" +warn_return_any = true +warn_unused_configs = true +disallow_untyped_defs = true + +[tool.pytest.ini_options] +testpaths = ["tests"] +python_files = ["test_*.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +markers = [ + "slow: marks tests as slow (deselect with '-m \"not slow\"')", + "e2e: marks tests as end-to-end (requires real infrastructure)", +] +addopts = [ + "--cov", + "--cov-report=term-missing", + "--cov-report=html", + "--strict-markers", +] +asyncio_default_fixture_loop_scope = "function" + +[tool.coverage.run] +source = ["stack_orchestrator"] +disable_warnings = ["couldnt-parse"] + +[tool.coverage.report] +exclude_lines = [ + "pragma: no cover", + "def __repr__", + "raise AssertionError", + "raise NotImplementedError", +]