ai-check-template 0.2.0-alpha.0

package/package-templates/prompts/rls-permission.md

@@ -0,0 +1,94 @@
+# rls-permission プロンプト
+
+> **ステータス**: Draft v0.1（Phase 1 dogfooding 後に改訂予定）
+
+## 目的
+
+Row Level Security（RLS）や権限制御で、「見えるべき / 見えてはいけない」「書けるべき / 書けてはいけない」の両方をテストする。フロントの表示制御だけで満足せず、サーバー側 API / DB level で境界が破られないことを確認する。
+
+形名参同の「名」に権限境界の拒否ケースを含めるための観点設計プロンプト。
+
+## プロンプト本文
+
+```
+以下の権限制御仕様について、デシジョンテーブルで権限境界を整理し、許可される操作と拒否される操作の両方をテストしてください。
+
+## 仕様
+（例: 「ユーザーは自身が作成した記事を更新・削除できる。他人の記事は閲覧のみ可。管理者は全記事を更新・削除できる」）
+
+## 手順
+
+1. role を列挙（例: anonymous / user / owner / admin）
+2. 対象リソースの状態を列挙（例: 自分のリソース / 他人のリソース / 公開 / 非公開）
+3. 操作を列挙（read / create / update / delete）
+4. role × resource state × 操作 のマトリクスで「許可 / 拒否」を明示
+5. 各セルに対応するテストケースを生成
+6. **拒否ケースは API level でテスト**（フロントの非表示だけでは不十分）
+
+## 出力形式
+
+### Step 1: 権限マトリクス
+
+| role | resource | read | create | update | delete |
+|---|---|---|---|---|---|
+| anonymous | any | OK / NG | NG | NG | NG |
+| user | self | OK | OK | OK | OK |
+| user | others | OK / NG | NG | NG | NG |
+| admin | any | OK | OK | OK | OK |
+
+### Step 2: 拒否ケースのテスト（最重要）
+
+各 NG セルについて:
+- 該当 role / resource を使い、該当操作を試みる
+- 401 / 403 / 404 等の拒否応答を確認
+- DB / RLS 等のサーバー側 level で実際に拒否されることを確認（mock や middleware で擬似的に通さない）
+
+### Step 3: 許可ケースのテスト
+
+各 OK セルについて:
+- 該当 role / resource で該当操作が成功する
+
+## 制約
+
+- 拒否は **API 直叩き** でテストする（curl / supertest / API client）。UI 経由だけでは網羅性が不足
+- フロントの「ボタンを非表示」は UX 改善であって、セキュリティ対策ではない
+- RLS（Row Level Security）を使う場合、ポリシー単位で許可・拒否両方をテストする
+```
+
+## 利用例
+
+### 入力仕様
+> 記事は user_id で所有される。自分の記事は更新・削除可。他人の記事は閲覧のみ。admin は全記事を更新可能。
+
+### 期待される AI 出力
+
+```
+| role | 記事所有 | read | update | delete |
+|---|---|---|---|---|
+| anonymous | - | OK（公開のみ） | NG | NG |
+| user | self | OK | OK | OK |
+| user | others | OK（公開のみ） | NG | NG |
+| admin | any | OK | OK | NG（admin は削除権限なし） |
+```
+
+各セルのテスト:
+- `user (others) update 記事` → 403 / 404 を確認
+- DB-RLS test: 別 user_id でログインし、他人の記事を直接 UPDATE SQL → 0 rows affected または error
+
+## 隣接する思想
+
+- [`../docs/philosophy/qa-techniques.md`](../docs/philosophy/qa-techniques.md) §3. デシジョンテーブル — 権限マトリクスは特殊な DT
+- [`../docs/philosophy/test-pyramid.md`](../docs/philosophy/test-pyramid.md) §5. DB-RLS test 層
+- [`../docs/philosophy/given-when-then.md`](../docs/philosophy/given-when-then.md) — 拒否ケースを GWT で記述
+- [`../docs/philosophy/formal-name-match.md`](../docs/philosophy/formal-name-match.md) — 権限境界の「名」を機械検証可能化
+
+## カスタマイズ
+
+- **multi-tenant**: organization_id / tenant_id の境界もマトリクスに加える
+- **行レベル + 列レベル権限**: ある列だけ管理者にも見せないケースを別行で扱う
+- **時間依存権限**: 「公開予約日時前は所有者のみ閲覧」等は state-transition プロンプトと組み合わせる
+
+## 出典
+
+- Notion ページ: `35b68c677f4380bfa1ffeab248264e92` — テストフロー再設計（参照日 2026-05-13）の Supabase / RLS 観点
+- 補強: `7c531b165bab4b7ea2dce1782469ac52` — Supabase Testing 戦略（pgTAP, service_role を使わない検証）

