feat: implement Phase A foundation and Phase B Postgres walking skeleton (#1)

Author: nixrajput

.claude/settings.json

@@ -36,14 +36,14 @@
     "deny": [
       "Read(./.env)",
       "Read(./.env.*)",
-      "Read(./secrets/**)",
+      "Read(/secrets/**)",
       "Read(./config/credentials.json)",
       "Read(./**/*.key)",
       "Read(./**/*.pem)",
       "Read(./**/*.crt)",
       "Write(./.env)",
       "Write(./.env.*)",
-      "Write(./secrets/**)",
+      "Write(/secrets/**)",
       "Write(./config/credentials.json)",
       "Write(./**/*.key)",
       "Write(./**/*.pem)",

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          cache: true
+      - uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.12.2
+
+  test:
+    name: Test (${{ matrix.os }})
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          cache: true
+      - name: go vet
+        run: go vet ./...
+      - name: go test
+        run: go test ./...

.golangci.yml

@@ -0,0 +1,67 @@
+version: "2"
+
+run:
+  timeout: 5m
+
+linters:
+  default: none
+  enable:
+    - errcheck
+    - govet
+    - ineffassign
+    - misspell
+    - staticcheck
+    - unused
+    - depguard
+  # Note: revive is intentionally NOT enabled in Phase A. Its `exported`
+  # rule would require doc comments on every exported symbol, which is
+  # bikeshedding at scaffold stage. Reconsider in a later phase.
+  settings:
+    depguard:
+      rules:
+        cli-may-not-import-domain:
+          list-mode: lax
+          files:
+            - "**/internal/cli/**"
+            - "!**/_test.go"
+          deny:
+            - pkg: "github.com/nixrajput/siphon/internal/driver"
+              desc: "CLI must go through internal/app, not Driver directly"
+        tui-may-not-import-cli:
+          list-mode: lax
+          files:
+            - "**/internal/tui/**"
+            - "!**/_test.go"
+          deny:
+            - pkg: "github.com/nixrajput/siphon/internal/cli"
+              desc: "TUI and CLI are siblings and may not depend on each other"
+        cli-may-not-import-tui-except-root:
+          list-mode: lax
+          files:
+            - "**/internal/cli/**"
+            - "!**/internal/cli/root.go"
+            - "!**/_test.go"
+          deny:
+            - pkg: "github.com/nixrajput/siphon/internal/tui"
+              desc: "Only the root command may launch the TUI"
+        driver-may-not-import-presentation:
+          list-mode: lax
+          files:
+            - "**/internal/driver/**"
+            - "!**/_test.go"
+          deny:
+            - pkg: "github.com/nixrajput/siphon/internal/cli"
+              desc: "Drivers must not depend on presentation"
+            - pkg: "github.com/nixrajput/siphon/internal/tui"
+              desc: "Drivers must not depend on presentation"
+            - pkg: "github.com/nixrajput/siphon/internal/app"
+              desc: "Drivers must not depend on Application — dependency flows down"
+  exclusions:
+    rules:
+      - path: _test\.go
+        linters:
+          - errcheck
+
+formatters:
+  enable:
+    - gofmt

Makefile

@@ -0,0 +1,37 @@
+SHELL := /usr/bin/env bash
+.DEFAULT_GOAL := help
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| sort \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
+
+lint: ## Run golangci-lint
+	golangci-lint run
+
+test: ## Run unit tests
+	go test ./...
+
+test-verbose: ## Run unit tests verbosely
+	go test -v ./...
+
+test-integration: ## Run integration tests (build tag: integration)
+	go test -tags=integration ./...
+
+build: ## Build the siphon binary into ./bin
+	@mkdir -p bin
+	go build -ldflags "-s -w -X github.com/nixrajput/siphon/internal/cli.Version=$$(git describe --tags --always --dirty 2>/dev/null || echo dev)" -o bin/siphon ./cmd/siphon
+
+run: ## Run siphon from source (bare invocation -> TUI)
+	go run ./cmd/siphon
+
+install: ## Install siphon to GOBIN
+	go install ./cmd/siphon
+
+tidy: ## Run go mod tidy
+	go mod tidy
+
+clean: ## Remove build artifacts
+	rm -rf bin/ dist/ coverage.out coverage.html
+
+.PHONY: help lint test test-verbose test-integration build run install tidy clean

cmd/siphon/main.go

@@ -0,0 +1,11 @@
+// Command siphon is the CLI entry point. All real work lives in
+// internal/cli; this file exists only to satisfy the Go executable layout.
+package main
+
+import (
+	"os"
+
+	"github.com/nixrajput/siphon/internal/cli"
+)
+
+func main() { os.Exit(cli.Execute()) }

go.mod

@@ -0,0 +1,89 @@
+module github.com/nixrajput/siphon
+
+go 1.26.3
+
+require (
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/jackc/pgx/v5 v5.9.2
+	github.com/oklog/ulid/v2 v2.1.1
+	github.com/spf13/cobra v1.10.2
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
+	github.com/charmbracelet/x/ansi v0.10.1 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
+	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/ebitengine/purego v0.10.0 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/klauspost/compress v1.18.5 // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.2.0 // indirect
+	github.com/moby/moby/api v1.54.1 // indirect
+	github.com/moby/moby/client v0.4.0 // indirect
+	github.com/moby/patternmatcher v0.6.1 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.2 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/rogpeppe/go-internal v1.15.0 // indirect
+	github.com/shirou/gopsutil/v4 v4.26.3 // indirect
+	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
+	github.com/testcontainers/testcontainers-go v0.42.0 // indirect
+	github.com/tklauser/go-sysconf v0.3.16 // indirect
+	github.com/tklauser/numcpus v0.11.0 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0 // indirect
+	go.opentelemetry.io/otel v1.41.0 // indirect
+	go.opentelemetry.io/otel/metric v1.41.0 // indirect
+	go.opentelemetry.io/otel/trace v1.41.0 // indirect
+	golang.org/x/crypto v0.48.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
+)