konfetti-spider 1.2__tar.gz

konfetti_spider-1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Natzkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

konfetti_spider-1.2/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: konfetti-spider
+Version: 1.2
+Summary: POC-Framework zur Nachvollziehbarkeit von AI-Agent-Entscheidungen (Planungsbaum + Audit-Log).
+Author-email: David Natzkin <david.natzkin+spider@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/KonFetti11/spider
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == "mcp"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file
+
+# 🕷 Spider – AI Traceability Framework
+
+**POC-Framework zur Nachvollziehbarkeit von AI-Agent-Entscheidungen.**
+
+Spider zwingt Coding-Agents dazu, jeden Entscheidungsschritt als Knoten in einem
+persistenten Baumgraphen zu dokumentieren. Das Ergebnis ist ein vollständig
+nachvollziehbarer Planungsbaum, der für menschliche Reviewer transparent und
+interaktiv visualisierbar ist.
+
+---
+
+## Kernkonzept
+
+```
+Root-Knoten (reifegrad = 0.0 → 1.0)
+├── Planungsbereich A
+│   ├── ✓ Option 1 (akzeptiert)  → reifegrad = 1.0
+│   └── ✗ Option 2 (abgelehnt)  → reifegrad = 1.0
+└── Planungsbereich B
+    └── ? Option X (offen)       → reifegrad = 0.0
+```
+
+- **reifegrad = 1.0** am Root = Alle Entscheidungen getroffen → Planungsphase abgeschlossen
+- Jede Entscheidung (accept/reject) wird mit Begründung dokumentiert
+- Alle Änderungen erzeugen automatisch einen unveränderlichen **Audit-Log (Actions)**
+- Optional lässt sich an jedem Knoten die zugehörige Aufgabenstellung verlinken
+  (`taskRef` – Pfad/Link) oder direkt einbetten (`taskMarkdown` – Markdown-Inhalt)
+
+---
+
+## Schnellstart
+
+```bash
+# 1. Installieren (editable, inkl. optionalem MCP-Server)
+pip install -e ".[mcp]"
+
+# 2. Demo-Daten laden (in ./.spider/spider.db)
+python -m spider.db.seed
+
+# 3. Visualisierung starten (wählt freien Port, gibt die URL aus)
+python -m spider.launch
+
+# Optional: HTTP-API – nur für Netzwerk-/Remote-Zugriff (Port 8765, Docs unter /docs)
+python -m spider.server.main
+```
+
+> Für die Einbindung in **eigene** Projekte nicht den obigen Demo-Flow nutzen, sondern
+> `spider-init` – siehe [Einbindung in ein neues Projekt](#einbindung-in-ein-neues-projekt).
+
+---
+
+## Projektstruktur
+
+```
+spider/
+├── db/
+│   ├── models.py      # Dataclasses: Node, Action
+│   ├── database.py    # SQLite CRUD + reifegrad/confidence-Berechnung
+│   └── seed.py        # Demo-Testdaten
+├── server/
+│   ├── schemas.py     # Pydantic Request/Response-Modelle
+│   ├── api.py         # FastAPI REST-Endpunkte
+│   └── main.py        # Uvicorn-Einstiegspunkt (Port 8765)
+├── tools/
+│   ├── agent_tools.py # SpiderTools-Klasse für AI-Agents
+│   └── tool_schemas.py# JSON-Schemas für function-calling
+├── visualization/
+│   ├── serve.py       # Visualisierungsserver (Port 8766)
+│   └── tree.html      # Interaktiver D3.js-Baum
+├── templates/
+│   └── AGENTS.md      # Nutzungsvorlage für Zielprojekte
+├── data/
+│   └── spider.db      # SQLite-Datenbank (auto-erstellt)
+├── AGENTS.md          # Bauanleitung für Coding-Agents
+└── .env.example       # Konfigurationsvorlage
+```
+
+---
+
+## API-Endpunkte
+
+| Method | Endpunkt                  | Beschreibung                         |
+|--------|---------------------------|--------------------------------------|
+| GET    | `/nodes`                  | Alle Nodes (flach)                   |
+| GET    | `/nodes/{id}`             | Einzelner Node                       |
+| GET    | `/nodes/{id}/children`    | Direktkinder eines Nodes             |
+| POST   | `/nodes`                  | Neuen Node erstellen                 |
+| PATCH  | `/nodes/{id}`             | Node aktualisieren                   |
+| POST   | `/nodes/{id}/reject`      | Node ablehnen                        |
+| POST   | `/nodes/{id}/accept`      | Node akzeptieren                     |
+| GET    | `/tree`                   | Kompletter Baum (flach)              |
+| GET    | `/tree/nested`            | Baum verschachtelt                   |
+| GET    | `/tree/stats`             | Fortschrittsstatistiken              |
+| GET    | `/actions`                | Alle Audit-Log-Einträge              |
+| POST   | `/actions`                | Manuellen Audit-Eintrag erstellen    |
+
+---
+
+## Einbindung in ein neues Projekt
+
+### Schritt 1: Spider einmalig installieren
+```bash
+# Lokal (Entwicklung), aus dem Spider-Repo – inkl. MCP-Server:
+pip install -e ".[mcp]"
+
+# Später, nach GitHub-Publish:
+pip install "spider[mcp] @ git+https://github.com/<user>/spider.git"
+```
+Installiere in das Python, das deine Projekte nutzen (System-Python, oder das venv des Projekts).
+`[mcp]` ist optional – nur für den nativen MCP-Server nötig.
+
+### Schritt 2: Projekt initialisieren
+Ein Befehl macht ein beliebiges Projekt Spider-fähig:
+```bash
+spider-init /pfad/zum/projekt        # oder: python -m spider.init /pfad/zum/projekt
+```
+Das legt im Zielprojekt an:
+- `.spider/.env` – zentrale Konfiguration (`SPIDER_DB_PATH`, optional `SPIDER_BASE_URL`),
+- `.spider/spider.db` – die projekteigene Datenbank (lazy, isoliert pro Projekt),
+- `.spider/work_agent.md` – System-Prompt für read-only Subagents,
+- `AGENTS.md` – Agent-Anweisungen (neu) bzw. ein angehängter, markierter Block,
+- `spider_tools.py` – Tool-Shim (exportiert `spider` und read-only `spider_ro`),
+- `.mcp.json` – MCP-Server-Konfiguration für Claude Code & Co.,
+- `.claude/commands/spider-plan.md` + `spider-execute.md` – Slash-Commands,
+- `spider-viz.ps1` / `spider-viz.sh` – Start-Helper für die Visualisierung.
+
+### Schritt 3: Tools nutzen
+
+**a) Native MCP-Tools (empfohlen, z.B. Claude Code):** Beim Öffnen des Projekts findet der Client
+`.mcp.json` und startet `python -m spider.mcp_server` (Direkt-DB, kein Server). Verfügbare Tools:
+`spider_create_node`, `spider_get_tree`, `spider_get_tree_stats`, `spider_accept_node`,
+`spider_reject_node`, `spider_update_node`, `spider_add_action`, `spider_get_node`,
+`spider_get_children`, `spider_get_actions`. (Projekt-MCP-Server einmalig bestätigen.)
+
+**b) Per Python (kein Server nötig):**
+```python
+from spider_tools import spider       # voller Zugriff
+spider.get_tree_stats()
+from spider_tools import spider_ro     # read-only (für Subagents; Schreib-Methoden werfen)
+```
+
+**Netzwerk-/Remote-Zugriff** (z.B. Claude Code vom Handy): in `.spider/.env`
+`SPIDER_BASE_URL=http://<host>:8765` setzen und `python -m spider.server.main` starten –
+Shim/MCP nutzen dann HTTP, gleiche DB darunter, keine Migration.
+
+### Schritt 4: Zwei-Phasen-Workflow (Slash-Commands)
+- **`/spider-plan`** – Planungsphase: baut den Entscheidungsbaum auf, bis `root.reifegrad == 1.0`.
+- **`/spider-execute`** – Ausführungsphase: Orchestrator mit exklusivem Schreibzugriff startet
+  read-only Subagents (siehe `.spider/work_agent.md`), die Ergebnisse zurückmelden; nur der
+  Orchestrator schreibt sie nach Spider.
+
+### Schritt 5: Visualisierung öffnen
+```bash
+./spider-viz.ps1        # Windows   (bzw.  ./spider-viz.sh  unter Linux/macOS)
+# wählt automatisch einen freien Port und gibt die URL aus
+```
+
+### Bestehendes Projekt upgraden
+Nach einem Spider-Update die generierten Dateien im Projekt aktualisieren – Nutzerdaten
+(`.spider/.env`, `.spider/spider.db`) bleiben unangetastet:
+```bash
+spider-init /pfad/zum/projekt --force
+```
+
+---
+
+## reifegrad-Logik
+
+| Knotentyp                          | reifegrad |
+|------------------------------------|-----------|
+| Blattknoten, akzeptiert            | 1.0       |
+| Blattknoten, abgelehnt             | 1.0       |
+| Blattknoten, offen                 | 0.0       |
+| Interner Knoten                    | Ø(Children)|
+| Root (Ziel)                        | **1.0**   |
+
+---
+
+## Konfiguration (`.spider/.env`)
+
+Pro Projekt liegt die Konfiguration in `.spider/.env` (von `spider-init` erzeugt, autoritativ
+geladen via `spider/config.py`). Ein relativer `SPIDER_DB_PATH` wird relativ zur Projektwurzel
+aufgelöst.
+
+```env
+SPIDER_DB_PATH=.spider/spider.db
+# Optionaler Netzwerk-/Remote-Zugriff (Shim/MCP schalten dann auf HTTP):
+# SPIDER_BASE_URL=http://127.0.0.1:8765
+# Optionale feste Ports (sonst wählt der Viz-Start einen freien Port):
+# SPIDER_HOST=127.0.0.1
+# SPIDER_PORT=8765
+# SPIDER_VIZ_HOST=127.0.0.1
+# SPIDER_VIZ_PORT=8766
+```
+
+---
+
+## POC-Status & Nächste Schritte
+
+Dieser POC validiert das Grundkonzept. Bei Erfolg geplant:
+
+- [ ] Rückwirkende Integration für laufende Projekte
+- [ ] API-Key-Authentifizierung für Multi-Agent-Setups
+- [ ] PostgreSQL-Migration für Produktion
+- [ ] PDF/Markdown-Export des Entscheidungsbaums
+- [ ] Webhook-Benachrichtigungen bei Reifegrad-Schwellwerten
+- [ ] pip-Package-Veröffentlichung
+