package/package-templates/prompts/state-transition.md

@@ -0,0 +1,81 @@
+# state-transition プロンプト
+
+> **ステータス**: Draft v0.1（Phase 1 dogfooding 後に改訂予定）
+
+## 目的
+
+状態を持つ機能（注文ステータス・記事ライフサイクル・予約ワークフロー等）で、許可される遷移と**禁止される遷移**の両方をテストする。AI は許可遷移だけテストしがちなので、不正遷移の拒否確認を明示的に依頼する。
+
+形名参同の「名」に「不正遷移の拒否」を含めるための観点設計プロンプト。
+
+## プロンプト本文
+
+```
+以下のステータス仕様について、状態遷移表を作成し、許可遷移と禁止遷移の両方をテストしてください。
+
+## 仕様
+（例: 「注文ステータスは pending / confirmed / shipped / delivered / cancelled。pending → confirmed → shipped → delivered の順で進む。pending または confirmed からのみ cancelled へ遷移できる」）
+
+## 手順
+
+1. 状態リストを列挙
+2. 遷移表を作成（行: 遷移元、列: 遷移先、セル: 許可 / 禁止）
+3. 許可遷移のテストケースを生成
+4. 禁止遷移のテストケースを生成（**こちらが重要**）
+5. 各禁止遷移について、サーバー側（API / DB）で拒否されることを確認
+
+## 出力形式
+
+### Step 1: 状態遷移表
+
+| from \\ to | pending | confirmed | shipped | delivered | cancelled |
+|---|---|---|---|---|---|
+| pending | - | OK | NG | NG | OK |
+| confirmed | NG | - | OK | NG | OK |
+...
+
+### Step 2: テストコード
+
+- 許可遷移: 「pending → confirmed が成功する」「confirmed → shipped が成功する」...
+- 禁止遷移: 「pending → shipped が API で拒否される（4xx 応答）」「delivered → pending が拒否される」...
+
+## 制約
+
+- 全 N×N 通りの遷移を表に明示すること（自己遷移含む）
+- 禁止遷移は**サーバー側 API / DB level** で拒否されることを確認（フロントの非表示だけでは不十分）
+- 1 遷移 1 テストケース
+```
+
+## 利用例
+
+### 入力仕様
+> 記事ステータスは draft / review / published / archived。draft → review → published の順。published → archived は許可、archived → published は禁止。
+
+### 期待される AI 出力
+
+```
+| from \\ to | draft | review | published | archived |
+|---|---|---|---|---|
+| draft | - | OK | NG | NG |
+| review | OK | - | OK | NG |
+| published | NG | NG | - | OK |
+| archived | NG | NG | NG | - |
+```
+
+各セルに対応するテストケース（許可遷移 OK ケース + 禁止遷移の拒否ケース）。
+
+## 隣接する思想
+
+- [`../docs/philosophy/qa-techniques.md`](../docs/philosophy/qa-techniques.md) §4. 状態遷移テスト — 技法の理論
+- [`../docs/philosophy/given-when-then.md`](../docs/philosophy/given-when-then.md) — 遷移を GWT で記述する
+- [`../docs/philosophy/test-pyramid.md`](../docs/philosophy/test-pyramid.md) — DB-RLS 層と Integration 層の境界
+
+## カスタマイズ
+
+- **状態数が多い（10 以上）**: 表が肥大化。条件付き遷移（例: role 別の許可遷移）に切り出すと整理しやすい
+- **時間依存遷移**: 「予約日時を過ぎたら自動的に cancelled」等は別プロンプト（バッチ処理テスト）と組み合わせる
+
+## 出典
+
+- Notion ページ: `dc8774cd03c8490688b066c2b0179cac` — AI 駆動開発時代に押さえる QA 技法（参照日 2026-05-13）の「4. 状態遷移テスト」節
+- 一次資料: ISTQB Foundation Level Syllabus

