Audit phase 5f

.github/workflows/ci.yml

@@ -0,0 +1,148 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ./api
+        pip install pytest-cov
+
+    - name: Create required directories
+      run: mkdir -p api/storage api/logs
+
+    - name: Create admin API key file for tests
+      run: echo "test-ci-key" > api/src/.admin_api_key
+
+    - name: Run tests with coverage
+      run: |
+        cd api
+        python -m pytest --cov=src/zotify_api --cov-report=xml --cov-fail-under=85
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install ruff
+      run: python -m pip install ruff
+
+    - name: Run ruff
+      run: python -m ruff check .
+
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.22' # Updated to resolve linter incompatibility
+        cache: false # Disable caching as there are no dependencies
+
+    - name: Run golangci-lint
+      uses: golangci/golangci-lint-action@v4
+      with:
+        # Downgrade to a known stable version to avoid linter/toolchain bugs
+        version: v1.55.2
+        working-directory: snitch
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ./api
+
+    - name: Run mypy
+      run: |
+        cd api
+        python -m mypy --config-file mypy.ini src tests
+
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ./api
+
+    - name: Run bandit
+      run: |
+        cd api
+        python -m bandit -r . -c bandit.yml
+
+    - name: Run safety
+      run: |
+        pip install "safety<3.0.0"
+        python -m safety check --ignore=51167 --ignore=77740
+
+  doc-linter:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0 # Fetch all history for git diff to work
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Run documentation linter
+      run: python ${{ github.workspace }}/scripts/lint-docs.py

.gitignore

@@ -154,4 +154,19 @@ Zotify\ Music/
 Zotify\ Podcasts/
 
 # Testing
