ZANVEX
Git
D L

Dokumentation / stackyard

Stackyard – Handbuch

Stackyard ist ein lokales Dev-Control-Center für viele Softwareprojekte. Es scannt konfigurierte Projektordner und bündelt Projektmetadaten, Git-Zustände, TODOs, Toolchains, Dienste, Ports und sichere Aktionen in einer lokalen WebUI.

Download

Auf der Projektseite stehen ZIP-Pakete für folgende Plattformen bereit:

Nach dem Entpacken liegen die Binary, config.yaml, README.md und ein leerer Ordner projects/ gemeinsam in einem Verzeichnis. Unter Linux und macOS muss die Binary je nach verwendetem ZIP-Programm einmalig ausführbar gemacht werden:

chmod +x stackyard

Start

Windows:

.\stackyard.exe serve

Linux und macOS:

./stackyard serve

Danach ist die Oberfläche standardmäßig unter http://127.0.0.1:8799 erreichbar. Ohne expliziten --config-Parameter sucht Stackyard die config.yaml direkt neben der ausführbaren Datei.

Konfiguration

Ein minimales Beispiel:

server:
  listen: "127.0.0.1:8799"

database:
  path: "./stackyard.db"

monitoring:
  refresh_seconds: 10

roots:
  - name: "Projects"
    path: "./projects"

scanner:
  max_depth: 2
  ignore_dirs:
    - node_modules
    - .venv
    - vendor
    - target
    - dist
    - build
    - .git

Relative Pfade werden relativ zum Verzeichnis der Konfigurationsdatei aufgelöst. Die Projektinformationen und der Git-Cache werden in SQLite gespeichert. Projektdateien selbst werden nicht in die Datenbank kopiert.

Projekte und Projektmappen

Ein Rescan erkennt Projekte anhand typischer Marker wie .git, go.mod, package.json, pyproject.toml, Cargo.toml, Compose-Dateien und README. Über Projektmappen können zusammengehörige Projekte als Workspace organisiert werden. Eine Projektmappe verschiebt oder verändert keine Verzeichnisse.

Die Projektseite zeigt unter anderem:

Sicher deklarierte Aktionen

Optionale Aktionen und Dienste werden pro Projekt in .stackyard/project.yaml beschrieben:

description: Lokaler Go-Dienst
provider: go-service

services:
  - name: WebUI
    port: 8080
    url: http://127.0.0.1:8080
    health_path: /health

actions:
  - name: Tests
    kind: go-test
  - name: Build
    kind: go-build
  - name: Entwicklungsserver
    kind: go-run

Unterstützte Aktionstypen:

| Typ | Fester Befehl | Verhalten | | --- | --- | --- | | go-test | go test ./... | einmaliger, zeitbegrenzter Job | | go-build | go build ./... | einmaliger, zeitbegrenzter Job | | go-run | go run . | verwalteter Dienst mit Start, Stop und Live-Log |

Freie Shell-Befehle, zusätzliche Argumente und Befehle aus Webformularen sind nicht erlaubt. Logs verwalteter Dienste bleiben im Arbeitsspeicher und sind auf die letzten 128 KiB begrenzt.

Git

Stackyard führt ausschließlich fest definierte Git-Aktionen aus:

Destruktive Befehle wie reset --hard, clean -fd oder Force-Push gehören nicht zum Funktionsumfang.

Health-Monitoring

Konfigurierte Dienste werden über ihren lokalen TCP-Port geprüft. Für lokale HTTP-Adressen kann zusätzlich ein Health-Pfad abgefragt werden. HTTP-Prüfungen sind auf Loopback-Ziele wie localhost und 127.0.0.1 beschränkt.

Aus Quellcode starten

Voraussetzung ist Go 1.24 oder eine passende mise-Toolchain:

mise exec -- go test ./...
mise exec -- go run ./cmd/stackyard serve --config ./app/example.config.yaml

Release-ZIPs lassen sich unter Windows beziehungsweise mit PowerShell 7 bauen:

.\build.ps1 -Version 0.1.0

Fehlerbehebung

Projektpfad nicht erreichbar

Netzlaufwerk oder Freigabe prüfen und anschließend einen neuen Projektscan starten. Stackyard zeigt einen nicht erreichbaren Pfad als Warnung an, ohne dass die WebUI dadurch ausfällt.

Git meldet „dubious ownership“

Stackyard setzt safe.directory ausschließlich für den jeweiligen internen Git-Aufruf. Eine globale Änderung der Git-Konfiguration ist nicht notwendig.

Git-Index beschädigt

Ein beschädigter .git/index ist ein Problem des betroffenen Repositorys. Stackyard überspringt dieses Repository und protokolliert die eigentliche Git-Fehlermeldung, statt den gesamten Scan abzubrechen.

Editor oder Terminal startet nicht

Prüfen, ob der konfigurierte Launcher im PATH liegt oder in config.yaml als vollständiger Pfad eingetragen ist.