@houserules/payload 0.0.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Devin T. Currie
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,30 @@
1
+ # @houserules/payload
2
+
3
+ The shared libraries that back houserules's installed hooks: reading `houserules.config.json`,
4
+ reading and writing the backlog/decision ledgers, listing workspace packages, and running
5
+ child processes. Every one of them ships with zero runtime dependencies, node builtins only,
6
+ because they are copied byte for byte into a user's `.claude/scripts/lib/` and executed there
7
+ on bare node.
8
+
9
+ This package is not a plugin. It contributes no modules and is never installed directly.
10
+ [`@houserules/cli`](https://github.com/DTCurrie/houserules/tree/main/packages/cli)
11
+ depends on it directly, copying these libs alongside every hook script that imports one, and any
12
+ first-party or third-party plugin that needs one of them imports it by package name:
13
+
14
+ ```ts
15
+ import { loadConfigSafe } from '@houserules/payload/config';
16
+ ```
17
+
18
+ That import never reaches the published `.mjs`. `@houserules/cli`'s payload build rewrites it to
19
+ a relative path pointing at a copy of the lib placed alongside the importing script, which is
20
+ what keeps the installed hook dependency-free.
21
+
22
+ ## Part of houserules
23
+
24
+ [houserules](https://github.com/DTCurrie/houserules) is portable Claude Code
25
+ infrastructure that keeps the agent's context lean. The
26
+ [package list](https://github.com/DTCurrie/houserules#packages) has the rest.
27
+
28
+ ## License
29
+
30
+ MIT. See [LICENSE](./LICENSE).
package/package.json ADDED
@@ -0,0 +1,87 @@
1
+ {
2
+ "name": "@houserules/payload",
3
+ "version": "0.0.0",
4
+ "description": "houserules: shared payload libraries, copied into .claude/scripts/lib and executed on bare node with zero runtime dependencies.",
5
+ "type": "module",
6
+ "publishConfig": {
7
+ "access": "public"
8
+ },
9
+ "files": [
10
+ "payload-dist"
11
+ ],
12
+ "exports": {
13
+ "./package.json": "./package.json",
14
+ "./*": {
15
+ "types": "./payload-dist/scripts/lib/*.d.mts",
16
+ "default": "./payload-dist/scripts/lib/*.mjs"
17
+ }
18
+ },
19
+ "wireit": {
20
+ "build": {
21
+ "command": "tsc -p tsconfig.payload.json && publint",
22
+ "files": [
23
+ "payload/**",
24
+ "!payload/**/__test__/**",
25
+ "tsconfig.payload.json"
26
+ ],
27
+ "output": [
28
+ "payload-dist/**"
29
+ ]
30
+ },
31
+ "check": {
32
+ "command": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.payload.json",
33
+ "dependencies": [
34
+ "../test:build"
35
+ ],
36
+ "files": [
37
+ "payload/**/*.mts",
38
+ "payload/**/__test__/**/*.ts",
39
+ "tsconfig.json",
40
+ "tsconfig.payload.json"
41
+ ],
42
+ "output": []
43
+ },
44
+ "test": {
45
+ "command": "vitest run",
46
+ "dependencies": [
47
+ "../test:build"
48
+ ],
49
+ "files": [
50
+ "payload/**",
51
+ "vitest.config.ts"
52
+ ],
53
+ "output": []
54
+ }
55
+ },
56
+ "engines": {
57
+ "node": ">=22"
58
+ },
59
+ "repository": {
60
+ "type": "git",
61
+ "url": "git+https://github.com/DTCurrie/houserules.git",
62
+ "directory": "packages/payload"
63
+ },
64
+ "homepage": "https://github.com/DTCurrie/houserules/tree/main/packages/payload#readme",
65
+ "bugs": "https://github.com/DTCurrie/houserules/issues",
66
+ "license": "MIT",
67
+ "author": "Devin T. Currie (https://github.com/DTCurrie)",
68
+ "keywords": [
69
+ "houserules",
70
+ "claude-code",
71
+ "hooks"
72
+ ],
73
+ "devDependencies": {
74
+ "@types/node": "^26.1.2",
75
+ "publint": "^0.3.23",
76
+ "type-fest": "^5.8.0",
77
+ "typescript": "^6.0.3",
78
+ "vitest": "^4.1.10",
79
+ "wireit": "^0.14.13",
80
+ "@houserules/test": "0.0.0"
81
+ },
82
+ "scripts": {
83
+ "build": "wireit",
84
+ "check": "wireit",
85
+ "test": "wireit"
86
+ }
87
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * A backlog entry ID: `<PREFIX>-<6 hex>`, where PREFIX is one or more uppercase ASCII
3
+ * characters. The single source of truth for the shape, shared by backlog-log.mjs, which
4
+ * mints IDs, and package-changelog.mjs, which scrapes them out of commit messages. Change
5
+ * the shape here and both follow.
6
+ */
7
+ export declare const BACKLOG_ID: RegExp;
8
+ export declare const ENTRY_HEAD: RegExp;
9
+ /**
10
+ * Content-hashed, so the same prefix and title at a given instant are stable while a
11
+ * re-add gets a fresh ID through the timestamp.
12
+ */
13
+ export declare function makeId(prefix: string, title: string, iso: string): string;
@@ -0,0 +1,20 @@
1
+ import { createHash } from 'node:crypto';
2
+ /**
3
+ * A backlog entry ID: `<PREFIX>-<6 hex>`, where PREFIX is one or more uppercase ASCII
4
+ * characters. The single source of truth for the shape, shared by backlog-log.mjs, which
5
+ * mints IDs, and package-changelog.mjs, which scrapes them out of commit messages. Change
6
+ * the shape here and both follow.
7
+ */
8
+ export const BACKLOG_ID = /\b[A-Z][A-Z0-9]*-[0-9a-f]{6}\b/g;
9
+ export const ENTRY_HEAD = /^## \[([A-Z][A-Z0-9]*-[0-9a-f]{6})\] (.+)$/;
10
+ /**
11
+ * Content-hashed, so the same prefix and title at a given instant are stable while a
12
+ * re-add gets a fresh ID through the timestamp.
13
+ */
14
+ export function makeId(prefix, title, iso) {
15
+ const h = createHash('sha256')
16
+ .update(`${prefix}|${title}|${iso}`)
17
+ .digest('hex')
18
+ .slice(0, 6);
19
+ return `${prefix}-${h}`;
20
+ }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * A single comment found in JS/TS source.
3
+ *
4
+ * `text` is the raw source slice including its delimiters (`//`, `/* ... *\/`), so a caller
5
+ * can inspect the exact bytes rather than a re-derived body.
6
+ */
7
+ export interface Comment {
8
+ text: string;
9
+ /** 1-indexed line the comment starts on. */
10
+ line: number;
11
+ kind: 'line' | 'block' | 'tsdoc';
12
+ }
13
+ /**
14
+ * Extracts every `//` and `/* *\/` comment from JS/TS source, without misreading comment-like
15
+ * text inside string literals, template literals (including `${}` interpolation), or regex
16
+ * literals as a real comment.
17
+ *
18
+ * Regex-versus-division is genuinely ambiguous without a full parser: `/` can open a regex
19
+ * literal or mean division, and the two read identically until more context resolves them.
20
+ * This uses the standard last-significant-token heuristic (regex is allowed right after an
21
+ * operator, `(`, `,`, `;`, `{`, `}`, `[`, or a keyword like `return`, and disallowed right
22
+ * after an identifier, a number, `)`, or `]`), which is what most parser-free JS tokenizers
23
+ * use and correctly handles `/https:\/\//`. It can still misjudge pathological input such as
24
+ * `a\n/re/g` split oddly, or division immediately after a keyword also used as an identifier.
25
+ * On the ambiguous side this favors treating `/` as a regex start, since misreading a regex's
26
+ * body as code risks reading its own `//` as a comment (a false comment finding), while
27
+ * misreading division as a regex start only swallows code until the next unescaped `/` or
28
+ * the end of the line, which cannot itself invent a comment.
29
+ */
30
+ export declare function scanComments(source: string): Comment[];
@@ -0,0 +1,244 @@
1
+ /**
2
+ * Keywords after which a following `/` starts an expression, so it is a regex, not division.
3
+ * `return x /y/.test(z)/2` is legal but rare, and this list favors the common case.
4
+ */
5
+ const REGEX_ALLOWED_AFTER = new Set([
6
+ 'return',
7
+ 'typeof',
8
+ 'instanceof',
9
+ 'in',
10
+ 'of',
11
+ 'new',
12
+ 'delete',
13
+ 'void',
14
+ 'yield',
15
+ 'case',
16
+ 'do',
17
+ 'else',
18
+ 'throw',
19
+ 'await',
20
+ ]);
21
+ const IDENTIFIER_START = /[A-Za-z_$]/;
22
+ const IDENTIFIER_PART = /[A-Za-z0-9_$]/;
23
+ const DIGIT = /[0-9]/;
24
+ const NUMBER_PART = /[0-9.eExXa-fA-FoObB_]/;
25
+ function classifyBlock(raw) {
26
+ if (raw === '/**/')
27
+ return 'block';
28
+ if (!raw.startsWith('/**'))
29
+ return 'block';
30
+ if (raw.startsWith('/***'))
31
+ return 'block';
32
+ return 'tsdoc';
33
+ }
34
+ /**
35
+ * Scans a JS/TS regex literal starting at the opening `/` and returns the index past its
36
+ * closing delimiter and flags, or null when it cannot be a valid regex literal (an
37
+ * unterminated one, since JS regex literals cannot span a line).
38
+ */
39
+ function scanRegexLiteral(source, start) {
40
+ let i = start + 1;
41
+ let inClass = false;
42
+ while (i < source.length) {
43
+ const ch = source[i];
44
+ if (ch === '\n')
45
+ return null;
46
+ if (ch === '\\') {
47
+ i += 2;
48
+ continue;
49
+ }
50
+ if (ch === '[') {
51
+ inClass = true;
52
+ i++;
53
+ continue;
54
+ }
55
+ if (ch === ']') {
56
+ inClass = false;
57
+ i++;
58
+ continue;
59
+ }
60
+ if (ch === '/' && !inClass) {
61
+ i++;
62
+ while (i < source.length && /[a-zA-Z]/.test(source[i]))
63
+ i++;
64
+ return i;
65
+ }
66
+ i++;
67
+ }
68
+ return null;
69
+ }
70
+ /**
71
+ * Extracts every `//` and `/* *\/` comment from JS/TS source, without misreading comment-like
72
+ * text inside string literals, template literals (including `${}` interpolation), or regex
73
+ * literals as a real comment.
74
+ *
75
+ * Regex-versus-division is genuinely ambiguous without a full parser: `/` can open a regex
76
+ * literal or mean division, and the two read identically until more context resolves them.
77
+ * This uses the standard last-significant-token heuristic (regex is allowed right after an
78
+ * operator, `(`, `,`, `;`, `{`, `}`, `[`, or a keyword like `return`, and disallowed right
79
+ * after an identifier, a number, `)`, or `]`), which is what most parser-free JS tokenizers
80
+ * use and correctly handles `/https:\/\//`. It can still misjudge pathological input such as
81
+ * `a\n/re/g` split oddly, or division immediately after a keyword also used as an identifier.
82
+ * On the ambiguous side this favors treating `/` as a regex start, since misreading a regex's
83
+ * body as code risks reading its own `//` as a comment (a false comment finding), while
84
+ * misreading division as a regex start only swallows code until the next unescaped `/` or
85
+ * the end of the line, which cannot itself invent a comment.
86
+ */
87
+ export function scanComments(source) {
88
+ const comments = [];
89
+ const frames = [];
90
+ let line = 1;
91
+ let prevAllowsRegex = true;
92
+ let i = 0;
93
+ const advance = () => {
94
+ if (source[i] === '\n')
95
+ line++;
96
+ i++;
97
+ };
98
+ /**
99
+ * Consumes a single or double quoted string, including its closing quote.
100
+ *
101
+ * Split out of the main scan loop so the escape branch does not push the loop past four
102
+ * levels of nesting. A backslash consumes the next character whatever it is, which is what
103
+ * keeps an escaped quote from ending the string early.
104
+ */
105
+ const skipQuoted = (quote) => {
106
+ advance();
107
+ while (i < source.length && source[i] !== quote) {
108
+ if (source[i] === '\\') {
109
+ advance();
110
+ if (i < source.length)
111
+ advance();
112
+ continue;
113
+ }
114
+ advance();
115
+ }
116
+ if (i < source.length)
117
+ advance();
118
+ };
119
+ while (i < source.length) {
120
+ const top = frames[frames.length - 1];
121
+ if (top?.kind === 'template') {
122
+ const ch = source[i];
123
+ if (ch === '\\') {
124
+ advance();
125
+ if (i < source.length)
126
+ advance();
127
+ continue;
128
+ }
129
+ if (ch === '`') {
130
+ frames.pop();
131
+ advance();
132
+ prevAllowsRegex = false;
133
+ continue;
134
+ }
135
+ if (ch === '$' && source[i + 1] === '{') {
136
+ frames.push({ kind: 'interpolation', braceDepth: 0 });
137
+ advance();
138
+ advance();
139
+ prevAllowsRegex = true;
140
+ continue;
141
+ }
142
+ advance();
143
+ continue;
144
+ }
145
+ const ch = source[i];
146
+ const next = source[i + 1];
147
+ if (ch === '/' && next === '/') {
148
+ const start = line;
149
+ let end = i + 2;
150
+ while (end < source.length && source[end] !== '\n')
151
+ end++;
152
+ comments.push({ text: source.slice(i, end), line: start, kind: 'line' });
153
+ i = end;
154
+ continue;
155
+ }
156
+ if (ch === '/' && next === '*') {
157
+ const start = line;
158
+ let end = i + 2;
159
+ while (end < source.length &&
160
+ !(source[end] === '*' && source[end + 1] === '/')) {
161
+ if (source[end] === '\n')
162
+ line++;
163
+ end++;
164
+ }
165
+ end = Math.min(end + 2, source.length);
166
+ const raw = source.slice(i, end);
167
+ comments.push({ text: raw, line: start, kind: classifyBlock(raw) });
168
+ i = end;
169
+ prevAllowsRegex = false;
170
+ continue;
171
+ }
172
+ if (ch === "'" || ch === '"') {
173
+ skipQuoted(ch);
174
+ prevAllowsRegex = false;
175
+ continue;
176
+ }
177
+ if (ch === '`') {
178
+ frames.push({ kind: 'template' });
179
+ advance();
180
+ continue;
181
+ }
182
+ if (top?.kind === 'interpolation') {
183
+ if (ch === '{') {
184
+ top.braceDepth++;
185
+ advance();
186
+ prevAllowsRegex = true;
187
+ continue;
188
+ }
189
+ if (ch === '}') {
190
+ if (top.braceDepth === 0) {
191
+ frames.pop();
192
+ advance();
193
+ continue;
194
+ }
195
+ top.braceDepth--;
196
+ advance();
197
+ prevAllowsRegex = false;
198
+ continue;
199
+ }
200
+ }
201
+ if (ch === '/' && prevAllowsRegex) {
202
+ const end = scanRegexLiteral(source, i);
203
+ if (end !== null) {
204
+ i = end;
205
+ prevAllowsRegex = false;
206
+ continue;
207
+ }
208
+ }
209
+ if (ch === ' ' || ch === '\t' || ch === '\r') {
210
+ i++;
211
+ continue;
212
+ }
213
+ if (ch === '\n') {
214
+ line++;
215
+ i++;
216
+ continue;
217
+ }
218
+ if (IDENTIFIER_START.test(ch)) {
219
+ let end = i + 1;
220
+ while (end < source.length && IDENTIFIER_PART.test(source[end]))
221
+ end++;
222
+ const word = source.slice(i, end);
223
+ i = end;
224
+ prevAllowsRegex = REGEX_ALLOWED_AFTER.has(word);
225
+ continue;
226
+ }
227
+ if (DIGIT.test(ch)) {
228
+ let end = i + 1;
229
+ while (end < source.length && NUMBER_PART.test(source[end]))
230
+ end++;
231
+ i = end;
232
+ prevAllowsRegex = false;
233
+ continue;
234
+ }
235
+ if (ch === ')' || ch === ']') {
236
+ advance();
237
+ prevAllowsRegex = false;
238
+ continue;
239
+ }
240
+ advance();
241
+ prevAllowsRegex = true;
242
+ }
243
+ return comments;
244
+ }
@@ -0,0 +1,139 @@
1
+ export interface RunnerBlock {
2
+ runner?: string;
3
+ filterFlag?: string;
4
+ runScriptPrefix?: string[];
5
+ commands?: string[];
6
+ /** `fix` only: run the fixer when a subagent stops. */
7
+ onSubagentStop?: boolean;
8
+ /** `fix` only: per-command file extensions, e.g. {"lint:fix": ["ts","tsx"]}. */
9
+ commandExtensions?: Record<string, string[]>;
10
+ /** `verify` only: branch the changed-file diff is taken against. */
11
+ baseBranch?: string;
12
+ }
13
+ export interface ConfigTarget {
14
+ name: string;
15
+ prefix?: string;
16
+ packageName?: string;
17
+ pathPrefix?: string;
18
+ sourcePath?: string;
19
+ label?: string;
20
+ fixCommands?: string[] | null;
21
+ verifyCommands?: string[] | null;
22
+ changelogPath?: string;
23
+ logPath?: string;
24
+ regen?: {
25
+ sourceGlob?: string;
26
+ command?: string;
27
+ };
28
+ }
29
+ /**
30
+ * The shape the hooks read, typed loosely on purpose. `src/core/config.ts` holds the
31
+ * strict zod schema and is the authority on what a valid houserules.config.json looks like. This
32
+ * reader is the other half of that split. It runs inside a user's repo with no
33
+ * dependencies and has to cope with a config the schema would reject outright, because a
34
+ * hook that dies on a bad config is noise on every tool call. Every field is therefore
35
+ * optional and callers default rather than assume.
36
+ *
37
+ * The two cannot be one type. The payload compiles with `rootDir=payload` and can never
38
+ * import from `src/`, which would drag zod into a user's repo.
39
+ */
40
+ export interface HouseConfig {
41
+ version?: number;
42
+ packageManager?: string;
43
+ fix?: RunnerBlock;
44
+ verify?: RunnerBlock;
45
+ lintableExtensions?: string[];
46
+ generatedFilePattern?: string;
47
+ guard?: {
48
+ gitCommit?: boolean;
49
+ gitPush?: boolean;
50
+ gitStash?: boolean;
51
+ prCreate?: boolean;
52
+ custom?: {
53
+ pattern: string;
54
+ message: string;
55
+ }[];
56
+ };
57
+ changesets?: {
58
+ enabled?: boolean;
59
+ stopCheck?: boolean;
60
+ baseBranch?: string;
61
+ };
62
+ ledger?: {
63
+ enabled?: boolean;
64
+ };
65
+ ledgers?: {
66
+ dir?: string;
67
+ };
68
+ readGuard?: {
69
+ enabled?: boolean;
70
+ maxBytes?: number;
71
+ denyGlobs?: string[];
72
+ };
73
+ claudeMd?: {
74
+ managed?: boolean;
75
+ };
76
+ targets: ConfigTarget[];
77
+ [key: string]: unknown;
78
+ }
79
+ /** What `filterFlag` means when a runner block omits it: a workspace, filtered per package. */
80
+ export declare const DEFAULT_FILTER_FLAG = "--filter";
81
+ /**
82
+ * The commands that actually run for one target, from its own override and the block's list.
83
+ *
84
+ * `null` and `undefined` are different answers, which is why this is not a bare `??`. An
85
+ * absent override inherits the block's commands. An explicit `null` means this target has
86
+ * none, the escape hatch for a package the runner should skip entirely.
87
+ */
88
+ export declare function resolveTargetCommands(override: string[] | null | undefined, blockCommands: string[] | undefined): string[];
89
+ /**
90
+ * Whether a runner block's commands run as REPO-ROOT scripts rather than once per package.
91
+ *
92
+ * An empty `filterFlag` is how a single-package repo, or a workspace whose lint and format
93
+ * live at the root, is spelled. Both runners drop the package name from the argv in that
94
+ * shape, so the script that has to exist is the ROOT one no matter which target contributed
95
+ * the command.
96
+ */
97
+ export declare function runsAtRepoRoot(block: RunnerBlock | undefined): boolean;
98
+ export declare function repoRoot(): string;
99
+ /**
100
+ * `repoRoot()` for a script that must not crash. Returns null outside a git work tree, or
101
+ * when `git` is absent, rather than throwing.
102
+ *
103
+ * A runtime-invoked payload script is required to exit 0 on every failure path, and a
104
+ * throw at module load defeats that before any handler can run. Such a script resolves its
105
+ * root through this and exits cleanly on null.
106
+ */
107
+ export declare function repoRootSafe(): string | null;
108
+ export declare const GUARD_DEFAULTS: {
109
+ gitCommit: boolean;
110
+ gitPush: boolean;
111
+ gitStash: boolean;
112
+ prCreate: boolean;
113
+ custom: never[];
114
+ };
115
+ /**
116
+ * Defaults for the opt-in PreToolUse(Read) guard. Only unbounded whole-file reads, those
117
+ * with no offset or limit, of generated or oversized files are redirected. `maxBytes` is
118
+ * deliberately high so it catches only genuinely huge files, and `denyGlobs` handles the
119
+ * common always-generated cases regardless of size.
120
+ */
121
+ export declare const READ_GUARD_DEFAULTS: {
122
+ enabled: boolean;
123
+ maxBytes: number;
124
+ denyGlobs: string[];
125
+ };
126
+ /**
127
+ * Reads `<repo>/.claude/houserules.config.json`, the declarative file adapting the scripts to a
128
+ * repo's package layout and toolchain. CLI-style scripts demand a config and exit loudly
129
+ * without one. Hooks must call `loadConfigSafe()` instead.
130
+ */
131
+ export declare function loadConfig(root?: string, { required }?: {
132
+ required?: boolean;
133
+ }): HouseConfig;
134
+ /**
135
+ * The loader hooks must use. It never exits and never throws, returning an empty config
136
+ * in the worst case. A hook that crashes on a missing or broken config is noise on every
137
+ * single tool call.
138
+ */
139
+ export declare function loadConfigSafe(): HouseConfig;