@guardsmith/cli 0.2.2 → 0.3.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 +102 -0
  2. package/README.md +63 -87
  3. package/package.json +2 -2
package/README.ja.md ADDED
@@ -0,0 +1,102 @@
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
+ `guard new` の後は Claude Code でプロジェクトを開いてください — 同梱の `init-project`
55
+ スキルがインタビューを行い、テンプレートを具体化します。初期化が本当に完了すると
56
+ `guard lint` が PASS します。
57
+
58
+ ## ポリシーの要点
59
+
60
+ ```yaml
61
+ # guard.policy.yaml
62
+ version: 1
63
+ target: claude-code
64
+ extends:
65
+ - github:novexar/guardsmith//presets/baseline.yaml@v0.5.1 # tag pinning is mandatory
66
+ # Projects with a frontend also add:
67
+ # - github:novexar/guardsmith//presets/frontend.yaml@v0.5.1
68
+ rules: [] # add or override (redefining an id overrides it)
69
+ exemptions: [] # time-boxed waivers: reason + approved_by + expires required
70
+ ```
71
+
72
+ `extends` は OSS baseline → private 組織 overlay → PJ ごとのポリシー、と合成されます。
73
+ private リポジトリは `GITHUB_TOKEN` 環境変数で取得されるため、組織固有ルールが
74
+ GitHub の外に出ることはありません。期限切れの例外(exemption)は error として表面化します
75
+ — 黙って永久に免除されることはありません。
76
+
77
+ ## CI での強制
78
+
79
+ [GuardSmith Lint Action](https://github.com/marketplace/actions/guardsmith-lint) を
80
+ workflow に 1 行追加:
81
+
82
+ ```yaml
83
+ - uses: novexar/Guardsmith@v0.5.1
84
+ ```
85
+
86
+ 違反した PR はサマリコメントと SARIF レポート付きで失敗します。閉域網などの環境では
87
+ [GitHub Releases](https://github.com/novexar/Guardsmith/releases) に添付された
88
+ 自己完結バンドルのみで実行できます(`source: release` / `node guard.mjs`)—
89
+ npm レジストリへのアクセスは不要です。
90
+
91
+ ## ドキュメント
92
+
93
+ - はじめに・コンセプト: https://github.com/novexar/Guardsmith
94
+ - 3層ポリシー設計: https://github.com/novexar/Guardsmith/blob/main/docs/LAYERING.ja.md
95
+ - 標準更新への追随(リリースごとのチェックリスト): https://github.com/novexar/Guardsmith/tree/main/docs/migration
96
+
97
+ ## ライセンス
98
+
99
+ Apache-2.0
100
+
101
+ サードパーティライセンス: 依存パッケージは npm 経由で各自のライセンスに従います。
102
+ オフライン用リリースバンドルには `THIRD-PARTY-NOTICES.md` を同梱しています。
package/README.md CHANGED
@@ -1,126 +1,102 @@
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
+ After `guard new`, open the project with Claude Code — the bundled `init-project` skill
55
+ interviews you and concretizes the templates. `guard lint` passes once initialization
56
+ is genuinely complete.
57
+
58
+ ## Policy in a nutshell
40
59
 
41
60
  ```yaml
61
+ # guard.policy.yaml
42
62
  version: 1
43
63
  target: claude-code
44
64
  extends:
45
- - github:novexar/guardsmith//presets/baseline.yaml@v0.2.1 # タグ固定必須
46
- rules: [] # 追加・上書き(同idで再定義=上書き)
47
- exemptions: [] # 期限付き例外(expires + approved_by 必須。期限切れは error)
48
- ```
49
-
50
- `extends: github:owner/repo[//path]@tag` により OSS baseline → 組織 private overlay → 各プロジェクト
51
- の3層合成ができます。private リポジトリは `GITHUB_TOKEN` 環境変数で取得します。
52
-
53
- ## CI(GitHub Action)
54
-
55
- ```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
65
+ - github:novexar/guardsmith//presets/baseline.yaml@v0.5.1 # tag pinning is mandatory
66
+ # Projects with a frontend also add:
67
+ # - github:novexar/guardsmith//presets/frontend.yaml@v0.5.1
68
+ rules: [] # add or override (redefining an id overrides it)
69
+ exemptions: [] # time-boxed waivers: reason + approved_by + expires required
68
70
  ```
69
71
 
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
76
-
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
- ```
72
+ `extends` composes OSS baseline → private organization overlay → per-project policy.
73
+ Private repositories are fetched with the `GITHUB_TOKEN` environment variable, so
74
+ organization-specific rules never leave your GitHub. Expired exemptions surface as
75
+ errors — nothing is waived silently forever.
93
76
 
94
- Requires Node.js 20+.
77
+ ## CI enforcement
95
78
 
96
- ## Quick start
79
+ Add one line to your workflow using the
80
+ [GuardSmith Lint Action](https://github.com/marketplace/actions/guardsmith-lint):
97
81
 
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
82
+ ```yaml
83
+ - uses: novexar/Guardsmith@v0.5.1
105
84
  ```
106
85
 
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.
86
+ Violating PRs fail with a summary comment and a SARIF report. Air-gapped environments can
87
+ run entirely from the self-contained bundle attached to
88
+ [GitHub Releases](https://github.com/novexar/Guardsmith/releases) (`source: release` /
89
+ `node guard.mjs`) — no npm registry access required.
118
90
 
119
91
  ## Documentation
120
92
 
121
- - Repository / getting started: https://github.com/novexar/Guardsmith
122
- - 3-layer overlay design: https://github.com/novexar/Guardsmith/blob/main/docs/LAYERING.md
93
+ - Getting started & concepts: https://github.com/novexar/Guardsmith
94
+ - 3-layer policy design: https://github.com/novexar/Guardsmith/blob/main/docs/LAYERING.md
95
+ - Upgrading standards (per-release checklist): https://github.com/novexar/Guardsmith/tree/main/docs/migration
123
96
 
124
97
  ## License
125
98
 
126
99
  Apache-2.0
100
+
101
+ Third-party licenses: dependencies carry their own licenses via npm; the offline release
102
+ 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.3.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.3.0"
23
23
  }
24
24
  }