procoder-cli 0.1.1 → 0.1.3

package/CONTRIBUTORS.md

@@ -11,6 +11,24 @@ Maintainer notes for this template repository.
 
 ## Local 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`.
+
+Quick local smoke path:
+
 ```bash
 make check
 make build

package/Makefile

@@ -12,7 +12,8 @@ HELPER_CMD_PATH ?= ./cmd/$(HELPER_NAME)
 DIST_DIR ?= dist
 BIN_PATH ?= $(DIST_DIR)/$(BIN_NAME)
 HELPER_PATH ?= $(DIST_DIR)/$(HELPER_ASSET)
-LDFLAGS ?= -s -w
+VERSION ?= $(shell node -p "require('./package.json').version" 2>/dev/null)
+LDFLAGS ?= -s -w -X github.com/amxv/procoder/internal/buildinfo.Version=$(if $(VERSION),$(VERSION),dev)
 
 .PHONY: help fmt test vet lint check build build-helper build-all install-local clean release-tag
 

package/README.md

@@ -1,125 +1,145 @@
 # procoder
 
-`procoder` is a Go CLI for an offline Git exchange workflow between:
+`procoder` is a CLI for getting real Git commits back from ChatGPT's coding sandbox.
 
-- a local developer repository
-- a locked-down ChatGPT coding container
+ChatGPT 5.4 Pro is the best coding model, but it is not available in Codex. `procoder` solves that specific problem: your repository stays local, ChatGPT works inside its locked-down sandbox, and you still get real commits back through a clean upload/download workflow powered by `git bundle`.
 
-The default round trip is:
+The workflow is simple:
 
-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.
+1. You run `procoder prepare` and upload the generated zip.
+2. ChatGPT works inside that package and gives you an optimized incremental Git bundle as a zip file.
+3. You run `procoder apply`, which applies the commit ChatGPT made.
+
+It is Git-native, not a patch-copying workaround.
 
 ## Install
 
-Global install via npm:
+Install globally with npm:
 
 ```bash
 npm i -g procoder-cli
 procoder --help
 ```
 
-The installer fetches two release assets when available:
+## Quick Start
+
+```bash
+procoder prepare
+```
 
-- the host `procoder` binary
-- the packaged `linux/amd64` `procoder-return` helper used inside prepared task packages
+Upload the generated task package to ChatGPT and give it a prompt like:
 
-If those release assets are unavailable, `scripts/postinstall.js` falls back to local Go builds for both binaries.
+```text
+Make the requested changes in this repository.
 
-## Workflow
+Commit them on the prepared branch.
 
-### `procoder prepare`
+Then run ./procoder-return and give me the sandbox path to the generated zip.
+```
 
-Run `procoder prepare` from the root of a clean Git worktree:
+After downloading the return package locally:
 
 ```bash
-procoder prepare
+procoder apply procoder-return-<exchange-id>.zip
 ```
 
-`prepare` does the following:
+If you want to inspect the import first:
 
-- 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
+```bash
+procoder apply procoder-return-<exchange-id>.zip --dry-run
+```
 
-The current checkout is left unchanged. On success the command prints the task branch ref and the absolute task package path.
+## Why `git bundle` is the right primitive
 
-### `./procoder-return`
+`git bundle` is what makes this workflow feel native instead of fragile.
 
-After ChatGPT has made one or more commits inside the exported repo, run the helper from that prepared task package:
+It lets `procoder` move Git commits, trees, blobs, and refs as a portable file, without requiring a network connection or a Git server. That matters because the ChatGPT sandbox can work with Git locally, but it cannot push to your remote.
 
-```bash
-./procoder-return
+Using an incremental bundle also keeps the return package small. The sandbox sends back only the objects created after `prepare`, not the whole repository again.
+
+## Workflow Diagram
+
+```mermaid
+flowchart TD
+    A[Local Git repo] -->|procoder prepare| B[Task zip]
+    B -->|Upload to ChatGPT| C[ChatGPT codes, commits on the prepared branch,<br/>and runs the included ./procoder-return binary]
+    C -->|Download return zip and run procoder apply| D[Local task branch updated]
 ```
 
-The helper:
+## The Three Tools
+
+### `procoder prepare`
 
-- 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
+Runs locally in your clean repository.
 
-On success it prints the absolute zip path and a `sandbox:` hint that can be pasted back to the local user.
+It creates a dedicated task branch, builds a sanitized export of your repo, injects the `procoder-return` helper, and writes a task zip you can upload to ChatGPT.
+
+### `./procoder-return`
+
+Runs inside the exported repository in the ChatGPT sandbox.
+
+It is a simple agent-friendly binary with no arguments or subcommands. After making one or more commits, the agent runs `./procoder-return`, and then sends back the path to the generated zip file.
 
 ### `procoder apply`
 
-Apply the returned work from the original source repo:
+Runs locally in your original repository.
 
-```bash
-procoder apply procoder-return-<exchange-id>.zip
-```
+It verifies the returned bundle, checks whether the target refs are still safe to update, and then imports the returned commits into your repo.
 
-Supported flags:
+## How it works under the hood
 
-- `--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
+At a high level, `procoder` works because it ships Git history into the sandbox and ships only new Git history back out.
 
-Examples:
+### 1. `prepare` makes an offline-capable repo
 
-```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
-```
+The task package is a sanitized Git repository, not just a folder of files.
 
-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`.
+That export:
 
-## Command Summary
+- includes your tracked files
+- includes local branches and tags for read-only context
+- creates a dedicated task branch for the exchange
+- strips remotes, credentials, hooks, reflogs, and other local-only Git state
+- includes a Linux `procoder-return` helper binary at the repo root
 
-```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
-```
+So when ChatGPT opens the zip, it already has a working repo with real history and a branch ready to commit on. No internet connection is required for that part because the relevant Git state is already inside the upload.
 
-## Development
+### 2. ChatGPT returns only the incremental update
 
-Common local commands:
+After ChatGPT commits its changes, `./procoder-return` does not re-export the entire repository.
 
-```bash
-make fmt
-make test
-make vet
-make lint
-make check
-make build
-make build-helper
-make build-all
-make install-local
-```
+Instead, it creates:
+
+- `procoder-return.json`
+  a small manifest describing the returned refs and commit IDs
+- `procoder-return.bundle`
+  an incremental Git bundle containing only the new objects needed to move those refs forward
+
+That is the key idea. The return package is a portable Git layer that can be applied on top of the base commit prepared earlier.
+
+### 3. `apply` verifies before it updates anything
+
+When you run `procoder apply`, the CLI verifies the bundle, imports it into a temporary namespace, checks that the imported refs match the manifest, and only then updates your local task branch when it is safe.
+
+If the branch moved locally, or the return package tries to update something outside the allowed exchange branch family, `procoder` fails clearly instead of guessing.
+
+That gives you the practical feeling of "ChatGPT committed to my repo", while still keeping the operation local and controlled.
+
+## Current V1 Constraints
+
+The happy path is intentionally narrow:
+
+- run `procoder prepare` from a clean repo
+- no Git LFS support
+- no submodule support
+- returned work must stay inside the prepared exchange branch family
+- tag changes are not part of the V1 return flow
+
+Those constraints keep the round trip predictable and let `apply` behave like "update when safe, otherwise fail."
 
-`make build-all` produces the release binaries for the host CLI targets plus the packaged helper asset `procoder-return_linux_amd64`.
+## Docs
 
-See [AGENTS.md](AGENTS.md) and [CONTRIBUTORS.md](CONTRIBUTORS.md) for implementation and release details.
+- [How It Works](docs/how-it-works.md)
+- [Command Reference](docs/commands.md)
+- [Agent Guidance](AGENTS.md)
+- [Maintainer Notes](CONTRIBUTORS.md)

package/cmd/procoder-return/main.go

@@ -5,12 +5,13 @@ import (
 	"io"
 	"os"
 
+	"github.com/amxv/procoder/internal/buildinfo"
 	"github.com/amxv/procoder/internal/errs"
 	"github.com/amxv/procoder/internal/output"
 	"github.com/amxv/procoder/internal/returnpkg"
 )
 
