@point-seven-studio/jq-groundcrew 0.0.0-stage → 0.1.2
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 +106 -2
- package/dist/groundcrew.mjs +604 -0
- package/dist/index.mjs +599 -0
- package/dist/types/groundcrew-cli.d.ts +24 -0
- package/dist/types/groundcrew-core.d.ts +142 -0
- package/dist/types/groundcrew-gather.d.ts +12 -0
- package/dist/types/groundcrew-page.d.ts +20 -0
- package/dist/types/index.d.ts +5 -0
- package/dist/types/main.d.ts +1 -0
- package/package.json +59 -4
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* JQ Groundcrew: the checks, as pure functions.
|
|
3
|
+
*
|
|
4
|
+
* Groundcrew is a local, read-only page that tells a developer how their Claude Code setup
|
|
5
|
+
* looks: what loads into every session, what runs automatically, and which guardrails are on.
|
|
6
|
+
* groundcrew-gather.ts reads the files and groundcrew-cli.ts serves the page. This file decides what the
|
|
7
|
+
* page says. It reads nothing and imports nothing, so it is unit-tested with plain objects.
|
|
8
|
+
*
|
|
9
|
+
* Every check rests on a statement in Anthropic's Claude Code documentation, and carries the
|
|
10
|
+
* link, so a reader can verify the advice. The facts were checked against the docs on
|
|
11
|
+
* 2026-11-14. A check that is only our opinion says "our suggestion" in its text.
|
|
12
|
+
*
|
|
13
|
+
* Nothing here judges a transcript. The docs say the transcript format "is internal to Claude
|
|
14
|
+
* Code and changes between versions", so session checks are a separate, later piece.
|
|
15
|
+
*/
|
|
16
|
+
export type Status = 'pass' | 'warn' | 'fail' | 'info';
|
|
17
|
+
export type Group = 'setup' | 'guardrails' | 'verification';
|
|
18
|
+
export interface MemoryFile {
|
|
19
|
+
/** A label a person can read, such as "CLAUDE.md" or "~/.claude/CLAUDE.md". */
|
|
20
|
+
label: string;
|
|
21
|
+
lines: number;
|
|
22
|
+
bytes: number;
|
|
23
|
+
}
|
|
24
|
+
export interface SettingsFile {
|
|
25
|
+
/** "user", "project", "local" or "managed". */
|
|
26
|
+
scope: 'user' | 'project' | 'local' | 'managed';
|
|
27
|
+
label: string;
|
|
28
|
+
allow: string[];
|
|
29
|
+
ask: string[];
|
|
30
|
+
deny: string[];
|
|
31
|
+
defaultMode: string | null;
|
|
32
|
+
additionalDirectories: number;
|
|
33
|
+
/** Hook event names that have at least one handler. */
|
|
34
|
+
hookEvents: string[];
|
|
35
|
+
/** The command of each command hook, with the event it runs on. Used on this machine only. */
|
|
36
|
+
hookCommands: Array<{
|
|
37
|
+
event: string;
|
|
38
|
+
command: string;
|
|
39
|
+
}>;
|
|
40
|
+
sandboxEnabled: boolean | null;
|
|
41
|
+
cleanupPeriodDays: number | null;
|
|
42
|
+
}
|
|
43
|
+
export interface SetupFacts {
|
|
44
|
+
platform: string;
|
|
45
|
+
memory: MemoryFile[];
|
|
46
|
+
/** Files under .claude/rules/ and ~/.claude/rules/. */
|
|
47
|
+
ruleFiles: number;
|
|
48
|
+
/** The auto memory index, when the project has one. */
|
|
49
|
+
autoMemoryIndex: MemoryFile | null;
|
|
50
|
+
settings: SettingsFile[];
|
|
51
|
+
skills: {
|
|
52
|
+
project: number;
|
|
53
|
+
user: number;
|
|
54
|
+
};
|
|
55
|
+
subagents: {
|
|
56
|
+
project: number;
|
|
57
|
+
user: number;
|
|
58
|
+
};
|
|
59
|
+
/** Each subagent file, and whether its frontmatter limits its tools (`tools` or `disallowedTools`). */
|
|
60
|
+
subagentFiles: Array<{
|
|
61
|
+
name: string;
|
|
62
|
+
limitsTools: boolean;
|
|
63
|
+
}>;
|
|
64
|
+
/** .claude/commands/*.md, the older form that the docs merge into skills. */
|
|
65
|
+
legacyCommands: number;
|
|
66
|
+
mcpServers: {
|
|
67
|
+
project: number;
|
|
68
|
+
user: number;
|
|
69
|
+
};
|
|
70
|
+
/** Paths, from the project root, of files that usually hold secrets, such as "apps/api/.env". Names only, never contents. */
|
|
71
|
+
secretFiles: string[];
|
|
72
|
+
}
|
|
73
|
+
export interface Check {
|
|
74
|
+
id: string;
|
|
75
|
+
group: Group;
|
|
76
|
+
title: string;
|
|
77
|
+
status: Status;
|
|
78
|
+
/** What was found. */
|
|
79
|
+
detail: string;
|
|
80
|
+
/** What to change. Empty for a pass or a plain fact. */
|
|
81
|
+
fix: string;
|
|
82
|
+
/** The documentation page the check rests on. */
|
|
83
|
+
source: string;
|
|
84
|
+
/**
|
|
85
|
+
* Text to paste into Claude Code to make the fix: a prompt, or a slash command. Empty when
|
|
86
|
+
* nothing needs fixing. A prompt always asks to see the change before it is saved.
|
|
87
|
+
*/
|
|
88
|
+
prompt: string;
|
|
89
|
+
}
|
|
90
|
+
/** "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." */
|
|
91
|
+
export declare const MEMORY_LINE_TARGET = 200;
|
|
92
|
+
/** Twice the target. Our own line for "this is far over", not the docs'. */
|
|
93
|
+
export declare const MEMORY_LINE_FAIL = 400;
|
|
94
|
+
/** A deny rule that keeps the agent from reading a secrets file. */
|
|
95
|
+
export declare function deniesSecrets(rule: string): boolean;
|
|
96
|
+
/** An allow rule that approves every shell command. */
|
|
97
|
+
export declare function allowsEveryCommand(rule: string): boolean;
|
|
98
|
+
type Unprompted = Omit<Check, 'prompt'>;
|
|
99
|
+
/** A command that tests, lints, type-checks or builds: something the agent can run to check a change. */
|
|
100
|
+
export declare function looksLikeACheck(command: string): boolean;
|
|
101
|
+
/**
|
|
102
|
+
* The text to paste into Claude Code for a check that needs a fix. Each prompt names the goal,
|
|
103
|
+
* the constraint from the docs, and asks for the plan or the diff first, so pasting one never
|
|
104
|
+
* changes a file unseen.
|
|
105
|
+
*/
|
|
106
|
+
export declare function promptFor(check: Unprompted, facts: SetupFacts): string;
|
|
107
|
+
export declare function runChecks(facts: SetupFacts): Check[];
|
|
108
|
+
export interface Summary {
|
|
109
|
+
pass: number;
|
|
110
|
+
warn: number;
|
|
111
|
+
fail: number;
|
|
112
|
+
info: number;
|
|
113
|
+
/** Passes as a share of the checks that can pass or fail, 0 to 100. Plain facts are not counted. */
|
|
114
|
+
score: number;
|
|
115
|
+
}
|
|
116
|
+
export declare function summarize(checks: Check[]): Summary;
|
|
117
|
+
/** The levels --fail-on takes. "warn" also counts a fail; an info row never counts. */
|
|
118
|
+
export type FailOn = 'fail' | 'warn';
|
|
119
|
+
export declare const FAIL_ON_LEVELS: readonly FailOn[];
|
|
120
|
+
/** The checks at the given level or worse. Empty means a CI step should pass. */
|
|
121
|
+
export declare function failing(checks: Check[], level: FailOn): Check[];
|
|
122
|
+
export interface BoardCheck {
|
|
123
|
+
id: string;
|
|
124
|
+
group: Group;
|
|
125
|
+
title: string;
|
|
126
|
+
status: Status;
|
|
127
|
+
}
|
|
128
|
+
export interface BoardSummary {
|
|
129
|
+
score: number;
|
|
130
|
+
pass: number;
|
|
131
|
+
warn: number;
|
|
132
|
+
fail: number;
|
|
133
|
+
checks: BoardCheck[];
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* A summary that is safe to send to a team board, if you build one: the score, the counts, and each check's
|
|
137
|
+
* id, group, title and status. It is built field by field, so a field added to Check later is
|
|
138
|
+
* not sent by accident. What was found, the fix and the prompt name the developer's files, and
|
|
139
|
+
* they are never part of this.
|
|
140
|
+
*/
|
|
141
|
+
export declare function boardSummary(checks: Check[]): BoardSummary;
|
|
142
|
+
export {};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { SetupFacts } from './groundcrew-core.js';
|
|
2
|
+
export declare const tilde: (file: string) => string;
|
|
3
|
+
/**
|
|
4
|
+
* Whether this process may list the project folder. A background process on macOS is refused
|
|
5
|
+
* folders such as ~/Desktop, and a refused folder looks the same as an empty one to
|
|
6
|
+
* `existsSync`. A caller must check this first, or every check would report "nothing found".
|
|
7
|
+
*/
|
|
8
|
+
export declare function canRead(project: string): boolean;
|
|
9
|
+
export declare function gather(project: string): {
|
|
10
|
+
facts: SetupFacts;
|
|
11
|
+
filesRead: string[];
|
|
12
|
+
};
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* JQ Groundcrew: the page, as one function from a report to an HTML string.
|
|
3
|
+
*
|
|
4
|
+
* The page loads nothing from the network, so opening it sends nothing anywhere. Its one
|
|
5
|
+
* script is inline and does one thing: a "Copy" button puts a suggested prompt on the
|
|
6
|
+
* clipboard. With scripts off, the prompt is still on the page as text to select.
|
|
7
|
+
*
|
|
8
|
+
* Layout: what needs a fix comes first, as full cards with the prompt to paste. What is
|
|
9
|
+
* already good, and plain facts, are one line each, so they do not bury the fixes. Status is
|
|
10
|
+
* never color alone: each row has an icon and a word. Light and dark follow the system.
|
|
11
|
+
*/
|
|
12
|
+
import type { Check, Summary } from './groundcrew-core.js';
|
|
13
|
+
export interface Report {
|
|
14
|
+
project: string;
|
|
15
|
+
generatedAt: string;
|
|
16
|
+
filesRead: string[];
|
|
17
|
+
checks: Check[];
|
|
18
|
+
summary: Summary;
|
|
19
|
+
}
|
|
20
|
+
export declare function renderPage(report: Report): string;
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/** The checks, the reader and the page, for running Groundcrew inside your own tool. */
|
|
2
|
+
export * from './groundcrew-core.js';
|
|
3
|
+
export { canRead, gather, tilde } from './groundcrew-gather.js';
|
|
4
|
+
export { DEFAULT_PORT, exitCodeFor, parseArgs, report, runLocal, type Parsed } from './groundcrew-cli.js';
|
|
5
|
+
export { renderPage, type Report } from './groundcrew-page.js';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,61 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@point-seven-studio/jq-groundcrew",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.2",
|
|
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
|
+
"dist/index.mjs",
|
|
12
|
+
"dist/types",
|
|
13
|
+
"README.md",
|
|
14
|
+
"LICENSE",
|
|
15
|
+
"NOTICE"
|
|
16
|
+
],
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=18"
|
|
19
|
+
},
|
|
20
|
+
"keywords": [
|
|
21
|
+
"claude-code",
|
|
22
|
+
"developer-tools",
|
|
23
|
+
"ai-coding",
|
|
24
|
+
"setup",
|
|
25
|
+
"guardrails"
|
|
26
|
+
],
|
|
27
|
+
"author": "Point Seven Studio",
|
|
28
|
+
"license": "Apache-2.0",
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "git+https://github.com/point-seven-studio/jq-tools.git",
|
|
32
|
+
"directory": "packages/groundcrew"
|
|
33
|
+
},
|
|
34
|
+
"scripts": {
|
|
35
|
+
"typecheck": "tsc --noEmit",
|
|
36
|
+
"test": "vitest run",
|
|
37
|
+
"build": "./build.sh",
|
|
38
|
+
"check": "npm run typecheck && npm test && ./build.sh --check",
|
|
39
|
+
"prepublishOnly": "npm run check"
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@types/node": "^20.14.0",
|
|
43
|
+
"esbuild": "^0.21.5",
|
|
44
|
+
"typescript": "^5.4.5",
|
|
45
|
+
"vitest": "^1.6.0"
|
|
46
|
+
},
|
|
47
|
+
"publishConfig": {
|
|
48
|
+
"access": "public"
|
|
49
|
+
},
|
|
50
|
+
"homepage": "https://github.com/point-seven-studio/jq-tools/tree/main/packages/groundcrew#readme",
|
|
51
|
+
"bugs": {
|
|
52
|
+
"url": "https://github.com/point-seven-studio/jq-tools/issues"
|
|
53
|
+
},
|
|
54
|
+
"exports": {
|
|
55
|
+
".": {
|
|
56
|
+
"types": "./dist/types/index.d.ts",
|
|
57
|
+
"default": "./dist/index.mjs"
|
|
58
|
+
}
|
|
59
|
+
},
|
|
60
|
+
"types": "./dist/types/index.d.ts"
|
|
61
|
+
}
|