@aaac/runtime 0.1.55 → 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/README.md +6 -11
- package/dist/adapters/adk-sdk.d.ts +3 -3
- package/dist/adapters/adk-sdk.js +6 -8
- package/dist/adapters/adk-sdk.js.map +1 -1
- package/dist/adapters/claude-agent-sdk.d.ts +3 -3
- package/dist/adapters/claude-agent-sdk.js +22 -23
- package/dist/adapters/claude-agent-sdk.js.map +1 -1
- package/dist/adapters/mock.d.ts +2 -3
- package/dist/adapters/openai-agents-sdk.d.ts +3 -3
- package/dist/adapters/openai-agents-sdk.js +6 -5
- package/dist/adapters/openai-agents-sdk.js.map +1 -1
- package/dist/chunk-2INQL5TG.js +298 -0
- package/dist/chunk-2INQL5TG.js.map +1 -0
- package/dist/chunk-3CLWG72V.js +47 -0
- package/dist/chunk-3CLWG72V.js.map +1 -0
- package/dist/chunk-3DDB34BU.js +237 -0
- package/dist/chunk-3DDB34BU.js.map +1 -0
- package/dist/chunk-ABXDSTUV.js +685 -0
- package/dist/chunk-ABXDSTUV.js.map +1 -0
- package/dist/{chunk-3H3PVPPF.js → chunk-F5R46S7I.js} +151 -204
- package/dist/chunk-F5R46S7I.js.map +1 -0
- package/dist/chunk-FKAI54OM.js +234 -0
- package/dist/chunk-FKAI54OM.js.map +1 -0
- package/dist/chunk-KTVMMG33.js +1111 -0
- package/dist/chunk-KTVMMG33.js.map +1 -0
- package/dist/chunk-MSVIEEGR.js +269 -0
- package/dist/chunk-MSVIEEGR.js.map +1 -0
- package/dist/chunk-VJXGCWSZ.js +36 -0
- package/dist/chunk-VJXGCWSZ.js.map +1 -0
- package/dist/claude-bundles/full.js +311 -309
- package/dist/claude-bundles/lean.js +6 -6
- package/dist/claude-bundles/prompt.js +17 -0
- package/dist/generator/index.d.ts +2 -2
- package/dist/generator/index.js +8 -7
- package/dist/guardrail-hooks-CB23nhZV.d.ts +202 -0
- package/dist/hook-protocol-CFnNudiV.d.ts +96 -0
- package/dist/hooks-lite-CoWWnCRH.d.ts +428 -0
- package/dist/index-BlSepCSZ.d.ts +296 -0
- package/dist/index.d.ts +785 -105
- package/dist/index.js +2189 -634
- package/dist/index.js.map +1 -1
- package/dist/lib/claude-native/hooks-lite.d.ts +3 -26
- package/dist/lib/claude-native/hooks-lite.js +18 -36
- package/dist/lib/claude-native/hooks-prompt.d.ts +5 -0
- package/dist/lib/claude-native/hooks-prompt.js +33 -0
- package/dist/lib/claude-native/hooks-prompt.js.map +1 -0
- package/dist/lib/claude-native/index.d.ts +56 -214
- package/dist/lib/claude-native/index.js +79 -280
- package/dist/lib/claude-native/index.js.map +1 -1
- package/dist/{navigation-context-D_E1NIUf.d.ts → navigation-context-B-RpUg3_.d.ts} +1 -1
- package/dist/navigation-index-prompt-CbrS5laO.d.ts +43 -0
- package/dist/{task-runner-DfIEorkU.d.ts → task-runner-GWoI7_71.d.ts} +100 -493
- package/dist/workspace-user-prompt-submit-D11Iu0zO.d.ts +269 -0
- package/package.json +15 -6
- package/dist/chunk-3H3PVPPF.js.map +0 -1
- package/dist/chunk-DBM5XN67.js +0 -354
- package/dist/chunk-DBM5XN67.js.map +0 -1
- package/dist/chunk-KXGUWBGK.js +0 -370
- package/dist/chunk-KXGUWBGK.js.map +0 -1
- package/dist/chunk-LDCQZPDG.js +0 -11
- package/dist/chunk-LDCQZPDG.js.map +0 -1
- package/dist/chunk-N4KNGDYY.js +0 -1963
- package/dist/chunk-N4KNGDYY.js.map +0 -1
- package/dist/chunk-NMX4C6LC.js +0 -332
- package/dist/chunk-NMX4C6LC.js.map +0 -1
- package/dist/chunk-QVH5KKBR.js +0 -374
- package/dist/chunk-QVH5KKBR.js.map +0 -1
- package/dist/context-DKkamYX_.d.ts +0 -31
- package/dist/guardrail-hooks-slK-z0Dz.d.ts +0 -83
- package/dist/index-LqEvaRk-.d.ts +0 -299
- package/dist/workspace-pre-tool-use-C6nidc0q.d.ts +0 -333
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
import { c as PreToolUseInput, H as HookOutput } from './hook-protocol-CFnNudiV.js';
|
|
2
|
+
import { a as GuardrailRuleData } from './guardrail-hooks-CB23nhZV.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Cache Store — read/write `.claude/cache/` directory.
|
|
6
|
+
*
|
|
7
|
+
* Stores navigation-index.json and metadata for graph cache invalidation.
|
|
8
|
+
* Uses atomic write (write-to-temp + rename) for concurrent-access safety.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Deciding whether an entry is fresh is deliberately NOT a method here.
|
|
12
|
+
* `navigation-cache.ts` owns that question, and owning it in one place is what
|
|
13
|
+
* keeps the hook that READS the index and the builder that WRITES it from
|
|
14
|
+
* disagreeing about the same file.
|
|
15
|
+
*/
|
|
16
|
+
interface CacheEntry<T = unknown> {
|
|
17
|
+
data: T;
|
|
18
|
+
/** ISO timestamp of when the cache was written. */
|
|
19
|
+
writtenAt: string;
|
|
20
|
+
/** Hash of source inputs used for invalidation. */
|
|
21
|
+
sourceHash: string;
|
|
22
|
+
/**
|
|
23
|
+
* The files `sourceHash` was computed over.
|
|
24
|
+
*
|
|
25
|
+
* Recorded with the hash, in the same record and the same atomic write, so a
|
|
26
|
+
* reader can re-check freshness without being able to resolve that list
|
|
27
|
+
* itself. Resolving it means parsing the project manifest, which is what the
|
|
28
|
+
* interactive hooks must not pay for; the builder already knows the answer, so
|
|
29
|
+
* it writes it down (#278).
|
|
30
|
+
*/
|
|
31
|
+
sourceFiles?: string[];
|
|
32
|
+
}
|
|
33
|
+
interface CacheStoreOptions {
|
|
34
|
+
/** Absolute path to the `.claude/cache/` directory. */
|
|
35
|
+
cacheDir: string;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* What a caller knows about `data` and this module does not.
|
|
39
|
+
*
|
|
40
|
+
* `read` is generic over `T`, so the only thing here that could establish `T` is
|
|
41
|
+
* the caller's own predicate — `as CacheEntry<T>` promised whatever the call
|
|
42
|
+
* site asked for and delivered whatever was on disk, which is how a cache file
|
|
43
|
+
* written by another process (or an older build) reached `computeCurrentHash`
|
|
44
|
+
* as `sourceFiles: 5` and threw `TypeError: sourceFiles is not iterable`.
|
|
45
|
+
*/
|
|
46
|
+
type DataPredicate<T> = (value: unknown) => value is T;
|
|
47
|
+
/**
|
|
48
|
+
* The shape of an entry whose `data` is declared no more precisely than "an
|
|
49
|
+
* object" — what both navigation-index readers ask for. It checks exactly that
|
|
50
|
+
* and no more: a predicate that demanded the index's own keys would promise more
|
|
51
|
+
* than {@link FreshNavigationBuild} declares, and reject builds the type admits.
|
|
52
|
+
*/
|
|
53
|
+
declare const isCachedRecord: (value: unknown) => value is Record<string, unknown>;
|
|
54
|
+
interface CacheStore {
|
|
55
|
+
/**
|
|
56
|
+
* The entry under `key` if the file holds one whose `data` satisfies `isData`,
|
|
57
|
+
* else `null` — the same answer an absent or unparseable file gets, because a
|
|
58
|
+
* record this reader cannot use is not one, however it came to be that way.
|
|
59
|
+
*/
|
|
60
|
+
read<T>(key: string, isData: DataPredicate<T>): Promise<CacheEntry<T> | null>;
|
|
61
|
+
write<T = unknown>(key: string, data: T, sourceHash: string, sourceFiles?: string[]): Promise<void>;
|
|
62
|
+
/** Get the mtime of a file (for invalidation checks). */
|
|
63
|
+
getFileMtime(filePath: string): Promise<number | null>;
|
|
64
|
+
}
|
|
65
|
+
declare function createCacheStore(options: CacheStoreOptions): CacheStore;
|
|
66
|
+
/**
|
|
67
|
+
* Compute a simple hash string from an array of file mtimes and content strings.
|
|
68
|
+
* Not cryptographic — used only for cache invalidation.
|
|
69
|
+
*/
|
|
70
|
+
declare function computeSourceHash(inputs: Array<string | number>): string;
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Is the cached navigation build still the one this project's sources describe?
|
|
74
|
+
*
|
|
75
|
+
* THE freshness predicate — there is deliberately no other. `cache-store` offers
|
|
76
|
+
* no freshness method, and `ensureNavigationIndex` decides whether to rebuild by
|
|
77
|
+
* asking this, so the hooks that READ a build and the builder that WRITES it
|
|
78
|
+
* cannot answer differently about the same files.
|
|
79
|
+
*
|
|
80
|
+
* ITS OWN MODULE, and that is load-bearing rather than tidiness. The bundler
|
|
81
|
+
* layers chunks by MODULE (`layerOnto` in scripts/build-claude-bundles.mjs), so
|
|
82
|
+
* everything in one file lands on one side of the #278 split. Freshness is
|
|
83
|
+
* needed on BOTH sides — by `build-contextpack`, which escalates a stale cache
|
|
84
|
+
* to a rebuild, and by `check-artifact-edit`, which must not judge from one —
|
|
85
|
+
* while the escalation itself (`runEnsureNavigationIndexBin`, a `spawn`) must
|
|
86
|
+
* never be reachable from the PreToolUse guard: that hook fires on every tool
|
|
87
|
+
* call and has no business starting the DSL loader. Splitting the file is what
|
|
88
|
+
* makes "the guard can ask, and cannot rebuild" a fact about the chunk graph
|
|
89
|
+
* instead of a convention.
|
|
90
|
+
*/
|
|
91
|
+
|
|
92
|
+
declare const DEFAULT_CACHE_KEY = "navigation-index";
|
|
93
|
+
/**
|
|
94
|
+
* Cache hash for a set of source files: their mtimes, in order.
|
|
95
|
+
*
|
|
96
|
+
* There is no TTL — the index is stale exactly when one of the files it was
|
|
97
|
+
* built from has been touched. Callers must pass the same `sourceFiles` the
|
|
98
|
+
* build used, or the hash will never match.
|
|
99
|
+
*/
|
|
100
|
+
declare function computeCurrentHash(sourceFiles: string[]): Promise<string>;
|
|
101
|
+
/**
|
|
102
|
+
* What one `ensureNavigationIndex` run produced: the navigation index and the
|
|
103
|
+
* DSL guardrail rules resolved alongside it.
|
|
104
|
+
*
|
|
105
|
+
* Returned together because they were WRITTEN together, under one hash. A
|
|
106
|
+
* caller that could take one without the other would be free to pair a current
|
|
107
|
+
* artifact registry with a superseded rule set.
|
|
108
|
+
*/
|
|
109
|
+
interface FreshNavigationBuild {
|
|
110
|
+
navigationIndex: Record<string, unknown>;
|
|
111
|
+
guardrailRules: GuardrailRuleData;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* The cached build if it is still fresh, else undefined. Never builds.
|
|
115
|
+
*
|
|
116
|
+
* The file list the hash is checked against comes from the CACHE ENTRY, not from
|
|
117
|
+
* re-resolving the project manifest. That is what keeps this readable from the
|
|
118
|
+
* lean graph: resolving the list means loading the manifest parser (zod + yaml),
|
|
119
|
+
* which every per-interaction hook would then carry. The builder resolved it
|
|
120
|
+
* already and wrote it down, so the reader just re-stats it.
|
|
121
|
+
*
|
|
122
|
+
* An entry with no recorded list is treated as stale. It was written by an older
|
|
123
|
+
* build, and rebuilding is exactly what upgrades it — the alternative, assuming
|
|
124
|
+
* it is fresh, would pin a stale index forever.
|
|
125
|
+
*
|
|
126
|
+
* FRESH MEANS THE WHOLE BUILD, not just the index. One run writes both entries,
|
|
127
|
+
* so an index sitting next to no companion is the same "written by an older
|
|
128
|
+
* build" case and has to be answered the same way. Asking only about the index
|
|
129
|
+
* is not merely incomplete: `ensureNavigationIndex` returns early on this
|
|
130
|
+
* predicate, so it would keep returning the untouched index and the companion
|
|
131
|
+
* the PreToolUse guard reads could never come back (#304).
|
|
132
|
+
*/
|
|
133
|
+
declare function readFreshNavigationBuild(options: {
|
|
134
|
+
cacheDir: string;
|
|
135
|
+
cacheKey?: string;
|
|
136
|
+
}): Promise<FreshNavigationBuild | undefined>;
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Artifact Resolver — reverse-lookup path to artifact_id using navigation-index.
|
|
140
|
+
*
|
|
141
|
+
* Uses glob matching from guardrail-hooks.ts to match file paths against
|
|
142
|
+
* artifact path_patterns defined in the navigation index.
|
|
143
|
+
*/
|
|
144
|
+
/** Minimal shape of a navigation-index artifact node. */
|
|
145
|
+
interface NavigationArtifact {
|
|
146
|
+
properties?: {
|
|
147
|
+
type?: string;
|
|
148
|
+
authority?: string;
|
|
149
|
+
manual_edit?: string;
|
|
150
|
+
[key: string]: unknown;
|
|
151
|
+
};
|
|
152
|
+
files?: {
|
|
153
|
+
path_patterns?: string[];
|
|
154
|
+
[key: string]: unknown;
|
|
155
|
+
};
|
|
156
|
+
agents?: {
|
|
157
|
+
owners?: string[];
|
|
158
|
+
editors?: string[];
|
|
159
|
+
[key: string]: unknown;
|
|
160
|
+
};
|
|
161
|
+
routes?: {
|
|
162
|
+
regenerate?: string;
|
|
163
|
+
[key: string]: unknown;
|
|
164
|
+
};
|
|
165
|
+
relations?: {
|
|
166
|
+
derived_artifacts?: string[];
|
|
167
|
+
[key: string]: unknown;
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
interface ArtifactMatch {
|
|
171
|
+
artifactId: string;
|
|
172
|
+
artifact: NavigationArtifact;
|
|
173
|
+
/** The glob pattern that matched. */
|
|
174
|
+
matchedPattern: string;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Resolve a file path to its artifact(s) in the navigation index.
|
|
178
|
+
* Returns all matching artifacts (a file may belong to multiple artifacts).
|
|
179
|
+
*/
|
|
180
|
+
declare function resolvePathToArtifacts(filePath: string, navigationIndex: Record<string, unknown>): ArtifactMatch[];
|
|
181
|
+
/**
|
|
182
|
+
* Check if a file path targets a protected artifact (generated or manual_edit: forbidden).
|
|
183
|
+
*/
|
|
184
|
+
declare function isProtectedArtifact(match: ArtifactMatch): {
|
|
185
|
+
protected: boolean;
|
|
186
|
+
reason: string;
|
|
187
|
+
};
|
|
188
|
+
/**
|
|
189
|
+
* Get all artifact entries from a navigation index as a flat list.
|
|
190
|
+
*/
|
|
191
|
+
declare function listArtifacts(navigationIndex: Record<string, unknown>): Array<{
|
|
192
|
+
id: string;
|
|
193
|
+
artifact: NavigationArtifact;
|
|
194
|
+
}>;
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* PreToolUse Hook Handler — artifact guardrail + DSL guardrail enforcement.
|
|
198
|
+
*
|
|
199
|
+
* Executed before EVERY tool use — `.claude/settings.json` registers this hook
|
|
200
|
+
* with no matcher, so which guard covers a call is decided here. Two guards:
|
|
201
|
+
* 1. the ARTIFACT guard: file path → artifact reverse lookup → deny if protected
|
|
202
|
+
* 2. the DSL GUARDRAIL guard: every rule the project declares — `command_regex`
|
|
203
|
+
* over the command, `file_glob` over the file the call names, `content_regex`
|
|
204
|
+
* over the text it is about to write — through `GuardrailHooks`. This hook is
|
|
205
|
+
* Claude Code's ONLY refusal point, so a rule kind that is not consulted here
|
|
206
|
+
* is a rule kind the session does not enforce (#316).
|
|
207
|
+
*
|
|
208
|
+
* Both read an input the SessionStart / UserPromptSubmit hooks materialize into
|
|
209
|
+
* `.claude/cache/`. An input that is not there is not the same as an input that
|
|
210
|
+
* says nothing — see `unmaterializedGuardReason`.
|
|
211
|
+
*
|
|
212
|
+
* The two guards are independent — `commandGuardCovers` and
|
|
213
|
+
* `artifactGuardTarget` are asked separately, so one payload can answer to
|
|
214
|
+
* both — and the artifact side defaults to COVERED: an enumeration of the tools
|
|
215
|
+
* to guard is an enumeration that goes stale every time Claude Code grows one
|
|
216
|
+
* (#309).
|
|
217
|
+
*/
|
|
218
|
+
|
|
219
|
+
interface PreToolUseHandlerConfig {
|
|
220
|
+
/**
|
|
221
|
+
* Navigation index read from the cache, or `undefined` when that cache entry
|
|
222
|
+
* was not there to read. Pass what the read returned — do NOT substitute an
|
|
223
|
+
* empty index, which reads as "this project protects no artifact".
|
|
224
|
+
*/
|
|
225
|
+
navigationIndex?: Record<string, unknown>;
|
|
226
|
+
/**
|
|
227
|
+
* DSL guardrail rules read from the companion cache entry, or `undefined`
|
|
228
|
+
* when that entry was not there to read. A project with no guardrails still
|
|
229
|
+
* HAS the entry (the builder writes it empty), so `undefined` means the guard
|
|
230
|
+
* has no rules to consult, never that there are none.
|
|
231
|
+
*/
|
|
232
|
+
guardrailRules?: GuardrailRuleData;
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* Create a PreToolUse hook handler.
|
|
236
|
+
*
|
|
237
|
+
* The caller passes the cache reads verbatim; deciding what an absent read
|
|
238
|
+
* means is this handler's job, not the calling bin's.
|
|
239
|
+
*/
|
|
240
|
+
declare function createPreToolUseHandler(config: PreToolUseHandlerConfig): (input: PreToolUseInput) => Promise<HookOutput>;
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* File Suggestion Handler — artifact-aware @ completion for Claude Code.
|
|
244
|
+
*
|
|
245
|
+
* Reads stdin prefix, filters navigation-index artifacts, and emits NDJSON
|
|
246
|
+
* candidates sorted by relevance score.
|
|
247
|
+
*/
|
|
248
|
+
interface FileSuggestionCandidate {
|
|
249
|
+
label: string;
|
|
250
|
+
path: string;
|
|
251
|
+
kind: "artifact" | "file";
|
|
252
|
+
/** Artifact ID this file/pattern belongs to. */
|
|
253
|
+
artifact?: string;
|
|
254
|
+
/** Authority of the artifact (canonical, generated, etc.). */
|
|
255
|
+
authority?: string;
|
|
256
|
+
/** Manual edit policy for the artifact. */
|
|
257
|
+
manual_edit?: string;
|
|
258
|
+
/** Relevance score (higher = more relevant). */
|
|
259
|
+
score: number;
|
|
260
|
+
}
|
|
261
|
+
interface FileSuggestionOptions {
|
|
262
|
+
/** The navigation index to search. */
|
|
263
|
+
navigationIndex: Record<string, unknown>;
|
|
264
|
+
/** Maximum number of candidates to return. */
|
|
265
|
+
maxCandidates?: number;
|
|
266
|
+
/**
|
|
267
|
+
* Prefix prepended to every emitted path (#266). Artifact `path_patterns` are
|
|
268
|
+
* project-root relative, so in a workspace — where Claude Code's cwd is the
|
|
269
|
+
* workspace root — a member's candidates must be re-rooted under the member
|
|
270
|
+
* directory. The mirror image of `stripMemberPrefix` on the PreToolUse side.
|
|
271
|
+
*/
|
|
272
|
+
pathPrefix?: string;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* Generate file suggestion candidates from the navigation index.
|
|
276
|
+
* Filters by prefix if provided, then returns NDJSON-formatted candidates.
|
|
277
|
+
*/
|
|
278
|
+
declare function generateCandidates(prefix: string, options: FileSuggestionOptions): FileSuggestionCandidate[];
|
|
279
|
+
/**
|
|
280
|
+
* Format candidates as NDJSON (one JSON object per line).
|
|
281
|
+
*/
|
|
282
|
+
declare function formatNdjson(candidates: FileSuggestionCandidate[]): string;
|
|
283
|
+
/**
|
|
284
|
+
* Main handler for file-suggestion bin script.
|
|
285
|
+
* Reads prefix from stdin, returns NDJSON candidates to stdout.
|
|
286
|
+
*/
|
|
287
|
+
declare function handleFileSuggestion(navigationIndex: Record<string, unknown>, stdinData: string): Promise<string>;
|
|
288
|
+
/** One workspace member's cached index, as the file-suggestion bin knows it. */
|
|
289
|
+
interface WorkspaceFileSuggestionMember {
|
|
290
|
+
/** Member name (for diagnostics only). */
|
|
291
|
+
name: string;
|
|
292
|
+
/** Workspace-relative member path — prepended to every candidate path. */
|
|
293
|
+
memberPath: string;
|
|
294
|
+
/** Cache key of this member's navigation-index. */
|
|
295
|
+
cacheKey: string;
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Workspace variant (#266): merge candidates from every member's own index.
|
|
299
|
+
*
|
|
300
|
+
* The single-component handler reads the lone `navigation-index` cache entry,
|
|
301
|
+
* which workspace mode never writes (each member has its own key) — so `@`
|
|
302
|
+
* completion returned nothing at all. Members whose index has not been built yet
|
|
303
|
+
* are skipped rather than failing the hook: SessionStart warms them.
|
|
304
|
+
*/
|
|
305
|
+
declare function handleWorkspaceFileSuggestion(cacheDir: string, members: WorkspaceFileSuggestionMember[], stdinData: string, maxCandidates?: number): Promise<string>;
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Workspace Router — route a file path to the owning workspace member.
|
|
309
|
+
*
|
|
310
|
+
* Pure path-manipulation module. No imports from navigation-context,
|
|
311
|
+
* agent-contracts, or any heavy dependency — safe for the lean hooks-lite
|
|
312
|
+
* entry point.
|
|
313
|
+
*
|
|
314
|
+
* Algorithm: longest-prefix match among member absolute root paths.
|
|
315
|
+
*
|
|
316
|
+
* C4 resolution: stripMemberPrefix converts a workspace-relative path
|
|
317
|
+
* (`aaac/packages/runtime/x.ts`) into a repo-relative path
|
|
318
|
+
* (`packages/runtime/x.ts`) so existing member DSL path_patterns work
|
|
319
|
+
* without modification.
|
|
320
|
+
*/
|
|
321
|
+
interface WorkspaceMember {
|
|
322
|
+
/** Human-readable member name (e.g. `"aaac"`). */
|
|
323
|
+
name: string;
|
|
324
|
+
/** Absolute path to the member root directory. */
|
|
325
|
+
root: string;
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* Route a file path to the workspace member whose root is the longest
|
|
329
|
+
* matching prefix of that path.
|
|
330
|
+
*
|
|
331
|
+
* Generic over `T extends WorkspaceMember` so callers that pass a richer
|
|
332
|
+
* member type (e.g. `WorkspaceMemberPreToolUseConfig`) get back that type
|
|
333
|
+
* without a cast.
|
|
334
|
+
*
|
|
335
|
+
* @param filePath - Absolute or workspace-root-relative file path (as
|
|
336
|
+
* received from Claude Code's `tool_input.file_path`).
|
|
337
|
+
* @param members - Workspace members with **absolute** root paths.
|
|
338
|
+
* @param workspaceRoot - Absolute path to the workspace root directory.
|
|
339
|
+
* Used to resolve relative `filePath` values.
|
|
340
|
+
* @returns The owning member, or `null` when no member claims this path.
|
|
341
|
+
*/
|
|
342
|
+
declare function routePathToMember<T extends WorkspaceMember>(filePath: string, members: T[], workspaceRoot: string): T | null;
|
|
343
|
+
/**
|
|
344
|
+
* Strip the member root prefix from `filePath` to obtain a repo-relative
|
|
345
|
+
* path that member DSL `path_patterns` can match against unchanged (C4).
|
|
346
|
+
*
|
|
347
|
+
* Example:
|
|
348
|
+
* filePath = "aaac/packages/runtime/x.ts" (workspace-relative)
|
|
349
|
+
* memberRoot = "/abs/workspace/aaac"
|
|
350
|
+
* workspaceRoot = "/abs/workspace"
|
|
351
|
+
* → returns "packages/runtime/x.ts"
|
|
352
|
+
*
|
|
353
|
+
* @param filePath - Absolute or workspace-root-relative path.
|
|
354
|
+
* @param memberRoot - Absolute path to the member root.
|
|
355
|
+
* @param workspaceRoot - Absolute path to the workspace root.
|
|
356
|
+
* @returns Repo-relative path (no leading slash/dot).
|
|
357
|
+
* Falls back to the original `filePath` when stripping is not possible.
|
|
358
|
+
*/
|
|
359
|
+
declare function stripMemberPrefix(filePath: string, memberRoot: string, workspaceRoot: string): string;
|
|
360
|
+
|
|
361
|
+
/**
|
|
362
|
+
* Workspace PreToolUse Hook Handler — routes edits to the owning member
|
|
363
|
+
* and enforces that member's artifact guardrails.
|
|
364
|
+
*
|
|
365
|
+
* Hot-path module. Does NOT import navigation-context or agent-contracts —
|
|
366
|
+
* it only reads an already-built navigation index from the cache. Suitable
|
|
367
|
+
* for inclusion in the lean hooks-lite entry point.
|
|
368
|
+
*
|
|
369
|
+
* Flow (per PreToolUse invocation, once `artifactGuardTarget` names a file the
|
|
370
|
+
* file guards have to judge):
|
|
371
|
+
* 1. Extract file path from tool input.
|
|
372
|
+
* 2. Route to owning member via longest-prefix match (workspace-router).
|
|
373
|
+
* 3. Read the member's fresh build — navigation-index + guardrail rules.
|
|
374
|
+
* 4. Strip member-root prefix → repo-relative path (C4 resolution).
|
|
375
|
+
* 5. Apply the member's file + content guardrails to that path.
|
|
376
|
+
* 6. Resolve path to artifacts; deny if protected.
|
|
377
|
+
*/
|
|
378
|
+
|
|
379
|
+
interface WorkspaceMemberPreToolUseConfig extends WorkspaceMember {
|
|
380
|
+
/**
|
|
381
|
+
* Cache key for this member's navigation-index JSON.
|
|
382
|
+
* Format: `navigation-index.<name>` (e.g. `navigation-index.aaac`).
|
|
383
|
+
*
|
|
384
|
+
* The member's DSL guardrail rules live in the companion entry this key
|
|
385
|
+
* implies. There is no override for that: `ensureNavigationIndex` — the only
|
|
386
|
+
* writer — derives the companion key from this one, so a reader free to name
|
|
387
|
+
* a different entry could only ever name one nothing writes (#316).
|
|
388
|
+
*/
|
|
389
|
+
cacheKey: string;
|
|
390
|
+
}
|
|
391
|
+
interface WorkspacePreToolUseConfig {
|
|
392
|
+
/** Absolute path to the workspace root directory. */
|
|
393
|
+
workspaceRoot: string;
|
|
394
|
+
/** Absolute path to the shared `.claude/cache/` directory. */
|
|
395
|
+
cacheDir: string;
|
|
396
|
+
/** Workspace members to route edits to. */
|
|
397
|
+
members: WorkspaceMemberPreToolUseConfig[];
|
|
398
|
+
}
|
|
399
|
+
/**
|
|
400
|
+
* Create a workspace-aware PreToolUse hook handler.
|
|
401
|
+
*
|
|
402
|
+
* On each invocation both guards are asked — independently, so one payload can
|
|
403
|
+
* answer to both — and the handler:
|
|
404
|
+
* - file guards, over the file `artifactGuardTarget` names:
|
|
405
|
+
* - Routes the target path to the owning member by longest-prefix match.
|
|
406
|
+
* - Reads the member's fresh build (refuses if it has none).
|
|
407
|
+
* - Strips the member-root prefix so the member's `path_patterns` and
|
|
408
|
+
* `file_glob` patterns both receive the repo-relative path they are written
|
|
409
|
+
* against (C4).
|
|
410
|
+
* - Denies a blocking `file_glob` / `content_regex` violation, then denies if
|
|
411
|
+
* any matched artifact is protected (Phase 1).
|
|
412
|
+
* - command guard, when the call carries one (#238 / C5, Phase 3):
|
|
413
|
+
* - Routes the command to the owning member via a path token in the command
|
|
414
|
+
* (longest-prefix match); when no member path is present, evaluates the
|
|
415
|
+
* command against every member's rules so safety guardrails are never
|
|
416
|
+
* silently skipped.
|
|
417
|
+
* - Denies blocking command violations from that member's rules.
|
|
418
|
+
*
|
|
419
|
+
* Artifact protection (Phase 1) and DSL guardrails (Phase 3) are independent and
|
|
420
|
+
* coexist: a member with only artifact rules keeps working unchanged, and a
|
|
421
|
+
* member with only guardrail rules still enforces command and file safety.
|
|
422
|
+
*
|
|
423
|
+
* A member with no usable build refuses the operations its guards cover, rather
|
|
424
|
+
* than admitting them — see `unmaterializedGuardReason`.
|
|
425
|
+
*/
|
|
426
|
+
declare function createWorkspacePreToolUseHandler(config: WorkspacePreToolUseConfig): (input: PreToolUseInput) => Promise<HookOutput>;
|
|
427
|
+
|
|
428
|
+
export { type ArtifactMatch as A, type CacheEntry as C, DEFAULT_CACHE_KEY as D, type FileSuggestionCandidate as F, type NavigationArtifact as N, type PreToolUseHandlerConfig as P, type WorkspaceFileSuggestionMember as W, type CacheStore as a, type CacheStoreOptions as b, type FileSuggestionOptions as c, type FreshNavigationBuild as d, type WorkspaceMember as e, type WorkspaceMemberPreToolUseConfig as f, type WorkspacePreToolUseConfig as g, computeCurrentHash as h, computeSourceHash as i, createCacheStore as j, createPreToolUseHandler as k, createWorkspacePreToolUseHandler as l, formatNdjson as m, generateCandidates as n, handleFileSuggestion as o, handleWorkspaceFileSuggestion as p, isCachedRecord as q, isProtectedArtifact as r, listArtifacts as s, readFreshNavigationBuild as t, resolvePathToArtifacts as u, routePathToMember as v, stripMemberPrefix as w };
|