docs: standardize release runbook and installable artifact flow

Author: Kingson4Wu

.claude/commands/release.md

@@ -1,78 +1,234 @@
-description: Cut a release — verify, bump version, push, publish a GitHub release, and validate the install/update path
-argument-hint: "[patch|minor|major|X.Y.Z] [no-deploy]"
-allowed-tools: Bash, Read, Edit, Write
+description: Cut a production-ready release with a minimal cross-platform install package
+argument-hint: "[patch|minor|major|X.Y.Z]"
+allowed-tools: Bash, PowerShell, Read, Edit, Write
 ---
 
-You are running the **full git-auto-sync release flow**. Follow the phases in order.
-Treat every verification as a gate: if a step fails, **STOP and report** — do not tag, push, or publish the release.
+You are running the **git-auto-sync release runbook**. Execute these phases in order.
+Treat any failing check as a hard stop. Do not tag, push, or publish a release until every
+required gate passes.
 
 Arguments: `$ARGUMENTS`
-- First token = the bump: `patch` (default), `minor`, `major`, or an explicit `X.Y.Z`.
-- If `no-deploy` appears anywhere, skip the optional deployment verification phase.
+- First token = `patch` (default), `minor`, `major`, or explicit `X.Y.Z`.
 
-## Phase 0 — Preflight (abort on any problem)
+## Phase 0 — Preflight
 
-1. Confirm the branch is `main` and the working tree is clean except for changes you are about to make.
-2. `git fetch --tags origin` to ensure release tags are present locally.
-3. Run the verification gate and require all green:
-   - `uv run pytest -q`
-   - `uv run ruff check .`
-   - `uv run ruff format --check git_auto_sync/ tests/`
+1. Confirm branch state and remote:
+
+```bash
+git remote -v
+git branch --show-current
+git status --short
+git fetch --all --prune
+git pull --ff-only origin main
+```
+
+2. Make sure required release tooling is available:
+
+```bash
+command -v gh >/dev/null || { echo "Install gh first"; exit 1; }
+command -v uv >/dev/null || { echo "Install uv first"; exit 1; }
+command -v tar >/dev/null || { echo "Install tar first"; exit 1; }
+```
+
+3. Fetch tags and run verification gates:
+
+```bash
+git fetch --tags origin
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check git_auto_sync/ tests/
+```
+
+4. Verify release payload files exist:
+
+```bash
+test -f install.sh
+test -f install.ps1
+test -f pyproject.toml
+test -f git_auto_sync/__init__.py
+test -f uv.lock
+```
 
 ## Phase 1 — Version bump
 
