rollout-cli 0.3.2__tar.gz → 0.4.1__tar.gz

rollout_cli-0.4.1/.claude/skills/mass-update/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: mass-update
+type: command
+description: >
+  Propagate ONE deterministic change across many GitHub repos at once. Targets
+  are GitHub slugs (`owner/repo`), not local paths. For each target, mass-update
+  clones fresh into a scratch dir, applies a verbatim file drop (`--file`) or
+  anchored edit (`--edit`), and cleans up on exit. Default is PREVIEW (zero
+  outward effect); `--pr` pushes a branch, opens a PR, and files a companion
+  tracking issue. No LLM, no ask-colleague — increment 1 is deterministic only.
+  Triggers when the user says "mass update", "propagate this change across
+  repos", "apply X to all these repos", "roll this out to agentculture/foo", or
+  "relicense these repos". One call = one PR per repo; run it several times for
+  independent changes.
+---
+
+# mass-update — one deterministic change, many repos
+
+`mass-update` is a **deterministic** cross-repo propagator. It clones each target
+repo fresh into a scratch directory, applies verbatim file drops or anchored
+edits, and cleans up on exit. No LLM, no `ask-colleague`.
+
+## What changed
+
+mass-update previously drove `ask-colleague` against sibling local checkouts
+(worktrees, `colleague/<id>` branches, `--apply`/`--pr` landing). That flow is
+gone. The new mechanism:
+
+- **Targets are GitHub slugs** (`owner/repo`), not local paths. A local path is
+  rejected.
+- For each target it **clones fresh** into a gitignored scratch dir
+  (`.mass-update/clones/<owner>-<repo>/`) inside rollout-cli, branches off the
+  default branch, applies a deterministic change in the clone, and cleans the
+  clone up on exit (success or failure). `--keep-clone` retains it for debugging.
+- The cardinal rule: **rollout-cli never reaches beyond its own repo.** The
+  entire on-disk footprint stays inside rollout-cli; the only outward effects
+  are `git push` (the PR) and `/communicate` (the issue).
+- Increment 1 supports only deterministic ops: `--file` (verbatim) and
+  `--edit` (anchored unique-occurrence replace). Free-text described changes are
+  a deferred follow-up.
+
+## How to run
+
+```bash
+bash .claude/skills/mass-update/scripts/mass-update.sh \
+  --repos <owner/repo[,owner/repo...]> <ops> [--pr] [--keep-clone]
+```
+
+Run it from the rollout-cli repo root. `--repos` takes comma-separated GitHub
+slugs (e.g. `agentculture/widget-cli`).
+
+## Op shapes (combinable in one call)
+
+| Op | What it does |
+|----|--------------|
+| `--file DEST --from SRC` | Create/replace `DEST` in each clone with **exactly** `SRC`'s bytes (verbatim). Use this for content the model shouldn't regenerate — a `LICENSE`, a CI workflow, a config file. |
+| `--file DEST --content '...'` | Same, but the verbatim content is given inline. |
+| `--edit 'FILE: FIND => REPLACE'` | Replace the **unique** occurrence of `FIND` with `REPLACE` in `FILE`. Errors on 0 or >1 matches. Repeatable. |
+
+All ops given in one call are applied to each clone. At least one op is required.
+
+## Landing — preview or PR
+
+| Flag | Effect |
+|------|--------|
+| *(none)* | **PREVIEW.** Clone, apply ops, print diff, cleanup. **Zero outward effect.** Always start here. |
+| `--pr` | Clone, apply, commit, push, open PR, file a companion tracking issue via `communicate/scripts/post-issue.sh`, cleanup. Both the PR URL and issue URL are printed. |
+| `--keep-clone` | Retain the scratch clone on exit (debug). |
+
+## Worked example — propagate a LICENSE to a sibling repo
+
+Replace `agentculture/widget-cli`'s `LICENSE` with rollout-cli's own `LICENSE`,
+then open a PR and file a tracking issue:
+
+```bash
+bash .claude/skills/mass-update/scripts/mass-update.sh \
+  --repos agentculture/widget-cli \
+  --file LICENSE --from ./LICENSE \
+  --pr
+```
+
+Run it **without `--pr` first** to inspect the preview diff; re-run with `--pr`
+once the diff is correct.
+
+## Where it fits
+
+- **`rollout` engine** — deterministic recipes, reproducible, no model. Reach for
+  it for org-wide fan-out (`--org`) and exact, scriptable transforms.
+- **`mass-update`** — *this skill*: deterministic cross-repo propagation via
+  fresh clones, for verbatim file drops and anchored edits across a handful of
+  GitHub repos.
+
+## Honest limits
+
+- **Deterministic only (increment 1).** Free-text described changes are NOT
+  supported — they are a deferred follow-up that needs an `ask-colleague`
+  edit-in-place mode.
+- **One drive per target.** Each target succeeds or fails independently; a
+  non-zero exit means at least one target failed (others may have landed).
+  Re-run for the failures.
+- **Requires `gh` and `git`.** Both must be on PATH and authenticated
+  (`gh auth status` must succeed) before any clone begins.
+- **`--keep-clone`** retains the scratch directory for debugging; without it,
+  clones are cleaned up on both success and failure.
+
+## Provenance
+
+mass-update is a rollout-cli-local skill. The `cite, don't import` policy holds:
+downstream repos copy it, they don't symlink or depend on it.

