dsh-better-edit 0.2.2 → 0.3.1

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.
Files changed (85) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +317 -240
  3. package/README.zh.md +19 -11
  4. package/lib/constants.js +3 -1
  5. package/lib/contract.js +159 -63
  6. package/lib/drift.js +5 -98
  7. package/lib/dsh-context.js +2 -24
  8. package/lib/edit-engine.js +9 -8
  9. package/lib/edit-pipeline.js +3 -121
  10. package/lib/edit-response.js +16 -8
  11. package/lib/file-kind.js +6 -121
  12. package/lib/file-reader.js +4 -77
  13. package/lib/file-view.js +486 -0
  14. package/lib/guidance/index.js +8 -0
  15. package/lib/guidance/materialize.js +212 -0
  16. package/lib/guidance/parse.js +80 -0
  17. package/lib/guidance/resolve.js +116 -0
  18. package/lib/guidance.js +6 -388
  19. package/lib/hash-store.js +6 -4
  20. package/lib/hashline/alphabet.js +2 -6
  21. package/lib/hashline/anchor-pipeline.js +786 -0
  22. package/lib/hashline/apply.js +2 -223
  23. package/lib/hashline/hash-assign.js +255 -0
  24. package/lib/hashline/hash.js +67 -29
  25. package/lib/hashline/hasher.js +2 -23
  26. package/lib/hashline/index.js +9 -4
  27. package/lib/hashline/parse.js +2 -35
  28. package/lib/hashline/pure.js +2 -213
  29. package/lib/hashline/resolve.js +3 -361
  30. package/lib/hashline/served.js +2 -120
  31. package/lib/index.js +1 -3
  32. package/lib/mutation.js +266 -0
  33. package/lib/noop-guard.js +20 -0
  34. package/lib/preview-controller.js +65 -0
  35. package/lib/prompts.js +14 -20
  36. package/lib/read-and-serve.js +23 -23
  37. package/lib/read-render.js +3 -139
  38. package/lib/served-store.js +2 -216
  39. package/lib/session-view.js +332 -0
  40. package/lib/tool-batch-edit.js +9 -10
  41. package/lib/tool-edit.js +73 -129
  42. package/lib/tool-read.js +3 -5
  43. package/lib/tool-undo.js +16 -10
  44. package/lib/truncate.js +3 -95
  45. package/lib/types/constants.d.ts +2 -0
  46. package/lib/types/contract.d.ts +120 -15
  47. package/lib/types/drift.d.ts +5 -29
  48. package/lib/types/dsh-context.d.ts +2 -20
  49. package/lib/types/edit-engine.d.ts +2 -2
  50. package/lib/types/edit-pipeline.d.ts +3 -44
  51. package/lib/types/file-kind.d.ts +6 -18
  52. package/lib/types/file-reader.d.ts +4 -45
  53. package/lib/types/file-view.d.ts +139 -0
  54. package/lib/types/guidance/index.d.ts +8 -0
  55. package/lib/types/guidance/materialize.d.ts +23 -0
  56. package/lib/types/guidance/parse.d.ts +36 -0
  57. package/lib/types/guidance/resolve.d.ts +55 -0
  58. package/lib/types/guidance.d.ts +6 -127
  59. package/lib/types/hashline/alphabet.d.ts +1 -5
  60. package/lib/types/hashline/anchor-pipeline.d.ts +127 -0
  61. package/lib/types/hashline/apply.d.ts +1 -22
  62. package/lib/types/hashline/hash-assign.d.ts +25 -0
  63. package/lib/types/hashline/hash.d.ts +8 -9
  64. package/lib/types/hashline/hasher.d.ts +1 -8
  65. package/lib/types/hashline/index.d.ts +12 -4
  66. package/lib/types/hashline/parse.d.ts +1 -7
  67. package/lib/types/hashline/pure.d.ts +1 -26
  68. package/lib/types/hashline/resolve.d.ts +1 -58
  69. package/lib/types/hashline/served.d.ts +1 -43
  70. package/lib/types/mutation.d.ts +131 -0
  71. package/lib/types/noop-guard.d.ts +29 -0
  72. package/lib/types/preview-controller.d.ts +33 -0
  73. package/lib/types/prompts.d.ts +9 -9
  74. package/lib/types/read-and-serve.d.ts +6 -5
  75. package/lib/types/read-render.d.ts +3 -18
  76. package/lib/types/served-store.d.ts +2 -81
  77. package/lib/types/session-view.d.ts +92 -0
  78. package/lib/types/tool-edit.d.ts +3 -14
  79. package/lib/types/truncate.d.ts +3 -29
  80. package/lib/types/validation.d.ts +6 -7
  81. package/lib/types/workspace.d.ts +2 -21
  82. package/lib/validation.js +6 -33
  83. package/lib/workspace.js +2 -27
  84. package/lib/write-hook.js +2 -2
  85. package/package.json +2 -2