-1. Read current `version` from `pyproject.toml`.
-2. Compute new version from bump argument (default `patch`).
-3. Update `pyproject.toml` and refresh lockfile:
-   - `uv sync`
-4. Commit exactly version files:
-   ```bash
-   git add pyproject.toml uv.lock
-   git commit -m "chore: bump version to X.Y.Z"
-   ```
-
-## Phase 2 — Push
-
-`git push origin main`.
-
-## Phase 3 — GitHub release
-
-1. Resolve previous tag: `git describe --tags --abbrev=0 HEAD^` (after fetching tags).
-2. Draft release notes from `git log <prevtag>..HEAD --no-merges` in repo style:
-   - Title: `vX.Y.Z — <short summary>`
-   - A short lead, then `## Fixed` / `## Changed` / `## Added` sections as warranted.
-   - Install one-liner:
-     `curl -fsSL https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.sh | bash`
-   - `**Full Changelog**: https://github.com/OctopusGarage/git-auto-sync/compare/<prevtag>...vX.Y.Z`
-3. Create release:
-   ```bash
-   gh release create vX.Y.Z --target main --title "vX.Y.Z — ..." --notes-file - <<'EOF'
-   ...
-   EOF
-   ```
-4. Verify:
-   - `gh release list -L 3` shows `vX.Y.Z` as **Latest**
-   - `git ls-remote --tags origin vX.Y.Z` resolves
-
-## Phase 4 — Self-consistency check
-
-Because install/update pull the latest release tarball, confirm the new tag's tarball includes the built code:
+1. Read current versions:
+
+```bash
+grep -n '^version' pyproject.toml
+grep -n '^__version__' git_auto_sync/__init__.py
+```
+
+2. Set new version (`vX.Y.Z`, patch by default):
+
+```bash
+VERSION="vX.Y.Z"
+```
+
+3. Bump files and refresh lockfile:
+
+```bash
+sed -i "s/^version = \".*\"/version = \"${VERSION#v}\"/" pyproject.toml
+sed -i "s/^__version__ = \".*\"/__version__ = \"${VERSION#v}\"/" git_auto_sync/__init__.py
+uv sync
+```
+
+4. Commit the bump:
+
+```bash
+git add pyproject.toml git_auto_sync/__init__.py uv.lock
+git commit -m "chore: bump version to ${VERSION}"
+```
+
+## Phase 2 — Build a minimal release package
+
+Build a distributable that excludes repository internals not needed by users.
+The package must contain runtime source + launch scripts only.
+
+```bash
+VERSION="vX.Y.Z"
+PACKAGE_NAME="git-auto-sync-${VERSION}-release.tar.gz"
+PACKAGE_DIR="dist/tmp/git-auto-sync-${VERSION}"
+RELEASE_FILES=(
+  git_auto_sync
+  README.md
+  config.example.toml
+  install.sh
+  install.ps1
+  pyproject.toml
+  uv.lock
+)
+
+mkdir -p "$PACKAGE_DIR"
+for item in "${RELEASE_FILES[@]}"; do
+  test -e "$item" || { echo "Missing $item"; exit 1; }
+  cp -R "$item" "$PACKAGE_DIR/"
+done
+
+cp -f .claude/commands/release.md "$PACKAGE_DIR/"
+
+mkdir -p dist
+tar -czf "dist/${PACKAGE_NAME}" -C dist/tmp "git-auto-sync-${VERSION}"
+sha256sum "dist/${PACKAGE_NAME}" | tee "dist/${PACKAGE_NAME}.sha256sum"
+ls -lh "dist/${PACKAGE_NAME}" "dist/${PACKAGE_NAME}.sha256sum"
+
+rm -rf dist/tmp
+```
+
+## Phase 3 — GitHub release and asset upload
+
+1. Draft release notes:
+
+```bash
+PREV_TAG="$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || git rev-list --max-parents=0 HEAD)"
+cat <<'EOF' > /tmp/release-notes.md
+## What's Changed
+
+## Added
+- ...
+
+## Changed
+- ...
+
+## Fixed
+- ...
+
+**Full Changelog**
+https://github.com/OctopusGarage/git-auto-sync/compare/${PREV_TAG}...${VERSION}
+
+**Install**
+curl -fsSL https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.sh | bash
+
+**Install (Windows)**
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.ps1 | iex"
+EOF
+```
+
+2. Create release and attach package:
+
+```bash
+gh release create "${VERSION}" --target main --title "${VERSION} — release notes" --notes-file /tmp/release-notes.md
+gh release upload "${VERSION}" "dist/${PACKAGE_NAME}" "dist/${PACKAGE_NAME}.sha256sum" --clobber
+```
+
+3. Verify assets and tag:
+
+```bash
+gh release view "${VERSION}" --json name,tagName,isLatest,publishedAt,url -q '{name, tag: .tagName, latest: .isLatest, publishedAt, url}'
+gh release view "${VERSION}" --json assets --jq ".assets[].name" | sort
+git ls-remote --tags origin "${VERSION}"
+```
+
+## Phase 3.1 — Monitor CI for this tag
+
+```bash
+RUN_ID="$(gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
+gh run view "$RUN_ID" --json status,conclusion,workflowName,name,url -q '{workflow: .workflowName, name: .name, status: .status, conclusion: .conclusion, url: .url}'
+gh run watch "$RUN_ID"
+```
+
+```powershell
+ $runId = (gh run list --workflow ci.yml --limit 1 --json databaseId --jq "[0].databaseId")
+ gh run view $runId --json status,conclusion,workflowName,name,url -q '{workflow: .workflowName, name: .name, status: .status, conclusion: .conclusion, url: .url}'
+ gh run watch $runId
+```
+
+If a failure is found, fix locally and rerun from the current failed phase only after pushing follow-up commits.
+
+## Phase 4 — Validate installer and updater (all platforms)
+
+### macOS / Linux
+
 ```bash
-TAG=$(git describe --tags --abbrev=0)
-url=$(curl -fsSLI -o /dev/null -w '%{url_effective}' "https://github.com/OctopusGarage/git-auto-sync/releases/latest")
-TAG="${url##*/}"
-curl -fsSL "https://github.com/OctopusGarage/git-auto-sync/archive/refs/tags/${TAG}.tar.gz" -o /tmp/git-auto-sync.tar.gz
-tar -tzf /tmp/git-auto-sync.tar.gz | rg "setup\.(sh|ps1)|pyproject.toml|git_auto_sync/cli.py"
+curl -fsSL https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.sh | bash
+git-auto-sync --help
+git-auto-sync --version
+git-auto-sync update --check
 ```
 