-debug.py
+debug.py
+
+# Ignore admin API key file
+.admin_api_key
+
+# Ignore snitch binary
+snitch/snitch
+snitch/snitch.exe
+snitch/bin/
+
+# Ignore spotify tokens file
+api/src/storage/spotify_tokens.json
+
+# Ignore API storage directory and database files
+api/storage/
+api/*.db

.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+repos:
+  # 1. Code formatting & linting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.0.280
+    hooks:
+      - id: ruff
+        args: ["--fix"]  # fixes formatting and common style issues
+
+  # 2. Type checking
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.5.1
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+
+  # 3. Security checks
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.5
+    hooks:
+      - id: bandit
+        args: ["-r", "."]
+
+  - repo: https://github.com/returntocorp/semgrep
+    rev: v1.37.0
+    hooks:
+      - id: semgrep
+        args: ["--config=p/ci"]
+
+  # 4. Documentation linter (local)
+  - repo: local
+    hooks:
+      - id: doc-linter
+        name: Documentation Linter
+        entry: python scripts/lint-docs.py
+        language: python
+        types: [file, python]
+        pass_filenames: false
+        additional_dependencies: [pyyaml]
+
+  # 5. Optional: complexity checks (Radon/Xenon) as a local hook
+  - repo: local
+    hooks:
+      - id: complexity
+        name: Cyclomatic Complexity
+        entry: python scripts/check_complexity.py
+        language: python
+        types: [python]
+        pass_filenames: false

AGENTS.md

@@ -0,0 +1,93 @@
+# Agent Instructions & Automated Workflow System
+
+**Version:** 2.0
+**Status:** Active
+
+---
+
+## 0. Fundamental Rules
+
+This is a mandatory, non-optional rule that all agents must follow at all times.
+
+    Do not approve your own tasks or plans. Do not make un-asked for changes. Do not start tasks or plans without approval.
+
+---
+
+## 1. About This System
+
+### 1.1. Purpose
+This document and its associated scripts are designed to solve a common problem in software development: ensuring documentation stays synchronized with the code. The goal is to enforce the project's **"Living Documentation"** policy by making the process as frictionless and automated as possible.
+
+### 1.2. How It Works
+The system consists of three main components:
+1.  **This Document (`AGENTS.md`):** The central source of truth for the workflow. AI agents are programmed to read this file and follow its instructions.
+2.  **Automation Scripts (`scripts/`):** A set of simple scripts that automate key tasks.
+3.  **Configuration (`scripts/doc-lint-rules.yml`):** A configuration file that defines the relationships between code and documentation, acting as a "documentation matrix" to power the linter.
+
+### 1.3. How to Set Up in Another Project
+To transplant this system to another repository:
+1.  **Copy Files:** Copy this `AGENTS.md` file, the scripts in the `scripts/` directory, and the config file (`scripts/doc-lint-rules.yml`).
+2.  **Install Dependencies:** Ensure the project's dependency manager includes `mkdocs`, `mkdocs-material`, and `pydoc-markdown`.
+3.  **Customize:** Edit `scripts/doc-lint-rules.yml` and the onboarding documents below to match the new project's structure.
+
+---
+
+## 2. Agent Onboarding
+
+Before starting any new task, you **must** first read the following document to understand the project's context and procedures:
+- `project/ONBOARDING.md`
+
+---
+
+## 3. The Automated Workflow
+
+This workflow is designed to be followed for every task that involves code or documentation changes.
+
+### Step 1: Code and Document
+This is the primary development task. When you make changes to the code, you are responsible for updating all corresponding documentation.
+
+#### Project-Level Documentation
+To identify which documents are relevant for a given change, you **must** consult the `project/PROJECT_REGISTRY.md`. This file is the single source of truth for all high-level project documents.
+
+#### API Documentation
+The API documentation has its own master index. When creating new documentation for the API, you **must** register it in the following locations:
+1.  **`api/docs/MASTER_INDEX.md`**: The new documentation file must be added to this master list.
+2.  **`scripts/doc-lint-rules.yml`**: The new file must be added to the appropriate rule or mapping.
+3.  **`api/docs/reference/CODE_QUALITY_INDEX.md`**: A new row must be added for the documentation file with an initial quality score of 'X'.
+
+### Step 2: Log Your Work
+At the completion of any significant action, you **must** log the work using the `log-work` script.
+
+*   **Command:** `python scripts/log-work.py --activity "..." --session "..." --state "..." --files ...`
+*   **Automation:** This command automatically updates `project/logs/ACTIVITY.md`, `project/logs/CURRENT_STATE.md` and `project/logs/SESSION_LOG.md`.
+
+### Step 3: Maintain the Quality Index
+To ensure a high standard of quality, all new source code and documentation files must be registered in the quality index. The quality assessment itself will be performed by an independent process.
+
+1.  **Add New Files to Index:** When you create a new source file (`.py`, `.go' or `.js`) or a new documentation file (`.md`), you **must** add a corresponding entry to the appropriate `CODE_QUALITY_INDEX.md` file.
+2.  **Set Initial Score:** The initial "Documentation Score" and "Code Score" for any new file must be set to **'X'**, signifying that the quality is "Unknown" and pending review.
+
+### Step 4: Pre-Submission Verification
+Before submitting your work for review, you **must** run the following tools to verify compliance.
+
+1.  **Run Tests:**
+    *   **Command:** `bash scripts/run_lint.sh.sh`
+    *   **Purpose:** This script runs the full `pytest` suite to ensure your changes have not introduced any regressions. You must resolve any test failures.
+
+2.  **Run Documentation Linter:**
+    *   **Command:** `python scripts/lint-docs.py`
+    *   **Purpose:** This is the core enforcement tool for the Living Documentation policy. It uses the "documentation matrix" defined in `scripts/doc-lint-rules.yml` to check that all required documentation has been updated. You must resolve any errors it reports.
+
+3.  **Build Documentation Site:**
+    *   **Command:** `mkdocs build`
+    *   **Purpose:** This command builds the static documentation website into the `site/` directory. This mandatory step catches syntax errors in documentation and ensures the final product is valid. The site can be previewed at http://<server_ip>:8008 by running `mkdocs serve`. 
+
+---
+
+## 4. Key Policy Documents (Reference)
+
+This automated workflow is designed to fulfill the rules defined in the following core documents. Refer to them if you need more context on the *why* behind the rules.
+
+*   `project/PID.md`
+*   `project/HIGH_LEVEL_DESIGN.md`
+*   `project/TASK_CHECKLIST.md`