dsh-better-edit 0.2.1 → 0.3.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.
Files changed (44) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +327 -238
  3. package/README.zh.md +44 -16
  4. package/lib/contract.js +40 -1
  5. package/lib/edit-engine.js +4 -4
  6. package/lib/edit-pipeline.js +4 -4
  7. package/lib/file-view.js +63 -0
  8. package/lib/guidance/index.js +8 -0
  9. package/lib/guidance/materialize.js +191 -0
  10. package/lib/guidance/parse.js +80 -0
  11. package/lib/guidance/resolve.js +122 -0
  12. package/lib/guidance.js +6 -279
  13. package/lib/hash-store.js +1 -2
  14. package/lib/hashline/anchor-pipeline.js +23 -0
  15. package/lib/hashline/hash-assign.js +20 -0
  16. package/lib/hashline/index.js +4 -5
  17. package/lib/hashline/resolve.js +5 -0
  18. package/lib/index.js +10 -2
  19. package/lib/mutation.js +58 -0
  20. package/lib/read-and-serve.js +23 -23
  21. package/lib/served-store.js +1 -1
  22. package/lib/session-view.js +34 -0
  23. package/lib/tool-batch-edit.js +9 -10
  24. package/lib/tool-edit.js +9 -11
  25. package/lib/tool-read.js +3 -5
  26. package/lib/tool-undo.js +6 -6
  27. package/lib/types/contract.d.ts +31 -0
  28. package/lib/types/edit-engine.d.ts +2 -2
  29. package/lib/types/edit-pipeline.d.ts +2 -2
  30. package/lib/types/file-view.d.ts +74 -0
  31. package/lib/types/guidance/index.d.ts +8 -0
  32. package/lib/types/guidance/materialize.d.ts +23 -0
  33. package/lib/types/guidance/parse.d.ts +36 -0
  34. package/lib/types/guidance/resolve.d.ts +55 -0
  35. package/lib/types/guidance.d.ts +6 -95
  36. package/lib/types/hashline/anchor-pipeline.d.ts +26 -0
  37. package/lib/types/hashline/hash-assign.d.ts +19 -0
  38. package/lib/types/hashline/index.d.ts +7 -5
  39. package/lib/types/hashline/resolve.d.ts +5 -0
  40. package/lib/types/mutation.d.ts +78 -0
  41. package/lib/types/read-and-serve.d.ts +6 -5
  42. package/lib/types/session-view.d.ts +33 -0
  43. package/lib/write-hook.js +2 -2
  44. package/package.json +2 -10
@@ -15,7 +15,7 @@
15
15
  * @module dsh-better-edit/served-store
16
16
  */
17
17
  import { randomUUID } from "node:crypto";
18
- import { HASH_RE } from "./hashline/alphabet.js";
18
+ import { HASH_RE } from "./hashline/hash-assign.js";
19
19
  import { loadHashStore, withStore } from "./hash-store.js";
20
20
  let fallbackSessionKey;
21
21
  /**
@@ -0,0 +1,34 @@
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
+ * @module dsh-better-edit/session-view
24
+ */
25
+ // --- served state (persistence seam) ---
26
+ export { sessionKeyFor, _mergeServedRows, loadServed, recordServed, recordServedTruncated, driftReported, markDriftReported, clearDriftReported, wipeServedState, servedPositionsOf, currentPositionOfDrifted, } from "./served-store.js";
27
+ // --- drift (pure + IO) ---
28
+ export { computeDrift, scanDrift, DRIFT_NOTICE_HEADING } from "./drift.js";
29
+ // --- explicit workspace (re-export for seam visibility) ---
30
+ export { withWorkspace, workspaceCwd } from "./workspace.js";
31
+ export { execCwd, execSessionKey } from "./dsh-context.js";
32
+ export { configDir, hashStorePath, resolveTarget } from "./paths.js";
33
+ // Re-export hash-store explicit-cwd API as part of this seam's persistence note
34
+ export { loadHashStore, shutdownHashStore, withStore } from "./hash-store.js";
@@ -9,15 +9,14 @@
9
9
  */
10
10
  import { defineTool } from "@deepseek-ai/dsh-tools";
11
11
  import { abortIf, isRec, normalizeFilePath, splitLines, } from "./utils.js";
12
- import { assertBatchEditRequest, } from "./contract.js";
13
- import { normReq } from "./edit-normalize.js";
14
- import { persistUndoAndWrite, resolveMissingPath, runFileEdits, } from "./edit-engine.js";
15
- import { buildBatchResult } from "./edit-response.js";
16
- import { recordServedTruncated } from "./served-store.js";
12
+ import { assertBatchEditRequest, normalizeRequest as normReq, } from "./contract.js";
13
+ import { commit, resolveMissingPath, applySequence, } from "./mutation.js";
14
+ import { buildBatchResult } from "./mutation.js";
15
+ import { recordServedTruncated } from "./session-view.js";
17
16
  import { BATCH_EDIT_DESCRIPTION } from "./prompts.js";
