ftmon 2.0.0a1__tar.gz

ftmon-2.0.0a1/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+# The same gate contributors run locally (README "Development" section).
+# Deterministic by design: realsystem tests are deselected by pytest defaults.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q

ftmon-2.0.0a1/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+# Tag-driven release: v* tags run the full gate, build sdist+wheel, publish
+# to PyPI via Trusted Publishing (OIDC - no stored API tokens), then attach
+# the artifacts to a GitHub Release. The PyPI side requires a (pending)
+# trusted publisher registered for project "ftmon" with this repository,
+# workflow file "release.yml", and environment "pypi".
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      # The tag must match the built version so PyPI, the GitHub Release,
+      # and `ftmon --version` can never disagree.
+      - name: Check tag matches package version
+        run: |
+          version=$(uv run python -c "import ftmon; print(ftmon.__version__)")
+          test "v${version}" = "${GITHUB_REF_NAME}" || {
+            echo "tag ${GITHUB_REF_NAME} != package version v${version}" >&2
+            exit 1
+          }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ftmon
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          prerelease=""
+          case "${GITHUB_REF_NAME}" in
+            *a*|*b*|*rc*) prerelease="--prerelease" ;;
+          esac
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes ${prerelease}

ftmon-2.0.0a1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.coverage
+# Local AI-agent session state (tool permission grants), not project content.
+.claude/
+# The original GPLv2 Perl project is published on SourceForge. Keep any local
+# reference checkout out of this MIT-licensed v2 repository.
+ftmon-legacy/
+ftmon_legacy/

ftmon-2.0.0a1/AGENTS.md

@@ -0,0 +1,44 @@
+# Repository Guidelines
+
+> **Note to AI Agents:** The comprehensive, up-to-date instructions, architecture, and workflow for this repository are maintained in [CLAUDE.md](CLAUDE.md). Please read `CLAUDE.md` before proceeding with any code changes.
+
+## Project Structure & Module Organization
+
+This repository contains FTMON v2. The original Perl implementation remains
+separately published at <https://sourceforge.net/projects/ftmon/> and must not
+be added to this repository.
+
+- `SPEC.md` is the authoritative product and architecture specification for new work. Requirements have stable IDs and tests should reference them.
+- `CLAUDE.md` summarizes the v2 architecture, commands, and the spec/traceability workflow for AI coding agents.
+- `README.md` gives users and contributors the repository entry point.
+- `docs/` contains the install guide, user manual, and definition reference.
+
+New v2 code should follow `SPEC.md`: Python package code in `ftmon/`, tests in `tests/`, and user-editable monitor definitions as TOML.
+
+## Build, Test, and Development Commands
+
+Use the checked-in `uv` environment for development and validation:
+
+```sh
+uv sync
+uv run ruff check src tests
+uv run pytest -q
+```
+
+## Coding Style & Naming Conventions
+
+For v2, follow `SPEC.md`: Python 3.11+, `uv`, `ruff`, `pytest`, SQLite, and TOML monitor definitions. Keep platform-specific logic behind the specified adapters.
+
+## Testing Guidelines
+
+Add pytest coverage for all v2 behavior. Name tests by behavior, and include requirement IDs from `SPEC.md` where relevant, for example `test_daemon_rejects_second_instance_pm_02`. Prefer fixture-driven deterministic tests; keep real-system smoke tests opt-in.
+
+## Commit & Pull Request Guidelines
+
+This repository has no existing commit history, so no local convention is established. Use concise, imperative commit subjects such as `Add daemon lock handling` or `Document legacy config validation`.
+
+Pull requests should describe the change, reference affected `SPEC.md` requirement IDs, and list validation commands run. Include screenshots only for web UI changes.
+
+## Security & Configuration Tips
+
+Monitor definitions must remain declarative TOML with restricted expression evaluation, as specified in `SPEC.md`.

