dsh-better-edit 0.2.1 → 0.2.2

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 CHANGED
@@ -6,6 +6,12 @@ Entries link to the originating spec issue in [pi-hashline-edit-lsz](https://git
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.2.2] - 2026-08-19
10
+
11
+ ### Added
12
+
13
+ - Guidance reset & restore defaults (issue #17): emptying or deleting an override file — or deleting its whole `<preset>/` directory — restores that section's compiled default guidance and order: the default renders at session-start and the file re-seeds at next boot (shipped presets; a deleted custom-preset override stays absent). A whitespace-only file with no front-matter fence means "I want the default"; any well-formed fence (even keyless, even an empty body) is a deliberate-intent signal and is never reset. Malformed fences now fast-fail instead of degrading to prose: a missing closing `---`, a non-integer `order`, or an unknown key rejects the file — the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
14
+
9
15
  ## [0.2.1] - 2026-08-18
10
16
 
11
17
  ### Added
package/README.md CHANGED
@@ -5,8 +5,8 @@
5
5
  <h1 align="center">dsh-better-edit</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>Hash-anchored edit tools for DeepSeek Harness.<br>
9
- Edit by content address — not by line numbers, not by string replacement. Fewer tokens. More attention for real work. Zero misapplied edits.</strong>
8
+ <strong>A better edit tool for DeepSeek Harness<br>
9
+ Powered by hash‑anchored positioning — not by line numbers, not by string replacement, fewer tokens, more context space for real work.</strong>
10
10
  </p>
11
11
 
12
12
  <p align="center">
@@ -59,8 +59,9 @@ Not for one-line touch-ups (near parity) or new files (`write`). It pays off in
59
59
  ### Install
60
60
 
61
61
  ```sh
62
- dsh plugin --profile <name> add dsh-better-edit # from npm
63
- dsh plugin --profile <name> add /path/to/dsh-better-edit # from a local checkout
62
+ npx @deepseek-ai/dsh plugin --profile web add github:Rianico/dsh-better-edit # from github
63
+ npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # from npm
64
+ npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # from a local checkout
64
65
  ```
65
66
 
66
67
  The profile's next session runs with the hashline tools installed. To verify the layer is active:
@@ -125,7 +126,8 @@ On first boot the plugin seeds the four shipped presets — `standard/`, `code/`
125
126
  `minimal/`, `cordis/` — each with the compiled guidance as editable files (plus
126
127
  `order` front-matter), so every preset's guidance starts editable rather than
127
128
  blank. A `README.md` at the plugin-home root documents the scheme. Files are
128
- seeded once and never rewritten, so your edits survive. A preset directory may
129
+ seeded once and never rewritten, so your edits survive — a reset is the one
130
+ exception (see *Reset / restore defaults* below). A preset directory may
129
131
  hold only the sections you want to override — the rest fall through to the
130
132
  compiled defaults.
131
133
 
@@ -148,6 +150,20 @@ dir to its name. A deployment without the `agentPresets` service (no preset
148
150
  roster) keeps the compiled defaults and never touches these files; presets are
149
151
  never required.
150
152
 
153
+ ### Reset / restore defaults
154
+
155
+ Emptying or deleting an override file restores that section's compiled default
156
+ guidance and order: the default renders at session-start, and the file re-seeds
157
+ at next boot.
158
+
159
+ - **Reset = delete the file, or empty it AND remove the front-matter fence.** A whitespace-only file with no fence means "I want the default" — the compiled default renders, and the file re-seeds at next boot for any preset dir, shipped or custom.
160
+ - **Blank on purpose = keep a valid fence.** Any well-formed `---` fence — even a keyless `---\n---\n`, even an empty body — is a deliberate-intent signal: the file is explicit content and is never reset or re-seeded.
161
+ - **Broken fence = fast fail.** A `---` fence that does not parse (missing closing `---`, non-integer `order`, unknown key) is rejected: the malformed text is never injected into the context, the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
162
+ - **Shipped vs custom.** Shipped preset files (`standard`, `code`, `minimal`, `cordis`) re-seed at boot; a deleted custom-preset override stays absent — absence is no override. Deleting a whole `<preset>/` directory re-seeds all four section files at boot (shipped presets).
163
+ - **Reset restores the current bundle defaults** — a plugin upgrade yields new defaults.
164
+
165
+ Re-seeding happens at boot, never mid-session.
166
+
151
167
  ## Why Hashline
152
168
 
153
169
  **Token-saving.** An edit call carries `remove_from` / `remove_to` (two 3-char hashes) plus the
package/README.zh.md CHANGED
@@ -5,8 +5,8 @@
5
5
  <h1 align="center">dsh-better-edit</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>面向 DeepSeek Harness 的哈希锚定编辑工具。<br>
9
- 按内容地址编辑——不靠行号,也不靠字符串替换。更省 token。更多注意力留给真正的工作。绝不会改错行。</strong>
8
+ <strong>一个专为 DeepSeek Harness 而生的更好的编辑工具。<br>
9
+ 底层基于 hash-anchored 定位——不依赖行号,也不靠字符串替换,更少的词源消耗,留出更多的上下文空间给真正的工作。</strong>
10
10
  </p>
11
11
 
12
12
  <p align="center">
@@ -55,8 +55,9 @@ Hashline 用两个哈希代替旧文本——**编辑 token 减少 31%**(多
55
55
  ### 安装
56
56
 
57
57
  ```sh
58
- dsh plugin --profile <name> add dsh-better-edit # 从 npm
59
- dsh plugin --profile <name> add /path/to/dsh-better-edit # 从本地源码
58
+ npx @deepseek-ai/dsh plugin --profile web add github:Rianico/dsh-better-edit # 从 github
59
+ npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # 从 npm
60
+ npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # 从本地源码
60
61
  ```
61
62
 
62
63
  该 profile 的下一个会话将带着 hashline 工具运行。验证该层是否生效:
@@ -118,7 +119,7 @@ $DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md
118
119
 
119
120
  首次启动时插件会为四个随附 preset——`standard/`、`code/`、`minimal/`、`cordis/`——各自写入编译内置的
120
121
  可编辑指引文件(含 `order` front-matter),让每个 preset 的指引一开始就可编辑,而不是空白。插件主目录
121
- 根的 `README.md` 说明整套机制。文件只在首次写入时生成、之后绝不被覆盖,因此你的修改会保留。preset 目录
122
+ 根的 `README.md` 说明整套机制。文件只在首次写入时生成、之后绝不被覆盖,因此你的修改会保留——唯一的例外是重置(见下文 *重置 / 恢复默认*)。preset 目录
122
123
  里可以只放你想覆盖的片段文件,其余自动回退到编译内置默认值。
123
124
 
124
125
  文件默认为纯文本;除非以 `order` front-matter 栅栏开头,它会改变该片段在组装后的系统提示中的位置:
@@ -137,6 +138,24 @@ session-start 时读取一次,因此修改只影响新会话——绝不影响
137
138
  (即没有 preset 名册)的部署继续使用编译内置默认值,完全不会触碰这些文件;
138
139
  preset 从来不是必需的。
139
140
 
141
+ ### 重置 / 恢复默认
142
+
143
+ **想让指引“回到默认”?删掉覆盖文件,或把它清空(同时删掉开头的 `---` 栅栏)即可。**
144
+
145
+ 清空文件时,只要文件里是空白内容、并且没有 `---` 栅栏,插件就认为你不想再自定义这一片段了,于是:
146
+
147
+ - 新会话开始时,直接使用插件内置的默认指引;
148
+ - 下一次启动插件时,会用默认内容把这个文件重新生成。
149
+
150
+ 再细致一点:
151
+
152
+ - **为什么要连栅栏一起删**:只要文件里还有 `---` 栅栏,哪怕是空的、什么内容也没有,插件都当成“你有意留空”,不会去动它。所以“故意留空”就保留栅栏;“恢复默认”就把栅栏和内容一起清掉。
153
+ - **栅栏写错了会怎样**:少了一个 `---`、`order` 不是数字、出现了不认识的键——只要栅栏格式不对,插件会直接忽略这个文件:仍然渲染默认指引,并在日志里提示是哪个文件、哪里写错了。你写的正文会原样留在磁盘上,方便改好后再用。
154
+ - **自带 preset 与自定义 preset**:插件自带的四个 preset(`standard`、`code`、`minimal`、`cordis`)会在下一次启动时自动补全空白文件;自定义 preset 里删除的覆盖文件不会自动出现(删了就当“没有这个文件”)。删掉某一整个 preset 目录,下次启动时插件会重新生成里面的四个文件(仅限自带 preset)。
155
+ - **恢复的是“当前版本”的默认**:插件升级后,重置得到的是新版本带的新默认内容,不是旧版本留下的。
156
+
157
+ 文件的重新生成只发生在插件启动时,绝不影响进行中的会话。
158
+
140
159
  ## 为什么用 Hashline
141
160
 
142
161
  **省 token。** 一次编辑调用只携带 `remove_from` / `remove_to`(两个 3 字符哈希)加替换文本——从不回显被替换的文本。`str_replace` 调用则必须逐字复现被替换的文本。在一个真实文件上的 12 次编辑会话中,这可以**减少 31% 的输出 token**(多行范围达 43%)——而且这些是*输出* token,按输入的约 5-6 倍计费。见[基准测试](#基准测试)。
package/lib/guidance.js CHANGED
@@ -9,11 +9,13 @@
9
9
  * never the workspace store) and are resolved per section as
10
10
  * `<preset>/<section>.md` → compiled default.
11
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.
12
+ * fence carrying only an `order` key (`---` / `order: N` / `---`). Any
13
+ * well-formed fence — even keyless, even an empty body — is deliberate content
14
+ * and wins. A leading `---` that does not parse (a missing closing fence, a
15
+ * non-integer `order`, an unknown key) is a MALFORMED override and must never
16
+ * reach the model: resolution falls back to the compiled default and reports
17
+ * the file and parse reason. An absent or blank override (whitespace-only body,
18
+ * no fence) means "use the default" and is re-seeded at boot.
17
19
  *
18
20
  * Resolution is pure: no cordis services, no harness wiring. The installer
19
21
  * ticket reads the resolved sections once per agent at session-start;
@@ -82,25 +84,41 @@ function stripCR(line) {
82
84
  }
83
85
  /**
84
86
  * Parse an override file. Only a leading `---` fence whose lines are empty or
85
- * `order: <integer>` is accepted; every other shape (no fence, no closing
86
- * fence, unknown key, non-integer value) yields the whole file as prose.
87
+ * `order: <integer>` is accepted. A leading `---` that does not parse (no
88
+ * closing fence, unknown key, non-integer value) is a malformed override;
89
+ * anything else is pure prose (the whole file as text).
87
90
  */
88
91
  export function parseSectionFile(content) {
89
92
  const lines = content.split("\n");
90
- if (lines.length < 3 || stripCR(lines[0]) !== "---") {
93
+ if (stripCR(lines[0]) !== "---") {
91
94
  return { text: content };
92
95
  }
93
96
  const close = lines.findIndex((line, index) => index > 0 && stripCR(line) === "---");
94
- if (close < 0)
95
- return { text: content };
97
+ if (close < 0) {
98
+ return { text: content, malformed: true, reason: "missing closing fence" };
99
+ }
96
100
  let order;
97
101
  for (let index = 1; index < close; index++) {
98
102
  const line = stripCR(lines[index]);
99
103
  if (line.trim() === "")
100
104
  continue;
105
+ const key = line.split(":")[0].trim();
101
106
  const match = /^order:\s*(-?\d+)\s*$/.exec(line);
102
- if (!match)
103
- return { text: content };
107
+ if (!match) {
108
+ if (key === "order") {
109
+ const value = line.slice(line.indexOf(":") + 1).trim();
110
+ return {
111
+ text: content,
112
+ malformed: true,
113
+ reason: `non-integer order '${value}'`,
114
+ };
115
+ }
116
+ return {
117
+ text: content,
118
+ malformed: true,
119
+ reason: `unknown key '${key}'`,
120
+ };
121
+ }
104
122
  order = Number.parseInt(match[1], 10);
105
123
  }
106
124
  // Front-matter body: strip leading blank lines after the closing fence so
@@ -112,6 +130,27 @@ export function parseSectionFile(content) {
112
130
  bodyStart++;
113
131
  return { order, text: body.slice(bodyStart).join("\n") };
114
132
  }
133
+ /**
134
+ * True when an override file is blank: whitespace-only body and NO front-matter
135
+ * fence (the "I want the default" case). The single source of truth for whether
136
+ * a boot-time materialization pass should re-seed a file. False for prose with
137
+ * content, for any valid fence (including a keyless/empty one — a deliberate
138
+ * blank), and for malformed files.
139
+ */
140
+ export function isBlankOverride(content) {
141
+ const parsed = parseSectionFile(content);
142
+ return (!parsed.malformed &&
143
+ parsed.order === undefined &&
144
+ parsed.text.trim() === "" &&
145
+ !startsWithFenceLine(content));
146
+ }
147
+ /** True when an override file opens with a leading `---` fence that is malformed. */
148
+ export function isMalformedOverride(content) {
149
+ return parseSectionFile(content).malformed === true;
150
+ }
151
+ function startsWithFenceLine(content) {
152
+ return stripCR(content.split("\n")[0]) === "---";
153
+ }
115
154
  function overrideCandidates(file, options) {
116
155
  const candidates = [];
117
156
  if (options.presetId !== undefined) {
@@ -121,8 +160,9 @@ function overrideCandidates(file, options) {
121
160
  }
122
161
  /**
123
162
  * Resolve one section's guidance: the first override file that exists wins,
124
- * falling back to the compiled default. A missing file (ENOENT) advances the
125
- * chain; any other read error propagates.
163
+ * falling back to the compiled default. A missing or blank file (ENOENT, or
164
+ * whitespace-only with no fence) advances the chain; a malformed file resolves
165
+ * to the compiled default and reports itself; any other read error propagates.
126
166
  */
127
167
  export async function resolveSection(name, options) {
128
168
  const section = SECTION_BY_NAME.get(name);
@@ -137,6 +177,22 @@ export async function resolveSection(name, options) {
137
177
  if (content === undefined)
138
178
  continue;
139
179
  const parsed = parseSectionFile(content);
180
+ if (parsed.malformed) {
181
+ // A broken override must never reach the model. Resolve to the
182
+ // compiled default and report the file + parse reason to the caller.
183
+ return {
184
+ order: section.defaultOrder,
185
+ text: section.renderDefault(),
186
+ malformed: {
187
+ file: candidate,
188
+ reason: parsed.reason ?? "malformed override",
189
+ },
190
+ };
191
+ }
192
+ // Blank (no fence, whitespace-only) means "use the default": advance the
193
+ // fallback chain rather than render an empty section.
194
+ if (isBlankOverride(content))
195
+ continue;
140
196
  return { order: parsed.order ?? section.defaultOrder, text: parsed.text };
141
197
  }
142
198
  return { order: section.defaultOrder, text: section.renderDefault() };
@@ -147,11 +203,16 @@ export async function resolveSection(name, options) {
147
203
  */
148
204
  export async function composeSections(presetId, homeDir) {
149
205
  return Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
150
- const { order, text } = await resolveSection(section.name, {
206
+ const resolved = await resolveSection(section.name, {
151
207
  presetId,
152
208
  homeDir,
153
209
  });
154
- return { name: section.name, order, text };
210
+ return {
211
+ name: section.name,
212
+ order: resolved.order,
213
+ text: resolved.text,
214
+ malformed: resolved.malformed,
215
+ };
155
216
  }));
156
217
  }
157
218
  /**
@@ -237,9 +298,13 @@ export const GUIDANCE_HOME_README_ZH = `# dsh-better-edit 指引
237
298
  * For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
238
299
  * undo_last_edit}.md\` rendered from the compiled defaults (with order
239
300
  * front-matter), plus a root \`README.md\` documenting the convention.
240
- * Idempotent: existing files are never rewritten (a user-edited file survives
241
- * repeated calls) and missing directories are created on demand. Each file is
242
- * written exclusively, so two concurrent first runs race safely.
301
+ * Idempotent: a user-edited file survives repeated calls. A blank override file
302
+ * (whitespace-only body, no fence) is re-seeded with the current compiled
303
+ * default; malformed, non-blank, and deliberate-blank (valid-fence) files are
304
+ * never touched. Custom preset directories present on disk are scanned the same
305
+ * way but never fabricated. Missing directories are created on demand (shipped
306
+ * presets only), and shipped files are written exclusively so two concurrent
307
+ * first runs race safely.
243
308
  */
244
309
  export async function ensurePresetGuidance(homeDir) {
245
310
  await mkdir(homeDir, { recursive: true });
@@ -248,10 +313,12 @@ export async function ensurePresetGuidance(homeDir) {
248
313
  await mkdir(dir, { recursive: true });
249
314
  const existing = new Set(await readdir(dir));
250
315
  await Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
251
- if (existing.has(section.file))
316
+ const path = join(dir, section.file);
317
+ if (existing.has(section.file)) {
318
+ await healBlankOverride(path, section);
252
319
  return;
253
- const content = `---\norder: ${section.defaultOrder}\n---\n\n${section.renderDefault()}`;
254
- await writeFile(join(dir, section.file), content, {
320
+ }
321
+ await writeFile(path, seededContent(section), {
255
322
  encoding: "utf-8",
256
323
  flag: "wx",
257
324
  }).catch((error) => {
@@ -262,6 +329,21 @@ export async function ensurePresetGuidance(homeDir) {
262
329
  });
263
330
  }));
264
331
  }));
332
+ // Custom presets present on disk: heal existing blank section files only.
333
+ // Absence is respected — a custom preset's files are never fabricated, and
334
+ // malformed / non-blank / deliberate-blank files are left untouched.
335
+ const entries = await readdir(homeDir, { withFileTypes: true });
336
+ await Promise.all(entries
337
+ .filter((entry) => entry.isDirectory() && !DEFAULT_PRESETS.includes(entry.name))
338
+ .map(async (entry) => {
339
+ const dir = join(homeDir, entry.name);
340
+ const existing = new Set(await readdir(dir));
341
+ await Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
342
+ if (!existing.has(section.file))
343
+ return;
344
+ await healBlankOverride(join(dir, section.file), section);
345
+ }));
346
+ }));
265
347
  const homeFiles = new Set(await readdir(homeDir));
266
348
  const readmes = [
267
349
  ["README.md", GUIDANCE_HOME_README],
@@ -280,3 +362,30 @@ export async function ensurePresetGuidance(homeDir) {
280
362
  });
281
363
  }));