@@ -1,26 +1 @@
1
- import { initHasher } from "./hasher.js";
2
- import { HASH_LEN, ALPH_RE, HASH_CLASS } from "./alphabet.js";
3
- export { initHasher, HASH_LEN, ALPH_RE, HASH_CLASS };
4
- export declare const ANCHOR_LEN = 3;
5
- export declare const HASH_SEP = "\u2502";
6
- export declare const HASH_SPACE: number;
7
- export declare const MAX_HASH_LINES: number;
8
- export declare const HASH_PROBE_STRIDE: number;
9
- export declare const HL_PREFIX_PLUS_RE: RegExp;
10
- export declare const HL_PREFIX_MINUS_RE: RegExp;
11
- export declare const HL_BARE_PREFIX_RE: RegExp;
12
- export declare function canon(line: string): string;
13
- /**
14
- * Pure hash-anchor assignment: every line of `content` gets a unique 3-char
15
- * anchor derived from its canonicalized content via xxhash32 + probe-stride
16
- * allocation. No I/O, no store — the persistence-aware wrapper
17
- * {@link lineHashes} (in ./hash.js) composes this with snapshot load/upsert.
18
- */
19
- export declare function lineHashesPure(content: string): string[];
20
- /**
21
- * Pure stable re-hash: given the pre-edit content + anchors and the new
22
- * content (plus the hashes removed by the edit), map surviving lines to
23
- * their old anchors, re-claim removed anchors for identical lines, and
24
- * allocate fresh anchors for the rest. No I/O, no store.
25
- */
26
- export declare function mapStableHashes(oldContent: string, oldHashes: string[], newContent: string, removedHashes?: Set<string>): string[];
1
+ export * from "./hash-assign.js";
@@ -1,58 +1 @@
1
- import { type Anchor } from "./parse.js";
2
- import type { ServedRow } from "./served.js";
3
- export type RAnchor = {
4
- line: number;
5
- hash: string;
6
- hashMatched: boolean;
7
- };
8
- export type HEdit = {
9
- content_lines: string[];
10
- hash_bounds: [Anchor, Anchor];
11
- };
12
- export type RHEdit = {
13
- content_lines: string[];
14
- hash_bounds: [RAnchor, RAnchor];
15
- };
16
- interface HMismatch {
17
- ref: Anchor;
18
- kind: "not_found" | "ambiguous";
19
- candidates?: number[];
20
- context?: RAnchor;
21
- }
22
- export interface BDup {
23
- kind: "trailing" | "leading" | "first-new-after" | "last-new-before";
24
- replacementLineIndex: number;
25
- }
26
- export interface AutoFix {
27
- kind: "trailing" | "leading" | "first-new-after" | "last-new-before";
28
- removedLine: string;
29
- removedLineIndex: number;
30
- }
31
- export interface NEdit {
32
- loc: string;
33
- currentContent: string;
34
- }
35
- export type HTEdit = {
36
- replacement_text: string;
37
- remove_from: string;
38
- remove_to: string;
39
- };
40
- export declare function fmtMismatchWithServes(mismatches: HMismatch[], fileLines: string[], fileHashes: string[], filePath?: string): {
41
- message: string;
42
- servedRows: ServedRow[];
43
- };
44
- export declare function resEdit(edit: HTEdit, warnings?: string[]): HEdit;
45
- declare function warnUnicodeEsc(edit: HEdit, warnings: string[]): void;
46
- export declare function stripBarePrefixes(edit: HEdit, fileHashes: string[], warnings: string[]): HEdit;
47
- export declare function stripDiffPrefixes(edit: HEdit, warnings: string[]): HEdit;
48
- export declare function swapReversedRanges(edit: HEdit, fileHashes: string[], warnings: string[]): HEdit;
49
- export declare function findNewEdge(contentLines: string[], rangeLines: string[], fromEnd: boolean): {
50
- index: number;
51
- line: string;
52
- } | undefined;
53
- export declare function valEdit(edit: HEdit, fileLines: string[], fileHashes: string[], warnings: string[], signal: AbortSignal | undefined): {
54
- resolved: RHEdit | undefined;
55
- mismatches: HMismatch[];
56
- boundaryDups: BDup[];
57
- };
58
- export { warnUnicodeEsc };
1
+ export * from "./anchor-pipeline.js";
@@ -1,43 +1 @@
1
- export type ServedCode = "E_RANGE_STALE" | "E_RANGE_UNSERVED" | "E_RANGE_UNVERIFIED";
2
- export interface ServedRow {
3
- position: number;
4
- hash: string;
5
- }
6
- export declare class ServedRejectionError extends Error {
7
- readonly code: ServedCode;
8
- readonly firstOffendingLine: number | undefined;
9
- readonly servedRows: ServedRow[];
10
- constructor(opts: {
11
- code: ServedCode;
12
- message: string;
13
- firstOffendingLine?: number;
14
- servedRows: ServedRow[];
15
- });
16
- }
17
- export declare function isServedRejection(error: unknown): error is ServedRejectionError;
18
- export declare class AnchorMismatchError extends Error {
19
- readonly servedRows: ServedRow[];
20
- constructor(message: string, servedRows: ServedRow[]);
21
- }
22
- export declare function isAnchorMismatch(error: unknown): error is AnchorMismatchError;
23
- export declare function buildRangeEcho(startLine: number, endLine: number, fileHashes: string[]): ServedRow[];
24
- export declare function fmtServedRows(rows: ServedRow[], fileLines: string[]): string;
25
- export declare function verifyServedRange(args: {
26
- served: (string | null)[];
27
- startHash: string;
28
- endHash: string;
29
- startLine: number;
30
- endLine: number;
31
- fileHashes: string[];
32
- fileLines: string[];
33
- filePath?: string;
34
- }): void;
35
- export interface ResolvedRange {
36
- startLine: number;
37
- endLine: number;
38
- startHash: string;
39
- endHash: string;
40
- delta: number;
41
- }
42
- export type ServeRecordPolicy = "live" | "preview";
43
- export declare function recordEchoServes(sessionKey: string, path: string, rows: ServedRow[], policy: ServeRecordPolicy, lineCount?: number): Promise<void>;
1
+ export * from "./anchor-pipeline.js";
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Mutation — deep module owning the full file mutation lifecycle.
3
+ *
4
+ * Previously fragmented: tool-edit → edit-pipeline → edit-engine.applyOne →
5
+ * edit-response/diff/drift, and tool-batch-edit → edit-engine.runFileEdits
6
+ * (loop + unionRange + counters) → persistUndoAndWrite with a boolean flag.
7
+ * Warnings, hadUtf8DecodeErrors, firstChangedLine, driftNotice were threaded
8
+ * by mutation across 5 hops; bugs hid in wiring, not pure helpers.
9
+ *
10
+ * This seam owns: read → normalize → loadServed → applyOne* → stableRehash →
11
+ * drift → persist → render. Tools become thin adapters: validate → delegate → return.
12
+ * edit-diff, drift, noop-guard are private helpers of this seam.
13
+ *
14
+ * Public surface:
15
+ * execute(io, items, {sessionKey, exec, sandbox, signal}) → string — deep seam: ONE interface
16
+ * applySingle(io, params, cwd, opts) → PipelineResult — single-edit helper
17
+ * applySequence(io, items, ctx) → FileEditResult — per-file sequencer
18
+ * commit(io, files, {exec, sandboxPolicy, signal}) → void — transaction
19
+ *
20
+ * Depth: small interface (execute) with large implementation — locality and leverage.
21
+ *
22
+ * Internals (private): verifyServedRange, resToSpan, assemble, scanDrift,
23
+ * boundaryDups, noopGuard. Tested via PipelineResult/FileEditResult, not via split e2e.
24
+ *
25
+ * @module dsh-better-edit/mutation
26
+ */
27
+ import type { FileIO } from "./fs-bridge.js";
28
+ import type { EditParams } from "./contract.js";
29
+ import type { HashStore } from "./hash-store.js";
30
+ import type { ToolExecution } from "@deepseek-ai/dsh-tools";
31
+ import type { SandboxExecutionPolicy } from "@deepseek-ai/dsh-sandbox";
32
+ import type { FsSandboxController } from "./sandbox.js";
33
+ import type { LineEnding } from "./edit-diff.js";
34
+ import { type NEdit } from "./hashline/anchor-pipeline.js";
35
+ import type { ResolvedRange } from "./hashline/anchor-pipeline.js";
36
+ import { scanDrift } from "./session-view.js";
37
+ import { runFileEdits, resolveMissingPath, persistUndoAndWrite, enforceNoopLoop, collectRemovedHashes, countLineChanges } from "./edit-engine.js";
38
+ import type { FileEditResult, PreparedItem } from "./edit-engine.js";
39
+ import { buildMetrics, buildNoop, buildChanged, buildBatchResult } from "./edit-response.js";
40
+ import type { RMeta, BatchSection } from "./edit-response.js";
41
+ import { genDiff, restoreEndings, toLF, stripBOM } from "./edit-diff.js";
42
+ import { computeDrift } from "./drift.js";
43
+ import { trackNoopPayload, clearNoopLoop, noopPayloadKey } from "./noop-guard.js";
44
+ export interface PipelineResult {
45
+ path: string;
46
+ absolutePath: string;
47
+ originalNormalized: string;
48
+ result: string;
49
+ bom: string;
50
+ originalEnding: LineEnding;
51
+ hadUtf8DecodeErrors: boolean;
52
+ warnings: string[];
53
+ noopEdit?: NEdit;
54
+ firstChangedLine?: number;
55
+ lastChangedLine?: number;
56
+ originalHashes: string[];
57
+ resultHashes: string[];
58
+ totalAddedLines: number;
59
+ totalRemovedLines: number;
60
+ driftNotice?: string;
61
+ range: ResolvedRange;
62
+ }
63
+ export interface ExecPipelineOptions {
64
+ signal?: AbortSignal;
65
+ store?: HashStore;
66
+ noPersist?: boolean;
67
+ sessionKey?: string;
68
+ }
69
+ export declare function execPipeline(io: FileIO, params: EditParams, cwd: string, options?: ExecPipelineOptions): Promise<PipelineResult>;
70
+ /** Resolve the display path a caller names against the session cwd. */
71
+ export declare function resolveDisplayPath(path: string, cwd: string): string;
72
+ /** Snapshot bookkeeping for noop/success results (best-effort). */
73
+ export declare function snapshotIdFor(io: FileIO, absolutePath: string, signal?: AbortSignal): Promise<string | undefined>;
74
+ export { runFileEdits, resolveMissingPath, persistUndoAndWrite, enforceNoopLoop, collectRemovedHashes, countLineChanges, };
75
+ export type { FileEditResult, PreparedItem };
76
+ export { buildMetrics, buildNoop, buildChanged, buildBatchResult };
77
+ export type { RMeta, BatchSection };
78
+ export { genDiff, restoreEndings, toLF, stripBOM };
79
+ export { computeDrift, scanDrift };
80
+ export { trackNoopPayload, clearNoopLoop, noopPayloadKey };
81
+ /**
82
+ * Deep seam: execute the full mutation lifecycle.
83
+ *
84
+ * Owns: applySequence → branch (single/multi × noop/applied) → commit →
85
+ * buildBatchResult → recordServedTruncated → return text.
86
+ *
87
+ * The tool layer (adapter) only validates and resolves the nullable path; all
88
+ * lifecycle branching concentrates here (locality). One interface serves N
89
+ * call sites (leverage). Deleting this module would scatter the lifecycle
90
+ * across every tool — it concentrates (deep).
91
+ */
92
+ export declare function execute(opts: {
93
+ io: FileIO;
94
+ items: PreparedItem[];
95
+ sessionKey: string;
96
+ signal?: AbortSignal;
97
+ exec: ToolExecution;
98
+ sandbox: FsSandboxController;
99
+ sandboxPolicy: SandboxExecutionPolicy | undefined;
100
+ }): Promise<string>;
101
+ /** Apply a single edit — owns read→normalize→loadServed→applyOne→stableRehash→drift. */
102
+ export declare function applySingle(io: FileIO, params: EditParams, cwd: string, opts?: {
103
+ sessionKey?: string;
104
+ signal?: AbortSignal;
105
+ store?: HashStore;
106
+ noPersist?: boolean;
107
+ }): Promise<PipelineResult>;
108
+ /** Apply a per-file sequence (batch's group) — owns the loop + unionRange + counters. */
109
+ export declare function applySequence(io: FileIO, items: PreparedItem[], ctx: {
110
+ sessionKey: string;
111
+ signal?: AbortSignal;
112
+ }): Promise<FileEditResult>;
113
+ /** Commit the transaction — owns persist-undo → write → restore. */
114
+ export declare function commit(opts: {
115
+ io: FileIO;
116
+ files: Array<{
117
+ absolutePath: string;
118
+ displayPath: string;
119
+ originalNormalized: string;
120
+ bom: string;
121
+ originalEnding: import("./edit-diff.js").LineEnding;
122
+ originalHashes: string[];
123
+ result: string;
124
+ }>;
125
+ exec: ToolExecution;
126
+ sandbox: FsSandboxController;
127
+ sandboxPolicy: SandboxExecutionPolicy | undefined;
128
+ signal?: AbortSignal;
129
+ undoUnavailableMessage: (displayPath: string) => string;
130
+ restoreUnwrittenUndos?: boolean;
131
+ }): Promise<void>;
@@ -3,3 +3,32 @@ export declare function noopPayloadKey(absolutePath: string, removeFrom: string,
3
3
  export declare function trackNoopPayload(absolutePath: string, payload: string): number;
4
4
  export declare function clearNoopLoop(absolutePath: string): void;
5
5
  export { NOOP_LOOP_THRESHOLD };
6
+ export interface NoopPolicyInput {
7
+ absolutePath: string;
8
+ removeFrom: string;
9
+ removeTo: string;
10
+ replacementText: string;
11
+ ref: string;
12
+ batch: boolean;
13
+ range: {
14
+ startLine: number;
15
+ endLine: number;
16
+ };
17
+ hashes: string[];
18
+ lines: string[];
19
+ sessionKey: string;
20
+ }
21
+ export type NoopPolicyOutcome = {
22
+ action: "proceed";
23
+ count: number;
24
+ } | {
25
+ action: "warn";
26
+ count: number;
27
+ notice: string;
28
+ } | {
29
+ action: "reject";
30
+ count: number;
31
+ message: string;
32
+ };
33
+ export declare function runNoopPolicySync(input: NoopPolicyInput, count: number): NoopPolicyOutcome;
34
+ export declare function runNoopPolicy(input: NoopPolicyInput): Promise<NoopPolicyOutcome>;
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Debounced preview controller — extracted from buildToolDef so hashline seams
3
+ * stay pure and the debounce invariant is testable.
4
+ * @module dsh-better-edit/preview-controller
5
+ */
6
+ export declare const PREVIEW_DEBOUNCE_MS = 150;
7
+ export interface PreviewHost {
8
+ cwd: string;
9
+ executionStarted: boolean;
10
+ argsComplete: boolean;
11
+ state: RRState;
12
+ invalidate: () => void;
13
+ }
14
+ export type PreviewCompute = (args: unknown, cwd: string) => Promise<RPreview>;
15
+ export interface RPreview {
16
+ error?: string;
17
+ text?: string;
18
+ }
19
+ export interface RRState {
20
+ argsKey?: string;
21
+ preview?: RPreview;
22
+ previewGeneration?: number;
23
+ previewTimer?: ReturnType<typeof setTimeout>;
24
+ }
25
+ export declare function getPreviewInput(_args: unknown): unknown;
26
+ export declare class DebouncedPreview {
27
+ private readonly compute;
28
+ private readonly debounceMs;
29
+ constructor(compute: PreviewCompute, debounceMs?: number);
30
+ renderCall(host: PreviewHost, args: unknown): void;
31
+ cancel(state: RRState): void;
32
+ clearResult(state: RRState): void;
33
+ }
@@ -6,22 +6,22 @@
6
6
  * followed by tight bullets.
7
7
  * @module dsh-better-edit/prompts
8
8
  */
9
- /**
10
- * One tool's guidance: a brief opener plus concise bullets. The `intro` is
11
- * shown above the bullets; it does not duplicate the tool-schema `description`
12
- * (that already reaches the model through the tool catalog).
13
- */
14
9
  export interface ToolGuidance {
15
- /** One-line lead shown above the bullets. */
16
10
  intro: string;
17
- /** Concise bullets; each is self-contained within its section. */
18
11
  lines: readonly string[];
19
12
  }
20
13
  export declare const EDIT_DESCRIPTION: string;
21
14
  export declare const EDIT_GUIDANCE: ToolGuidance;
22
15
  export declare const READ_DESCRIPTION: string;
23
16
  export declare const READ_GUIDANCE: ToolGuidance;
24
- export declare const BATCH_EDIT_DESCRIPTION: string;
25
- export declare const BATCH_EDIT_GUIDANCE: ToolGuidance;
26
17
  export declare const UNDO_DESCRIPTION: string;
27
18
  export declare const UNDO_GUIDANCE: ToolGuidance;
19
+ /**
20
+ * @deprecated batch_edit guidance seam was removed with ADR-0003 (payload contract
21
+ * merged batch_edit into edit's {path, edits:[[hash,hash,text]]} arity). This alias
22
+ * is kept for backwards compat — use EDIT_DESCRIPTION. The guidance system no
23
+ * longer includes tool:batch_edit.
24
+ */
25
+ export declare const BATCH_EDIT_DESCRIPTION: string;
26
+ /** @deprecated see BATCH_EDIT_DESCRIPTION — use EDIT_GUIDANCE */
27
+ export declare const BATCH_EDIT_GUIDANCE: ToolGuidance;
@@ -1,9 +1,10 @@
1
1
  /**
2
- * The shared read-and-serve operation: resolve → read → normalize → render
3
- * the hashline preview → record the served rows → clear the drift marks →
4
- * append the UTF-8 rewrite note. Used by the `read` tool and by the write
5
- * auto-read hook, so the model is always shown fresh anchors the same way no
6
- * matter which tool produced the read.
2
+ * The shared read-and-serve operation — now a thin wrapper over FileView.
3
+ *
4
+ * FileView owns normalize → hash → render → truncate → served selection.
5
+ * This module only adds the persistence seam: recordServed + clearDriftReported
6
+ * + UTF-8 rewrite note. Used by the `read` tool and by the write auto-read
7
+ * hook, so the model is always shown fresh anchors the same way.
7
8
  * @module dsh-better-edit/read-and-serve
8
9
  */
9
10
  import type { FileIO } from "./fs-bridge.js";
@@ -1,21 +1,6 @@
1
1
  /**
2
- * Hash-anchored read rendering: turn normalized text into `HASH│content` rows
3
- * with pagination hints, oversized-line markers, and served-row bookkeeping.
4
- * Ported from pi-hashline-edit-lsz's read tool (pi APIs replaced by local
5
- * helpers).
2
+ * @deprecated — private to FileView seam. Use `from "./file-view.js"` instead.
3
+ * Thin shim re-exporting the read path now owned by FileView.
6
4
  * @module dsh-better-edit/read-render
7
5
  */
8
- import { MAX_HASH_LINES } from './hashline/index.js';
9
- import type { ServedRow } from './hashline/served.js';
10
- import { type TruncationResult } from './truncate.js';
11
- export declare function formatPaginationHint(startLine: number, endLine: number, totalLines: number, nextOffset: number, byteLimit?: number): string;
12
- export declare function fmtReadPreview(text: string, options: {
13
- offset?: number;
14
- limit?: number;
15
- }, precomputedHashes?: string[], path?: string, maxLineBytes?: number, maxTruncLines?: number): Promise<{
16
- text: string;
17
- truncation?: TruncationResult;
18
- nextOffset?: number;
19
- served: ServedRow[];
20
- }>;
21
- export { MAX_HASH_LINES };
6
+ export * from "./file-view.js";
@@ -1,84 +1,5 @@
1
1
  /**
2
- * Served state — what the model has been shown, per session and path.
3
- *
4
- * This is the ONE module that owns the served-state concept: the served-row
5
- * merge invariant, the reported-drift set, and the position-reconstruction
6
- * math used by drift notices. Persistence goes through the hash store's
7
- * served domain API (`hash-store.ts`); the reject-and-serve errors and range
8
- * verification live with the hashline module (`hashline/served.ts`); drift
9
- * computation lives in `drift.ts`. Both import from here.
10
- *
11
- * The API is async-only: every operation loads the per-workspace hash store
12
- * and resolves it through the active workspace context. There is deliberately
13
- * no sync half — the two-vocabulary, every-op-twice surface it produced is
14
- * gone.
2
+ * @deprecated — private to SessionView seam. Use `from "./session-view.js"` instead.
15
3
  * @module dsh-better-edit/served-store
16
4
  */
17
- export type ServedEntry = {
18
- position: number;
19
- hash: string | null;
20
- };
21
- /**
22
- * Map a caller to the served-state session key. dsh passes the live session id
23
- * (`exec.agent.session.id`); callers without one (tests, previews) share a
24
- * process-local fallback so hashline verification never fabricates a session.
25
- */
26
- export declare function sessionKeyFor(sessionId?: string): string;
27
- /**
28
- * Merge served rows into a copy of the stored array. This single helper owns
29
- * the served-merge invariant shared by {@link recordServed} and
30
- * {@link recordServedTruncated}:
31
- *
32
- * - positions are validated before anything is written (invalid rows throw
33
- * and never reach the store);
34
- * - when `truncateTo` is given, positions beyond the file's line count are
35
- * dropped FIRST — a serve of the current file state must never leave a hash
36
- * at an old position beyond the line count, because that stale claim makes
37
- * a chained edit's boundary anchor look ambiguous (`E_RANGE_UNVERIFIED`,
38
- * "served at N positions") instead of verifying cleanly;
39
- * - when `clearFrom` is given, positions at/after the mutation's first
40
- * changed line are re-shaped by the edit, so the model's previous view of
41
- * them is cleared before the diff rows land;
42
- * - trailing never-served markers are trimmed so an empty tail never grows
43
- * the stored array.
44
- *
45
- * Underscore-prefixed: internal, exported only so the invariant has a direct
46
- * test seam.
47
- */
48
- export declare function _mergeServedRows(current: (string | null)[], rows: ServedEntry[], options?: {
49
- truncateTo?: number;
50
- clearFrom?: number;
51
- }): (string | null)[];
52
- /** The served array for one session+path, or `[]` when nothing was served. */
53
- export declare function loadServed(sessionKey: string, path: string): Promise<(string | null)[]>;
54
- /**
55
- * Record served rows for one session+path. Without `lineCount` the rows merge
56
- * into the stored array as-is; with it, the stored array is truncated to the
57
- * file's current line count before the rows land (see
58
- * {@link _mergeServedRows} for why). Failures are logged, never thrown — a
59
- * store problem must not fail the read that produced these rows.
60
- */
61
- export declare function recordServed(sessionKey: string, path: string, rows: ServedEntry[], lineCount?: number): Promise<void>;
62
- /**
63
- * Record post-mutation diff serves against the file's CURRENT length. The
64
- * stored array is truncated to `lineCount` and cleared from `clearFrom`
65
- * (the edit's first changed line) before the diff rows land, so a hash that
66
- * survived into the diff never keeps its pre-edit position claim.
67
- */
68
- export declare function recordServedTruncated(sessionKey: string, path: string, rows: ServedEntry[], lineCount: number, clearFrom?: number): Promise<void>;
69
- /** The hashes already reported as drifted for one session+path. */
70
- export declare function driftReported(sessionKey: string, path: string): Promise<Set<string>>;
71
- /** Mark hashes as already reported as drifted, so later notices skip them. */
72
- export declare function markDriftReported(sessionKey: string, path: string, hashes: string[]): Promise<void>;
73
- /** Clear the reported-drift set for one session+path (a fresh read resets it). */
74
- export declare function clearDriftReported(sessionKey: string, path: string): Promise<void>;
75
- /** Drop every served row and reported-drift mark for one session. */
76
- export declare function wipeServedState(sessionKey: string): Promise<void>;
77
- /** Every served position of a hash in a served array (the E_RANGE_UNVERIFIED probe). */
78
- export declare function servedPositionsOf(served: (string | null)[], hash: string): number[];
79
- /**
80
- * Reconstruct where a drifted hash sits in the current file: map through the
81
- * nearest surviving served neighbor (below, else above), else fall back to
82
- * the served index plus the range's line delta.
83
- */
84
- export declare function currentPositionOfDrifted(served: (string | null)[], currentPositions: Map<string, number>, surviving: Set<string>, servedIndex: number, delta: number): number;
5
+ export * from "./session-view.js";
@@ -0,0 +1,92 @@
1
+ /**
2
+ * SessionView — deep module owning served rows + drift + position reconstruction.
3
+ *
4
+ * Previously split: served-store (merge invariant, persistence via hash-store)
5
+ * and drift (pure computeDrift + IO scanDrift that reads+writes served state).
6
+ * The drift notice both *reads* served state and *writes* it (marking reported
7
+ * + recording drift rows) — a side effect hidden inside a "notice" module.
8
+ *
9
+ * This seam co-locates that invariant. Public surface:
10
+ * view(sessionKey, path) -> {served, reported}
11
+ * recordRead(sessionKey, path, rows, lineCount)
12
+ * recordEdit(sessionKey, path, rows, lineCount, clearFrom)
13
+ * scanDrift(sessionKey, path, resultHashes, resultLines, range) -> notice?
14
+ * servedPositionsOf, currentPositionOfDrifted, _mergeServedRows (via served-store)
15
+ *
16
+ * Explicit Workspace note: loadHashStore(cwd) now requires cwd. The
17
+ * AsyncLocalStorage magic in workspace.ts is @internal — new code should pass
18
+ * cwd explicitly through read-and-serve / edit-pipeline / drift. Forgetting
19
+ * cwd is now a compile error where callers use this seam; legacy callers
20
+ * via served-store still fall back to workspaceCwd() for backwards compat
21
+ * but are marked deprecated.
22
+ *
23
+ * Ownership: This file now OWNS the served-merge invariant
24
+ * (_mergeServedRows), the position-reconstruction math, and the drift
25
+ * computation. Deleting it would scatter the served+drift invariant
26
+ * across 4 files — it concentrates (deep).
27
+ *
28
+ * @module dsh-better-edit/session-view
29
+ */
30
+ import type { ToolExecution } from "@deepseek-ai/dsh-tools";
31
+ import type { ServedRow, ResolvedRange } from "./hashline/served.js";
32
+ import { configDir, hashStorePath, resolveTarget } from "./paths.js";
33
+ export declare function withWorkspace<T>(cwd: string, fn: () => Promise<T>): Promise<T>;
34
+ export declare function workspaceCwd(): string | undefined;
35
+ export declare function sessionKeyFor(sessionId?: string): string;
36
+ export declare function execCwd(exec: ToolExecution): string;
37
+ export declare function execSessionKey(exec: ToolExecution): string;
38
+ export { configDir, hashStorePath, resolveTarget };
39
+ export { loadHashStore, shutdownHashStore, withStore } from "./hash-store.js";
40
+ export type { HashStore } from "./hash-store.js";
41
+ export type ServedEntry = {
42
+ position: number;
43
+ hash: string | null;
44
+ };
45
+ /**
46
+ * Merge served rows into a copy of the stored array. This single helper owns
47
+ * the served-merge invariant shared by recordServed and recordServedTruncated.
48
+ * Eagerly heals orphaned serves: if the same hash is written at a new position
49
+ * the old position is nulled (O(n) scan, no extra I/O). This prevents a
50
+ * partial re-serve from leaving a stale duplicate behind (ADR-0008).
51
+ */
52
+ export declare function _mergeServedRows(current: (string | null)[], rows: ServedEntry[], options?: {
53
+ truncateTo?: number;
54
+ clearFrom?: number;
55
+ }): (string | null)[];
56
+ export declare function loadServed(sessionKey: string, path: string): Promise<(string | null)[]>;
57
+ export declare function recordServed(sessionKey: string, path: string, rows: ServedEntry[], lineCount?: number): Promise<void>;
58
+ export declare function recordServedTruncated(sessionKey: string, path: string, rows: ServedEntry[], lineCount: number, clearFrom?: number): Promise<void>;
59
+ export declare function driftReported(sessionKey: string, path: string): Promise<Set<string>>;
60
+ export declare function markDriftReported(sessionKey: string, path: string, hashes: string[]): Promise<void>;
61
+ export declare function clearDriftReported(sessionKey: string, path: string): Promise<void>;
62
+ export declare function wipeServedState(sessionKey: string): Promise<void>;
63
+ export declare function servedPositionsOf(served: (string | null)[], hash: string): number[];
64
+ export declare function currentPositionOfDrifted(served: (string | null)[], currentPositions: Map<string, number>, surviving: Set<string>, servedIndex: number, delta: number): number;
65
+ export declare const DRIFT_NOTICE_HEADING = "drift:";
66
+ export interface DriftRow extends ServedRow {
67
+ content: string;
68
+ drifted: boolean;
69
+ }
70
+ export interface ComputeDriftInput {
71
+ served: (string | null)[];
72
+ resultHashes: string[];
73
+ resultLines: string[];
74
+ range: ResolvedRange;
75
+ reported: Set<string>;
76
+ cap?: number;
77
+ }
78
+ export interface DriftNoticeResult {
79
+ text: string;
80
+ rows: DriftRow[];
81
+ total: number;
82
+ allAlreadyReported: boolean;
83
+ }
84
+ export declare function computeDrift(input: ComputeDriftInput): DriftNoticeResult | undefined;
85
+ export declare function scanDrift(input: {
86
+ sessionKey: string;
87
+ served: (string | null)[];
88
+ resultHashes: string[];
89
+ resultLines: string[];
90
+ range: ResolvedRange;
91
+ path: string;
92
+ }): Promise<string | undefined>;
@@ -1,23 +1,12 @@
1
1
  /**
2
2
  * The dsh `edit` tool: hash-anchored literal range edits that shadow the
3
- * built-in `edit` on the agent's own scope layer. Registered through the
4
- * agent context so the model-facing contract (remove_from/remove_to hashes,
5
- * served-range verification, reject-and-serve) replaces the built-in one.
3
+ * built-in `edit` on the agent's own scope layer. Now the sole mutation tool
4
+ * (batch_edit removed, ADR-0007): payload is { path: string|null, edits: [[remove_from,remove_to,replacement_text],...] }
5
+ * single-file atomic batch, null path inference via anchors.
6
6
  * @module dsh-better-edit/tool-edit
7
7
  */
8
8
  import type { Context } from "@deepseek-ai/cordis";
9
9
  import type { FileIO } from "./fs-bridge.js";
10
10
  import type { FsSandboxController } from "./sandbox.js";
11
- /**
12
- * Register the hash-anchored `edit` tool on the calling agent's scope.
13
- * @param _rootCtx - host context (logger, lifecycle).
14
- * @param agentCtx - the agent's scoped context; registrations here land on the
15
- * agent's OWN scope layer, shadowing the preset's built-in `edit`.
16
- * @param io - the filesystem bridge (ctx.fs backed in deployment).
17
- * @returns the exact disposer that unregisters the tool.
18
- */
19
11
  export declare function buildEditTool(io: FileIO, sandbox: FsSandboxController): import("@deepseek-ai/dsh-tools").ToolDefinition;
20
- /**
21
- * Register the hashline tool on the calling agent’s scope (own layer).
22
- */
23
12
  export declare function registerEditTool(_rootCtx: Context, agentCtx: Context, io: FileIO, sandbox: FsSandboxController): () => void;
@@ -1,32 +1,6 @@
1
1
  /**
2
- * Truncation utilities for read output (ported from pi-coding-agent's shared
3
- * tool rendering): keep the head of a text payload within line and byte caps,
4
- * never emitting partial lines.
2
+ * @deprecated — private to FileView seam. Use `from "./file-view.js"` instead.
3
+ * Thin shim re-exporting the read path now owned by FileView.
5
4
  * @module dsh-better-edit/truncate
6
5
  */
7
- export declare const DEFAULT_MAX_LINES = 2000;
8
- export declare const DEFAULT_MAX_BYTES: number;
9
- export interface TruncationResult {
10
- content: string;
11
- truncated: boolean;
12
- truncatedBy: 'lines' | 'bytes' | null;
13
- totalLines: number;
14
- totalBytes: number;
15
- outputLines: number;
16
- outputBytes: number;
17
- lastLinePartial: boolean;
18
- firstLineExceedsLimit: boolean;
19
- maxLines: number;
20
- maxBytes: number;
21
- }
22
- /** Format bytes as a human-readable size. */
23
- export declare function formatSize(bytes: number): string;
24
- /**
25
- * Truncate content from the head (keep the first N lines/bytes). Suitable for
26
- * file reads; never returns partial lines. When the first line alone exceeds
27
- * the byte limit the content is emptied with `firstLineExceedsLimit`.
28
- */
29
- export declare function truncateHead(content: string, options?: {
30
- maxLines?: number;
31
- maxBytes?: number;
32
- }): TruncationResult;
6
+ export * from "./file-view.js";