konfetti_spider-1.2/README.md

@@ -0,0 +1,208 @@
+# 🕷 Spider – AI Traceability Framework
+
+**POC-Framework zur Nachvollziehbarkeit von AI-Agent-Entscheidungen.**
+
+Spider zwingt Coding-Agents dazu, jeden Entscheidungsschritt als Knoten in einem
+persistenten Baumgraphen zu dokumentieren. Das Ergebnis ist ein vollständig
+nachvollziehbarer Planungsbaum, der für menschliche Reviewer transparent und
+interaktiv visualisierbar ist.
+
+---
+
+## Kernkonzept
+
+```
+Root-Knoten (reifegrad = 0.0 → 1.0)
+├── Planungsbereich A
+│   ├── ✓ Option 1 (akzeptiert)  → reifegrad = 1.0
+│   └── ✗ Option 2 (abgelehnt)  → reifegrad = 1.0
+└── Planungsbereich B
+    └── ? Option X (offen)       → reifegrad = 0.0
+```
+
+- **reifegrad = 1.0** am Root = Alle Entscheidungen getroffen → Planungsphase abgeschlossen
+- Jede Entscheidung (accept/reject) wird mit Begründung dokumentiert
+- Alle Änderungen erzeugen automatisch einen unveränderlichen **Audit-Log (Actions)**
+- Optional lässt sich an jedem Knoten die zugehörige Aufgabenstellung verlinken
+  (`taskRef` – Pfad/Link) oder direkt einbetten (`taskMarkdown` – Markdown-Inhalt)
+
+---
+
+## Schnellstart
+
+```bash
+# 1. Installieren (editable, inkl. optionalem MCP-Server)
+pip install -e ".[mcp]"
+
+# 2. Demo-Daten laden (in ./.spider/spider.db)
+python -m spider.db.seed
+
+# 3. Visualisierung starten (wählt freien Port, gibt die URL aus)
+python -m spider.launch
+
+# Optional: HTTP-API – nur für Netzwerk-/Remote-Zugriff (Port 8765, Docs unter /docs)
+python -m spider.server.main
+```
+
+> Für die Einbindung in **eigene** Projekte nicht den obigen Demo-Flow nutzen, sondern
+> `spider-init` – siehe [Einbindung in ein neues Projekt](#einbindung-in-ein-neues-projekt).
+
+---
+
+## Projektstruktur
+
+```
+spider/
+├── db/
+│   ├── models.py      # Dataclasses: Node, Action
+│   ├── database.py    # SQLite CRUD + reifegrad/confidence-Berechnung
+│   └── seed.py        # Demo-Testdaten
+├── server/
+│   ├── schemas.py     # Pydantic Request/Response-Modelle
+│   ├── api.py         # FastAPI REST-Endpunkte
+│   └── main.py        # Uvicorn-Einstiegspunkt (Port 8765)
+├── tools/
+│   ├── agent_tools.py # SpiderTools-Klasse für AI-Agents
+│   └── tool_schemas.py# JSON-Schemas für function-calling
+├── visualization/
+│   ├── serve.py       # Visualisierungsserver (Port 8766)
+│   └── tree.html      # Interaktiver D3.js-Baum
+├── templates/
+│   └── AGENTS.md      # Nutzungsvorlage für Zielprojekte
+├── data/
+│   └── spider.db      # SQLite-Datenbank (auto-erstellt)
+├── AGENTS.md          # Bauanleitung für Coding-Agents
+└── .env.example       # Konfigurationsvorlage
+```
+
+---
+
+## API-Endpunkte
+
+| Method | Endpunkt                  | Beschreibung                         |
+|--------|---------------------------|--------------------------------------|
+| GET    | `/nodes`                  | Alle Nodes (flach)                   |
+| GET    | `/nodes/{id}`             | Einzelner Node                       |
+| GET    | `/nodes/{id}/children`    | Direktkinder eines Nodes             |
+| POST   | `/nodes`                  | Neuen Node erstellen                 |
+| PATCH  | `/nodes/{id}`             | Node aktualisieren                   |
+| POST   | `/nodes/{id}/reject`      | Node ablehnen                        |
+| POST   | `/nodes/{id}/accept`      | Node akzeptieren                     |
+| GET    | `/tree`                   | Kompletter Baum (flach)              |
+| GET    | `/tree/nested`            | Baum verschachtelt                   |
+| GET    | `/tree/stats`             | Fortschrittsstatistiken              |
+| GET    | `/actions`                | Alle Audit-Log-Einträge              |
+| POST   | `/actions`                | Manuellen Audit-Eintrag erstellen    |
+
+---
+
+## Einbindung in ein neues Projekt
+
+### Schritt 1: Spider einmalig installieren
+```bash
+# Lokal (Entwicklung), aus dem Spider-Repo – inkl. MCP-Server:
+pip install -e ".[mcp]"
+
+# Später, nach GitHub-Publish:
+pip install "spider[mcp] @ git+https://github.com/<user>/spider.git"
+```
+Installiere in das Python, das deine Projekte nutzen (System-Python, oder das venv des Projekts).
+`[mcp]` ist optional – nur für den nativen MCP-Server nötig.
+
+### Schritt 2: Projekt initialisieren
+Ein Befehl macht ein beliebiges Projekt Spider-fähig:
+```bash
+spider-init /pfad/zum/projekt        # oder: python -m spider.init /pfad/zum/projekt
+```
+Das legt im Zielprojekt an:
+- `.spider/.env` – zentrale Konfiguration (`SPIDER_DB_PATH`, optional `SPIDER_BASE_URL`),
+- `.spider/spider.db` – die projekteigene Datenbank (lazy, isoliert pro Projekt),
+- `.spider/work_agent.md` – System-Prompt für read-only Subagents,
+- `AGENTS.md` – Agent-Anweisungen (neu) bzw. ein angehängter, markierter Block,
+- `spider_tools.py` – Tool-Shim (exportiert `spider` und read-only `spider_ro`),
+- `.mcp.json` – MCP-Server-Konfiguration für Claude Code & Co.,
+- `.claude/commands/spider-plan.md` + `spider-execute.md` – Slash-Commands,
+- `spider-viz.ps1` / `spider-viz.sh` – Start-Helper für die Visualisierung.
+
+### Schritt 3: Tools nutzen
+
+**a) Native MCP-Tools (empfohlen, z.B. Claude Code):** Beim Öffnen des Projekts findet der Client
+`.mcp.json` und startet `python -m spider.mcp_server` (Direkt-DB, kein Server). Verfügbare Tools:
+`spider_create_node`, `spider_get_tree`, `spider_get_tree_stats`, `spider_accept_node`,
+`spider_reject_node`, `spider_update_node`, `spider_add_action`, `spider_get_node`,
+`spider_get_children`, `spider_get_actions`. (Projekt-MCP-Server einmalig bestätigen.)
+
+**b) Per Python (kein Server nötig):**
+```python
+from spider_tools import spider       # voller Zugriff
+spider.get_tree_stats()
+from spider_tools import spider_ro     # read-only (für Subagents; Schreib-Methoden werfen)
+```
+
+**Netzwerk-/Remote-Zugriff** (z.B. Claude Code vom Handy): in `.spider/.env`
+`SPIDER_BASE_URL=http://<host>:8765` setzen und `python -m spider.server.main` starten –
+Shim/MCP nutzen dann HTTP, gleiche DB darunter, keine Migration.
+
+### Schritt 4: Zwei-Phasen-Workflow (Slash-Commands)
+- **`/spider-plan`** – Planungsphase: baut den Entscheidungsbaum auf, bis `root.reifegrad == 1.0`.
+- **`/spider-execute`** – Ausführungsphase: Orchestrator mit exklusivem Schreibzugriff startet
+  read-only Subagents (siehe `.spider/work_agent.md`), die Ergebnisse zurückmelden; nur der
+  Orchestrator schreibt sie nach Spider.
+
+### Schritt 5: Visualisierung öffnen
+```bash
+./spider-viz.ps1        # Windows   (bzw.  ./spider-viz.sh  unter Linux/macOS)
+# wählt automatisch einen freien Port und gibt die URL aus
+```
+
+### Bestehendes Projekt upgraden
+Nach einem Spider-Update die generierten Dateien im Projekt aktualisieren – Nutzerdaten
+(`.spider/.env`, `.spider/spider.db`) bleiben unangetastet:
+```bash
+spider-init /pfad/zum/projekt --force
+```
+
+---
+
+## reifegrad-Logik
+
+| Knotentyp                          | reifegrad |
+|------------------------------------|-----------|
+| Blattknoten, akzeptiert            | 1.0       |
+| Blattknoten, abgelehnt             | 1.0       |
+| Blattknoten, offen                 | 0.0       |
+| Interner Knoten                    | Ø(Children)|
+| Root (Ziel)                        | **1.0**   |
+
+---
+
+## Konfiguration (`.spider/.env`)
+
+Pro Projekt liegt die Konfiguration in `.spider/.env` (von `spider-init` erzeugt, autoritativ
+geladen via `spider/config.py`). Ein relativer `SPIDER_DB_PATH` wird relativ zur Projektwurzel
+aufgelöst.
+
+```env
+SPIDER_DB_PATH=.spider/spider.db
+# Optionaler Netzwerk-/Remote-Zugriff (Shim/MCP schalten dann auf HTTP):
+# SPIDER_BASE_URL=http://127.0.0.1:8765
+# Optionale feste Ports (sonst wählt der Viz-Start einen freien Port):
+# SPIDER_HOST=127.0.0.1
+# SPIDER_PORT=8765
+# SPIDER_VIZ_HOST=127.0.0.1
+# SPIDER_VIZ_PORT=8766
+```
+
+---
+
+## POC-Status & Nächste Schritte
+
+Dieser POC validiert das Grundkonzept. Bei Erfolg geplant:
+
+- [ ] Rückwirkende Integration für laufende Projekte
+- [ ] API-Key-Authentifizierung für Multi-Agent-Setups
+- [ ] PostgreSQL-Migration für Produktion
+- [ ] PDF/Markdown-Export des Entscheidungsbaums
+- [ ] Webhook-Benachrichtigungen bei Reifegrad-Schwellwerten
+- [ ] pip-Package-Veröffentlichung
+