package/package-templates/scripts/README.md

@@ -0,0 +1,78 @@
+# scripts/
+
+`ai:check` 系の薄い entry point スクリプト。配布される example。
+
+> **ステータス**: Draft v0.1（Phase 1 dogfooding 後に改訂予定）
+
+## 提供物
+
+```
+scripts/
+├── ai-check.sh         # full check（Static + Unit + Integration + Diagnostic + E2E）
+└── ai-check-fast.sh    # fast check（Static + Unit のみ、AI 内部ループ用）
+```
+
+## 思想
+
+形名参同（[`../docs/philosophy/formal-name-match.md`](../docs/philosophy/formal-name-match.md)）の「形」を取得する実体。
+
+- 「名」（成功基準）は `package.json` の `ai:check` / `ai:check:fast` スクリプトに定義
+- 「形」（実測値）はそれらを実行した出力
+- 本スクリプトは PM 抽象化と最小ロギングのみ担当し、ロジックは npm scripts に委譲する
+
+## 使い方
+
+### 直接実行
+```bash
+bash scripts/ai-check.sh
+bash scripts/ai-check-fast.sh
+```
+
+### PM 切り替え
+デフォルトは `pnpm`。`PM` 環境変数で上書き可:
+```bash
+PM=npm  bash scripts/ai-check.sh
+PM=yarn bash scripts/ai-check.sh
+PM=bun  bash scripts/ai-check.sh
+```
+
+### 直接 npm script を呼ぶ場合
+シェルスクリプトを使わず `pnpm` 直接呼びでも同等:
+```bash
+pnpm ai:check
+pnpm ai:check:fast
+```
+
+シェルスクリプトの利点:
+- PM 非依存（環境変数で切り替え）
+- 非 Node プロジェクトでも entry point として配置可能
+- 統一 logging プレフィックス（`[ai-check]` / `[ai-check-fast]`）
+
+## package.scripts.fragment.json との関係
+
+`ai:check` / `ai:check:fast` の中身は `../package.scripts.fragment.json` に定義される。
+利用者は自プロジェクトの `package.json` に scripts エントリをマージする。
+
+```
+scripts/ai-check.sh → ${PM} ai:check → package.json scripts.ai:check
+                                       (typecheck → lint → test → e2e:smoke 等を連鎖)
+```
+
+## CI 統合との関係
+
+[`../ci-examples/github-actions/ai-check.yml`](../ci-examples/github-actions/ai-check.yml) でも同じ `${PM} ai:check` を呼ぶ。
+ローカル（シェル）と CI（GitHub Actions）で**同じコマンド**が走る設計。
+
+## Claude Code Hook との関係
+
+[`../.claude/settings.hook-fragment.json`](../.claude/settings.hook-fragment.json) の Edit hook が `pnpm ai:check:fast` を呼び、Stop hook が `pnpm ai:check` を呼ぶ。
+シェル経由でも npm script 直接でも、最終的に同じスクリプトが走る。
+
+## カスタマイズ
+
+- timeout: シェルラッパーには timeout 設定なし。CI 側で `timeout-minutes` を設定する
+- 失敗時の自動修正ループ: 本スクリプトはスコープ外。AI への修正指示は上位の運用プロンプトで行う
+
+## 出典
+
+- Notion Doc #2（`c3e549660ca44005a20c4f6fdb54c8d5`、参照日 2026-05-13）の「## package.jsonに入れる推奨script」節

