pi-soly 0.2.1

package/integrations.ts

@@ -0,0 +1,64 @@
+// =============================================================================
+// integrations.ts — Registry of known cross-extension integrations
+// =============================================================================
+//
+// soly treats itself as a platform: it composes with sibling pi-extensions
+// when they're loaded. This file is the single source of truth for which
+// external extensions we know about and how to advertise them in the
+// system prompt. Add a new entry when a sibling extension ships a tool
+// that the LLM should reach for in a soly-aware way.
+//
+// Detection: passive (read `pi.getActiveTools()` from `before_agent_start`).
+// We only mention extensions that are *actually installed* — no noise about
+// extensions the user hasn't loaded.
+// =============================================================================
+
+export interface KnownIntegration {
+	/** Tool name as registered with `pi.registerTool`. Case-sensitive match. */
+	tool: string;
+	/** Short human label for the extension package (e.g. "pi-ask"). */
+	extension: string;
+	/** One-line summary of what the tool does. */
+	summary: string;
+	/** When/how the LLM should use this tool inside a soly workflow. */
+	whenToUse: string;
+}
+
+/** Single registry — add new entries here, no other code changes needed. */
+export const KNOWN_INTEGRATIONS: KnownIntegration[] = [
+	{
+		tool: "ask_pro",
+		extension: "pi-ask",
+		summary: "Multi-question tabbed picker (Claude Code style).",
+		whenToUse:
+			"Use instead of `soly_ask_user` for `soly discuss` flows when you have multiple related questions. PREFERRED in `soly discuss` when available.",
+	},
+	{
+		tool: "todo_update",
+		extension: "pi-todo",
+		summary: "Live, user-visible task list rendered in the footer.",
+		whenToUse:
+			"During `soly execute <plan>`, seed todos at the start with one item per `<task>` so the user sees real-time progress. Update as you work: pending → in_progress → completed. Clear the list when the SUMMARY is committed.",
+	},
+];
+
+/** Build the cross-extension integrations section for the system prompt.
+ *  Returns null when none of the registered tools are present (no noise). */
+export function buildIntegrationsSection(activeTools: readonly string[]): string | null {
+	const installed = KNOWN_INTEGRATIONS.filter((i) => activeTools.includes(i.tool));
+	if (installed.length === 0) return null;
+
+	const lines: string[] = [];
+	lines.push("");
+	lines.push("## Cross-extension integrations (active in this session)");
+	lines.push("");
+	lines.push(
+		"The following optional pi-extensions are loaded. Use their tools when the situation matches — they exist to make your output more useful to the user.",
+	);
+	lines.push("");
+	for (const i of installed) {
+		lines.push(`- \`${i.tool}\` (from \`${i.extension}\`) — ${i.summary}`);
+		lines.push(`  When: ${i.whenToUse}`);
+	}
+	return lines.join("\n");
+}

package/intent.ts

