@nto300002/devguard

v0.1.4

Published

5 hours ago

Pre-commit and pre-push self-review CLI for AI-assisted development.

0High
0Medium
0Low

nto300002

DevGuard

DevGuardは、git commit や git push の前に危険な変更を検出し、開発者が一度立ち止まって確認できるようにする TypeScript + Node.js 製のCLIツールです。

AIコーディングやADHD傾向のある開発フローでは、コード品質そのものよりも「確認漏れ」が問題になりがちです。DevGuardは、commit粒度の粗さ、debug logの消し忘れ、環境変数やSecretsの確認漏れ、Issueスコープ外のDB/config変更、レビュー前確認の曖昧さをGit操作前に可視化します。

コンセプト

DevGuardは、AI時代のpre-commit / pre-push型セルフレビュー支援ツールです。

Copilotのようにコードを書くツールではなく、レビュー担当者を置き換えるものでもありません。Git操作の直前に差分を解析し、「何を変更したか」「何が危険か」「人間がまだ確認すべきことは何か」を説明できる状態に整えるためのガードです。

MVPスコープ

MVPでは以下に注力します。

任意のサブディレクトリからのGit root検出
Git root相対パスへの正規化
.devguard.yml の読み込みとdefault config
devguard doctor
devguard check --staged
devguard push-check
defaultBranch...HEAD 差分解析
keyword rule
厳しめのdebug log検出
reason必須の抑制コメント
環境変数 / Secrets の整合性チェック
Issueスコープチェック
手動テスト確認todo
AIエージェント向け確認ブロック
pre-commit / pre-push hook導入

MVPでは、GitHub OAuth、GitHub Secretsの実在確認、GitHub Issue本文の取得、Web UI、VS Code拡張、AST解析、自動修正、AI生成コードの正しさ判定は扱いません。

対象技術

初期preset:

TypeScript
Python
PHP
Next.js
FastAPI

その他の技術スタックもdefault keyword databaseには含まれる場合がありますが、MVPの正式presetとしては有効化しません。

コマンド

devguard doctor
devguard init
devguard check --staged
devguard check --staged-diff
devguard check --worktree-diff
devguard check --all-diff
devguard push-check
devguard install-hooks

インストール

npm公開版をグローバルインストールする場合:

npm install -g @nto300002/devguard

インストール後は devguard コマンドを使えます。

devguard --help
devguard doctor

一度だけ実行する場合:

npx @nto300002/devguard doctor
npx @nto300002/devguard check --staged
npx @nto300002/devguard check --staged-diff
npx @nto300002/devguard check --worktree-diff
npx @nto300002/devguard check --all-diff

GitHub Releaseからtarballをダウンロードして導入する場合:

npm install -g ./nto300002-devguard-0.1.0.tgz

ローカルインストール

このリポジトリからローカル開発用に使う場合:

npm install
npm run build
npm link

link後は、ローカル環境で devguard コマンドを使えます。

devguard --help
devguard doctor

linkを解除する場合:

npm unlink -g @nto300002/devguard

ローカルでの使い方

staged差分をcommit前に確認します。

git add <files>
devguard check --staged

staged差分のファイル数・変更行数を強めに意識して確認する場合:

devguard check --staged-diff

まだ git add していない作業ツリー差分を確認する場合:

devguard check --worktree-diff

staged / unstaged / untracked をまとめて確認する場合:

devguard check --all-diff

差分確認コマンドの使い分け:

check --staged: commit直前のstaged差分を確認
check --staged-diff: staged差分に加えてPRサイズ目安を強調
check --worktree-diff: git add 前のunstaged / untracked差分を確認
check --all-diff: HEADから見たstaged / unstaged / untracked差分をまとめて確認

差分サイズの目安:

1-5 files / <=150 changed lines: compact PR
6-10 files or 151-300 changed lines: consider splitting
11+ files or 301+ changed lines: split into smaller PRs

branch全体をpush前に確認します。

devguard push-check --agent-block

現在のリポジトリにGit hookを導入します。

devguard install-hooks

導入されるhookは以下を実行します。

pre-commit: npx @nto300002/devguard check --staged
pre-push: npx @nto300002/devguard push-check --agent-block

packageを公開せずにローカル開発版でhookを試す場合は、DEVGUARD_BIN で実行コマンドを差し替えられます。

DEVGUARD_BIN="node /absolute/path/to/DevGuard/dist/cli.js" git commit -m "test"

現在のセキュリティ検出

DevGuardはdefault keyword databaseで以下のセキュリティ関連パターンを検出します。

console.log(user) のような変数debug log
API_KEY、TOKEN、PASSWORD、DATABASE_URL、OPENAI_API_KEY などのsecretらしい名前
${{ secrets.STRIPE_SECRET_KEY }} のようなGitHub Actions secret参照
eval(、innerHTML、dangerouslySetInnerHTML などの危険API
browser-storage-risk ruleによる localStorage / sessionStorage 使用

Hookの挙動

pre-commit では以下を実行します。

npx @nto300002/devguard check --staged

pre-push では以下を実行します。

npx @nto300002/devguard push-check --agent-block

High riskのcommit findingがある場合はcommitを停止します。High riskのpush findingがある場合はpushを停止します。

ドキュメント

MVP完成条件

TypeScript、Python、PHP、Next.js、FastAPIのプロジェクトで、危険なlog、環境変数 / Secrets追加、スコープ外DB/config変更をcommit前・push前に安定して検出できることをMVP完成条件とします。