Mega refactor: package layout, typed events, tests, docs, tooling

.github/workflows/ci.yml

@@ -6,31 +6,111 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
+env:
+  GO_VERSION: '1.23'
+
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version: ${{ env.GO_VERSION }}
+          cache: true
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v7
+        with:
+          version: v2.11
+          args: --timeout=5m ./...
+
+  fmt-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          cache: true
+      - name: gofmt
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "::error::These files are not gofmt-formatted:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+  govet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          cache: true
+      - name: go vet
+        run: go vet ./...
+
+  staticcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          cache: true
+      - name: Install staticcheck
+        run: go install honnef.co/go/tools/cmd/staticcheck@v0.6.1
+      - name: staticcheck
+        run: staticcheck ./...
+
+  tidy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
           cache: true
-      - name: Lint
-        uses: golangci/golangci-lint-action@v6
+      - name: Verify go mod tidy is clean
+        run: |
+          go mod tidy
+          git diff --exit-code -- go.mod go.sum
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
         with:
-          version: latest
-          args: --timeout=5m
+          go-version: ${{ env.GO_VERSION }}
+          cache: true
+      - name: Test
+        run: go test -race -count=1 ./...
 
   build:
+    needs: [lint, fmt-check, govet, staticcheck, tidy, test]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version: ${{ env.GO_VERSION }}
           cache: true
       - name: Build
-        run: go build -o pi-stream .
+        run: |
+          VERSION="${GITHUB_SHA::7}"
+          go build \
+            -ldflags="-s -w -X github.com/crazy-goat/pi-stream/internal/cli.Version=${VERSION}" \
+            -o pi-stream .
       - name: Upload binary
         uses: actions/upload-artifact@v4
         with:

.golangci.yml

@@ -0,0 +1,30 @@
+version: "2"
+
+run:
+  timeout: 5m
+  issues-exit-code: 1
+  tests: true
+
+linters:
+  default: none
+  enable:
+    - govet
+    - staticcheck
+    - unused
+    - ineffassign
+    - errcheck
+    - dupl
+  settings:
+    staticcheck:
+      checks:
+        - "all"
+        - "-QF*"
+        - "-ST*"
+
+formatters:
+  enable:
+    - gofmt
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piotr Hałas
+
+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.

Makefile

@@ -1,14 +1,82 @@
-.PHONY: build clean install all
+.PHONY: build install test clean lint lint-fix fmt vet staticcheck check tidy help
 
-BINARY := pi-stream
+BINARY  := pi-stream
+PKG     := github.com/crazy-goat/pi-stream/internal/cli
+VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
+LDFLAGS := -s -w -X $(PKG).Version=$(VERSION)
 
-all: build
+GOLANGCI_LINT := $(shell command -v golangci-lint 2>/dev/null || echo "$$(go env GOPATH)/bin/golangci-lint")
+
+help:
+	@echo "Available targets:"
+	@echo "  make build        - Build the binary (with version embedded)"
+	@echo "  make install      - Build and copy binary to \$$HOME/.local/bin"
+	@echo "  make test         - Run tests with -race"
+	@echo "  make lint         - Run golangci-lint"
+	@echo "  make lint-fix     - Run golangci-lint with auto-fix"
+	@echo "  make fmt          - Format code with gofmt"
+	@echo "  make vet          - Run go vet"
+	@echo "  make staticcheck  - Run staticcheck"
+	@echo "  make tidy         - go mod tidy + diff check"
+	@echo "  make check        - Run fmt, vet, staticcheck, lint, test, build"
+	@echo "  make clean        - Remove built binary"
 
 build:
