ci and tests and build and release

Author: roodboi

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    tags-ignore:
+      - "v*"
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: "1.3.5"
+      - name: Install dependencies
+        run: bun install
+      - name: Lint
+        run: bun run lint
+      - name: Typecheck
+        run: bun run typecheck
+      - name: Tests
+        run: bun test

.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: "1.3.5"
+      - name: Install dependencies
+        run: bun install
+      - name: Resolve version
+        id: version
+        run: |
+          VERSION="$(bun -e "const pkg = await Bun.file('package.json').json(); console.log(pkg.version)")"
+          if [ "v$VERSION" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match package.json version $VERSION."
+            exit 1
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+      - name: Build release artifacts
+        run: bun run build:release --version="${{ steps.version.outputs.version }}"
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: "v${{ steps.version.outputs.version }}"
+          generate_release_notes: true
+          files: |
+            dist/release/hack-${{ steps.version.outputs.version }}-*.tar.gz
+            dist/release/hack-${{ steps.version.outputs.version }}-install.sh
+            dist/release/hack-install.sh
+            dist/release/hack-${{ steps.version.outputs.version }}-release/SHA256SUMS

.gitignore

@@ -37,4 +37,6 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 SPECS/
 _DOCS
 TODO.md
-REVIEW.md
+REVIEW.md
+
+dist

.husky/commit-msg

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname "$0")/_/h"
+
+bunx --no-install commitlint --edit "$1"

.releaserc.json

@@ -0,0 +1,20 @@
+{
+  "branches": ["main"],
+  "tagFormat": "v${version}",
+  "plugins": [
+    ["@semantic-release/commit-analyzer", { "preset": "conventionalcommits" }],
+    ["@semantic-release/release-notes-generator", { "preset": "conventionalcommits" }],
+    ["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" }],
+    [
+      "@semantic-release/exec",
+      { "prepareCmd": "bun run scripts/prepare-release.ts --version=${nextRelease.version}" }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md", "package.json", "bun.lock"],
+        "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
+      }
+    ]
+  ]
+}

ARCHITECTURE.md

@@ -13,17 +13,22 @@ Running multiple local projects at the same time is messy when everything wants
 ## System overview
 
 `hack` is a Bun CLI that writes per-project Compose files under `.hack/` and manages a machine-wide
-proxy + logging stack under `~/.hack/`. Caddy routes `*.hack` based on container labels and the
-logging stack (Alloy + Loki + Grafana) captures Docker Compose logs.
+proxy, DNS helpers, and logging stack under `~/.hack/`.
+
+- **Caddy** (docker-proxy) routes `*.hack` based on container labels.
+- **CoreDNS** resolves `*.hack` inside containers to the Caddy IP.
+- **Alloy + Loki + Grafana** capture logs and provide history.
+- **Schemas** are served by Caddy at `https://schemas.hack`.
 
 ```mermaid
-flowchart LR
+graph LR
   CLI["hack CLI (Bun)"]
   Browser["Browser"]
 
   subgraph Host["Developer machine"]
     subgraph Global["Global infra (~/.hack)"]
       Caddy["Caddy docker-proxy"]
+      CoreDNS["CoreDNS"]
       Loki["Loki"]
       Grafana["Grafana"]
       Alloy["Alloy (Docker logs)"]
@@ -43,20 +48,46 @@ flowchart LR
   Services -->|"container logs"| Alloy
   Alloy --> Loki --> Grafana
 
+  CoreDNS -->|"*.hack → Caddy IP"| Services
   Caddy -->|"https://*.hack"| Browser
   Grafana -->|"https://logs.hack"| Browser
+  Caddy -->|"https://schemas.hack"| Browser
 ```
 
 ## Global vs project scope
 
 - Global scope (`~/.hack`)