-## Phase 5 — Optional local validation (if not skipped)
+### Windows
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.ps1 | iex"
+git-auto-sync --help
+git-auto-sync --version
+git-auto-sync update --check
+```
+
+## AI Release Operator Prompt (copy/paste)
+
+```text
+You are a strict release operator for the git-auto-sync repository.
+Run this command sequence exactly:
+1) preflight checks on main
+2) version bump (`patch|minor|major|X.Y.Z`)
+3) minimal package build
+4) GitHub release creation and asset upload
+5) CI monitor
+6) macOS/Linux/Windows install+update verification
+Stop at the first failed command and report the command, output, and required fix.
+All outputs must be in English.
+Release argument is: `$ARGUMENTS`.
+```
 
-Run installation/update smoke checks:
-1. `curl -fsSL https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.sh | bash`
-2. `git-auto-sync --help`
-3. `uv run git-auto-sync config check`
-4. `git-auto-sync update --check` expects to report up-to-date at new version.
+## AI Install Prompt (copy/paste)
+
+```text
+I need a clean install on current machine.
+Use the latest release package and do not clone the full source.
+Run one of these:
+
+macOS/Linux:
+curl -fsSL https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.sh | bash
+
+Windows:
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.ps1 | iex"
+```
 
-## Report
+## Completion report
 
-Summarize: new version, commit SHA, release URL, and verification results. If stopped early, identify the failing gate and required fix.
+Record:
+- New version and tag
+- Release URL
+- Asset names and checksums
+- Verification outputs
+- Blocking issues and fixes if stopped early

README.md

@@ -135,6 +135,37 @@ Use the assistant command:
   - version bump (`pyproject.toml` + `uv.lock`)
   - release publish on GitHub
   - install/update validation
+  - CI monitoring
+  - dedicated release package format: `git-auto-sync-vX.Y.Z-release.tar.gz`
+
+```bash
+# macOS / Linux
+cat .claude/commands/release.md
+
+# Windows
+Get-Content .claude/commands/release.md
+```
+
+Use this copy-paste prompt for AI-assisted release operations:
+
+```text
+Run the full release flow in .claude/commands/release.md:
+preflight, version bump, minimal package build, publish + asset upload,
+and cross-platform validation.
+Stop immediately on first failure and report the blocked step plus fix.
+```
+
+Copyable installation prompt for AI on any platform:
+
+```text
+Install git-auto-sync using the latest release package and do not fetch the full source.
+
+macOS / Linux:
+curl -fsSL https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.sh | bash
+
+Windows:
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/OctopusGarage/git-auto-sync/main/install.ps1 | iex"
+```
 
 For manual release scripts, run the version bump and release flow in that file.