procoder-cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md
+
+Guidance for coding agents working in `procoder`.
+
+## Purpose
+
+This repo builds `procoder`, a Go CLI for an offline Git exchange workflow between:
+
+- a local developer repository
+- a locked-down ChatGPT coding container
+
+The main user flow is:
+
+- `procoder prepare`
+- remote work inside the exported repo
+- `./procoder-return`
+- `procoder apply <return-package.zip>`
+
+## Architecture
+
+- `cmd/procoder/main.go`: process entrypoint, error handling, exits non-zero on failure.
+- `cmd/procoder-return/main.go`: remote helper entrypoint used inside prepared task packages.
+- `internal/app/app.go`: command parser + top-level CLI handlers.
+- `internal/exchange/`: exchange IDs, task-ref helpers, and JSON models for `exchange.json` / `procoder-return.json`.
+- `internal/gitx/`: Git command runner with structured output and typed failures.
+- `internal/prepare/`: `procoder prepare` implementation.
+- `internal/returnpkg/`: `./procoder-return` implementation.
+- `internal/apply/`: `procoder apply` implementation.
+- `bin/procoder.js`: npm shim that invokes packaged native binary.
+- `scripts/postinstall.js`: downloads or builds both the host CLI binary and the packaged `linux/amd64` helper.
+- `.github/workflows/release.yml`: tag-driven release pipeline.
+
+## Exchange Model
+
+The current Git-valid task-family shape is:
+
+- default prepared task branch: `refs/heads/procoder/<exchange-id>/task`
+- writable task-family prefix: `refs/heads/procoder/<exchange-id>`
+- allowed returned refs: `refs/heads/procoder/<exchange-id>/*`
+
+Important:
+
+- do not reintroduce the invalid older shape where both `refs/heads/procoder/<exchange-id>` and `refs/heads/procoder/<exchange-id>/*` exist at the same time
+- Git cannot store both of those refs because one path would need to be both a ref and a directory
+
+Machine-owned metadata lives under `.git/procoder/`.
+
+- local exchange record: `.git/procoder/exchanges/<exchange-id>/exchange.json`
+- exported repo exchange record: `.git/procoder/exchange.json`
+
+User-facing artifacts live at repo root by default:
+
+- task package: `./procoder-task-<exchange-id>.zip`
+- return package: `./procoder-return-<exchange-id>.zip`
+
+When changing exchange behavior, keep `gg/agent-outputs/procoder-handoff-v1-product-spec.md` and `gg/agent-outputs/procoder-exchange-v1-internal-spec.md` aligned with the code.
+
+## Local commands
+
+Use `make` targets:
+
+- `make fmt`
+- `make test`
+- `make vet`
+- `make lint`
+- `make check`
+- `make build`
+- `make build-helper`
+- `make build-all`
+- `make install-local`
+
+Direct commands:
+
+- `go test ./...`
+- `go vet ./...`
+- `npm run lint`
+
+Phase-oriented validation:
+
+- `procoder prepare` changes should be covered by integration tests under `internal/prepare/`
+- `procoder-return` changes should be covered by integration tests under `internal/returnpkg/`
+- `procoder apply` changes should be covered by integration tests under `internal/apply/`
+
+## How to customize safely
+
+1. Rename CLI command consistently in all places:
+- directory `cmd/procoder`
+- `package.json` values (`bin`, `config.cliBinaryName`)
+- `bin/procoder.js`
+- workflow env `CLI_BINARY`
+- `Makefile` `BIN_NAME`
+
+2. Keep binary naming convention unchanged unless you also update postinstall/workflow:
+- release assets: `<cli>_<goos>_<goarch>[.exe]`
+- packaged helper asset: `procoder-return_linux_amd64`
+- npm-installed binary path: `bin/<cli>-bin` (or `.exe` on Windows)
+
+3. If adding dependencies, commit `go.sum` and optionally enable Go cache in workflow.
+
+4. Keep help output expressive and command-local (`<command> --help` should explain examples).
+
+5. If you change exchange filenames, helper asset names, or task-family ref naming, update:
+- code
+- tests
+- `README.md`
+- `AGENTS.md`
+- both spec docs under `gg/agent-outputs/`
+
+## Release contract
+
+Release pipeline triggers on `v*` tags and expects:
+
+- `NPM_TOKEN` GitHub secret present.
+- npm package name in `package.json` is publishable under your account/org.
+- repository URL matches the release origin used by `scripts/postinstall.js`.
+
+## Guardrails
+
+- Prefer additive changes; do not break the release asset naming contract unintentionally.
+- If you change release artifacts or CLI binary name, update both workflow and postinstall script in the same PR.
+- Keep agent-facing failures specific and actionable, especially for `procoder-return`.
+- Favor integration tests for real Git behavior over mocked unit-only coverage for exchange flows.

