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.
- package/CHANGELOG.md +33 -0
- package/README.md +317 -240
- package/README.zh.md +19 -11
- package/lib/constants.js +3 -1
- package/lib/contract.js +159 -63
- package/lib/drift.js +5 -98
- package/lib/dsh-context.js +2 -24
- package/lib/edit-engine.js +9 -8
- package/lib/edit-pipeline.js +3 -121
- package/lib/edit-response.js +16 -8
- package/lib/file-kind.js +6 -121
- package/lib/file-reader.js +4 -77
- package/lib/file-view.js +486 -0
- package/lib/guidance/index.js +8 -0
- package/lib/guidance/materialize.js +212 -0
- package/lib/guidance/parse.js +80 -0
- package/lib/guidance/resolve.js +116 -0
- package/lib/guidance.js +6 -388
- package/lib/hash-store.js +6 -4
- package/lib/hashline/alphabet.js +2 -6
- package/lib/hashline/anchor-pipeline.js +786 -0
- package/lib/hashline/apply.js +2 -223
- package/lib/hashline/hash-assign.js +255 -0
- package/lib/hashline/hash.js +67 -29
- package/lib/hashline/hasher.js +2 -23
- package/lib/hashline/index.js +9 -4
- package/lib/hashline/parse.js +2 -35
- package/lib/hashline/pure.js +2 -213
- package/lib/hashline/resolve.js +3 -361
- package/lib/hashline/served.js +2 -120
- package/lib/index.js +1 -3
- package/lib/mutation.js +266 -0
- package/lib/noop-guard.js +20 -0
- package/lib/preview-controller.js +65 -0
- package/lib/prompts.js +14 -20
- package/lib/read-and-serve.js +23 -23
- package/lib/read-render.js +3 -139
- package/lib/served-store.js +2 -216
- package/lib/session-view.js +332 -0
- package/lib/tool-batch-edit.js +9 -10
- package/lib/tool-edit.js +73 -129
- package/lib/tool-read.js +3 -5
- package/lib/tool-undo.js +16 -10
- package/lib/truncate.js +3 -95
- package/lib/types/constants.d.ts +2 -0
- package/lib/types/contract.d.ts +120 -15
- package/lib/types/drift.d.ts +5 -29
- package/lib/types/dsh-context.d.ts +2 -20
- package/lib/types/edit-engine.d.ts +2 -2
- package/lib/types/edit-pipeline.d.ts +3 -44
- package/lib/types/file-kind.d.ts +6 -18
- package/lib/types/file-reader.d.ts +4 -45
- package/lib/types/file-view.d.ts +139 -0
- package/lib/types/guidance/index.d.ts +8 -0
- package/lib/types/guidance/materialize.d.ts +23 -0
- package/lib/types/guidance/parse.d.ts +36 -0
- package/lib/types/guidance/resolve.d.ts +55 -0
- package/lib/types/guidance.d.ts +6 -127
- package/lib/types/hashline/alphabet.d.ts +1 -5
- package/lib/types/hashline/anchor-pipeline.d.ts +127 -0
- package/lib/types/hashline/apply.d.ts +1 -22
- package/lib/types/hashline/hash-assign.d.ts +25 -0
- package/lib/types/hashline/hash.d.ts +8 -9
- package/lib/types/hashline/hasher.d.ts +1 -8
- package/lib/types/hashline/index.d.ts +12 -4
- package/lib/types/hashline/parse.d.ts +1 -7
- package/lib/types/hashline/pure.d.ts +1 -26
- package/lib/types/hashline/resolve.d.ts +1 -58
- package/lib/types/hashline/served.d.ts +1 -43
- package/lib/types/mutation.d.ts +131 -0
- package/lib/types/noop-guard.d.ts +29 -0
- package/lib/types/preview-controller.d.ts +33 -0
- package/lib/types/prompts.d.ts +9 -9
- package/lib/types/read-and-serve.d.ts +6 -5
- package/lib/types/read-render.d.ts +3 -18
- package/lib/types/served-store.d.ts +2 -81
- package/lib/types/session-view.d.ts +92 -0
- package/lib/types/tool-edit.d.ts +3 -14
- package/lib/types/truncate.d.ts +3 -29
- package/lib/types/validation.d.ts +6 -7
- package/lib/types/workspace.d.ts +2 -21
- package/lib/validation.js +6 -33
- package/lib/workspace.js +2 -27
- package/lib/write-hook.js +2 -2
- package/package.json +2 -2
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Materializer: IO-heavy seam owning per-preset directory seeding, blank-heal,
|
|
3
|
+
* and README generation. Idempotent and concurrent-safe (wx).
|
|
4
|
+
* @module dsh-better-edit/guidance/materialize
|
|
5
|
+
*/
|
|
6
|
+
import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
|
|
7
|
+
import { join } from "node:path";
|
|
8
|
+
import { errCode } from "../utils.js";
|
|
9
|
+
import { isBlankOverride } from "./parse.js";
|
|
10
|
+
import { GUIDANCE_SECTIONS } from "./resolve.js";
|
|
11
|
+
/** The presets shipped by the harness, each seeded with editable guidance. */
|
|
12
|
+
export const DEFAULT_PRESETS = [
|
|
13
|
+
"standard",
|
|
14
|
+
"code",
|
|
15
|
+
"minimal",
|
|
16
|
+
"cordis",
|
|
17
|
+
];
|
|
18
|
+
/**
|
|
19
|
+
* The root README: the per-preset customization convention users see in the
|
|
20
|
+
* plugin home.
|
|
21
|
+
*/
|
|
22
|
+
export const GUIDANCE_HOME_README = `# dsh-better-edit guidance
|
|
23
|
+
|
|
24
|
+
Each agent preset has its own guidance directory here: \`<preset>/<section>.md\`.
|
|
25
|
+
On first boot the plugin seeds the shipped presets (\`standard\`, \`code\`,
|
|
26
|
+
\`minimal\`, \`cordis\`) with the compiled defaults; existing files are never
|
|
27
|
+
overwritten, so your edits survive.
|
|
28
|
+
|
|
29
|
+
Each file is one tool section:
|
|
30
|
+
|
|
31
|
+
- \`read.md\` -> \`tool:read\`
|
|
32
|
+
- \`edit.md\` -> \`tool:edit\`
|
|
33
|
+
- \`undo_last_edit.md\` -> \`tool:undo_last_edit\`
|
|
34
|
+
|
|
35
|
+
## Customize
|
|
36
|
+
|
|
37
|
+
Edit the \`<section>.md\` file for the preset and section you want to change —
|
|
38
|
+
the file body IS the text the model reads for that section. Files are read once
|
|
39
|
+
per agent at session-start, so edits apply to new sessions.
|
|
40
|
+
|
|
41
|
+
An optional YAML front-matter fence places the section at a custom position in
|
|
42
|
+
the assembled system prompt:
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
order: 150
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
<section text>
|
|
49
|
+
|
|
50
|
+
A file without front-matter keeps the default order. A malformed fence (a
|
|
51
|
+
missing closing \`---\`, a non-integer \`order\`, an unknown key) makes the whole
|
|
52
|
+
file plain prose.
|
|
53
|
+
|
|
54
|
+
## Fallback
|
|
55
|
+
|
|
56
|
+
A preset with no directory here, or a missing section file, falls back to the
|
|
57
|
+
compiled defaults in the plugin bundle. To customize a preset that has no
|
|
58
|
+
seeded directory, copy a seeded one to its name.
|
|
59
|
+
`;
|
|
60
|
+
export const GUIDANCE_HOME_README_ZH = `# dsh-better-edit 指引
|
|
61
|
+
|
|
62
|
+
每个 agent preset 在这里都有自己的指引目录:\`<preset>/<section>.md\`。首次启动时
|
|
63
|
+
插件会为随附的 preset(\`standard\`、\`code\`、\`minimal\`、\`cordis\`)写入编译内置的
|
|
64
|
+
默认内容;已有文件绝不被覆盖,因此你的编辑会保留。
|
|
65
|
+
|
|
66
|
+
每个文件对应一个工具片段:
|
|
67
|
+
|
|
68
|
+
- \`read.md\` -> \`tool:read\`
|
|
69
|
+
- \`edit.md\` -> \`tool:edit\`
|
|
70
|
+
- \`undo_last_edit.md\` -> \`tool:undo_last_edit\`
|
|
71
|
+
|
|
72
|
+
## 自定义
|
|
73
|
+
|
|
74
|
+
编辑你想修改的 preset 与片段的 \`<section>.md\` 文件即可——文件正文就是该片段呈
|
|
75
|
+
现给模型的文本。文件在 agent 的 session-start 时读取一次,因此修改只影响新会话。
|
|
76
|
+
|
|
77
|
+
可以用可选的 YAML front-matter 栅栏把片段放到组装后系统提示中的自定义位置:
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
order: 150
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
<片段文本>
|
|
84
|
+
|
|
85
|
+
没有 front-matter 的文件保持默认顺序。格式错误的栅栏(缺少收尾 \`---\`、非整数
|
|
86
|
+
\`order\`、未知键)会让整个文件退化为纯文本。
|
|
87
|
+
|
|
88
|
+
## 回退
|
|
89
|
+
|
|
90
|
+
这里没有对应目录的 preset、或缺失某个片段文件时,会回退到插件包内的编译内置默认
|
|
91
|
+
值。要自定义没有种子目录的 preset,把一个种子目录复制成它的名字即可。
|
|
92
|
+
`;
|
|
93
|
+
/** The content a seeded override file carries, rendered from the current defaults. */
|
|
94
|
+
function seededContent(section) {
|
|
95
|
+
return `---\norder: ${section.defaultOrder}\n---\n\n${section.renderDefault()}`;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Heal an existing empty override file: a blank file means "use the default",
|
|
99
|
+
* so it is rewritten with the current seeded default. Malformed, non-blank, and
|
|
100
|
+
* deliberate-blank (valid-fence) files are left untouched — overwriting a
|
|
101
|
+
* malformed file would destroy the user's salvageable body. Plain overwrite:
|
|
102
|
+
* the file already exists. Errors propagate to the boot caller, which never
|
|
103
|
+
* fails init.
|
|
104
|
+
*/
|
|
105
|
+
async function healBlankOverride(path, section) {
|
|
106
|
+
let content;
|
|
107
|
+
try {
|
|
108
|
+
content = await readFile(path, "utf-8");
|
|
109
|
+
}
|
|
110
|
+
catch (error) {
|
|
111
|
+
// Vanished between readdir and read; nothing to heal.
|
|
112
|
+
if (errCode(error) === "ENOENT")
|
|
113
|
+
return;
|
|
114
|
+
throw error;
|
|
115
|
+
}
|
|
116
|
+
if (!isBlankOverride(content))
|
|
117
|
+
return;
|
|
118
|
+
await writeFile(path, seededContent(section), { encoding: "utf-8" });
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* Materialize per-preset guidance directories in the plugin home.
|
|
122
|
+
*
|
|
123
|
+
* For each of `DEFAULT_PRESETS` creates `<preset>/{read,edit,
|
|
124
|
+
* undo_last_edit}.md` rendered from the compiled defaults (with order
|
|
125
|
+
* front-matter), plus a root `README.md` documenting the convention.
|
|
126
|
+
* Idempotent: a user-edited file survives repeated calls. A blank override file
|
|
127
|
+
* (whitespace-only body, no fence) is re-seeded with the current compiled
|
|
128
|
+
* default; malformed, non-blank, and deliberate-blank (valid-fence) files are
|
|
129
|
+
* never touched. Custom preset directories present on disk are scanned the same
|
|
130
|
+
* way but never fabricated. Missing directories are created on demand (shipped
|
|
131
|
+
* presets only), and shipped files are written exclusively so two concurrent
|
|
132
|
+
* first runs race safely.
|
|
133
|
+
*/
|
|
134
|
+
export async function ensurePresetGuidance(homeDir) {
|
|
135
|
+
await mkdir(homeDir, { recursive: true });
|
|
136
|
+
await Promise.all(DEFAULT_PRESETS.map(async (preset) => {
|
|
137
|
+
const dir = join(homeDir, preset);
|
|
138
|
+
await mkdir(dir, { recursive: true });
|
|
139
|
+
const existing = new Set(await readdir(dir));
|
|
140
|
+
await Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
141
|
+
const path = join(dir, section.file);
|
|
142
|
+
if (existing.has(section.file)) {
|
|
143
|
+
await healBlankOverride(path, section);
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
146
|
+
await writeFile(path, seededContent(section), {
|
|
147
|
+
encoding: "utf-8",
|
|
148
|
+
flag: "wx",
|
|
149
|
+
}).catch((error) => {
|
|
150
|
+
// A concurrent writer landed first; never clobber it.
|
|
151
|
+
if (errCode(error) === "EEXIST")
|
|
152
|
+
return;
|
|
153
|
+
throw error;
|
|
154
|
+
});
|
|
155
|
+
}));
|
|
156
|
+
}));
|
|
157
|
+
// Ghost seam cleanup (ADR-0003): remove orphan batch_edit.md override files left
|
|
158
|
+
// from pre-0.3.0 homes. The payload contract merged batch_edit into edit's
|
|
159
|
+
// {path, edits:[[hash,hash,text]]} arity — the file is dead. Best-effort,
|
|
160
|
+
// idempotent, concurrent-safe (ignore ENOENT).
|
|
161
|
+
for (const preset of DEFAULT_PRESETS) {
|
|
162
|
+
const ghost = join(homeDir, preset, "batch_edit.md");
|
|
163
|
+
await unlink(ghost).catch((error) => {
|
|
164
|
+
if (errCode(error) === "ENOENT")
|
|
165
|
+
return;
|
|
166
|
+
throw error;
|
|
167
|
+
});
|
|
168
|
+
}
|
|
169
|
+
// Custom presets present on disk: heal existing blank section files only.
|
|
170
|
+
// Absence is respected — a custom preset's files are never fabricated, and
|
|
171
|
+
// malformed / non-blank / deliberate-blank files are left untouched.
|
|
172
|
+
const entries = await readdir(homeDir, { withFileTypes: true });
|
|
173
|
+
await Promise.all(entries
|
|
174
|
+
.filter((entry) => entry.isDirectory() && !DEFAULT_PRESETS.includes(entry.name))
|
|
175
|
+
.map(async (entry) => {
|
|
176
|
+
const dir = join(homeDir, entry.name);
|
|
177
|
+
const existing = new Set(await readdir(dir));
|
|
178
|
+
await Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
179
|
+
if (!existing.has(section.file))
|
|
180
|
+
return;
|
|
181
|
+
await healBlankOverride(join(dir, section.file), section);
|
|
182
|
+
}));
|
|
183
|
+
}));
|
|
184
|
+
// Ghost seam cleanup for custom presets (same ADR-0003 dead file).
|
|
185
|
+
for (const entry of entries) {
|
|
186
|
+
if (!entry.isDirectory() || DEFAULT_PRESETS.includes(entry.name))
|
|
187
|
+
continue;
|
|
188
|
+
const ghost = join(homeDir, entry.name, "batch_edit.md");
|
|
189
|
+
await unlink(ghost).catch((error) => {
|
|
190
|
+
if (errCode(error) === "ENOENT")
|
|
191
|
+
return;
|
|
192
|
+
throw error;
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
const homeFiles = new Set(await readdir(homeDir));
|
|
196
|
+
const readmes = [
|
|
197
|
+
["README.md", GUIDANCE_HOME_README],
|
|
198
|
+
["README.zh.md", GUIDANCE_HOME_README_ZH],
|
|
199
|
+
];
|
|
200
|
+
await Promise.all(readmes.map(async ([file, content]) => {
|
|
201
|
+
if (homeFiles.has(file))
|
|
202
|
+
return;
|
|
203
|
+
await writeFile(join(homeDir, file), content, {
|
|
204
|
+
encoding: "utf-8",
|
|
205
|
+
flag: "wx",
|
|
206
|
+
}).catch((error) => {
|
|
207
|
+
if (errCode(error) === "EEXIST")
|
|
208
|
+
return;
|
|
209
|
+
throw error;
|
|
210
|
+
});
|
|
211
|
+
}));
|
|
212
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
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
|
+
function stripCR(line) {
|
|
10
|
+
return line.endsWith("\r") ? line.slice(0, -1) : line;
|
|
11
|
+
}
|
|
12
|
+
function startsWithFenceLine(content) {
|
|
13
|
+
return stripCR(content.split("\n")[0]) === "---";
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Parse an override file. Only a leading `---` fence whose lines are empty or
|
|
17
|
+
* `order: <integer>` is accepted. A leading `---` that does not parse (no
|
|
18
|
+
* closing fence, unknown key, non-integer value) is a malformed override;
|
|
19
|
+
* anything else is pure prose (the whole file as text).
|
|
20
|
+
*/
|
|
21
|
+
export function parseSectionFile(content) {
|
|
22
|
+
const lines = content.split("\n");
|
|
23
|
+
if (stripCR(lines[0] ?? "") !== "---") {
|
|
24
|
+
return { text: content };
|
|
25
|
+
}
|
|
26
|
+
const close = lines.findIndex((line, index) => index > 0 && stripCR(line) === "---");
|
|
27
|
+
if (close < 0) {
|
|
28
|
+
return { text: content, malformed: true, reason: "missing closing fence" };
|
|
29
|
+
}
|
|
30
|
+
let order;
|
|
31
|
+
for (let index = 1; index < close; index++) {
|
|
32
|
+
const line = stripCR(lines[index]);
|
|
33
|
+
if (line.trim() === "")
|
|
34
|
+
continue;
|
|
35
|
+
const key = line.split(":")[0].trim();
|
|
36
|
+
const match = /^order:\s*(-?\d+)\s*$/.exec(line);
|
|
37
|
+
if (!match) {
|
|
38
|
+
if (key === "order") {
|
|
39
|
+
const value = line.slice(line.indexOf(":") + 1).trim();
|
|
40
|
+
return {
|
|
41
|
+
text: content,
|
|
42
|
+
malformed: true,
|
|
43
|
+
reason: `non-integer order '${value}'`,
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
return {
|
|
47
|
+
text: content,
|
|
48
|
+
malformed: true,
|
|
49
|
+
reason: `unknown key '${key}'`,
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
order = Number.parseInt(match[1], 10);
|
|
53
|
+
}
|
|
54
|
+
// Front-matter body: strip leading blank lines after the closing fence so
|
|
55
|
+
// `---\n…\n---\n\nbody` and `---\n…\n---\nbody` parse identically (the
|
|
56
|
+
// materialized preset files carry a blank line after the fence).
|
|
57
|
+
const body = lines.slice(close + 1);
|
|
58
|
+
let bodyStart = 0;
|
|
59
|
+
while (bodyStart < body.length && body[bodyStart].trim() === "")
|
|
60
|
+
bodyStart++;
|
|
61
|
+
return { order, text: body.slice(bodyStart).join("\n") };
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* True when an override file is blank: whitespace-only body and NO front-matter
|
|
65
|
+
* fence (the "I want the default" case). The single source of truth for whether
|
|
66
|
+
* a boot-time materialization pass should re-seed a file. False for prose with
|
|
67
|
+
* content, for any valid fence (including a keyless/empty one — a deliberate
|
|
68
|
+
* blank), and for malformed files.
|
|
69
|
+
*/
|
|
70
|
+
export function isBlankOverride(content) {
|
|
71
|
+
const parsed = parseSectionFile(content);
|
|
72
|
+
return (!parsed.malformed &&
|
|
73
|
+
parsed.order === undefined &&
|
|
74
|
+
parsed.text.trim() === "" &&
|
|
75
|
+
!startsWithFenceLine(content));
|
|
76
|
+
}
|
|
77
|
+
/** True when an override file opens with a leading `---` fence that is malformed. */
|
|
78
|
+
export function isMalformedOverride(content) {
|
|
79
|
+
return parseSectionFile(content).malformed === true;
|
|
80
|
+
}
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolver: IO-light seam owning "first existing candidate wins, blank=skip,
|
|
3
|
+
* malformed=fallback+report" policy for guidance override files.
|
|
4
|
+
*
|
|
5
|
+
* Tested via temp-home FS; materializer stubs this module.
|
|
6
|
+
* @module dsh-better-edit/guidance/resolve
|
|
7
|
+
*/
|
|
8
|
+
import { readFile } from "node:fs/promises";
|
|
9
|
+
import { join } from "node:path";
|
|
10
|
+
import { EDIT_GUIDANCE, READ_GUIDANCE, UNDO_GUIDANCE, } from "../prompts.js";
|
|
11
|
+
import { errCode } from "../utils.js";
|
|
12
|
+
import { isBlankOverride, parseSectionFile } from "./parse.js";
|
|
13
|
+
/**
|
|
14
|
+
* Render one tool's guidance as its intro line, a blank line, then bullets.
|
|
15
|
+
* Uniform across the four sections: no tool-schema description is duplicated
|
|
16
|
+
* (that already reaches the model through the tool catalog).
|
|
17
|
+
*/
|
|
18
|
+
function guidanceText(g) {
|
|
19
|
+
return [g.intro, "", bulletLines(g.lines)].join("\n");
|
|
20
|
+
}
|
|
21
|
+
function bulletLines(lines) {
|
|
22
|
+
return lines.map((line) => `- ${line}`).join("\n");
|
|
23
|
+
}
|
|
24
|
+
/** The three sections, in default-order sequence. */
|
|
25
|
+
export const GUIDANCE_SECTIONS = [
|
|
26
|
+
{
|
|
27
|
+
name: "tool:read",
|
|
28
|
+
file: "read.md",
|
|
29
|
+
defaultOrder: 130,
|
|
30
|
+
renderDefault: () => guidanceText(READ_GUIDANCE),
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
name: "tool:edit",
|
|
34
|
+
file: "edit.md",
|
|
35
|
+
defaultOrder: 131,
|
|
36
|
+
renderDefault: () => guidanceText(EDIT_GUIDANCE),
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
name: "tool:undo_last_edit",
|
|
40
|
+
file: "undo_last_edit.md",
|
|
41
|
+
defaultOrder: 133,
|
|
42
|
+
renderDefault: () => guidanceText(UNDO_GUIDANCE),
|
|
43
|
+
},
|
|
44
|
+
];
|
|
45
|
+
const SECTION_BY_NAME = new Map(GUIDANCE_SECTIONS.map((section) => [section.name, section]));
|
|
46
|
+
/** Render the compiled default text for one section. */
|
|
47
|
+
export function renderSectionDefault(name) {
|
|
48
|
+
const section = SECTION_BY_NAME.get(name);
|
|
49
|
+
if (!section)
|
|
50
|
+
throw new Error(`unknown guidance section: ${name}`);
|
|
51
|
+
return section.renderDefault();
|
|
52
|
+
}
|
|
53
|
+
function overrideCandidates(file, options) {
|
|
54
|
+
const candidates = [];
|
|
55
|
+
if (options.presetId !== undefined) {
|
|
56
|
+
candidates.push(join(options.homeDir, options.presetId, file));
|
|
57
|
+
}
|
|
58
|
+
return candidates;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Resolve one section's guidance: the first override file that exists wins,
|
|
62
|
+
* falling back to the compiled default. A missing or blank file (ENOENT, or
|
|
63
|
+
* whitespace-only with no fence) advances the chain; a malformed file resolves
|
|
64
|
+
* to the compiled default and reports itself; any other read error propagates.
|
|
65
|
+
*/
|
|
66
|
+
export async function resolveSection(name, options) {
|
|
67
|
+
const section = SECTION_BY_NAME.get(name);
|
|
68
|
+
if (!section)
|
|
69
|
+
throw new Error(`unknown guidance section: ${name}`);
|
|
70
|
+
for (const candidate of overrideCandidates(section.file, options)) {
|
|
71
|
+
const content = await readFile(candidate, "utf-8").catch((error) => {
|
|
72
|
+
if (errCode(error) === "ENOENT")
|
|
73
|
+
return undefined;
|
|
74
|
+
throw error;
|
|
75
|
+
});
|
|
76
|
+
if (content === undefined)
|
|
77
|
+
continue;
|
|
78
|
+
const parsed = parseSectionFile(content);
|
|
79
|
+
if (parsed.malformed) {
|
|
80
|
+
// A broken override must never reach the model. Resolve to the
|
|
81
|
+
// compiled default and report the file + parse reason to the caller.
|
|
82
|
+
return {
|
|
83
|
+
order: section.defaultOrder,
|
|
84
|
+
text: section.renderDefault(),
|
|
85
|
+
malformed: {
|
|
86
|
+
file: candidate,
|
|
87
|
+
reason: parsed.reason ?? "malformed override",
|
|
88
|
+
},
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
// Blank (no fence, whitespace-only) means "use the default": advance the
|
|
92
|
+
// fallback chain rather than render an empty section.
|
|
93
|
+
if (isBlankOverride(content))
|
|
94
|
+
continue;
|
|
95
|
+
return { order: parsed.order ?? section.defaultOrder, text: parsed.text };
|
|
96
|
+
}
|
|
97
|
+
return { order: section.defaultOrder, text: section.renderDefault() };
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Resolve all three sections for a preset. `presetId === undefined` skips the
|
|
101
|
+
* `<preset>/` layer and resolves straight to the compiled defaults.
|
|
102
|
+
*/
|
|
103
|
+
export async function composeSections(presetId, homeDir) {
|
|
104
|
+
return Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
105
|
+
const resolved = await resolveSection(section.name, {
|
|
106
|
+
presetId,
|
|
107
|
+
homeDir,
|
|
108
|
+
});
|
|
109
|
+
return {
|
|
110
|
+
name: section.name,
|
|
111
|
+
order: resolved.order,
|
|
112
|
+
text: resolved.text,
|
|
113
|
+
malformed: resolved.malformed,
|
|
114
|
+
};
|
|
115
|
+
}));
|
|
116
|
+
}
|