ftmon-2.0.0a1/CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+FTMON v2 is a lightweight, local-first, single-host systems monitor for Linux
+(Python ≥ 3.11, MIT). It detects memory leaks, CPU hogs, disks filling, service
+failures, and notable journal events; keeps bounded metric history in SQLite;
+and exposes a CLI, a loopback-only web dashboard, and a local stdio MCP server.
+
+It succeeds a GPL-licensed Perl monitoring engine from 2001–2003, porting its
+design ideas (delta/monotonic calcs, consecutive-cycle confirmation,
+baselining, escalation) but none of its code. The original source is
+intentionally kept out of this repository (a local reference checkout may sit
+in the gitignored `ftmon-legacy/`) and remains available at
+<https://sourceforge.net/projects/ftmon/>. Do not vendor it here — the MIT/GPL
+boundary is deliberate.
+
+## Commands
+
+Everything runs through `uv`:
+
+```sh
+uv sync                        # install/refresh the environment
+uv run ruff check src tests    # lint (ruff is also the formatter; line length 100)
+uv run pytest -q               # full gate: unit + e2e + traceability (~20 s)
+uv run pytest tests/unit/test_expr_eval.py -q          # one file
+uv run ftmon init --profile desktop|server             # write config + builtin definitions
+uv run ftmon check             # one-shot sample/evaluate
+uv run ftmon daemon            # the monitor loop
+uv run ftmon web               # dashboard on http://127.0.0.1:8420/ (loopback only)
+uv run ftmon doctor            # DB/config diagnostics
+python3 tools/gen_reqindex.py --check   # regenerate/verify tests/reqindex.json from SPEC.md
+```
+
+Real-system smoke tests are opt-in (deselected by default); the CI suite is
+deterministic and fixture-driven.
+
+## Spec-driven workflow (the central process fact)
+
+`SPEC.md` is the authoritative product spec; `DESIGN.md` is the companion
+design (elements marked FROZEN must not be changed without amending the doc
+first). Every requirement has a stable ID like `SA-06`, `IN-03`, `EC-02`.
+
+Traceability is machine-enforced by `tests/unit/test_traceability.py` (TS-01):
+
+- Tests cite the requirement IDs they verify in **bracketed docstrings**:
+  `"""[EX-06] ..."""`.
+- `tests/reqindex.json` is generated from SPEC.md by `tools/gen_reqindex.py`
+  and must match on regeneration; `tests/traceability_pending.json` lists
+  testable IDs not yet covered (a ratchet — an ID can't be both covered and
+  pending).
+- Adding/changing a requirement ⇒ regenerate the index. Covering a pending
+  ID ⇒ remove it from the pending list. `NG-*`/`DO-*` IDs are exempt.
+
+When you land a user-visible change, updating the matching docs
+(`docs/manual.md`, `docs/install.md`, `docs/definitions.md`) is part of the
+work package, not a follow-up. See `CONTRIBUTING.md` — its prime rule:
+comments/docstrings record **why** (constraint, trade-off, spec ID), never
+narrate mechanics. Every module docstring cites the spec IDs that shaped it.
+
+## Architecture
+
+Package layout (full annotated tree in DESIGN.md §1):
+
+- `src/ftmon/expr/` — restricted expression language (parse → IR → eval).
+  **Stdlib-only, imports nothing from `ftmon.*`** (EX-04); `eval` never raises
+  (EX-06) — errors become `None` plus a counter tick. Three-valued logic in
+  `tribool.py`.
+- `src/ftmon/definitions/` — TOML monitor definitions: `schema.py` validator,
+  `loader.py` (TOML → `MonitorDef`, topo-sorted derived metrics), and
+  `builtins/*.toml` package data. **Definitions are data, never code.** The
+  normative copies live in `design/builtins/*.toml` and are mirrored into
+  `src/ftmon/definitions/builtins/`; keep the two trees identical.
+- `src/ftmon/sources/` — `Sampler`/`EventSource` implementations (process,
+  disk, system, net, unit, journald) plus deterministic `fixtures.py` fakes
+  that ship in the prod package and keep the platform seams honest (PL-04).
+- `src/ftmon/checks/` — administrator-registered external checks: `registry.py`
+  (argv authority), `runner.py` (no shell, scrubbed env, process-group kill,
+  bounded output), Nagios/FTMON-JSON adapters. AI/definitions may reference a
+  check alias but can never create one (EC-01).
+- `src/ftmon/engine/` — scheduler tick loop, per-monitor `pipeline.py`
+  (snapshot → rings → derived → rules), ring buffers, `incidents.py` (pure
+  state machine, FROZEN), episodes, effects/actions.
+- `src/ftmon/store/` — SQLite (WAL, incremental autovacuum): migrations gated
+  by `PRAGMA user_version`, daemon-side batched `writer.py`, shared `query.py`,
+  retention/rollups, durable notification `outbox.py`.
+- `src/ftmon/notify/` — desktop/file/ntfy/webhook/SMTP adapters with
+  independent durable retry.
+- `daemon.py` (composition root; owns the only bulk-write connection),
+  `cli.py`, `mcp_server.py`, `web/` (operational app + isolated synthetic demo
+  app), `demo.py`, `selfmon.py`, `systemd/` units.
+
+Key invariants:
+
+- **No direct time access** — `time.time`/`datetime.now`/`time.sleep` only in
+  `clock.py` (TS-03); everything else takes an injected `Clock`.
+- Platform-specific behavior lives behind exactly four seams: samplers, event
+  sources, notification adapter, paths/service wrapper (PL-01). No platform
+  conditionals elsewhere.
+- The web UI binds to 127.0.0.1 only; no auth exists by design (NG-05) — never
+  add a non-loopback listener.
+- Core model types are frozen dataclasses; the pipeline is pure-ish data flow
+  so incidents can be tested independently.
+- Respect SPEC §1.1 non-goals (fleet monitoring, plugin loading, etc.) — they
+  are enforced scope, not TODOs.
+
+## Conventions
+
+- Lint rules are enforced as tests; `uv run pytest -q` is the gate for
+  everything.
+- Name tests by behavior and requirement, e.g.
+  `test_daemon_rejects_second_instance_pm_02`.
+- Commit subjects are concise and imperative, often milestone-prefixed
+  (`M9: add bounded external checks`, `Docs: ...`).
+- `dist/`, `.venv/`, caches, and `ftmon-legacy/` are gitignored; don't commit
+  build artifacts or the legacy tree.