package/CONTRIBUTORS.md

@@ -0,0 +1,79 @@
+# CONTRIBUTORS.md
+
+Maintainer notes for this template repository.
+
+## Prerequisites
+
+- Go `1.26+`
+- Node `18+`
+- npm account with publish rights for the package name in `package.json`
+- GitHub repo admin access
+
+## Local development
+
+```bash
+make check
+make build
+make build-helper
+./dist/procoder --help
+```
+
+Install command locally:
+
+```bash
+make install-local
+procoder --help
+```
+
+`make install-local` installs both `procoder` and `procoder-return_linux_amd64` into `~/.local/bin`.
+
+## Release process
+
+1. Ensure `main` is green:
+
+```bash
+make check
+```
+
+2. Prepare release tag:
+
+```bash
+make release-tag VERSION=0.1.0
+```
+
+3. GitHub Actions `release` workflow runs automatically:
+- quality checks
+- cross-platform `procoder` binary build
+- packaged `procoder-return_linux_amd64` helper build
+- GitHub release publish
+- npm publish
+
+## Required GitHub secret
+
+- `NPM_TOKEN`: npm automation token with publish rights for your package.
+
+Set via GitHub CLI:
+
+```bash
+gh secret set NPM_TOKEN --repo amxv/procoder
+```
+
+## npm token setup
+
+Create token at npm:
+
+- Profile -> Access Tokens -> Create New Token
+- Use an automation/granular token scoped to required package/org
+
+Validate auth locally:
+
+```bash
+npm whoami
+```
+
+## Notes on package naming
+
+Before first publish, set a package name you control in `package.json`.
+
+- Example unscoped: `"name": "your-cli-name"`
+- Example scoped: `"name": "@your-scope/your-cli-name"`

package/Makefile