konfetti_spider-1.2/__init__.py

@@ -0,0 +1,2 @@
+"""Spider – AI Traceability Framework"""
+

konfetti_spider-1.2/config.py

@@ -0,0 +1,94 @@
+"""
+Spider Framework – zentrale Konfiguration / .env-Laden.
+
+Sorgt dafür, dass alle SPIDER_*-Einstellungen (insbesondere SPIDER_DB_PATH)
+**konsistent aus der Projekt-.env** kommen. Jeder Einstiegspunkt (Tool-Shim,
+`launch.py`, `server.main`, `db.seed`, `db.database.get_db`) ruft `load_project_env()`
+auf, bevor er Konfiguration liest.
+
+Konventionen:
+  - Pro Projekt liegt die Konfiguration in `<projekt>/.spider/.env`
+    (isoliert von einer evtl. vorhandenen App-eigenen `.env` im Projektwurzelordner).
+  - Gesucht wird ab einem Startverzeichnis aufwärts: zuerst `.spider/.env`,
+    ersatzweise `.env` im selben Verzeichnis.
+  - Die `.env` ist **autoritativ** (`override=True`): ihre Werte gewinnen gegenüber
+    bereits gesetzten Prozess-Umgebungsvariablen. Damit kann keine global gesetzte
+    SPIDER_DB_PATH-Variable ein Projekt mehr „kapern". Schlüssel, die *nicht* in der
+    `.env` stehen (z.B. ein per Shell gesetztes SPIDER_BASE_URL), bleiben unberührt.
+  - Ein relativer SPIDER_DB_PATH wird relativ zur **Projektwurzel** (dem Verzeichnis,
+    das `.spider/` enthält) zu einem absoluten Pfad aufgelöst.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+_loaded = False
+
+
+def find_project_env(start: Optional[Path] = None) -> Optional[Path]:
+    """Sucht ab `start` (default: CWD) aufwärts die nächste Projekt-.env."""
+    base = (Path(start) if start else Path.cwd()).resolve()
+    for d in [base, *base.parents]:
+        candidate = d / ".spider" / ".env"
+        if candidate.is_file():
+            return candidate
+        candidate = d / ".env"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _parse_env(text: str) -> dict[str, str]:
+    """Minimaler .env-Parser (KEY=VALUE, # Kommentare, optionale Quotes)."""
+    values: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):]
+        if "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        key = key.strip()
+        val = val.strip().strip('"').strip("'")
+        if key:
+            values[key] = val
+    return values
+
+
+def _project_root(env_path: Path) -> Path:
+    """Projektwurzel = Verzeichnis, das `.spider/` enthält (bzw. .env-Verzeichnis)."""
+    if env_path.parent.name == ".spider":
+        return env_path.parent.parent
+    return env_path.parent
+
+
+def load_project_env(start: Optional[Path] = None, override: bool = True, force: bool = False) -> Optional[Path]:
+    """
+    Lädt die Projekt-.env in os.environ. Idempotent (nur einmal pro Prozess, außer force=True).
+    Gibt den geladenen .env-Pfad zurück (oder None, wenn keine gefunden wurde).
+    """
+    global _loaded
+    if _loaded and not force:
+        return None
+    _loaded = True
+
+    env_path = find_project_env(start)
+    if env_path is None:
+        return None
+
+    values = _parse_env(env_path.read_text(encoding="utf-8"))
+    for key, val in values.items():
+        if override or key not in os.environ:
+            os.environ[key] = val
+
+    # Relativen SPIDER_DB_PATH relativ zur Projektwurzel absolut machen (portabel).
+    db_path = os.environ.get("SPIDER_DB_PATH")
+    if db_path and not Path(db_path).is_absolute():
+        os.environ["SPIDER_DB_PATH"] = str((_project_root(env_path) / db_path).resolve())
+
+    return env_path

konfetti_spider-1.2/db/__init__.py

@@ -0,0 +1,2 @@
+"""Spider DB package"""
+