test-release

リリーステスト

リリース済みの archon バイナリを対象とした自動スモークテストです。次の 3 つのインストール方法を対象とします。

• brew — macOS の Homebrew tap（formula とチェックサムをテストします）
• curl-mac — macOS での curl install.sh（一時ディレクトリ内でサンドボックス化し、インストールスクリプトをテストします）
• curl-vps — リモート Linux VPS での curl install.sh（Linux バイナリとインストール全体の流れをテストします）

どの方法でもバイナリをインストールし、固定のスモークテストスイートを実行して、後片付けを行います。開発用の bun link バイナリには一切触れず、テスト中も引き続き PATH 上のデフォルトの archon として使えます。

このスキルを使用しない場合：

• まだリリースされていない場合 — bash scripts/build-binaries.sh でローカルバイナリをビルドし、dist/binaries/ から直接実行します
• 開発用クローンをテストしたい場合 — bun run validate を使用するか、bun packages/cli/src/cli.ts でソースを直接実行します
• サーバーと Web UI のデプロイフロー全体をテストしたい場合 — 実際の VPS で deploy/cloud-init.yml の cloud-init を使用します

リリース前 QA 向けのローカルビルド

CI とまったく同じフラグと定数でバイナリをローカルビルドするには、 のように scripts/build-binaries.sh` を直接実行します。このスクリプトは 2 つのモードをサポートします。

# Multi-target mode (builds all 4 local platforms into dist/binaries/)
VERSION=0.3.1 GIT_COMMIT=abc12345 bash scripts/build-binaries.sh

# Single-target mode (matches one CI matrix job)
VERSION=0.3.1 \
GIT_COMMIT=abc12345 \
TARGET=bun-darwin-arm64 \
OUTFILE=dist/test-archon-darwin-arm64 \
bash scripts/build-binaries.sh

# Verify the binary — use the path from the mode you built:
#   multi-target → ./dist/binaries/archon-darwin-arm64
#   single-target → the OUTFILE you passed above
./dist/test-archon-darwin-arm64 version
# Expected: Archon CLI v0.3.1, Build: binary, Git commit: abc12345

ビルド時定数に関する問題をローカルで検出するため、リリースにタグを付ける前に実行してください。 このスクリプトが正式なエントリーポイントです。ローカル開発と リリースワークフローの両方で同じ方法で呼び出されるため、ローカルビルドが成功すれば、CI の ビルドでも同じコードパスが実行されます。

フェーズ 1 — 対象範囲の決定

引数を解析します。このスキルでは最大 3 つの引数を受け取ります。

1. インストール方法（brew | curl-mac | curl-vps）：実行するインストールフロー
2. 想定バージョン（任意）：リリースで報告されるべきバージョンタグ（例：0.3.1）。指定されていない場合は、次の方法で取得します。

gh release list --repo coleam00/Archon --limit 1 --json tagName --jq '.[0].tagName'

3. VPS の接続先（curl-vps のみ）：user@host または host 形式の SSH 接続先（デフォルトの SSH 設定を使用します）

引数が不足している場合は、何も実行する前にユーザーに確認してください。インストール方法や想定バージョンを推測してはいけません。

フェーズ 2 に進む前に、計画をユーザーに確認します。出力は次のようになります。

About to test:
  Path:     brew (Homebrew tap on macOS)
  Version:  0.3.1 (expected)
  Cleanup:  will uninstall after tests (brew uninstall + untap)
            If `archon-stable` symlink is detected in Phase 2, it will be
            restored at the end of Phase 5 by reinstalling the tap formula.

Proceed? (y/N)

明示的な確認を得るまでは先に進まないでください。リリーステストではインストール状態に変更を加えるため、ユーザーがそのことを把握している必要があります。

フェーズ 2 — 事前確認

何かに触れる前に、次の作業を行います。

1. 参照用に、現在の開発用バイナリの状態を記録します。

which -a archon
archon version 2>&1 | head -5

開発用バイナリのパスとバージョンを記録し、最終レポートで「開発用バイナリには変更を加えていない」と示せるようにします。

2. 選択した方法の前提条件を確認します。

   • brew：brew --version が成功する必要があります。失敗した場合は、「Homebrew がインストールされていません — https://brew.sh/ を参照してください」で中止します。
   • curl-mac：curl --version が成功する必要があります（macOS では実質的に常に成功します）。
   • curl-vps：ssh <target> 'uname -a' が成功する必要があります。失敗した場合は、「 に SSH 接続できません」で中止します。また、ssh <target> 'command -v curl' がパスを返すことも確認します。

3. GitHub にリリースが存在することを確認します。

gh release view v<version> --repo coleam00/Archon --json tagName,assets --jq '{tag: .tagName, assetCount: (.assets | length)}'

リリースが存在しない、またはアセットがない場合は、わかりやすいメッセージを表示して中止します。存在しないリリースをインストールしようとしてはいけません。

4. 永続的な archon-stable インストールを検出します（brew の場合のみ）。 ユーザーが以前の brew インストールの名前を archon-stable に変更している場合（デュアル Homebrew パターン — ~/.config/fish/functions/brew-upgrade-archon.fish を参照）、フェーズ 5 の brew uninstall によって削除されます。状態を記録し、フェーズ 5b で復元できるようにします。

ARCHON_STABLE_WAS_INSTALLED=""
if [ -L /opt/homebrew/bin/archon-stable ] || [ -L /usr/local/bin/archon-stable ]; then
  ARCHON_STABLE_WAS_INSTALLED="yes"
  echo "Detected persistent archon-stable — will restore after Phase 5 uninstall."
fi

フェーズ 5b で使用する環境に ARCHON_STABLE_WAS_INSTALLED をエクスポートします。対象は brew の場合のみです。curl-mac と curl-vps は brew を経由せず、archon-stable に影響しません。

フェーズ 3 — インストール

方法：brew

brew tap coleam00/archon
brew install coleam00/archon/archon
BINARY="$(brew --prefix coleam00/archon/archon)/bin/archon"

フェーズ 4 で使用するため、$BINARY を取得します。ファイルが存在し、実行可能であることを確認します。

パス：curl-mac

開発用の bun link バイナリが変更されずに PATH に残るよう、専用の一時ディレクトリにインストールします。

INSTALL_DIR=/tmp/archon-test-release-$(date +%s)
mkdir -p "$INSTALL_DIR"
curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | INSTALL_DIR="$INSTALL_DIR" bash
BINARY="$INSTALL_DIR/archon"

環境変数は curl ではなく bash の前に指定する必要があります。 VAR=x cmd1 | cmd2 では、代入が適用されるのは cmd1 だけです。そのため、INSTALL_DIR=… curl … | bash とすると、ダウンロードには設定されますが、インストーラーはデフォルトの /usr/local/bin を使用します。 この失敗は明らかではなく、分かりにくいものです。スクリプトはダウンロードしてチェックサムを検証した後、sudo を要求し、sudo: a terminal is required to read the password というエラーで終了します。0.7.1 のテストで確認されています。

scripts/install.sh も、ヘッダーの使用例に同じ誤った形式（INSTALL_DIR=~/.local/bin curl -fsSL ... | bash）が記載されているため、それをコピーしたユーザーも同じ問題に遭遇します。両方まとめて修正してください。issue #2436 を参照してください。

$BINARY が存在し、実行可能であることを確認します。クリーンアップ用にインストールディレクトリを記録します。

パス：curl-vps

VPS でインストールスクリプトを実行します。

ssh <target> 'curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | bash'

バイナリのインストール先を特定します。install.sh はデフォルトで /usr/local/bin/archon を使用しますが、/usr/local/bin に書き込めない場合は $HOME/.local/bin/archon にフォールバックします。

ssh <target> 'command -v archon'

リモートのパスを $REMOTE_BINARY として記録します。Phase 4 の残りの作業では、すべてのコマンドを ssh <target> '<cmd>' で実行します。

SHA256 とバージョンの記録

インストール直後に、以下を記録します。

# Local paths (brew / curl-mac)
shasum -a 256 "$BINARY" | awk '{print $1}'
"$BINARY" version 2>&1

# Remote path (curl-vps)
ssh <target> "shasum -a 256 $REMOTE_BINARY || sha256sum $REMOTE_BINARY" | awk '{print $1}'
ssh <target> "$REMOTE_BINARY version" 2>&1

レポート用に両方を記録します。SHA256 を使えば、バグを報告したユーザーが、テストしたものとまったく同じアーティファクトを実行しているか、後から確認できます。

フェーズ 4 — スモークテスト

以下のテストを順番に $BINARY（curl-vps の場合は ssh <target> $REMOTE_BINARY）に対して実行します。必ずバイナリのフルパスを使用し、PATH 上の archon は決して使わないでください。 これにより、テスト対象のバイナリを明確にできます。

最終レポート用に、各テストのコマンド出力全体を記録します。テストに失敗した場合も次のテストを続けて（レポートを完成させるため）、全体の結果は FAIL とします。

テスト 1 — バージョンが正しく表示される

"$BINARY" version

合格基準：

• 終了コードが 0
• 出力に Archon CLI v<expected-version> が含まれる
• 出力に Build: binary が含まれる（Build: source (bun) ではない）
• unknown ではない git コミットが出力される（つまり、Git commit: <sha>）

よくある失敗：

• 終了コードが 0 以外 → pino-pretty のクラッシュ（#960）または同様の起動失敗
• 誤ったバージョンが表示される → バイナリが古いか、ビルドスクリプトによる bundled-build.ts の更新に失敗した
• Build: source (bun) → ビルド時に BUNDLED_IS_BINARY が true に設定されていなかった（#979 の再発）
• Git commit: unknown → ビルドスクリプトがコミットを取得できなかった

テスト 2 — バンドルされたワークフローが読み込まれる

CLI が操作できるよう、一時的な Git リポジトリを作成します。

TESTREPO=/tmp/archon-test-repo-$(date +%s)
mkdir -p "$TESTREPO"
cd "$TESTREPO"
git init -q
git commit -q --allow-empty -m init
"$BINARY" workflow list

合格基準：

• 終了コードが 0
• バンドルされた sdlc パックのワークフローが一覧表示される：archon-triage、archon-investigate、archon-plan、archon-implement、archon-pr、archon-review、archon-validate、archon-deliver、archon-upkeep、archon-ship
• ワークフローファイルの欠落や JSON の解析失敗に関するエラーがない

よくある失敗：

• 一覧が空 → デフォルトのバンドルがバイナリに埋め込まれていない（isBinaryBuild 検出パスの再発）
• Not in a git repository → 作業ディレクトリの処理に関するバグ
• 解析エラー → 埋め込み JSON が破損しているか、古い

テスト 3 — SDK パスが機能する（archon-investigate ワークフロー）

前提条件。 コンパイル済みバイナリの実行には、ホストに Claude Code がインストールされ、バイナリのパスが設定されている必要があります。このテストを実行する前に、以下のいずれかを確認してください。

# Option A — env var (easy for ad-hoc testing)
# After the native installer (Anthropic's default):
export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"
# Or after npm global install:
export CLAUDE_BIN_PATH="$(npm root -g)/@anthropic-ai/claude-code/cli.js"

# Option B — config file (persistent)
#   Add to ~/.archon/config.yaml:
#   assistants:
#     claude:
#       claudeBinaryPath: /absolute/path/to/claude

次に、同じ $TESTREPO で以下を実行します。

"$BINARY" workflow run archon-investigate --no-worktree "say hello and nothing else" 2>&1 | tee /tmp/archon-test-investigate.log

合格条件：

• 終了コードが 0
• Claude のサブプロセスが正常に起動する（初期出力に spawn EACCES、ENOENT、process exited with code 1 が含まれない）
• Claude Code CLI not found エラーが発生しない（これはリゾルバーが設定されたパスを拒否したことを意味します。cli.js が実際に存在することを確認してください）
• 応答が生成される（どのような応答でも構いません。「hello」だけでも、SDK のラウンドトリップが機能することを確認できます）

よくある失敗：

• Claude Code not found → CLAUDE_BIN_PATH / claudeBinaryPath が未設定か、存在しないファイルを指しています。パスを修正して再実行してください。
• Module not found "/Users/runner/..." → #1210 のリグレッションです。リゾルバーが迂回され、SDK の import.meta.url フォールバックからビルドホストのパスが漏れています。packages/providers/src/claude/provider.ts とリゾルバーを調査してください。
• Credit balance is too low → 認証に、クレジット残高がなくなった API キーが設定されています（CLAUDE_USE_GLOBAL_AUTH と ~/.archon/.env を確認してください）
• unable to determine transport target for "pino-pretty" → #960 のリグレッションです。TTY 上でバイナリがクラッシュします。
• package.json not found (bad installation?) → #961 のリグレッションです。isBinaryBuild の検出が機能していません。
• 出力を生成する前にプロセスが終了する → 一般的な起動失敗です。標準エラー出力を取得してください。

テスト 3b — リゾルバーのエラーパス（CLAUDE_BIN_PATH を指定せずに実行）

何も設定されていない場合にリゾルバーが明確なエラーを出すことを、手早く確認します。

(unset CLAUDE_BIN_PATH; "$BINARY" workflow run archon-investigate --no-worktree "hello" 2>&1 | tee /tmp/archon-test-no-path.log)

合格条件（~/.archon/config.yaml に claudeBinaryPath が設定されていない場合）：

• エラーメッセージに Claude Code not found が含まれる
• エラーメッセージに、解決方法として CLAUDE_BIN_PATH と claudeBinaryPath の両方が記載されている
• CI ファイルシステムを参照する Module not found のスタックトレースがない

グローバルに claudeBinaryPath を設定している場合は、このテストをスキップするか、一時的に ~/.archon/config.yaml の名前を変更してください。

テスト 4 — Env リークガードで .env から機密キーを除去する

偽の機密キーを含む、使い捨ての 2 つ目のリポジトリを作成します。

LEAKREPO=/tmp/archon-test-leak-$(date +%s)
mkdir -p "$LEAKREPO"
cd "$LEAKREPO"
git init -q
git commit -q --allow-empty -m init
printf 'ANTHROPIC_API_KEY=sk-ant-test-fake\n' > .env
"$BINARY" workflow run archon-investigate --no-worktree "hello" 2>&1 | tee /tmp/archon-test-leak.log

合格基準（現在の動作 — ガードは除去し、拒否はしません）：

• 出力に、リポジトリ名とソースファイルを示す次の形式の除去行が含まれていること： [archon] stripped N keys from <repo> (.env) to prevent target repo env from leaking into Archon processes
• N が仕込んだキーの数と一致すること（上記の .env では 1）。0 はファイルがまったく読み込まれていないことを意味し、実際のリグレッションです。
• その後、ワークフローが続行され、正常に完了すること

除去行を検証します。このリポジトリとこのキー数に限定することで、別のディレクトリからの除去による誤った合格を防ぎます。終了ステータスも取得してください。除去方式ではワークフローは成功する想定なので、ゼロ以外の終了ステータスはそれ自体が失敗です。

"$BINARY" workflow run archon-investigate --no-worktree "hello" > /tmp/archon-test-leak.log 2>&1
leak_exit=$?

# $LEAKREPO may be a symlinked path (/tmp -> /private/tmp on macOS); the binary
# logs the resolved form, so compare against that.
resolved_repo=$(cd "$LEAKREPO" && pwd -P)
expected="[archon] stripped 1 keys from ${resolved_repo} (.env) to prevent target repo env from leaking into Archon processes"

if [ "$leak_exit" -ne 0 ]; then
  echo "FAIL: workflow exited $leak_exit — the guard strips and proceeds, it should not abort"
elif grep -qxF "$expected" /tmp/archon-test-leak.log; then
  echo "PASS: env-leak guard stripped exactly the planted key from this repo"
else
  echo "FAIL: expected strip line absent. Got:"
  grep -F '[archon] stripped' /tmp/archon-test-leak.log || echo "  (no strip line at all — guard inactive)"
fi

ここで完全一致を使うのは意図的です。stripped [1-9][0-9]* keys .*\.env のような緩いパターンでは、どのパスからのどの正の数も合格してしまいます。そのため、別のリポジトリに属する除去や、無関係な .env によって増えたカウントが成功と判定され、このテストで検出すべきリグレッションが見逃されます。

経緯 — 古い基準を再度検証しないでください。 このテストは以前、拒否（Cannot add codebase / Cannot run workflow、ゼロ以外の終了ステータス）を想定していました。これは #1036/#1038/#983 の動作でした。現在の設計は 2 層の除去ガードです。対象リポジトリの .env を読み込み、危険なキーを Archon のサブプロセスに渡す環境から削除して、実行を続けます。0.7.1 のテストでは、ガードが正しく動作し、仕込んだキー 1 つだけを除去したバイナリに対して、古いアサーションが FAIL を報告しました。検証すべきなのはセキュリティ上の特性（キーがサブプロセスに決して渡らないこと）であり、古くなった対処メッセージではありません。

よくある失敗：

• 除去行がない → ガードが有効になっていません。.env がサブプロセスに渡されています
• stripped 0 keys → ファイルは見つかりましたが、解析されていません
• 除去行に誤ったファイルまたはリポジトリが記載されている → パス解決のリグレッション

リークテスト用リポジトリをクリーンアップします。

rm -rf "$LEAKREPO"

テスト 5 — 分離リストが機能することを確認する（健全性チェック）

同じ $TESTREPO で実行します。

"$BINARY" isolation list

合格基準：

• 終了コードが 0
• エラーがないこと（ワークツリーが作成されていない場合、リストが空でも問題ありません）

これは、ほかのテストでは表面化しない分離サブシステムのリグレッションを検出します。

テスト 6 — テスト用リポジトリをクリーンアップする

rm -rf "$TESTREPO"

curl-vps の場合は、SSH 経由で作成したリモートテスト用リポジトリもクリーンアップします。

フェーズ 5 — アンインストール

フェーズ 4 が失敗した場合でも、必ずアンインストールを実行してください。 テスト前と同じ状態にシステムを戻すことが目的です。

パス：brew

brew uninstall coleam00/archon/archon
brew untap coleam00/archon

開発用バイナリが引き続きデフォルトであることを確認します。

which -a archon
# should show only the ~/.bun/bin/archon path, not a brew path

archon version | head -1
# should match the dev version captured in Phase 2

テスト前に archon-stable が存在していた場合は復元します（デュアル Homebrew パターン — フェーズ 2 の項目 4 を参照）。

if [ -n "$ARCHON_STABLE_WAS_INSTALLED" ]; then
  echo "Restoring archon-stable (detected before test)..."
  brew tap coleam00/archon
  brew install coleam00/archon/archon
  BREW_BIN="$(brew --prefix)/bin"
  if [ -e "$BREW_BIN/archon" ]; then
    mv "$BREW_BIN/archon" "$BREW_BIN/archon-stable"
    echo "archon-stable restored: $(archon-stable version 2>/dev/null | head -1)"
  else
    echo "WARNING: brew install succeeded but $BREW_BIN/archon missing — check formula"
  fi
fi

復元されるバージョンについて：タップから再インストールするため、通常はタップで現在提供されているバージョン、つまりテストしたばかりのリリースがインストールされます（そのため、archon-stable は新たにテストしたバージョンになります）。通常、これはオペレーターが望む状態です。新しいリリースが動作することを確認したので、archon-stable をそのバージョンに設定したいはずです。古いバージョンの後方互換性 QA のためにテストしていた場合、復元される archon-stable はテスト前のバージョンではなく、現在のタップのフォーミュラになります。そのまれなケースでは、テスト後にオペレーターが brew-upgrade-archon を手動で再実行してください。

パス：curl-mac

rm -rf "$INSTALL_DIR"

パス：curl-vps

ssh <target> "sudo rm -f /usr/local/bin/archon || rm -f \$HOME/.local/bin/archon"

任意：QA を継続するために VPS のバイナリをインストールしたままにしたい場合があります。削除する前に確認してください。

フェーズ 6 — レポート

以下を含む構造化レポートを作成します。

• ヘッダー：テストしたリリースバージョン、インストールパス、タイムスタンプ、テスト対象バイナリの SHA256
• 環境：開発用バイナリのパスとバージョン（開発環境のインストールに影響していないことの証明）
• テスト結果テーブル：テストごとに 1 行を設け、PASS／FAIL／SKIP を記載
• 取得した出力：FAIL の場合は、正確なコマンド、終了コード、stderr／stdout の末尾 20 行を記載
• 全体の判定：すべてのテストに合格した場合は PASS、いずれかのテストに失敗した場合は FAIL
• 次のステップ：FAIL の場合は、具体的な対応（ホットフィックスの issue を起票する、再タグ付けする、ビルドワークフローを確認するなど）を提案

PASS レポートの例：

Test Release Report — archon v0.3.1 via brew
────────────────────────────────────────────
Tested at:    2026-04-08 15:42 UTC
Binary SHA:   e62eb73547b3740d56f242859b434a91d3830360a0d18f14de383da0fd7a0be6
Binary path:  /opt/homebrew/Cellar/archon/0.3.1/bin/archon
Dev binary:   /Users/rasmus/.bun/bin/archon → ../install/.../cli.ts (unchanged)

  [PASS]  Test 1  version reports 0.3.1, Build: binary, commit abc1234
  [PASS]  Test 2  workflow list returned 21 bundled workflows
  [PASS]  Test 3  workflow run archon-investigate produced output
  [PASS]  Test 4  env-leak guard stripped exactly the planted key
  [PASS]  Test 5  isolation list executed without errors
  [PASS]  Cleanup brew uninstall + untap clean, dev binary unchanged

Overall: PASS

This release is safe to announce. Next steps:
  - Update release notes on GitHub if not done already
  - Announce on whatever channels you use

FAIL レポートの例：

Test Release Report — archon v0.3.1 via curl-vps
────────────────────────────────────────────────
Tested at:    2026-04-08 15:42 UTC
Binary SHA:   0cf83e15e6af228e3c3473467ca30fa7525b6d7069818d85f97a115ea703d708
Binary path:  user@vps:/usr/local/bin/archon
Dev binary:   /Users/rasmus/.bun/bin/archon (unchanged)

  [PASS]  Test 1  version reports 0.3.1, Build: binary
  [FAIL]  Test 2  workflow list returned 0 workflows

    Command:  archon workflow list
    Exit:     0
    Output:
      Discovering workflows in: /tmp/archon-test-repo-1712590923
      Found 0 workflow(s):

  [SKIP]  Test 3  SDK test skipped because Test 2 failed
  [SKIP]  Test 4  env-leak guard test skipped because Test 2 failed
  [PASS]  Test 5  isolation list executed without errors
  [PASS]  Cleanup VPS binary removed

Overall: FAIL

Likely cause: bundled workflows were not embedded in the binary.
Check the build workflow for missing asset embedding, or verify that
BUNDLED_WORKFLOWS in packages/workflows/src/defaults/bundled-defaults.ts
was populated at build time.

Next steps:
  1. File a P0 hotfix issue with the captured output
  2. Do NOT announce v0.3.1 until the hotfix ships as v0.3.2
  3. Consider adding a CI guard that blocks releases if BUNDLED_WORKFLOWS is empty

主な動作

• 開発用の bun link バイナリには絶対に触れないでください。 フェーズ 4 のテストでは、必ずインストール済みバイナリのパスを使用してください。実行前と実行後に確認します。
• 失敗時はクリーンアップします。 フェーズ 4 の途中で失敗しても、次回の実行時にクリーンな状態で開始できるよう、必ずフェーズ 5 を実行してください。
• インストール直後に SHA256 を取得します。 これにより、バグ報告でテスト対象のアーティファクトを特定できます。
• インストール前に明示的な確認を取ります。 2 つ目のバイナリをユーザーに予告なくインストールしてはいけません。
• 開発用バイナリの状態を、前置きと後書きの両方で報告します。 テストによって開発環境に影響していないことを証明します。
• いずれかのテストが失敗した場合は、ゼロ以外の終了コードを返します。 スキルは失敗を伝播し、自動化されたラッパー（CI、スクリプト）が検出できるようにします。

関連項目

• scripts/build-binaries.sh — リリースに含まれるバイナリアーティファクトをビルドします
• .github/workflows/release.yml — タグのプッシュ時にバイナリをビルドして公開します
• homebrew/archon.rb — Homebrew tap のフォーミュラ（リリースごとに更新）
• scripts/install.sh — curl インストールスクリプト
• scripts/install-local.sh / install-local.ps1 — ローカルファイル用のインストールハーネス（GitHub リリースではなく、ブランチからビルドしたバイナリのリリース前 QA 用）
• /release スキル — リリース手順そのもの（このフローとは逆側）