-	go build -o $(BINARY) .
+	go build -ldflags='$(LDFLAGS)' -o $(BINARY) .
+
+install: build
+	install -d $(HOME)/.local/bin
+	install -m 0755 $(BINARY) $(HOME)/.local/bin/$(BINARY)
+	@echo "Installed $(BINARY) to $(HOME)/.local/bin"
+
+test:
+	go test -race -count=1 ./...
+
+fmt:
+	@echo "Formatting code..."
+	@gofmt -w .
+	@echo "Done"
+
+vet:
+	@echo "Running go vet..."
+	@go vet ./...
+	@echo "Done"
+
+lint:
+	@echo "Running golangci-lint..."
+	@if [ -x "$(GOLANGCI_LINT)" ]; then \
+		$(GOLANGCI_LINT) run ./...; \
+	else \
+		echo "golangci-lint not installed. Install with:"; \
+		echo "  curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $$(go env GOPATH)/bin"; \
+		exit 1; \
+	fi
+
+lint-fix:
+	@echo "Running golangci-lint with auto-fix..."
+	@if [ -x "$(GOLANGCI_LINT)" ]; then \
+		$(GOLANGCI_LINT) run --fix ./...; \
+	else \
+		echo "golangci-lint not installed."; \
+		exit 1; \
+	fi
+
+staticcheck:
+	@echo "Running staticcheck..."
+	@if command -v staticcheck >/dev/null 2>&1; then \
+		staticcheck ./...; \
+	else \
+		echo "staticcheck not installed. Install with:"; \
+		echo "  go install honnef.co/go/tools/cmd/staticcheck@latest"; \
+		exit 1; \
+	fi
+
+tidy:
+	go mod tidy
+	@git diff --exit-code -- go.mod go.sum || (echo "go.mod/go.sum changed; commit the tidy result"; exit 1)
+
+check: fmt vet staticcheck lint test build
+	@echo "All checks passed!"
 
 clean:
 	rm -f $(BINARY)
-
-install: build
-	cp $(BINARY) ~/.local/bin/

README.md

@@ -0,0 +1,86 @@
+# pi-stream
+
+A small streaming proxy for [`pi`](https://github.com/) in RPC mode. It launches
+`pi --mode rpc`, sends a single prompt over its JSON-RPC stdin, and renders the
+event stream from pi's stdout as styled terminal output:
+
+- thinking tokens in dim italic
+- assistant text plain
+- tool calls (`🔧 name args`) when the model decides to invoke a tool
+- tool execution (`⚡ name: cmd`) when the tool actually runs
+- truncated tool result with `✓` / `✗` status
+
+## Requirements
+
+- Go 1.23+ to build
+- A working `pi` binary on `$PATH` (this proxy spawns it)
+
+## Install
+
+```sh
+make install        # builds and copies pi-stream into ~/.local/bin
+# or
+go install github.com/crazy-goat/pi-stream@latest
+```
+
+## Usage
+
+```sh
+pi-stream [flags] <prompt>
+```
+
+### Flags
+
+| Flag         | Default | Description                                                  |
+| ------------ | ------- | ------------------------------------------------------------ |
+| `--model`    | (auto)  | Model name forwarded to pi (e.g. `"GLM 5.1"`).               |
+| `--thinking` | `high`  | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. |
+| `-t`         | (none)  | Comma-separated tool allowlist (e.g. `bash,read`).           |
+| `--session`  | (none)  | pi session file path; share between invocations for context. |
+| `--version`  |         | Print version and exit.                                      |
+
+### Examples
+
+```sh
+# Quick one-shot prompt
+pi-stream --model "GLM 5.1" --thinking off "tell me a one-line joke"
+
+# Let the model use bash
+pi-stream --model "GLM 5.1" -t bash "list files in this repo and summarize"
+
+# Reuse a session across multiple calls
+pi-stream --session /tmp/sess "first message"
+pi-stream --session /tmp/sess "follow-up that should remember the first"
+```
+
+### Exit codes
+
+| Code | Meaning                                            |
+| ---- | -------------------------------------------------- |
+| 0    | Normal completion (`agent_end` received)           |
+| 1    | pi reported an error envelope, or startup failed   |
+| 2    | Invalid CLI flags / missing prompt                 |
+| 130  | Interrupted by `SIGINT` or `SIGTERM` (Ctrl+C)      |
+
+## Development
+
+```sh
+make build        # compile
+make test         # go test -race ./...
+make lint         # golangci-lint run
+make tidy         # go mod tidy + diff check
+```
+
+Layout:
+
+```
+main.go                       # ~10-line entrypoint
+internal/event/               # typed event structs for pi's JSON stream
+internal/render/              # state-machine Renderer that styles events
+internal/pi/                  # subprocess lifecycle (Start, Events, Close)
+internal/cli/                 # flag parsing + event-loop orchestration
+```
+
+## License
+
+MIT