rollout_cli-0.4.1/.claude/skills/mass-update/scripts/mass-update.sh

@@ -0,0 +1,410 @@
+#!/usr/bin/env bash
+#
+# mass-update — deterministic mass-update across GitHub repos.
+#
+# Clones each target repo into a scratch dir, applies deterministic ops,
+# and optionally opens a PR + tracking issue. No LLM, no ask-colleague.
+#
+set -euo pipefail
+
+usage() {
+    cat <<'EOF'
+mass-update — deterministic mass-update across GitHub repos.
+
+Usage:
+  mass-update --repos OWNER/REPO[,OWNER/REPO...] <ops> [--pr] [--keep-clone] [-h|--help]
+
+Ops (at least one required):
+  --file DEST --from SRC          Write DEST with verbatim bytes of SRC (relative to cwd).
+  --file DEST --content TEXT      Write DEST with verbatim TEXT.
+  --edit 'FILE: FIND => REPLACE'  Replace UNIQUE occurrence of FIND with REPLACE in FILE.
+
+Landing:
+  (default)  PREVIEW: clone, apply ops, print diff, cleanup. No push/PR/issue.
+  --pr       clone, apply, commit, push, open PR, file tracking issue, cleanup.
+  --keep-clone   Retain the scratch clone on exit (debug).
+
+Targets:
+  --repos a/b,c/d    Comma-separated GitHub slugs (owner/repo). Required.
+
+Other:
+  -h, --help         Show this help.
+EOF
+}
+
+# Guard a value-taking flag.
+need_value() {
+    [[ "$1" -ge 2 ]] || { echo "error: $2 requires a value" >&2; echo "hint: run 'mass-update --help'" >&2; exit 2; }
+}
+
+# ── defaults + accumulators ──────────────────────────────────────────────────
+REPOS_CSV=""
+FILE_DESTS=()
+FILE_KINDS=()
+FILE_SRCS=()
+FILE_CONTENTS=()
+EDITS=()
+DO_PR=0
+KEEP_CLONE=0
+PENDING_FILE=""
+
+_push_file() {
+    [[ -n "$PENDING_FILE" ]] || { echo "error: $([[ "$1" == "from" ]] && echo --from || echo --content) given before any --file DEST" >&2; exit 2; }
+    FILE_DESTS+=("$PENDING_FILE")
+    FILE_KINDS+=("$1")
+    if [[ "$1" == "from" ]]; then
+        FILE_SRCS+=("$2")
+        FILE_CONTENTS+=("")
+    else
+        FILE_SRCS+=("")
+        FILE_CONTENTS+=("$2")
+    fi
+    PENDING_FILE=""
+}
+
+# ── parse arguments ─────────────────────────────────────────────────────────
+POSITIONAL_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repos)
+            need_value "$#" "$1"
+            REPOS_CSV="$2"
+            shift 2
+            ;;
+        --file)
+            need_value "$#" "$1"
+            [[ -z "$PENDING_FILE" ]] || { echo "error: --file $PENDING_FILE has no --from/--content before the next --file" >&2; exit 2; }
+            PENDING_FILE="$2"
+            shift 2
+            ;;
+        --from)
+            need_value "$#" "$1"
+            _push_file from "$2"
+            shift 2
+            ;;
+        --content)
+            need_value "$#" "$1"
+            _push_file content "$2"
+            shift 2
+            ;;
+        --edit)
+            need_value "$#" "$1"
+            EDITS+=("$2")
+            shift 2
+            ;;
+        --pr)
+            DO_PR=1
+            shift
+            ;;
+        --keep-clone)
+            KEEP_CLONE=1
+            shift
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        -*)
+            echo "error: unknown option '$1'" >&2
+            echo "hint: run 'mass-update --help'" >&2
+            exit 2
+            ;;
+        *)
+            POSITIONAL_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+[[ -z "$PENDING_FILE" ]] || { echo "error: --file $PENDING_FILE is missing its --from SRC or --content '...'" >&2; exit 2; }
+
+# Reject positional free-text — it's a deferred follow-up.
+if [[ ${#POSITIONAL_ARGS[@]} -gt 0 ]]; then
+    echo "error: positional free-text is not supported in this version" >&2
+    echo "hint: free-text is a deferred follow-up; use --file or --edit for deterministic ops" >&2
+    exit 2
+fi
+
+# Require at least one op.
+if [[ ${#FILE_DESTS[@]} -eq 0 && ${#EDITS[@]} -eq 0 ]]; then
+    echo "error: no change requested — pass at least one --file or --edit" >&2
+    echo "hint: run 'mass-update --help'" >&2
+    exit 2
+fi
+
+# ── validate slug format ────────────────────────────────────────────────────
+validate_slug() {
+    local slug="$1"
+    # Must match OWNER/REPO pattern with valid chars
+    if [[ ! "$slug" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]]; then
+        echo "error: '$slug' is not a valid GitHub slug (owner/repo)" >&2
+        echo "hint: slugs must match OWNER/REPO format, e.g. 'agentculture/widget-cli'" >&2
+        return 1
+    fi
+    # Reject local paths that happen to contain a slash
+    if [[ "$slug" == ../* || "$slug" == ./* || "$slug" == /* ]]; then
+        echo "error: '$slug' is not a valid GitHub slug — looks like a local path" >&2
+        echo "hint: slugs must be GitHub OWNER/REPO, not filesystem paths" >&2
+        return 1
+    fi
+    return 0
+}
+
+# Reject a DEST/FILE path that could escape the scratch clone — absolute paths
+# or any '..' path segment. This enforces the cardinal rule: every write stays
+# inside the clone, never reaching beyond the repo.
+validate_relpath() {
+    local p="$1" what="$2"
+    if [[ "$p" == /* ]]; then
+        echo "error: $what '$p' must be a repo-relative path, not absolute" >&2
+        echo "hint: targets must stay inside the scratch clone" >&2
+        return 1
+    fi
+    if [[ "$p" == ".." || "$p" == "../"* || "$p" == *"/.." || "$p" == *"/../"* ]]; then
+        echo "error: $what '$p' may not contain a '..' path segment" >&2
+        echo "hint: targets must stay inside the scratch clone" >&2
+        return 1
+    fi
+    return 0
+}
+
+# ── check preconditions ─────────────────────────────────────────────────────
+if ! command -v gh >/dev/null 2>&1; then
+    echo "error: gh not found on PATH" >&2
+    echo "hint: install the GitHub CLI (gh) to use mass-update" >&2
+    exit 1
+fi
+
+if ! command -v git >/dev/null 2>&1; then
+    echo "error: git not found on PATH" >&2
+    echo "hint: install git to use mass-update" >&2
+    exit 1
+fi
+
+# ── parse repos ─────────────────────────────────────────────────────────────
+IFS=',' read -r -a TARGETS <<< "$REPOS_CSV"
+
+# Require at least one non-empty slug — an absent/blank --repos is an error,
+# not a silent no-op that exits 0.
+nonempty_targets=0
+for raw in ${TARGETS[@]+"${TARGETS[@]}"}; do
+    t="${raw#"${raw%%[![:space:]]*}"}"
+    t="${t%"${t##*[![:space:]]}"}"
+    [[ -n "$t" ]] && nonempty_targets=$((nonempty_targets + 1))
+done
+if [[ "$nonempty_targets" -eq 0 ]]; then
+    echo "error: no target repos — pass --repos OWNER/REPO[,...]" >&2
+    echo "hint: at least one GitHub slug is required" >&2
+    exit 2
+fi
+
+# Validate all slugs first
+for raw in "${TARGETS[@]}"; do
+    target="${raw#"${raw%%[![:space:]]*}"}"
+    target="${target%"${target##*[![:space:]]}"}"
+    [[ -n "$target" ]] || continue
+    if ! validate_slug "$target"; then
+        exit 2
+    fi
+done
+
+# Validate every destination/target path BEFORE any clone, so a traversal
+# attempt never even creates the scratch dir.
+for ((i=0; i<${#FILE_DESTS[@]}; i++)); do
+    validate_relpath "${FILE_DESTS[$i]}" "--file DEST" || exit 2
+done
+for ((i=0; i<${#EDITS[@]}; i++)); do
+    edit_file="${EDITS[$i]%%: *}"
+    validate_relpath "$edit_file" "--edit FILE" || exit 2
+done
+
+# ── scratch dir setup ───────────────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Root the scratch dir at the git toplevel, not the (arbitrary) cwd — so a run
+# from a subdir still confines and cleans up under <repo-root>/.mass-update.
+if ! REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"; then
+    echo "error: not inside a git repository" >&2
+    echo "hint: run mass-update from within the rollout-cli repo" >&2
+    exit 1
+fi
+SCRATCH_DIR="$REPO_ROOT/.mass-update"
+CLONES_DIR="$SCRATCH_DIR/clones"
+
+# Track which scratch dirs to clean up
+CLEANUP_DIRS=()
+cleanup() {
+    for d in "${CLEANUP_DIRS[@]}"; do
+        if [[ -d "$d" ]]; then
+            rm -rf "$d"
+        fi
+    done
+    # Also remove the .mass-update dir itself if empty or if not keep-clone
+    if [[ "$KEEP_CLONE" -eq 0 ]]; then
+        rm -rf "$SCRATCH_DIR"
+    fi
+}
+
+if [[ "$KEEP_CLONE" -eq 0 ]]; then
+    trap cleanup EXIT
+fi
+
+# ── apply ops to a clone ────────────────────────────────────────────────────
+apply_file_ops() {
+    local clone_dir="$1"
+    local i dest
+
+    for ((i=0; i<${#FILE_DESTS[@]}; i++)); do
+        dest="${FILE_DESTS[$i]}"
+        # Ensure parent dir exists
+        mkdir -p "$(dirname "$clone_dir/$dest")"
+        if [[ "${FILE_KINDS[$i]}" == "from" ]]; then
+            # Byte-verbatim copy — `$(cat)` would strip trailing newlines.
+            cp -- "${FILE_SRCS[$i]}" "$clone_dir/$dest"
+        else
+            printf '%s' "${FILE_CONTENTS[$i]}" > "$clone_dir/$dest"
+        fi
+    done
+}
+
+apply_edit_ops() {
+    local clone_dir="$1"
+    local edit file_part find_part replace_part
+
+    for edit in "${EDITS[@]}"; do
+        # Parse 'FILE: FIND => REPLACE'
+        # Split on first ': ' to get file and the rest
+        file_part="${edit%%: *}"
+        rest="${edit#*: }"
+        # Split on ' => ' to get find and replace
+        find_part="${rest%% => *}"
+        replace_part="${rest#* => }"
+
+        local target_file="$clone_dir/$file_part"
+        if [[ ! -f "$target_file" ]]; then
+            echo "error: file '$file_part' not found in clone" >&2
+            return 1
+        fi
+
+        # Use Python for unique-replace check
+        python3 -c "
+import sys
+content = open(sys.argv[1]).read()
+find = sys.argv[2]
+replace = sys.argv[3]
+count = content.count(find)
+if count != 1:
+    print(f\"error: '{find}' occurs {count} times (need exactly 1)\", file=sys.stderr)
+    sys.exit(1)
+content = content.replace(find, replace)
+open(sys.argv[1], 'w').write(content)
+" "$target_file" "$find_part" "$replace_part" || return 1
+    done
+}
+
+# ── process each repo ───────────────────────────────────────────────────────
+overall_rc=0
+
+for raw in "${TARGETS[@]}"; do
+    target="${raw#"${raw%%[![:space:]]*}"}"
+    target="${target%"${target##*[![:space:]]}"}"
+    [[ -n "$target" ]] || continue
+
+    owner="${target%%/*}"
+    repo="${target#*/}"
+    clone_name="${owner}-${repo}"
+    clone_dir="$CLONES_DIR/$clone_name"
+
+    # Check auth before cloning
+    if ! gh auth status >/dev/null 2>&1; then
+        echo "error: gh auth status failed" >&2
+        echo "hint: run 'gh auth login' to authenticate with GitHub" >&2
+        exit 1
+    fi
+
+    # Create scratch dirs
+    mkdir -p "$clone_dir"
+    CLEANUP_DIRS+=("$clone_dir")
+
+    # Clone the repo; fail this target if it didn't produce a git work tree
+    # (don't let a failed clone silently fall through to confusing op errors).
+    if ! gh repo clone "$target" "$clone_dir" 2>/dev/null \
+        || ! git -C "$clone_dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        echo "error: failed to clone $target" >&2
+        echo "hint: check the slug, your gh auth, and network access" >&2
+        overall_rc=1
+        continue
+    fi
+
+    # Create work branch
+    git -C "$clone_dir" checkout -b "mass-update/$clone_name" 2>/dev/null || \
+        git -C "$clone_dir" switch -c "mass-update/$clone_name" 2>/dev/null || true
+
+    # Apply file ops
+    apply_file_ops "$clone_dir" || { overall_rc=1; continue; }
+
+    # Apply edit ops
+    apply_edit_ops "$clone_dir" || { overall_rc=1; continue; }
+
+    if [[ "$DO_PR" -eq 1 ]]; then
+        # Issues are filed ONLY via communicate's post-issue.sh — no direct
+        # `agtag` fallback (that would bypass the /communicate channel).
+        post_issue_script="$SCRIPT_DIR/../../communicate/scripts/post-issue.sh"
+        if [[ ! -f "$post_issue_script" ]]; then
+            echo "error: communicate post-issue.sh not found — cannot file tracking issue" >&2
+            echo "hint: issues must be filed via /communicate (post-issue.sh); install the communicate skill" >&2
+            overall_rc=1
+            continue
+        fi
+
+        # Stage + commit (fail this target loudly on error, never mask it).
+        git -C "$clone_dir" add -A
+        if ! git -C "$clone_dir" commit -m "mass-update: deterministic update"; then
+            echo "error: commit failed for $target" >&2
+            overall_rc=1
+            continue
+        fi
+
+        # Push work branch — a failed push must not be swallowed.
+        if ! git -C "$clone_dir" push origin "mass-update/$clone_name"; then
+            echo "error: push failed for $target" >&2
+            overall_rc=1
+            continue
+        fi
+
+        # Create PR — capture failure rather than printing an empty URL.
+        if ! pr_url="$(gh pr create \
+            --repo "$target" \
+            --title "mass-update: deterministic update" \
+            --body "Automated update via mass-update skill." \
+            --head "mass-update/$clone_name")" || [[ -z "$pr_url" ]]; then
+            echo "error: gh pr create failed for $target" >&2
+            overall_rc=1
+            continue
+        fi
+        echo "PR_URL: $pr_url"
+
+        # File the companion tracking issue. Keep the body file INSIDE the
+        # scratch dir — never $TMPDIR — so no write lands outside the repo.
+        tmp_body="$(mktemp -p "$SCRATCH_DIR")"
+        printf 'PR: %s\n' "$pr_url" > "$tmp_body"
+        if ! issue_url="$(bash "$post_issue_script" \
+            --repo "$target" \
+            --title "mass-update: deterministic update" \
+            --body-file "$tmp_body")" || [[ -z "$issue_url" ]]; then
+            echo "error: filing tracking issue failed for $target" >&2
+            rm -f "$tmp_body"
+            overall_rc=1
+            continue
+        fi
+        rm -f "$tmp_body"
+        echo "ISSUE_URL: $issue_url"
+    else
+        # Preview mode: stage and show diff
+        git -C "$clone_dir" add -A
+        echo "=== Diff for $target ==="
+        git -C "$clone_dir" diff --cached
+    fi
+done
+
+exit "$overall_rc"