@point-seven-studio/jq-groundcrew 0.0.0-stage → 0.1.1
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.
- package/LICENSE +202 -0
- package/NOTICE +2 -0
- package/README.md +93 -2
- package/dist/groundcrew.mjs +604 -0
- package/package.json +50 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
package/NOTICE
ADDED
package/README.md
CHANGED
|
@@ -1,3 +1,94 @@
|
|
|
1
|
-
#
|
|
1
|
+
# JQ Groundcrew
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The setup check for Claude Code.
|
|
4
|
+
|
|
5
|
+
Groundcrew reads how Claude Code is set up for a project and shows you what to fix. Each fix comes with a prompt you can copy and paste into Claude Code.
|
|
6
|
+
|
|
7
|
+
It runs on your machine. It sends nothing anywhere.
|
|
8
|
+
|
|
9
|
+
## Run it
|
|
10
|
+
|
|
11
|
+
In the folder of a project:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npx @point-seven-studio/jq-groundcrew
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Then open <http://127.0.0.1:4317>. Refresh the page to check again after a change.
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npx @point-seven-studio/jq-groundcrew path/to/project # check another folder
|
|
21
|
+
npx @point-seven-studio/jq-groundcrew --html report.html # write the page to a file
|
|
22
|
+
npx @point-seven-studio/jq-groundcrew --json # print the report
|
|
23
|
+
npx @point-seven-studio/jq-groundcrew --port 5000 # serve on another port
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
It needs Node 18 or later. It has no dependency.
|
|
27
|
+
|
|
28
|
+
## In CI
|
|
29
|
+
|
|
30
|
+
From version 0.1.1, `--fail-on fail` exits with code 1 when any check fails. `--fail-on warn` also counts a warning. The report still prints to stdout, and each counted check is named on stderr.
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
npx @point-seven-studio/jq-groundcrew@0.1.1 --json --fail-on fail
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Pin the version, so a new check cannot fail your build overnight. Running it only when the setup changes (`CLAUDE.md`, `.claude/`, `.env*`) is enough.
|
|
37
|
+
|
|
38
|
+
Not every check means something in CI. A fresh clone has no `.env` file, because those are ignored by git, so the secrets check passes there whether or not a rule protects them. Run that one on a developer's machine. In CI the useful checks are the ones about files in the repository: `CLAUDE.md` growing past its target, a hook being removed, and a rule that approves every command.
|
|
39
|
+
|
|
40
|
+
## What it checks
|
|
41
|
+
|
|
42
|
+
**Setup: what loads into every session, and what runs without being asked**
|
|
43
|
+
|
|
44
|
+
- The length of each `CLAUDE.md`, against the target in the Claude Code docs of under 200 lines per file.
|
|
45
|
+
- Whether the auto memory index is longer than the part that loads.
|
|
46
|
+
- Whether any hook is configured.
|
|
47
|
+
- Whether any command is pre-approved.
|
|
48
|
+
- Your skills, subagents, custom commands and MCP servers, as plain facts.
|
|
49
|
+
|
|
50
|
+
**Guardrails: what the agent may reach, and what stops it**
|
|
51
|
+
|
|
52
|
+
- Whether a deny rule keeps the agent from reading secret files such as `.env`. This fails only if such a file exists and no rule covers it.
|
|
53
|
+
- Whether an allow rule approves every shell command.
|
|
54
|
+
- The permission mode.
|
|
55
|
+
- Whether the sandbox is on.
|
|
56
|
+
- How many folders outside the project the agent can reach.
|
|
57
|
+
- How long session transcripts are kept.
|
|
58
|
+
|
|
59
|
+
**Verification: who checks the work when the agent says it is done**
|
|
60
|
+
|
|
61
|
+
- Whether the agent can run a test, lint, type-check or build command without asking.
|
|
62
|
+
- Whether a hook runs when the agent finishes. A Stop hook can send it back to keep working.
|
|
63
|
+
- Whether each subagent is limited to the tools its job needs.
|
|
64
|
+
|
|
65
|
+
Each check links the page of Anthropic's Claude Code documentation it rests on. Advice that is ours, and not the docs', says "our suggestion".
|
|
66
|
+
|
|
67
|
+
## What it reads, and what it does not
|
|
68
|
+
|
|
69
|
+
It reads:
|
|
70
|
+
|
|
71
|
+
- the Claude Code settings files (user, project, local and managed);
|
|
72
|
+
- `CLAUDE.md` files, to count their lines;
|
|
73
|
+
- the names of your skills, subagents, commands and MCP servers;
|
|
74
|
+
- the names of files that usually hold secrets, to tell you whether a rule protects them.
|
|
75
|
+
|
|
76
|
+
It never opens a secrets file. It never reads a session transcript. The page lists every file it read.
|
|
77
|
+
|
|
78
|
+
The page has one small script, which copies a prompt to your clipboard when you press Copy. It loads nothing from the network.
|
|
79
|
+
|
|
80
|
+
## The prompts
|
|
81
|
+
|
|
82
|
+
A suggested prompt asks Claude Code to show its plan or its diff before it changes a file. Read that before you approve it. Groundcrew itself changes nothing.
|
|
83
|
+
|
|
84
|
+
## Limits
|
|
85
|
+
|
|
86
|
+
- It covers Claude Code only.
|
|
87
|
+
- It checks setup. It does not look at how a session went.
|
|
88
|
+
- The checks follow the Claude Code documentation as it stood on 2026-11-14. The documentation can change.
|
|
89
|
+
|
|
90
|
+
## About
|
|
91
|
+
|
|
92
|
+
Made by Point Seven Studio. Unofficial: not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are Anthropic's names for their products.
|
|
93
|
+
|
|
94
|
+
Licence: Apache-2.0. See the LICENSE file.
|
|
@@ -0,0 +1,604 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// src/groundcrew-cli.ts
|
|
4
|
+
import { existsSync as existsSync2, writeFileSync } from "fs";
|
|
5
|
+
import { createServer } from "http";
|
|
6
|
+
import path2 from "path";
|
|
7
|
+
|
|
8
|
+
// src/groundcrew-core.ts
|
|
9
|
+
var DOCS = "https://code.claude.com/docs/en";
|
|
10
|
+
var MEMORY_LINE_TARGET = 200;
|
|
11
|
+
var MEMORY_LINE_FAIL = 400;
|
|
12
|
+
var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
|
|
13
|
+
var all = (files, pick) => files.flatMap(pick);
|
|
14
|
+
function deniesSecrets(rule) {
|
|
15
|
+
return /^Read\(/.test(rule) && /\.env|secret|credential|\.pem|\.key\b|id_rsa/i.test(rule);
|
|
16
|
+
}
|
|
17
|
+
function allowsEveryCommand(rule) {
|
|
18
|
+
return /^Bash(\(\s*(\*|:\*|\*\*)?\s*\))?$/.test(rule.trim());
|
|
19
|
+
}
|
|
20
|
+
function memoryChecks(facts) {
|
|
21
|
+
const source = `${DOCS}/memory.md`;
|
|
22
|
+
if (!facts.memory.length) {
|
|
23
|
+
return [
|
|
24
|
+
{
|
|
25
|
+
id: "memory-exists",
|
|
26
|
+
group: "setup",
|
|
27
|
+
title: "Project instructions",
|
|
28
|
+
status: "warn",
|
|
29
|
+
detail: "No CLAUDE.md or AGENTS.md was found for this project.",
|
|
30
|
+
fix: "Run /init to create one, then cut it down to the lines that prevent a mistake.",
|
|
31
|
+
source
|
|
32
|
+
}
|
|
33
|
+
];
|
|
34
|
+
}
|
|
35
|
+
const checks = facts.memory.map((file) => {
|
|
36
|
+
const status = file.lines > MEMORY_LINE_FAIL ? "fail" : file.lines > MEMORY_LINE_TARGET ? "warn" : "pass";
|
|
37
|
+
return {
|
|
38
|
+
id: `memory-length:${file.label}`,
|
|
39
|
+
group: "setup",
|
|
40
|
+
title: `${file.label} length`,
|
|
41
|
+
status,
|
|
42
|
+
detail: status === "pass" ? `${plural(file.lines, "line")}, under the ${MEMORY_LINE_TARGET}-line target.` : `${plural(file.lines, "line")}. The docs say to target under ${MEMORY_LINE_TARGET} lines per file, because a longer file uses more context and is followed less well. Every session loads all of it.`,
|
|
43
|
+
fix: status === "pass" ? "" : `For each line, ask whether removing it would cause a mistake. Move what only some tasks need into a skill or into ${facts.ruleFiles ? "the existing" : "a"} .claude/rules/ file, and turn a rule that must happen every time into a hook.`,
|
|
44
|
+
source
|
|
45
|
+
};
|
|
46
|
+
});
|
|
47
|
+
const index = facts.autoMemoryIndex;
|
|
48
|
+
if (index) {
|
|
49
|
+
const over = index.lines > 200 || index.bytes > 25e3;
|
|
50
|
+
checks.push({
|
|
51
|
+
id: "auto-memory-index",
|
|
52
|
+
group: "setup",
|
|
53
|
+
title: "Auto memory index",
|
|
54
|
+
status: over ? "warn" : "pass",
|
|
55
|
+
detail: over ? `MEMORY.md is ${plural(index.lines, "line")} and ${Math.round(index.bytes / 1e3)} KB. Only the first 200 lines or 25 KB are loaded, so the rest is never read.` : `MEMORY.md is ${plural(index.lines, "line")}, inside what is loaded.`,
|
|
56
|
+
fix: over ? "Shorten the index, or merge entries, so the ones that matter are in the part that loads." : "",
|
|
57
|
+
source
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
return checks;
|
|
61
|
+
}
|
|
62
|
+
function automationChecks(facts) {
|
|
63
|
+
const events = [...new Set(all(facts.settings, (f) => f.hookEvents))].sort();
|
|
64
|
+
const allow = all(facts.settings, (f) => f.allow);
|
|
65
|
+
const skills = facts.skills.project + facts.skills.user;
|
|
66
|
+
const checks = [
|
|
67
|
+
{
|
|
68
|
+
id: "hooks",
|
|
69
|
+
group: "setup",
|
|
70
|
+
title: "Hooks",
|
|
71
|
+
status: events.length ? "pass" : "warn",
|
|
72
|
+
detail: events.length ? `Hooks run on: ${events.join(", ")}.` : "No hook is configured, so nothing runs automatically.",
|
|
73
|
+
fix: events.length ? "" : "Our suggestion: a rule that must happen every time, such as formatting or a lint run after an edit, belongs in a hook. A line in CLAUDE.md is advice that can be skipped.",
|
|
74
|
+
source: `${DOCS}/hooks.md`
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
id: "allow-rules",
|
|
78
|
+
group: "setup",
|
|
79
|
+
title: "Pre-approved commands",
|
|
80
|
+
status: allow.length ? "pass" : "warn",
|
|
81
|
+
detail: allow.length ? `${plural(allow.length, "allow rule")} across ${plural(facts.settings.filter((f) => f.allow.length).length, "settings file")}.` : "No allow rule is set, so every command asks for approval.",
|
|
82
|
+
fix: allow.length ? "" : "Use /permissions to allow the commands you trust, such as your test and lint commands.",
|
|
83
|
+
source: `${DOCS}/permissions.md`
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
id: "skills",
|
|
87
|
+
group: "setup",
|
|
88
|
+
title: "Skills",
|
|
89
|
+
status: "info",
|
|
90
|
+
detail: skills ? `${plural(facts.skills.project, "project skill")} and ${plural(facts.skills.user, "user skill")}.` : "No skill is defined. A skill holds knowledge that only some tasks need, so it stays out of every other session.",
|
|
91
|
+
fix: "",
|
|
92
|
+
source: `${DOCS}/skills.md`
|
|
93
|
+
}
|
|
94
|
+
];
|
|
95
|
+
if (facts.legacyCommands) {
|
|
96
|
+
checks.push({
|
|
97
|
+
id: "legacy-commands",
|
|
98
|
+
group: "setup",
|
|
99
|
+
title: "Custom commands",
|
|
100
|
+
status: "info",
|
|
101
|
+
detail: `${plural(facts.legacyCommands, "file")} in .claude/commands/. They still work. The docs merge commands into skills and prefer a skill for new work.`,
|
|
102
|
+
fix: "",
|
|
103
|
+
source: `${DOCS}/skills.md`
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
checks.push({
|
|
107
|
+
id: "subagents-and-mcp",
|
|
108
|
+
group: "setup",
|
|
109
|
+
title: "Subagents and connected tools",
|
|
110
|
+
status: "info",
|
|
111
|
+
detail: `${plural(facts.subagents.project + facts.subagents.user, "subagent")}. ${plural(facts.mcpServers.project, "project MCP server")} and ${plural(facts.mcpServers.user, "user MCP server")}.`,
|
|
112
|
+
fix: "",
|
|
113
|
+
source: `${DOCS}/mcp.md`
|
|
114
|
+
});
|
|
115
|
+
return checks;
|
|
116
|
+
}
|
|
117
|
+
function guardrailChecks(facts) {
|
|
118
|
+
const files = facts.settings;
|
|
119
|
+
const deny = all(files, (f) => f.deny);
|
|
120
|
+
const secretRules = deny.filter(deniesSecrets);
|
|
121
|
+
const broad = all(files, (f) => f.allow.filter(allowsEveryCommand).map((rule) => `${rule} in ${f.label}`));
|
|
122
|
+
const modes = files.filter((f) => f.defaultMode).map((f) => ({ mode: f.defaultMode, label: f.label }));
|
|
123
|
+
const bypass = modes.find((m) => m.mode === "bypassPermissions");
|
|
124
|
+
const loose = modes.find((m) => m.mode === "dontAsk" || m.mode === "auto");
|
|
125
|
+
const sandboxOn = files.some((f) => f.sandboxEnabled === true);
|
|
126
|
+
const windows = facts.platform === "win32";
|
|
127
|
+
const reach = files.reduce((sum, f) => sum + f.additionalDirectories, 0);
|
|
128
|
+
const retention = files.map((f) => f.cleanupPeriodDays).find((d) => d !== null) ?? null;
|
|
129
|
+
const checks = [
|
|
130
|
+
{
|
|
131
|
+
id: "deny-secrets",
|
|
132
|
+
group: "guardrails",
|
|
133
|
+
title: "Secrets are off limits",
|
|
134
|
+
status: secretRules.length ? "pass" : facts.secretFiles.length ? "fail" : "warn",
|
|
135
|
+
detail: secretRules.length ? `${plural(secretRules.length, "deny rule")} cover secret files: ${secretRules.join(", ")}.` : facts.secretFiles.length ? `No deny rule covers secret files, and this project has ${facts.secretFiles.join(", ")}. The agent can read ${facts.secretFiles.length === 1 ? "it" : "them"}.` : "No deny rule covers secret files. None was found in the project, so nothing is exposed today.",
|
|
136
|
+
fix: secretRules.length ? "" : `Add deny rules to .claude/settings.json: ${facts.secretFiles.length ? facts.secretFiles.map((file) => `"Read(./${file})"`).join(", ") : '"Read(./.env)" and "Read(./secrets/**)", for example'}. A deny rule is checked before any allow rule.`,
|
|
137
|
+
source: `${DOCS}/permissions.md`
|
|
138
|
+
},
|
|
139
|
+
{
|
|
140
|
+
id: "broad-allow",
|
|
141
|
+
group: "guardrails",
|
|
142
|
+
title: "No blanket approval of shell commands",
|
|
143
|
+
status: broad.length ? "fail" : "pass",
|
|
144
|
+
detail: broad.length ? `These rules approve every shell command: ${broad.join("; ")}.` : "No allow rule approves every shell command.",
|
|
145
|
+
fix: broad.length ? "Replace the blanket rule with rules for the commands you trust." : "",
|
|
146
|
+
source: `${DOCS}/permissions.md`
|
|
147
|
+
},
|
|
148
|
+
{
|
|
149
|
+
id: "default-mode",
|
|
150
|
+
group: "guardrails",
|
|
151
|
+
title: "Permission mode",
|
|
152
|
+
status: bypass ? "fail" : loose ? "warn" : "pass",
|
|
153
|
+
detail: bypass ? `${bypass.label} sets the default mode to bypassPermissions, so nothing asks for approval.` : loose ? `${loose.label} sets the default mode to ${loose.mode}, which approves actions without asking.` : modes.length ? `Default mode: ${modes.map((m) => `${m.mode} (${m.label})`).join(", ")}.` : "No default mode is set, so the standard mode applies and actions ask for approval.",
|
|
154
|
+
fix: bypass ? "Use this mode only inside a container or a virtual machine that holds nothing you care about." : loose ? "Check that this is what you intend on a machine with real credentials." : "",
|
|
155
|
+
source: `${DOCS}/permissions.md`
|
|
156
|
+
},
|
|
157
|
+
{
|
|
158
|
+
id: "sandbox",
|
|
159
|
+
group: "guardrails",
|
|
160
|
+
title: "Sandbox",
|
|
161
|
+
status: sandboxOn ? "pass" : windows ? "info" : "warn",
|
|
162
|
+
detail: sandboxOn ? "The sandbox is enabled, so commands run inside OS-level limits." : windows ? "The sandbox is off. It is not supported on native Windows." : "The sandbox is off, which is the default. Commands run with your full access to files and the network.",
|
|
163
|
+
fix: sandboxOn || windows ? "" : 'Turn it on with /sandbox, or set "sandbox": { "enabled": true } in settings.',
|
|
164
|
+
source: `${DOCS}/sandboxing.md`
|
|
165
|
+
},
|
|
166
|
+
{
|
|
167
|
+
id: "reach",
|
|
168
|
+
group: "guardrails",
|
|
169
|
+
title: "Reach outside the project",
|
|
170
|
+
status: "info",
|
|
171
|
+
detail: reach ? `${reach} additional ${reach === 1 ? "directory" : "directories"} outside the project can be reached.` : "No additional directory is granted, so the agent works inside the project.",
|
|
172
|
+
fix: "",
|
|
173
|
+
source: `${DOCS}/permissions.md`
|
|
174
|
+
},
|
|
175
|
+
{
|
|
176
|
+
id: "retention",
|
|
177
|
+
group: "guardrails",
|
|
178
|
+
title: "Session records",
|
|
179
|
+
status: "info",
|
|
180
|
+
detail: `Session transcripts are kept for ${retention ?? 30} days${retention === null ? ", the default" : ""}. They are the record of what the agent did.`,
|
|
181
|
+
fix: "",
|
|
182
|
+
source: `${DOCS}/sessions.md`
|
|
183
|
+
}
|
|
184
|
+
];
|
|
185
|
+
if (files.some((f) => f.scope === "managed")) {
|
|
186
|
+
checks.push({
|
|
187
|
+
id: "managed",
|
|
188
|
+
group: "guardrails",
|
|
189
|
+
title: "Managed settings",
|
|
190
|
+
status: "info",
|
|
191
|
+
detail: "A managed settings file is present. Its rules come first and a project cannot override them.",
|
|
192
|
+
fix: "",
|
|
193
|
+
source: `${DOCS}/managed-settings.md`
|
|
194
|
+
});
|
|
195
|
+
}
|
|
196
|
+
return checks;
|
|
197
|
+
}
|
|
198
|
+
function looksLikeACheck(command) {
|
|
199
|
+
return /\b(test|tests|jest|vitest|pytest|mocha|lint|eslint|ruff|tsc|typecheck|type-check|mypy|pyright|check|build|cargo (test|check|clippy)|go (test|vet))\b/i.test(command);
|
|
200
|
+
}
|
|
201
|
+
function verificationChecks(facts) {
|
|
202
|
+
const files = facts.settings;
|
|
203
|
+
const allowed = all(files, (f) => f.allow.filter((rule) => /^Bash\(/.test(rule) && looksLikeACheck(rule)));
|
|
204
|
+
const hooked = all(files, (f) => f.hookCommands.filter((h) => looksLikeACheck(h.command)));
|
|
205
|
+
const stopEvents = [...new Set(all(files, (f) => f.hookEvents.filter((event) => event === "Stop" || event === "SubagentStop")))].sort();
|
|
206
|
+
const unscoped = facts.subagentFiles.filter((agent) => !agent.limitsTools).map((agent) => agent.name);
|
|
207
|
+
const checks = [
|
|
208
|
+
{
|
|
209
|
+
id: "verify-command",
|
|
210
|
+
group: "verification",
|
|
211
|
+
title: "The agent can run your checks",
|
|
212
|
+
status: allowed.length || hooked.length ? "pass" : "warn",
|
|
213
|
+
detail: allowed.length || hooked.length ? `${plural(allowed.length, "allow rule")} and ${plural(hooked.length, "hook")} name a test, lint, type-check or build command.` : 'No allow rule and no hook names a test, lint, type-check or build command. Without a check it can run, the agent only has "looks done" to go on.',
|
|
214
|
+
fix: allowed.length || hooked.length ? "" : "Our suggestion: pre-approve the commands that check a change, so the agent can run them without asking each time.",
|
|
215
|
+
source: `${DOCS}/permissions.md`
|
|
216
|
+
},
|
|
217
|
+
{
|
|
218
|
+
id: "stop-check",
|
|
219
|
+
group: "verification",
|
|
220
|
+
title: "Something checks the work before the agent stops",
|
|
221
|
+
status: stopEvents.length ? "pass" : "warn",
|
|
222
|
+
detail: stopEvents.length ? `A hook runs on ${stopEvents.join(" and ")}. A Stop hook can send the agent back to keep working.` : "No hook runs when the agent finishes. The agent decides on its own that it is done, and you find out whether it was.",
|
|
223
|
+
fix: stopEvents.length ? "" : "Our suggestion: a Stop hook that runs a fast check and exits with code 2 when it fails. The docs say that sends Claude back to keep working, and they cap consecutive continuations at eight, so it cannot loop forever.",
|
|
224
|
+
source: `${DOCS}/hooks.md`
|
|
225
|
+
}
|
|
226
|
+
];
|
|
227
|
+
if (facts.subagentFiles.length) {
|
|
228
|
+
checks.push({
|
|
229
|
+
id: "subagent-scope",
|
|
230
|
+
group: "verification",
|
|
231
|
+
title: "Each subagent is limited to the tools its job needs",
|
|
232
|
+
status: unscoped.length ? "warn" : "pass",
|
|
233
|
+
detail: unscoped.length ? `${plural(unscoped.length, "subagent")} set no tools line: ${unscoped.join(", ")}. The docs say a subagent then "inherits every tool available to subagents".` : `All ${plural(facts.subagentFiles.length, "subagent")} limit their tools.`,
|
|
234
|
+
fix: unscoped.length ? "Add a tools line to the frontmatter that lists only what the subagent needs, or a disallowedTools line that removes what it must not use." : "",
|
|
235
|
+
source: `${DOCS}/sub-agents.md`
|
|
236
|
+
});
|
|
237
|
+
} else {
|
|
238
|
+
checks.push({
|
|
239
|
+
id: "subagent-scope",
|
|
240
|
+
group: "verification",
|
|
241
|
+
title: "Subagents",
|
|
242
|
+
status: "info",
|
|
243
|
+
detail: "No subagent is defined. A subagent with a narrow job, such as a reviewer that sees only the diff, checks work in a fresh context.",
|
|
244
|
+
fix: "",
|
|
245
|
+
source: `${DOCS}/sub-agents.md`
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
return checks;
|
|
249
|
+
}
|
|
250
|
+
function promptFor(check, facts) {
|
|
251
|
+
if (check.status !== "fail" && check.status !== "warn") return "";
|
|
252
|
+
const [id, label] = check.id.split(":");
|
|
253
|
+
switch (id) {
|
|
254
|
+
case "memory-exists":
|
|
255
|
+
return "/init";
|
|
256
|
+
case "memory-length": {
|
|
257
|
+
const file = facts.memory.find((m) => m.label === label);
|
|
258
|
+
return `${label} is ${file?.lines ?? "many"} lines. The Claude Code docs say to target under ${MEMORY_LINE_TARGET} lines per file, because a longer file uses more context and is followed less well. Read it and give me a plan before you edit anything. For each section, say one of: keep; delete, because the code or the README already says it; move to a skill, because only some tasks need it; move to a file under .claude/rules/; or turn into a hook, because it must happen every time. Give the line count the file would have after the plan. Change nothing until I approve it.`;
|
|
259
|
+
}
|
|
260
|
+
case "auto-memory-index":
|
|
261
|
+
return "The auto memory index MEMORY.md is longer than what loads (the first 200 lines or 25 KB). Read it and propose which entries to merge, shorten or remove so that the ones that matter load. Show me the new index before you save it.";
|
|
262
|
+
case "hooks":
|
|
263
|
+
return 'This project has no Claude Code hooks. Look at how it formats, lints and tests code. Propose at most two hooks for .claude/settings.json that run after an edit (the PostToolUse event, with the matcher "Edit|Write"), for example the formatter on the changed file. For each one, show me the JSON, the command it runs and how long that command takes. Do not change the settings file until I approve.';
|
|
264
|
+
case "allow-rules":
|
|
265
|
+
return "/permissions";
|
|
266
|
+
case "deny-secrets": {
|
|
267
|
+
const rules = facts.secretFiles.length ? facts.secretFiles.map((file) => `Read(./${file})`).join(", ") : "Read(./.env), Read(./secrets/**)";
|
|
268
|
+
return `Add deny rules to the permissions.deny array in .claude/settings.json so that Claude Code cannot read secret files: ${rules}. Keep every rule that is already in the file. Show me the diff before you save it, and tell me how to confirm afterwards that a read of one of these files is refused.`;
|
|
269
|
+
}
|
|
270
|
+
case "broad-allow":
|
|
271
|
+
return "My Claude Code settings hold an allow rule that approves every shell command. Find it in the settings files, then list the shell commands this project really needs, such as its test, lint and build commands. Propose scoped allow rules for those to replace the blanket rule. Show me the diff before you save it.";
|
|
272
|
+
case "sandbox":
|
|
273
|
+
return "/sandbox";
|
|
274
|
+
case "verify-command":
|
|
275
|
+
return "/permissions";
|
|
276
|
+
case "stop-check":
|
|
277
|
+
return "Nothing checks your work before you stop. Look at how this project tests and lints, and find the fastest check that catches a broken change, such as the type check. Propose a Stop hook for .claude/settings.json that runs it and exits with code 2 when it fails, so that you are sent back to keep working. Show me the JSON, the command and how long the command takes. Do not change the settings file until I approve.";
|
|
278
|
+
case "subagent-scope":
|
|
279
|
+
return "Some of my subagents inherit every tool. For each subagent file under .claude/agents/, read what it is for and propose a tools line in its frontmatter that lists only the tools that job needs. Show me the proposed line for each file before you edit any of them.";
|
|
280
|
+
default:
|
|
281
|
+
return "";
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
function runChecks(facts) {
|
|
285
|
+
const checks = [...memoryChecks(facts), ...automationChecks(facts), ...guardrailChecks(facts), ...verificationChecks(facts)];
|
|
286
|
+
return checks.map((check) => ({ ...check, prompt: promptFor(check, facts) }));
|
|
287
|
+
}
|
|
288
|
+
function summarize(checks) {
|
|
289
|
+
const count = (status) => checks.filter((c) => c.status === status).length;
|
|
290
|
+
const [pass, warn, fail, info] = [count("pass"), count("warn"), count("fail"), count("info")];
|
|
291
|
+
const judged = pass + warn + fail;
|
|
292
|
+
return { pass, warn, fail, info, score: judged ? Math.round(pass / judged * 100) : 0 };
|
|
293
|
+
}
|
|
294
|
+
var FAIL_ON_LEVELS = ["fail", "warn"];
|
|
295
|
+
function failing(checks, level) {
|
|
296
|
+
return checks.filter((c) => c.status === "fail" || level === "warn" && c.status === "warn");
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
// src/groundcrew-gather.ts
|
|
300
|
+
import { existsSync, readFileSync, readdirSync, statSync } from "fs";
|
|
301
|
+
import os from "os";
|
|
302
|
+
import path from "path";
|
|
303
|
+
var SECRET_NAMES = /^(\.env(\..+)?|secrets?(\..+)?|credentials(\..+)?|.*\.pem|id_rsa)$/i;
|
|
304
|
+
var NOT_SECRET = /\.(example|sample|template)$/i;
|
|
305
|
+
var SECRET_DEPTH = 3;
|
|
306
|
+
var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "vendor", "coverage"]);
|
|
307
|
+
var home = () => os.homedir();
|
|
308
|
+
var configDir = () => process.env.CLAUDE_CONFIG_DIR || path.join(home(), ".claude");
|
|
309
|
+
var tilde = (file) => file.startsWith(home()) ? `~${file.slice(home().length)}` : file;
|
|
310
|
+
function canRead(project) {
|
|
311
|
+
try {
|
|
312
|
+
readdirSync(project);
|
|
313
|
+
return true;
|
|
314
|
+
} catch {
|
|
315
|
+
return false;
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
function readJson(file) {
|
|
319
|
+
try {
|
|
320
|
+
return JSON.parse(readFileSync(file, "utf-8"));
|
|
321
|
+
} catch {
|
|
322
|
+
return null;
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
function countFiles(dir, test) {
|
|
326
|
+
if (!existsSync(dir)) return 0;
|
|
327
|
+
let total = 0;
|
|
328
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
329
|
+
if (entry.isDirectory()) total += countFiles(path.join(dir, entry.name), test);
|
|
330
|
+
else if (test(entry.name)) total += 1;
|
|
331
|
+
}
|
|
332
|
+
return total;
|
|
333
|
+
}
|
|
334
|
+
function findSecretFiles(root, relative, depth) {
|
|
335
|
+
const dir = path.join(root, relative);
|
|
336
|
+
if (depth > SECRET_DEPTH || !existsSync(dir)) return [];
|
|
337
|
+
const found = [];
|
|
338
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
339
|
+
const here = relative ? `${relative}/${entry.name}` : entry.name;
|
|
340
|
+
if (entry.isDirectory()) {
|
|
341
|
+
if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) found.push(...findSecretFiles(root, here, depth + 1));
|
|
342
|
+
} else if (SECRET_NAMES.test(entry.name) && !NOT_SECRET.test(entry.name)) {
|
|
343
|
+
found.push(here);
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
return found;
|
|
347
|
+
}
|
|
348
|
+
function hookCommands(hooks) {
|
|
349
|
+
const found = [];
|
|
350
|
+
for (const [event, groups] of Object.entries(hooks)) {
|
|
351
|
+
for (const group of Array.isArray(groups) ? groups : []) {
|
|
352
|
+
for (const handler of Array.isArray(group?.hooks) ? group.hooks : []) {
|
|
353
|
+
if (typeof handler?.command === "string") found.push({ event, command: handler.command });
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
return found;
|
|
358
|
+
}
|
|
359
|
+
function subagentFiles(dir) {
|
|
360
|
+
if (!existsSync(dir)) return [];
|
|
361
|
+
const found = [];
|
|
362
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
363
|
+
const file = path.join(dir, entry.name);
|
|
364
|
+
if (entry.isDirectory()) found.push(...subagentFiles(file));
|
|
365
|
+
else if (entry.name.endsWith(".md")) {
|
|
366
|
+
const frontmatter = /^---\n([\s\S]*?)\n---/.exec(readFileSync(file, "utf-8"))?.[1] ?? "";
|
|
367
|
+
found.push({ name: entry.name.replace(/\.md$/, ""), limitsTools: /^(tools|disallowedTools)\s*:/m.test(frontmatter) });
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
return found;
|
|
371
|
+
}
|
|
372
|
+
var isMarkdown = (name) => name.endsWith(".md");
|
|
373
|
+
var strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
|
|
374
|
+
function gather(project) {
|
|
375
|
+
const filesRead = [];
|
|
376
|
+
const label = (file) => file.startsWith(project + path.sep) ? file.slice(project.length + 1) : tilde(file);
|
|
377
|
+
const memoryFile = (file) => {
|
|
378
|
+
if (!existsSync(file) || !statSync(file).isFile()) return null;
|
|
379
|
+
const text = readFileSync(file, "utf-8");
|
|
380
|
+
filesRead.push(label(file));
|
|
381
|
+
return { label: label(file), lines: text.split("\n").length - (text.endsWith("\n") ? 1 : 0), bytes: Buffer.byteLength(text) };
|
|
382
|
+
};
|
|
383
|
+
const memory = [
|
|
384
|
+
path.join(project, "CLAUDE.md"),
|
|
385
|
+
path.join(project, ".claude", "CLAUDE.md"),
|
|
386
|
+
path.join(project, "CLAUDE.local.md"),
|
|
387
|
+
path.join(project, "AGENTS.md"),
|
|
388
|
+
path.join(configDir(), "CLAUDE.md")
|
|
389
|
+
].map(memoryFile).filter((file) => file !== null);
|
|
390
|
+
const settingsFile = (scope, file) => {
|
|
391
|
+
const json = readJson(file);
|
|
392
|
+
if (!json) return null;
|
|
393
|
+
filesRead.push(label(file));
|
|
394
|
+
const permissions = json.permissions || {};
|
|
395
|
+
const hooks = json.hooks && typeof json.hooks === "object" ? json.hooks : {};
|
|
396
|
+
return {
|
|
397
|
+
scope,
|
|
398
|
+
label: label(file),
|
|
399
|
+
allow: strings(permissions.allow),
|
|
400
|
+
ask: strings(permissions.ask),
|
|
401
|
+
deny: strings(permissions.deny),
|
|
402
|
+
defaultMode: typeof permissions.defaultMode === "string" ? permissions.defaultMode : null,
|
|
403
|
+
additionalDirectories: strings(permissions.additionalDirectories).length,
|
|
404
|
+
hookEvents: Object.keys(hooks).filter((event) => Array.isArray(hooks[event]) && hooks[event].length > 0),
|
|
405
|
+
hookCommands: hookCommands(hooks),
|
|
406
|
+
sandboxEnabled: typeof json.sandbox?.enabled === "boolean" ? json.sandbox.enabled : null,
|
|
407
|
+
cleanupPeriodDays: typeof json.cleanupPeriodDays === "number" ? json.cleanupPeriodDays : null
|
|
408
|
+
};
|
|
409
|
+
};
|
|
410
|
+
const managed = process.platform === "darwin" ? "/Library/Application Support/ClaudeCode/managed-settings.json" : process.platform === "win32" ? "C:\\Program Files\\ClaudeCode\\managed-settings.json" : "/etc/claude-code/managed-settings.json";
|
|
411
|
+
const settings = [
|
|
412
|
+
settingsFile("managed", managed),
|
|
413
|
+
settingsFile("local", path.join(project, ".claude", "settings.local.json")),
|
|
414
|
+
settingsFile("project", path.join(project, ".claude", "settings.json")),
|
|
415
|
+
settingsFile("user", path.join(configDir(), "settings.json"))
|
|
416
|
+
].filter((file) => file !== null);
|
|
417
|
+
const projectMcp = readJson(path.join(project, ".mcp.json"));
|
|
418
|
+
const userConfig = readJson(path.join(home(), ".claude.json"));
|
|
419
|
+
const userServers = Object.keys(userConfig?.mcpServers || {}).length + Object.keys(userConfig?.projects?.[project]?.mcpServers || {}).length;
|
|
420
|
+
if (projectMcp) filesRead.push(".mcp.json");
|
|
421
|
+
if (userConfig) filesRead.push("~/.claude.json (MCP server names only)");
|
|
422
|
+
const encoded = project.replace(/[^a-zA-Z0-9]/g, "-");
|
|
423
|
+
return {
|
|
424
|
+
filesRead,
|
|
425
|
+
facts: {
|
|
426
|
+
platform: process.platform,
|
|
427
|
+
memory,
|
|
428
|
+
ruleFiles: countFiles(path.join(project, ".claude", "rules"), isMarkdown) + countFiles(path.join(configDir(), "rules"), isMarkdown),
|
|
429
|
+
autoMemoryIndex: memoryFile(path.join(configDir(), "projects", encoded, "memory", "MEMORY.md")),
|
|
430
|
+
settings,
|
|
431
|
+
skills: {
|
|
432
|
+
project: countFiles(path.join(project, ".claude", "skills"), (name) => name === "SKILL.md"),
|
|
433
|
+
user: countFiles(path.join(configDir(), "skills"), (name) => name === "SKILL.md")
|
|
434
|
+
},
|
|
435
|
+
subagents: {
|
|
436
|
+
project: countFiles(path.join(project, ".claude", "agents"), isMarkdown),
|
|
437
|
+
user: countFiles(path.join(configDir(), "agents"), isMarkdown)
|
|
438
|
+
},
|
|
439
|
+
subagentFiles: [...subagentFiles(path.join(project, ".claude", "agents")), ...subagentFiles(path.join(configDir(), "agents"))],
|
|
440
|
+
legacyCommands: countFiles(path.join(project, ".claude", "commands"), isMarkdown),
|
|
441
|
+
mcpServers: { project: Object.keys(projectMcp?.mcpServers || {}).length, user: userServers },
|
|
442
|
+
secretFiles: findSecretFiles(project, "", 0).sort()
|
|
443
|
+
}
|
|
444
|
+
};
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
// src/groundcrew-page.ts
|
|
448
|
+
var esc = (text) => text.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """);
|
|
449
|
+
var STATUS = {
|
|
450
|
+
fail: { icon: "\u2715", word: "Fix" },
|
|
451
|
+
warn: { icon: "!", word: "Look" },
|
|
452
|
+
pass: { icon: "\u2713", word: "Good" },
|
|
453
|
+
info: { icon: "i", word: "Fact" }
|
|
454
|
+
};
|
|
455
|
+
var GROUP_TITLE = { setup: "Setup", guardrails: "Guardrails", verification: "Verification" };
|
|
456
|
+
var GROUPS = [
|
|
457
|
+
{ key: "setup", intro: "What loads into every session, and what runs without being asked." },
|
|
458
|
+
{ key: "guardrails", intro: "What the agent may reach, and what stops it." },
|
|
459
|
+
{ key: "verification", intro: "Who checks the work when the agent says it is done." }
|
|
460
|
+
];
|
|
461
|
+
var ORDER = ["fail", "warn", "pass", "info"];
|
|
462
|
+
var needsFix = (check) => check.status === "fail" || check.status === "warn";
|
|
463
|
+
var anchor = (check) => `check-${check.id.replace(/[^a-zA-Z0-9]+/g, "-")}`;
|
|
464
|
+
var CSS = `
|
|
465
|
+
:root{--bg:#faf9f6;--card:#fff;--fg:#1c1b19;--mut:#5f5c55;--line:#dddad1;--well:#f1efe9;--fail:#d03b3b;--warn:#fab219;--pass:#0ca30c;--info:#8f8e86}
|
|
466
|
+
@media (prefers-color-scheme:dark){:root{--bg:#161512;--card:#1f1e1a;--fg:#ece9e1;--mut:#a09c91;--line:#35332d;--well:#161512}}
|
|
467
|
+
*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,sans-serif}
|
|
468
|
+
main{max-width:860px;margin:0 auto;padding:28px 16px 60px}h1{font-size:26px;margin:0}h2{font-size:19px;margin:36px 0 2px}
|
|
469
|
+
p{margin:6px 0}.mut{color:var(--mut)}code,pre{font:13px/1.5 ui-monospace,Menlo,monospace}a{color:inherit}[id]{scroll-margin-top:14px}
|
|
470
|
+
.score{display:flex;flex-wrap:wrap;gap:10px;margin:18px 0 0}.tile{flex:1;min-width:120px;background:var(--card);border:1px solid var(--line);
|
|
471
|
+
border-radius:10px;padding:10px 14px}.tile b{display:block;font-size:26px;line-height:1.15}.tile span{font-size:12.5px;color:var(--mut)}
|
|
472
|
+
.bar{display:flex;gap:2px;height:8px;margin:14px 0 0}.bar i{display:block;border-radius:999px}
|
|
473
|
+
.todo{margin:14px 0 0;padding:0;list-style:none}.todo li{display:flex;gap:8px;align-items:center;padding:3px 0;font-size:14.5px}
|
|
474
|
+
.check{background:var(--card);border:1px solid var(--line);border-left-width:5px;border-radius:10px;padding:12px 14px;margin:10px 0 0}
|
|
475
|
+
.check h3{font-size:15.5px;margin:0;display:flex;align-items:center;gap:8px}.check p{font-size:14px}
|
|
476
|
+
.dot{display:inline-flex;align-items:center;justify-content:center;width:18px;height:18px;border-radius:50%;font-size:11px;font-weight:700;
|
|
477
|
+
color:#fff;flex:none}.word{font-size:11.5px;font-weight:600;color:var(--mut);border:1px solid var(--line);border-radius:999px;padding:0 8px;margin-left:auto}
|
|
478
|
+
.fix{border-top:1px solid var(--line);margin-top:8px;padding-top:8px}.src{font-size:12.5px}
|
|
479
|
+
.prompt{margin-top:10px;border:1px solid var(--line);border-radius:8px;background:var(--well)}
|
|
480
|
+
.prompt header{display:flex;align-items:center;gap:8px;padding:6px 10px;border-bottom:1px solid var(--line);font-size:12.5px;color:var(--mut)}
|
|
481
|
+
.prompt pre{margin:0;padding:10px;white-space:pre-wrap;overflow-wrap:anywhere;color:var(--fg)}
|
|
482
|
+
.prompt button{margin-left:auto;font:600 12.5px system-ui,sans-serif;color:var(--fg);background:var(--card);border:1px solid var(--line);border-radius:6px;
|
|
483
|
+
padding:3px 12px;cursor:pointer}.prompt button:hover{border-color:var(--mut)}.prompt button:focus-visible{outline:2px solid var(--fg);outline-offset:2px}
|
|
484
|
+
.rows{margin:10px 0 0;padding:0;list-style:none;background:var(--card);border:1px solid var(--line);border-radius:10px}
|
|
485
|
+
.rows li{display:grid;grid-template-columns:18px minmax(120px,220px) 1fr;gap:4px 10px;align-items:start;padding:8px 12px;font-size:14px}
|
|
486
|
+
.rows li+li{border-top:1px solid var(--line)}.rows .dot{margin-top:2px}.rows b{font-weight:600}.rows .src{grid-column:3}
|
|
487
|
+
@media (max-width:600px){.rows li{grid-template-columns:18px 1fr}.rows span.d,.rows .src{grid-column:2}}
|
|
488
|
+
footer{margin-top:40px;border-top:1px solid var(--line);padding-top:12px;font-size:13px;color:var(--mut)}footer li{margin:2px 0}
|
|
489
|
+
${ORDER.map((s) => `.s-${s}{border-left-color:var(--${s})}.s-${s} .dot,.s-${s}.dot,.bar .b-${s}{background:var(--${s})}`).join("")}
|
|
490
|
+
.s-warn .dot,.s-warn.dot{color:#0b0b0b}`;
|
|
491
|
+
var COPY_SCRIPT = `document.addEventListener('click',function(e){var b=e.target.closest('button[data-copy]');if(!b)return;
|
|
492
|
+
var t=document.getElementById(b.getAttribute('data-copy')).textContent;
|
|
493
|
+
function done(){b.textContent='Copied';setTimeout(function(){b.textContent='Copy'},1600)}
|
|
494
|
+
function old(){var a=document.createElement('textarea');a.value=t;document.body.appendChild(a);a.select();document.execCommand('copy');a.remove();done()}
|
|
495
|
+
if(navigator.clipboard&&window.isSecureContext){navigator.clipboard.writeText(t).then(done,old)}else{old()}});`;
|
|
496
|
+
var dot = (status) => `<span class="dot s-${status}" aria-hidden="true">${STATUS[status].icon}</span>`;
|
|
497
|
+
var sourceLink = (check) => `<a href="${esc(check.source)}" target="_blank" rel="noopener noreferrer">${esc(check.source.replace(/^https:\/\/code\.claude\.com\/docs\/en\//, "docs: ").replace(/\.md$/, ""))}</a>`;
|
|
498
|
+
function fixCard(check) {
|
|
499
|
+
const status = STATUS[check.status];
|
|
500
|
+
const id = anchor(check);
|
|
501
|
+
const isCommand = check.prompt.startsWith("/");
|
|
502
|
+
const prompt = check.prompt ? `<div class="prompt"><header>${isCommand ? "Type this command in Claude Code" : "Paste this into Claude Code"}<button type="button" data-copy="${id}-prompt">Copy</button></header><pre id="${id}-prompt">${esc(check.prompt)}</pre></div>` : "";
|
|
503
|
+
return `<section class="check s-${check.status}" id="${id}"><h3>${dot(check.status)}${esc(check.title)}<span class="word">${status.word}</span></h3><p>${esc(check.detail)}</p>${check.fix ? `<p class="fix"><b>What to change:</b> ${esc(check.fix)}</p>` : ""}${prompt}<p class="src mut">Rests on ${sourceLink(check)}</p></section>`;
|
|
504
|
+
}
|
|
505
|
+
var row = (check) => `<li>${dot(check.status)}<b>${esc(check.title)}<span class="mut"> \xB7 ${STATUS[check.status].word}</span></b><span class="d">${esc(check.detail)}</span><span class="src mut">${sourceLink(check)}</span></li>`;
|
|
506
|
+
function renderPage(report2) {
|
|
507
|
+
const { summary } = report2;
|
|
508
|
+
const judged = summary.pass + summary.warn + summary.fail;
|
|
509
|
+
const bar = ["fail", "warn", "pass"].filter((s) => summary[s] > 0).map((s) => `<i class="b-${s}" style="flex:${summary[s]}"></i>`).join("");
|
|
510
|
+
const sorted = [...report2.checks].sort((a, b) => ORDER.indexOf(a.status) - ORDER.indexOf(b.status));
|
|
511
|
+
const fixes = sorted.filter(needsFix);
|
|
512
|
+
const todo = fixes.length ? `<h2>Do these first</h2><ul class="todo">${fixes.map((c) => `<li>${dot(c.status)}<a href="#${anchor(c)}">${esc(c.title)}</a><span class="mut">${GROUP_TITLE[c.group]}</span></li>`).join("")}</ul>` : '<h2>Nothing to fix</h2><p class="mut">Every check that can fail passes.</p>';
|
|
513
|
+
const groups = GROUPS.map((group) => {
|
|
514
|
+
const mine = sorted.filter((c) => c.group === group.key);
|
|
515
|
+
const rest = mine.filter((c) => !needsFix(c));
|
|
516
|
+
return `<h2>${GROUP_TITLE[group.key]}</h2><p class="mut">${group.intro}</p>${mine.filter(needsFix).map(fixCard).join("")}` + (rest.length ? `<ul class="rows">${rest.map(row).join("")}</ul>` : "");
|
|
517
|
+
}).join("");
|
|
518
|
+
return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>JQ Groundcrew: ${esc(report2.project)}</title><style>${CSS}</style></head><body><main><h1>JQ Groundcrew</h1><p class="mut">The setup check for Claude Code. How it is set up for <code>${esc(report2.project)}</code>. Read ${esc(report2.generatedAt)}. Refresh to read again.</p><div class="score"><div class="tile"><b>${summary.fail}</b><span>to fix</span></div><div class="tile"><b>${summary.warn}</b><span>to look at</span></div><div class="tile"><b>${summary.pass}</b><span>good</span></div><div class="tile"><b>${summary.score}%</b><span>of ${judged} checks pass</span></div></div><div class="bar" role="img" aria-label="${summary.fail} to fix, ${summary.warn} to look at, ${summary.pass} good">${bar}</div>` + todo + groups + `<footer><p>This page was made on your machine from the files below, and it loads nothing, so nothing left the machine. Its one script copies a prompt to your clipboard when you press Copy. It read settings and counted files. It did not read the contents of any secret file, and it read no session transcript.</p><p>A suggested prompt asks Claude Code to show its plan or its diff first. Read that before you approve it.</p><ul>${report2.filesRead.map((file) => `<li><code>${esc(file)}</code></li>`).join("")}</ul><p>Each check names the page of Anthropic\u2019s Claude Code documentation it rests on. The documentation was checked on 2026-11-14 and can change.</p></footer></main><script>${COPY_SCRIPT}</script></body></html>
|
|
519
|
+
`;
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
// src/groundcrew-cli.ts
|
|
523
|
+
var DEFAULT_PORT = 4317;
|
|
524
|
+
function report(project) {
|
|
525
|
+
const { facts, filesRead } = gather(project);
|
|
526
|
+
const checks = runChecks(facts);
|
|
527
|
+
return { project: tilde(project), generatedAt: (/* @__PURE__ */ new Date()).toLocaleString("en-US"), filesRead, checks, summary: summarize(checks) };
|
|
528
|
+
}
|
|
529
|
+
function parseArgs(args, defaultProject) {
|
|
530
|
+
const valueAfter = (flag) => {
|
|
531
|
+
const at = args.indexOf(flag);
|
|
532
|
+
return at === -1 ? null : { at, value: args[at + 1] };
|
|
533
|
+
};
|
|
534
|
+
const html = valueAfter("--html");
|
|
535
|
+
const port = valueAfter("--port");
|
|
536
|
+
const failOn = valueAfter("--fail-on");
|
|
537
|
+
if (html && (!html.value || html.value.startsWith("--"))) throw new Error("--html needs a file name");
|
|
538
|
+
const portNumber = port ? Number(port.value) : DEFAULT_PORT;
|
|
539
|
+
if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) throw new Error("--port needs a number from 1 to 65535");
|
|
540
|
+
if (failOn && !FAIL_ON_LEVELS.includes(failOn.value)) throw new Error("--fail-on needs fail or warn");
|
|
541
|
+
if (failOn && !html && !args.includes("--json")) throw new Error("--fail-on works with --json or --html, not with the page server");
|
|
542
|
+
const taken = new Set([html?.at, port?.at, failOn?.at].filter((at) => at !== void 0).map((at) => at + 1));
|
|
543
|
+
const dir = args.find((arg, i) => !arg.startsWith("--") && !taken.has(i));
|
|
544
|
+
const project = path2.resolve(dir || defaultProject);
|
|
545
|
+
if (!existsSync2(project) || !canRead(project)) throw new Error(`cannot read the folder: ${project}`);
|
|
546
|
+
return { project, flags: new Set(args.filter((arg) => arg.startsWith("--"))), html: html?.value ?? null, port: portNumber, failOn: failOn?.value ?? null };
|
|
547
|
+
}
|
|
548
|
+
function exitCodeFor(checks, failOn) {
|
|
549
|
+
if (!failOn) return 0;
|
|
550
|
+
const counted = failing(checks, failOn);
|
|
551
|
+
for (const check of counted) console.error(`groundcrew: ${check.status}: ${check.title}`);
|
|
552
|
+
return counted.length ? 1 : 0;
|
|
553
|
+
}
|
|
554
|
+
function runLocal(parsed) {
|
|
555
|
+
const { project } = parsed;
|
|
556
|
+
if (parsed.flags.has("--json")) {
|
|
557
|
+
const result = report(project);
|
|
558
|
+
console.log(JSON.stringify(result, null, 2));
|
|
559
|
+
return exitCodeFor(result.checks, parsed.failOn);
|
|
560
|
+
}
|
|
561
|
+
if (parsed.html) {
|
|
562
|
+
const result = report(project);
|
|
563
|
+
writeFileSync(parsed.html, renderPage(result));
|
|
564
|
+
console.log(`wrote ${parsed.html}`);
|
|
565
|
+
return exitCodeFor(result.checks, parsed.failOn);
|
|
566
|
+
}
|
|
567
|
+
createServer((request, response) => {
|
|
568
|
+
if (request.url !== "/") {
|
|
569
|
+
response.writeHead(404).end("not found");
|
|
570
|
+
return;
|
|
571
|
+
}
|
|
572
|
+
response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }).end(renderPage(report(project)));
|
|
573
|
+
}).listen(parsed.port, "127.0.0.1", () => console.log(`JQ Groundcrew for ${tilde(project)}: http://127.0.0.1:${parsed.port} (Ctrl+C to stop)`));
|
|
574
|
+
return 0;
|
|
575
|
+
}
|
|
576
|
+
|
|
577
|
+
// src/main.ts
|
|
578
|
+
var VERSION = true ? "0.1.1" : "dev";
|
|
579
|
+
var HELP = `JQ Groundcrew ${VERSION}: the setup check for Claude Code.
|
|
580
|
+
|
|
581
|
+
It reads how Claude Code is set up for a project and shows what to fix, with a prompt to copy
|
|
582
|
+
for each fix. It runs on your machine and sends nothing anywhere.
|
|
583
|
+
|
|
584
|
+
jq-groundcrew [folder] open a page at http://127.0.0.1:${DEFAULT_PORT}
|
|
585
|
+
jq-groundcrew [folder] --html FILE write the page to a file
|
|
586
|
+
jq-groundcrew [folder] --json print the report
|
|
587
|
+
jq-groundcrew --port NUMBER serve on another port
|
|
588
|
+
jq-groundcrew --json --fail-on fail exit 1 if a check fails, for CI
|
|
589
|
+
(--fail-on warn also counts a warning)
|
|
590
|
+
|
|
591
|
+
The folder defaults to the one you are in. It reads settings files, counts lines in CLAUDE.md
|
|
592
|
+
files, and lists the names of skills, subagents, MCP servers and files that usually hold
|
|
593
|
+
secrets. It never opens a secrets file and never reads a session transcript.
|
|
594
|
+
|
|
595
|
+
Unofficial. Not affiliated with or endorsed by Anthropic.`;
|
|
596
|
+
try {
|
|
597
|
+
const args = process.argv.slice(2);
|
|
598
|
+
if (args.includes("--help") || args.includes("-h")) console.log(HELP);
|
|
599
|
+
else if (args.includes("--version") || args.includes("-v")) console.log(VERSION);
|
|
600
|
+
else process.exitCode = runLocal(parseArgs(args, process.cwd()));
|
|
601
|
+
} catch (error) {
|
|
602
|
+
console.error(error.message || error);
|
|
603
|
+
process.exit(1);
|
|
604
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,52 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@point-seven-studio/jq-groundcrew",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "The setup check for Claude Code: what loads into every session, what runs automatically, and which guardrails are on. Runs on your machine and sends nothing anywhere. Unofficial; not affiliated with or endorsed by Anthropic.",
|
|
5
|
+
"bin": {
|
|
6
|
+
"jq-groundcrew": "dist/groundcrew.mjs"
|
|
7
|
+
},
|
|
8
|
+
"type": "module",
|
|
9
|
+
"files": [
|
|
10
|
+
"dist/groundcrew.mjs",
|
|
11
|
+
"README.md",
|
|
12
|
+
"LICENSE",
|
|
13
|
+
"NOTICE"
|
|
14
|
+
],
|
|
15
|
+
"engines": {
|
|
16
|
+
"node": ">=18"
|
|
17
|
+
},
|
|
18
|
+
"keywords": [
|
|
19
|
+
"claude-code",
|
|
20
|
+
"developer-tools",
|
|
21
|
+
"ai-coding",
|
|
22
|
+
"setup",
|
|
23
|
+
"guardrails"
|
|
24
|
+
],
|
|
25
|
+
"author": "Point Seven Studio",
|
|
26
|
+
"license": "Apache-2.0",
|
|
27
|
+
"repository": {
|
|
28
|
+
"type": "git",
|
|
29
|
+
"url": "git+https://github.com/point-seven-studio/jq-tools.git",
|
|
30
|
+
"directory": "packages/groundcrew"
|
|
31
|
+
},
|
|
32
|
+
"scripts": {
|
|
33
|
+
"typecheck": "tsc --noEmit",
|
|
34
|
+
"test": "vitest run",
|
|
35
|
+
"build": "./build.sh",
|
|
36
|
+
"check": "npm run typecheck && npm test && ./build.sh --check",
|
|
37
|
+
"prepublishOnly": "npm run check"
|
|
38
|
+
},
|
|
39
|
+
"devDependencies": {
|
|
40
|
+
"@types/node": "^20.14.0",
|
|
41
|
+
"esbuild": "^0.21.5",
|
|
42
|
+
"typescript": "^5.4.5",
|
|
43
|
+
"vitest": "^1.6.0"
|
|
44
|
+
},
|
|
45
|
+
"publishConfig": {
|
|
46
|
+
"access": "public"
|
|
47
|
+
},
|
|
48
|
+
"homepage": "https://github.com/point-seven-studio/jq-tools/tree/main/packages/groundcrew#readme",
|
|
49
|
+
"bugs": {
|
|
50
|
+
"url": "https://github.com/point-seven-studio/jq-tools/issues"
|
|
51
|
+
}
|
|
52
|
+
}
|