procoder-cli 0.1.0

package/internal/errs/errors.go

@@ -0,0 +1,114 @@
+package errs
+
+import (
+	stderrors "errors"
+	"fmt"
+)
+
+type Code string
+
+const (
+	CodeNotGitRepo             Code = "NOT_GIT_REPO"
+	CodeWorktreeDirty          Code = "WORKTREE_DIRTY"
+	CodeUntrackedFilesPresent  Code = "UNTRACKED_FILES_PRESENT"
+	CodeSubmodulesUnsupported  Code = "SUBMODULES_UNSUPPORTED"
+	CodeLFSUnsupported         Code = "LFS_UNSUPPORTED"
+	CodeInvalidExchange        Code = "INVALID_EXCHANGE"
+	CodeInvalidReturnPackage   Code = "INVALID_RETURN_PACKAGE"
+	CodeBundleVerifyFailed     Code = "BUNDLE_VERIFY_FAILED"
+	CodeRefOutOfScope          Code = "REF_OUT_OF_SCOPE"
+	CodeNoNewCommits           Code = "NO_NEW_COMMITS"
+	CodeBranchMoved            Code = "BRANCH_MOVED"
+	CodeRefExists              Code = "REF_EXISTS"
+	CodeTargetBranchCheckedOut Code = "TARGET_BRANCH_CHECKED_OUT"
+	CodeUnknownCommand         Code = "UNKNOWN_COMMAND"
+	CodeNotImplemented         Code = "NOT_IMPLEMENTED"
+	CodeGitCommandFailed       Code = "GIT_COMMAND_FAILED"
+	CodeGitUnavailable         Code = "GIT_UNAVAILABLE"
+	CodeInternal               Code = "INTERNAL"
+)
+
+type Error struct {
+	Code    Code
+	Message string
+	Hint    string
+	Details []string
+	Err     error
+}
+
+func (e *Error) Error() string {
+	if e == nil {
+		return ""
+	}
+	if e.Message == "" {
+		return string(e.Code)
+	}
+	return fmt.Sprintf("%s: %s", e.Code, e.Message)
+}
+
+func (e *Error) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Err
+}
+
+type Option func(*Error)
+
+func New(code Code, message string, opts ...Option) *Error {
+	e := &Error{
+		Code:    code,
+		Message: message,
+	}
+	for _, opt := range opts {
+		opt(e)
+	}
+	return e
+}
+
+func Wrap(code Code, message string, err error, opts ...Option) *Error {
+	opts = append([]Option{WithCause(err)}, opts...)
+	return New(code, message, opts...)
+}
+
+func WithHint(hint string) Option {
+	return func(e *Error) {
+		e.Hint = hint
+	}
+}
+
+func WithDetails(details ...string) Option {
+	return func(e *Error) {
+		e.Details = append(e.Details, details...)
+	}
+}
+
+func WithDetailf(format string, args ...any) Option {
+	return WithDetails(fmt.Sprintf(format, args...))
+}
+
+func WithCause(err error) Option {
+	return func(e *Error) {
+		e.Err = err
+	}
+}
+
+func As(err error) (*Error, bool) {
+	if err == nil {
+		return nil, false
+	}
+	var typed *Error
+	if stderrors.As(err, &typed) {
+		return typed, true
+	}
+	return nil, false
+}
+
+func CodeOf(err error) Code {
+	if typed, ok := As(err); ok {
+		if typed.Code != "" {
+			return typed.Code
+		}
+	}
+	return CodeInternal
+}

package/internal/exchange/exchange_test.go

