From 65c74dde5a555e44cba02f13519103954500a2cd Mon Sep 17 00:00:00 2001 From: zphinx Date: Mon, 4 May 2026 04:08:50 +0200 Subject: [PATCH] update Co-authored-by: Copilot --- .gitea/workflows/ci.yml | 6 ++++++ .github/workflows/ci.yml | 6 ++++++ .yamllint.yml | 16 ++++++++++++++++ CHANGELOG.md | 5 ++++- README.md | 6 +++--- ROADMAP.md | 18 +++++++++++------- pyproject.toml | 2 ++ 7 files changed, 48 insertions(+), 11 deletions(-) create mode 100644 .yamllint.yml diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index d37e702..5011c6c 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -88,6 +88,12 @@ jobs: - name: Lint run: .venv/bin/python -m ruff check . + - name: Lint Markdown + run: .venv/bin/mdformat --check README.md ROADMAP.md CHANGELOG.md + + - name: Lint YAML + run: .venv/bin/yamllint . + - name: Type-check run: .venv/bin/python -m mypy src diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8465b2a..08ca86d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,6 +25,12 @@ jobs: - name: Lint run: ruff check . + - name: Lint Markdown + run: mdformat --check README.md ROADMAP.md CHANGELOG.md + + - name: Lint YAML + run: yamllint . + - name: Type-check run: mypy src diff --git a/.yamllint.yml b/.yamllint.yml new file mode 100644 index 0000000..cb10dc2 --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,16 @@ +extends: default + +ignore: | + .git/ + .venv/ + .mypy_cache/ + .pytest_cache/ + .ruff_cache/ + +rules: + document-start: disable + line-length: + max: 120 + truthy: + allowed-values: ["true", "false"] + check-keys: false diff --git a/CHANGELOG.md b/CHANGELOG.md index 068452c..4b57691 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,11 +4,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ---- +______________________________________________________________________ ## [Unreleased] ### Added + - `README.md` — project overview, description, example workflow, supported distributions, and suggested tooling - `ROADMAP.md` — phased development plan covering decisions, data collection, AI integration, CLI design, and hardening - `CHANGELOG.md` — this file; established changelog tracking for the project @@ -27,8 +28,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - Test scaffold (`pytest`) with initial parser and CLI coverage - SSH test coverage for policy checks, SSH argument construction, and config summary behavior - CI workflow for lint (`ruff`), type-check (`mypy`), and tests (`pytest`) +- CI coverage expanded with Markdown formatting checks (`mdformat --check`) and YAML linting (`yamllint`) ### Decided + - Implementation language: **Python** - Distribution strategy: single distributable binary via **Nuitka** (PyInstaller as fallback) - SSH authentication: **keypair only** (ed25519/RSA); auto-accept new hosts; hard reject on host key change with MITM warning diff --git a/README.md b/README.md index 296c068..74ed425 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,8 @@ The agent operates in **read-only mode at all times**. It will never modify the A troubleshooter receives a ticket reporting that the Apache service on a remote server has failed to start. They provide `tai` with: 1. The ticket description or error message -2. The hostname of the affected system -3. Any relevant directories to focus on +1. The hostname of the affected system +1. Any relevant directories to focus on `tai` then connects to the host, reads through system logs, service configurations, and any other related files, and returns a structured analysis of the likely cause along with recommended next steps. @@ -32,4 +32,4 @@ A troubleshooter receives a ticket reporting that the Apache service on a remote | AI inference backend | [vLLM](https://github.com/vllm-project/vllm) | | Model | `gemma4:a4b` | -> **Note:** A suitable implementation language for this project is yet to be determined. \ No newline at end of file +> **Note:** A suitable implementation language for this project is yet to be determined. diff --git a/ROADMAP.md b/ROADMAP.md index 235c6a4..45dbc1d 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,13 +2,14 @@ This document outlines the major decisions, milestones, and development phases required to bring `tai` from concept to a working tool. ---- +______________________________________________________________________ ## Phase 0 — Decisions & Prerequisites These must be resolved before meaningful development can begin. ### Language Selection + - [x] **Decision: Python** - Key factors: native vLLM integration, mature SSH libraries (`paramiko` / `asyncssh`), strong text/log parsing, rapid development - Single binary distribution will be achieved via **Nuitka** (preferred for true compilation) or **PyInstaller** as a fallback @@ -16,12 +17,14 @@ These must be resolved before meaningful development can begin. - [ ] Add binary build step to CI pipeline ### AI Backend & Model + - [ ] Confirm use of [vLLM](https://github.com/vllm-project/vllm) as the inference backend - [ ] Confirm `gemma4:a4b` as the default model (or select an alternative) - [ ] Define minimum hardware requirements for running the model locally - [ ] Decide whether the AI backend is bundled, self-hosted externally, or user-supplied ### SSH Strategy + - [x] **Decision: keypair authentication only** — no password auth; eliminates credential storage risk - Default key resolution: `~/.ssh/id_ed25519`, `~/.ssh/id_rsa` (in order of preference) - CLI override via `--identity-file ` @@ -33,6 +36,7 @@ These must be resolved before meaningful development can begin. - Override switch: `--ignore-ssh-config` to bypass local SSH config when required ### Scope & Constraints + - [ ] Define the supported scope of issues (services, network, disk, kernel, etc.) - [ ] Confirm read-only guarantee — document exactly what "read-only" means in practice - [x] **Decision: interactive REPL mode for v0.1, full TUI for v0.2+** @@ -40,7 +44,7 @@ These must be resolved before meaningful development can begin. - v0.2+: `textual`-based TUI with split panes (collected data | AI output | input bar) - Built-in slash commands: `/collect`, `/show logs`, `/clear`, `/host `, `/help`, `/quit` ---- +______________________________________________________________________ ## Phase 1 — Project Foundation @@ -58,7 +62,7 @@ Basic project scaffolding and connectivity. - [x] Input parser and CLI tests added - [x] SSH module tests added for command policy and SSH argv behavior ---- +______________________________________________________________________ ## Phase 2 — Data Collection Layer @@ -74,7 +78,7 @@ Define what information the agent gathers and how. - [ ] Add support for per-distro variations (Ubuntu vs RHEL path differences, etc.) - [ ] Write tests with mocked SSH output ---- +______________________________________________________________________ ## Phase 3 — AI Integration @@ -87,7 +91,7 @@ Wire collected data into the local AI model. - [ ] Add streaming support for long AI responses - [ ] Evaluate and test model output quality on common issue types ---- +______________________________________________________________________ ## Phase 4 — CLI & User Experience @@ -99,7 +103,7 @@ Polish the interface for real-world use. - [ ] Support output to file or clipboard - [ ] Write man page / `--help` documentation ---- +______________________________________________________________________ ## Phase 5 — Hardening & Distribution @@ -111,7 +115,7 @@ Prepare for broader use. - [ ] Write installation and quickstart documentation - [ ] End-to-end integration tests against a test VM ---- +______________________________________________________________________ ## Decisions Log diff --git a/pyproject.toml b/pyproject.toml index 2e8d855..3c80449 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,8 @@ dev = [ "pytest>=8.2,<9.0", "ruff>=0.5,<1.0", "mypy>=1.10,<2.0", + "mdformat>=0.7,<1.0", + "yamllint>=1.35,<2.0", ] build = [ "nuitka>=2.4,<3.0",