@houserules/payload 0.1.0 → 0.2.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@houserules/payload",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "houserules: shared payload libraries, copied into .claude/scripts/lib and executed on bare node with zero runtime dependencies.",
5
5
  "type": "module",
6
6
  "publishConfig": {
@@ -95,6 +95,19 @@ export declare function resolveTargetCommands(override: string[] | null | undefi
95
95
  * the command.
96
96
  */
97
97
  export declare function runsAtRepoRoot(block: RunnerBlock | undefined): boolean;
98
+ /**
99
+ * The work tree root, throwing outside one. Memoized per process, keyed by the cwd it was
100
+ * resolved from.
101
+ *
102
+ * The memo is the point. `loadConfigSafe()` resolves the root internally and the hook
103
+ * calling it usually resolved the root too, so a hook invocation spawned
104
+ * `git rev-parse --show-toplevel` twice. A hook is a one-shot process, so the answer cannot
105
+ * go stale within one.
106
+ *
107
+ * The key is the cwd because the answer depends on it, and a long-lived caller such as a
108
+ * test can chdir between calls. Only a successful resolution is memoized, so a throw stays
109
+ * a throw and `repoRootSafe()` keeps reporting null outside a work tree.
110
+ */
98
111
  export declare function repoRoot(): string;
99
112
  /**
100
113
  * `repoRoot()` for a script that must not crash. Returns null outside a git work tree, or
@@ -135,5 +148,9 @@ export declare function loadConfig(root?: string, { required }?: {
135
148
  * The loader hooks must use. It never exits and never throws, returning an empty config
136
149
  * in the worst case. A hook that crashes on a missing or broken config is noise on every
137
150
  * single tool call.
151
+ *
152
+ * @param root Pass the root when the caller already resolved one, which skips the git
153
+ * spawn entirely. `proc.mts` holds its own root memo, so a script that resolved the root
154
+ * through that one would otherwise still pay a second spawn here.
138
155
  */
139
- export declare function loadConfigSafe(): HouseConfig;
156
+ export declare function loadConfigSafe(root?: string): HouseConfig;
@@ -26,12 +26,32 @@ export function resolveTargetCommands(override, blockCommands) {
26
26
  export function runsAtRepoRoot(block) {
27
27
  return !(block?.filterFlag ?? DEFAULT_FILTER_FLAG);
28
28
  }
29
+ const rootByCwd = new Map();
30
+ /**
31
+ * The work tree root, throwing outside one. Memoized per process, keyed by the cwd it was
32
+ * resolved from.
33
+ *
34
+ * The memo is the point. `loadConfigSafe()` resolves the root internally and the hook
35
+ * calling it usually resolved the root too, so a hook invocation spawned
36
+ * `git rev-parse --show-toplevel` twice. A hook is a one-shot process, so the answer cannot
37
+ * go stale within one.
38
+ *
39
+ * The key is the cwd because the answer depends on it, and a long-lived caller such as a
40
+ * test can chdir between calls. Only a successful resolution is memoized, so a throw stays
41
+ * a throw and `repoRootSafe()` keeps reporting null outside a work tree.
42
+ */
29
43
  export function repoRoot() {
30
- return execSync('git rev-parse --show-toplevel', {
44
+ const cwd = process.cwd();
45
+ const cached = rootByCwd.get(cwd);
46
+ if (cached !== undefined)
47
+ return cached;
48
+ const root = execSync('git rev-parse --show-toplevel', {
31
49
  stdio: ['ignore', 'pipe', 'ignore'],
32
50
  })
33
51
  .toString()
34
52
  .trim();
53
+ rootByCwd.set(cwd, root);
54
+ return root;
35
55
  }
36
56
  /**
37
57
  * `repoRoot()` for a script that must not crash. Returns null outside a git work tree, or
@@ -120,10 +140,14 @@ export function loadConfig(root = repoRoot(), { required = true } = {}) {
120
140
  * The loader hooks must use. It never exits and never throws, returning an empty config
121
141
  * in the worst case. A hook that crashes on a missing or broken config is noise on every
122
142
  * single tool call.
143
+ *
144
+ * @param root Pass the root when the caller already resolved one, which skips the git
145
+ * spawn entirely. `proc.mts` holds its own root memo, so a script that resolved the root
146
+ * through that one would otherwise still pay a second spawn here.
123
147
  */
124
- export function loadConfigSafe() {
148
+ export function loadConfigSafe(root) {
125
149
  try {
126
- return loadConfig(repoRoot(), { required: false });
150
+ return loadConfig(root ?? repoRoot(), { required: false });
127
151
  }
128
152
  catch {
129
153
  return EMPTY;
@@ -1,3 +1,4 @@
1
+ import { type LedgerKind } from './ledger-index.mjs';
1
2
  export declare const SEPARATOR = "---";
2
3
  export declare const nowIso: () => string;
3
4
  export declare const todayDate: () => string;
@@ -39,10 +40,28 @@ export declare function ledgerPath(repoRoot: string, name: string, configuredDir
39
40
  * produces and a decision never does, since superseding leaves the entry rendered.
40
41
  */
41
42
  export declare function rebuildWouldDropEntries(file: string, nextContent: string, intentionallyDropped?: ReadonlySet<string>): boolean;
43
+ /** The local enable token a projects sync bootstrap writes into the ledger directory. */
44
+ export declare const PROJECTS_ENABLE_TOKEN = ".projects.json";
45
+ /**
46
+ * Whether the pulled index, rather than the queue, is the store this ledger's surfaces render
47
+ * from.
48
+ *
49
+ * Without a projects sync the queue is the only durable copy of an entry, so a surface holding
50
+ * entries the queue cannot account for means the queue was truncated and rewriting would
51
+ * destroy them. With a sync configured the model inverts: the queue jsonl drains to zero after
52
+ * a successful push, and the board is the durable store, pulled into the index. A fully synced
53
+ * repo therefore sits at zero queued entries with a rendered surface, which the queue
54
+ * comparison reads as corruption and refuses forever.
55
+ *
56
+ * The index has to be on disk for this. A repo that enabled the sync but has never pulled
57
+ * knows nothing about the board, so the queue comparison is still the only safe one there.
58
+ */
59
+ export declare function indexIsAuthoritative(ledgerDirectory: string, kind: LedgerKind): boolean;
42
60
  export declare function readSurface(file: string): string;
43
61
  /** Reads the body from the argument, or from stdin when it was omitted and stdin is a pipe. */
44
62
  export declare function readContentArg(content: string | undefined): string;
45
63
  export declare function relativeToRoot(repoRoot: string, p: string): string;
64
+ export declare const DEFAULT_LEDGER_DIR = ".claude/ledgers";
46
65
  /**
47
66
  * The ledger directory, from `ledgers.dir` or the default.
48
67
  *
@@ -3,6 +3,7 @@ import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readFileSyn
3
3
  import { homedir } from 'node:os';
4
4
  import { dirname, relative, resolve } from 'node:path';
5
5
  import { ENTRY_HEAD } from './backlog-id.mjs';
6
+ import { loadIndex } from './ledger-index.mjs';
6
7
  export const SEPARATOR = '---';
7
8
  const TRANSCRIPT_TAIL_BYTES = 16384;
8
9
  const METADATA_LINE = /^\*\*([A-Za-z][A-Za-z ]*):\*\*\s+(.+)$/;
@@ -185,6 +186,27 @@ export function rebuildWouldDropEntries(file, nextContent, intentionallyDropped
185
186
  const after = new Set(parseEntries(nextContent).map((e) => e.id));
186
187
  return before.some((e) => !after.has(e.id) && !intentionallyDropped.has(e.id));
187
188
  }
189
+ /** The local enable token a projects sync bootstrap writes into the ledger directory. */
190
+ export const PROJECTS_ENABLE_TOKEN = '.projects.json';
191
+ /**
192
+ * Whether the pulled index, rather than the queue, is the store this ledger's surfaces render
193
+ * from.
194
+ *
195
+ * Without a projects sync the queue is the only durable copy of an entry, so a surface holding
196
+ * entries the queue cannot account for means the queue was truncated and rewriting would
197
+ * destroy them. With a sync configured the model inverts: the queue jsonl drains to zero after
198
+ * a successful push, and the board is the durable store, pulled into the index. A fully synced
199
+ * repo therefore sits at zero queued entries with a rendered surface, which the queue
200
+ * comparison reads as corruption and refuses forever.
201
+ *
202
+ * The index has to be on disk for this. A repo that enabled the sync but has never pulled
203
+ * knows nothing about the board, so the queue comparison is still the only safe one there.
204
+ */
205
+ export function indexIsAuthoritative(ledgerDirectory, kind) {
206
+ if (!existsSync(resolve(ledgerDirectory, PROJECTS_ENABLE_TOKEN)))
207
+ return false;
208
+ return loadIndex(ledgerDirectory, kind) !== null;
209
+ }
188
210
  export function readSurface(file) {
189
211
  return existsSync(file) ? readFileSync(file, 'utf8') : '';
190
212
  }
@@ -199,7 +221,7 @@ export function readContentArg(content) {
199
221
  export function relativeToRoot(repoRoot, p) {
200
222
  return relative(repoRoot, resolve(p));
201
223
  }
202
- const DEFAULT_LEDGER_DIR = '.claude/ledgers';
224
+ export const DEFAULT_LEDGER_DIR = '.claude/ledgers';
203
225
  /**
204
226
  * The ledger directory, from `ledgers.dir` or the default.
205
227
  *