@@ -0,0 +1,165 @@
+package exchange
+
+import (
+	"bytes"
+	"path/filepath"
+	"reflect"
+	"regexp"
+	"testing"
+	"time"
+)
+
+func TestGenerateID(t *testing.T) {
+	now := time.Date(2026, time.March, 20, 11, 30, 15, 0, time.UTC)
+	id, err := GenerateID(now, bytes.NewReader([]byte{0xAA, 0x01, 0xBC}))
+	if err != nil {
+		t.Fatalf("GenerateID returned error: %v", err)
+	}
+
+	const expected = "20260320-113015-aa01bc"
+	if id != expected {
+		t.Fatalf("unexpected id: got %q want %q", id, expected)
+	}
+
+	matched, err := regexp.MatchString(`^\d{8}-\d{6}-[0-9a-f]{6}$`, id)
+	if err != nil {
+		t.Fatalf("regexp compile failed: %v", err)
+	}
+	if !matched {
+		t.Fatalf("id does not match expected format: %q", id)
+	}
+}
+
+func TestGenerateIDInsufficientRandomBytes(t *testing.T) {
+	_, err := GenerateID(time.Now(), bytes.NewReader([]byte{0xAB}))
+	if err == nil {
+		t.Fatal("expected error for insufficient random bytes")
+	}
+}
+
+func TestExchangeAndReturnJSONRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	now := time.Date(2026, time.March, 20, 10, 30, 0, 0, time.UTC)
+	ex := Exchange{
+		Protocol:    ExchangeProtocolV1,
+		ExchangeID:  "20260320-103000-a1b2c3",
+		CreatedAt:   now,
+		ToolVersion: "0.1.0",
+		Source: ExchangeSource{
+			HeadRef: "refs/heads/main",
+			HeadOID: "abc123",
+		},
+		Task: ExchangeTask{
+			RootRef:   "refs/heads/procoder/20260320-103000-a1b2c3/task",
+			RefPrefix: "refs/heads/procoder/20260320-103000-a1b2c3",
+			BaseOID:   "abc123",
+		},
+		Context: ExchangeContext{
+			Heads: map[string]string{
+				"refs/heads/main": "abc123",
+			},
+			Tags: map[string]string{
+				"refs/tags/v1.0.0": "def456",
+			},
+		},
+	}
+
+	ret := Return{
+		Protocol:    ReturnProtocolV1,
+		ExchangeID:  ex.ExchangeID,
+		CreatedAt:   now.Add(30 * time.Minute),
+		ToolVersion: "0.1.0",
+		BundleFile:  "procoder-return.bundle",
+		Task: ReturnTask{
+			RootRef: ex.Task.RootRef,
+			BaseOID: ex.Task.BaseOID,
+		},
+		Updates: []RefUpdate{
+			{
+				Ref:    ex.Task.RootRef,
+				OldOID: "abc123",
+				NewOID: "def456",
+			},
+		},
+	}
+
+	exPath := filepath.Join(t.TempDir(), "exchange.json")
+	if err := WriteExchange(exPath, ex); err != nil {
+		t.Fatalf("WriteExchange failed: %v", err)
+	}
+	gotEx, err := ReadExchange(exPath)
+	if err != nil {
+		t.Fatalf("ReadExchange failed: %v", err)
+	}
+	if !reflect.DeepEqual(ex, gotEx) {
+		t.Fatalf("exchange mismatch after round trip:\n got: %#v\nwant: %#v", gotEx, ex)
+	}
+
+	retPath := filepath.Join(t.TempDir(), "procoder-return.json")
+	if err := WriteReturn(retPath, ret); err != nil {
+		t.Fatalf("WriteReturn failed: %v", err)
+	}
+	gotRet, err := ReadReturn(retPath)
+	if err != nil {
+		t.Fatalf("ReadReturn failed: %v", err)
+	}
+	if !reflect.DeepEqual(ret, gotRet) {
+		t.Fatalf("return mismatch after round trip:\n got: %#v\nwant: %#v", gotRet, ret)
+	}
+}
+
+func TestIsTaskRef(t *testing.T) {
+	exchangeID := "20260320-113015-a1b2c3"
+	root := TaskRootRef(exchangeID)
+	prefix := TaskRefPrefix(exchangeID)
+
+	if !IsTaskRef(exchangeID, root) {
+		t.Fatalf("expected root ref to be allowed: %q", root)
+	}
+	if IsTaskRef(exchangeID, prefix) {
+		t.Fatalf("did not expect prefix-only ref to be allowed: %q", prefix)
+	}
+	sibling := prefix + "/experiment"
+	if !IsTaskRef(exchangeID, sibling) {
+		t.Fatalf("expected sibling task-family ref to be allowed: %q", sibling)
+	}
+	if IsTaskRef(exchangeID, "refs/heads/main") {
+		t.Fatal("did not expect refs/heads/main to be allowed")
+	}
+}
+
+func TestTaskRefHelpersFailClosedForInvalidExchangeID(t *testing.T) {
+	t.Parallel()
+
+	refInNamespace := "refs/heads/procoder/20260320-113015-a1b2c3/task"
+	testCases := []struct {
+		name string
+		id   string
+	}{
+		{name: "empty", id: ""},
+		{name: "spaces", id: "   "},
+		{name: "date-only", id: "20260320"},
+		{name: "missing-random", id: "20260320-113015"},
+		{name: "contains-slash", id: "20260320-113015-a1b2c3/child"},
+		{name: "path-traversal", id: "../20260320-113015-a1b2c3"},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			root := TaskRootRef(tc.id)
+			if root != "" {
+				t.Fatalf("expected empty root for invalid exchange ID %q, got %q", tc.id, root)
+			}
+			if prefix := TaskRefPrefix(tc.id); prefix != "" {
+				t.Fatalf("expected empty prefix for invalid exchange ID %q, got %q", tc.id, prefix)
+			}
+			if IsTaskRef(tc.id, refInNamespace) {
+				t.Fatalf("expected IsTaskRef false for invalid exchange ID %q", tc.id)
+			}
+		})
+	}
+}