@@ -0,0 +1,82 @@
+SHELL := /bin/bash
+
+GO ?= go
+GOFMT ?= gofmt
+BIN_NAME ?= procoder
+CMD_PATH ?= ./cmd/$(BIN_NAME)
+HELPER_NAME ?= procoder-return
+HELPER_GOOS ?= linux
+HELPER_GOARCH ?= amd64
+HELPER_ASSET ?= $(HELPER_NAME)_$(HELPER_GOOS)_$(HELPER_GOARCH)
+HELPER_CMD_PATH ?= ./cmd/$(HELPER_NAME)
+DIST_DIR ?= dist
+BIN_PATH ?= $(DIST_DIR)/$(BIN_NAME)
+HELPER_PATH ?= $(DIST_DIR)/$(HELPER_ASSET)
+LDFLAGS ?= -s -w
+
+.PHONY: help fmt test vet lint check build build-helper build-all install-local clean release-tag
+
+help:
+	@echo "procoder command runner"
+	@echo ""
+	@echo "Targets:"
+	@echo "  make fmt          - format Go files"
+	@echo "  make test         - run go test ./..."
+	@echo "  make vet          - run go vet ./..."
+	@echo "  make lint         - run Node script checks"
+	@echo "  make check        - fmt + test + vet + lint"
+	@echo "  make build        - build local binary to dist/procoder"
+	@echo "  make build-helper - build the linux/amd64 procoder-return helper asset"
+	@echo "  make build-all    - build release binaries for 5 target platforms plus helper asset"
+	@echo "  make install-local - install CLI and helper to ~/.local/bin"
+	@echo "  make clean        - remove dist artifacts"
+	@echo "  make release-tag  - create and push git tag (requires VERSION=x.y.z)"
+
+fmt:
+	@$(GOFMT) -w $$(find . -type f -name '*.go' -not -path './dist/*')
+
+test:
+	@$(GO) test ./...
+
+vet:
+	@$(GO) vet ./...
+
+lint:
+	@npm run lint
+
+check: fmt test vet lint
+
+build:
+	@mkdir -p $(DIST_DIR)
+	@$(GO) build -trimpath -ldflags="$(LDFLAGS)" -o $(BIN_PATH) $(CMD_PATH)
+
+build-helper:
+	@mkdir -p $(DIST_DIR)
+	@CGO_ENABLED=0 GOOS=$(HELPER_GOOS) GOARCH=$(HELPER_GOARCH) \
+		$(GO) build -trimpath -ldflags="$(LDFLAGS)" -o $(HELPER_PATH) $(HELPER_CMD_PATH)
+
+build-all: build-helper
+	@mkdir -p $(DIST_DIR)
+	@for target in "darwin amd64" "darwin arm64" "linux amd64" "linux arm64" "windows amd64"; do \
+		set -- $$target; \
+		GOOS=$$1; GOARCH=$$2; \
+		EXT=""; \
+		if [ "$$GOOS" = "windows" ]; then EXT=".exe"; fi; \
+		echo "Building $(BIN_NAME) for $$GOOS/$$GOARCH"; \
+		CGO_ENABLED=0 GOOS=$$GOOS GOARCH=$$GOARCH $(GO) build -trimpath -ldflags="$(LDFLAGS)" -o "$(DIST_DIR)/$(BIN_NAME)_$$GOOS_$$GOARCH$$EXT" $(CMD_PATH); \
+	done
+
+install-local: build build-helper
+	@mkdir -p $$HOME/.local/bin
+	@install -m 755 $(BIN_PATH) $$HOME/.local/bin/$(BIN_NAME)
+	@install -m 755 $(HELPER_PATH) $$HOME/.local/bin/$(HELPER_ASSET)
+	@echo "Installed $(BIN_NAME) to $$HOME/.local/bin/$(BIN_NAME)"
+	@echo "Installed $(HELPER_ASSET) to $$HOME/.local/bin/$(HELPER_ASSET)"
+
+clean:
+	@rm -rf $(DIST_DIR)
+
+release-tag:
+	@test -n "$(VERSION)" || (echo "Usage: make release-tag VERSION=x.y.z" && exit 1)
+	@git tag "v$(VERSION)"
+	@git push origin "v$(VERSION)"

package/README.md

