@cad0p/pi-napkin 0.2.4-20260518.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.
@@ -0,0 +1,392 @@
1
+ /**
2
+ * First-run auto-setup for auto-distill.
3
+ *
4
+ * Auto-distill needs the vault to be a git repo with a `.gitignore` that
5
+ * excludes its ephemeral state (distill worktrees, Obsidian workspace-local
6
+ * caches). Vaults typically ship without any of this — we scaffold it at
7
+ * `session_start` when `distill.enabled` is true.
8
+ *
9
+ * PR #12 (agent-driven merge): pre-PR-12 auto-distill also installed an
10
+ * `*.md merge=napkin-distill-merge` rule in `.gitattributes` to route
11
+ * concurrent-distill conflicts through an LLM merge driver. PR #12 deleted
12
+ * that driver — the distill agent now resolves merges itself in its
13
+ * worktree, so the rule is no longer needed. New vaults never get the rule
14
+ * installed. Existing vaults that already have it are left alone (manual
15
+ * cleanup; the rule becomes inert once the driver script is gone — git
16
+ * silently falls back to its built-in merge driver). See design.md
17
+ * "Migration" for rationale.
18
+ *
19
+ * Design contract:
20
+ * - Idempotent: re-running on an already-set-up vault is a no-op (returns
21
+ * `{ initialized: false, scaffolded: [] }`).
22
+ * - Non-destructive: never clobbers existing `.gitignore` content; only
23
+ * appends missing lines.
24
+ * - Fail-soft: returns `{ error }` instead of throwing so the caller can
25
+ * surface a notify() and keep the session alive.
26
+ */
27
+
28
+ import { spawnSync } from "node:child_process";
29
+ import * as fs from "node:fs";
30
+ import * as path from "node:path";
31
+
32
+ import { GIT_SUBCOMMAND_TIMEOUT_MS } from "./distill-workspace";
33
+
34
+ /**
35
+ * Lines appended to `<vault>/.gitignore` when scaffolding. Order is stable so
36
+ * diff noise stays minimal on re-runs. Each group has a section-comment
37
+ * header — we match on the non-comment lines for idempotence, the comments
38
+ * are cosmetic.
39
+ */
40
+ export const GITIGNORE_LINES: readonly string[] = [
41
+ "# napkin-distill ephemeral state",
42
+ ".napkin/distill/",
43
+ "",
44
+ "# Obsidian workspace-local state",
45
+ ".obsidian/workspace*.json",
46
+ ".obsidian/cache",
47
+ ".obsidian/.trash/",
48
+ "",
49
+ "# Local tmp/cache",
50
+ "search-cache.json",
51
+ ".DS_Store",
52
+ "",
53
+ "# Common secrets — belt-and-braces for vaults that end up alongside dev",
54
+ "# work. Auto-distill commits 'git add .' on first run; these patterns",
55
+ "# keep credentials out of the initial commit even if a user's vault",
56
+ "# happens to contain them.",
57
+ ".env",
58
+ ".env.local",
59
+ ".env.*.local",
60
+ "*.pem",
61
+ "*.key",
62
+ "id_rsa",
63
+ "id_ecdsa",
64
+ "id_ed25519",
65
+ "secrets.json",
66
+ ".aws/credentials",
67
+ ];
68
+
69
+ /**
70
+ * Result of {@link ensureVaultReadyForAutoDistill}.
71
+ *
72
+ * - `initialized`: a brand-new `git init` ran (vault had no `.git/` before).
73
+ * - `scaffolded`: files whose contents were created or modified. Callers use
74
+ * this to decide whether to surface a first-run notify to the user.
75
+ * - `error`: populated on fail-soft paths (git init failed, filesystem
76
+ * errors writing the scaffolding, legacy-layout refusal). If set, other
77
+ * fields reflect partial progress.
78
+ * - `legacyLayout`: populated when auto-setup refused to scaffold because
79
+ * the vault is using napkin's legacy embedded layout (`configPath ===
80
+ * contentPath`). The worktree-based concurrency architecture relies on
81
+ * napkin's findVault resolving cwd=worktree to the worktree itself —
82
+ * which only works for subdir-layout vaults (those that track a
83
+ * `.napkin/config.json`). `error` is set to `"legacy-embedded-layout"`
84
+ * so callers can branch on it.
85
+ */
86
+ export interface SetupResult {
87
+ initialized: boolean;
88
+ scaffolded: string[];
89
+ error?: string;
90
+ legacyLayout?: {
91
+ /** Absolute path to the vault's `.napkin/` (= contentPath for legacy). */
92
+ configPath: string;
93
+ };
94
+ /**
95
+ * Set to `true` when the vault had a `.git/` but no commits (HEAD
96
+ * unresolvable) and auto-setup synthesized an empty initial commit to
97
+ * make HEAD valid. Distinct from `initialized` (which is "we ran
98
+ * `git init`"): this path fires on an existing-but-empty repo where
99
+ * someone ran `git init` by hand and never committed. Without the
100
+ * seed, `git worktree add ... HEAD` in createDistillWorktree would
101
+ * fail with `fatal: invalid reference: HEAD` — the bug that
102
+ * motivated FB-2.
103
+ */
104
+ seededCommit?: boolean;
105
+ }
106
+
107
+ /**
108
+ * Sentinel value set in `SetupResult.error` when auto-setup refuses to
109
+ * scaffold because the vault is using napkin's legacy embedded layout.
110
+ * Exported so callers (session_start handler, tests) can branch on the
111
+ * exact sentinel instead of pattern-matching on the free-form message.
112
+ */
113
+ export const LEGACY_EMBEDDED_LAYOUT_ERROR = "legacy-embedded-layout";
114
+
115
+ /**
116
+ * Minimal vault handle this module accepts. Mirrors
117
+ * `StaleCleanupVault` in `distill-workspace.ts` — keeps the callsite
118
+ * symmetric: both setup and cleanup take the same vault shape and
119
+ * neither forces the caller to construct a full Napkin instance.
120
+ *
121
+ * Both paths are required: legacy-embedded-layout detection needs to
122
+ * compare `configPath` and `contentPath` directly (legacy vaults have
123
+ * them equal; subdir vaults have them distinct).
124
+ */
125
+ export interface SetupVault {
126
+ contentPath: string;
127
+ configPath: string;
128
+ }
129
+
130
+ /**
131
+ * Run `git` in `cwd` and return `{ status, stdout, stderr }`. Does not throw
132
+ * on non-zero exit — we translate failures to `SetupResult.error`.
133
+ */
134
+ function runGit(
135
+ cwd: string,
136
+ args: string[],
137
+ ): { status: number | null; stdout: string; stderr: string } {
138
+ // `env: process.env` is required for Bun: unlike Node, Bun's spawnSync
139
+ // does NOT propagate mutations to `process.env` to the child unless
140
+ // `env` is passed explicitly (it snapshots env at runtime startup).
141
+ // Passing process.env here is a no-op on Node and restores Node-compat
142
+ // semantics on Bun so tests can control git identity via env vars.
143
+ const r = spawnSync("git", args, {
144
+ cwd,
145
+ encoding: "utf-8",
146
+ timeout: GIT_SUBCOMMAND_TIMEOUT_MS,
147
+ env: process.env,
148
+ });
149
+ return {
150
+ status: r.status,
151
+ stdout: r.stdout || "",
152
+ stderr: r.stderr || r.error?.message || "",
153
+ };
154
+ }
155
+
156
+ /**
157
+ * Merge `newLines` into the file at `filePath`, appending only the
158
+ * non-comment, non-blank lines that aren't already present. A line is
159
+ * considered "present" if it appears verbatim anywhere in the existing file
160
+ * (leading/trailing whitespace trimmed for comparison). Returns `true` if
161
+ * the file was created or modified.
162
+ *
163
+ * Creates the file if it doesn't exist. Preserves the existing content
164
+ * verbatim otherwise — we never rewrite or re-order user lines.
165
+ */
166
+ function mergeLines(filePath: string, newLines: readonly string[]): boolean {
167
+ const existed = fs.existsSync(filePath);
168
+ const existing = existed ? fs.readFileSync(filePath, "utf-8") : "";
169
+ const existingSet = new Set(
170
+ existing
171
+ .split("\n")
172
+ .map((l) => l.trim())
173
+ .filter((l) => l.length > 0 && !l.startsWith("#")),
174
+ );
175
+
176
+ const toAppend: string[] = [];
177
+ let sawMeaningful = false;
178
+ for (const line of newLines) {
179
+ const trimmed = line.trim();
180
+ if (trimmed.length === 0 || trimmed.startsWith("#")) {
181
+ // Only keep headers/spacers if there's at least one real line to append
182
+ // below them. We can't decide that until we've scanned the whole block,
183
+ // so buffer optimistically and trim at the end.
184
+ toAppend.push(line);
185
+ continue;
186
+ }
187
+ if (!existingSet.has(trimmed)) {
188
+ toAppend.push(line);
189
+ sawMeaningful = true;
190
+ }
191
+ }
192
+
193
+ if (!sawMeaningful) {
194
+ // File already has everything meaningful — no change needed even if we
195
+ // accumulated section headers in `toAppend`.
196
+ return false;
197
+ }
198
+
199
+ // Prefix with a blank line if the existing file doesn't end with one, so
200
+ // appended sections are visually separated.
201
+ let prefix = "";
202
+ if (existed && existing.length > 0 && !existing.endsWith("\n")) prefix = "\n";
203
+ else if (existed && existing.length > 0 && !existing.endsWith("\n\n"))
204
+ prefix = "\n";
205
+
206
+ const body = `${toAppend.join("\n")}\n`;
207
+ fs.writeFileSync(filePath, existing + prefix + body);
208
+ return true;
209
+ }
210
+
211
+ /**
212
+ * Ensure `<vaultPath>` is a git repo with a `.gitignore` that covers
213
+ * auto-distill's needs. Called once per `session_start` when
214
+ * `distill.enabled` is true.
215
+ *
216
+ * Lifecycle:
217
+ * 0. Refuse if the vault uses napkin's legacy embedded layout
218
+ * (`configPath === contentPath`). Worktree-based concurrency doesn't
219
+ * work on legacy layouts because the branch can't track a `.napkin/`
220
+ * subdir that findVault could resolve to. Returns `{ error:
221
+ * "legacy-embedded-layout", legacyLayout }` without touching git.
222
+ * 1. If `.git/` is missing → `git init`. Failure here aborts with `error`.
223
+ * 2. Merge scaffolding lines into `.gitignore` (idempotent; no-op if
224
+ * already present).
225
+ * 3. If anything changed:
226
+ * - fresh init → `git add .` + commit `"napkin: initial vault commit
227
+ * (auto-distill setup)"`
228
+ * - existing repo → `git add .gitignore` + commit
229
+ * `"napkin: scaffold auto-distill git config"`
230
+ *
231
+ * Returned `scaffolded` always uses vault-relative paths so notify messages
232
+ * are compact and portable.
233
+ */
234
+ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
235
+ const vaultPath = vault.contentPath;
236
+
237
+ // Legacy-embedded layout is incompatible with the worktree-based
238
+ // concurrency architecture. In a legacy vault (`~/.napkin/`), the
239
+ // vault IS the `.napkin/` directory — `configPath === contentPath`.
240
+ // When a distill subprocess runs with `cwd = worktree` (a checkout of
241
+ // a `distill/*` branch that does NOT track a `.napkin/` subdir),
242
+ // napkin's `findVault` walks past the worktree and resolves to the
243
+ // user's REAL vault via the global config fallback. Writes bypass the
244
+ // worktree entirely, making the concurrency guarantee a no-op.
245
+ //
246
+ // Refuse to scaffold here so session_start can surface a migration
247
+ // notify. Manual `/distill` still works on any layout (it doesn't go
248
+ // through this path).
249
+ //
250
+ // Detection mirrors napkin's own `resolveVaultLayout` semantics: subdir
251
+ // layout sets `contentPath` via `vault.root` (distinct from `configPath`),
252
+ // while legacy embedded layout has no `vault.root` and defaults both to
253
+ // the `.napkin/` dir. See `@cad0p/napkin` `dist/utils/vault.js`.
254
+ if (vault.configPath === vault.contentPath) {
255
+ return {
256
+ initialized: false,
257
+ scaffolded: [],
258
+ error: LEGACY_EMBEDDED_LAYOUT_ERROR,
259
+ legacyLayout: { configPath: vault.configPath },
260
+ };
261
+ }
262
+
263
+ const gitDir = path.join(vaultPath, ".git");
264
+ let initialized = false;
265
+
266
+ if (!fs.existsSync(gitDir)) {
267
+ const init = runGit(vaultPath, ["init", "-q", "-b", "main"]);
268
+ if (init.status !== 0) {
269
+ return {
270
+ initialized: false,
271
+ scaffolded: [],
272
+ error: `git init failed: ${init.stderr.trim() || "unknown error"}`,
273
+ };
274
+ }
275
+ initialized = true;
276
+ }
277
+
278
+ const scaffolded: string[] = [];
279
+
280
+ try {
281
+ const giPath = path.join(vaultPath, ".gitignore");
282
+ if (mergeLines(giPath, GITIGNORE_LINES)) scaffolded.push(".gitignore");
283
+ // PR #12: no `.gitattributes` scaffolding. Pre-PR-12 we wrote an
284
+ // `*.md merge=napkin-distill-merge` line; the agent-driven merge
285
+ // architecture has no driver to register.
286
+ } catch (err) {
287
+ const msg = err instanceof Error ? err.message : String(err);
288
+ return {
289
+ initialized,
290
+ scaffolded,
291
+ error: `failed to write scaffolding: ${msg}`,
292
+ };
293
+ }
294
+
295
+ if (initialized) {
296
+ // Fresh init: commit the entire vault so auto-distill has a HEAD to
297
+ // branch from. `git add .` respects the just-written .gitignore so we
298
+ // don't accidentally stage `.napkin/distill/` (the per-worktree
299
+ // session fork) or common secret files (see GITIGNORE_LINES). Distill
300
+ // worktrees themselves live OUTSIDE the vault now (XDG cache), so
301
+ // there's no in-vault worktrees/ path to exclude.
302
+ const add = runGit(vaultPath, ["add", "."]);
303
+ if (add.status !== 0) {
304
+ return {
305
+ initialized,
306
+ scaffolded,
307
+ error: `git add failed: ${add.stderr.trim() || "unknown error"}`,
308
+ };
309
+ }
310
+ const commit = runGit(vaultPath, [
311
+ "commit",
312
+ "-q",
313
+ "-m",
314
+ "napkin: initial vault commit (auto-distill setup)",
315
+ ]);
316
+ if (commit.status !== 0) {
317
+ return {
318
+ initialized,
319
+ scaffolded,
320
+ error: `git commit failed: ${commit.stderr.trim() || "unknown error"}`,
321
+ };
322
+ }
323
+ } else if (scaffolded.length > 0) {
324
+ // Existing repo: only stage the scaffolding files so we don't sweep in
325
+ // the user's unrelated working changes.
326
+ const add = runGit(vaultPath, ["add", ...scaffolded]);
327
+ if (add.status !== 0) {
328
+ return {
329
+ initialized,
330
+ scaffolded,
331
+ error: `git add failed: ${add.stderr.trim() || "unknown error"}`,
332
+ };
333
+ }
334
+ const commit = runGit(vaultPath, [
335
+ "commit",
336
+ "-q",
337
+ "-m",
338
+ "napkin: scaffold auto-distill git config",
339
+ ]);
340
+ if (commit.status !== 0) {
341
+ return {
342
+ initialized,
343
+ scaffolded,
344
+ error: `git commit failed: ${commit.stderr.trim() || "unknown error"}`,
345
+ };
346
+ }
347
+ }
348
+
349
+ // HEAD-valid invariant: createDistillWorktree requires HEAD to resolve
350
+ // to a commit. The paths above (fresh init OR existing repo + scaffolded
351
+ // files) produce a commit; the idempotent path (existing repo, nothing
352
+ // to scaffold) does NOT — so a vault where someone ran `git init` by
353
+ // hand and never committed leaves HEAD unresolvable. Seed an empty
354
+ // initial commit so `git worktree add ... HEAD` has something to pin to.
355
+ // This also covers the narrow window where `git init` succeeded above
356
+ // (we set `initialized = true`) but scaffolding wrote zero lines
357
+ // (`.gitignore` already present with our exact content) — that would
358
+ // fall into neither branch and leave a commit-less repo.
359
+ let seededCommit: SetupResult["seededCommit"];
360
+ const headAfter = runGit(vaultPath, ["rev-parse", "--verify", "HEAD"]);
361
+ if (headAfter.status !== 0) {
362
+ const seed = runGit(vaultPath, [
363
+ "commit",
364
+ "--allow-empty",
365
+ "-q",
366
+ "-m",
367
+ "napkin: initial vault commit (auto-distill setup)",
368
+ ]);
369
+ if (seed.status !== 0) {
370
+ return {
371
+ initialized,
372
+ scaffolded,
373
+ error: `git seed commit failed: ${seed.stderr.trim() || "unknown error"}`,
374
+ };
375
+ }
376
+ seededCommit = true;
377
+ }
378
+
379
+ return { initialized, scaffolded, seededCommit };
380
+ }
381
+
382
+ /**
383
+ * Count the files tracked in the vault's git index. Used by the first-run
384
+ * notify so the user sees a concrete scope ("42 files tracked") rather
385
+ * than the abstract scaffolding list. Returns `-1` if git fails or the
386
+ * vault isn't a repo; callers treat negative as "don't mention a count".
387
+ */
388
+ export function countTrackedFiles(vaultPath: string): number {
389
+ const res = runGit(vaultPath, ["ls-files"]);
390
+ if (res.status !== 0) return -1;
391
+ return res.stdout.split("\n").filter((l) => l.length > 0).length;
392
+ }
@@ -0,0 +1,58 @@
1
+ Your distill content lives in the git worktree at {{worktreePath}}. Use `git -C {{worktreePath}}` for all git operations there — your shell cwd is NOT the worktree. Edit files in the worktree by absolute path under `{{worktreePath}}/...` (or `cd {{worktreePath}}` first if your tool supports it).
2
+
3
+ For the distill-content phase (steps 1-6), edit files only inside `{{worktreePath}}`; do not edit files under `{{vaultPath}}`. Writing distill content to `{{vaultPath}}` directly bypasses the worktree's isolation and causes the merge in steps 7-8 to silently include none of your changes. The integration phase (steps 7-9) explicitly runs `git -C {{vaultPath}}` commands to squash and push — those are correct and required, not a violation of this rule.
4
+
5
+ Distill this conversation into the napkin vault, then integrate your changes back into the main vault yourself. The wrapper that invoked you will only validate the result; it will NOT run merge, squash, push, or cleanup on your behalf.
6
+
7
+ 1. `napkin overview` — learn the vault structure and what exists. Read `_about.md` files to understand what each folder is for. These are short folder descriptions (1-2 paragraphs) explaining what kinds of notes belong there — see existing ones for style.
8
+ 2. `napkin template list` and `napkin template read` — learn the note formats.
9
+ 3. Identify what's worth capturing. The vault structure and templates tell you what kinds of notes belong.
10
+ 4. For each note:
11
+ a. `napkin search` for the topic — if a note already covers it, `napkin append` instead of creating a duplicate
12
+ b. Create new notes with `napkin create`, following the template format; use the relevant folder path
13
+ c. Add `[[wikilinks]]` to related notes
14
+ 5. Append a brief summary of key activities and decisions to today's daily note in the relevant namespace (e.g. `{namespace}/daily/YYYY-MM-DD.md`). Follow existing patterns. Create it if it doesn't exist.
15
+ 6. Frontmatter convention: when you create a note that replaces an older one, add `supersedes: ["path/to/old/note.md"]` to its frontmatter. A future janitor will archive the superseded note. Leave the field empty or omit it for notes that stand alone.
16
+
17
+ Be selective. Only capture knowledge useful to someone working on this project later. Skip meta-discussion, tool output, and chatter.
18
+
19
+ 7. Integrate with main. If you decided nothing in this conversation merits capturing (per "Be selective" above), skip steps 7-9 entirely and exit — the wrapper will classify this as `no-content` and surface a warning to the user. Otherwise, from the worktree at {{worktreePath}}, commit your distilled content first if you haven't already:
20
+
21
+ git -C {{worktreePath}} add -A
22
+ git -C {{worktreePath}} commit -m "distill: <one-line summary>"
23
+
24
+ Then merge {{defaultBranch}} into your distill branch:
25
+
26
+ git -C {{worktreePath}} merge --no-edit {{defaultBranch}}
27
+
28
+ `--no-edit` accepts git's auto-generated merge commit message non-interactively; without it, git would open `core.editor` on a clean auto-merge and your bash tool (which has no TTY) would hang or fail.
29
+
30
+ If conflicts arise, you will see files with standard `<<<<<<<`, `=======`, `>>>>>>>` markers. Resolve each by editing the file in place to produce the correct merged content. Use the conversation history above to inform your choices — you have full context on what content you intended to add. Once all markers are gone:
31
+
32
+ git -C {{worktreePath}} add .
33
+ git -C {{worktreePath}} commit --no-edit
34
+
35
+ If `git -C {{worktreePath}} merge --no-edit {{defaultBranch}}` reports "Already up to date" (no merge commit), that's fine — proceed.
36
+
37
+ 8. Squash to main. From the main vault at {{vaultPath}}, switch to the default branch and squash-merge your branch:
38
+
39
+ git -C {{vaultPath}} checkout {{defaultBranch}}
40
+ git -C {{vaultPath}} merge --squash {{branchName}}
41
+ git -C {{vaultPath}} commit -m "distill: <one-line summary of what you captured>"
42
+
43
+ Use `--squash` to keep main's history linear (one commit per distill). If `git merge --squash` produces no staged changes (e.g. your distill content was already on main), skip the commit step — there's nothing new to land.
44
+
45
+ 9. Push if origin exists. Check `git -C {{vaultPath}} remote -v`. If `origin/{{defaultBranch}}` is configured, push your changes:
46
+
47
+ git -C {{vaultPath}} push origin {{defaultBranch}}
48
+
49
+ If push fails because the remote moved, recover with pull-merge-push (NOT pull-rebase):
50
+
51
+ git -C {{vaultPath}} pull --no-rebase origin {{defaultBranch}}
52
+ git -C {{vaultPath}} push origin {{defaultBranch}}
53
+
54
+ `--no-rebase` forces merge semantics regardless of any global `pull.rebase` config the user may have set.
55
+
56
+ NEVER use `--force` or `--force-with-lease`. If push fails for any reason and you cannot recover, stop — do not loop indefinitely. The wrapper will detect local-only state and surface a warning to the user.
57
+
58
+ Report progress concisely as you go. Stop when steps 1-9 are complete.
@@ -0,0 +1,212 @@
1
+ /**
2
+ * Distill prompt loader.
3
+ *
4
+ * The agent-driven distill prompt lives as markdown at
5
+ * `extensions/distill/distill-prompt.md`, with template placeholders the
6
+ * wrapper resolves at spawn time. This module reads that .md at runtime,
7
+ * substitutes the placeholders, and returns the resolved string for the
8
+ * wrapper to pass to `pi -p`.
9
+ *
10
+ * Why markdown + a loader (PR #12 design — "DISTILL_PROMPT location"):
11
+ * - Easier to edit / iterate the prompt without touching code
12
+ * - Markdown rendering in editors makes the prompt readable as prose
13
+ * - Snapshot tests assert prompt content directly against the .md
14
+ * - Bundled with npm publish via `package.json` `files` entry
15
+ *
16
+ * The loader is strict on placeholder coverage: every required placeholder
17
+ * MUST be present in the .md OR the loader throws. This protects against
18
+ * silent drift where a refactor renames a placeholder in the .md but
19
+ * leaves the TS-side input shape intact, sending an unresolved
20
+ * `{{worktreePath}}` literal to the agent. Per the methodology guide's
21
+ * never-deferrable categories, "stale references to renamed concepts" are
22
+ * a fix-now class — failing fast at load time keeps them out of agent
23
+ * prompts entirely.
24
+ */
25
+
26
+ import * as fs from "node:fs";
27
+ import * as path from "node:path";
28
+ import { fileURLToPath } from "node:url";
29
+
30
+ const _here = path.dirname(fileURLToPath(import.meta.url));
31
+
32
+ /** Absolute path to the distill prompt markdown file. */
33
+ export const DISTILL_PROMPT_PATH: string = path.join(
34
+ _here,
35
+ "distill-prompt.md",
36
+ );
37
+
38
+ /**
39
+ * Inputs to {@link buildDistillPrompt}. All four placeholders MUST be
40
+ * provided; passing an empty string is disallowed because that would
41
+ * produce an agent prompt with `git merge ` (empty branch name) or
42
+ * `cd ` (empty path) — silent corruption rather than fail-fast.
43
+ */
44
+ export interface DistillPromptInputs {
45
+ /** Absolute path to the per-distill git worktree. Substituted for `{{worktreePath}}`. */
46
+ worktreePath: string;
47
+ /** Absolute path to the main vault (the worktree's parent repo). Substituted for `{{vaultPath}}`. */
48
+ vaultPath: string;
49
+ /** Distill branch name, e.g. `distill/abc123-1700000000000`. Substituted for `{{branchName}}`. */
50
+ branchName: string;
51
+ /** Vault's default mainline branch (`main`, `master`, ...). Substituted for `{{defaultBranch}}`. */
52
+ defaultBranch: string;
53
+ }
54
+
55
+ /**
56
+ * Required placeholders the .md template must contain. Order matches the
57
+ * order they appear in the template; the validator below iterates this
58
+ * list to surface a precise diagnostic when one is missing.
59
+ */
60
+ const REQUIRED_PLACEHOLDERS = [
61
+ "{{worktreePath}}",
62
+ "{{vaultPath}}",
63
+ "{{branchName}}",
64
+ "{{defaultBranch}}",
65
+ ] as const;
66
+
67
+ /**
68
+ * Validate a single substitution input. Used for every field of
69
+ * {@link DistillPromptInputs}. Hard rejects:
70
+ *
71
+ * 1. Non-string / empty string — silent prompt corruption (e.g.
72
+ * `git merge ` with empty branch name) is worse than a loud
73
+ * validation throw.
74
+ * 2. ASCII control characters (NUL, BEL, BS, TAB, LF, CR, ESC, DEL,
75
+ * …; the `\x00–\x1F` and `\x7F` ranges). A `\n` in
76
+ * `worktreePath` would inject a newline into the agent's prompt,
77
+ * letting an attacker who controls a single field break out of
78
+ * one prompt-step and inject prose into another (prompt-
79
+ * injection class). NUL bytes truncate strings on most C-side
80
+ * consumers (the wrapper's `printf`, `git`'s argv parsing). TAB
81
+ * isn't strictly malicious but its inclusion in agent prompts
82
+ * breaks the `git -C "<tab>worktree"` quoting we rely on.
83
+ * 3. Mustache-style `{{` or `}}` runs — collide with the
84
+ * placeholder syntax this loader uses. A vault path that
85
+ * contained `{{worktreePath}}` would silently re-substitute
86
+ * itself on a second pass; even though we don't multi-pass
87
+ * today, defending the input shape lets future refactors of
88
+ * the substitution loop stay safe.
89
+ *
90
+ * Defense-in-depth (SEC-A-5): the JS-side caller already controls
91
+ * three of the four inputs (`worktreePath`, `branchName`,
92
+ * `defaultBranch` come from `createDistillWorkspace` /
93
+ * `detectDefaultBranch` which produce well-formed strings).
94
+ * `vaultPath` originates from the user's config but is
95
+ * `path.resolve`d before reaching here. So the realistic threat
96
+ * surface is narrow — but the validator is cheap, the failure mode
97
+ * is "throw with a clear message", and a future caller that bypasses
98
+ * the helpers (or a malformed config) would otherwise let bad input
99
+ * reach the agent prompt.
100
+ *
101
+ * Slashes (`/`), spaces, hyphens, dots, and underscores are all
102
+ * allowed: `feat/foo` branch names and `~/My Vault/notes` paths must
103
+ * pass.
104
+ */
105
+ function validateInput(name: string, value: unknown): asserts value is string {
106
+ if (typeof value !== "string" || value.length === 0) {
107
+ throw new Error(
108
+ `buildDistillPrompt: input '${name}' must be a non-empty string (got ${JSON.stringify(value)})`,
109
+ );
110
+ }
111
+ // Reject ASCII control chars (\x00–\x1F and \x7F). A literal `\n`
112
+ // in any input would break out of the prompt step it's embedded
113
+ // in — classic prompt-injection. JSON.stringify the value in the
114
+ // error so the offending char is visible (escaped) in the message.
115
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control chars IS the validator's job
116
+ if (/[\x00-\x1F\x7F]/.test(value)) {
117
+ throw new Error(
118
+ `buildDistillPrompt: input '${name}' contains control characters; reject (got ${JSON.stringify(value)})`,
119
+ );
120
+ }
121
+ // Reject placeholder-syntax collisions. A vault path that contained
122
+ // `{{worktreePath}}` would silently re-substitute on a second pass
123
+ // — defense-in-depth for future refactors of the substitution loop.
124
+ if (value.includes("{{") || value.includes("}}")) {
125
+ throw new Error(
126
+ `buildDistillPrompt: input '${name}' contains placeholder-syntax characters '{{' or '}}' (got ${JSON.stringify(value)})`,
127
+ );
128
+ }
129
+ }
130
+
131
+ /**
132
+ * Read a distill prompt markdown template from `promptPath` and
133
+ * substitute placeholders. The path-injected core of the loader.
134
+ *
135
+ * Test seam (CI-A-5): production callers should use
136
+ * {@link buildDistillPrompt}, which delegates to this helper with
137
+ * {@link DISTILL_PROMPT_PATH}. Tests that need to exercise template
138
+ * error paths (missing placeholder, empty template) point this at a
139
+ * tmpdir copy of the .md so the shipped artifact is never mutated.
140
+ *
141
+ * @throws Error if the .md file is missing, empty, or omits any required
142
+ * placeholder. Throws if any input value is empty (per the
143
+ * {@link DistillPromptInputs} contract).
144
+ *
145
+ * Pure function aside from the .md read: the loader does not cache, so
146
+ * tests that mutate the file (or replace it via mocked fs) see the
147
+ * fresh contents on each call. The .md is small (a few KB); re-reading
148
+ * it on each spawn is cheap relative to the agent task itself (60s+).
149
+ */
150
+ export function buildDistillPromptFromFile(
151
+ promptPath: string,
152
+ inputs: DistillPromptInputs,
153
+ ): string {
154
+ for (const [key, value] of Object.entries(inputs)) {
155
+ validateInput(key, value);
156
+ }
157
+
158
+ let template: string;
159
+ try {
160
+ template = fs.readFileSync(promptPath, "utf-8");
161
+ } catch (err) {
162
+ throw new Error(
163
+ `buildDistillPrompt: failed to read prompt template at ${promptPath}: ${(err as Error).message}`,
164
+ );
165
+ }
166
+ if (template.length === 0) {
167
+ throw new Error(
168
+ `buildDistillPrompt: prompt template at ${promptPath} is empty`,
169
+ );
170
+ }
171
+
172
+ for (const placeholder of REQUIRED_PLACEHOLDERS) {
173
+ if (!template.includes(placeholder)) {
174
+ throw new Error(
175
+ `buildDistillPrompt: prompt template at ${promptPath} is missing required placeholder '${placeholder}'`,
176
+ );
177
+ }
178
+ }
179
+
180
+ // Map placeholder → input key. Keep this aligned with REQUIRED_PLACEHOLDERS
181
+ // so the missing-placeholder error and the substitution loop never drift.
182
+ const substitutions: Array<[string, string]> = [
183
+ ["{{worktreePath}}", inputs.worktreePath],
184
+ ["{{vaultPath}}", inputs.vaultPath],
185
+ ["{{branchName}}", inputs.branchName],
186
+ ["{{defaultBranch}}", inputs.defaultBranch],
187
+ ];
188
+
189
+ let result = template;
190
+ for (const [placeholder, value] of substitutions) {
191
+ // String#replaceAll on each placeholder; values are not regex-special
192
+ // because they're filesystem paths or branch names. Even if a path
193
+ // contained a `$` or `\`, replaceAll on a literal string (not regex)
194
+ // is escape-safe.
195
+ result = result.replaceAll(placeholder, value);
196
+ }
197
+
198
+ return result;
199
+ }
200
+
201
+ /**
202
+ * Read the shipped distill prompt markdown and substitute placeholders.
203
+ * Public API — production callers should use this. Delegates to
204
+ * {@link buildDistillPromptFromFile} with the bundled .md path.
205
+ *
206
+ * @throws Error if the .md file is missing, empty, or omits any required
207
+ * placeholder. Throws if any input value is empty (per the
208
+ * {@link DistillPromptInputs} contract).
209
+ */
210
+ export function buildDistillPrompt(inputs: DistillPromptInputs): string {
211
+ return buildDistillPromptFromFile(DISTILL_PROMPT_PATH, inputs);
212
+ }