@guardsmith/cli 0.2.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.ja.md +118 -0
  2. package/README.md +80 -87
  3. package/package.json +2 -2
package/README.ja.md ADDED
@@ -0,0 +1,118 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/novexar/Guardsmith/main/assets/logo.png" width="96" alt="GuardSmith logo">
3
+ </p>
4
+
5
+ <h1 align="center">@guardsmith/cli</h1>
6
+
7
+ <p align="center">
8
+ すべてのリポジトリに同じ AI 開発標準を配り、守られているかを<b>機械検証</b>する。<br>
9
+ <a href="https://github.com/novexar/Guardsmith">GuardSmith</a> の <code>guard</code> コマンド。
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="https://github.com/novexar/Guardsmith/blob/main/packages/cli/README.md">English</a> | 日本語
14
+ </p>
15
+
16
+ ---
17
+
18
+ GuardSmith は AI 開発標準(`CLAUDE.md`・agents・skills)を、ESLint がコードスタイルを
19
+ 扱うのと同じ方法——**配布できる config + linter**——で扱います。本パッケージはその CLI です。
20
+
21
+ Node.js 20+ が必要です。
22
+
23
+ ## インストール
24
+
25
+ ```bash
26
+ npx @guardsmith/cli <command> # 単発実行
27
+ # または
28
+ pnpm add -D @guardsmith/cli # PJ ごとに導入。以後: pnpm guard <command>
29
+ ```
30
+
31
+ ## クイックスタート
32
+
33
+ ```bash
34
+ # 新規プロジェクト — 標準マスターから展開
35
+ # (CLAUDE.md・agents・skills・docs・Docker ローカル CI・デザイン仕様)
36
+ npx @guardsmith/cli new my-project
37
+
38
+ # 既存プロジェクト — ポリシーファイルのみ生成
39
+ npx @guardsmith/cli init
40
+
41
+ # 検証 (exit 1 = 違反あり: 未初期化テンプレ、
42
+ # 契約見出しの破壊、資格情報の混入、drift など)
43
+ npx @guardsmith/cli lint
44
+
45
+ # 標準マスターからの乖離(drift)を表示し、復元する
46
+ npx @guardsmith/cli sync # dry-run
47
+ npx @guardsmith/cli sync --write # 復元(PJ 固有セクションは保全)
48
+
49
+ # ルールの説明 / バージョン表示
50
+ npx @guardsmith/cli explain claude-md/thin-diff
51
+ npx @guardsmith/cli version
52
+ ```
53
+
54
+ | コマンド | 主なフラグ |
55
+ | ------------------------- | ---------------------------------------------------------------------------------------------- |
56
+ | `guard new <dir>` | — |
57
+ | `guard init` | — |
58
+ | `guard lint` | `--root`、`--policy`、`--format console\|sarif\|json`、`--out`、`--no-cache`、`--no-gitignore` |
59
+ | `guard sync` | `--root`、`--policy`、`--write`、`--no-cache`、`--no-gitignore` |
60
+ | `guard explain <rule-id>` | — |
61
+ | `guard version` | — |
62
+
63
+ 各 check は「**コミットされうるファイル**」を対象にします。既定で `.gitignore`(入れ子も)に
64
+ 追従し、`.git/` は常に除外するため、`secret-scan` は `.claude/settings.local.json` の中身を
65
+ 報告せず、`file-exists` は `.gitignore` 対象のパスを「存在しない」と扱います。さらにポリシーの
66
+ `ignore`(glob)を除外し、除外対象は結果フィルタではなく走査の時点で枝刈りします。
67
+ `--no-gitignore` で全走査に戻せます。
68
+
69
+ `guard new` の後は Claude Code でプロジェクトを開いてください — 同梱の `init-project`
70
+ スキルがインタビューを行い、テンプレートを具体化します。初期化が本当に完了すると
71
+ `guard lint` が PASS します。
72
+
73
+ ## ポリシーの要点
74
+
75
+ ```yaml
76
+ # guard.policy.yaml
77
+ version: 1
78
+ target: claude-code
79
+ extends:
80
+ - github:novexar/guardsmith//presets/baseline.yaml@v0.6.0 # tag pinning is mandatory
81
+ # Projects with a frontend also add:
82
+ # - github:novexar/guardsmith//presets/frontend.yaml@v0.6.0
83
+ ignore: [] # 全走査から除外する glob(extends 間で連結される)
84
+ rules: [] # add or override (redefining an id overrides it)
85
+ exemptions: [] # time-boxed waivers: reason + approved_by + expires required
86
+ ```
87
+
88
+ `extends` は OSS baseline → private 組織 overlay → PJ ごとのポリシー、と合成されます。
89
+ private リポジトリは `GITHUB_TOKEN` 環境変数で取得されるため、組織固有ルールが
90
+ GitHub の外に出ることはありません。期限切れの例外(exemption)は error として表面化します
91
+ — 黙って永久に免除されることはありません。
92
+
93
+ ## CI での強制
94
+
95
+ [GuardSmith Lint Action](https://github.com/marketplace/actions/guardsmith-lint) を
96
+ workflow に 1 行追加:
97
+
98
+ ```yaml
99
+ - uses: novexar/Guardsmith@v0.6.0
100
+ ```
101
+
102
+ 違反した PR はサマリコメントと SARIF レポート付きで失敗します。閉域網などの環境では
103
+ [GitHub Releases](https://github.com/novexar/Guardsmith/releases) に添付された
104
+ 自己完結バンドルのみで実行できます(`source: release` / `node guard.mjs`)—
105
+ npm レジストリへのアクセスは不要です。
106
+
107
+ ## ドキュメント
108
+
109
+ - はじめに・コンセプト: https://github.com/novexar/Guardsmith
110
+ - 3層ポリシー設計: https://github.com/novexar/Guardsmith/blob/main/docs/LAYERING.ja.md
111
+ - 標準更新への追随(リリースごとのチェックリスト): https://github.com/novexar/Guardsmith/tree/main/docs/migration
112
+
113
+ ## ライセンス
114
+
115
+ Apache-2.0
116
+
117
+ サードパーティライセンス: 依存パッケージは npm 経由で各自のライセンスに従います。
118
+ オフライン用リリースバンドルには `THIRD-PARTY-NOTICES.md` を同梱しています。
package/README.md CHANGED
@@ -1,126 +1,119 @@
1
- # @guardsmith/cli
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/novexar/Guardsmith/main/assets/logo.png" width="96" alt="GuardSmith logo">
3
+ </p>
2
4
 
3
- **AI開発標準の配布と統制を1つにしたガバナンスツールキット GuardSmith の CLI(`guard` コマンド)。**
4
- 標準(CLAUDE.md / agents / skills のテンプレート)を配り、守られているかを機械検証します —
5
- 「ESLint + 公式config」の関係を AI コーディング標準に対して提供します。
5
+ <h1 align="center">@guardsmith/cli</h1>
6
6
 
7
- _English follows Japanese._
7
+ <p align="center">
8
+ Ship the same AI coding standards to every repository — and <b>machine-verify</b> they are followed.<br>
9
+ The <code>guard</code> command of <a href="https://github.com/novexar/Guardsmith">GuardSmith</a>.
10
+ </p>
8
11
 
9
- ## インストール
12
+ <p align="center">
13
+ English | <a href="https://github.com/novexar/Guardsmith/blob/main/packages/cli/README.ja.md">日本語</a>
14
+ </p>
15
+
16
+ ---
17
+
18
+ GuardSmith treats AI development standards (`CLAUDE.md`, agents, skills) the way ESLint
19
+ treats code style: **a distributable config plus a linter**. This package provides the CLI.
20
+
21
+ Requires Node.js 20+.
22
+
23
+ ## Install
10
24
 
11
25
  ```bash
12
- npx @guardsmith/cli <command> # 都度実行
13
- # または
14
- pnpm add -D @guardsmith/cli # プロジェクトに導入して pnpm guard <command>
26
+ npx @guardsmith/cli <command> # one-off
27
+ # or
28
+ pnpm add -D @guardsmith/cli # per project, then: pnpm guard <command>
15
29
  ```
16
30
 
17
- Node.js 20 以上が必要です。
18
-
19
- ## クイックスタート
31
+ ## Quick start
20
32
 
21
33
  ```bash
22
- # 新規プロジェクト: 標準雛形(CLAUDE.md / agents / skills / docs)から展開
34
+ # New project — scaffold from the standards master
35
+ # (CLAUDE.md, agents, skills, docs, Docker-based local CI, design spec)
23
36
  npx @guardsmith/cli new my-project
24
37
 
25
- # 既存プロジェクト: 検証ポリシーだけ生成
38
+ # Existing project — generate the policy file only
26
39
  npx @guardsmith/cli init
27
40
 
28
- # 検証(プレースホルダ残置・契約見出し欠落・資格情報混入などを検出。exit 1 = error)
41
+ # Verify (exit 1 = violations found: uninitialized templates,
42
+ # broken contract headings, leaked credentials, drift, ...)
29
43
  npx @guardsmith/cli lint
30
44
 
31
- # 配布ファイルのマスター乖離(drift)を確認 → 復元
45
+ # Show drift against the standards master, then repair it
32
46
  npx @guardsmith/cli sync # dry-run
33
- npx @guardsmith/cli sync --write # 適用
47
+ npx @guardsmith/cli sync --write # restore (project-owned sections are preserved)
34
48
 
35
- # ルールの意図を表示
49
+ # Explain a rule / show versions
36
50
  npx @guardsmith/cli explain claude-md/thin-diff
51
+ npx @guardsmith/cli version
37
52
  ```
38
53
 
39
- ## ポリシー(guard.policy.yaml)
54
+ | Command | Key flags |
55
+ | ------------------------- | ---------------------------------------------------------------------------------------------- |
56
+ | `guard new <dir>` | — |
57
+ | `guard init` | — |
58
+ | `guard lint` | `--root`, `--policy`, `--format console\|sarif\|json`, `--out`, `--no-cache`, `--no-gitignore` |
59
+ | `guard sync` | `--root`, `--policy`, `--write`, `--no-cache`, `--no-gitignore` |
60
+ | `guard explain <rule-id>` | — |
61
+ | `guard version` | — |
40
62
 
41
- ```yaml
42
- version: 1
43
- target: claude-code
44
- extends:
45
- - github:novexar/guardsmith//presets/baseline.yaml@v0.2.1 # タグ固定必須
46
- rules: [] # 追加・上書き(同idで再定義=上書き)
47
- exemptions: [] # 期限付き例外(expires + approved_by 必須。期限切れは error)
48
- ```
63
+ Checks operate on **files that could be committed**: `.gitignore` (nested files included)
64
+ is honoured by default and `.git/` is always excluded, so `secret-scan` never reports a
65
+ value inside `.claude/settings.local.json`, and `file-exists` treats a `.gitignore`'d path
66
+ as missing. The policy's `ignore` globs are excluded on top of that, and excluded trees are
67
+ pruned during traversal rather than filtered afterwards. `--no-gitignore` restores the full
68
+ scan when you want to audit ignored files.
49
69
 
50
- `extends: github:owner/repo[//path]@tag` により OSS baseline → 組織 private overlay → 各プロジェクト
51
- の3層合成ができます。private リポジトリは `GITHUB_TOKEN` 環境変数で取得します。
70
+ After `guard new`, open the project with Claude Code — the bundled `init-project` skill
71
+ interviews you and concretizes the templates. `guard lint` passes once initialization
72
+ is genuinely complete.
52
73
 
53
- ## CI(GitHub Action)
74
+ ## Policy in a nutshell
54
75
 
55
76
  ```yaml
56
- # .github/workflows/guard.yml
57
- name: GuardSmith
58
- on: [pull_request]
59
- permissions:
60
- contents: read
61
- pull-requests: write
62
- jobs:
63
- guard:
64
- runs-on: ubuntu-latest
65
- steps:
66
- - uses: actions/checkout@v4
67
- - uses: novexar/Guardsmith@v0.4.0
77
+ # guard.policy.yaml
78
+ version: 1
79
+ target: claude-code
80
+ extends:
81
+ - github:novexar/guardsmith//presets/baseline.yaml@v0.6.0 # tag pinning is mandatory
82
+ # Projects with a frontend also add:
83
+ # - github:novexar/guardsmith//presets/frontend.yaml@v0.6.0
84
+ ignore: [] # globs excluded from every scan (concatenated across extends layers)
85
+ rules: [] # add or override (redefining an id overrides it)
86
+ exemptions: [] # time-boxed waivers: reason + approved_by + expires required
68
87
  ```
69
88
 
70
- 違反があるとジョブが失敗し、レポートが Job Summary と PR コメントに載ります(SARIF 出力対応)。
71
-
72
- ## ドキュメント
73
-
74
- - リポジトリ / 導入ガイド: https://github.com/novexar/Guardsmith
75
- - 3層 overlay 設計: https://github.com/novexar/Guardsmith/blob/main/docs/LAYERING.md
89
+ `extends` composes OSS baseline → private organization overlay → per-project policy.
90
+ Private repositories are fetched with the `GITHUB_TOKEN` environment variable, so
91
+ organization-specific rules never leave your GitHub. Expired exemptions surface as
92
+ errors — nothing is waived silently forever.
76
93
 
77
- ---
78
-
79
- # English
80
-
81
- **CLI (`guard`) for GuardSmith — a governance toolkit that unifies distribution and
82
- enforcement of AI development standards.** It distributes standards (templates for
83
- `CLAUDE.md` / agents / skills) and machine-verifies that projects follow them — the
84
- "ESLint + official config" relationship, applied to AI coding standards.
85
-
86
- ## Install
87
-
88
- ```bash
89
- npx @guardsmith/cli <command> # one-off
90
- # or
91
- pnpm add -D @guardsmith/cli # per project, then: pnpm guard <command>
92
- ```
93
-
94
- Requires Node.js 20+.
94
+ ## CI enforcement
95
95
 
96
- ## Quick start
96
+ Add one line to your workflow using the
97
+ [GuardSmith Lint Action](https://github.com/marketplace/actions/guardsmith-lint):
97
98
 
98
- ```bash
99
- npx @guardsmith/cli new my-project # scaffold a new project from the standards master
100
- npx @guardsmith/cli init # existing project: generate guard.policy.yaml only
101
- npx @guardsmith/cli lint # verify (exit 1 = errors found)
102
- npx @guardsmith/cli sync # show drift against the master (dry-run)
103
- npx @guardsmith/cli sync --write # repair drift
104
- npx @guardsmith/cli explain <rule> # explain a rule
99
+ ```yaml
100
+ - uses: novexar/Guardsmith@v0.6.0
105
101
  ```
106
102
 
107
- ## Policy (guard.policy.yaml)
108
-
109
- `extends: github:owner/repo[//path]@tag` chains OSS baseline → private org overlay →
110
- per-project policy (remote refs must pin a tag; private repos are fetched with the
111
- `GITHUB_TOKEN` environment variable). Exemptions require `expires` + `approved_by`,
112
- and expired exemptions surface as errors.
113
-
114
- ## CI enforcement
115
-
116
- Use the GitHub Action `novexar/Guardsmith@v0.4.0` — on violations the job fails, the
117
- report lands in the Job Summary and a PR comment, and a SARIF report is produced.
103
+ Violating PRs fail with a summary comment and a SARIF report. Air-gapped environments can
104
+ run entirely from the self-contained bundle attached to
105
+ [GitHub Releases](https://github.com/novexar/Guardsmith/releases) (`source: release` /
106
+ `node guard.mjs`) — no npm registry access required.
118
107
 
119
108
  ## Documentation
120
109
 
121
- - Repository / getting started: https://github.com/novexar/Guardsmith
122
- - 3-layer overlay design: https://github.com/novexar/Guardsmith/blob/main/docs/LAYERING.md
110
+ - Getting started & concepts: https://github.com/novexar/Guardsmith
111
+ - 3-layer policy design: https://github.com/novexar/Guardsmith/blob/main/docs/LAYERING.md
112
+ - Upgrading standards (per-release checklist): https://github.com/novexar/Guardsmith/tree/main/docs/migration
123
113
 
124
114
  ## License
125
115
 
126
116
  Apache-2.0
117
+
118
+ Third-party licenses: dependencies carry their own licenses via npm; the offline release
119
+ bundle ships with a `THIRD-PARTY-NOTICES.md`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guardsmith/cli",
3
- "version": "0.2.2",
3
+ "version": "0.5.0",
4
4
  "description": "GuardSmith CLI — the guard binary (init / lint / sync / new / explain)",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -19,6 +19,6 @@
19
19
  "bin"
20
20
  ],
21
21
  "dependencies": {
22
- "@guardsmith/core": "^0.2.2"
22
+ "@guardsmith/core": "^0.5.0"
23
23
  }
24
24
  }