-  - Caddy proxy listens on 80/443 and routes `https://*.hack` via Docker labels
-  - Logging stack captures all Compose logs (Alloy → Loki → Grafana)
+  - Caddy proxy on 80/443 (routes via Docker labels)
+  - CoreDNS for container DNS (`*.hack` → Caddy)
+  - macOS DNS helper: dnsmasq + `/etc/resolver` for `*.hack` → `127.0.0.1`
+  - Logging stack (Alloy → Loki → Grafana)
+  - Schemas hosted under `https://schemas.hack`
   - Networks: `hack-dev` (ingress) and `hack-logging`
 
 - Project scope (`.hack`)
-  - `docker-compose.yml` defines services and optional Caddy labels
+  - `docker-compose.yml` defines services + Caddy labels
   - `hack.config.json` stores project name, dev host, log preferences, OAuth alias
+  - Optional overrides:
+    - `.internal/compose.override.yml` (internal DNS/TLS injection)
+    - `.branch/compose.<branch>.override.yml` (branch builds)
+
+## Internal DNS + TLS (containers)
+
+When `internal.dns` / `internal.tls` are enabled, `hack up` writes a Compose override that:
+
+- sets each service’s DNS to the CoreDNS container
+- mounts Caddy’s local CA cert into each service
+- sets common SSL env vars (Node, curl, git, requests)
+
+This lets containers use the same `https://*.hack` hostnames as the host machine.
+
+```mermaid
+graph LR
+  Service["Project container"] -->|"DNS query *.hack"| CoreDNS["CoreDNS (hack-dev)"]
+  CoreDNS -->|"A record = Caddy IP"| Service
+  Service -->|"HTTPS request"| Caddy["Caddy docker-proxy"]
+  Caddy -->|"Routes by labels"| Upstream["Service upstream"]
+```
 
 ## Lifecycle (init → up → logs)
 
@@ -87,35 +118,57 @@ sequenceDiagram
 
 ## Logging pipeline
 
+`hack logs` supports two backends:
+
+- **compose**: fast, direct `docker compose logs`
+- **loki**: searchable history + LogQL filters
+
+NDJSON streaming (`hack logs --json`) emits `start`, `log`, and `end` events for MCP/TUI consumers.
+
 ```mermaid
-flowchart LR
+graph LR
   Containers["Compose containers"] -->|"stdout/stderr"| Alloy
   Alloy -->|"push"| Loki
   Loki -->|"query"| CLI["hack logs --loki"]
+  CLI -->|"NDJSON/pretty"| Terminal
   Loki -->|"Explore"| Grafana
-  CLI -->|"pretty output"| Terminal
 ```
 
+## Branch builds
+
+`--branch <name>` generates a per-branch Compose override that:
+
+- prefixes hostnames (e.g. `api.myapp.hack` → `api.<branch>.myapp.hack`)
+- prefixes the Compose project name
+
+This enables parallel worktrees without port or hostname collisions.
+
 ## Files and directories
 
 - `~/.hack/`
   - `caddy/docker-compose.yml`
+  - `caddy/Corefile` (CoreDNS config)
   - `logging/docker-compose.yml`
   - `logging/alloy.alloy`
   - `logging/loki.yaml`
   - `logging/grafana/...`
   - `schemas/hack.config.schema.json`
   - `schemas/hack.branches.schema.json`
+  - `certs/` (mkcert output for non-Caddy services)
   - `projects.json` (best-effort registry)
 
 - `<repo>/.hack/`
   - `docker-compose.yml`
   - `hack.config.json`
   - `hack.branches.json` (optional)
+  - `.internal/compose.override.yml`
+  - `.branch/compose.<branch>.override.yml`
 
 ## Key design choices
 
 - Docker Compose is the execution substrate for predictability and portability.
 - Caddy routes by container label so there is no per-repo reverse proxy config.
-- Logs default to `docker compose logs` for speed, with Loki for history and filtering.
-- Config lives alongside each repo in `.hack/` to keep repos isolated and portable.
+- CoreDNS gives containers the same `*.hack` namespace as the host.
+- Logs default to `docker compose logs` for speed; Loki is used for history and filtering.
+- Config lives alongside each repo in `.hack/` to keep repos isolated and portable.
+- Schemas are generated from templates and served locally for editor validation.

CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog