deploying-local-arch-packages

name	deploying-local-arch-packages
description	Use when Arch package changes need a host handoff, rebuild, publish, install, deploy, reinstall, downgrade, local pacman repo refresh, or post-change package verification in this repo.

Deploying Local Arch Packages

Use tools/amerge as the canonical repo-side host workflow for merge planning, rebuild, publish, install, resume, history, and logs.

This repo's local pacman target is strix-halo-gfx1151, published at /srv/pacman/strix-halo-gfx1151/x86_64. Do not use the sibling arch-pkgs repo target nisavid or /srv/pacman/nisavid/x86_64 for Strix Halo package artifacts.

Completion Rule

Host deployment is only the host-mutation phase. If the package lane changed tracked repo files, PKGBUILDs, generated outputs, docs, policy, or ledgers, the broader package-update task is not complete until the topic branch has gone through $yeet, GitHub checks/review, and merge, or until a real blocker is documented.

When package files, PKGBUILDs, repo metadata, or package versions changed and the privileged host mutation was not run, the final response must include the exact tools/amerge ... handoff command.

Before handing off a package lane, run the strongest non-privileged command yourself. For build -> deploy flows, complete tools/amerge build ... autonomously when the required build dependencies are already available, then hand off only the narrow tools/amerge deploy ... command when privileged publish/install remains.

Default broad package flow when installed repo packages are affected:

tools/amerge build --installed

Then hand off only the privileged publish/install step if it remains:

tools/amerge deploy --installed

If package artifacts are already built and only publish/install remains:

tools/amerge deploy <package-root>...

If the user wants to inspect the privileged commands first:

tools/amerge deploy --installed --preview=commands

Command Selection

• Narrow package lane:

tools/amerge run python-amd-aiter-gfx1151 python-vllm-rocm-gfx1151

• Include dependencies:

tools/amerge run --deps python-amd-aiter-gfx1151 python-vllm-rocm-gfx1151

• Rebuild all repo roots:

tools/amerge run --all

• Resume a failed run:

tools/amerge resume latest

• Deploy already-built package artifacts:

tools/amerge deploy python-amd-aiter-gfx1151 python-vllm-rocm-gfx1151

Inspect retained state with tools/amerge history and tools/amerge logs latest --path. Use --preview=tree --color=always when the user wants a colorized plan captured in logs or chat.

Operator Notes

• Own the unprivileged prepare/build/check phase for any similarly shaped workflow. User handoff starts at the first genuinely privileged or user-owned mutation step, not at an earlier convenient boundary.
• Do not hand build or broad run commands to the user when the remaining build step is unprivileged and agent-runnable. Complete the build first.
• Hand publish, install, and deploy commands to the user only when privileged host mutation is needed and you cannot run it from the current environment.
• When artifacts are built but host mutation is pending, close with the exact tools/amerge deploy ... command. Do not leave the deployment step implicit.
• Handoffs must be convenient: include cd <worktree>, the exact command, and the hand-back signal, then run the documented verification yourself after the user reports completion.
• After the user reports the privileged command has completed, run the applicable pacman -Q ... and smoke checks yourself when the host is accessible. Ask the user to run verification only when you cannot perform it from the current environment.
• tools/amerge build ... is intentionally unprivileged and should be usable autonomously when package build dependencies are already installed. If makepkg needs missing dependencies, handle that as a host setup blocker rather than warming sudo up front.
• The tool validates sudo once for plans containing privileged steps, keeps the sudo validation timestamp fresh, runs privileged commands with noninteractive sudo, and logs under docs/worklog/amerge/<plan-id>/.
• With run, each package root is built and published immediately. Rebuilt repo outputs are installed in prerequisite transactions when the next build group needs them via depends or makedepends, and remaining selected outputs are installed in a final transaction.
• Publish steps require package archives matching the current PKGBUILD makepkg --packagelist, so stale built artifacts fail before republishing.
• A --require-packagelist publish treats current PKGBUILD outputs as authoritative for their package names and preserves unrelated repo packages.
• A plan holds active.lock while running; do not start a second resume or run against the same plan if history reports it active.
• If no targets or selectors are given, hand the command to the user only for an interactive session; noninteractive use should pass targets, --all, or --installed.
• For the common rebuild -> install -> test flow, follow with python tools/run_inference_scenarios.py ....
• If shell glue is still needed around this Python CLI, use the idiomatic-zsh skill.