pi-soly 1.9.3 → 1.11.0

package/migrate.ts

@@ -0,0 +1,258 @@
+// =============================================================================
+// migrate.ts — Atomic .soly/ → .agents/ migration
+// =============================================================================
+//
+// Moves the legacy `.soly/` project state dir to the new vendor-neutral
+// `.agents/` location. The move tries fs.rename first (atomic on the same
+// filesystem). On Windows, rename often fails with EPERM because soly's
+// hot-reload watcher (or an editor) holds open handles on .soly/ files.
+// We retry the rename a few times, then fall back to recursive copy +
+// delete if the handle won't release. Validates after move that key files
+// made it.
+//
+// What gets moved (everything in `.soly/`):
+//   - ROADMAP.md
+//   - STATE.md
+//   - docs/         (intent docs)
+//   - rules/        (project rules)
+//   - phases/       (PLAN.md / SUMMARY.md / CONTEXT.md / RESEARCH.md)
+//   - iterations/   (per-execution context)
+//   - HANDOFF.json  (pause snapshot)
+//   - .continue-here.md
+//   - config.json   (per-project config — note: kept for backward compat
+//                     reading; new writes go to .agents/config.json too)
+//
+// What does NOT get moved:
+//   - rotor persistence (no longer used in 1.4.0)
+//   - git history — `git mv` would preserve; fs.rename loses history. We
+//     suggest the user commit beforehand.
+//
+// Usage:
+//   /soly-migrate              # confirm before doing
+//   /soly-migrate --yes        # skip confirmation
+//   /soly-migrate --dry-run    # show what would happen
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { LEGACY_SOLY_DIRNAME, SOLY_DIRNAME } from "./core.js";
+
+const renameAsync = promisify(fs.rename);
+const rmAsync = promisify(fs.rm);
+
+/**
+ * Cross-platform directory move.
+ *
+ * `fs.rename` is atomic on POSIX but on Windows it fails with EPERM if any
+ * file inside the source dir has an open handle (soly hot-reload watcher,
+ * editor, antivirus, the cwd itself). We:
+ *
+ *   1. Retry rename up to 5 times with 200ms backoff — most EPERM are
+ *      transient (OS releasing a handle).
+ *   2. Fall back to recursive copy-then-delete if rename keeps failing.
+ *      Slower but works when a handle is genuinely held for the duration.
+ */
+async function moveDir(from: string, to: string): Promise<void> {
+	let lastErr: unknown;
+	for (let attempt = 0; attempt < 5; attempt++) {
+		try {
+			await renameAsync(from, to);
+			return;
+		} catch (err) {
+			lastErr = err;
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") throw err;
+			await new Promise((r) => setTimeout(r, 200 * (attempt + 1)));
+		}
+	}
+	// Rename exhausted — fall back to copy + delete.
+	// This works even when handles are held because we open files read-only
+	// for the copy and the source is removed last.
+	await copyDirRecursive(from, to);
+	try {
+		await rmAsync(from, { recursive: true, force: true });
+	} catch (err) {
+		// Source dir couldn't be removed (handle still held). The migration
+		// itself succeeded — .agents/ has everything. Throw a soft warning so
+		// the caller can tell the user to delete .soly/ manually.
+		throw new Error(
+			`migrated to ${to} but could not remove ${from}: ${(err as Error).message}. ` +
+				`Delete ${from} manually after closing editors/pi.`,
+		);
+	}
+}
+
+function copyDirRecursive(src: string, dest: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		fs.mkdirSync(dest, { recursive: true });
+		const entries = fs.readdirSync(src, { withFileTypes: true });
+		let pending = entries.length;
+		if (pending === 0) return resolve();
+		let rejected = false;
+		const done = (err?: Error) => {
+			if (rejected) return;
+			if (err) {
+				rejected = true;
+				reject(err);
+				return;
+			}
+			pending -= 1;
+			if (pending === 0) resolve();
+		};
+		for (const entry of entries) {
+			const s = path.join(src, entry.name);
+			const d = path.join(dest, entry.name);
+			if (entry.isDirectory()) {
+				copyDirRecursive(s, d).then(() => done(), done);
+			} else if (entry.isSymbolicLink()) {
+				try {
+					fs.symlinkSync(fs.readlinkSync(s), d);
+					done();
+				} catch (e) {
+					done(e as Error);
+				}
+			} else {
+				fs.copyFile(s, d, (e) => done(e ? new Error(e.message) : undefined));
+			}
+		}
+	});
+}
+
+/** UI primitives needed by the migration. */
+export interface MigrateUI {
+	notify: (text: string, level?: "info" | "warning" | "error") => void;
+	confirm: (title: string, message: string) => Promise<boolean>;
+}
+
+export interface MigrateOptions {
+	/** Skip the confirmation dialog. */
+	autoYes?: boolean;
+	/** Don't actually move; just report. */
+	dryRun?: boolean;
+}
+
+export interface MigrateResult {
+	/** Whether the move happened (false if cancelled or skipped). */
+	moved: boolean;
+	/** What was moved (file/dir names relative to cwd). */
+	relocated: string[];
+	/** Warnings during validation. */
+	warnings: string[];
+}
+
+/** What we expect to find in `.soly/`. Listed for dry-run reporting. */
+const EXPECTED_ENTRIES = [
+	"ROADMAP.md",
+	"STATE.md",
+	"docs",
+	"rules",
+	"phases",
+	"iterations",
+	"HANDOFF.json",
+	".continue-here.md",
+	"config.json",
+] as const;
+
+/** Top-level move function. Returns a result so tests can assert. */
+export async function migrateSolyDir(
+	cwd: string,
+	ui: MigrateUI,
+	options: MigrateOptions = {},
+): Promise<MigrateResult> {
+	const from = path.join(cwd, LEGACY_SOLY_DIRNAME);
+	const to = path.join(cwd, SOLY_DIRNAME);
+	const result: MigrateResult = { moved: false, relocated: [], warnings: [] };
+
+	// Preconditions
+	if (!fs.existsSync(from)) {
+		ui.notify(`soly-migrate: no ${LEGACY_SOLY_DIRNAME}/ to migrate (already on ${SOLY_DIRNAME}/)`, "info");
+		return result;
+	}
+	if (fs.existsSync(to)) {
+		ui.notify(
+			`soly-migrate: both ${LEGACY_SOLY_DIRNAME}/ and ${SOLY_DIRNAME}/ exist. ` +
+				`Resolve manually before migrating.`,
+			"error",
+		);
+		return result;
+	}
+
+	// Inventory what's in .soly/
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(from);
+	} catch (err) {
+		ui.notify(`soly-migrate: cannot read ${from}: ${(err as Error).message}`, "error");
+		return result;
+	}
+	const inventory = entries.filter((e) => !e.startsWith("."));
+	result.relocated = inventory;
+
+	// Dry-run: report and exit
+	if (options.dryRun) {
+		ui.notify(
+			`soly-migrate (dry run): would move ${inventory.length} entries from ` +
+				`${LEGACY_SOLY_DIRNAME}/ to ${SOLY_DIRNAME}/:\n  - ${inventory.join("\n  - ")}`,
+			"info",
+		);
+		return { ...result, relocated: inventory };
+	}
+
+	// Confirm with the user
+	if (!options.autoYes) {
+		const ok = await ui.confirm(
+			`soly migrate ${LEGACY_SOLY_DIRNAME}/ → ${SOLY_DIRNAME}/`,
+			`Move ${inventory.length} entries (${inventory.slice(0, 5).join(", ")}${inventory.length > 5 ? ", …" : ""})? ` +
+				`This is atomic on the same filesystem but does NOT preserve git history. ` +
+				`Recommend committing ${LEGACY_SOLY_DIRNAME}/ separately first if you care about history.`,
+		);
+		if (!ok) {
+			ui.notify("soly-migrate: cancelled", "info");
+			return result;
+		}
+	}
+
+	// Do the move (with Windows EPERM retry + copy fallback)
+	try {
+		await moveDir(from, to);
+	} catch (err) {
+		const msg = (err as Error).message;
+		const isPartial = msg.includes("Delete ") || msg.includes("could not remove");
+		ui.notify(
+			isPartial
+				? `soly-migrate: ${msg}`
+				: `soly-migrate: rename failed: ${msg}. Original .soly/ untouched.`,
+			isPartial ? "warning" : "error",
+		);
+		return result;
+	}
+
+	// Validate the result
+	if (!fs.existsSync(to)) {
+		ui.notify(`soly-migrate: post-rename check failed — ${SOLY_DIRNAME}/ missing`, "error");
+		return result;
+	}
+	for (const expected of EXPECTED_ENTRIES) {
+		const src = path.join(from, expected);
+		const dst = path.join(to, expected);
+		// Only check items that existed before; some are optional
+		if (fs.existsSync(src) && !fs.existsSync(dst)) {
+			result.warnings.push(`missing after move: ${expected}`);
+		}
+	}
+
+	result.moved = true;
+
+	// Success message + git hint
+	const warnPart = result.warnings.length > 0
+		? `\n\nWarnings:\n  - ${result.warnings.join("\n  - ")}`
+		: "";
+	ui.notify(
+		`soly-migrate: done. ${inventory.length} entries moved to ${SOLY_DIRNAME}/.${warnPart}\n\n` +
+			`Recommended next:\n` +
+			`  git add -A && git commit -m "migrate soly state to .agents/"`,
+		"info",
+	);
+	return result;
+}