package/internal/exchange/id.go

@@ -0,0 +1,66 @@
+package exchange
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+	"time"
+)
+
+const (
+	TaskRefNamespace = "refs/heads/procoder"
+	taskBranchName   = "task"
+)
+
+var exchangeIDPattern = regexp.MustCompile(`^\d{8}-\d{6}-[0-9a-f]{6}$`)
+
+func NewID() (string, error) {
+	return GenerateID(time.Now().UTC(), rand.Reader)
+}
+
+func GenerateID(now time.Time, random io.Reader) (string, error) {
+	if random == nil {
+		return "", fmt.Errorf("random source is nil")
+	}
+	buf := make([]byte, 3)
+	if _, err := io.ReadFull(random, buf); err != nil {
+		return "", fmt.Errorf("read random bytes: %w", err)
+	}
+	stamp := now.UTC().Format("20060102-150405")
+	return fmt.Sprintf("%s-%s", stamp, hex.EncodeToString(buf)), nil
+}
+
+func TaskRootRef(exchangeID string) string {
+	prefix := TaskRefPrefix(exchangeID)
+	if prefix == "" {
+		return ""
+	}
+	return prefix + "/" + taskBranchName
+}
+
+func TaskRefPrefix(exchangeID string) string {
+	normalized, ok := normalizeExchangeID(exchangeID)
+	if !ok {
+		return ""
+	}
+	return TaskRefNamespace + "/" + normalized
+}
+
+func IsTaskRef(exchangeID, ref string) bool {
+	prefix := TaskRefPrefix(exchangeID)
+	if prefix == "" {
+		return false
+	}
+	return strings.HasPrefix(ref, prefix+"/")
+}
+
+func normalizeExchangeID(exchangeID string) (string, bool) {
+	exchangeID = strings.TrimSpace(exchangeID)
+	if !exchangeIDPattern.MatchString(exchangeID) {
+		return "", false
+	}
+	return exchangeID, true
+}

package/internal/exchange/json.go

@@ -0,0 +1,64 @@
+package exchange
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+func WriteExchange(path string, e Exchange) error {
+	if e.Protocol == "" {
+		e.Protocol = ExchangeProtocolV1
+	}
+	return writeJSON(path, e)
+}
+
+func ReadExchange(path string) (Exchange, error) {
+	var e Exchange
+	if err := readJSON(path, &e); err != nil {
+		return Exchange{}, err
+	}
+	return e, nil
+}
+
+func WriteReturn(path string, r Return) error {
+	if r.Protocol == "" {
+		r.Protocol = ReturnProtocolV1
+	}
+	return writeJSON(path, r)
+}
+
+func ReadReturn(path string) (Return, error) {
+	var r Return
+	if err := readJSON(path, &r); err != nil {
+		return Return{}, err
+	}
+	return r, nil
+}
+
+func writeJSON(path string, value any) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return fmt.Errorf("create directory for %s: %w", path, err)
+	}
+	encoded, err := json.MarshalIndent(value, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshal json for %s: %w", path, err)
+	}
+	encoded = append(encoded, '\n')
+	if err := os.WriteFile(path, encoded, 0o644); err != nil {
+		return fmt.Errorf("write %s: %w", path, err)
+	}
+	return nil
+}
+
+func readJSON(path string, out any) error {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return fmt.Errorf("read %s: %w", path, err)
+	}
+	if err := json.Unmarshal(data, out); err != nil {
+		return fmt.Errorf("decode %s: %w", path, err)
+	}
+	return nil
+}

