@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.
- package/LICENSE +22 -0
- package/README.md +451 -0
- package/extensions/distill/README.md +86 -0
- package/extensions/distill/auto-setup.ts +392 -0
- package/extensions/distill/distill-prompt.md +58 -0
- package/extensions/distill/distill-prompt.ts +212 -0
- package/extensions/distill/distill-workspace.ts +1248 -0
- package/extensions/distill/index.ts +1828 -0
- package/extensions/distill/scripts/distill-wrapper.sh +1472 -0
- package/extensions/distill/scripts-paths.ts +21 -0
- package/extensions/distill/session-touched-files.ts +216 -0
- package/extensions/distill/should-distill-on-shutdown.ts +68 -0
- package/extensions/napkin-context/index.ts +259 -0
- package/package.json +71 -0
- package/skills/napkin/SKILL.md +44 -0
|
@@ -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
|
+
}
|