282
364
  }
365
+ /** The content a seeded override file carries, rendered from the current defaults. */
366
+ function seededContent(section) {
367
+ return `---\norder: ${section.defaultOrder}\n---\n\n${section.renderDefault()}`;
368
+ }
369
+ /**
370
+ * Heal an existing empty override file: a blank file means "use the default",
371
+ * so it is rewritten with the current seeded default. Malformed, non-blank, and
372
+ * deliberate-blank (valid-fence) files are left untouched — overwriting a
373
+ * malformed file would destroy the user's salvageable body. Plain overwrite:
374
+ * the file already exists. Errors propagate to the boot caller, which never
375
+ * fails init.
376
+ */
377
+ async function healBlankOverride(path, section) {
378
+ let content;
379
+ try {
380
+ content = await readFile(path, "utf-8");
381
+ }
382
+ catch (error) {
383
+ // Vanished between readdir and read; nothing to heal.
384
+ if (errCode(error) === "ENOENT")
385
+ return;
386
+ throw error;
387
+ }
388
+ if (!isBlankOverride(content))
389
+ return;
390
+ await writeFile(path, seededContent(section), { encoding: "utf-8" });
391
+ }
package/lib/index.js CHANGED
@@ -56,7 +56,15 @@ async function resolveAgentSections(rootCtx, agent) {
56
56
  return compiledDefaultSections();
57
57
  try {
58
58
  const presetId = agentPresets.composedPreset(agent.ctx);
59
- return await composeSections(presetId, configDir());
59
+ const sections = await composeSections(presetId, configDir());
60
+ // Warn once per agent install (this runs once per agent, under the
61
+ // WeakSet guard) about any malformed override we had to ignore.
62
+ for (const section of sections) {
63
+ if (section.malformed) {
64
+ rootCtx.logger.warn(`dsh-better-edit: ignoring malformed guidance override ${section.malformed.file}: ${section.malformed.reason}; using compiled default`);
65
+ }
66
+ }
67
+ return sections;
60
68
  }
61
69
  catch (error) {
62
70
  rootCtx.logger.warn(`dsh-better-edit: guidance resolution failed for agent ${agent.id}, using compiled defaults: ${error instanceof Error ? error.message : String(error)}`);
@@ -9,11 +9,13 @@
9
9
  * never the workspace store) and are resolved per section as
10
10
  * `<preset>/<section>.md` → compiled default.
11
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.
12
+ * fence carrying only an `order` key (`---` / `order: N` / `---`). Any
13
+ * well-formed fence — even keyless, even an empty body — is deliberate content
14
+ * and wins. A leading `---` that does not parse (a missing closing fence, a
15
+ * non-integer `order`, an unknown key) is a MALFORMED override and must never
16
+ * reach the model: resolution falls back to the compiled default and reports
17
+ * the file and parse reason. An absent or blank override (whitespace-only body,
18
+ * no fence) means "use the default" and is re-seeded at boot.
17
19
  *
18
20
  * Resolution is pure: no cordis services, no harness wiring. The installer
19
21
  * ticket reads the resolved sections once per agent at session-start;
@@ -41,15 +43,30 @@ export declare function renderSectionDefault(name: string): string;
41
43
  export interface ParsedSection {
42
44
  /** Front-matter `order`, when present and valid. */
43
45
  order?: number;
44
- /** The section text: the file body, or the whole file when front-matter is absent or malformed. */
46
+ /** The section text: the file body, or the whole file when no fence is present. */
45
47
  text: string;
48
+ /** True when a leading `---` fence is present but does not parse (fast fail). */
49
+ malformed?: boolean;
50
+ /** Human-readable parse reason, present only when `malformed` is true. */
51
+ reason?: string;
46
52
  }
47
53
  /**
48
54
  * 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.
55
+ * `order: <integer>` is accepted. A leading `---` that does not parse (no
56
+ * closing fence, unknown key, non-integer value) is a malformed override;
57
+ * anything else is pure prose (the whole file as text).
51
58
  */
52
59
  export declare function parseSectionFile(content: string): ParsedSection;
60
+ /**
61
+ * True when an override file is blank: whitespace-only body and NO front-matter
62
+ * fence (the "I want the default" case). The single source of truth for whether
63
+ * a boot-time materialization pass should re-seed a file. False for prose with
64
+ * content, for any valid fence (including a keyless/empty one — a deliberate
65
+ * blank), and for malformed files.
66
+ */
67
+ export declare function isBlankOverride(content: string): boolean;
68
+ /** True when an override file opens with a leading `---` fence that is malformed. */
69
+ export declare function isMalformedOverride(content: string): boolean;
53
70
  /** Options for resolving one section's guidance. */
54
71
  export interface ResolveGuidanceOptions {
55
72
  /** Agent preset id, or undefined to skip the preset layer. */
@@ -61,11 +78,17 @@ export interface ResolveGuidanceOptions {
61
78
  export interface GuidanceResolution {
62
79
  order: number;
63
80
  text: string;
81
+ /** Set when the override file was malformed and the compiled default was used. */
82
+ malformed?: {
83
+ file: string;
84
+ reason: string;
85
+ };
64
86
  }
65
87
  /**
66
88
  * 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.
89
+ * falling back to the compiled default. A missing or blank file (ENOENT, or
90
+ * whitespace-only with no fence) advances the chain; a malformed file resolves
91
+ * to the compiled default and reports itself; any other read error propagates.
69
92
  */
70
93
  export declare function resolveSection(name: string, options: ResolveGuidanceOptions): Promise<GuidanceResolution>;
71
94
  /** The resolved configuration of one section, ready for the systemPrompt registry. */
@@ -73,6 +96,11 @@ export interface SectionOverride {
73
96
  name: string;
74
97
  order: number;
75
98
  text: string;
99
+ /** Set when the override file was malformed and the compiled default was used. */
100
+ malformed?: {
101
+ file: string;
102
+ reason: string;
103
+ };
76
104
  }
77
105
  /**
78
106
  * Resolve all four sections for a preset. `presetId === undefined` skips the
@@ -91,8 +119,12 @@ export declare const GUIDANCE_HOME_README_ZH = "# dsh-better-edit \u6307\u5F15\n
91
119
  * For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
92
120
  * undo_last_edit}.md\` rendered from the compiled defaults (with order
93
121
  * 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.
122
+ * Idempotent: a user-edited file survives repeated calls. A blank override file
123
+ * (whitespace-only body, no fence) is re-seeded with the current compiled
124
+ * default; malformed, non-blank, and deliberate-blank (valid-fence) files are
125
+ * never touched. Custom preset directories present on disk are scanned the same
126
+ * way but never fabricated. Missing directories are created on demand (shipped
127
+ * presets only), and shipped files are written exclusively so two concurrent
128
+ * first runs race safely.
97
129
  */
98
130
  export declare function ensurePresetGuidance(homeDir: string): Promise<void>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-better-edit",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "type": "module",
5
5
  "description": "Hash-anchored read/edit/batch_edit/undo_last_edit tools for DeepSeek Harness (dsh). Every line gets a unique 3-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
6
6
  "main": "lib/index.js",
@@ -54,19 +54,10 @@
54
54
  }
55
55
  },
56
56
  "dependencies": {
57
- "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
58
57
  "diff": "^8.0.2",
59
58
  "file-type": "^21.3.0",
60
59
  "xxhash-wasm": "^1.1.0"
61
60
  },
62
- "peerDependencies": {
63
- "@deepseek-ai/cordis": "^4.0.0",
64
- "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
65
- "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
66
- "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
67
- "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
68
- "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
69
- },
70
61
  "engines": {
71
62
  "node": "^22.19.0 || >=24.0.0"
72
63
  },
@@ -87,6 +78,7 @@
87
78
  "@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
88
79
  "@deepseek-ai/dsh-session": "0.1.0-rc.6",
89
80
  "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
81
+ "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
90
82
  "@types/node": "^24.0.0",
91
83
  "@vitest/coverage-v8": "^4.1.10",
92
84
  "js-tiktoken": "1.0.21",