package/internal/exchange/types.go

@@ -0,0 +1,55 @@
+package exchange
+
+import "time"
+
+const (
+	ExchangeProtocolV1 = "procoder-exchange/v1"
+	ReturnProtocolV1   = "procoder-return/v1"
+)
+
+type Exchange struct {
+	Protocol    string          `json:"protocol"`
+	ExchangeID  string          `json:"exchange_id"`
+	CreatedAt   time.Time       `json:"created_at"`
+	ToolVersion string          `json:"tool_version"`
+	Source      ExchangeSource  `json:"source"`
+	Task        ExchangeTask    `json:"task"`
+	Context     ExchangeContext `json:"context"`
+}
+
+type ExchangeSource struct {
+	HeadRef string `json:"head_ref"`
+	HeadOID string `json:"head_oid"`
+}
+
+type ExchangeTask struct {
+	RootRef   string `json:"root_ref"`
+	RefPrefix string `json:"ref_prefix"`
+	BaseOID   string `json:"base_oid"`
+}
+
+type ExchangeContext struct {
+	Heads map[string]string `json:"heads,omitempty"`
+	Tags  map[string]string `json:"tags,omitempty"`
+}
+
+type Return struct {
+	Protocol    string      `json:"protocol"`
+	ExchangeID  string      `json:"exchange_id"`
+	CreatedAt   time.Time   `json:"created_at"`
+	ToolVersion string      `json:"tool_version"`
+	BundleFile  string      `json:"bundle_file"`
+	Task        ReturnTask  `json:"task"`
+	Updates     []RefUpdate `json:"updates"`
+}
+
+type ReturnTask struct {
+	RootRef string `json:"root_ref"`
+	BaseOID string `json:"base_oid"`
+}
+
+type RefUpdate struct {
+	Ref    string `json:"ref"`
+	OldOID string `json:"old_oid"`
+	NewOID string `json:"new_oid"`
+}

package/internal/gitx/gitx.go

