dsh-better-edit 0.2.0 → 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.
@@ -0,0 +1,130 @@
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
+ * 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.
19
+ *
20
+ * Resolution is pure: no cordis services, no harness wiring. The installer
21
+ * ticket reads the resolved sections once per agent at session-start;
22
+ * nothing here watches or caches files.
23
+ * @module dsh-better-edit/guidance
24
+ */
25
+ /** The presets shipped by the harness, each seeded with editable guidance. */
26
+ export declare const DEFAULT_PRESETS: readonly string[];
27
+ /** One overridable tool section. */
28
+ export interface GuidanceSection {
29
+ /** Registry section name, e.g. `tool:edit`. */
30
+ name: string;
31
+ /** Override file name inside a preset directory, e.g. `edit.md`. */
32
+ file: string;
33
+ /** Order used when the override file carries no front-matter `order`. */
34
+ defaultOrder: number;
35
+ /** The compiled default text, byte-identical to today's inline rendering. */
36
+ renderDefault(): string;
37
+ }
38
+ /** The four sections, in default-order sequence. */
39
+ export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
40
+ /** Render the compiled default text for one section. */
41
+ export declare function renderSectionDefault(name: string): string;
42
+ /** The parsed content of one override file. */
43
+ export interface ParsedSection {
44
+ /** Front-matter `order`, when present and valid. */
45
+ order?: number;
46
+ /** The section text: the file body, or the whole file when no fence is present. */
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;
52
+ }
53
+ /**
54
+ * Parse an override file. Only a leading `---` fence whose lines are empty or
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).
58
+ */
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;
70
+ /** Options for resolving one section's guidance. */
71
+ export interface ResolveGuidanceOptions {
72
+ /** Agent preset id, or undefined to skip the preset layer. */
73
+ presetId?: string;
74
+ /** Plugin shared home directory (`$DSH_HOME/plugins/dsh-better-edit`). */
75
+ homeDir: string;
76
+ }
77
+ /** The resolved text and order for one section. */
78
+ export interface GuidanceResolution {
79
+ order: number;
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
+ };
86
+ }
87
+ /**
88
+ * Resolve one section's guidance: the first override file that exists wins,
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.
92
+ */
93
+ export declare function resolveSection(name: string, options: ResolveGuidanceOptions): Promise<GuidanceResolution>;
94
+ /** The resolved configuration of one section, ready for the systemPrompt registry. */
95
+ export interface SectionOverride {
96
+ name: string;
97
+ order: number;
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
+ };
104
+ }
105
+ /**
106
+ * Resolve all four sections for a preset. `presetId === undefined` skips the
107
+ * `<preset>/` layer and resolves straight to the compiled defaults.
108
+ */
109
+ export declare function composeSections(presetId: string | undefined, homeDir: string): Promise<SectionOverride[]>;
110
+ /**
111
+ * The root README: the per-preset customization convention users see in the
112
+ * plugin home.
113
+ */
114
+ 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";
115
+ 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";
116
+ /**
117
+ * Materialize per-preset guidance directories in the plugin home.
118
+ *
119
+ * For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
120
+ * undo_last_edit}.md\` rendered from the compiled defaults (with order
121
+ * front-matter), plus a root \`README.md\` documenting the convention.
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.
129
+ */
130
+ export declare function ensurePresetGuidance(homeDir: string): Promise<void>;
@@ -9,6 +9,10 @@
9
9
  * automatically when the agent is disposed. The built-in `write` stays in
10
10
  * place; a scoped `tools/post-execute` listener appends the fresh hashline
11
11
  * preview to write results.
12
+ *
13
+ * The four `tool:*` guidance sections resolve per agent preset from override
14
+ * files in the shared home (see `src/guidance.ts`); deployments without the
15
+ * `agentPresets` service keep the compiled defaults unchanged.
12
16
  * @module dsh-better-edit
13
17
  */
14
18
  import type { Context } from "@deepseek-ai/cordis";
@@ -1,17 +1,27 @@
1
1
  /**
2
2
  * Model-facing prompt text for the hashline tools, embedded so the bundle
3
- * ships no external prompt files. Each tool's description is short; the
4
- * `tool:*` system-prompt sections carry the full usage guidance the model
5
- * reads when the tools are presented.
3
+ * ships no external prompt files. Each tool's schema `description` is short;
4
+ * the `tool:*` system-prompt sections carry the brief guidance the model
5
+ * reads when the tools are presented. Guidance is uniform: a one-line opener
6
+ * followed by tight bullets.
6
7
  * @module dsh-better-edit/prompts
7
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
+ export interface ToolGuidance {
15
+ /** One-line lead shown above the bullets. */
16
+ intro: string;
17
+ /** Concise bullets; each is self-contained within its section. */
18
+ lines: readonly string[];
19
+ }
8
20
  export declare const EDIT_DESCRIPTION: string;
9
- export declare const EDIT_SNIPPET = "Edit lines in a text file via bare 3-char HASH anchors from read \u2014 hash only, never line content; anchor exactly the lines that change; one edit per tool call";
10
- export declare const EDIT_GUIDELINES: string[];
21
+ export declare const EDIT_GUIDANCE: ToolGuidance;
11
22
  export declare const READ_DESCRIPTION: string;
12
- export declare const READ_SNIPPET = "Read a file; each line returned as HASH\u2502content";
13
- export declare const READ_GUIDELINES: string[];
23
+ export declare const READ_GUIDANCE: ToolGuidance;
14
24
  export declare const BATCH_EDIT_DESCRIPTION: string;
15
- export declare const BATCH_EDIT_GUIDELINES: string[];
25
+ export declare const BATCH_EDIT_GUIDANCE: ToolGuidance;
16
26
  export declare const UNDO_DESCRIPTION: string;
17
- export declare const UNDO_GUIDELINES: string[];
27
+ export declare const UNDO_GUIDANCE: ToolGuidance;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-better-edit",
3
- "version": "0.2.0",
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",
@@ -35,6 +35,7 @@
35
35
  "dsh-plugin",
36
36
  "deepseek-harness",
37
37
  "coding-agent",
38
+ "oh-my-pi",
38
39
  "hashline",
39
40
  "hash-anchored",
40
41
  "hash",
@@ -53,19 +54,10 @@
53
54
  }
54
55
  },
55
56
  "dependencies": {
56
- "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
57
57
  "diff": "^8.0.2",
58
58
  "file-type": "^21.3.0",
59
59
  "xxhash-wasm": "^1.1.0"
60
60
  },
61
- "peerDependencies": {
62
- "@deepseek-ai/cordis": "^4.0.0",
63
- "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
64
- "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
65
- "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
66
- "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
67
- "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
68
- },
69
61
  "engines": {
70
62
  "node": "^22.19.0 || >=24.0.0"
71
63
  },
@@ -86,6 +78,7 @@
86
78
  "@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
87
79
  "@deepseek-ai/dsh-session": "0.1.0-rc.6",
88
80
  "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
81
+ "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
89
82
  "@types/node": "^24.0.0",
90
83
  "@vitest/coverage-v8": "^4.1.10",
91
84
  "js-tiktoken": "1.0.21",