package/notification.ts

@@ -0,0 +1,218 @@
+// =============================================================================
+// notification.ts — Styled, framed notifications for soly (pi-themed)
+// =============================================================================
+//
+// Uses pi's `ui.setWidget()` with a Box container and `theme.bg()` for a
+// soft background — the same pattern pi itself uses for branch summaries
+// and compaction messages (see pi-coding-agent's BranchSummaryMessage).
+//
+// Why a widget, not `ui.notify()`?
+//   - `notify()` is plain text, no background, no styled box
+//   - `setWidget(key, factory, opts)` accepts a factory returning a
+//     `Box` / `Text` component, which gives full theme support
+//   - The widget lives in the editor area (above/below the prompt),
+//     so the user actually sees it before sending the next message
+//
+// Lifecycle:
+//   - Each notification uses a unique key (or shared "soly-nudge" for nudges)
+//   - New notification with the same key REPLACES the previous
+//   - `autoClearMs` (default 5s) removes the widget via setWidget(undefined)
+//
+// API:
+//   - formatFramed(title, lines) — pure text → framed text (no styling)
+//   - notifyFramed(ui, title, lines, opts) — boxed widget with theme bg
+//   - notifyNudge(ui, variant, angle) — specific for prompt nudges
+//   - notifyDeprecation(ui, old, new, hint?) — for migration warnings
+//   - clearNotification(ui, key) — manual clear
+// =============================================================================
+
+import { Box, Spacer, Text, type TUI } from "@earendil-works/pi-tui";
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import { appendNotification } from "./notifications-log.ts";
+
+/** Theme background color names (subset of ThemeBg). */
+export type NotifBg =
+	| "customMessageBg"   // soft, neutral (default — matches branch summary)
+	| "selectedBg"        // for emphasis
+	| "toolPendingBg"     // warning yellow
+	| "toolSuccessBg"     // green
+	| "toolErrorBg";      // red
+
+export interface NotifOptions {
+	/** Auto-clear after N ms. Default 5000. 0 = no auto-clear. */
+	autoClearMs?: number;
+	/** "aboveEditor" (default) or "belowEditor". */
+	placement?: "aboveEditor" | "belowEditor";
+	/** Widget key for replacement/clearing. Default: "soly-notif". */
+	key?: string;
+	/** Background color name. Default "customMessageBg". */
+	bg?: NotifBg;
+	/** Bold the title. Default true. */
+	boldTitle?: boolean;
+}
+
+const DEFAULT_KEY = "soly-notif";
+
+/** Build a Box with the given title + body lines, themed with bg. */
+function buildNotifBox(
+	theme: Theme,
+	title: string,
+	lines: readonly string[],
+	bg: NotifBg,
+	boldTitle: boolean,
+): Box {
+	const box = new Box(1, 0, (t) => theme.bg(bg, t));
+	const titleStyled = boldTitle
+		? theme.bold(theme.fg("accent", title))
+		: theme.fg("accent", title);
+	box.addChild(new Text(titleStyled, 1, 0));
+	if (lines.length > 0) {
+		box.addChild(new Spacer(1));
+		for (const line of lines) {
+			box.addChild(new Text(line, 1, 0));
+		}
+	}
+	return box;
+}
+
+/**
+ * Show a framed, themed notification as a widget above/below the editor.
+ * Replaces any prior notification with the same key. Auto-clears after
+ * `autoClearMs` (default 5s) unless 0.
+ */
+export function notifyFramed(
+	ui: ExtensionUIContext,
+	title: string,
+	lines: readonly string[],
+	options: NotifOptions = {},
+): void {
+	const key = options.key ?? DEFAULT_KEY;
+	const bg: NotifBg = options.bg ?? "customMessageBg";
+	const placement = options.placement ?? "aboveEditor";
+	const autoClearMs = options.autoClearMs ?? 5000;
+	const boldTitle = options.boldTitle ?? true;
+	ui.setWidget(
+		key,
+		(_tui: TUI, theme: Theme) => buildNotifBox(theme, title, lines, bg, boldTitle),
+		{ placement },
+	);
+	if (autoClearMs > 0) {
+		setTimeout(() => {
+			try { ui.setWidget(key, undefined); } catch { /* session may have ended */ }
+		}, autoClearMs);
+	}
+}
+
+/** Manually clear a notification by key. */
+export function clearNotification(ui: ExtensionUIContext, key: string = DEFAULT_KEY): void {
+	try { ui.setWidget(key, undefined); } catch { /* ignore */ }
+}
+
+// ---------------------------------------------------------------------------
+// High-level helpers
+// ---------------------------------------------------------------------------
+
+/** Nudge: "I should clarify before acting on this non-trivial prompt". */
+export function notifyNudge(
+	ui: ExtensionUIContext,
+	variant: "nonTrivial" | "research",
+	angle: string,
+	cwd?: string,
+): void {
+	const title = variant === "research" ? "soly · research-heavy" : "soly · non-trivial";
+	const body = variant === "research"
+		? [
+				"Prompt looks like a research / look-up task.",
+				`Consider clarifying: ${angle}`,
+			]
+		: [
+				"Prompt looks like a non-trivial change.",
+				`Consider asking for: ${angle}`,
+			];
+	notifyFramed(ui, title, body, {
+		key: "soly-nudge",
+		bg: "customMessageBg",
+		autoClearMs: 4000, // nudge is transient — clears before next user input
+	});
+	if (cwd) {
+		appendNotification(cwd, { kind: "nudge", title, body, meta: { variant } });
+	}
+}
+
+/** Deprecation: warn when an old path/convention is used. */
+export function notifyDeprecation(
+	ui: ExtensionUIContext,
+	oldThing: string,
+	newThing: string,
+	hint?: string,
+	cwd?: string,
+): void {
+	const body: string[] = [
+		`Using:     ${oldThing}`,
+		`Preferred: ${newThing}`,
+	];
+	if (hint) body.push(hint);
+	notifyFramed(ui, "soly · deprecation", body, {
+		key: "soly-deprecation",
+		bg: "toolPendingBg", // warning yellow tint
+		autoClearMs: 12000,  // stays longer — user needs to see it
+	});
+	if (cwd) {
+		appendNotification(cwd, {
+			kind: "deprecation",
+			title: "soly · deprecation",
+			body,
+		});
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Plain-text fallback (no widget, just framed Unicode text via notify).
+// Used for the .soly/ migration banner and other places that don't have
+// access to a UI context yet (CLI startup, print mode, etc.)
+// ---------------------------------------------------------------------------
+
+const CHARS = {
+	topLeft: "╭",
+	topRight: "╮",
+	bottomLeft: "╰",
+	bottomRight: "╯",
+	horizontal: "─",
+	vertical: "│",
+} as const;
+
+/** Format lines as a rounded Unicode frame. Pure text, no ANSI. */
+export function formatFramed(
+	title: string,
+	lines: readonly string[],
+	options: { minWidth?: number } = {},
+): string {
+	const minWidth = options.minWidth ?? 30;
+	const titleWithSep = ` ${title} `;
+	const bodyWidths = lines.map((l) => stripAnsi(l).length);
+	const naturalWidth = Math.max(
+		titleWithSep.length + 2,
+		...bodyWidths.map((w) => w + 4),
+		minWidth,
+	);
+	const titlePadTotal = naturalWidth - titleWithSep.length - 2;
+	const titlePadLeft = Math.floor(titlePadTotal / 2);
+	const titlePadRight = titlePadTotal - titlePadLeft;
+	const horizontalRule =
+		CHARS.topLeft +
+		CHARS.horizontal.repeat(titlePadLeft) +
+		titleWithSep +
+		CHARS.horizontal.repeat(titlePadRight) +
+		CHARS.topRight;
+	const bottomRule =
+		CHARS.bottomLeft + CHARS.horizontal.repeat(naturalWidth - 2) + CHARS.bottomRight;
+	const bodyLines = lines.map((line) => {
+		const pad = naturalWidth - 4 - stripAnsi(line).length;
+		return CHARS.vertical + " " + line + " ".repeat(Math.max(0, pad)) + " " + CHARS.vertical;
+	});
+	return [horizontalRule, ...bodyLines, bottomRule].join("\n");
+}
+
+function stripAnsi(s: string): string {
+	return s.replace(/\u001b\[[0-9;]*m/g, "");
+}

package/notifications-log.ts

@@ -0,0 +1,83 @@
+// =============================================================================
+// notifications-log.ts — Persistent record of soly notifications
+// =============================================================================
+//
+// Appends every nudge/deprecation to a JSONL file at .agents/.soly/notifications.log
+// (inside the project dir; safe to commit if the user wants a public audit
+// trail, or .gitignore if not). One line per notification, JSON-encoded.
+//
+// Reading: `/soly-log notifications [N]` shows the last N entries (default 20).
+//
+// Why: transient Box widgets auto-clear. If the user missed a nudge or wants
+// to see what nudges fired in past turns/sessions, the log is the source of
+// truth.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { SOLY_DIRNAME } from "./core.js";
+
+/** Notification kinds we log. */
+export type NotificationKind = "nudge" | "deprecation" | "info" | "warning" | "error";
+
+export interface NotificationEntry {
+	ts: string;            // ISO timestamp
+	kind: NotificationKind;
+	title: string;         // e.g. "soly · non-trivial"
+	body: string[];        // message lines
+	/** Free-form metadata (e.g. "variant": "research") */
+	meta?: Record<string, unknown>;
+}
+
+/** Where the log file lives. Respects HOME for tests. */
+export function logFilePath(cwd: string, home?: string): string {
+	const h = home ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
+	return path.join(cwd, SOLY_DIRNAME, ".soly", "notifications.log");
+}
+
+/** Append a single entry to the log. Creates parent dirs as needed. */
+export function appendNotification(cwd: string, entry: Omit<NotificationEntry, "ts">): void {
+	const file = logFilePath(cwd);
+	try {
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+	} catch { /* ignore */ }
+	const full: NotificationEntry = { ts: new Date().toISOString(), ...entry };
+	try {
+		fs.appendFileSync(file, JSON.stringify(full) + "\n", "utf-8");
+	} catch { /* best-effort — don't fail the notification itself */ }
+}
+
+/** Read the last N entries (newest first). */
+export function readNotifications(cwd: string, limit: number = 20, home?: string): NotificationEntry[] {
+	const file = logFilePath(cwd, home);
+	if (!fs.existsSync(file)) return [];
+	let raw: string;
+	try {
+		raw = fs.readFileSync(file, "utf-8");
+	} catch {
+		return [];
+	}
+	const lines = raw.split("\n").filter((l) => l.length > 0);
+	const entries: NotificationEntry[] = [];
+	for (const line of lines) {
+		try {
+			entries.push(JSON.parse(line) as NotificationEntry);
+		} catch { /* skip malformed */ }
+	}
+	// Newest first
+	return entries.reverse().slice(0, limit);
+}
+
+/** Format entries for display in the TUI. */
+export function formatNotifications(entries: readonly NotificationEntry[]): string {
+	if (entries.length === 0) return "(no notifications recorded)";
+	const lines: string[] = [];
+	for (const e of entries) {
+		const date = e.ts.slice(0, 16).replace("T", " ");
+		lines.push(`[${date}] ${e.title}`);
+		for (const b of e.body) lines.push(`    ${b}`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.9.3",
+  "version": "1.11.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",
@@ -16,10 +16,15 @@
   "devDependencies": {
     "@earendil-works/pi-ai": "0.78.1",
     "@earendil-works/pi-coding-agent": "0.78.1",
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
+    "@modelcontextprotocol/sdk": "1.27.1",
     "@types/node": "^25.9.1",
     "bun-types": "^1.3.14",
+    "open": "^11.0.0",
+    "recheck": "^4.5.0",
     "typebox": "1.1.38",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
   },
   "files": [
     "README.md",
@@ -41,7 +46,16 @@
     "ask",
     "skills",
     "workflows",
-    "workflows-data"
+    "workflows-data",
+    "mcp",
+    "notification.ts",
+    "notifications-log.ts",
+    "status.ts",
+    "init.ts",
+    "migrate.ts",
+    "codemap.ts",
+    "state.ts",
+    "hotreload.ts"
   ],
   "keywords": [
     "pi",
@@ -53,6 +67,9 @@
     "workflow-engine",
     "rules-engine",
     "intent-docs",
+    "mcp",
+    "model-context-protocol",
+    "session-recovery",
     "ai-coding"
   ],
   "license": "MIT",