Audit completed

.github/workflows/ci.yml

@@ -0,0 +1,151 @@
+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: Install linter dependencies
+      run: python -m pip install PyYAML
+
+    - name: Run documentation linter
+      run: python3 ${{ github.workspace }}/scripts/linter.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,95 @@
+# 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: Register New Files
+The first step of any task is to understand where to register new files. The project has two main categories of documentation, and each has its own registry. Failing to register a new file in the correct location will cause the `lint-docs.py` verification script to fail.
+
+*   **Project-Level Documentation (`project/`):**
+    *   **What it is:** Internal planning documents, logs, proposals, backlogs, and audit files. Anything that lives in the `project/` directory.
+    *   **Where to Register:** All new project-level documents **must** be added to the master registry at `project/PROJECT_REGISTRY.md`.
+
+*   **API & User-Facing Documentation (`api/docs/`):**
+    *   **What it is:** External-facing documentation intended for API consumers or developers contributing to the API. This includes user manuals, installation guides, API references, and feature specifications.
+    *   **Where to Register:** New API documents **must** be registered in two places:
+        1.  `api/docs/MASTER_INDEX.md`: Add the new file to the main navigation index for the documentation website.
+        2.  `api/docs/reference/CODE_QUALITY_INDEX.md`: Add a new row for the file with an initial "Documentation Score" of 'X'.
+
+### Step 2: Code and Document
+This is the primary development task. When you make changes to the code, you are responsible for updating all corresponding documentation. Use the registries mentioned in Step 1 to identify relevant documents.
+
+### Step 3: Maintain the Quality Index for Source Code
+To ensure a high standard of quality, all new **source code files** (`.py`, `.go`, `.js`) must be registered in the appropriate 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, you **must** add a corresponding entry to the appropriate `CODE_QUALITY_INDEX.md` file (e.g., `api/docs/reference/CODE_QUALITY_INDEX.md` for API source files).
+2.  **Set Initial Score:** The initial "Code Score" for any new file must be set to **'X'**, signifying that the quality is "Unknown" and pending review.
+
+### Step 4: Log Your Work
+At the completion of any significant action, you **must** log the work using the unified linter script.
+
+*   **Command:** `python scripts/linter.py --log --summary "..." --objective "..." --outcome "..." --files ...`
+*   **Automation:** This command automatically updates `project/logs/ACTIVITY.md`, `project/logs/CURRENT_STATE.md` and `project/logs/SESSION_LOG.md`.
+
+> **Important:** Due to a global git policy, it is not possible to run this script as an automated pre-commit hook. Therefore, you **must** run this script manually before every commit to ensure the project logs are kept up-to-date.
+
+### Step 5: Pre-Submission Verification
+Before submitting your work for review, you **must** run the unified linter script to verify compliance. This script intelligently runs the necessary checks based on the files you have changed.
+
+*   **Command:** `python3 scripts/linter.py`
+*   **Purpose:** This script acts as a single entrypoint for all verification steps. It will:
+    1.  Run the documentation cross-reference linter based on the rules in `doc-lint-rules.yml`.
+    2.  Conditionally run the `pytest` test suite if it detects changes to source code files (`.py`, `.go`).
+    3.  Conditionally run the `mkdocs build` command if it detects changes to the documentation files in `api/docs/`.
+*   You must resolve any errors reported by the script before submitting.
+
+---
+
+## 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`
+*   `project/QA_GOVERNANCE.md`