@@ -0,0 +1,303 @@
+// =============================================================================
+// intent.ts — Project intent loader (the "0 point" of every soly project)
+// =============================================================================
+//
+// `.soly/docs/` is the zero-point of the project: documents written BEFORE
+// any soly plans, research, or code. It holds the user's vision, business
+// context, and architectural intent. Other soly artifacts (STATE, PLANS,
+// RESEARCH) flow FROM this input.
+//
+// Supported files: `.md` (full text) and `.html` (parsed for title + preview).
+// Nested directories are supported (e.g. `.soly/docs/api/auth.md`).
+//
+// Convention: any document in `.soly/docs/` is loaded into the system
+// prompt as "project intent". This is separate from:
+//   - rules (`.soly/rules/`) — how to behave
+//   - state (`.soly/STATE.md`, ROADMAP.md) — where we are
+//   - planning (PLAN.md, CONTEXT.md) — what to do next
+//
+// Optional: `.soly/phases/<N>/docs/` is also scanned if the directory exists
+// (for backward compat / phase-specific intent). Not required.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatTok, resolveImports } from "./core.js";
+import { extractTitleAndPreview, stripHtml } from "./html.js";
+
+const DOC_EXTS = new Set([".md", ".html", ".htm"]);
+
+export type IntentKind = "md" | "html";
+
+export interface IntentDoc {
+	relPath: string;
+	absPath: string;
+	kind: IntentKind;
+	title: string;
+	preview: string;
+	tokens: number;
+	/** True if this came from a phase-specific docs dir. */
+	phaseNumber?: number;
+	/** Size cap, files larger than this are still indexed but flagged. */
+	oversized: boolean;
+}
+
+const MAX_PREVIEW_CHARS = 200;
+const MAX_FILE_BYTES = 256 * 1024; // 256KB cap on indexed files
+
+function readFirstLineOfFile(absPath: string, max = 120): string {
+	try {
+		const stat = fs.statSync(absPath);
+		if (stat.size > MAX_FILE_BYTES) {
+			const fd = fs.openSync(absPath, "r");
+			try {
+				const buf = Buffer.alloc(max);
+				fs.readSync(fd, buf, 0, max, 0);
+				return buf.toString("utf-8").split(/\r?\n/)[0]?.trim() ?? "";
+			} finally {
+				fs.closeSync(fd);
+			}
+		}
+		const content = fs.readFileSync(absPath, "utf-8");
+		return content.split(/\r?\n/)[0]?.trim() ?? "";
+	} catch {
+		return "";
+	}
+}
+
+// ---- Walker ----
+
+function walkIntentDir(
+	absDir: string,
+	relBase: string,
+	phaseNumber: number | undefined,
+	out: IntentDoc[],
+): void {
+	if (!fs.existsSync(absDir)) return;
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(absDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const e of entries) {
+		if (e.name.startsWith(".")) continue;
+		const abs = path.join(absDir, e.name);
+		const rel = relBase ? `${relBase}/${e.name}` : e.name;
+		if (e.isDirectory()) {
+			walkIntentDir(abs, rel, phaseNumber, out);
+			continue;
+		}
+		if (!e.isFile()) continue;
+		const ext = path.extname(e.name).toLowerCase();
+		if (!DOC_EXTS.has(ext)) continue;
+
+		let stat: fs.Stats;
+		try {
+			stat = fs.statSync(abs);
+		} catch {
+			continue;
+		}
+
+		const oversized = stat.size > MAX_FILE_BYTES;
+		const kind: IntentKind = ext === ".md" ? "md" : "html";
+
+		let title = "";
+		let preview = "";
+		try {
+			// For oversized files, only read the first 64KB
+			const readBytes = Math.min(stat.size, 64 * 1024);
+			const buf = Buffer.alloc(readBytes);
+			const fd = fs.openSync(abs, "r");
+			try {
+				fs.readSync(fd, buf, 0, readBytes, 0);
+			} finally {
+				fs.closeSync(fd);
+			}
+			const content = buf.toString("utf-8");
+			// `ext` is `path.extname` output, always lowercased — cast to the
+			// narrow literal union the extractor expects.
+			const extNorm = (ext === ".md" || ext === ".html" || ext === ".htm" ? ext : ".md") as
+				| ".md"
+				| ".html"
+				| ".htm";
+			const extracted = extractTitleAndPreview(content, extNorm, { maxPreview: MAX_PREVIEW_CHARS });
+			title = extracted.title;
+			preview = extracted.preview || stripHtml(content).slice(0, MAX_PREVIEW_CHARS);
+		} catch {
+			// best effort
+		}
+
+		// Fallback title = filename without extension
+		if (!title) {
+			title = path.basename(e.name, ext).replace(/[-_]+/g, " ");
+		}
+
+		out.push({
+			relPath: rel,
+			absPath: abs,
+			kind,
+			title,
+			preview,
+			tokens: Math.ceil(stat.size / 4),
+			phaseNumber,
+			oversized,
+		});
+	}
+}
+
+export function loadIntentDocs(cwd: string, currentPhaseNumber?: number): IntentDoc[] {
+	const out: IntentDoc[] = [];
+	const docsRoot = path.join(cwd, ".soly", "docs");
+	walkIntentDir(docsRoot, "", undefined, out);
+
+	// Optional: phase-specific docs (only if current phase is known)
+	if (currentPhaseNumber != null) {
+		// We don't know the slug here without re-walking phases; scan any
+		// directory in .soly/phases/ whose name starts with the phase number.
+		// Skip if no phases dir exists.
+		const phasesRoot = path.join(cwd, ".soly", "phases");
+		if (fs.existsSync(phasesRoot)) {
+			try {
+				const phaseEntries = fs.readdirSync(phasesRoot, { withFileTypes: true });
+				for (const pe of phaseEntries) {
+					if (!pe.isDirectory()) continue;
+					const m = pe.name.match(/^(\d+)/);
+					if (!m) continue;
+					if (parseInt(m[1], 10) !== currentPhaseNumber) continue;
+					const fullPhaseDocsDir = path.join(phasesRoot, pe.name, "docs");
+					walkIntentDir(fullPhaseDocsDir, pe.name + "/docs", currentPhaseNumber, out);
+				}
+			} catch {
+				// best effort
+			}
+		}
+	}
+
+	// Sort: top-level files first (depth), then alphabetically
+	out.sort((a, b) => {
+		const da = a.relPath.split("/").length;
+		const db = b.relPath.split("/").length;
+		if (da !== db) return da - db;
+		return a.relPath.localeCompare(b.relPath);
+	});
+
+	return out;
+}
+
+export interface IntentSection {
+	hasContent: boolean;
+	section: string;
+}
+
+/** Render the "## project intent" section for the system prompt. */
+export function buildIntentSection(intent: IntentDoc[]): IntentSection {
+	if (intent.length === 0) {
+		return { hasContent: false, section: "" };
+	}
+
+	const lines: string[] = ["", "## project intent (from .soly/docs/)", ""];
+	lines.push(
+		"These documents are the **0 point** of this project — the user's vision, business context, and design intent, written BEFORE any soly plans. Read them first when planning, discussing, or executing. If implementation diverges from intent, fix one or the other — don't let drift compound.",
+	);
+	lines.push("");
+
+	// Group: always (top-level) vs phase-specific
+	const always = intent.filter((d) => d.phaseNumber == null);
+	const phaseSpecific = intent.filter((d) => d.phaseNumber != null);
+
+	if (always.length > 0) {
+		lines.push("**Always read first:**");
+		lines.push("");
+		for (const d of always) {
+			const title = d.title || d.relPath;
+			const tag = d.kind === "html" ? "html" : "md";
+			const oversize = d.oversized ? " (large file — use soly_snippet to read)" : "";
+			lines.push(`- \`${d.relPath}\` (${tag}, ${formatTok(d.tokens)} tokens)${oversize}`);
+			lines.push(`  - **${title}**`);
+			if (d.preview) {
+				lines.push(`  - ${d.preview.slice(0, 180)}${d.preview.length > 180 ? "…" : ""}`);
+			}
+		}
+		lines.push("");
+	}
+
+	if (phaseSpecific.length > 0) {
+		lines.push("**Phase-specific** (relevant to active phase):");
+		lines.push("");
+		for (const d of phaseSpecific) {
+			const title = d.title || d.relPath;
+			lines.push(`- \`${d.relPath}\` (phase ${d.phaseNumber}) — **${title}**`);
+			if (d.preview) {
+				lines.push(`  - ${d.preview.slice(0, 180)}${d.preview.length > 180 ? "…" : ""}`);
+			}
+		}
+		lines.push("");
+	}
+
+	lines.push(
+		"Use `soly_intent` to refresh this list, `soly_doc_search` for keyword search across all docs (including project .md), and `soly_snippet` to read a specific range.",
+	);
+
+	return { hasContent: true, section: lines.join("\n") };
+}
+
+// ---- Inline body resolution ----
+//
+// For .md intent docs, optionally inline the FULL body into the system prompt
+// (with @import resolution). Off by default — index is usually enough. Turn on
+// per-doc via frontmatter `inline: true`.
+
+export interface IntentInlineDoc {
+	relPath: string;
+	body: string;
+	tokens: number;
+}
+
+function parseIntentFrontmatter(raw: string): { inline: boolean; body: string } {
+	const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+	if (!m) return { inline: false, body: raw };
+	const yaml = m[1];
+	const body = m[2];
+	const inlineMatch = yaml.match(/^\s*inline\s*:\s*true\s*$/m);
+	return { inline: !!inlineMatch, body };
+}
+
+export function loadInlineIntentBodies(intent: IntentDoc[]): IntentInlineDoc[] {
+	const out: IntentInlineDoc[] = [];
+	for (const d of intent) {
+		if (d.kind !== "md") continue; // Only .md can opt-in to inlining
+		try {
+			const raw = fs.readFileSync(d.absPath, "utf-8");
+			const { inline, body } = parseIntentFrontmatter(raw);
+			if (!inline) continue;
+			if (d.oversized) continue; // Skip oversized even if opted-in
+
+			// Apply @import resolution (with cycle + depth protection).
+			// Inlined docs are read-only, so we use a fresh globalSeen set.
+			const globalSeen = new Set<string>([d.absPath]);
+			const resolved = resolveImports(body, d.absPath, globalSeen, 0, {
+				imported: [],
+			});
+
+			// Token cap (defense against accidental huge inlines that slipped
+			// past the bytes cap, e.g. dense code with low whitespace).
+			const tokens = Math.ceil(resolved.length / 4);
+			const TOKEN_CAP = 2000;
+			const finalBody =
+				tokens > TOKEN_CAP
+					? resolved.slice(0, TOKEN_CAP * 4) +
+						`\n\n<!-- inlined truncated to ${TOKEN_CAP} tokens (${tokens} total); use soly_snippet for the full file -->`
+					: resolved;
+
+			out.push({
+				relPath: d.relPath,
+				body: finalBody,
+				tokens: Math.ceil(finalBody.length / 4),
+			});
+		} catch {
+			// skip unreadable
+		}
+	}
+	return out;
+}