Skip to content

feat: DX, security, installability, and docs overhaul#18

Merged
Tom-De-Santa-FOSS merged 9 commits intomasterfrom
feature/dx-security-installability-overhaul
Apr 5, 2026
Merged

feat: DX, security, installability, and docs overhaul#18
Tom-De-Santa-FOSS merged 9 commits intomasterfrom
feature/dx-security-installability-overhaul

Conversation

@Tom-De-Santa-FOSS
Copy link
Copy Markdown
Owner

Summary

Comprehensive overhaul to beat virtui across developer experience, security, installability, and documentation. Implements epic awn-233 (6 child issues).

  • Security: Unix domain socket as default transport (0600 perms, stale cleanup, graceful shutdown). TCP is now opt-in via --tcp flag requiring AWN_TOKEN
  • DX: Typed Go SDK with functional options, 19 methods, structured error parsing. Extended create with --env, --dir, --record flags. Added --repeat to press
  • Installability: goreleaser v2 config for cross-platform binaries + Homebrew tap. CI pipeline with race-detected tests on ubuntu/macos matrix
  • Docs: Full README rewrite, SDK reference, error catalog, updated RPC docs
  • Errors: 9 new constructors, context maps, category constants, comprehensive test coverage

Commits (9 atomic units)

  1. Structured error constructors and context field
  2. Unix domain socket transport with stale cleanup
  3. Env, dir, record, repeat for session/input
  4. Unix socket dialing in RPC client
  5. Dual-mode daemon (Unix default + TCP opt-in)
  6. CLI support for all new features
  7. Typed Go SDK with functional options
  8. goreleaser, CI pipeline, version injection
  9. Documentation overhaul

Stats

  • 25 files changed (16 modified, 9 new)
  • ~1175 lines added, ~215 removed
  • 234 tests passing with race detector

Test plan

  • All 234 tests pass with go test -race ./...
  • Error constructors produce correct codes, categories, retryability
  • Unix socket binds with 0600, cleans stale sockets, probe-then-remove
  • SDK mock server tests cover all 19 methods
  • CLI flag parsing tests for env, dir, record, repeat
  • Manual: start daemon, verify Unix socket at ~/.awn/daemon.sock
  • Manual: awn create bash --env FOO=bar --dir /tmp
  • Manual: awn create bash --record
  • Manual: verify --tcp mode requires AWN_TOKEN
  • Manual: goreleaser dry-run (goreleaser release --snapshot --clean)

🤖 Generated with Claude Code

Tom-De-Santa-FOSS and others added 9 commits April 5, 2026 19:45
Add Context map to AwnError, 8 category constants, and 9 new error
constructors (SessionExited, DaemonNotRunning, DaemonAlreadyRunning,
ConnectionFailed, AuthRequired, AuthFailed, InvalidKey,
PipelineStepFailed, InvalidDir). Comprehensive test coverage for all
constructors, JSON serialization, IsRetryable, ErrorCode, and
errors.As unwrapping.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add ListenAndServeUnix() for 0600-permission socket binding, stale
socket detection via probe-then-remove, and Close() for graceful
listener shutdown and socket cleanup. Convert ListenAndServe() to use
net.Listen for shutdown support. Tests cover bind+accept, permissions,
stale cleanup, close removal, and TCP-without-token rejection.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Extend Config with Env and Dir fields, validate directory existence,
merge environment variables into spawned process. Extend RPC create
with env/dir/record/record_path params and input with repeat field.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add NewUnix constructor and Unix socket dial path to call() so the
internal client can connect via domain socket when no TCP address is set.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Default to Unix socket at ~/.awn/daemon.sock. Add --tcp flag for
explicit TCP mode (requires AWN_TOKEN). Add --socket flag, --version
flag, version/commit ldflags, and signal handler with socket cleanup.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Default RPC dialing to Unix socket when AWN_ADDR is unset. Add
structured error display with hint lines. Add --env, --dir, --record,
--record-path flags to create and --repeat/-n to press. Update daemon
start/status for dual transport. Tests for new flag combinations.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New sdk package with Connect(), 19 typed methods, functional options
pattern (WithAddr, WithSocket, WithToken, WithFull, WaitText, etc.),
and structured error parsing. Includes comprehensive test suite with
mock WebSocket server covering all methods.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add goreleaser v2 config for 3 binaries across linux/darwin/amd64/arm64
with Homebrew tap. Add CI workflow with Go test + race detector on
ubuntu/macos matrix and golangci-lint. Update release workflow to
tag-triggered goreleaser. Add LDFLAGS to Makefile and version flags
to awn-mcp.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rewrite README with install methods (Homebrew, Go, shell script,
binary), full CLI reference, Go SDK examples, architecture diagram,
security model, and environment variables. Add SDK reference, error
catalog, and updated RPC docs with new transport, fields, and error
format sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@Tom-De-Santa-FOSS Tom-De-Santa-FOSS merged commit 9862bda into master Apr 5, 2026
2 of 6 checks passed
@Tom-De-Santa-FOSS Tom-De-Santa-FOSS deleted the feature/dx-security-installability-overhaul branch April 5, 2026 14:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant