Add allod patch subcommand #77

New issue

Closed

opened 2026-06-29 20:18:11 +01:00 by vnprc-agent · 0 comments

vnprc-agent commented

2026-06-29 20:18:11 +01:00

Contributor

Goal

Add allod workflow helpers for handing public repository commits from a private-capable dev VM to a public-authorized checkout without copying working trees or granting one environment both capabilities.

Background

Some development sessions can read private local context but are intentionally not allowed to push public Allod repositories. The manual workaround is to leave a local commit ahead of origin, export a patch, transfer it to a public-authorized host, apply it, review it, and push. This should be a small scripted workflow so agents can produce a precise handoff artifact and humans can apply it consistently.

The preferred UX should not require the human to SSH into the dev VM, run one command, exit, and then run another command on the host. The public-authorized host should orchestrate the workflow: connect to the source VM over SSH, generate the patch artifact from the source checkout, pull only that artifact back, then apply/review it in the destination checkout.

Proposed interface

Add host-side subcommands, names can change if the existing CLI shape suggests better wording:

allod patch fetch <ssh-host>:<source-repo> [--base origin/master] [--output <dir>]
allod patch apply <manifest-or-dir> [--push]
allod patch receive <ssh-host>:<source-repo> <destination-repo> [--base origin/master] [--push]

fetch runs on the public-authorized host. It SSHes into the source dev VM and generates the handoff artifact from the source repo checkout:

require the source repo worktree to be clean;
require the source branch to be ahead of the chosen base;
run git format-patch for <base>..HEAD in a temporary artifact directory on the source VM;
write a manifest with repo identity, remote URL, base commit, head commit, patch count, patch filenames, and sha256s;
transfer only the patch files and manifest back to the host;
remove the temporary source-side artifact directory unless --keep-remote-artifact is explicitly requested;
print a concise handoff summary and the local artifact path.

apply runs on the public-authorized host in or against the destination repo checkout:

require a clean destination worktree;
verify the repo identity and remote match the manifest;
verify patch sha256s;
verify the manifest base is reachable or explain the mismatch clearly;
apply with git am --3way;
run git diff --check against the applied range;
show git log --oneline <base>..HEAD and git show --stat --oneline HEAD;
leave git push to the human by default. --push may exist, but should be explicit.

receive is the smooth-path wrapper that runs fetch and then apply from the public-authorized host. It should still stop before push unless --push is explicit.

Transfer model

The public-authorized host pulls a generated artifact from the source dev VM. The artifact is committed changes only: patches plus manifest.

Implementation can use scp for the generated artifact directory, or stream a tar archive over SSH if that is simpler and robust. In either case:

do not copy working trees;
do not use rsync;
do not transfer uncommitted files;
do not transfer tokens, secrets, or credential files;
keep the remote command narrow: Git metadata, git format-patch, manifest/checksum generation, and artifact cleanup.

Example happy path:

# On the public-authorized host only:
allod patch receive dev-vm:/home/user/work/allod/memory /home/user/work/allod/memory

cd /home/user/work/allod/memory
git show --stat --oneline HEAD
git push

Acceptance criteria

Unit or integration tests cover successful host-side fetch, dirty source worktree rejection, no-commits-to-export rejection, manifest checksum verification, wrong-destination-repo rejection, and successful git am --3way apply.
The workflow works for a single patch and multiple patches.
The smooth path can be run entirely from the public-authorized host.
The apply/receive commands do not push unless explicitly requested.
Error messages are actionable enough for a human to fix the handoff without reading the implementation.
Documentation includes a short example for host-side receive, review, and push, plus a lower-level fetch/apply example for debugging.

Non-goals

No token, secret, or credential transfer.
No copying full checkouts or uncommitted working tree state.
No automatic bypass of public repo authorization boundaries.
No PR body or validation-heading enforcement.

## Goal Add `allod` workflow helpers for handing public repository commits from a private-capable dev VM to a public-authorized checkout without copying working trees or granting one environment both capabilities. ## Background Some development sessions can read private local context but are intentionally not allowed to push public Allod repositories. The manual workaround is to leave a local commit ahead of origin, export a patch, transfer it to a public-authorized host, apply it, review it, and push. This should be a small scripted workflow so agents can produce a precise handoff artifact and humans can apply it consistently. The preferred UX should not require the human to SSH into the dev VM, run one command, exit, and then run another command on the host. The public-authorized host should orchestrate the workflow: connect to the source VM over SSH, generate the patch artifact from the source checkout, pull only that artifact back, then apply/review it in the destination checkout. ## Proposed interface Add host-side subcommands, names can change if the existing CLI shape suggests better wording: ```sh allod patch fetch <ssh-host>:<source-repo> [--base origin/master] [--output <dir>] allod patch apply <manifest-or-dir> [--push] allod patch receive <ssh-host>:<source-repo> <destination-repo> [--base origin/master] [--push] ``` `fetch` runs on the public-authorized host. It SSHes into the source dev VM and generates the handoff artifact from the source repo checkout: - require the source repo worktree to be clean; - require the source branch to be ahead of the chosen base; - run `git format-patch` for `<base>..HEAD` in a temporary artifact directory on the source VM; - write a manifest with repo identity, remote URL, base commit, head commit, patch count, patch filenames, and sha256s; - transfer only the patch files and manifest back to the host; - remove the temporary source-side artifact directory unless `--keep-remote-artifact` is explicitly requested; - print a concise handoff summary and the local artifact path. `apply` runs on the public-authorized host in or against the destination repo checkout: - require a clean destination worktree; - verify the repo identity and remote match the manifest; - verify patch sha256s; - verify the manifest base is reachable or explain the mismatch clearly; - apply with `git am --3way`; - run `git diff --check` against the applied range; - show `git log --oneline <base>..HEAD` and `git show --stat --oneline HEAD`; - leave `git push` to the human by default. `--push` may exist, but should be explicit. `receive` is the smooth-path wrapper that runs `fetch` and then `apply` from the public-authorized host. It should still stop before push unless `--push` is explicit. ## Transfer model The public-authorized host pulls a generated artifact from the source dev VM. The artifact is committed changes only: patches plus manifest. Implementation can use `scp` for the generated artifact directory, or stream a tar archive over SSH if that is simpler and robust. In either case: - do not copy working trees; - do not use rsync; - do not transfer uncommitted files; - do not transfer tokens, secrets, or credential files; - keep the remote command narrow: Git metadata, `git format-patch`, manifest/checksum generation, and artifact cleanup. Example happy path: ```sh # On the public-authorized host only: allod patch receive dev-vm:/home/user/work/allod/memory /home/user/work/allod/memory cd /home/user/work/allod/memory git show --stat --oneline HEAD git push ``` ## Acceptance criteria - Unit or integration tests cover successful host-side fetch, dirty source worktree rejection, no-commits-to-export rejection, manifest checksum verification, wrong-destination-repo rejection, and successful `git am --3way` apply. - The workflow works for a single patch and multiple patches. - The smooth path can be run entirely from the public-authorized host. - The apply/receive commands do not push unless explicitly requested. - Error messages are actionable enough for a human to fix the handoff without reading the implementation. - Documentation includes a short example for host-side receive, review, and push, plus a lower-level fetch/apply example for debugging. ## Non-goals - No token, secret, or credential transfer. - No copying full checkouts or uncommitted working tree state. - No automatic bypass of public repo authorization boundaries. - No PR body or validation-heading enforcement.