package/package-templates/scripts/ai-check-fast.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# ai-check-fast.sh — fast AI check entry point (Static + Unit のみ)
+#
+# 配布される example。AI 内部ループ（Claude Code の Edit hook）から呼ばれる軽量版。
+# Static check + Unit test までに限定し、E2E や Diagnostic（React Doctor 等）は含めない。
+# timeout 10 分以内で完走する想定。
+#
+# 詳細思想:
+#   - package-templates/docs/philosophy/formal-name-match.md §段階的導入 Phase A/B
+#   - Edit hook（fast）と PR Gate（full）のハイブリッド構成の片方
+#
+# PM 切り替え:
+#   ai-check.sh と同じ。PM 環境変数で上書き可。
+
+set -euo pipefail
+
+PM="${PM:-pnpm}"
+
+echo "[ai-check-fast] Running: ${PM} ai:check:fast"
+"${PM}" ai:check:fast

package/package-templates/scripts/ai-check.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# ai-check.sh — full AI check pipeline entry point
+#
+# 配布される example。利用者がコピーして自プロジェクトの scripts/ または bin/ に配置し、
+# `bash scripts/ai-check.sh` で呼ぶ薄いラッパー。
+#
+# 形名参同（package-templates/docs/philosophy/formal-name-match.md）:
+#   事前宣言した「名」（成功基準）と実測「形」（コマンド出力）を一括照合する。
+#   本スクリプトは「形」の取得を担当し、npm scripts の ai:check に委譲する。
+#
+# PM 切り替え:
+#   デフォルト pnpm。npm/yarn/bun を使う場合は PM 環境変数で上書き:
+#     PM=npm  bash ai-check.sh
+#     PM=yarn bash ai-check.sh
+#     PM=bun  bash ai-check.sh
+
+set -euo pipefail
+
+PM="${PM:-pnpm}"
+
+echo "[ai-check] Running: ${PM} ai:check"
+"${PM}" ai:check

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ai-check-template",
+  "version": "0.2.0-alpha.0",
+  "description": "Templates and CLI for verifying, repairing, and safely merging AI-generated code.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": [
+    "ai",
+    "testing",
+    "verification",
+    "cli",
+    "templates",
+    "github-actions",
+    "claude-code"
+  ],
+  "homepage": "https://github.com/heidayo/ai-check-template#readme",
+  "bugs": {
+    "url": "https://github.com/heidayo/ai-check-template/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heidayo/ai-check-template.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ai-check-template": "bin/ai-check-template.mjs"
+  },
+  "scripts": {
+    "cli:help": "node bin/ai-check-template.mjs --help",
+    "test": "node --test tests/cli/*.test.mjs",
+    "test:cli": "node --test tests/cli/*.test.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package-templates/",
+    "docs/cli.md",
+    "README.md",
+    "README-ja.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli/ci-workflows.mjs

@@ -0,0 +1,104 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { scriptCommand, validatePackageManager } from "./package-manager.mjs";
+import { fromTemplates } from "./utils.mjs";
+
+export const DIRECT_CI_FILES = ["ai-check.yml", "ai-check-fast.yml"];
+export const REUSABLE_CI_FILES = ["ai-quality-reusable.yml", "ai-quality-call.yml"];
+
+const PACKAGE_MANAGERS = ["pnpm", "npm", "yarn", "bun"];
+
+const PNPM_SETUP_BLOCK = `      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile`;
+
+const SETUP_BLOCKS = {
+  pnpm: PNPM_SETUP_BLOCK,
+  npm: `      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci`,
+  yarn: `      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: yarn
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: yarn install --immutable`,
+  bun: `      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile`,
+};
+
+export function ciWorkflowFiles(ciMode) {
+  return ciMode === "direct"
+    ? DIRECT_CI_FILES
+    : ciMode === "reusable"
+      ? REUSABLE_CI_FILES
+      : [];
+}
+
+export function inactiveCiWorkflowFiles(ciMode) {
+  return ciMode === "direct"
+    ? REUSABLE_CI_FILES
+    : ciMode === "reusable"
+      ? DIRECT_CI_FILES
+      : [...DIRECT_CI_FILES, ...REUSABLE_CI_FILES];
+}
+
+export function ciWorkflowRelativePath(fileName) {
+  return path.join(".github", "workflows", fileName);
+}
+
+export async function renderedCiWorkflow(fileName, packageManager) {
+  const validatedPackageManager = validatePackageManager(packageManager);
+  const source = await fs.readFile(fromTemplates("ci-examples", "github-actions", fileName), "utf8");
+
+  if (DIRECT_CI_FILES.includes(fileName)) {
+    return renderDirectWorkflow(source, fileName, validatedPackageManager);
+  }
+
+  if (fileName === "ai-quality-call.yml") {
+    return renderReusableCaller(source, validatedPackageManager);
+  }
+
+  return source;
+}
+
+export async function isManagedCiWorkflowContent(fileName, content) {
+  const variants = await Promise.all(
+    PACKAGE_MANAGERS.map((packageManager) => renderedCiWorkflow(fileName, packageManager)),
+  );
+
+  return variants.includes(content);
+}
+
+function renderDirectWorkflow(source, fileName, packageManager) {
+  const scriptName = fileName === "ai-check-fast.yml" ? "ai:check:fast" : "ai:check";
+  const checkCommand = scriptCommand(packageManager, scriptName);
+
+  return source
+    .replace(PNPM_SETUP_BLOCK, SETUP_BLOCKS[packageManager])
+    .replaceAll(`pnpm ${scriptName}`, checkCommand);
+}
+
+function renderReusableCaller(source, packageManager) {
+  return source
+    .replace("package-manager: pnpm", `package-manager: ${packageManager}`)
+    .replace("check-command: pnpm ai:check", `check-command: ${scriptCommand(packageManager, "ai:check")}`);
+}

package/src/cli/claude-hooks.mjs

@@ -0,0 +1,94 @@
+import { scriptCommand, validatePackageManager } from "./package-manager.mjs";
+
+const MANAGED_COMMANDS = new Map([
+  ["pnpm ai:check:fast", "ai:check:fast"],
+  ["pnpm ai:check", "ai:check"],
+]);
+
+const MANAGED_SCRIPT_COMMANDS = new Set(
+  ["pnpm", "npm", "yarn", "bun"].flatMap((packageManager) => [
+    scriptCommand(packageManager, "ai:check:fast"),
+    scriptCommand(packageManager, "ai:check"),
+  ]),
+);
+
+export function renderClaudeHookSettings(fragment, packageManager) {
+  const validatedPackageManager = validatePackageManager(packageManager);
+
+  return {
+    ...fragment,
+    hooks: Object.fromEntries(
+      Object.entries(fragment.hooks ?? {}).map(([name, entries]) => [
+        name,
+        renderHookEntries(entries, validatedPackageManager),
+      ]),
+    ),
+  };
+}
+
+export function mergeRenderedClaudeHookEntries(currentEntries, expectedEntries) {
+  if (!Array.isArray(currentEntries)) {
+    return expectedEntries;
+  }
+
+  const customEntries = currentEntries
+    .map((entry) => customHookEntry(entry))
+    .filter(Boolean);
+
+  return [...expectedEntries, ...customEntries];
+}
+
+function renderHookEntries(entries, packageManager) {
+  if (!Array.isArray(entries)) {
+    return entries;
+  }
+
+  return entries.map((entry) => ({
+    ...entry,
+    hooks: Array.isArray(entry.hooks)
+      ? entry.hooks.map((hook) => renderHookCommand(hook, packageManager))
+      : entry.hooks,
+  }));
+}
+
+function renderHookCommand(hook, packageManager) {
+  if (!hook || typeof hook !== "object" || hook.type !== "command") {
+    return hook;
+  }
+
+  const scriptName = MANAGED_COMMANDS.get(hook.command);
+  if (!scriptName) {
+    return { ...hook };
+  }
+
+  return {
+    ...hook,
+    command: scriptCommand(packageManager, scriptName),
+  };
+}
+
+function customHookEntry(entry) {
+  if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks)) {
+    return null;
+  }
+
+  const hooks = entry.hooks.filter((hook) => !isManagedCommandHook(hook));
+  if (hooks.length === 0) {
+    return null;
+  }
+
+  return {
+    ...entry,
+    hooks,
+  };
+}
+
+function isManagedCommandHook(hook) {
+  return (
+    hook &&
+    typeof hook === "object" &&
+    hook.type === "command" &&
+    typeof hook.command === "string" &&
+    MANAGED_SCRIPT_COMMANDS.has(hook.command)
+  );
+}