@afix-ci/cli-linux-x64 0.1.0-rc.31 → 0.1.0-rc.38

package/README.md

@@ -2,6 +2,72 @@
 
 A simple tool for running scripts and correcting their outputs
 
+## Prepare a pull request
+
+`afix prepare-pr` updates the current branch with the selected remote's
+advertised default branch, resolves configured smart-merge conflicts, runs
+repository setup and the normal afix fix loop, then submits the result. The
+working tree must be clean and HEAD must be attached to a local branch.
+`--forge` and `--submit-method` are required:
+
+```sh
+afix prepare-pr \
+  --forge github \
+  --submit-method dependent-pr \
+  --git-remote origin
+```
+
+By default, preparation mutates the current checkout. Use `--worktree` to
+prepare on a new afix-prefixed branch in a unique sibling worktree, leaving the
+current checkout unchanged:
+
+```sh
+afix prepare-pr --worktree \
+  --forge github \
+  --submit-method dependent-pr
+```
+
+Add `--swap-branch` when the submitted branch must retain the current branch
+name. This option requires `--worktree`: the host checkout moves to
+`<current-branch>-pre-pr-backup`, while the submission worktree checks out the
+original branch without changing its upstream tracking configuration.
+
+Failures before submission do not push or open a pull request. In worktree
+modes, the prepared checkout is retained; failures print its path for
+inspection. Swap setup is transactional, but after setup succeeds its backup
+branch is intentionally retained.
+
+### Repository preparation commands
+
+An optional `[submit]` section can replace the built-in merge and run setup
+after the upstream merge has been resolved:
+
+```toml
+[submit]
+pull_command = "git pull --no-edit origin main"
+setup_command = "yarn install --immutable"
+```
+
+Commands run directly in the prepared checkout without an implicit shell.
+They also accept the full command form for explicit arguments and environment:
+
+```toml
+[submit.pull_command]
+bin = "git"
+args = ["pull", "--no-edit", "origin", "main"]
+
+[submit.setup_command]
+bin = "yarn"
+args = ["install", "--immutable"]
+env = { CI = "true" }
+```
+
+`pull_command` runs instead of the built-in merge, but afix still fetches the
+advertised default target first and verifies that the command incorporated its
+exact commit. `setup_command` runs only after a clean merge and before afix
+loads validators and fixers. Relative binary paths are resolved within the
+prepared checkout.
+
 ## Useful Commands
 
 ```sh
@@ -11,7 +77,15 @@ afix autoclass ado-init
 afix autoclass pull-logs --count=500
 # run metrics to generate graphs and csv to ./afix-metrics
 afix autoclass metrics
+# render previously computed dwell history without scanning logs or reading Git
+afix autoclass metrics --metrics-provider=static
 # pull unique PR ids from metrics csv
 cat afix-metrics/build-history.csv | python3 -c 'import csv,sys; seen=set(); [print(r["pr_id"]) for r in csv.DictReader(sys.stdin) if r["is_open"]=="true" and r["fixable"]=="true" and r["is_safe_submit"]=="true" and not (r["pr_id"] in seen or seen.add(r["pr_id"]))]' > afix-metrics/safe-pr-ids.log
 # fix all, sequentially
 ```
+
+Metrics reports always use the current afix and smart-merge configuration.
+Compute and `pull-logs` runs populate config-keyed build classification history
+and commit-OID-keyed closure/token-usage facts in the shared SQLite cache.
+Static reports read only those cached historical inputs; a build without
+classification history for the current config is charted as `Unavailable`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afix-ci/cli-linux-x64",
-  "version": "0.1.0-rc.31",
+  "version": "0.1.0-rc.38",
   "license": "MIT",
   "os": [
     "linux"