pi-soly 1.9.2 → 1.10.0

package/ask/index.ts

@@ -165,6 +165,11 @@ export default function piAskExtension(pi: ExtensionAPI) {
 							if (!ctx.hasUI) return undefined;
 							return (await ctx.ui.input(req.title, req.placeholder)) ?? undefined;
 						},
+						// Bridge for the `n` note dialog. Reuses the same text-input UI.
+						onRequestNote: async (req) => {
+							if (!ctx.hasUI) return undefined;
+							return (await ctx.ui.input(req.title, req.placeholder)) ?? undefined;
+						},
 						title: `pi-ask — ${params.questions.length} question${params.questions.length > 1 ? "s" : ""}`,
 					});
 				},
@@ -184,14 +189,16 @@ export default function piAskExtension(pi: ExtensionAPI) {
 			}
 
 			const answers = result.answers ?? {};
+			const notes = result.notes ?? {};
 			// Pretty-print for the LLM
 			const out: string[] = ["User answers:"];
 			for (let i = 0; i < params.questions.length; i++) {
 				const q = params.questions[i];
 				if (!q) continue;
 				const a = answers[i];
+				let line: string;
 				if (a === undefined) {
-					out.push(`  Q${i + 1} (${q.header}): (no answer)`);
+					line = `  Q${i + 1} (${q.header}): (no answer)`;
 				} else if (Array.isArray(a)) {
 					const parts: string[] = [];
 					for (const item of a) {
@@ -201,17 +208,22 @@ export default function piAskExtension(pi: ExtensionAPI) {
 							parts.push(`"${item}"`);
 						}
 					}
-					out.push(`  Q${i + 1} (${q.header}) [multi]: ${parts.join(", ")}`);
+					line = `  Q${i + 1} (${q.header}) [multi]: ${parts.join(", ")}`;
 				} else if (typeof a === "number") {
-					out.push(`  Q${i + 1} (${q.header}): ${q.options[a]?.label ?? `?${a}`}`);
+					line = `  Q${i + 1} (${q.header}): ${q.options[a]?.label ?? `?${a}`}`;
 				} else {
-					out.push(`  Q${i + 1} (${q.header}) [Other]: "${a}"`);
+					line = `  Q${i + 1} (${q.header}) [Other]: "${a}"`;
+				}
+				// Append note if present
+				if (notes[i]) {
+					line += `  // note: "${notes[i]}"`;
 				}
+				out.push(line);
 			}
 
 			return {
 				content: [{ type: "text", text: out.join("\n") }],
-				details: { answers },
+				details: { answers, notes: Object.keys(notes).length > 0 ? notes : undefined },
 			};
 		},
 	});

package/ask/picker.ts

