Tsunagi Monorepo

Tsunagi (繋ぎ) — 複数 GitHub 組織のプロジェクトをローカルで統合管理し、 Claude AI による AI 駆動開発を可視化・制御する Web UI ツール。

このリポジトリは npm workspaces ベースの monorepo です。

パッケージ

パッケージ	場所	npm 公開	説明
@minimalcorp/tsunagi	apps/web/	✅	Tsunagi 本体 (Next.js + Fastify + Prisma)
tsunagi-docs	apps/docs/	❌	ユーザー向けドキュメントサイト (Nextra, GitHub Pages にデプロイ)

クイックスタート（エンドユーザー向け）

Tsunagi を使いたいだけの場合は、npm から直接起動できます:

npx @minimalcorp/tsunagi

詳細は apps/web/README.md または ドキュメントサイト を参照してください。

開発セットアップ

# リポジトリをクローン
git clone https://github.com/minimalcorp/tsunagi.git
cd tsunagi

# 依存関係インストール（全ワークスペース）
npm install

# Tsunagi 本体を開発モードで起動
npm run dev

# ドキュメントサイトを開発モードで起動
npm run docs:dev

よく使うコマンド（ルートから実行）

コマンド	説明
npm run dev	web + docs を並列起動（Ctrl+C で両方停止）
npm run web:dev	Tsunagi 本体のみ開発モードで起動
npm run docs:dev	ドキュメントサイトのみ開発モードで起動
npm run build	全ワークスペースをビルド
npm run lint	全ワークスペースで ESLint を実行
npm run type-check	全ワークスペースで TypeScript 型チェック
npm run format	Prettier で全ファイルをフォーマット
npm run format:check	Prettier でフォーマット差分チェック

リリース

GitHub Actions の Release workflow を手動実行することで、@minimalcorp/tsunagi の npm 公開、および docs の GitHub Pages デプロイを統合的に行えます:

1. GitHub の Actions タブから Release workflow を選択
2. 以下を入力して Run:
   • target: all / tsunagi / docs のいずれか
   • version: patch / minor / major (tsunagi にのみ適用)

詳細は .github/workflows/release.yml を参照。

初回実行前の必須セットアップ

初めて Release workflow を実行する前に、以下を手動で設定しておく必要があります。

1. npm Organization 準備

   • npmjs.com で @minimalcorp organization を作成（未作成の場合）
   • @minimalcorp/tsunagi パッケージ名が未取得であることを確認

2. npm Trusted Publisher を事前登録 (npm 側)

   • 本 workflow は npm Trusted Publishing (OIDC) を使用するため NPM_TOKEN は不要
   • npmjs.com で Trusted Publisher を追加: organization=minimalcorp, repository=tsunagi, workflow=release.yml, environment=production-release
   • パッケージがまだ存在しない段階でも "Pending Trusted Publisher" として事前登録可能

3. GitHub Pages を Actions ソースに設定

   • Settings → Pages → Source: GitHub Actions を選択（Deploy from a branch ではない）

4. production-release Environment の作成と承認者設定（必須）

   • Settings → Environments → New environment → 名前を production-release として作成
   • Required reviewers を有効化し、リリース承認権限を持つメンバー（自分自身でも可）を追加
   • Release workflow の approve job はこの Environment 配下で実行されるため、 workflow 実行時に GitHub UI で明示的な承認操作が必要になる
   • publish-tsunagi / deploy-docs 両方がこの approval を通過した後でのみ実行される
   • 承認画面で main の最新状態（他 PR の merge 状況等）を目視確認してから承認する ことで、意図しない内容のリリースを防ぐ

5. main ブランチ保護の bypass 設定（保護ルールを設定している場合）

   • Release workflow は npm version で bump した commit と tag を main に直接 push する
   • main に Require a pull request before merging 等の保護ルールがある場合、push がブロックされる
   • github-actions[bot] は user role を持たないため、Bypass list に明示的に以下のいずれかを設定する必要がある:
     • 独立した Deploy key を発行し Bypass に追加（推奨）
     • 管理者ユーザーの PAT を PAT_TOKEN secret として登録し、workflow の checkout で使用
     • 管理者ユーザー自身を Bypass に追加（workflow を本人が起動する運用）
   • 保護ルールを main に設定していない場合は不要

これらを設定せずに workflow を実行すると、途中で失敗してバージョン番号だけが bump された中途半端な状態になる可能性があるので、必ず事前に設定してください。

リリース中の concurrent push について

Release workflow には以下の保護機構が組み込まれています:

• 同時実行の排他制御: concurrency: release group により、2つ目の Release workflow は1つ目の完了を待機します
• Push retry with rebase: workflow の checkout から push までの間に別の PR が main に merge された場合でも、自動で rebase してから retry します（最大3回）。rebase により merge 済みの内容を取り込んだ上で version bump commit を再適用するため、npm publish は最新の main 状態で行われます
• Environment 承認ゲート: 人間が承認するタイミングで main の状態を目視確認できるため、意図しない内容のリリースを事前に察知できます

リポジトリ構成

tsunagi/
├── apps/
│   ├── web/                  # @minimalcorp/tsunagi (Tsunagi 本体)
│   └── docs/                 # tsunagi-docs (Nextra ドキュメントサイト)
├── .github/workflows/
│   ├── ci.yml                # PR CI (format / lint / type-check / build)
│   ├── release.yml           # 統合リリース (npm publish + Pages deploy)
│   └── cla.yml               # CLA Assistant bot
├── .husky/                   # Git hooks
├── package.json              # monorepo root (workspaces)
├── .prettierrc.json          # monorepo 共通 Prettier 設定
├── LICENSE                   # PolyForm Shield 1.0.0
├── CLA.md                    # Contributor License Agreement
├── CONTRIBUTING.md           # コントリビューションガイド
└── CLAUDE.md                 # Claude AI 向け作業ルール

対応 OS

• macOS
• Linux
• Windows は非サポート（WSL2 経由で動作する可能性はありますが保証されません）

必須ランタイム

• Node.js ≥ 20
• Git ≥ 2.42（空リポジトリを扱うため git worktree add --orphan を使用）
• Claude Code CLI（claude ≥ 2.1.280）または Codex CLI（codex ≥ 0.162.0）のどちらか（PATH 上に必要）

ライセンス

本リポジトリは PolyForm Shield License 1.0.0 のもとで公開されています。 これは source-available ライセンスであり、競合製品化は禁止されていますが、 個人利用・社内利用・通常の商用利用は自由です。詳細は LICENSE を 参照してください。

コントリビューション

Pull Request を送信する際は CONTRIBUTING.md を参照し、 CLA Assistant bot の指示に従って CLA への同意をお願いします。