drawbore 0.1.0 → 0.1.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/lib/prompts.js CHANGED
@@ -1,374 +1,376 @@
1
- // Prompt adapter for the Drawbore installer CLI.
2
- //
3
- // The installer supports two surfaces:
4
- // - a real terminal, where @inquirer/prompts gives arrow-key multiselect
5
- // checkboxes, confirmations with a stated default, and a spinner;
6
- // - a non-TTY stream (pipes, CI, test harnesses), where a small readline
7
- // fallback keeps the same questions answerable line by line.
8
- //
9
- // Both paths return the same values, so the install code never branches on how
10
- // the answer was collected.
11
-
12
- import { createInterface } from "node:readline";
13
-
14
- import { installMarkerFile, notebookDirectory, supportedLocations } from "./installer.js";
15
-
16
- /**
17
- * Build location multiselect choices from a project inspection result.
18
- *
19
- * Nothing starts selected: the user must opt into each harness location
20
- * explicitly. Each choice carries a short state hint (already installed /
21
- * instruction already present / not installed).
22
- *
23
- * @param {{ locations: Array<{ path: string, instructionName: string, instructionExists: boolean, skillsExist: boolean }> }} project
24
- */
25
- export function buildLocationChoices(project) {
26
- return project.locations.map((location) => {
27
- const state = location.skillsExist
28
- ? "already installed"
29
- : location.instructionExists
30
- ? "instruction already present"
31
- : "not installed";
32
- return {
33
- name: `${location.path} — ${state}`,
34
- value: location.path,
35
- checked: false,
36
- };
37
- });
38
- }
39
-
40
- /**
41
- * Build checkbox choices for always-read instruction files. Values are the
42
- * instruction target file names; every choice starts checked.
43
- *
44
- * @param {Array<{ instructionFile: string, exists?: boolean }>} targets
45
- */
46
- export function buildInstructionChoices(targets) {
47
- return targets.map((target) => ({
48
- name: `${target.instructionFile}${target.exists ? " — already exists" : " — will be created"}`,
49
- value: target.instructionFile,
50
- checked: true,
51
- }));
52
- }
53
-
54
- /**
55
- * Create the UI adapter for this process.
56
- *
57
- * `isTTY` is an explicit parameter (not read from process) so tests and
58
- * non-TTY harnesses can force the readline fallback path. An explicit `false`
59
- * always selects the fallback; an explicit `true` requires usable streams.
60
- *
61
- * @param {{ isTTY?: boolean, stdin?: unknown, stdout?: unknown, stderr?: unknown, prompts?: object }} [options]
62
- */
63
- export function createUi({ isTTY, stdin, stdout, stderr, prompts } = {}) {
64
- const input = stdin ?? process.stdin;
65
- const output = stdout ?? process.stdout;
66
- const errorOutput = stderr ?? process.stderr;
67
- const interactive = isTTY ?? (Boolean(input.isTTY) && Boolean(output.isTTY));
68
-
69
- if (interactive) {
70
- return createTtyUi({ stdin: input, stdout: output, stderr: errorOutput, prompts });
71
- }
72
- return createFallbackUi({ stdin: input, stdout: output, stderr: errorOutput });
73
- }
74
-
75
- // ---------------------------------------------------------------------------
76
- // TTY path (@inquirer/prompts)
77
- // ---------------------------------------------------------------------------
78
-
79
- function createTtyUi({ stdin, stdout, stderr, prompts }) {
80
- // One shared loader keeps the dynamic import — and its error translation —
81
- // in exactly one place. Inquirer writes prompts to stderr by default; the
82
- // explicit streams keep the banner (stdout) and prompts (stderr)
83
- // separable and testable. `prompts` may be injected for tests.
84
- async function load() {
85
- if (prompts) return prompts;
86
- try {
87
- return await import("@inquirer/prompts");
88
- } catch (error) {
89
- throw new Error(
90
- `Interactive prompts unavailable (${error.message}). ` +
91
- `Run with explicit flags instead: drawbore init --location .agents --notebook --instruction AGENTS.md`,
92
- );
93
- }
94
- }
95
-
96
- function handlePromptError(error) {
97
- if (error?.name === "ExitPromptError") {
98
- console.error("Installation cancelled. Nothing was installed.");
99
- process.exit(0);
100
- }
101
- throw error instanceof Error ? error : new Error(String(error));
102
- }
103
-
104
- // Hint shown in every prompt message: Ctrl+C (and Ctrl+D) abort via the
105
- // prompts' built-in ExitPromptError handling above. Inquirer reserves
106
- // Ctrl+* for its own shortcuts, so a custom "press q to cancel" key
107
- // cannot coexist with it — Ctrl+C is the cancel key.
108
- const CANCEL_HINT = "(Ctrl+C to cancel)";
109
-
110
- async function selectLocations(choices) {
111
- if (choices.length === 0) {
112
- return [];
113
- }
114
- try {
115
- // @inquirer/prompts has no `multiselect` export — the multi-select
116
- // component is `checkbox`. Using a non-existent name crashes the run.
117
- const { checkbox } = await load();
118
- return await checkbox({
119
- message: `Which harness locations should receive the Drawbore skills? ${CANCEL_HINT}`,
120
- choices,
121
- pageSize: Math.max(4, choices.length),
122
- input: stdin,
123
- output: stderr,
124
- });
125
- } catch (error) {
126
- handlePromptError(error);
127
- }
128
- return [];
129
- }
130
-
131
- async function selectInstructions(choices) {
132
- if (choices.length === 0) {
133
- return [];
134
- }
135
- try {
136
- const { checkbox } = await load();
137
- return await checkbox({
138
- message: `Which instruction files should get the always-on Drawbore guidance? ${CANCEL_HINT}`,
139
- choices,
140
- pageSize: Math.max(4, choices.length),
141
- input: stdin,
142
- output: stderr,
143
- });
144
- } catch (error) {
145
- handlePromptError(error);
146
- }
147
- return [];
148
- }
149
-
150
- async function confirm({ message, defaultValue }) {
151
- try {
152
- const { confirm: promptConfirm } = await load();
153
- return Boolean(
154
- await promptConfirm({
155
- message: `${message} ${CANCEL_HINT}`,
156
- default: defaultValue ?? true,
157
- input: stdin,
158
- output: stderr,
159
- }),
160
- );
161
- } catch (error) {
162
- handlePromptError(error);
163
- }
164
- return false;
165
- }
166
-
167
- return {
168
- renderProjectState: () => {},
169
- selectLocations,
170
- selectInstructions,
171
- confirm,
172
- startSpinner: (message) => createSpinner({ message, stderr }),
173
- close: () => {},
174
- };
175
- }
176
-
177
- // ---------------------------------------------------------------------------
178
- // Fallback path (readline, piped stdin/stdout)
179
- // ---------------------------------------------------------------------------
180
-
181
- function createFallbackUi({ stdin, stdout }) {
182
- const rl = createInterface({ input: stdin, output: stdout });
183
- const queue = [];
184
- const waiters = [];
185
- let closed = false;
186
-
187
- rl.on("line", (line) => {
188
- if (waiters.length > 0) {
189
- waiters.shift()(line);
190
- } else {
191
- queue.push(line);
192
- }
193
- });
194
-
195
- rl.on("close", () => {
196
- closed = true;
197
- while (waiters.length > 0) {
198
- waiters.shift()("");
199
- }
200
- });
201
-
202
- function ask(question) {
203
- stdout.write(question);
204
- if (queue.length > 0) {
205
- return Promise.resolve(queue.shift());
206
- }
207
- if (closed) {
208
- return Promise.resolve("");
209
- }
210
- return new Promise((resolve) => waiters.push(resolve));
211
- }
212
-
213
- function isDefaultYes(answer) {
214
- const normalized = answer.trim().toLowerCase();
215
- return normalized === "" || ["y", "yes"].includes(normalized);
216
- }
217
-
218
- async function confirm({ message, defaultValue }) {
219
- const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
220
- const answer = await ask(`${message}${suffix}`);
221
- const normalized = answer.trim().toLowerCase();
222
- if (isCancelKeyword(normalized)) {
223
- console.log("Installation cancelled. Nothing was installed.");
224
- process.exit(0);
225
- }
226
- if (normalized === "") {
227
- return Boolean(defaultValue);
228
- }
229
- return ["y", "yes"].includes(normalized);
230
- }
231
-
232
- async function selectLocations(choices) {
233
- const answer = await ask(
234
- 'Install skills into which locations? Comma-separated, or "none" [none]: ',
235
- );
236
-
237
- const requested = answer
238
- .split(",")
239
- .map((value) => value.trim())
240
- .filter(Boolean)
241
- .filter((value) => value !== "none");
242
-
243
- if (requested.some(isCancelKeyword)) {
244
- console.log("Installation cancelled. Nothing was installed.");
245
- process.exit(0);
246
- }
247
-
248
- const offered = new Set(choices.map((choice) => choice.value));
249
- const allowed = offered.size > 0 ? offered : new Set(Object.keys(supportedLocations));
250
- const invalid = requested.filter((location) => !allowed.has(location));
251
- if (invalid.length > 0) {
252
- throw new Error(`Unsupported location(s): ${invalid.join(", ")}`);
253
- }
254
-
255
- return [...new Set(requested)];
256
- }
257
-
258
- async function selectInstructions(choices) {
259
- if (choices.length === 0) {
260
- return [];
261
- }
262
-
263
- const selected = [];
264
- for (const choice of choices) {
265
- const preserved = choice.name.includes("already exists") ? " The existing file will be preserved." : "";
266
- const answer = await ask(
267
- `Add the always-on Drawbore instruction to ${choice.value}?${preserved} [Y/n] `,
268
- );
269
- if (isCancelKeyword(answer.trim().toLowerCase())) {
270
- console.log("Installation cancelled. Nothing was installed.");
271
- process.exit(0);
272
- }
273
- if (isDefaultYes(answer)) {
274
- selected.push(choice.value);
275
- }
276
- }
277
- return selected;
278
- }
279
-
280
- function isCancelKeyword(normalized) {
281
- return ["cancel", "q", "esc", "back"].includes(normalized);
282
- }
283
-
284
- return {
285
- renderProjectState: (project) => {
286
- console.log("\nSupported harness locations:");
287
- for (const location of project.locations) {
288
- const state = location.skillsExist ? "skills already present" : "not installed";
289
- const instruction = location.instructionExists ? "instruction exists" : "instruction absent";
290
- console.log(`- ${location.path} (${state}; ${instruction})`);
291
- }
292
- },
293
- selectLocations,
294
- selectInstructions,
295
- confirm,
296
- startSpinner: () => () => {},
297
- close() {
298
- rl.close();
299
- },
300
- };
301
- }
302
-
303
- // ---------------------------------------------------------------------------
304
- // Spinner
305
- // ---------------------------------------------------------------------------
306
-
307
- const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
308
-
309
- // Spinner lives on stderr (stdout is reserved for the machine-readable
310
- // result) and only animates when stderr is a TTY; otherwise it is a no-op so
311
- // pipes never see half-overwritten lines. The stop function clears the line.
312
- export function createSpinner({ message, stderr }) {
313
- if (!stderr.isTTY) {
314
- return () => {};
315
- }
316
-
317
- let frame = 0;
318
- let active = true;
319
- const tick = () => {
320
- if (!active) return;
321
- stderr.write(`\r${SPINNER_FRAMES[frame % SPINNER_FRAMES.length]} ${message}`);
322
- frame += 1;
323
- };
324
- tick();
325
- const timer = setInterval(tick, 80);
326
- timer.unref();
327
-
328
- return () => {
329
- active = false;
330
- clearInterval(timer);
331
- stderr.write("\r");
332
- };
333
- }
334
-
335
- /**
336
- * Render the final "Installed:" summary block. Used by both paths so the
337
- * result text stays byte-identical for non-TTY consumers.
338
- */
339
- export function formatInstallResult(
340
- selectedLocations,
341
- notebookCreated,
342
- instructionFiles,
343
- preservedSkillFiles = [],
344
- replacedSkillFiles = [],
345
- ) {
346
- const lines = ["Installed:"];
347
- for (const location of selectedLocations) {
348
- lines.push(`- skills: ${location}/skills/`);
349
- }
350
- if (notebookCreated) {
351
- lines.push(`- notebook: ${notebookDirectory}/`);
352
- }
353
- for (const instructionFile of [...new Set(instructionFiles)]) {
354
- lines.push(`- instruction: ${instructionFile}`);
355
- }
356
- lines.push(`- marker: ${installMarkerFile}`);
357
- if (replacedSkillFiles.length > 0) {
358
- lines.push("");
359
- lines.push("Replaced packaged skill files:");
360
- for (const file of [...new Set(replacedSkillFiles)]) {
361
- lines.push(`- ${file}`);
362
- }
363
- }
364
- if (preservedSkillFiles.length > 0) {
365
- lines.push("");
366
- lines.push("Preserved existing differing skill files:");
367
- for (const file of [...new Set(preservedSkillFiles)]) {
368
- lines.push(`- ${file}`);
369
- }
370
- }
371
- lines.push("");
372
- lines.push("Run the discover skill in your agent to propose the first durable records.");
373
- return lines.join("\n");
1
+ // Prompt adapter for the Drawbore installer CLI.
2
+ //
3
+ // The installer supports two surfaces:
4
+ // - a real terminal, where @inquirer/prompts gives arrow-key multiselect
5
+ // checkboxes, confirmations with a stated default, and a spinner;
6
+ // - a non-TTY stream (pipes, CI, test harnesses), where a small readline
7
+ // fallback keeps the same questions answerable line by line.
8
+ //
9
+ // Both paths return the same values, so the install code never branches on how
10
+ // the answer was collected.
11
+
12
+ import { createInterface } from "node:readline";
13
+
14
+ import { installMarkerFile, notebookDirectory, supportedLocations } from "./installer.js";
15
+
16
+ /**
17
+ * Build location multiselect choices from a project inspection result.
18
+ *
19
+ * Nothing starts selected: the user must opt into each harness location
20
+ * explicitly. Each choice carries a short state hint (already installed /
21
+ * instruction already present / not installed).
22
+ *
23
+ * @param {{ locations: Array<{ path: string, instructionName: string, instructionExists: boolean, skillsExist: boolean }> }} project
24
+ */
25
+ export function buildLocationChoices(project) {
26
+ return project.locations.map((location) => {
27
+ const state = location.skillsExist
28
+ ? "already installed"
29
+ : location.instructionExists
30
+ ? "instruction already present"
31
+ : "not installed";
32
+ return {
33
+ name: `${location.path} — ${state}`,
34
+ value: location.path,
35
+ checked: false,
36
+ };
37
+ });
38
+ }
39
+
40
+ /**
41
+ * Build checkbox choices for always-read instruction files. Values are the
42
+ * instruction target file names; every choice starts checked.
43
+ *
44
+ * @param {Array<{ instructionFile: string, exists?: boolean }>} targets
45
+ */
46
+ export function buildInstructionChoices(targets) {
47
+ return targets.map((target) => ({
48
+ name: `${target.instructionFile}${target.exists ? " — already exists" : " — will be created"}`,
49
+ value: target.instructionFile,
50
+ checked: true,
51
+ }));
52
+ }
53
+
54
+ /**
55
+ * Create the UI adapter for this process.
56
+ *
57
+ * `isTTY` is an explicit parameter (not read from process) so tests and
58
+ * non-TTY harnesses can force the readline fallback path. An explicit `false`
59
+ * always selects the fallback; an explicit `true` requires usable streams.
60
+ *
61
+ * @param {{ isTTY?: boolean, stdin?: unknown, stdout?: unknown, stderr?: unknown, prompts?: object }} [options]
62
+ */
63
+ export function createUi({ isTTY, stdin, stdout, stderr, prompts } = {}) {
64
+ const input = stdin ?? process.stdin;
65
+ const output = stdout ?? process.stdout;
66
+ const errorOutput = stderr ?? process.stderr;
67
+ const interactive = isTTY ?? (Boolean(input.isTTY) && Boolean(output.isTTY));
68
+
69
+ if (interactive) {
70
+ return createTtyUi({ stdin: input, stdout: output, stderr: errorOutput, prompts });
71
+ }
72
+ return createFallbackUi({ stdin: input, stdout: output, stderr: errorOutput });
73
+ }
74
+
75
+ // ---------------------------------------------------------------------------
76
+ // TTY path (@inquirer/prompts)
77
+ // ---------------------------------------------------------------------------
78
+
79
+ function createTtyUi({ stdin, stdout, stderr, prompts }) {
80
+ // One shared loader keeps the dynamic import — and its error translation —
81
+ // in exactly one place. Inquirer writes prompts to stderr by default; the
82
+ // explicit streams keep the banner (stdout) and prompts (stderr)
83
+ // separable and testable. `prompts` may be injected for tests.
84
+ async function load() {
85
+ if (prompts) return prompts;
86
+ try {
87
+ return await import("@inquirer/prompts");
88
+ } catch (error) {
89
+ throw new Error(
90
+ `Interactive prompts unavailable (${error.message}). ` +
91
+ `Run with explicit flags instead: drawbore init --location .agents --notebook --instruction AGENTS.md`,
92
+ );
93
+ }
94
+ }
95
+
96
+ function handlePromptError(error) {
97
+ if (error?.name === "ExitPromptError") {
98
+ console.error("Installation cancelled. Nothing was installed.");
99
+ process.exit(0);
100
+ }
101
+ throw error instanceof Error ? error : new Error(String(error));
102
+ }
103
+
104
+ // Hint shown in every prompt message: Ctrl+C (and Ctrl+D) abort via the
105
+ // prompts' built-in ExitPromptError handling above. Inquirer reserves
106
+ // Ctrl+* for its own shortcuts, so a custom "press q to cancel" key
107
+ // cannot coexist with it — Ctrl+C is the cancel key.
108
+ const CANCEL_HINT = "(Ctrl+C to cancel)";
109
+
110
+ async function selectLocations(choices) {
111
+ if (choices.length === 0) {
112
+ return [];
113
+ }
114
+ try {
115
+ // @inquirer/prompts has no `multiselect` export — the multi-select
116
+ // component is `checkbox`. Using a non-existent name crashes the run.
117
+ const { checkbox } = await load();
118
+ return await checkbox({
119
+ message: `Which harness locations should receive the Drawbore skills? ${CANCEL_HINT}`,
120
+ choices,
121
+ pageSize: Math.max(4, choices.length),
122
+ input: stdin,
123
+ output: stderr,
124
+ });
125
+ } catch (error) {
126
+ handlePromptError(error);
127
+ }
128
+ return [];
129
+ }
130
+
131
+ async function selectInstructions(choices) {
132
+ if (choices.length === 0) {
133
+ return [];
134
+ }
135
+ try {
136
+ const { checkbox } = await load();
137
+ return await checkbox({
138
+ message: `Which instruction files should get the always-on Drawbore guidance? ${CANCEL_HINT}`,
139
+ choices,
140
+ pageSize: Math.max(4, choices.length),
141
+ input: stdin,
142
+ output: stderr,
143
+ });
144
+ } catch (error) {
145
+ handlePromptError(error);
146
+ }
147
+ return [];
148
+ }
149
+
150
+ async function confirm({ message, defaultValue }) {
151
+ try {
152
+ const { confirm: promptConfirm } = await load();
153
+ return Boolean(
154
+ await promptConfirm({
155
+ message: `${message} ${CANCEL_HINT}`,
156
+ default: defaultValue ?? true,
157
+ input: stdin,
158
+ output: stderr,
159
+ }),
160
+ );
161
+ } catch (error) {
162
+ handlePromptError(error);
163
+ }
164
+ return false;
165
+ }
166
+
167
+ return {
168
+ isInteractive: true,
169
+ renderProjectState: () => {},
170
+ selectLocations,
171
+ selectInstructions,
172
+ confirm,
173
+ startSpinner: (message) => createSpinner({ message, stderr }),
174
+ close: () => {},
175
+ };
176
+ }
177
+
178
+ // ---------------------------------------------------------------------------
179
+ // Fallback path (readline, piped stdin/stdout)
180
+ // ---------------------------------------------------------------------------
181
+
182
+ function createFallbackUi({ stdin, stdout }) {
183
+ const rl = createInterface({ input: stdin, output: stdout });
184
+ const queue = [];
185
+ const waiters = [];
186
+ let closed = false;
187
+
188
+ rl.on("line", (line) => {
189
+ if (waiters.length > 0) {
190
+ waiters.shift()(line);
191
+ } else {
192
+ queue.push(line);
193
+ }
194
+ });
195
+
196
+ rl.on("close", () => {
197
+ closed = true;
198
+ while (waiters.length > 0) {
199
+ waiters.shift()("");
200
+ }
201
+ });
202
+
203
+ function ask(question) {
204
+ stdout.write(question);
205
+ if (queue.length > 0) {
206
+ return Promise.resolve(queue.shift());
207
+ }
208
+ if (closed) {
209
+ return Promise.resolve("");
210
+ }
211
+ return new Promise((resolve) => waiters.push(resolve));
212
+ }
213
+
214
+ function isDefaultYes(answer) {
215
+ const normalized = answer.trim().toLowerCase();
216
+ return normalized === "" || ["y", "yes"].includes(normalized);
217
+ }
218
+
219
+ async function confirm({ message, defaultValue }) {
220
+ const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
221
+ const answer = await ask(`${message}${suffix}`);
222
+ const normalized = answer.trim().toLowerCase();
223
+ if (isCancelKeyword(normalized)) {
224
+ console.log("Installation cancelled. Nothing was installed.");
225
+ process.exit(0);
226
+ }
227
+ if (normalized === "") {
228
+ return Boolean(defaultValue);
229
+ }
230
+ return ["y", "yes"].includes(normalized);
231
+ }
232
+
233
+ async function selectLocations(choices) {
234
+ const answer = await ask(
235
+ 'Install skills into which locations? Comma-separated, or "none" [none]: ',
236
+ );
237
+
238
+ const requested = answer
239
+ .split(",")
240
+ .map((value) => value.trim())
241
+ .filter(Boolean)
242
+ .filter((value) => value !== "none");
243
+
244
+ if (requested.some(isCancelKeyword)) {
245
+ console.log("Installation cancelled. Nothing was installed.");
246
+ process.exit(0);
247
+ }
248
+
249
+ const offered = new Set(choices.map((choice) => choice.value));
250
+ const allowed = offered.size > 0 ? offered : new Set(Object.keys(supportedLocations));
251
+ const invalid = requested.filter((location) => !allowed.has(location));
252
+ if (invalid.length > 0) {
253
+ throw new Error(`Unsupported location(s): ${invalid.join(", ")}`);
254
+ }
255
+
256
+ return [...new Set(requested)];
257
+ }
258
+
259
+ async function selectInstructions(choices) {
260
+ if (choices.length === 0) {
261
+ return [];
262
+ }
263
+
264
+ const selected = [];
265
+ for (const choice of choices) {
266
+ const preserved = choice.name.includes("already exists") ? " The existing file will be preserved." : "";
267
+ const answer = await ask(
268
+ `Add the always-on Drawbore instruction to ${choice.value}?${preserved} [Y/n] `,
269
+ );
270
+ if (isCancelKeyword(answer.trim().toLowerCase())) {
271
+ console.log("Installation cancelled. Nothing was installed.");
272
+ process.exit(0);
273
+ }
274
+ if (isDefaultYes(answer)) {
275
+ selected.push(choice.value);
276
+ }
277
+ }
278
+ return selected;
279
+ }
280
+
281
+ function isCancelKeyword(normalized) {
282
+ return ["cancel", "q", "esc", "back"].includes(normalized);
283
+ }
284
+
285
+ return {
286
+ isInteractive: false,
287
+ renderProjectState: (project) => {
288
+ console.log("\nSupported harness locations:");
289
+ for (const location of project.locations) {
290
+ const state = location.skillsExist ? "skills already present" : "not installed";
291
+ const instruction = location.instructionExists ? "instruction exists" : "instruction absent";
292
+ console.log(`- ${location.path} (${state}; ${instruction})`);
293
+ }
294
+ },
295
+ selectLocations,
296
+ selectInstructions,
297
+ confirm,
298
+ startSpinner: () => () => {},
299
+ close() {
300
+ rl.close();
301
+ },
302
+ };
303
+ }
304
+
305
+ // ---------------------------------------------------------------------------
306
+ // Spinner
307
+ // ---------------------------------------------------------------------------
308
+
309
+ const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
310
+
311
+ // Spinner lives on stderr (stdout is reserved for the machine-readable
312
+ // result) and only animates when stderr is a TTY; otherwise it is a no-op so
313
+ // pipes never see half-overwritten lines. The stop function clears the line.
314
+ export function createSpinner({ message, stderr }) {
315
+ if (!stderr.isTTY) {
316
+ return () => {};
317
+ }
318
+
319
+ let frame = 0;
320
+ let active = true;
321
+ const tick = () => {
322
+ if (!active) return;
323
+ stderr.write(`\r${SPINNER_FRAMES[frame % SPINNER_FRAMES.length]} ${message}`);
324
+ frame += 1;
325
+ };
326
+ tick();
327
+ const timer = setInterval(tick, 80);
328
+ timer.unref();
329
+
330
+ return () => {
331
+ active = false;
332
+ clearInterval(timer);
333
+ stderr.write("\r");
334
+ };
335
+ }
336
+
337
+ /**
338
+ * Render the final "Installed:" summary block. Used by both paths so the
339
+ * result text stays byte-identical for non-TTY consumers.
340
+ */
341
+ export function formatInstallResult(
342
+ selectedLocations,
343
+ notebookCreated,
344
+ instructionFiles,
345
+ preservedSkillFiles = [],
346
+ replacedSkillFiles = [],
347
+ ) {
348
+ const lines = ["Installed:"];
349
+ for (const location of selectedLocations) {
350
+ lines.push(`- skills: ${location}/skills/`);
351
+ }
352
+ if (notebookCreated) {
353
+ lines.push(`- notebook: ${notebookDirectory}/`);
354
+ }
355
+ for (const instructionFile of [...new Set(instructionFiles)]) {
356
+ lines.push(`- instruction: ${instructionFile}`);
357
+ }
358
+ lines.push(`- marker: ${installMarkerFile}`);
359
+ if (replacedSkillFiles.length > 0) {
360
+ lines.push("");
361
+ lines.push("Replaced packaged skill files:");
362
+ for (const file of [...new Set(replacedSkillFiles)]) {
363
+ lines.push(`- ${file}`);
364
+ }
365
+ }
366
+ if (preservedSkillFiles.length > 0) {
367
+ lines.push("");
368
+ lines.push("Preserved existing differing skill files:");
369
+ for (const file of [...new Set(preservedSkillFiles)]) {
370
+ lines.push(`- ${file}`);
371
+ }
372
+ }
373
+ lines.push("");
374
+ lines.push("Run the discover skill in your agent to propose the first durable records.");
375
+ return lines.join("\n");
374
376
  }