sc/sgard

Files

Kyle Isom 5f1bc4e14c Step 16: Polish — docs, flake, goreleaser, e2e test.

Phase 2 complete.

ARCHITECTURE.md: full rewrite covering gRPC protocol, SSH auth,
updated package structure, all Garden methods, design decisions.
README.md: add remote sync section, mirror/prune commands, sgardd usage.
CLAUDE.md: add gRPC/proto/x-crypto deps, server/client/sgardpb packages.
flake.nix: build both sgard + sgardd, updated vendorHash.
goreleaser: add sgardd build target.
E2e test: full push/pull cycle with SSH auth between two clients.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-24 00:10:04 -07:00

2.1 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Critical: Keep Project Docs Updated

Any change to the codebase MUST be reflected in these files:

ARCHITECTURE.md — design decisions, data model, package structure
PROJECT_PLAN.md — implementation steps; check off completed items
PROGRESS.md — current status, change log; update after completing any step

If another agent or engineer picks this up later, these files are how they resume. Keeping them accurate is not optional.

Project

sgard (Shimmering Clarity Gardener) — a dotfiles manager. Module: github.com/kisom/sgard. Author: K. Isom kyle@imap.cc.

Build

go build ./...                   # both sgard and sgardd

Nix:

nix build .#sgard                # builds both binaries

Run tests:

go test ./...

Lint:

golangci-lint run ./...

Regenerate proto (requires protoc toolchain):

make proto

Dependencies

gopkg.in/yaml.v3 — manifest serialization
github.com/spf13/cobra — CLI framework
github.com/jonboulle/clockwork — injectable clock for deterministic tests
google.golang.org/grpc — gRPC runtime
google.golang.org/protobuf — protobuf runtime
golang.org/x/crypto — SSH key auth (ssh, ssh/agent)

Package Structure

cmd/sgard/    CLI entry point (cobra commands, pure wiring)
cmd/sgardd/   gRPC server daemon
garden/       Core business logic (Garden struct orchestrating everything)
manifest/     YAML manifest parsing (Manifest/Entry structs, Load/Save)
store/        Content-addressable blob storage (SHA-256 keyed)
server/       gRPC server (RPC handlers, SSH auth interceptor, proto conversion)
client/       gRPC client library (Push, Pull, Prune, SSH credentials)
sgardpb/      Generated protobuf + gRPC Go code

Key rule: all logic lives in garden/. The cmd/ layer only parses flags and calls Garden methods. The server wraps Garden as gRPC endpoints. No logic duplication.

Each garden operation lives in its own file (garden/<op>.go) to minimize merge conflicts during parallel development.

2.1 KiB Raw Blame History