@@ -0,0 +1,125 @@
+# procoder
+
+`procoder` is a Go CLI for an offline Git exchange workflow between:
+
+- a local developer repository
+- a locked-down ChatGPT coding container
+
+The default round trip is:
+
+1. Run `procoder prepare` in a clean local repository.
+2. Upload `./procoder-task-<exchange-id>.zip` to ChatGPT.
+3. Work inside the exported repo, commit on the prepared task branch, and run `./procoder-return`.
+4. Download `./procoder-return-<exchange-id>.zip`.
+5. Run `procoder apply <return-package.zip>` in the source repository.
+
+## Install
+
+Global install via npm:
+
+```bash
+npm i -g procoder-cli
+procoder --help
+```
+
+The installer fetches two release assets when available:
+
+- the host `procoder` binary
+- the packaged `linux/amd64` `procoder-return` helper used inside prepared task packages
+
+If those release assets are unavailable, `scripts/postinstall.js` falls back to local Go builds for both binaries.
+
+## Workflow
+
+### `procoder prepare`
+
+Run `procoder prepare` from the root of a clean Git worktree:
+
+```bash
+procoder prepare
+```
+
+`prepare` does the following:
+
+- validates that the repo is clean and has no untracked files, submodules, or Git LFS usage
+- creates a local task branch at `refs/heads/procoder/<exchange-id>/task`
+- writes the local exchange record to `.git/procoder/exchanges/<exchange-id>/exchange.json`
+- builds a sanitized export repo that includes local heads and tags for read-only context
+- injects the `procoder-return` helper at the exported repo root
+- writes `./procoder-task-<exchange-id>.zip` in the source repo root
+
+The current checkout is left unchanged. On success the command prints the task branch ref and the absolute task package path.
+
+### `./procoder-return`
+
+After ChatGPT has made one or more commits inside the exported repo, run the helper from that prepared task package:
+
+```bash
+./procoder-return
+```
+
+The helper:
+
+- verifies that it is running inside a prepared task package
+- rejects dirty worktrees, tag changes, and branch changes outside `refs/heads/procoder/<exchange-id>/*`
+- bundles only task-family refs that descend from the prepared base commit
+- writes `./procoder-return-<exchange-id>.zip` at the repo root
+
+On success it prints the absolute zip path and a `sandbox:` hint that can be pasted back to the local user.
+
+### `procoder apply`
+
+Apply the returned work from the original source repo:
+
+```bash
+procoder apply procoder-return-<exchange-id>.zip
+```
+
+Supported flags:
+
+- `--dry-run`: verify the return package and print the ref update plan without mutating refs
+- `--namespace <prefix>`: import returned refs under `refs/heads/<prefix>/<exchange-id>/...`
+- `--checkout`: check out the updated default task branch after a successful apply
+
+Examples:
+
+```bash
+procoder apply procoder-return-<exchange-id>.zip
+procoder apply procoder-return-<exchange-id>.zip --dry-run
+procoder apply procoder-return-<exchange-id>.zip --namespace procoder-import
+procoder apply procoder-return-<exchange-id>.zip --checkout
+```
+
+Default apply behavior is "update when safe, otherwise fail." If the prepared task branch moved locally, `procoder apply` fails with a `BRANCH_MOVED` error and suggests retrying with `--namespace`.
+
+## Command Summary
+
+```bash
+procoder --help
+procoder prepare
+procoder apply <return-package.zip>
+procoder apply <return-package.zip> --dry-run
+procoder apply <return-package.zip> --namespace <prefix>
+procoder apply <return-package.zip> --checkout
+procoder version
+```
+
+## Development
+
+Common local commands:
+
+```bash
+make fmt
+make test
+make vet
+make lint
+make check
+make build
+make build-helper
+make build-all
+make install-local
+```
+
+`make build-all` produces the release binaries for the host CLI targets plus the packaged helper asset `procoder-return_linux_amd64`.
+
+See [AGENTS.md](AGENTS.md) and [CONTRIBUTORS.md](CONTRIBUTORS.md) for implementation and release details.

package/bin/procoder.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pkg = require("../package.json");
+const cliName = pkg.config?.cliBinaryName || "procoder";
+const executableName = process.platform === "win32" ? `${cliName}.exe` : `${cliName}-bin`;
+const executablePath = path.join(__dirname, executableName);
+
+if (!fs.existsSync(executablePath)) {
+  console.error(`${cliName} binary is not installed. Re-run: npm rebuild -g ${pkg.name}`);
+  process.exit(1);
+}
+
+const child = spawnSync(executablePath, process.argv.slice(2), { stdio: "inherit" });
+
+if (child.error) {
+  console.error(child.error.message);
+  process.exit(1);
+}
+
+if (child.signal) {
+  process.kill(process.pid, child.signal);
+}
+
+process.exit(child.status ?? 1);

package/cmd/procoder/main.go

@@ -0,0 +1,15 @@
+package main
+
+import (
+	"os"
+
+	"github.com/amxv/procoder/internal/app"
+	"github.com/amxv/procoder/internal/output"
+)
+
+func main() {
+	if err := app.Run(os.Args[1:], os.Stdout, os.Stderr); err != nil {
+		output.WriteError(os.Stderr, err)
+		os.Exit(1)
+	}
+}

package/cmd/procoder-return/main.go

