dsh-better-edit 0.8.2 → 1.1.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/CHANGELOG.md +173 -99
- package/README.md +61 -33
- package/README.zh.md +20 -17
- package/cordis.patch.yml +1 -1
- package/lib/constants.js +19 -4
- package/lib/contract.js +136 -79
- package/lib/domain-errors.js +570 -0
- package/lib/edit-diff.js +33 -7
- package/lib/file-encoding-state.js +27 -7
- package/lib/file-view.js +305 -82
- package/lib/fs-bridge.js +23 -7
- package/lib/guidance/materialize.js +7 -7
- package/lib/guidance/resolve.js +13 -8
- package/lib/hash-store.js +404 -278
- package/lib/hashline/anchor-pipeline.js +586 -378
- package/lib/hashline/hash-assign.js +21 -22
- package/lib/hashline/hash.js +6 -6
- package/lib/hashline/index.js +1 -1
- package/lib/hashline/resolve.js +1 -1
- package/lib/hashline/served-guard.js +181 -0
- package/lib/index.js +37 -11
- package/lib/mutation/engine.js +392 -96
- package/lib/mutation.js +22 -130
- package/lib/noop-guard.js +20 -9
- package/lib/prompts.js +20 -18
- package/lib/read-and-serve.js +44 -20
- package/lib/sandbox.js +1 -1
- package/lib/session-view.js +57 -43
- package/lib/snapshot-store/index.js +97 -0
- package/lib/snapshot-store/lineage-store.js +400 -0
- package/lib/snapshot-store/migrate.js +80 -0
- package/lib/snapshot-store/pairing.js +412 -0
- package/lib/snapshot-store/txn.js +63 -0
- package/lib/snapshot-store/vacuum.js +243 -0
- package/lib/store-lifecycle.js +13 -1
- package/lib/store-retry.js +34 -0
- package/lib/tool-edit.js +90 -44
- package/lib/tool-read.js +29 -1
- package/lib/tool-str-replace-editor.js +26 -18
- package/lib/tool-undo.js +25 -8
- package/lib/types/constants.d.ts +5 -2
- package/lib/types/contract.d.ts +76 -71
- package/lib/types/domain-errors.d.ts +410 -0
- package/lib/types/edit-response.d.ts +1 -1
- package/lib/types/file-encoding-state.d.ts +1 -0
- package/lib/types/file-view.d.ts +35 -6
- package/lib/types/guidance/materialize.d.ts +2 -2
- package/lib/types/guidance/resolve.d.ts +14 -2
- package/lib/types/hash-store.d.ts +38 -19
- package/lib/types/hashline/anchor-pipeline.d.ts +117 -36
- package/lib/types/hashline/hash-assign.d.ts +5 -5
- package/lib/types/hashline/hash.d.ts +1 -1
- package/lib/types/hashline/index.d.ts +2 -2
- package/lib/types/hashline/served-guard.d.ts +100 -0
- package/lib/types/index.d.ts +3 -3
- package/lib/types/mutation/engine.d.ts +49 -30
- package/lib/types/mutation.d.ts +1 -39
- package/lib/types/noop-guard.d.ts +4 -4
- package/lib/types/prompts.d.ts +1 -1
- package/lib/types/read-and-serve.d.ts +6 -0
- package/lib/types/sandbox.d.ts +1 -1
- package/lib/types/session-view.d.ts +38 -9
- package/lib/types/snapshot-store/index.d.ts +28 -0
- package/lib/types/snapshot-store/lineage-store.d.ts +96 -0
- package/lib/types/snapshot-store/migrate.d.ts +16 -0
- package/lib/types/snapshot-store/pairing.d.ts +99 -0
- package/lib/types/snapshot-store/txn.d.ts +12 -0
- package/lib/types/snapshot-store/vacuum.d.ts +79 -0
- package/lib/types/store-lifecycle.d.ts +0 -1
- package/lib/types/store-retry.d.ts +6 -0
- package/lib/types/tool-edit.d.ts +2 -2
- package/lib/types/tool-str-replace-editor.d.ts +2 -2
- package/lib/types/utils.d.ts +5 -6
- package/lib/types/workspace-context.d.ts +10 -1
- package/lib/undo-edit.js +27 -11
- package/lib/utils.js +12 -12
- package/lib/workspace-context.js +27 -9
- package/lib/write-hook.js +13 -4
- package/package.json +28 -30
|
@@ -0,0 +1,410 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Domain error registry — the closed, type-safe contract for every
|
|
3
|
+
* model-facing diagnostic. Zero dependencies: no imports, so any seam can
|
|
4
|
+
* throw without wiring a store, session, or hasher.
|
|
5
|
+
*
|
|
6
|
+
* INVARIANT (the point of this module): a code is never declared without a
|
|
7
|
+
* producer. Every `DomainErrorCode` member must have at least one
|
|
8
|
+
* `new DomainError(code, …)` / `formatError(code, …)` producer in src/
|
|
9
|
+
* (subclass constructions `new EditHashEchoError` / `new BadAnchorError` /
|
|
10
|
+
* `new AnchorMismatchError("E_STALE_ANCHOR", …)` /
|
|
11
|
+
* `new ServedRejectionError({ code, … })` /
|
|
12
|
+
* `new AnchorSpaceExhaustedError(…)` count as producers of their code), or be
|
|
13
|
+
* listed in `DEFERRED_PRODUCERS`, and every code passed at a producer site
|
|
14
|
+
* must be a union member. Asserted BOTH directions in
|
|
15
|
+
* test/arch/domain-error-registry.test.ts. This is what makes the registry a
|
|
16
|
+
* contract instead of a list.
|
|
17
|
+
*
|
|
18
|
+
* COUNT DEVIATION (F4, ratified): this registry's E_* vocabulary is larger
|
|
19
|
+
* than upstream's 19. Upstream has no str_replace_editor shadow; the six
|
|
20
|
+
* shadow codes (E_BLIND_REPLACE, E_UNSUPPORTED, E_BAD_COMMAND, E_FILE_EXISTS,
|
|
21
|
+
* E_NO_MATCH, E_AMBIGUOUS_MATCH) are live model-facing contract per accepted
|
|
22
|
+
* ADR-0015, and E_UNSERVED_RANGE is live contract too (T4 declined its
|
|
23
|
+
* retirement — its producers are reachable, CP1 H1 → `SR@790`). A closed
|
|
24
|
+
* vocabulary that omits live codes is not closed — it just pushes them
|
|
25
|
+
* outside the contract (T4 also deleted four declarations that had no local
|
|
26
|
+
* producer at all; see `DEFERRED_PRODUCERS`).
|
|
27
|
+
* WHY payloads carry facts, not pre-baked strings: the producer already holds
|
|
28
|
+
* the evidence (line numbers, hashes, paths, counts), so the registry owns the
|
|
29
|
+
* neutral sentence and the producer passes values. The one deliberate
|
|
30
|
+
* exception is `E_BAD_PAYLOAD`, whose payload is `{ message }` rendered
|
|
31
|
+
* verbatim — admission-boundary rejections are too heterogeneous for a fixed
|
|
32
|
+
* shape, and the message is the fact.
|
|
33
|
+
*
|
|
34
|
+
* WHY a remedy clause may appear only when it is helpful, unharmful and
|
|
35
|
+
* fail-closed, AND the evidence pins a single cause. When the intent is
|
|
36
|
+
* ambiguous the payload states the fact and carries NO remedy, because an
|
|
37
|
+
* intent-guessing suggestion steers the model's next action. Remedy-free by
|
|
38
|
+
* rule (no `remedy` field on the registry entry):
|
|
39
|
+
* - `E_UNKNOWN`: no cause is knowable at all.
|
|
40
|
+
* - `E_NOOP_LOOP`: the refusal's evidence pins the fact (the range already
|
|
41
|
+
* contains the text) but not the model's intent, so a remedy clause would
|
|
42
|
+
* dress a status fact as an action.
|
|
43
|
+
*
|
|
44
|
+
* WHY `remedy` is declaration-only and never rendered into the message: the
|
|
45
|
+
* `format` strings already carry their own retry prose where the evidence pins
|
|
46
|
+
* it. Do not "fix" this by appending `remedy` to the rendered text. The
|
|
47
|
+
* declaration is owned by `DECLARATION_ONLY_FIELDS` below, which the arch oracle
|
|
48
|
+
* pins by identity AND checks for readers (0 today) — so it cannot rot quietly.
|
|
49
|
+
*
|
|
50
|
+
* @module dsh-better-edit/domain-errors
|
|
51
|
+
*/
|
|
52
|
+
/**
|
|
53
|
+
* Message channel: `formatError` prefixes every rendered error with
|
|
54
|
+
* `[TO <AUDIENCE>]` — the `TO` marks the addressee (who must act), while the
|
|
55
|
+
* remedy text names the action.
|
|
56
|
+
*/
|
|
57
|
+
export type Audience = "MODEL" | "USER";
|
|
58
|
+
/**
|
|
59
|
+
* One served row — position is 0-based, hash is the 3-char anchor. Declared
|
|
60
|
+
* here (not in anchor-pipeline) so the registry stays zero-dependency and the
|
|
61
|
+
* pipeline imports it from here.
|
|
62
|
+
*/
|
|
63
|
+
export interface ServedRow {
|
|
64
|
+
position: number;
|
|
65
|
+
hash: string;
|
|
66
|
+
}
|
|
67
|
+
/** WHY: user-facing diagnosis carried as `details.cause` on range-family rejections. */
|
|
68
|
+
export type RangeCause = "retirement" | "tombstone" | "never-served" | "served-range staleness" | "anchor staleness" | "served span";
|
|
69
|
+
export type DomainErrorCode = "E_BAD_PAYLOAD" | "E_EMPTY_RANGE" | "E_STALE_ANCHOR" | "E_UNKNOWN_ANCHOR" | "E_FOREIGN_ANCHOR" | "E_STALE_RANGE" | "E_TARGET_LOST" | "E_UNVERIFIED_RANGE" | "E_MALFORMED_ANCHOR" | "E_SUSPICIOUS_TEXT" | "E_BATCH_ABORT" | "E_NOOP_LOOP" | "E_UNSUPPORTED_FILE" | "E_ACCESS" | "E_NOT_FOUND" | "E_UNDO_STALE" | "E_UNDO_UNAVAILABLE" | "E_UNDO_NOT_RECORDED" | "E_UNKNOWN" | "E_LARGE_FILE" | "E_UNSERVED_RANGE" | "E_BLIND_REPLACE" | "E_UNSUPPORTED" | "E_BAD_COMMAND" | "E_FILE_EXISTS" | "E_NO_MATCH" | "E_AMBIGUOUS_MATCH" | "E_STORE_NEWER_VERSION";
|
|
70
|
+
/**
|
|
71
|
+
* Applied-tier warning codes. A `[W_*]` line reports an applied mutation;
|
|
72
|
+
* `[E_*]` reports a rejection. `formatWarning` is the sole producer of
|
|
73
|
+
* `[W_*]` headers and `formatError` the sole composer of `[E_*]` headers:
|
|
74
|
+
* no raw `[E_*]`/`[W_*]` header literal may exist outside this module
|
|
75
|
+
* (asserted in test/arch/domain-error-registry.test.ts).
|
|
76
|
+
*/
|
|
77
|
+
export type DomainWarningCode = "W_NEVER_SERVED_SHAPE" | "W_SERVED_PREFIX_MISMATCH" | "W_REVERSED_ANCHORS" | "W_UNICODE_LITERAL" | "W_LITERAL_BYPASS" | "W_NOOP";
|
|
78
|
+
export interface ErrorPayloadMap {
|
|
79
|
+
E_BAD_PAYLOAD: {
|
|
80
|
+
message: string;
|
|
81
|
+
};
|
|
82
|
+
E_EMPTY_RANGE: Record<string, never>;
|
|
83
|
+
E_STALE_ANCHOR: {
|
|
84
|
+
headline: string;
|
|
85
|
+
servedRows?: ServedRow[];
|
|
86
|
+
servedBlock?: string;
|
|
87
|
+
cause?: RangeCause;
|
|
88
|
+
};
|
|
89
|
+
E_UNKNOWN_ANCHOR: {
|
|
90
|
+
path: string;
|
|
91
|
+
anchors: string[];
|
|
92
|
+
};
|
|
93
|
+
E_FOREIGN_ANCHOR: {
|
|
94
|
+
path: string;
|
|
95
|
+
anchors: string[];
|
|
96
|
+
homes: string[];
|
|
97
|
+
};
|
|
98
|
+
E_STALE_RANGE: {
|
|
99
|
+
headline: string;
|
|
100
|
+
servedRows: ServedRow[];
|
|
101
|
+
servedBlock: string;
|
|
102
|
+
cause?: RangeCause;
|
|
103
|
+
firstOffendingLine?: number;
|
|
104
|
+
};
|
|
105
|
+
E_TARGET_LOST: {
|
|
106
|
+
servedLine: number;
|
|
107
|
+
path?: string;
|
|
108
|
+
cause: RangeCause;
|
|
109
|
+
firstOffendingLine?: number;
|
|
110
|
+
};
|
|
111
|
+
E_UNVERIFIED_RANGE: {
|
|
112
|
+
servedRows: ServedRow[];
|
|
113
|
+
servedBlock: string;
|
|
114
|
+
cause: RangeCause;
|
|
115
|
+
firstOffendingLine?: number;
|
|
116
|
+
};
|
|
117
|
+
E_MALFORMED_ANCHOR: {
|
|
118
|
+
rawAnchor: string;
|
|
119
|
+
reason: string;
|
|
120
|
+
};
|
|
121
|
+
E_SUSPICIOUS_TEXT: {
|
|
122
|
+
target: "edit" | "write";
|
|
123
|
+
path: string;
|
|
124
|
+
line: number;
|
|
125
|
+
hash: string;
|
|
126
|
+
servedLine: number;
|
|
127
|
+
/**
|
|
128
|
+
* Submission tally. Optional: the edit/write producers hold no tally
|
|
129
|
+
* state, so they omit it and the refusal renders without the submission
|
|
130
|
+
* clause. Present only when a caller tracks resubmissions.
|
|
131
|
+
*/
|
|
132
|
+
count?: number;
|
|
133
|
+
};
|
|
134
|
+
E_BATCH_ABORT: {
|
|
135
|
+
/** First failing item: routes the typed path and keeps the single-failure envelope byte-identical. */
|
|
136
|
+
index: number;
|
|
137
|
+
path: string;
|
|
138
|
+
/** The first failing item's inner failure message (already header-bearing). */
|
|
139
|
+
inner: string;
|
|
140
|
+
/**
|
|
141
|
+
* Range context for the failed item: either the current on-disk range
|
|
142
|
+
* block or the "Call read()…" fallback. Empty when no range context
|
|
143
|
+
* exists (non-anchor failures) — the merge hint is omitted with it.
|
|
144
|
+
*/
|
|
145
|
+
echoBlock: string;
|
|
146
|
+
/**
|
|
147
|
+
* Every failing item in order; present only when more than one failed
|
|
148
|
+
* (C: one resubmission fixes every failure). Each item keeps its own
|
|
149
|
+
* `[E_*]` inline in `inner`.
|
|
150
|
+
*/
|
|
151
|
+
failures?: Array<{
|
|
152
|
+
index: number;
|
|
153
|
+
inner: string;
|
|
154
|
+
}>;
|
|
155
|
+
/** Union of every failing item's rows, in item order. */
|
|
156
|
+
servedRows: ServedRow[];
|
|
157
|
+
/** Every failing item's block joined in item order ("" when none). */
|
|
158
|
+
servedBlock: string;
|
|
159
|
+
/** Carried only when every failing item agrees on one diagnosis. */
|
|
160
|
+
cause?: RangeCause;
|
|
161
|
+
};
|
|
162
|
+
E_NOOP_LOOP: {
|
|
163
|
+
ref: string;
|
|
164
|
+
anchorFrom: string;
|
|
165
|
+
anchorTo: string;
|
|
166
|
+
count: number;
|
|
167
|
+
batch: boolean;
|
|
168
|
+
servedBlock: string;
|
|
169
|
+
/**
|
|
170
|
+
* Present on engine single rejects: the display path ("in <path>" flavor).
|
|
171
|
+
* The batch ref already names the item, so no index is needed.
|
|
172
|
+
*/
|
|
173
|
+
path?: string;
|
|
174
|
+
};
|
|
175
|
+
E_UNSUPPORTED_FILE: {
|
|
176
|
+
path: string;
|
|
177
|
+
kind: "directory" | "binary" | "image";
|
|
178
|
+
description?: string;
|
|
179
|
+
};
|
|
180
|
+
E_ACCESS: {
|
|
181
|
+
path: string;
|
|
182
|
+
kind: "denied" | "symlink-loop" | "unreachable";
|
|
183
|
+
access?: "read" | "write";
|
|
184
|
+
};
|
|
185
|
+
E_NOT_FOUND: {
|
|
186
|
+
path: string;
|
|
187
|
+
};
|
|
188
|
+
E_UNDO_STALE: {
|
|
189
|
+
path: string;
|
|
190
|
+
reason?: "deleted" | "modified";
|
|
191
|
+
};
|
|
192
|
+
E_UNDO_UNAVAILABLE: {
|
|
193
|
+
path: string;
|
|
194
|
+
batch?: boolean;
|
|
195
|
+
};
|
|
196
|
+
E_UNDO_NOT_RECORDED: {
|
|
197
|
+
path: string;
|
|
198
|
+
};
|
|
199
|
+
E_UNKNOWN: {
|
|
200
|
+
errorName: string;
|
|
201
|
+
message: string;
|
|
202
|
+
};
|
|
203
|
+
E_LARGE_FILE: {
|
|
204
|
+
path?: string;
|
|
205
|
+
limitKind: "lines" | "hash-space";
|
|
206
|
+
lineCount?: number;
|
|
207
|
+
limit: number;
|
|
208
|
+
};
|
|
209
|
+
E_UNSERVED_RANGE: {
|
|
210
|
+
headline: string;
|
|
211
|
+
servedRows: ServedRow[];
|
|
212
|
+
servedBlock: string;
|
|
213
|
+
unservedKind: "boundary" | "interior";
|
|
214
|
+
firstOffendingLine?: number;
|
|
215
|
+
cause?: RangeCause;
|
|
216
|
+
};
|
|
217
|
+
E_BLIND_REPLACE: {
|
|
218
|
+
path: string;
|
|
219
|
+
/** The tool whose observation gate fired: the shadow or the write policy. */
|
|
220
|
+
command: string;
|
|
221
|
+
};
|
|
222
|
+
E_UNSUPPORTED: {
|
|
223
|
+
/** The known-but-unimplemented command (undo_edit). */
|
|
224
|
+
command: string;
|
|
225
|
+
};
|
|
226
|
+
E_BAD_COMMAND: {
|
|
227
|
+
/** The unknown command value (any JSON value the caller sent). */
|
|
228
|
+
command: unknown;
|
|
229
|
+
};
|
|
230
|
+
E_FILE_EXISTS: {
|
|
231
|
+
path: string;
|
|
232
|
+
};
|
|
233
|
+
E_NO_MATCH: {
|
|
234
|
+
path: string;
|
|
235
|
+
};
|
|
236
|
+
E_AMBIGUOUS_MATCH: {
|
|
237
|
+
path: string;
|
|
238
|
+
matches: number;
|
|
239
|
+
};
|
|
240
|
+
E_STORE_NEWER_VERSION: {
|
|
241
|
+
path: string;
|
|
242
|
+
storedVersion: number;
|
|
243
|
+
supportedVersion: number;
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
export interface CodeSpec<P> {
|
|
247
|
+
audience: Audience;
|
|
248
|
+
format: (payload: P) => string;
|
|
249
|
+
remedy?: string;
|
|
250
|
+
}
|
|
251
|
+
export declare function numericAnchorNote(anchors: string[]): string;
|
|
252
|
+
/** SAFETY: exact heading for an unverified fresh-read serve — machine-checkable. */
|
|
253
|
+
export declare const FRESH_READ_HEADING = "Current range (fresh read):";
|
|
254
|
+
/** SAFETY: one general headline clause for an unplaceable bound — no narration. */
|
|
255
|
+
export declare const UNVERIFIED_HEADLINE = "a bound of this range no longer resolves to the line identity it was served with.";
|
|
256
|
+
/** SAFETY: recovery sentence for a target-lost rejection — the only retry is a read. */
|
|
257
|
+
export declare const TARGET_LOST_RECOVERY = "The line you targeted was deleted or replaced; your anchors describe a version of this file that no longer exists. Read the file and re-target.";
|
|
258
|
+
export declare const ERROR_REGISTRY: {
|
|
259
|
+
[K in DomainErrorCode]: CodeSpec<ErrorPayloadMap[K]>;
|
|
260
|
+
};
|
|
261
|
+
export interface WarningPayloadMap {
|
|
262
|
+
W_NEVER_SERVED_SHAPE: {
|
|
263
|
+
count: number;
|
|
264
|
+
};
|
|
265
|
+
W_SERVED_PREFIX_MISMATCH: {
|
|
266
|
+
k: number;
|
|
267
|
+
anchor: string;
|
|
268
|
+
servedLine: number;
|
|
269
|
+
};
|
|
270
|
+
W_REVERSED_ANCHORS: {
|
|
271
|
+
fromHash: string;
|
|
272
|
+
toHash: string;
|
|
273
|
+
};
|
|
274
|
+
W_UNICODE_LITERAL: {
|
|
275
|
+
line: number;
|
|
276
|
+
};
|
|
277
|
+
W_LITERAL_BYPASS: Record<string, never>;
|
|
278
|
+
W_NOOP: {
|
|
279
|
+
ref: string;
|
|
280
|
+
anchorFrom: string;
|
|
281
|
+
anchorTo: string;
|
|
282
|
+
batch: boolean;
|
|
283
|
+
count: number;
|
|
284
|
+
/** Present on engine single warns: the display path ("in <path>" flavor). */
|
|
285
|
+
path?: string;
|
|
286
|
+
};
|
|
287
|
+
}
|
|
288
|
+
export declare const WARNING_REGISTRY: {
|
|
289
|
+
[K in DomainWarningCode]: CodeSpec<WarningPayloadMap[K]>;
|
|
290
|
+
};
|
|
291
|
+
/**
|
|
292
|
+
* SAFETY: the sole producer of `[W_*]` headers. Renders
|
|
293
|
+
* `[<AUDIENCE>] [<W_CODE>] <neutral-observation>` from the registry, so every
|
|
294
|
+
* applied-tier warning carries its machine-readable code and audience by
|
|
295
|
+
* construction.
|
|
296
|
+
*
|
|
297
|
+
* PURE by contract (T6 CP2, F2): a formatter carries no state. The deferral
|
|
298
|
+
* witnesses below are INJECTED (`AllowlistTrigger.holds(fired)`), never accumulated —
|
|
299
|
+
* a module-global "did it fire?" latch made a guard's verdict depend on whether an
|
|
300
|
+
* earlier test happened to render the warning, so a witness satisfiable by another
|
|
301
|
+
* test's side effect proved nothing about the guard that consumed it. The witness is
|
|
302
|
+
* derived by the test layer from a source scan (`test/support/arch-scan.ts`,
|
|
303
|
+
* `firedWarnings`) — a READ, so the verdict is a pure function of the tree and cannot
|
|
304
|
+
* depend on evaluation order or on a test-only reset hook.
|
|
305
|
+
*/
|
|
306
|
+
export declare function formatWarning<K extends DomainWarningCode>(code: K, payload: WarningPayloadMap[K]): string;
|
|
307
|
+
/**
|
|
308
|
+
* SAFETY: the sole composer of `[TO <AUDIENCE>] [<E_CODE>]` prefixes for errors.
|
|
309
|
+
* `DomainError` delegates here, so header construction has exactly one site.
|
|
310
|
+
*/
|
|
311
|
+
export declare function formatError<K extends DomainErrorCode>(code: K, payload: ErrorPayloadMap[K]): string;
|
|
312
|
+
export declare class DomainError<K extends DomainErrorCode = DomainErrorCode> extends Error {
|
|
313
|
+
readonly code: K;
|
|
314
|
+
readonly audience: Audience;
|
|
315
|
+
readonly payload: ErrorPayloadMap[K];
|
|
316
|
+
readonly servedRows: ServedRow[];
|
|
317
|
+
readonly servedBlock: string;
|
|
318
|
+
readonly cause?: RangeCause;
|
|
319
|
+
readonly firstOffendingLine?: number;
|
|
320
|
+
readonly details: {
|
|
321
|
+
cause?: RangeCause;
|
|
322
|
+
code: K;
|
|
323
|
+
};
|
|
324
|
+
constructor(code: K, payload: ErrorPayloadMap[K]);
|
|
325
|
+
}
|
|
326
|
+
export declare function isDomainErrorCode(code: unknown): code is DomainErrorCode;
|
|
327
|
+
/** Warning analogue of `isDomainErrorCode`: only registry members qualify. */
|
|
328
|
+
export declare function isDomainWarningCode(code: unknown): code is DomainWarningCode;
|
|
329
|
+
/**
|
|
330
|
+
* A trigger must be CHECKABLE, not a phrase. `text` names the artifact whose
|
|
331
|
+
* change makes this entry actionable — a queue line (`Q-T<n>`), an issue
|
|
332
|
+
* (`#NN`), an absorb branch (`absorb/<branch>`), or a `src/` path — and
|
|
333
|
+
* `holds(fired)` is a predicate that must remain true while the entry exists. The
|
|
334
|
+
* witness is INJECTED, never read from module state: production carries no latch, so
|
|
335
|
+
* the same source yields the same verdict in any evaluation order (T6 CP2, F2). The
|
|
336
|
+
* arch oracle supplies its own, independently derived witness and asserts both
|
|
337
|
+
* (`AllowlistEntry` is the two-referents rule in type form; see
|
|
338
|
+
* `test/support/arch-scan.ts`).
|
|
339
|
+
*/
|
|
340
|
+
export interface AllowlistTrigger {
|
|
341
|
+
readonly text: string;
|
|
342
|
+
/** `fired` = codes whose producer became visible to the caller's witness scan. */
|
|
343
|
+
readonly holds: (fired: ReadonlySet<string>) => boolean;
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* An allowlist entry. `owner` must be an ADDRESSABLE identity — **a bare `T6` is
|
|
347
|
+
* not an identity**: `docs/absorption-plan.md:35` gives T6 to the README+CONTEXT
|
|
348
|
+
* merge while the T4 brief gives it to multi-window read, so the id collides
|
|
349
|
+
* across lanes (T4 CP1-r5 G7).
|
|
350
|
+
*/
|
|
351
|
+
export interface AllowlistEntry {
|
|
352
|
+
readonly owner: string;
|
|
353
|
+
readonly trigger: AllowlistTrigger;
|
|
354
|
+
}
|
|
355
|
+
/** Owners and trigger texts must start with one of these addressable forms. */
|
|
356
|
+
export declare const ADDRESSABLE_OWNER_RE: RegExp;
|
|
357
|
+
/**
|
|
358
|
+
* Registry fields that are declared but never rendered, keyed by field name.
|
|
359
|
+
* `owner`/`trigger` are identities (see `AllowlistEntry`); the arch oracle pins
|
|
360
|
+
* this map by identity against its own copy **and** independently computes the
|
|
361
|
+
* "still declaration-only" predicate (0 readers of `.<field>` across `src/`).
|
|
362
|
+
*/
|
|
363
|
+
export declare const DECLARATION_ONLY_FIELDS: Readonly<Record<string, AllowlistEntry>>;
|
|
364
|
+
/**
|
|
365
|
+
* Codes declared by the contract but produced by a later ticket. Shrink-only:
|
|
366
|
+
* a code that gains a producer MUST be removed from this map (the arch oracle
|
|
367
|
+
* fails otherwise).
|
|
368
|
+
*
|
|
369
|
+
* Upstream parity is NOT a reason to keep a code nothing can produce — and it
|
|
370
|
+
* is not a reason to hide one either. T4 (CP1-r3) removed four declarations
|
|
371
|
+
* that had zero local producers, zero reachable messages and no nameable local
|
|
372
|
+
* owner. FU-4 (absorb/follow-upstream, upstream `pi-better-edit@b92e0ec`)
|
|
373
|
+
* re-introduced all four WITH their producers — per-code decision: **adopt the
|
|
374
|
+
* upstream diagnostic** (the alternative, mapping onto `E_STALE_RANGE` /
|
|
375
|
+
* `E_UNSERVED_RANGE`, is what ADR-0022 recorded and what this absorb
|
|
376
|
+
* supersedes):
|
|
377
|
+
*
|
|
378
|
+
* | ported upstream diagnostic | upstream producer (pi-better-edit@b92e0ec) | local producer |
|
|
379
|
+
* |---|---|---|
|
|
380
|
+
* | `E_FOREIGN_ANCHOR` | `lease-resolve.ts:116` | `anchor-pipeline.ts` (`throwUnknownOrForeign`, boundary placement) |
|
|
381
|
+
* | `E_UNKNOWN_ANCHOR` | `lease-resolve.ts:118`, `served-verification.ts:745` | `anchor-pipeline.ts` (boundary placement, pre-gate) |
|
|
382
|
+
* | `E_UNVERIFIED_RANGE` | `lease-resolve.ts:186`, `served-verification.ts:187` | `anchor-pipeline.ts` (pre-gate stale-boundary arm) |
|
|
383
|
+
* | `E_TARGET_LOST` | `served-verification.ts:170`, `lease-resolve.ts:196` | `anchor-pipeline.ts` (pre-gate stale-boundary arm) |
|
|
384
|
+
*
|
|
385
|
+
* Their owner is `"upstream absorb"` and their trigger is the absorb that
|
|
386
|
+
* ports the corresponding producer. When that happens, reintroduce the code
|
|
387
|
+
* WITH its producer: the union member is gone, so the port will not compile
|
|
388
|
+
* until the absorber records a per-code decision (adopt the upstream
|
|
389
|
+
* diagnostic, or map it onto `E_STALE_RANGE` / `E_UNSERVED_RANGE` /
|
|
390
|
+
* `E_STALE_ANCHOR`). `docs/absorption-plan.md` ("Debt — T4 …") carries the
|
|
391
|
+
* same record for the next absorb.
|
|
392
|
+
*
|
|
393
|
+
* ── IDENTITY, NOT SHAPE (T4 CP1-r4/r5; T6 R15) ──
|
|
394
|
+
* `owner` and `trigger.text` below are pinned BY IDENTITY in
|
|
395
|
+
* `test/arch/domain-error-registry.test.ts` (C7/C16), so changing one is a
|
|
396
|
+
* deliberate edit that must touch the test — never a silent one. T6 replaced the
|
|
397
|
+
* lane-letter owner (`Q-T6`) with the addressable producer seam, and the
|
|
398
|
+
* `holds: () => isDomainWarningCode(…)` with a predicate over an INJECTED witness:
|
|
399
|
+
* `holds(fired)` is false exactly when a producer for that code is visible to the
|
|
400
|
+
* caller's scan (T6 CP2 F2). Production keeps no state, so the verdict cannot be
|
|
401
|
+
* satisfied by another test's earlier firing — the defect the first form had. The arch
|
|
402
|
+
* oracle derives the witness from source (a read) and recomputes the same producer scan
|
|
403
|
+
* as its independent second referent.
|
|
404
|
+
*
|
|
405
|
+
* FU-5 (absorb/follow-upstream, upstream `pi-better-edit@b92e0ec` §4.7) landed the
|
|
406
|
+
* two deferred `W_*` producers in `src/hashline/served-guard.ts` — per the shrink-only
|
|
407
|
+
* rule above both entries are removed. The map is empty; the mechanism and the
|
|
408
|
+
* identity pins stay for the next deferral.
|
|
409
|
+
*/
|
|
410
|
+
export declare const DEFERRED_PRODUCERS: Readonly<Record<string, AllowlistEntry>>;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { ServedRow } from "./hashline/anchor-pipeline.js";
|
|
2
2
|
export type EditDetails = {
|
|
3
3
|
diff: string;
|
|
4
|
-
/** Bare `E_*` code for the primary error signal, if any (no `[MODEL]` prefix). Structured counterpart to message-string codes. */
|
|
4
|
+
/** Bare `E_*` code for the primary error signal, if any (no `[TO MODEL]` prefix). Structured counterpart to message-string codes. */
|
|
5
5
|
errCode?: string;
|
|
6
6
|
/** Disambiguator for `E_UNSERVED_RANGE`: boundary miss vs interior hole. */
|
|
7
7
|
unservedKind?: "boundary" | "interior";
|
|
@@ -30,6 +30,7 @@ export declare function setAutoGuessFooter(targetKey: string, footer: string): v
|
|
|
30
30
|
export declare function clearAutoGuessFooter(targetKey?: string): void;
|
|
31
31
|
/** Invalidate memo when FsVersion drifted (ADR-0012). */
|
|
32
32
|
export declare function invalidateIfStale(targetKey: string, currentVersion: string | undefined): void;
|
|
33
|
+
export declare function buildTop3Description(candidates: CandidatePreview[]): string;
|
|
33
34
|
export declare function buildTop3ErrorMessage(displayPath: string, candidates: CandidatePreview[]): string;
|
|
34
35
|
export interface DecodeAdmissionConfig {
|
|
35
36
|
autoGuessEncoding: boolean;
|
package/lib/types/file-view.d.ts
CHANGED
|
@@ -24,6 +24,7 @@ import type { HashStore } from "./hash-store.js";
|
|
|
24
24
|
export declare const MAX_HASH_LINES: number;
|
|
25
25
|
export declare const DEFAULT_MAX_LINES = 2000;
|
|
26
26
|
export declare const DEFAULT_MAX_BYTES: number;
|
|
27
|
+
export declare const MAX_READ_WINDOWS = 16;
|
|
27
28
|
export interface TruncationResult {
|
|
28
29
|
content: string;
|
|
29
30
|
truncated: boolean;
|
|
@@ -42,16 +43,25 @@ export declare function truncateHead(content: string, options?: {
|
|
|
42
43
|
maxLines?: number;
|
|
43
44
|
maxBytes?: number;
|
|
44
45
|
}): TruncationResult;
|
|
46
|
+
/** Snapshot identity and size: the only `fs.Stats` fields this codebase reads. */
|
|
47
|
+
export interface FileStats {
|
|
48
|
+
ino: number;
|
|
49
|
+
size: number;
|
|
50
|
+
mtimeMs: number;
|
|
51
|
+
ctimeMs: number;
|
|
52
|
+
}
|
|
53
|
+
export interface LFileText {
|
|
54
|
+
kind: "text";
|
|
55
|
+
text: string;
|
|
56
|
+
stats?: FileStats;
|
|
57
|
+
hadUtf8DecodeErrors?: true;
|
|
58
|
+
}
|
|
45
59
|
export type LFile = {
|
|
46
60
|
kind: "directory";
|
|
47
61
|
} | {
|
|
48
62
|
kind: "image";
|
|
49
63
|
mimeType: string;
|
|
50
|
-
} | {
|
|
51
|
-
kind: "text";
|
|
52
|
-
text: string;
|
|
53
|
-
hadUtf8DecodeErrors?: true;
|
|
54
|
-
} | {
|
|
64
|
+
} | LFileText | {
|
|
55
65
|
kind: "binary";
|
|
56
66
|
description: string;
|
|
57
67
|
};
|
|
@@ -81,7 +91,7 @@ export type SnapInfo = {
|
|
|
81
91
|
ctimeMs: number;
|
|
82
92
|
size: number;
|
|
83
93
|
};
|
|
84
|
-
export declare function fileSnap(absolutePath: string): Promise<SnapInfo>;
|
|
94
|
+
export declare function fileSnap(absolutePath: string, preloadedStats?: FileStats): Promise<SnapInfo>;
|
|
85
95
|
export interface ReadNormOptions {
|
|
86
96
|
signal?: AbortSignal;
|
|
87
97
|
accessMode?: number;
|
|
@@ -115,10 +125,27 @@ export declare function normFromText(input: {
|
|
|
115
125
|
};
|
|
116
126
|
}): Promise<NormFile>;
|
|
117
127
|
export declare function readNormFile(path: string, cwd: string, options?: ReadNormOptions): Promise<NormFile>;
|
|
128
|
+
/** One requested line range of a multi-window read (FU-6, port of pi-better-edit@2334352). */
|
|
129
|
+
export interface ReadWindow {
|
|
130
|
+
offset: number;
|
|
131
|
+
limit: number;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* The windows rule, owned here so the preview and the serve-side full-read contract
|
|
135
|
+
* cannot disagree: `undefined` and `[]` both mean "no windows" — the caller falls back to the
|
|
136
|
+
* single-window `offset`/`limit` contract, so an empty array stays backward compatible.
|
|
137
|
+
*
|
|
138
|
+
* WHY (moved with the rule from read-and-serve): `windows: []` falls back to a
|
|
139
|
+
* full read in the preview, so the full-read contract has to follow the same rule — otherwise an
|
|
140
|
+
* empty array silently skips the drift clear that a full read owes. A non-empty multi-window
|
|
141
|
+
* read serves sparse rows, never the full file.
|
|
142
|
+
*/
|
|
143
|
+
export declare function hasRequestedWindows(windows: readonly ReadWindow[] | undefined): windows is readonly ReadWindow[];
|
|
118
144
|
export declare function formatPaginationHint(startLine: number, endLine: number, totalLines: number, nextOffset: number, byteLimit?: number): string;
|
|
119
145
|
export declare function fmtReadPreview(text: string, options: {
|
|
120
146
|
offset?: number;
|
|
121
147
|
limit?: number;
|
|
148
|
+
windows?: ReadWindow[];
|
|
122
149
|
}, precomputedHashes?: string[], path?: string, maxLineBytes?: number, maxTruncLines?: number): Promise<{
|
|
123
150
|
text: string;
|
|
124
151
|
truncation?: TruncationResult;
|
|
@@ -140,6 +167,8 @@ export interface FileView {
|
|
|
140
167
|
export interface PreviewOpts {
|
|
141
168
|
offset?: number;
|
|
142
169
|
limit?: number;
|
|
170
|
+
/** FU-6 (2334352): disjoint ranges in one call; wins over offset/limit when non-empty. */
|
|
171
|
+
windows?: ReadWindow[];
|
|
143
172
|
}
|
|
144
173
|
export interface ReadViewOpts extends PreviewOpts {
|
|
145
174
|
encoding?: string;
|
|
@@ -4,8 +4,8 @@ export declare const DEFAULT_PRESETS: readonly string[];
|
|
|
4
4
|
* The root README: the per-preset customization convention users see in the
|
|
5
5
|
* plugin home.
|
|
6
6
|
*/
|
|
7
|
-
export declare const GUIDANCE_HOME_README = "# dsh-better-edit guidance\n\nEach agent preset has its own guidance directory here: `<preset>/<section>.md`.\nOn first boot the plugin seeds the shipped presets (`standard`, `
|
|
8
|
-
export declare const GUIDANCE_HOME_README_ZH = "# dsh-better-edit \u6307\u5F15\n\n\u6BCF\u4E2A agent preset \u5728\u8FD9\u91CC\u90FD\u6709\u81EA\u5DF1\u7684\u6307\u5F15\u76EE\u5F55\uFF1A`<preset>/<section>.md`\u3002\u9996\u6B21\u542F\u52A8\u65F6\n\u63D2\u4EF6\u4F1A\u4E3A\u968F\u9644\u7684 preset\uFF08`standard`\u3001`
|
|
7
|
+
export declare const GUIDANCE_HOME_README = "# dsh-better-edit guidance\n\nEach agent preset has its own guidance directory here: `<preset>/<section>.md`.\nOn first boot the plugin seeds the shipped presets (`standard`, `ptc`,\n`minimal`, `cordis`) with the compiled defaults; existing files are never\noverwritten, so your edits survive.\n\nEach file is one tool section:\n\n- `read.md` -> `tool:read`\n- `edit.md` -> `tool:edit`\n- `undo_last_edit.md` -> `tool:undo_last_edit`\n\n## Customize\n\nEdit the `<section>.md` file for the preset and section you want to change \u2014\nthe file body IS the text the model reads for that section. Files are read once\nper agent when it is created (`agent/created`), so edits apply to new sessions.\n\nAn optional YAML front-matter fence places the section at a custom position in\nthe assembled system prompt:\n\n ---\n order: 1100\n ---\n\n <section text>\n\nA file without front-matter keeps the default order. A malformed fence (a\nmissing closing `---`, a non-integer `order`, an unknown key) makes the whole\nfile plain prose.\n\n## Fallback\n\nA preset with no directory here, or a missing section file, falls back to the\ncompiled defaults in the plugin bundle. To customize a preset that has no\nseeded directory, copy a seeded one to its name.\n";
|
|
8
|
+
export declare const GUIDANCE_HOME_README_ZH = "# dsh-better-edit \u6307\u5F15\n\n\u6BCF\u4E2A agent preset \u5728\u8FD9\u91CC\u90FD\u6709\u81EA\u5DF1\u7684\u6307\u5F15\u76EE\u5F55\uFF1A`<preset>/<section>.md`\u3002\u9996\u6B21\u542F\u52A8\u65F6\n\u63D2\u4EF6\u4F1A\u4E3A\u968F\u9644\u7684 preset\uFF08`standard`\u3001`ptc`\u3001`minimal`\u3001`cordis`\uFF09\u5199\u5165\u7F16\u8BD1\u5185\u7F6E\u7684\n\u9ED8\u8BA4\u5185\u5BB9\uFF1B\u5DF2\u6709\u6587\u4EF6\u7EDD\u4E0D\u88AB\u8986\u76D6\uFF0C\u56E0\u6B64\u4F60\u7684\u7F16\u8F91\u4F1A\u4FDD\u7559\u3002\n\n\u6BCF\u4E2A\u6587\u4EF6\u5BF9\u5E94\u4E00\u4E2A\u5DE5\u5177\u7247\u6BB5\uFF1A\n\n- `read.md` -> `tool:read`\n- `edit.md` -> `tool:edit`\n- `undo_last_edit.md` -> `tool:undo_last_edit`\n\n## \u81EA\u5B9A\u4E49\n\n\u7F16\u8F91\u4F60\u60F3\u4FEE\u6539\u7684 preset \u4E0E\u7247\u6BB5\u7684 `<section>.md` \u6587\u4EF6\u5373\u53EF\u2014\u2014\u6587\u4EF6\u6B63\u6587\u5C31\u662F\u8BE5\u7247\u6BB5\u5448\n\u73B0\u7ED9\u6A21\u578B\u7684\u6587\u672C\u3002\u6587\u4EF6\u5728 agent \u521B\u5EFA\u65F6\uFF08`agent/created`\uFF09\u8BFB\u53D6\u4E00\u6B21\uFF0C\u56E0\u6B64\u4FEE\u6539\u53EA\u5F71\u54CD\u65B0\u4F1A\u8BDD\u3002\n\n\u53EF\u4EE5\u7528\u53EF\u9009\u7684 YAML front-matter \u6805\u680F\u628A\u7247\u6BB5\u653E\u5230\u7EC4\u88C5\u540E\u7CFB\u7EDF\u63D0\u793A\u4E2D\u7684\u81EA\u5B9A\u4E49\u4F4D\u7F6E\uFF1A\n\n ---\n order: 1100\n ---\n\n <\u7247\u6BB5\u6587\u672C>\n\n\u6CA1\u6709 front-matter \u7684\u6587\u4EF6\u4FDD\u6301\u9ED8\u8BA4\u987A\u5E8F\u3002\u683C\u5F0F\u9519\u8BEF\u7684\u6805\u680F\uFF08\u7F3A\u5C11\u6536\u5C3E `---`\u3001\u975E\u6574\u6570\n`order`\u3001\u672A\u77E5\u952E\uFF09\u4F1A\u8BA9\u6574\u4E2A\u6587\u4EF6\u9000\u5316\u4E3A\u7EAF\u6587\u672C\u3002\n\n## \u56DE\u9000\n\n\u8FD9\u91CC\u6CA1\u6709\u5BF9\u5E94\u76EE\u5F55\u7684 preset\u3001\u6216\u7F3A\u5931\u67D0\u4E2A\u7247\u6BB5\u6587\u4EF6\u65F6\uFF0C\u4F1A\u56DE\u9000\u5230\u63D2\u4EF6\u5305\u5185\u7684\u7F16\u8BD1\u5185\u7F6E\u9ED8\u8BA4\n\u503C\u3002\u8981\u81EA\u5B9A\u4E49\u6CA1\u6709\u79CD\u5B50\u76EE\u5F55\u7684 preset\uFF0C\u628A\u4E00\u4E2A\u79CD\u5B50\u76EE\u5F55\u590D\u5236\u6210\u5B83\u7684\u540D\u5B57\u5373\u53EF\u3002\n";
|
|
9
9
|
/**
|
|
10
10
|
* Materialize per-preset guidance directories in the plugin home.
|
|
11
11
|
*
|
|
@@ -4,8 +4,18 @@ export interface GuidanceSection {
|
|
|
4
4
|
name: string;
|
|
5
5
|
/** Override file name inside a preset directory, e.g. `edit.md`. */
|
|
6
6
|
file: string;
|
|
7
|
-
/**
|
|
7
|
+
/**
|
|
8
|
+
* Order used when neither the override file nor the harness names one — the
|
|
9
|
+
* fallback for a registry that predates `systemPrompt.getSectionOrder`.
|
|
10
|
+
* Mirrors dsh 0.2.1's `SECTION_ORDERS` tool band.
|
|
11
|
+
*/
|
|
8
12
|
defaultOrder: number;
|
|
13
|
+
/**
|
|
14
|
+
* The `systemPrompt.getSectionOrder` name of the tool slot this section
|
|
15
|
+
* shadows (e.g. `TOOL_READ`), so the live band wins over `defaultOrder`.
|
|
16
|
+
* Absent for plugin-owned sections with no harness slot.
|
|
17
|
+
*/
|
|
18
|
+
orderName?: "TOOL_READ" | "TOOL_EDIT";
|
|
9
19
|
/** The compiled default text, byte-identical to today's inline rendering. */
|
|
10
20
|
renderDefault(): string;
|
|
11
21
|
}
|
|
@@ -19,6 +29,8 @@ export interface ResolveGuidanceOptions {
|
|
|
19
29
|
presetId?: string;
|
|
20
30
|
/** Plugin shared home directory (`$DSH_HOME/plugins/dsh-better-edit`). */
|
|
21
31
|
homeDir: string;
|
|
32
|
+
/** Live harness slot for a section, when the registry exposes one. */
|
|
33
|
+
defaultOrder?: (section: GuidanceSection) => number;
|
|
22
34
|
}
|
|
23
35
|
/** The resolved text and order for one section. */
|
|
24
36
|
export interface GuidanceResolution {
|
|
@@ -52,4 +64,4 @@ export interface SectionOverride {
|
|
|
52
64
|
* Resolve all three sections for a preset. `presetId === undefined` skips the
|
|
53
65
|
* `<preset>/` layer and resolves straight to the compiled defaults.
|
|
54
66
|
*/
|
|
55
|
-
export declare function composeSections(presetId: string | undefined, homeDir: string): Promise<SectionOverride[]>;
|
|
67
|
+
export declare function composeSections(presetId: string | undefined, homeDir: string, defaultOrder?: (section: GuidanceSection) => number): Promise<SectionOverride[]>;
|