pi-soly 2.2.0 → 2.2.2

package/README.md

@@ -303,7 +303,7 @@ Use it when a visual, rendered result beats terminal text (example galleries, co
                 └──────────────────┘
 ```
 
-State lives in `.agents/` — portable, git-friendly, human-readable. (Projects from before the rename used `.soly/`; soly no longer reads it — run `mv .soly .agents`.)
+State lives in `.agents/` — portable, git-friendly, human-readable.
 
 ```
 .agents/

package/built-in-rules/release-discipline.md

@@ -0,0 +1,105 @@
+# Release Discipline Rule
+
+> **Every version bump = a CHANGELOG entry.** Soly ships with a release
+> workflow that publishes a tagged version to npm on push. If the
+> workflow fires for a commit that bumped the version but didn't touch
+> `CHANGELOG.md`, the release is shipped blind — users have no way to
+> know what changed. **Always update CHANGELOG.md in the same commit that
+> bumps the version.**
+
+## The rule
+
+When `package.json` `version` is incremented (any field under `version`):
+
+1. **Open `CHANGELOG.md` first** (or via `soly_snippet` / `soly_doc_search`).
+2. **Move the entry out of `[Unreleased]`** into a new section with the
+   new version as the header: `## [<new-ver>] — <YYYY-MM-DD>`.
+3. **Group changes under standard subsections** — pick only what applies:
+   - `### Added` — new feature visible to users
+   - `### Changed` — behavior change in existing feature
+   - `### Deprecated` — feature still works but slated for removal
+   - `### Removed` — feature gone
+   - `### Fixed` — bug fix
+   - `### Security` — security-relevant change
+4. **Each bullet = one user-visible change** (not "touched X file" —
+   that belongs in the commit message, not the changelog).
+5. **Reference the function / command / file** the change is in
+   (e.g., `soly execute`, `goal-verify.ts`, `settings UI`).
+6. **Semantic Versioning** rules:
+   - **PATCH** (x.y.**Z+1**) — bug fix, no API change, no behavior change.
+   - **MINOR** (x.**Y+1**.0) — new feature visible to user; existing
+     commands behave the same.
+   - **MAJOR** (**X+1**.0.0) — breaking change: command renamed,
+     output format changed, file moved, default config changed.
+7. **No empty version blocks** — if the section is empty, don't add the
+   header. Leave it in `[Unreleased]`.
+
+## Why this matters
+
+- Users `npm update` and read the changelog to decide whether to upgrade.
+- The soly release workflow (`ci.yml` → `publish` job) runs the same
+  pipeline as `bun test` and `bun run typecheck`. A clean CHANGELOG
+  alongside a version bump is the user's signal that the bump was
+  intentional, not a typo.
+- Search engines / GitHub release notes auto-render the `[X.Y.Z]`
+  headers — empty or missing entries = "garbage release".
+
+## Examples
+
+### Good
+
+```markdown
+## [2.2.0] — 2026-07-05
+
+### Added
+- **`/sly` and `/s` aliases** for the `/soly` picker. Same body, three
+  command names. The `/soly` modal header shows `· /sly · /s` as a hint.
+
+### Changed
+- **`mcp/panel-keys.ts` → `visual/panel-keys.ts`.** The keybindings
+  primitive used by `ListPanel`, `McpPanel`, and `McpSetupPanel` is
+  now its own visual-UI module.
+```
+
+### Bad
+
+```markdown
+## [2.2.0] — 2026-07-05
+
+### Changed
+- refactored
+```
+
+(Too vague to be useful; the user can't tell what changed or whether
+it matters to them.)
+
+### Worse
+
+```markdown
+## [2.2.0] — 2026-07-05
+```
+
+(Empty section — the bump is real, the user has no idea why.)
+
+## Workflow
+
+When `soly done <plan>` (or any version-bump commit) lands:
+
+1. The `package.json` bump should be in the **same commit** as the
+   CHANGELOG edit. If you forgot, the release workflow still passes —
+   it doesn't enforce this rule. (We could add a CI check: `git diff
+   ${prev-tag}..HEAD -- package.json | grep version && ! git diff
+   ${prev-tag}..HEAD -- CHANGELOG.md | head -1` — but for now it's
+   convention.)
+2. The release CI runs `ci.yml` → publishes to npm. It does NOT lint
+   CHANGELOG.
+3. The GitHub release auto-renders from the tag's commit message
+   (`release: pi-soly v2.2.0`); the CHANGELOG entry is the canonical
+   "what changed" surface.
+
+## Override
+
+This rule is built-in to the soly extension and ships with every
+install. If your project ships a `.agents/rules/release-discipline.md`
+that adds (or contradicts) the rules above, the project rule wins per
+the standard soly priority rules (project > global > built-in).

package/commands/_helpers.ts

@@ -0,0 +1,87 @@
+// =============================================================================
+// commands/_helpers.ts — shared types + helpers for the per-command modules
+// =============================================================================
+//
+// Re-exports from here:
+//   - CommandUI, CommandsDeps      — contracts the slash commands need
+//   - openListPanel                 — wraps ListPanel in ctx.ui.custom
+//   - openExternally                — OS-default handler for URLs/files
+//
+// Each per-command module imports what it needs from here. The thin
+// `commands/index.ts` orchestrator wires the deps object.
+// =============================================================================
+
+import * as path from "node:path";
+import { platform } from "node:os";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { ListPanel, type ListItem, type ListAction, type ListGroup } from "../visual/list-panel.ts";
+import type { SolyState, RuleFile } from "../core.ts";
+import type { SolyConfig } from "../config.ts";
+import type { IntentDoc } from "../intent.ts";
+
+/** Minimum ui surface the command handlers actually need. */
+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>;
+}
+
+/** All live-state callbacks the slash commands need. The orchestrator
+ *  (index.ts) injects these from the extension's runtime. Per-command
+ *  modules take a `Pick<CommandsDeps, …>` of just what they need. */
+export interface CommandsDeps {
+	getRules: () => RuleFile[];
+	getOverridden: () => string[];
+	refreshRules: () => void;
+	getState: () => SolyState;
+	refreshState: () => void;
+	updateStatus: (ui: CommandUI) => void;
+	getConfig: () => SolyConfig;
+	reloadConfig: () => void;
+	getIntentDocs: () => IntentDoc[];
+}
+
+/** Open a focused list modal (overlay) for the given grouped items. */
+export async function openListPanel(
+	ctx: ExtensionCommandContext,
+	spec: {
+		title: string;
+		headerRight?: string;
+		build: () => ListGroup[];
+		actions?: ListAction[];
+		onSelect?: (item: ListItem) => void;
+	},
+): Promise<void> {
+	await ctx.ui.custom<void>(
+		(tui, theme, keybindings, done) =>
+			new ListPanel({
+				tui,
+				theme,
+				keybindings,
+				done: () => done(),
+				title: spec.title,
+				headerRight: spec.headerRight,
+				groups: spec.build(),
+				actions: spec.actions,
+				refresh: spec.build,
+				onSelect: spec.onSelect,
+			}),
+		{ overlay: true },
+	);
+}
+
+/** Open a URL/file with the OS default handler (browser for http/.html). */
+export async function openExternally(pi: ExtensionAPI, target: string): Promise<void> {
+	const o = platform();
+	const r =
+		o === "darwin"
+			? await pi.exec("open", [target])
+			: o === "win32"
+				? await pi.exec("cmd", ["/c", "start", "", target])
+				: await pi.exec("xdg-open", [target]);
+	if (r.code !== 0) throw new Error(r.stderr || `open failed (exit ${r.code})`);
+}
+
+/** Re-export path used by some command bodies. */
+export { path };

package/commands/artifacts.ts

@@ -0,0 +1,86 @@
+// =============================================================================
+// commands/artifacts.ts — /artifacts command (browse html_artifact gallery)
+// =============================================================================
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getArtifactServer, ensureArtifactServer, artifactDir } from "../artifact/session.ts";
+import { openListPanel, openExternally, type CommandsDeps } from "./_helpers.ts";
+
+type ArtifactsDeps = Pick<CommandsDeps, "getConfig">;
+
+export function registerArtifactsCommand(pi: ExtensionAPI, deps: ArtifactsDeps): void {
+	const { getConfig } = deps;
+
+	pi.registerCommand("artifacts", {
+		description: "browse this project's html_artifact gallery (list, open, clear)",
+		handler: async (args, ctx) => {
+			if (!getConfig().artifacts.server) {
+				ctx.ui.notify("soly: artifact server is disabled (artifacts.server=false)", "info");
+				return;
+			}
+			// Always re-resolve: reuse another window's server or start ours, and
+			// re-probe a stale client whose owner may have died in the meantime.
+			let server = getArtifactServer();
+			try {
+				server = await ensureArtifactServer(artifactDir(getConfig().artifacts.dir, ctx.cwd), ctx.cwd);
+			} catch {
+				// ignore — handled by the count check below
+			}
+			if (!server || server.count === 0) {
+				ctx.ui.notify("soly: no artifacts for this project yet (use the html_artifact tool)", "info");
+				return;
+			}
+			const gallery = server.galleryUrl();
+			const sub = args.trim().split(/\s+/).filter(Boolean)[0] ?? "";
+
+			if (sub === "clear") {
+				const n = server.clear();
+				ctx.ui.notify(`soly: cleared ${n} artifact(s)`, "info");
+				return;
+			}
+			if (sub === "open" || sub === "gallery") {
+				try {
+					await openExternally(pi, gallery);
+					ctx.ui.notify(`soly: opened ${gallery}`, "info");
+				} catch {
+					ctx.ui.notify(`soly artifacts gallery: ${gallery}`, "info");
+				}
+				return;
+			}
+
+			if (ctx.mode === "tui") {
+				await openListPanel(ctx, {
+					title: "soly · artifacts",
+					headerRight: `${server.count} artifact${server.count === 1 ? "" : "s"}`,
+					build: () => [
+						{
+							id: "artifacts",
+							title: "Artifacts",
+							icon: "▦",
+							items: (getArtifactServer()?.list() ?? []).map((a) => ({
+								id: a.id,
+								marker: "▦", // BMP glyph — an astral emoji (🖼) breaks ListPanel width
+								label: a.title,
+								meta: new Date(a.createdAt).toLocaleTimeString(),
+								body: a.url,
+							})),
+						},
+					],
+					onSelect: (it) => {
+						const a = getArtifactServer()?.list().find((x) => x.id === it.id);
+						if (a) void openExternally(pi, a.url);
+					},
+					actions: [
+						{ key: "g", hint: "gallery", run: () => void openExternally(pi, gallery) },
+						{ key: "x", hint: "delete", run: (it) => { getArtifactServer()?.remove(it.id); } },
+					],
+				});
+				return;
+			}
+
+			// Non-TUI: print the list + gallery URL.
+			const lines = server.list().map((a) => `🖼 ${a.title} — ${a.url}`);
+			ctx.ui.notify([`soly artifacts gallery: ${gallery}`, "", ...lines].join("\n"), "info");
+		},
+	});
+}

package/commands/docs.ts

@@ -0,0 +1,74 @@
+// =============================================================================
+// commands/docs.ts — /docs command (list, stats)
+// =============================================================================
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { formatTok, solyDirFor } from "../core.ts";
+import { buildIntentStats, formatIntentStats, loadInlineIntentBodies, type IntentInlineDoc } from "../intent.ts";
+import { openListPanel, type CommandUI, type CommandsDeps } from "./_helpers.ts";
+
+type DocsDeps = Pick<CommandsDeps, "getIntentDocs">;
+
+export function registerDocsCommand(pi: ExtensionAPI, deps: DocsDeps): void {
+	const { getIntentDocs } = deps;
+
+	pi.registerCommand("docs", {
+		description: "manage soly intent docs (stats — show context breakdown)",
+		handler: async (args, ctx) => {
+			const ui: CommandUI = {
+				notify: (t, k) => ctx.ui.notify(t, k ?? "info"),
+				select: async (label, options) => {
+					const result = await ctx.ui.select(label, options);
+					return result === undefined ? null : options.indexOf(result);
+				},
+				confirm: (title, message) => ctx.ui.confirm(title, message),
+			};
+			const parts = args.trim().split(/\s+/);
+			// Bare `/docs` opens the modal; an explicit subcommand (e.g. stats) does not.
+			const sub = parts[0] || "list";
+
+			if (sub === "list") {
+				const docs = getIntentDocs();
+				if (docs.length === 0) {
+					ui.notify("no intent docs found in .agents/docs/ — drop your vision/domain docs there", "info");
+					return;
+				}
+				if (ctx.mode === "tui") {
+					const total = docs.reduce((s, d) => s + d.tokens, 0);
+					await openListPanel(ctx, {
+						title: "soly · docs",
+						headerRight: `${docs.length} docs · ${formatTok(total)}`,
+						build: () => [
+							{
+								id: "docs",
+								title: "Docs",
+								icon: "☖",
+								items: getIntentDocs().map((d) => ({
+									id: d.relPath,
+									marker: "○",
+									label: d.title || d.relPath,
+									meta: `${d.kind} · ${formatTok(d.tokens)} tok${d.oversized ? " · oversized" : ""}`,
+									body: d.preview,
+								})),
+							},
+						],
+					});
+					return;
+				}
+				ui.notify(docs.map((d) => `○ ${d.title || d.relPath} (${formatTok(d.tokens)} tok)`).join("\n"), "info");
+				return;
+			}
+
+			if (sub === "stats") {
+				const docs = getIntentDocs();
+				const inlineBodies: IntentInlineDoc[] = loadInlineIntentBodies(docs);
+				const stats = buildIntentStats(docs, inlineBodies);
+				ui.notify(formatIntentStats(stats), "info");
+				return;
+			}
+
+			ui.notify("Usage: /docs <list|stats>", "error");
+			void solyDirFor; // kept available for future subcommands
+		},
+	});
+}

package/commands/rules.ts

@@ -0,0 +1,187 @@
+// =============================================================================
+// commands/rules.ts — /rules command (list, show, stats, analytics, reload, enable, disable)
+// =============================================================================
+
+import * as path from "node:path";
+import * as fs from "node:fs";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { CONTEXT_WINDOW_TOKENS, formatTok, analyzeRules, buildRulesContextStats, formatAnalyticsFull, formatRulesContextStats, readIfExists, type RuleFile } from "../core.ts";
+import type { ListItem } from "../visual/list-panel.ts";
+import { openListPanel, type CommandUI, type CommandsDeps } from "./_helpers.ts";
+
+/** Status marker for a rule: ● always-on · ◐ glob-matched · ○ disabled. */
+function ruleMarker(r: RuleFile): string {
+	if (!r.enabled) return "○";
+	return r.meta.always || !(r.meta.globs && r.meta.globs.length) ? "●" : "◐";
+}
+
+/** Map a rule to a panel row (token estimate + globs + description preview). */
+function ruleItem(r: RuleFile): ListItem {
+	const tokens = Math.ceil(r.body.length / 4);
+	const bits = [`${formatTok(tokens)} tok`];
+	if (r.meta.globs && r.meta.globs.length) bits.push(r.meta.globs.join(","));
+	if (!r.enabled) bits.push("off");
+	return {
+		id: r.relPath,
+		marker: ruleMarker(r),
+		label: r.relPath,
+		meta: bits.join(" · "),
+		body: r.meta.description ? `${r.meta.description}\n\n${r.body}` : r.body,
+	};
+}
+
+type RulesDeps = Pick<CommandsDeps, "getRules" | "getOverridden" | "refreshRules" | "updateStatus">;
+
+export function registerRulesCommand(pi: ExtensionAPI, deps: RulesDeps): void {
+	const { getRules, getOverridden, refreshRules, updateStatus } = deps;
+
+	pi.registerCommand("rules", {
+		description: "manage soly rules (list, show, stats, analytics, reload, enable, disable)",
+		handler: async (args, ctx) => {
+			const ui: CommandUI = {
+				notify: (t, k) => ctx.ui.notify(t, k ?? "info"),
+				select: async (label, options) => {
+					const result = await ctx.ui.select(label, options);
+					return result === undefined ? null : options.indexOf(result);
+				},
+				confirm: (title, message) => ctx.ui.confirm(title, message),
+			};
+			const parts = args.trim().split(/\s+/);
+			// Bare `/rules` (empty args) opens the modal; an explicit subcommand does not.
+			const sub = parts[0] || "list";
+			const target = parts[1];
+
+			if (sub === "list") {
+				const rules = getRules();
+				const overridden = getOverridden();
+				if (rules.length === 0 && overridden.length === 0) {
+					ui.notify("soly: no rules loaded — check `.agents/rules/` or `~/.agents/rules/`", "warning");
+					return;
+				}
+				// Rich modal in the TUI; plain select elsewhere (RPC/print).
+				if (ctx.mode === "tui") {
+					const analytics = analyzeRules(getRules(), CONTEXT_WINDOW_TOKENS);
+					await openListPanel(ctx, {
+						title: "soly · rules",
+						headerRight: `${getRules().length} rules · ${formatTok(analytics.totalTokens)} · ${analytics.contextBudgetPct.toFixed(1)}%`,
+						build: () => [
+							{ id: "rules", title: "Rules", icon: "▤", items: getRules().map(ruleItem) },
+						],
+						actions: [
+							{ key: "e", hint: "enable", run: (it) => { const r = getRules().find((x) => x.relPath === it.id); if (r) r.enabled = true; } },
+							{ key: "d", hint: "disable", run: (it) => { const r = getRules().find((x) => x.relPath === it.id); if (r) r.enabled = false; } },
+							{ key: "r", hint: "reload", run: () => refreshRules() },
+						],
+					});
+					updateStatus(ui);
+					return;
+				}
+				const lines: string[] = [];
+				for (const r of rules) {
+					const status = r.enabled ? "●" : "○";
+					const desc = r.meta.description ? ` — ${r.meta.description}` : "";
+					lines.push(`${status} [${r.sourceLabel}] ${r.relPath}${desc}`);
+				}
+				for (const p of overridden) {
+					lines.push(`⊘ [overridden] ${p}`);
+				}
+				ui.notify(lines.join("\n"), "info");
+				return;
+			}
+
+			if (sub === "show") {
+				if (!target) {
+					ui.notify("Usage: /rules show <relPath>", "error");
+					return;
+				}
+				const r = getRules().find((x) => x.relPath === target);
+				if (!r) {
+					ui.notify(`Rule not found: ${target}`, "error");
+					return;
+				}
+				const text = `---\n${r.meta.description ? `description: ${r.meta.description}\n` : ""}source: ${r.sourceLabel}\nenabled: ${r.enabled}\n---\n\n${r.body}`;
+				ui.notify(text, "info");
+				return;
+			}
+
+			if (sub === "stats") {
+				const analytics = analyzeRules(getRules(), CONTEXT_WINDOW_TOKENS);
+				ui.notify(formatAnalyticsFull(analytics), "info");
+				return;
+			}
+
+			if (sub === "analytics") {
+				const rules = getRules();
+				const stats = buildRulesContextStats(rules, CONTEXT_WINDOW_TOKENS);
+				ui.notify(formatRulesContextStats(stats), "info");
+				return;
+			}
+
+			if (sub === "enable" || sub === "disable") {
+				if (!target) {
+					ui.notify(`Usage: /rules ${sub} <relPath>`, "error");
+					return;
+				}
+				const r = getRules().find((x) => x.relPath === target);
+				if (!r) {
+					ui.notify(`Rule not found: ${target}`, "error");
+					return;
+				}
+				r.enabled = sub === "enable";
+				updateStatus(ui);
+				ui.notify(`Rule ${target}: ${sub}d`, "info");
+				return;
+			}
+
+			if (sub === "reload") {
+				refreshRules();
+				updateStatus(ui);
+				ui.notify(`Reloaded ${getRules().length} rules`, "info");
+				return;
+			}
+
+			if (sub === "add") {
+				ui.notify(
+					"Use /rulewizard add <url> (or /rules add for the rule-creation guide).",
+					"info",
+				);
+				return;
+			}
+
+			if (sub === "new") {
+				ui.notify(
+					"Use /rulewizard to scaffold a new rule (it guides the rule-vs-editorconfig-vs-linter decision).",
+					"info",
+				);
+				return;
+			}
+
+			if (sub === "path") {
+				const cwd = process.cwd();
+				const dirs = [
+					path.join(cwd, ".agents", "rules.local"),
+					path.join(cwd, ".agents", "rules"),
+					path.join(cwd, ".pi", "rules"),
+					path.join(require("node:os").homedir(), ".agents", "rules"),
+				];
+				const found = dirs.filter((d) => fs.existsSync(d));
+				ui.notify(
+					"Rules sources (existing first):\n" +
+						(found.length ? found.map((d) => `  ✓ ${d}`).join("\n") : "  (none)") +
+						"\n" +
+						dirs
+							.filter((d) => !found.includes(d))
+							.map((d) => `  - ${d}`)
+							.join("\n"),
+					"info",
+				);
+				return;
+			}
+
+			ui.notify(
+				`Usage: /rules <list|show|stats|analytics|enable|disable|reload|add|new|path> [target]`,
+				"error",
+			);
+		},
+	});
+}

package/commands/rulewizard.ts

@@ -0,0 +1,43 @@
+// =============================================================================
+// commands/rulewizard.ts — /rulewizard command (interactive guide)
+// =============================================================================
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export function registerRulewizardCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("rulewizard", {
+		description:
+			"interactive guide: decide whether a constraint should be a soly rule, an .editorconfig entry, or a linter config (eslint/biome/prettier). Use this BEFORE writing a new rule to avoid duplicating what linters already enforce.",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(
+				[
+					"soly-rule-wizard:",
+					"",
+					"tell me what behavior or outcome you want to constrain. I'll help you",
+					"decide whether it should be:",
+					"  • a soly rule (.agents/rules/*.md) — for process, behavior, or project",
+					"    conventions the LLM must follow",
+					"  • an .editorconfig entry — for formatting (indent, line endings, EOL,",
+					"    charset, trailing whitespace, max line length)",
+					"  • a linter config (eslint / biome / prettier) — for code style that",
+					"    a tool can check automatically",
+					"  • or nothing — if an existing tool already covers it",
+					"",
+					"decide first:",
+					"  1. is it about LLM behavior / process / project conventions?  → soly rule",
+					"  2. is it about whitespace, indent, line endings?             → .editorconfig",
+					"  3. is it about code style a linter can check?                → eslint/biome",
+					"  4. is it already covered by an existing tool?                → don't duplicate",
+					"",
+					"useful commands first:",
+					"  /rules           — see existing rules (so we don't duplicate)",
+					"  /rules analytics — see file sizes, missing descriptions, duplicates",
+					"",
+					"when you've decided:",
+					"  /rules new       — scaffold a new rule from the soly template",
+				].join("\n"),
+				"info",
+			);
+		},
+	});
+}