@@ -31,6 +31,13 @@ export interface AskOption {
 	label: string;
 	description?: string;
 	recommended?: boolean;
+	/** Optional preview content shown in a side panel when this option is
+	 *  focused. Use markdown or plain text to show code snippets, structure
+	 *  examples, or elaboration of what the option entails.
+	 *
+	 *  Example:
+	 *    preview: "```ts\nclass Auth {\n  token: string\n}\n```" */
+	preview?: string;
 }
 
 export interface AskQuestion {
@@ -59,6 +66,10 @@ export interface AskProResult {
 	cancelled?: boolean;
 	/** Map of question index → answer. Single: number | string. Multi: (number | string)[] */
 	answers?: Record<number, AskAnswer | AskMultiAnswer>;
+	/** Optional free-text notes the user added to specific questions.
+	 *  Keyed by question index. Added when the user pressed `n` after
+	 *  picking an option and typed a note. */
+	notes?: Record<number, string>;
 }
 
 /** Options for the text-input dialog opened when "Other…" is picked. */
@@ -80,6 +91,10 @@ interface AskProComponentDeps {
 	 *  option is hidden even when `allowOther: true` (caller should ensure
 	 *  the dependency is present if it advertises allowOther). */
 	onRequestInput?: (req: AskProInputRequest) => Promise<string | undefined>;
+	/** Open a text-input dialog for adding a note to the current question
+	 *  (triggered by pressing `n`). Returns the typed text, or undefined
+	 *  if cancelled. If omitted, the `n` shortcut is a no-op. */
+	onRequestNote?: (req: AskProInputRequest) => Promise<string | undefined>;
 }
 
 // ---------------------------------------------------------------------------
@@ -107,12 +122,15 @@ export class AskProComponent extends Container {
 	private keybindings: KeybindingsManager;
 	private done: (result: AskProResult) => void;
 	private onRequestInput?: (req: AskProInputRequest) => Promise<string | undefined>;
+	private onRequestNote?: (req: AskProInputRequest) => Promise<string | undefined>;
 	private title: string;
 
 	private currentIndex = 0;
 	private selectedIndex = 0;
 	/** answers[questionIdx] = AskAnswer (single) or AskMultiAnswer (multi). */
 	private answers = new Map<number, AskAnswer | AskMultiAnswer>();
+	/** notes[questionIdx] = free-text note added by user (via `n` key). */
+	private notes = new Map<number, string>();
 	/** Set true once `done` is called — further input is ignored. */
 	private completed = false;
 	/** Set while a text-input dialog is awaiting the user's reply. */
@@ -120,6 +138,7 @@ export class AskProComponent extends Container {
 
 	private tabsText!: Text;
 	private bodyContainer!: Container;
+	private previewText!: Text;
 	private footerText!: Text;
 
 	constructor(deps: AskProComponentDeps) {
@@ -129,6 +148,7 @@ export class AskProComponent extends Container {
 		this.keybindings = deps.keybindings;
 		this.done = deps.done;
 		this.onRequestInput = deps.onRequestInput;
+		this.onRequestNote = deps.onRequestNote;
 		this.title = deps.title ?? "pi-ask";
 
 		const titleText = new Text(this.theme.fg("accent", this.theme.bold(this.title)), 1, 0);
@@ -194,6 +214,11 @@ export class AskProComponent extends Container {
 		const q = this.questions[this.currentIndex];
 		if (!q) return;
 
+		// Compute the current preview (from the option under the cursor).
+		// Shown side-by-side with the option list via pad-right.
+		const currentPreview = this.currentPreviewLines();
+		const hasPreview = currentPreview.length > 0;
+
 		// Question line: "Q1 of 3: <question>"
 		this.bodyContainer.addChild(
 			new Text(
@@ -397,6 +422,12 @@ export class AskProComponent extends Container {
 			// Single-select: Enter is the action key
 			parts.push(this.theme.fg("accent", isLast ? "⏎ submit" : "⏎ next"));
 		}
+		// `n` hint: add/edit note (only if dep is wired)
+		if (this.onRequestNote) {
+			const hasNote = this.notes.has(this.currentIndex);
+			const hint = hasNote ? "n ✓note" : "n note";
+			parts.push(this.theme.fg(hasNote ? "success" : "dim", hint));
+		}
 		parts.push(this.theme.fg("dim", "esc cancel"));
 		return parts.join("   ");
 	}
@@ -565,6 +596,13 @@ export class AskProComponent extends Container {
 			}
 			return;
 		}
+
+		// `n` — add/edit a free-text note for the current question.
+		// Requires onRequestNote dep; otherwise ignored.
+		if (keyData === "n" && this.onRequestNote) {
+			void this.requestNoteInput();
+			return;
+		}
 	}
 
 	private handlePick(optionIdx: number): void {
@@ -659,14 +697,54 @@ export class AskProComponent extends Container {
 		}
 	}
 
+	/** Open a text-input dialog to add/edit a note for the current question.
+	 *  Triggered by the `n` key. Pre-fills with any existing note so the
+	 *  user can edit it. An empty submission clears the note. */
+	private async requestNoteInput(): Promise<void> {
+		if (!this.onRequestNote) return;
+		const q = this.questions[this.currentIndex];
+		if (!q) return;
+		this.awaitingInput = true;
+		const existing = this.notes.get(this.currentIndex) ?? "";
+		const text = await this.onRequestNote({
+			title: q.header,
+			prompt: `Add a note to your answer for: ${q.question}`,
+			placeholder: existing || "Add context, edge cases, or reasoning…",
+		});
+		this.awaitingInput = false;
+		if (text === undefined) {
+			// Cancelled — keep existing note, just redraw
+			this.repaint();
+			return;
+		}
+		const trimmed = text.trim();
+		if (trimmed === "") {
+			// Empty submission clears the note
+			this.notes.delete(this.currentIndex);
+		} else {
+			this.notes.set(this.currentIndex, trimmed);
+		}
+		this.repaint();
+	}
+
 	private submit(): void {
 		if (!this.allAnswered()) return;
 		const answers: Record<number, AskAnswer | AskMultiAnswer> = {};
 		for (let i = 0; i < this.questions.length; i++) {
 			answers[i] = this.answers.get(i) as AskAnswer | AskMultiAnswer;
 		}
+		// Include notes only if at least one was added
+		const notes: Record<number, string> = {};
+		let hasNotes = false;
+		for (let i = 0; i < this.questions.length; i++) {
+			const n = this.notes.get(i);
+			if (n) {
+				notes[i] = n;
+				hasNotes = true;
+			}
+		}
 		this.completed = true;
-		this.done({ answers });
+		this.done(hasNotes ? { answers, notes } : { answers });
 	}
 
 	// -------------------------------------------------------------------------
@@ -678,6 +756,103 @@ export class AskProComponent extends Container {
 		this.completed = true;
 		this.awaitingInput = false;
 	}
+
+	// -----------------------------------------------------------------------
+	// Side-by-side render: stack picker column (left) with preview column
+	// (right) row-by-row. Each visible body row gets padded to SPLIT_COL and
+	// the matching preview row is appended. If no preview is set, the left
+	// column takes the full width (no padding).
+	// -----------------------------------------------------------------------
+	private static readonly SPLIT_COL = 60; // picker column width when preview is present
+	private static readonly PREVIEW_COL = 60; // preview column width
+
+	/** Lines of preview content for the option currently under the cursor.
+	 *  Returns [] when no option is focused or the option has no preview. */
+	private currentPreviewLines(): string[] {
+		const q = this.questions[this.currentIndex];
+		if (!q) return [];
+		// Only real options carry previews (not "Other…")
+		if (this.selectedIndex < 0 || this.selectedIndex >= q.options.length) return [];
+		const opt = q.options[this.selectedIndex];
+		if (!opt?.preview) return [];
+		// Trim and split on newlines; drop leading/trailing blank lines.
+		const lines = opt.preview
+			.replace(/\r\n/g, "\n")
+			.split("\n")
+			.map((l) => l.trimEnd());
+		while (lines.length > 0 && lines[0]?.trim() === "") lines.shift();
+		while (lines.length > 0 && lines[lines.length - 1]?.trim() === "") lines.pop();
+		return lines;
+	}
+
+	/** Override render to produce a side-by-side layout when a preview is
+	 *  present. Falls back to default Container render otherwise. */
+	render(width: number): string[] {
+		const superLines = super.render(width);
+		const previewLines = this.currentPreviewLines();
+		if (previewLines.length === 0) return superLines;
+
+		// We need to find which body lines belong to the option list and
+		// merge the preview next to them. Simpler approach: append a preview
+		// block below the picker body, styled as a framed right-aligned panel.
+		// True side-by-side would require row index tracking which Container
+		// doesn't expose; the framed block is visually distinct and avoids
+		// fragile index math.
+		const splitCol = Math.min(AskProComponent.SPLIT_COL, Math.floor(width * 0.6));
+		const previewWidth = Math.max(30, width - splitCol - 3);
+		const border = this.theme.fg("dim", "│");
+
+		// Wrap preview lines to previewWidth
+		const wrapped: string[] = [];
+		for (const line of previewLines) {
+			if (line.length === 0) {
+				wrapped.push("");
+				continue;
+			}
+			// Simple greedy word wrap
+			const words = line.split(" ");
+			let cur = "";
+			for (const w of words) {
+				if (cur.length === 0) {
+					cur = w;
+				} else if (cur.length + 1 + w.length <= previewWidth) {
+					cur += " " + w;
+				} else {
+					wrapped.push(cur);
+					cur = w;
+				}
+			}
+			if (cur) wrapped.push(cur);
+		}
+
+		// Insert preview as a side panel: pad each picker line to splitCol,
+		// then add a vertical border and the matching preview line.
+		// We do this for ALL super lines so the preview spans the picker's
+		// full height.
+		const result: string[] = [];
+		// Header row above the preview content
+		result.push("".padEnd(splitCol) + " " + border + " " + this.theme.fg("dim", "— preview —"));
+		for (let i = 0; i < superLines.length; i++) {
+			const superLine = superLines[i] ?? "";
+			// Strip ANSI for width measurement
+			const visibleLen = superLine.replace(/\x1b\[[0-9;]*m/g, "").length;
+			const pad = Math.max(1, splitCol - visibleLen);
+			let row = superLine + " ".repeat(pad) + border + " ";
+			const pLine = wrapped[i];
+			if (pLine !== undefined) {
+				row += this.theme.fg("text", pLine);
+			}
+			result.push(row);
+		}
+		// If preview has more lines than the picker, append them below
+		if (wrapped.length > superLines.length) {
+			for (let i = superLines.length; i < wrapped.length; i++) {
+				const pLine = wrapped[i] ?? "";
+				result.push(" ".repeat(splitCol + 1) + border + " " + this.theme.fg("text", pLine));
+			}
+		}
+		return result;
+	}
 }
 
 /** Type guard for the public component. */

package/ask/prompt.ts

@@ -30,8 +30,12 @@ DON'T use it for:
 - When the user already gave a clear answer — don't second-guess
 - Trivial clarifications — use plain text first, escalate to \`ask_pro\` only if the answer matters
 
-Keyboard in the picker: \`↑↓\` navigate, \`1-N\` instant-pick, \`Tab\` next question, \`Space\` toggle (multi-select only), \`Enter\` confirm/advance/submit, \`Esc\` cancel.
+Keyboard in the picker: \`↑↓\` navigate, \`1-N\` instant-pick, \`Tab\` next question, \`Space\` toggle (multi-select only), \`Enter\` confirm/advance/submit, \`n\` add a free-text note to the current question, \`Esc\` cancel.
 
-Schema reminder: \`questions: [{ header, question, options: [{label, description?, recommended?}], multiSelect? }]\`. Mark exactly one option \`recommended: true\` per question when you have a default.
+Schema reminder: \`questions: [{ header, question, options: [{label, description?, recommended?, preview?}], multiSelect? }]\`. Mark exactly one option \`recommended: true\` per question when you have a default.
+
+**Option previews:** \`option.preview\` (markdown/plain string) shows in a side panel next to the option list while that option is focused. Use it when the question is about a code structure, API shape, or concrete example — show a small snippet of what each option entails so the user can decide without asking follow-ups. Example: when asking "how should we model auth?", each option's preview can show the relevant type signature.
+
+**Notes:** the user can press \`n\` after picking an answer to attach a free-text note (edge cases, constraints, reasoning). The note is returned to you as \`// note: \"...\"\` next to the chosen answer. Treat it as a hard constraint.
 `;
 }

package/ask/tests/picker.test.ts

@@ -586,3 +586,165 @@ describe("AskProComponent — Other… option (allowOther)", () => {
 		expect(picker.getSelectedIndex()).toBeLessThan(2);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// Option previews (side-by-side)
+// ---------------------------------------------------------------------------
+
+describe("AskProComponent — option previews", () => {
+	test("currentPreviewLines returns [] when option has no preview", () => {
+		const { picker } = setup();
+		// Type-level access: currentPreviewLines is private; verify via render
+		// (no preview lines means render falls back to super.render width-only)
+		const lines = picker.render(80);
+		// Just verify it doesn't throw and returns some lines
+		expect(lines.length).toBeGreaterThan(0);
+	});
+
+	test("render includes preview content when option has preview", () => {
+		const qsWithPreview: AskQuestion[] = [
+			{
+				header: "Model",
+				question: "Which schema?",
+				options: [
+					{
+						label: "Relational",
+						description: "Postgres + strict schema",
+						preview: "CREATE TABLE users (\n  id SERIAL PRIMARY KEY,\n  email TEXT NOT NULL\n);",
+					},
+					{ label: "Document", description: "MongoDB" },
+				],
+			},
+		];
+		const { picker } = setup(qsWithPreview);
+		const lines = picker.render(100);
+		const joined = lines.join("\n");
+		// Preview content should appear in the rendered output
+		expect(joined).toContain("CREATE TABLE");
+		expect(joined).toContain("preview");
+	});
+
+	test("preview disappears when focused option has none", () => {
+		const qsWithPreview: AskQuestion[] = [
+			{
+				header: "Model",
+				question: "Which schema?",
+				options: [
+					{
+						label: "Relational",
+						description: "Postgres",
+						preview: "CREATE TABLE users (id INT);",
+					},
+					{ label: "Document", description: "MongoDB" },
+				],
+			},
+		];
+		const { picker } = setup(qsWithPreview);
+		// Focus option 0 (has preview)
+		picker.handleInput("j"); // wait, default 0 already; move to 1
+		picker.handleInput("j"); // option 1 (no preview)
+		const lines = picker.render(100);
+		const joined = lines.join("\n");
+		// No preview lines for option without preview
+		expect(joined).not.toContain("CREATE TABLE");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Notes (`n` key)
+// ---------------------------------------------------------------------------
+
+describe("AskProComponent — notes (n key)", () => {
+	test("n is a no-op when onRequestNote is not provided", () => {
+		const { picker } = setup();
+		// Should not throw, no effect
+		expect(() => picker.handleInput("n")).not.toThrow();
+	});
+
+	test("n opens note dialog when onRequestNote is provided", async () => {
+		let noteRequestCount = 0;
+		let resolveNote: (value: string | undefined) => void = () => {};
+		const picker = new AskProComponent({
+			questions: sampleQuestions,
+			theme,
+			keybindings,
+			done: () => {},
+			onRequestNote: async () => {
+				noteRequestCount++;
+				return new Promise<string | undefined>((r) => {
+					resolveNote = r;
+				});
+			},
+		});
+		// `n` should trigger note request
+		expect(noteRequestCount).toBe(0);
+		picker.handleInput("n");
+		// Microtask to let async start
+		await Promise.resolve();
+		expect(noteRequestCount).toBe(1);
+		// Resolve with a note
+		resolveNote("only for prod, use TLS");
+		await Promise.resolve();
+	});
+
+	test("note is included in submit result", async () => {
+		let doneResult: AskProResult | null = null;
+		const pendingNotes: Array<(v: string | undefined) => void> = [];
+		const picker = new AskProComponent({
+			questions: sampleQuestions,
+			theme,
+			keybindings,
+			done: (r) => {
+				doneResult = r;
+			},
+			onRequestNote: async () => {
+				return new Promise<string | undefined>((resolve) => {
+					pendingNotes.push(resolve);
+				});
+			},
+		});
+		// Pick Q1 → advance to Q2
+		picker.handleInput("1");
+		// Add note to Q2
+		picker.handleInput("n");
+		// Wait for the promise to register
+		await Promise.resolve();
+		await Promise.resolve();
+		expect(pendingNotes.length).toBe(1);
+		pendingNotes[0]!("rotate keys monthly");
+		// Wait for the dialog to settle
+		await Promise.resolve();
+		await Promise.resolve();
+		// Submit Q2 (last question, all answered)
+		picker.handleInput("1");
+		expect(doneResult).not.toBeNull();
+		const result = doneResult as AskProResult | null;
+		expect(result?.notes).toBeDefined();
+		expect(result?.notes?.[1]).toBe("rotate keys monthly");
+	});
+
+	test("empty note submission clears existing note", async () => {
+		let resolveNote: (value: string | undefined) => void = () => {};
+		const picker = new AskProComponent({
+			questions: sampleQuestions,
+			theme,
+			keybindings,
+			done: () => {},
+			onRequestNote: async () => {
+				return new Promise<string | undefined>((r) => {
+					resolveNote = r;
+				});
+			},
+		});
+		// Add a note
+		picker.handleInput("n");
+		resolveNote("first note");
+		await Promise.resolve();
+		// Clear it with empty
+		picker.handleInput("n");
+		resolveNote("   ");
+		await Promise.resolve();
+		// No crash — note cleared
+		expect(() => picker.render(80)).not.toThrow();
+	});
+});

package/commands.ts

@@ -51,6 +51,7 @@ export interface CommandUI {
 	notify: (text: string, kind?: "info" | "warning" | "error") => void;
 	select: (label: string, options: string[]) => Promise<number | null>;
 	confirm: (title: string, message: string) => Promise<boolean>;
+	input?: (label: string, placeholder?: string) => Promise<string | undefined>;
 }
 
 export interface CommandsDeps {
@@ -430,7 +431,13 @@ What must the LLM do?
 				| "minimal" | "web-app" | "library" | "cli" | undefined) ?? undefined;
 			const autoYes = args.includes("--yes");
 			const projectName = args.match(/--name[= ](\S+)/)?.[1];
-			await initSolyProject(ctx.cwd, ui, { template, autoYes, projectName });
+			const initUi = {
+				notify: (t: string, k?: "info" | "warning" | "error") => ctx.ui.notify(t, k ?? "info"),
+				select: async (label: string, options: string[]) => ctx.ui.select(label, options),
+				confirm: (title: string, message: string) => ctx.ui.confirm(title, message),
+				input: (label: string, placeholder?: string) => ctx.ui.input(label, placeholder),
+			};
+			await initSolyProject(ctx.cwd, initUi, { template, autoYes, projectName });
 		},
 	});
 

package/core.ts

@@ -26,7 +26,10 @@ import * as path from "node:path";
 export type RuleSource =
   | "project-soly"
   | "global-soly"
-  | "phase-soly";
+  | "phase-soly"
+  | "project-agents"
+  | "global-agents"
+  | "phase-agents";
 
 export interface RuleFrontmatter {
   description?: string;
@@ -59,7 +62,7 @@ export interface RuleFile {
   enabled: boolean;
   mtimeMs: number;
   source: RuleSource;
-  sourceLabel: "soly" | "phase" | "local";
+  sourceLabel: "soly" | "phase" | "local" | "agents";
   priority: number; // higher wins on relPath collision
   /** Phase number for phase-scoped rules; undefined otherwise. */
   phaseNumber?: number;
@@ -70,7 +73,7 @@ export interface RuleFile {
 export interface SourceSpec {
   dir: string;
   source: RuleSource;
-  sourceLabel: "soly" | "phase" | "local";
+  sourceLabel: "soly" | "phase" | "local" | "agents";
   priority: number; // higher wins on relPath collision
   /** Optional phase number (for phase-scoped sources). */
   phaseNumber?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Project management + workflow engine for pi-coding-agent. Plans, state, MANDATORY rules, multi-question picker — one npm install, zero config. LLM is the executor (no subagent layer).",
   "type": "module",
   "main": "index.ts",