@@ -0,0 +1,105 @@
+package gitx
+
+import (
+	"bytes"
+	stderrors "errors"
+	"fmt"
+	"io"
+	"os/exec"
+	"strconv"
+	"strings"
+
+	"github.com/amxv/procoder/internal/errs"
+)
+
+type Runner struct {
+	Dir string
+	Env []string
+}
+
+type Result struct {
+	Args     []string
+	Stdout   string
+	Stderr   string
+	ExitCode int
+}
+
+func NewRunner(dir string) Runner {
+	return Runner{Dir: dir}
+}
+
+func (r Runner) Run(args ...string) (Result, error) {
+	return r.run(nil, args...)
+}
+
+func (r Runner) RunWithInput(input string, args ...string) (Result, error) {
+	return r.run(strings.NewReader(input), args...)
+}
+
+func (r Runner) run(stdin io.Reader, args ...string) (Result, error) {
+	cmd := exec.Command("git", args...)
+	cmd.Dir = r.Dir
+	if len(r.Env) > 0 {
+		cmd.Env = append(cmd.Environ(), r.Env...)
+	}
+	if stdin != nil {
+		cmd.Stdin = stdin
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	result := Result{
+		Args: args,
+	}
+
+	err := cmd.Run()
+	result.Stdout = stdout.String()
+	result.Stderr = stderr.String()
+	result.ExitCode = getExitCode(err)
+	if err == nil {
+		return result, nil
+	}
+
+	var execErr *exec.Error
+	if stderrors.As(err, &execErr) {
+		return result, errs.Wrap(
+			errs.CodeGitUnavailable,
+			"git executable is unavailable",
+			err,
+			errs.WithHint("install Git and retry"),
+		)
+	}
+
+	commandText := "git"
+	if len(args) > 0 {
+		commandText += " " + strings.Join(args, " ")
+	}
+	details := []string{
+		"Command: " + commandText,
+		"Exit code: " + strconv.Itoa(result.ExitCode),
+	}
+	stderrText := strings.TrimRight(result.Stderr, "\n")
+	if stderrText != "" {
+		details = append(details, "Stderr: "+stderrText)
+	}
+	return result, errs.Wrap(
+		errs.CodeGitCommandFailed,
+		fmt.Sprintf("git command failed: %s", commandText),
+		err,
+		errs.WithDetails(details...),
+	)
+}
+
+func getExitCode(err error) int {
+	if err == nil {
+		return 0
+	}
+	var exitErr *exec.ExitError
+	if stderrors.As(err, &exitErr) {
+		return exitErr.ExitCode()
+	}
+	return -1
+}

package/internal/gitx/gitx_test.go

@@ -0,0 +1,51 @@
+package gitx
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/amxv/procoder/internal/errs"
+	"github.com/amxv/procoder/internal/testutil/gitrepo"
+)
+
+func TestRunnerRunSuccess(t *testing.T) {
+	repo := gitrepo.New(t)
+	repo.WriteFile("README.md", "hello\n")
+	headOID := repo.CommitAll("initial commit")
+
+	runner := NewRunner(repo.Dir)
+	result, err := runner.Run("rev-parse", "HEAD")
+	if err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	if result.ExitCode != 0 {
+		t.Fatalf("expected exit code 0, got %d", result.ExitCode)
+	}
+	if strings.TrimSpace(result.Stdout) != headOID {
+		t.Fatalf("unexpected stdout: got %q want %q", strings.TrimSpace(result.Stdout), headOID)
+	}
+}
+
+func TestRunnerRunFailure(t *testing.T) {
+	repo := gitrepo.New(t)
+	runner := NewRunner(repo.Dir)
+
+	result, err := runner.Run("rev-parse", "refs/heads/does-not-exist")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if result.ExitCode == 0 {
+		t.Fatalf("expected non-zero exit code, got %d", result.ExitCode)
+	}
+
+	typed, ok := errs.As(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if typed.Code != errs.CodeGitCommandFailed {
+		t.Fatalf("expected code %s, got %s", errs.CodeGitCommandFailed, typed.Code)
+	}
+	if !strings.Contains(strings.Join(typed.Details, "\n"), "Exit code:") {
+		t.Fatalf("expected exit code detail, got %v", typed.Details)
+	}
+}

package/internal/output/errors.go

@@ -0,0 +1,49 @@
+package output
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/amxv/procoder/internal/errs"
+)
+
+func WriteError(w io.Writer, err error) {
+	if err == nil {
+		return
+	}
+	_, _ = io.WriteString(w, FormatError(err))
+}
+
+func FormatError(err error) string {
+	if err == nil {
+		return ""
+	}
+
+	var b strings.Builder
+	if typed, ok := errs.As(err); ok {
+		code := typed.Code
+		if code == "" {
+			code = errs.CodeInternal
+		}
+		message := typed.Message
+		if message == "" {
+			message = "unexpected error"
+		}
+		_, _ = fmt.Fprintf(&b, "%s: %s\n", code, message)
+		for _, detail := range typed.Details {
+			detail = strings.TrimSpace(detail)
+			if detail == "" {
+				continue
+			}
+			_, _ = fmt.Fprintf(&b, "%s\n", detail)
+		}
+		if typed.Hint != "" {
+			_, _ = fmt.Fprintf(&b, "Hint: %s\n", typed.Hint)
+		}
+		return b.String()
+	}
+
+	_, _ = fmt.Fprintf(&b, "%s: %s\n", errs.CodeInternal, err.Error())
+	return b.String()
+}

package/internal/output/errors_test.go

@@ -0,0 +1,41 @@
+package output
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/amxv/procoder/internal/errs"
+)
+
+func TestFormatErrorTyped(t *testing.T) {
+	err := errs.New(
+		errs.CodeBranchMoved,
+		"cannot update refs/heads/procoder/20260320-abc123",
+		errs.WithDetails(
+			"Expected old OID: abc123",
+			"Current local OID: def456",
+		),
+		errs.WithHint("rerun with --namespace procoder-import"),
+	)
+
+	got := FormatError(err)
+	wantLines := []string{
+		"BRANCH_MOVED: cannot update refs/heads/procoder/20260320-abc123",
+		"Expected old OID: abc123",
+		"Current local OID: def456",
+		"Hint: rerun with --namespace procoder-import",
+	}
+	for _, line := range wantLines {
+		if !strings.Contains(got, line) {
+			t.Fatalf("missing line %q in output:\n%s", line, got)
+		}
+	}
+}
+
+func TestFormatErrorUntyped(t *testing.T) {
+	got := FormatError(errors.New("boom"))
+	if got != "INTERNAL: boom\n" {
+		t.Fatalf("unexpected fallback format: %q", got)
+	}
+}