18
- import { pathSchema, removeFromSchema, removeToSchema, replacementTextSchema, } from "./schema.js";
19
- import { execCwd, execSessionKey } from "./dsh-context.js";
20
- import { withWorkspace } from "./workspace.js";
17
+ import { pathSchema, removeFromSchema, removeToSchema, replacementTextSchema, } from "./contract.js";
18
+ import { execCwd, execSessionKey } from "./session-view.js";
19
+ import { withWorkspace } from "./session-view.js";
21
20
  async function prepareItems(io, params, cwd, signal) {
22
21
  const items = [];
23
22
  for (let index = 0; index < params.edits.length; index++) {
@@ -141,12 +140,12 @@ export function buildBatchEditTool(io, sandbox) {
141
140
  const processed = [];
142
141
  for (const groupItems of groups.values()) {
143
142
  abortIf(signal);
144
- processed.push(await runFileEdits(io, groupItems, {
143
+ processed.push(await applySequence(io, groupItems, {
145
144
  signal,
146
145
  sessionKey,
147
146
  }));
148
147
  }
149
- await persistUndoAndWrite({
148
+ await commit({
150
149
  io,
151
150
  files: processed
152
151
  .filter((file) => file.appliedCount > 0)
package/lib/tool-edit.js CHANGED
@@ -6,18 +6,16 @@
6
6
  * @module dsh-better-edit/tool-edit
7
7
  */
8
8
  import { defineTool } from "@deepseek-ai/dsh-tools";
9
- import { normReq } from "./edit-normalize.js";
9
+ import { normalizeRequest as normReq, assertEditRequest, pathSchema, removeFromSchema, removeToSchema, replacementTextSchema } from "./contract.js";
10
10
  import { abortIf, isRec, splitLines } from "./utils.js";
11
- import { assertEditRequest } from "./contract.js";
12
- import { enforceNoopLoop, persistUndoAndWrite, resolveMissingPath, } from "./edit-engine.js";
13
- import { execPipeline, snapshotIdFor, } from "./edit-pipeline.js";
11
+ import { enforceNoopLoop, commit, resolveMissingPath, } from "./mutation.js";
12
+ import { applySingle, snapshotIdFor, } from "./mutation.js";
14
13
  import { clearNoopLoop, noopPayloadKey, trackNoopPayload, } from "./noop-guard.js";
15
- import { buildNoop, buildChanged } from "./edit-response.js";
16
- import { recordServedTruncated } from "./served-store.js";
14
+ import { buildNoop, buildChanged } from "./mutation.js";
15
+ import { recordServedTruncated } from "./session-view.js";
17
16
  import { EDIT_DESCRIPTION } from "./prompts.js";
18
- import { pathSchema, removeFromSchema, removeToSchema, replacementTextSchema, } from "./schema.js";
19
- import { execCwd, execSessionKey } from "./dsh-context.js";
20
- import { withWorkspace } from "./workspace.js";
17
+ import { execCwd, execSessionKey } from "./session-view.js";
18
+ import { withWorkspace } from "./session-view.js";
21
19
  /**
22
20
  * Register the hash-anchored `edit` tool on the calling agent's scope.
23
21
  * @param _rootCtx - host context (logger, lifecycle).
@@ -58,7 +56,7 @@ export function buildEditTool(io, sandbox) {
58
56
  const normalizedParams = canonical;
59
57
  const path = normalizedParams.path;
60
58
  abortIf(signal);
61
- const pipeline = await execPipeline(io, normalizedParams, cwd, {
59
+ const pipeline = await applySingle(io, normalizedParams, cwd, {
62
60
  signal,
63
61
  sessionKey,
64
62
  });
@@ -105,7 +103,7 @@ export function buildEditTool(io, sandbox) {
105
103
  warnings.push("Non-UTF-8 bytes were shown as U+FFFD; this edit rewrote the file as UTF-8.");
106
104
  }
107
105
  abortIf(signal);
108
- await persistUndoAndWrite({
106
+ await commit({
109
107
  io,
110
108
  files: [
111
109
  {
package/lib/tool-read.js CHANGED
@@ -6,13 +6,11 @@
6
6
  * @module dsh-better-edit/tool-read
7
7
  */
8
8
  import { defineTool } from "@deepseek-ai/dsh-tools";
9
- import { normReq } from "./edit-normalize.js";
10
- import { assertReadRequest } from "./contract.js";
9
+ import { normalizeRequest as normReq, assertReadRequest, pathSchema } from "./contract.js";
11
10
  import { readAndServe } from "./read-and-serve.js";
12
11
  import { READ_DESCRIPTION } from "./prompts.js";
13
- import { pathSchema } from "./schema.js";
14
- import { execCwd, execSessionKey } from "./dsh-context.js";
15
- import { withWorkspace } from "./workspace.js";
12
+ import { execCwd, execSessionKey } from "./session-view.js";
13
+ import { withWorkspace } from "./session-view.js";
16
14
  /**
17
15
  * Register the hash-anchored `read` tool on the calling agent's scope.
18
16
  * @param _rootCtx - host context.
package/lib/tool-undo.js CHANGED
@@ -8,15 +8,15 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
8
8
  import { toLF, stripBOM, genDiff, restoreEndings } from "./edit-diff.js";
9
9
  import { cntDiff, splitLines } from "./utils.js";
10
10
  import { assertUndoRequest } from "./contract.js";
11
- import { normReq } from "./edit-normalize.js";
11
+ import { normalizeRequest as normReq } from "./contract.js";
12
12
  import { upsertSnapshotFor } from "./hash-store.js";
13
- import { contentChecksum } from "./hashline/hasher.js";
14
- import { lineHashes, changedRange } from "./hashline/index.js";
13
+ import { contentChecksum, lineHashes } from "./hashline/hash-assign.js";
14
+ import { changedRange } from "./hashline/anchor-pipeline.js";
15
15
  import { getUndo, clearUndo } from "./undo-edit.js";
16
- import { recordServedTruncated } from "./served-store.js";
16
+ import { recordServedTruncated } from "./session-view.js";
17
17
  import { UNDO_DESCRIPTION } from "./prompts.js";
18
- import { execCwd, execSessionKey } from "./dsh-context.js";
19
- import { withWorkspace } from "./workspace.js";
18
+ import { execCwd, execSessionKey } from "./session-view.js";
19
+ import { withWorkspace } from "./session-view.js";
20
20
  /**
21
21
  * Register the `undo_last_edit` tool on the calling agent's scope.
22
22
  * @param _rootCtx - host context.
@@ -33,7 +33,38 @@ export interface ReadParams {
33
33
  export interface UndoParams {
34
34
  path: string;
35
35
  }
36
+ /**
37
+ * Normalize `file_path` → `path` alias on the request record. Returns the
38
+ * input unchanged when not a record; otherwise returns a shallow copy with
39
+ * the alias applied so callers never mutate the original `args` object.
40
+ */
41
+ export declare function normalizeRequest(input: unknown): unknown;
42
+ /** @deprecated use normalizeRequest — kept as alias for migration */
43
+ export declare const normReq: typeof normalizeRequest;
36
44
  export declare function assertEditRequest(request: unknown): asserts request is EditParams;
37
45
  export declare function assertBatchEditRequest(request: unknown): asserts request is BatchEditParams;
38
46
  export declare function assertReadRequest(request: unknown): asserts request is ReadParams;
39
47
  export declare function assertUndoRequest(request: unknown): asserts request is UndoParams;
48
+ /**
49
+ * Shared model-facing parameter schemas for the hashline tools, expressed in
50
+ * the dsh schema DSL (not TypeBox). `path` is deliberately NOT `required` at
51
+ * the schema level: the tools accept the built-in `file_path` spelling too
52
+ * (the implicit parameter root stays open), and enforce path presence in
53
+ * `assertEditRequest` after `normalizeFilePath` aliasing.
54
+ */
55
+ export declare const replacementTextSchema: {
56
+ readonly type: "string";
57
+ readonly description: "Replacement text as a single string with \\n line separators; every \\n separates lines, so a trailing \\n adds a final empty line. Mirror the removed lines exactly, blank lines included. A replacement that is only blank lines is written as one \\n per blank line. Use \"\" to delete the range.";
58
+ };
59
+ export declare const removeFromSchema: {
60
+ readonly type: "string";
61
+ readonly description: "Bare 3-char HASH only (e.g. \"aB3\") — copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the FIRST line to remove (inclusive)";
62
+ };
63
+ export declare const removeToSchema: {
64
+ readonly type: "string";
65
+ readonly description: "Bare 3-char HASH only (e.g. \"aB3\") — copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the LAST line to remove (inclusive)";
66
+ };
67
+ export declare const pathSchema: {
68
+ readonly type: "string";
69
+ readonly description: "Path to edit. Required — always provide it explicitly; it is only auto-resolved from the anchors as a fallback when omitted by mistake.";
70
+ };
@@ -15,8 +15,8 @@ import type { SandboxExecutionPolicy } from "@deepseek-ai/dsh-sandbox";
15
15
  import type { FileIO } from "./fs-bridge.js";
16
16
  import type { HashStore } from "./hash-store.js";
17
17
  import type { LineEnding } from "./edit-diff.js";
18
- import { type HEdit, type NEdit } from "./hashline/index.js";
19
- import { type ResolvedRange, type ServeRecordPolicy, type ServedRow } from "./hashline/served.js";
18
+ import { type HEdit, type NEdit } from "./hashline/anchor-pipeline.js";
19
+ import { type ResolvedRange, type ServeRecordPolicy, type ServedRow } from "./hashline/anchor-pipeline.js";
20
20
  import type { FsSandboxController } from "./sandbox.js";
21
21
  export interface PreparedItem {
22
22
  index: number;
@@ -12,8 +12,8 @@
12
12
  import type { HashStore } from './hash-store.js';
13
13
  import type { FileIO } from './fs-bridge.js';
14
14
  import type { LineEnding } from './edit-diff.js';
15
- import { type NEdit } from './hashline/index.js';
16
- import type { ResolvedRange } from './hashline/served.js';
15
+ import { type NEdit } from './hashline/anchor-pipeline.js';
16
+ import type { ResolvedRange } from './hashline/anchor-pipeline.js';
17
17
  import type { EditParams } from './contract.js';
18
18
  export interface PipelineResult {
19
19
  path: string;
@@ -0,0 +1,74 @@
1
+ /**
2
+ * FileView — deep module owning "what the model sees".
3
+ *
4
+ * Single seam for normalize → hash → render → truncate → served-row
5
+ * selection. The read path was 6 shallow modules for one concept:
6
+ * `tool-read → read-and-serve → file-reader → read-render → fs-bridge
7
+ * → file-kind/validation/truncate`, each with interface ≈ implementation.
8
+ *
9
+ * Now: one file to understand reads. The private helpers
10
+ * (`file-reader`, `read-render`, `truncate`, `file-kind`, `validation`)
11
+ * are *private to this seam* — do not import them directly outside this
12
+ * module. Import from `file-view` instead. `fs-bridge` stays as the IO seam.
13
+ *
14
+ * Two surfaces:
15
+ * - `preview` (pure, no IO) — tested without filesystem
16
+ * - `readView` (IO) — read + normalize + render + truncate + hashes
17
+ *
18
+ * The emergent interaction (MAX_HASH_LINES vs MAX_READ_LINE_BYTES vs
19
+ * truncation, partial serve on oversized lines) now lives in one module
20
+ * and is one test surface.
21
+ *
22
+ * @module dsh-better-edit/file-view
23
+ */
24
+ import { MAX_HASH_LINES } from "./read-render.js";
25
+ import type { FileIO } from "./fs-bridge.js";
26
+ import type { ServedRow } from "./hashline/served.js";
27
+ import type { TruncationResult } from "./truncate.js";
28
+ import type { LineEnding } from "./edit-diff.js";
29
+ /** What the model sees for one read — the deep seam's core type. */
30
+ export interface FileView {
31
+ /** Model-facing preview text (hashline rows + pagination/oversized notes). */
32
+ text: string;
33
+ /** Per-line hashes for the whole file (canonical, stored deterministically). */
34
+ hashes: string[];
35
+ /** Rows actually shown to the model (empty when nothing shown, e.g. empty file edge). */
36
+ served: ServedRow[];
37
+ /** Canonical absolute path (resolved against cwd). */
38
+ absolutePath: string;
39
+ /** Truncation meta when preview was capped. */
40
+ truncation?: TruncationResult;
41
+ /** Next pagination offset when preview was paginated/truncated. */
42
+ nextOffset?: number;
43
+ /** Whether the raw file had non-UTF-8 bytes (shown as U+FFFD, rewritten on edit). */
44
+ hadUtf8DecodeErrors: boolean;
45
+ /** Stripped BOM if present (for round-trip fidelity on edit/write). */
46
+ bom: string;
47
+ /** Original line ending (for round-trip fidelity). */
48
+ originalEnding: LineEnding;
49
+ /** Normalized LF content (internal, but useful for callers that need content + hashes). */
50
+ normalized: string;
51
+ }
52
+ export interface PreviewOpts {
53
+ offset?: number;
54
+ limit?: number;
55
+ }
56
+ export interface ReadViewOpts extends PreviewOpts {
57
+ signal?: AbortSignal;
58
+ }
59
+ /**
60
+ * Pure rendering without IO — tested without filesystem.
61
+ * Wraps `fmtReadPreview` so callers have one place to render.
62
+ */
63
+ export declare function preview(content: string, hashes: string[], opts?: PreviewOpts, absolutePath?: string): Promise<{
64
+ text: string;
65
+ served: ServedRow[];
66
+ truncation?: TruncationResult;
67
+ nextOffset?: number;
68
+ }>;
69
+ /**
70
+ * IO version: read + normalize + render + truncate + hashes.
71
+ * Single place that decides `served[]` — no emergent partial-serve.
72
+ */
73
+ export declare function readView(io: FileIO, path: string, cwd: string, opts?: ReadViewOpts): Promise<FileView>;
74
+ export { MAX_HASH_LINES };
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Barrel for guidance sub-seams — parse (pure), resolve (IO-light), materialize (IO-heavy).
3
+ * Re-exported via `src/guidance.ts` so existing `from "./guidance.js"` imports keep working.
4
+ * @module dsh-better-edit/guidance/index
5
+ */
6
+ export * from "./parse.js";
7
+ export * from "./resolve.js";
8
+ export * from "./materialize.js";
@@ -0,0 +1,23 @@
1
+ /** The presets shipped by the harness, each seeded with editable guidance. */
2
+ export declare const DEFAULT_PRESETS: readonly string[];
3
+ /**
4
+ * The root README: the per-preset customization convention users see in the
5
+ * plugin home.
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`, `code`,\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- `batch_edit.md` -> `tool:batch_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 at session-start, 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: 150\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`code`\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- `batch_edit.md` -> `tool:batch_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 \u7684 session-start \u65F6\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: 150\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
+ /**
10
+ * Materialize per-preset guidance directories in the plugin home.
11
+ *
12
+ * For each of `DEFAULT_PRESETS` creates `<preset>/{read,edit,batch_edit,
13
+ * undo_last_edit}.md` rendered from the compiled defaults (with order
14
+ * front-matter), plus a root `README.md` documenting the convention.
15
+ * Idempotent: a user-edited file survives repeated calls. A blank override file
16
+ * (whitespace-only body, no fence) is re-seeded with the current compiled
17
+ * default; malformed, non-blank, and deliberate-blank (valid-fence) files are
18
+ * never touched. Custom preset directories present on disk are scanned the same
19
+ * way but never fabricated. Missing directories are created on demand (shipped
20
+ * presets only), and shipped files are written exclusively so two concurrent
21
+ * first runs race safely.
22
+ */
23
+ export declare function ensurePresetGuidance(homeDir: string): Promise<void>;
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Pure parser for per-preset guidance override files.
3
+ *
4
+ * Only a leading `---` fence whose lines are empty or `order: <integer>` is
5
+ * accepted. This module has zero IO — exhaustive unit testing without a temp
6
+ * home.
7
+ * @module dsh-better-edit/guidance/parse
8
+ */
9
+ /** The parsed content of one override file. */
10
+ export interface ParsedSection {
11
+ /** Front-matter `order`, when present and valid. */
12
+ order?: number;
13
+ /** The section text: the file body, or the whole file when no fence is present. */
14
+ text: string;
15
+ /** True when a leading `---` fence is present but does not parse (fast fail). */
16
+ malformed?: boolean;
17
+ /** Human-readable parse reason, present only when `malformed` is true. */
18
+ reason?: string;
19
+ }
20
+ /**
21
+ * Parse an override file. Only a leading `---` fence whose lines are empty or
22
+ * `order: <integer>` is accepted. A leading `---` that does not parse (no
23
+ * closing fence, unknown key, non-integer value) is a malformed override;
24
+ * anything else is pure prose (the whole file as text).
25
+ */
26
+ export declare function parseSectionFile(content: string): ParsedSection;
27
+ /**
28
+ * True when an override file is blank: whitespace-only body and NO front-matter
29
+ * fence (the "I want the default" case). The single source of truth for whether
30
+ * a boot-time materialization pass should re-seed a file. False for prose with
31
+ * content, for any valid fence (including a keyless/empty one — a deliberate
32
+ * blank), and for malformed files.
33
+ */
34
+ export declare function isBlankOverride(content: string): boolean;
35
+ /** True when an override file opens with a leading `---` fence that is malformed. */
36
+ export declare function isMalformedOverride(content: string): boolean;
@@ -0,0 +1,55 @@
1
+ /** One overridable tool section. */
2
+ export interface GuidanceSection {
3
+ /** Registry section name, e.g. `tool:edit`. */
4
+ name: string;
5
+ /** Override file name inside a preset directory, e.g. `edit.md`. */
6
+ file: string;
7
+ /** Order used when the override file carries no front-matter `order`. */
8
+ defaultOrder: number;
9
+ /** The compiled default text, byte-identical to today's inline rendering. */
10
+ renderDefault(): string;
11
+ }
12
+ /** The four sections, in default-order sequence. */
13
+ export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
14
+ /** Render the compiled default text for one section. */
15
+ export declare function renderSectionDefault(name: string): string;
16
+ /** Options for resolving one section's guidance. */
17
+ export interface ResolveGuidanceOptions {
18
+ /** Agent preset id, or undefined to skip the preset layer. */
19
+ presetId?: string;
20
+ /** Plugin shared home directory (`$DSH_HOME/plugins/dsh-better-edit`). */
21
+ homeDir: string;
22
+ }
23
+ /** The resolved text and order for one section. */
24
+ export interface GuidanceResolution {
25
+ order: number;
26
+ text: string;
27
+ /** Set when the override file was malformed and the compiled default was used. */
28
+ malformed?: {
29
+ file: string;
30
+ reason: string;
31
+ };
32
+ }
33
+ /**
34
+ * Resolve one section's guidance: the first override file that exists wins,
35
+ * falling back to the compiled default. A missing or blank file (ENOENT, or
36
+ * whitespace-only with no fence) advances the chain; a malformed file resolves
37
+ * to the compiled default and reports itself; any other read error propagates.
38
+ */
39
+ export declare function resolveSection(name: string, options: ResolveGuidanceOptions): Promise<GuidanceResolution>;
40
+ /** The resolved configuration of one section, ready for the systemPrompt registry. */
41
+ export interface SectionOverride {
42
+ name: string;
43
+ order: number;
44
+ text: string;
45
+ /** Set when the override file was malformed and the compiled default was used. */
46
+ malformed?: {
47
+ file: string;
48
+ reason: string;
49
+ };
50
+ }
51
+ /**
52
+ * Resolve all four sections for a preset. `presetId === undefined` skips the
53
+ * `<preset>/` layer and resolves straight to the compiled defaults.
54
+ */
55
+ export declare function composeSections(presetId: string | undefined, homeDir: string): Promise<SectionOverride[]>;
@@ -1,98 +1,9 @@
1
1
  /**
2
- * Per-preset guidance overrides for the hashline tool sections.
3
- *
4
- * Each of the four `tool:*` prompt sections the plugin registers has a
5
- * compiled default rendered from `prompts.ts` (byte-identical to the inline
6
- * rendering `src/index.ts` uses today). A user can override any section's text
7
- * and `order` with a plain markdown file keyed by agent preset: the override
8
- * files live in the plugin's shared home (`$DSH_HOME/plugins/dsh-better-edit`,
9
- * never the workspace store) and are resolved per section as
10
- * `<preset>/<section>.md` → compiled default.
11
- *
12
- * An override file is pure prose unless it opens with a valid YAML front-matter
13
- * fence carrying only an `order` key (`---` / `order: N` / `---`); anything
14
- * else — a missing closing fence, a non-integer `order`, an unknown key —
15
- * degrades the WHOLE file to prose so the mistake stays visible in the
16
- * rendered section.
17
- *
18
- * Resolution is pure: no cordis services, no harness wiring. The installer
19
- * ticket reads the resolved sections once per agent at session-start;
20
- * nothing here watches or caches files.
2
+ * Backwards-compat barrel — the real seams live in `src/guidance/`:
3
+ * `parse.ts` (pure), `resolve.ts` (IO-light), `materialize.ts` (IO-heavy).
4
+ * Keeping this file means existing `from "./guidance.js"` imports keep working.
21
5
  * @module dsh-better-edit/guidance
22
6
  */
23
- /** The presets shipped by the harness, each seeded with editable guidance. */
24
- export declare const DEFAULT_PRESETS: readonly string[];
25
- /** One overridable tool section. */
26
- export interface GuidanceSection {
27
- /** Registry section name, e.g. `tool:edit`. */
28
- name: string;
29
- /** Override file name inside a preset directory, e.g. `edit.md`. */
30
- file: string;
31
- /** Order used when the override file carries no front-matter `order`. */
32
- defaultOrder: number;
33
- /** The compiled default text, byte-identical to today's inline rendering. */
34
- renderDefault(): string;
35
- }
36
- /** The four sections, in default-order sequence. */
37
- export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
38
- /** Render the compiled default text for one section. */
39
- export declare function renderSectionDefault(name: string): string;
40
- /** The parsed content of one override file. */
41
- export interface ParsedSection {
42
- /** Front-matter `order`, when present and valid. */
43
- order?: number;
44
- /** The section text: the file body, or the whole file when front-matter is absent or malformed. */
45
- text: string;
46
- }
47
- /**
48
- * Parse an override file. Only a leading `---` fence whose lines are empty or
49
- * `order: <integer>` is accepted; every other shape (no fence, no closing
50
- * fence, unknown key, non-integer value) yields the whole file as prose.
51
- */
52
- export declare function parseSectionFile(content: string): ParsedSection;
53
- /** Options for resolving one section's guidance. */
54
- export interface ResolveGuidanceOptions {
55
- /** Agent preset id, or undefined to skip the preset layer. */
56
- presetId?: string;
57
- /** Plugin shared home directory (`$DSH_HOME/plugins/dsh-better-edit`). */
58
- homeDir: string;
59
- }
60
- /** The resolved text and order for one section. */
61
- export interface GuidanceResolution {
62
- order: number;
63
- text: string;
64
- }
65
- /**
66
- * Resolve one section's guidance: the first override file that exists wins,
67
- * falling back to the compiled default. A missing file (ENOENT) advances the
68
- * chain; any other read error propagates.
69
- */
70
- export declare function resolveSection(name: string, options: ResolveGuidanceOptions): Promise<GuidanceResolution>;
71
- /** The resolved configuration of one section, ready for the systemPrompt registry. */
72
- export interface SectionOverride {
73
- name: string;
74
- order: number;
75
- text: string;
76
- }
77
- /**
78
- * Resolve all four sections for a preset. `presetId === undefined` skips the
79
- * `<preset>/` layer and resolves straight to the compiled defaults.
80
- */
81
- export declare function composeSections(presetId: string | undefined, homeDir: string): Promise<SectionOverride[]>;
82
- /**
83
- * The root README: the per-preset customization convention users see in the
84
- * plugin home.
85
- */
86
- 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`, `code`,\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- `batch_edit.md` -> `tool:batch_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 at session-start, 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: 150\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";
87
- 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`code`\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- `batch_edit.md` -> `tool:batch_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 \u7684 session-start \u65F6\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: 150\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";
88
- /**
89
- * Materialize per-preset guidance directories in the plugin home.
90
- *
91
- * For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
92
- * undo_last_edit}.md\` rendered from the compiled defaults (with order
93
- * front-matter), plus a root \`README.md\` documenting the convention.
94
- * Idempotent: existing files are never rewritten (a user-edited file survives
95
- * repeated calls) and missing directories are created on demand. Each file is
96
- * written exclusively, so two concurrent first runs race safely.
97
- */
98
- export declare function ensurePresetGuidance(homeDir: string): Promise<void>;
7
+ export * from "./guidance/parse.js";
8
+ export * from "./guidance/resolve.js";
9
+ export * from "./guidance/materialize.js";
@@ -0,0 +1,26 @@
1
+ /**
2
+ * AnchorPipeline — deep module owning the anchor autofix chain.
3
+ *
4
+ * Single ordering invariant (private):
5
+ * swapReversed → stripBare → stripDiff → valEdit → boundaryDups splice → valEdit → verifyServed → resToSpan
6
+ *
7
+ * Detection (valEdit → boundaryDups[]) and correction (splice + second valEdit)
8
+ * were split across resolve.ts / apply.ts with an implicit coupling.
9
+ * This seam co-locates that invariant. Public surface is two functions:
10
+ * resEdit — pre-validation (tool-layer, no file state)
11
+ * applyEdit — full pipeline (file + hashes + served verification)
12
+ *
13
+ * Private to this seam (not re-exported): stripBarePrefixes, stripDiffPrefixes,
14
+ * swapReversedRanges, valEdit, boundaryDups helpers, warnUnicodeEsc, findNewEdge.
15
+ * They remain exported from resolve.ts for backwards compat but are marked
16
+ * @internal and should be imported via this module only.
17
+ *
18
+ * @module dsh-better-edit/hashline/anchor-pipeline
19
+ */
20
+ export { resEdit } from "./resolve.js";
21
+ export type { HEdit, HTEdit, NEdit, BDup, AutoFix } from "./resolve.js";
22
+ export { applyEdit, fmtRegion, changedRange, buildIdx } from "./apply.js";
23
+ export type { Anchor } from "./parse.js";
24
+ export { parseHashRef, parseText } from "./parse.js";
25
+ export { ServedRejectionError, AnchorMismatchError, isServedRejection, isAnchorMismatch, verifyServedRange, buildRangeEcho, fmtServedRows, recordEchoServes, } from "./served.js";
26
+ export type { ServedRow, ResolvedRange, ServedCode, ServeRecordPolicy, } from "./served.js";
@@ -0,0 +1,19 @@
1
+ /**
2
+ * HashAssign — deep module owning hash assignment.
3
+ *
4
+ * Owns the `HASH_SPACE = 62^3` allocation invariant: every line of a file
5
+ * gets a unique 3-char anchor derived from canonicalized content via xxHash
6
+ * + probe-stride allocation. The triad `alphabet + hasher + pure + hash`
7
+ * is interdependent; this seam hides that coupling.
8
+ *
9
+ * Private internals (not re-exported as public API): ALPH, idxToHash/hashAt,
10
+ * nextZeroBit/assignHash, getBit/setBit, hashToIndex/nearestNew, xxh32 internals.
11
+ * Callers use the deep interface below — one test surface for determinism +
12
+ * stable mapping + persistence.
13
+ *
14
+ * @module dsh-better-edit/hashline/hash-assign
15
+ */
16
+ export { ANCHOR_LEN, HASH_SEP, HASH_SPACE, HASH_PROBE_STRIDE, MAX_HASH_LINES, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE, HL_BARE_PREFIX_RE, ALPH_RE, HASH_CLASS, HASH_LEN, canon, lineHashesPure, mapStableHashes, initHasher, } from "./pure.js";
17
+ export { HASH_RE } from "./alphabet.js";
18
+ export { contentChecksum } from "./hasher.js";
19
+ export { lineHashes } from "./hash.js";
@@ -1,5 +1,7 @@
1
- export { ANCHOR_LEN, HASH_SEP, HASH_SPACE, HASH_PROBE_STRIDE, MAX_HASH_LINES, lineHashesPure, initHasher, canon, } from "./pure.js";
2
- export { lineHashes } from "./hash.js";
3
- export { parseHashRef, parseText, type Anchor, } from "./parse.js";
4
- export { type HEdit, type HTEdit, type NEdit, resEdit, } from "./resolve.js";
5
- export { applyEdit, fmtRegion, changedRange, } from "./apply.js";
1
+ export { ANCHOR_LEN, HASH_SEP, HASH_SPACE, HASH_PROBE_STRIDE, MAX_HASH_LINES, HASH_LEN, HASH_CLASS, HASH_RE, ALPH_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE, HL_BARE_PREFIX_RE, canon, lineHashesPure, mapStableHashes, initHasher, lineHashes, contentChecksum, } from "./hash-assign.js";
2
+ export { parseHashRef, parseText } from "./parse.js";
3
+ export type { Anchor } from "./parse.js";
4
+ export { resEdit } from "./anchor-pipeline.js";
5
+ export type { HEdit, HTEdit, NEdit, BDup, AutoFix } from "./anchor-pipeline.js";
6
+ export { applyEdit, fmtRegion, changedRange, buildIdx, ServedRejectionError, AnchorMismatchError, isServedRejection, isAnchorMismatch, verifyServedRange, buildRangeEcho, fmtServedRows, } from "./anchor-pipeline.js";
7
+ export type { ServedRow, ResolvedRange, ServedCode, } from "./anchor-pipeline.js";
@@ -43,13 +43,18 @@ export declare function fmtMismatchWithServes(mismatches: HMismatch[], fileLines
43
43
  };
44
44
  export declare function resEdit(edit: HTEdit, warnings?: string[]): HEdit;
45
45
  declare function warnUnicodeEsc(edit: HEdit, warnings: string[]): void;
46
+ /** @internal — private to anchor-pipeline seam; do not import directly, use anchor-pipeline.ts */
46
47
  export declare function stripBarePrefixes(edit: HEdit, fileHashes: string[], warnings: string[]): HEdit;
48
+ /** @internal — private to anchor-pipeline seam */
47
49
  export declare function stripDiffPrefixes(edit: HEdit, warnings: string[]): HEdit;
50
+ /** @internal — private to anchor-pipeline seam */
48
51
  export declare function swapReversedRanges(edit: HEdit, fileHashes: string[], warnings: string[]): HEdit;
52
+ /** @internal — private to anchor-pipeline seam */
49
53
  export declare function findNewEdge(contentLines: string[], rangeLines: string[], fromEnd: boolean): {
50
54
  index: number;
51
55
  line: string;
52
56
  } | undefined;
57
+ /** @internal — private to anchor-pipeline seam: detection + boundaryDups belongs to AnchorPipeline ordering */
53
58
  export declare function valEdit(edit: HEdit, fileLines: string[], fileHashes: string[], warnings: string[], signal: AbortSignal | undefined): {
54
59
  resolved: RHEdit | undefined;
55
60
  mismatches: HMismatch[];