-var version = "dev"
+var version = buildinfo.CurrentVersion()
 var runReturn = returnpkg.Run
 
 func main() {

package/internal/app/app.go

@@ -6,13 +6,14 @@ import (
 	"strings"
 
 	"github.com/amxv/procoder/internal/apply"
+	"github.com/amxv/procoder/internal/buildinfo"
 	"github.com/amxv/procoder/internal/errs"
 	"github.com/amxv/procoder/internal/prepare"
 )
 
 const commandName = "procoder"
 
-var version = "dev"
+var version = buildinfo.CurrentVersion()
 var runPrepare = prepare.Run
 var runApplyDryRun = apply.RunDryRun
 var runApply = apply.Run
@@ -24,11 +25,12 @@ func Run(args []string, stdout, stderr io.Writer) error {
 		printRootHelp(stdout)
 		return nil
 	}
-
-	switch args[0] {
-	case "version":
+	if len(args) == 1 && isVersionArg(args[0]) {
 		_, _ = fmt.Fprintf(stdout, "%s %s\n", commandName, version)
 		return nil
+	}
+
+	switch args[0] {
 	case "prepare":
 		if len(args) > 1 && isHelpArg(args[1]) {
 			printPrepareHelp(stdout)
@@ -172,22 +174,26 @@ func isHelpArg(v string) bool {
 	}
 }
 
+func isVersionArg(v string) bool {
+	return v == "--version"
+}
+
 func printRootHelp(w io.Writer) {
 	writeLines(w,
 		"procoder",
 		"",
 		"Usage:",
+		"  procoder [--version]",
 		"  procoder <command> [arguments]",
 		"",
 		"Commands:",
 		"  prepare                        create a task package",
 		"  apply <return-package.zip>     apply a return package",
-		"  version                        print CLI version",
 		"",
 		"Examples:",
+		"  procoder --version",
 		"  procoder prepare",
 		"  procoder apply procoder-return-<exchange-id>.zip --dry-run",
-		"  procoder version",
 	)
 }
 

package/internal/app/app_test.go

@@ -31,7 +31,7 @@ func TestRunVersion(t *testing.T) {
 	var out bytes.Buffer
 	var errBuf bytes.Buffer
 
-	err := Run([]string{"version"}, &out, &errBuf)
+	err := Run([]string{"--version"}, &out, &errBuf)
 	if err != nil {
 		t.Fatalf("Run returned error: %v", err)
 	}
@@ -41,6 +41,27 @@ func TestRunVersion(t *testing.T) {
 	}
 }
 
+func TestRunVersionSubcommandUnknown(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"version"}, &out, &errBuf)
+	if err == nil {
+		t.Fatal("expected error for removed version subcommand")
+	}
+
+	typed, ok := errs.As(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if typed.Code != errs.CodeUnknownCommand {
+		t.Fatalf("unexpected error code: %s", typed.Code)
+	}
+	if !strings.Contains(typed.Message, "unknown command") {
+		t.Fatalf("expected unknown command message, got %q", typed.Message)
+	}
+}
+
 func TestRunApplyHelpTerminology(t *testing.T) {
 	var out bytes.Buffer
 	var errBuf bytes.Buffer

package/internal/buildinfo/buildinfo.go

@@ -0,0 +1,16 @@
+package buildinfo
+
+import "strings"
+
+const defaultVersion = "dev"
+
+// Version is overridden at build time via linker flags.
+var Version = defaultVersion
+
+func CurrentVersion() string {
+	trimmed := strings.TrimSpace(Version)
+	if trimmed == "" {
+		return defaultVersion
+	}
+	return trimmed
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procoder-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Offline Git exchange CLI for local repositories and locked-down ChatGPT coding containers",
   "license": "MIT",
   "author": "amxv",

package/scripts/postinstall.js

@@ -60,6 +60,11 @@ function buildReleaseAssetURL({ repoOwner, repoName, version, assetName }) {
   return `https://github.com/${repoOwner}/${repoName}/releases/download/v${version}/${assetName}`;
 }
 
+function buildLdflags(version) {
+  const resolvedVersion = `${version || ""}`.trim() || "dev";
+  return `-s -w -X github.com/amxv/procoder/internal/buildinfo.Version=${resolvedVersion}`;
+}
+
 function buildInstallPlan({
   pkg,
   cliName,
@@ -167,6 +172,7 @@ function fallbackBuildOrExit(plan) {
 }
 
 function buildFallbackBuilds(plan) {
+  const ldflags = buildLdflags(plan.version);
   return [
     {
       destination: plan.cli.destination,
@@ -174,7 +180,7 @@ function buildFallbackBuilds(plan) {
       args: [
         "build",
         "-trimpath",
-        '-ldflags=-s -w',
+        `-ldflags=${ldflags}`,
         "-o",
         plan.cli.destination,
         `./cmd/${plan.cli.name}`
@@ -190,7 +196,7 @@ function buildFallbackBuilds(plan) {
       args: [
         "build",
         "-trimpath",
-        '-ldflags=-s -w',
+        `-ldflags=${ldflags}`,
         "-o",
         plan.helper.destination,
         `./cmd/${plan.helper.name}`
@@ -245,6 +251,7 @@ function downloadToFile(url, destinationPath) {
 
 module.exports = {
   buildFallbackBuilds,
+  buildLdflags,
   buildInstallPlan,
   buildReleaseAssetName,
   buildReleaseAssetURL,