ftmon-2.0.0a1/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing / Documentation Standard
+
+This project is built spec-first and implemented partly by AI models working
+from frozen contracts. Documentation is how rationale survives that process.
+These rules are binding for all code, human- or model-written.
+
+## The prime rule: document the WHY
+
+Code shows *what* it does; comments and docstrings exist to record what the
+code cannot show — **why it is this way**: the constraint, the trade-off, the
+rejected alternative, the spec requirement. A comment that restates the next
+line is noise and will be removed in review.
+
+Bad:  `# loop over the entities`
+Good: `# deadline is checked between entities, not inside psutil calls -
+       a stuck native call cannot be interrupted in-process (SA-02)`
+
+## Docstrings
+
+- **Every module** starts with a docstring: one line of purpose, then the
+  rationale/constraints that shaped it, citing SPEC requirement IDs in
+  parentheses — e.g. `(EX-04)`, `(PM-06)`. The IDs are load-bearing: they let
+  a reader jump from code to the reasoning in SPEC.md/DESIGN.md.
+- **Every public class/function** gets a docstring stating behavior at the
+  contract level (inputs, outputs, error behavior, None semantics). Private
+  helpers need one only when their reason for existing is non-obvious.
+- **Every test** carries the requirement ID(s) it verifies in its docstring,
+  bracketed: `"""[EX-06] Three-valued semantics..."""` — the traceability
+  tooling (TS-01) depends on this.
+
+## Comments
+
+- Explain invariants the type system cannot express ("oldest first",
+  "one transaction per tick, PM-03").
+- Explain deliberate omissions ("per-process attribution deferred, NG-06").
+- Never narrate mechanics, never leave commented-out code, never write
+  comments addressed to a reviewer about the change itself.
+
+## Documentation deliverables (SPEC section 17)
+
+| Doc | Audience | Grows |
+| --- | --- | --- |
+| `docs/manual.md` (DO-04) | end users - install, concepts, daily use, tuning | one chapter per milestone; placeholders are marked |
+| `docs/definitions.md` (DO-01) | monitor authors, human or AI (also the MCP resource) | frozen with the language |
+| `docs/install.md` (DO-02) | operators | M6 |
+| `--help` text (DO-03) | CLI users | with each subcommand |
+| SPEC.md / DESIGN.md | maintainers | change-controlled, changelog required |
+
+When you land a user-visible feature, updating the manual chapter is part of
+the work package, not a follow-up.
+
+## Style
+
+Python >= 3.11, ruff (line length 100) is the linter and formatter authority.
+No direct `time.time`/`datetime.now`/`time.sleep` outside `clock.py` (TS-03).
+The `expr/` package imports stdlib only (EX-04). Layering rules: DESIGN.md
+section 1. All lint rules are enforced as tests - `uv run pytest tests -q`
+is the gate.