@@ -0,0 +1,67 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/amxv/procoder/internal/errs"
+	"github.com/amxv/procoder/internal/output"
+	"github.com/amxv/procoder/internal/returnpkg"
+)
+
+var version = "dev"
+var runReturn = returnpkg.Run
+
+func main() {
+	if err := run(os.Args[1:], os.Stdout, os.Stderr); err != nil {
+		output.WriteError(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(args []string, stdout, stderr io.Writer) error {
+	_ = stderr
+
+	if len(args) > 0 && isHelpArg(args[0]) {
+		printHelp(stdout)
+		return nil
+	}
+	if len(args) > 0 {
+		return errs.New(
+			errs.CodeUnknownCommand,
+			fmt.Sprintf("unknown argument %q for `procoder-return`", args[0]),
+			errs.WithHint("run `procoder-return --help`"),
+		)
+	}
+
+	result, err := runReturn(returnpkg.Options{ToolVersion: version})
+	if err != nil {
+		return err
+	}
+	_, _ = fmt.Fprintln(stdout, returnpkg.FormatSuccess(result))
+	return nil
+}
+
+func printHelp(w io.Writer) {
+	lines := []string{
+		"procoder-return - create a return package",
+		"",
+		"Usage:",
+		"  procoder-return",
+		"",
+		"This command creates a return package inside a prepared task package.",
+	}
+	for _, line := range lines {
+		_, _ = io.WriteString(w, line+"\n")
+	}
+}
+
+func isHelpArg(v string) bool {
+	switch v {
+	case "-h", "--help", "help":
+		return true
+	default:
+		return false
+	}
+}

package/cmd/procoder-return/main_test.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/amxv/procoder/internal/errs"
+	"github.com/amxv/procoder/internal/returnpkg"
+)
+
+func TestPrintHelpTerminology(t *testing.T) {
+	var out bytes.Buffer
+	printHelp(&out)
+
+	got := out.String()
+	if !strings.Contains(got, "return package") {
+		t.Fatalf("expected return package terminology, got: %q", got)
+	}
+	if !strings.Contains(got, "prepared task package") {
+		t.Fatalf("expected prepared task package terminology, got: %q", got)
+	}
+	if strings.Contains(got, "remote handoff flow") {
+		t.Fatalf("unexpected stale wording in help output, got: %q", got)
+	}
+}
+
+func TestRunSuccessOutputIncludesSandboxHint(t *testing.T) {
+	originalRunReturn := runReturn
+	t.Cleanup(func() {
+		runReturn = originalRunReturn
+	})
+
+	runReturn = func(opts returnpkg.Options) (returnpkg.Result, error) {
+		if opts.ToolVersion == "" {
+			t.Fatal("expected tool version in returnpkg options")
+		}
+		return returnpkg.Result{
+			ExchangeID:        "20260320-120000-a1b2c3",
+			ReturnPackagePath: "/tmp/procoder-return-20260320-120000-a1b2c3.zip",
+		}, nil
+	}
+
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	if err := run(nil, &out, &errBuf); err != nil {
+		t.Fatalf("run returned error: %v", err)
+	}
+	got := out.String()
+	if !strings.Contains(got, "Created return package.") {
+		t.Fatalf("expected success header, got %q", got)
+	}
+	if !strings.Contains(got, "/tmp/procoder-return-20260320-120000-a1b2c3.zip") {
+		t.Fatalf("expected absolute return package path, got %q", got)
+	}
+	if !strings.Contains(got, "sandbox:/tmp/procoder-return-20260320-120000-a1b2c3.zip") {
+		t.Fatalf("expected sandbox hint output, got %q", got)
+	}
+}
+
+func TestRunUnknownArgument(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := run([]string{"unexpected"}, &out, &errBuf)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	typed, ok := errs.As(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if typed.Code != errs.CodeUnknownCommand {
+		t.Fatalf("unexpected code: got %s want %s", typed.Code, errs.CodeUnknownCommand)
+	}
+}

package/go.mod

@@ -0,0 +1,3 @@
+module github.com/amxv/procoder
+
+go 1.26