pi-soly 1.8.0 → 1.9.0

package/commands.ts

@@ -3,7 +3,8 @@
 // =============================================================================
 //
 // Registers slash commands (via pi.registerCommand):
-//   - /rules         manage soly rules (list/show/analytics/reload/enable/disable/add/new)
+//   - /rules         manage soly rules (list/show/stats/analytics/reload/enable/disable/add/new)
+//   - /docs          manage soly intent docs (stats — context breakdown)
 //   - /soly          project state inspection (position/plan/phases/tasks/...)
 //                    subcommands: position, state, plan, context, research, roadmap,
 //                                 progress, phases, tasks, task <id>, features,
@@ -32,6 +33,13 @@ import {
 	type RuleFile,
 	type SolyState,
 } from "./core.ts";
+import {
+	buildIntentStats,
+	formatIntentStats,
+	loadInlineIntentBodies,
+	type IntentDoc,
+	type IntentInlineDoc,
+} from "./intent.ts";
 import type { SolyConfig } from "./config.ts";
 import { migrateSolyDir } from "./migrate.js";
 import { initSolyProject } from "./init.js";
@@ -53,6 +61,7 @@ export interface CommandsDeps {
 	refreshState: () => void;
 	updateStatus: (ui: CommandUI) => void;
 	getConfig: () => SolyConfig;
+	getIntentDocs: () => IntentDoc[];
 }
 
 export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
@@ -64,6 +73,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 		refreshState,
 		updateStatus,
 		getConfig,
+		getIntentDocs,
 	} = deps;
 
 	// ============================================================================
@@ -347,6 +357,40 @@ What must the LLM do?
 	},
 	});
 
+	// ============================================================================
+	// /docs — manage soly intent docs (stats subcommand shows context usage)
+	// ============================================================================
+	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+/);
+			const sub = parts[0] ?? "stats";
+
+			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 stats — show context breakdown for intent docs\n` +
+				`Found ${getIntentDocs().length} doc(s) loaded.`,
+				"info",
+			);
+		},
+	});
+
 	// ============================================================================
 	// /soly migrate — move .soly/ → .agents/ atomically
 	// ============================================================================

package/index.ts

@@ -307,6 +307,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 		refreshState: () => refreshState(),
 		updateStatus: (ui) => updateStatus(ui),
 		getConfig: getActiveConfig,
+		getIntentDocs: () => intentDocs,
 	});
 
 	registerTools(pi, {

package/intent.ts

@@ -301,3 +301,109 @@ export function loadInlineIntentBodies(intent: IntentDoc[]): IntentInlineDoc[] {
 	}
 	return out;
 }
+
+// =============================================================================
+// Intent stats — Claude-memory-style breakdown for docs
+// =============================================================================
+//
+// Shows how docs consume context. Most docs are preview-only (cheap),
+// only `inline: true` docs inject their full body (expensive).
+
+export interface IntentDocStat {
+  relPath: string;
+  kind: "md" | "html";
+  title: string;
+  tokens: number;       // full file tokens (what would be loaded if inline)
+  previewTokens: number; // preview tokens (what's actually loaded by default)
+  inline: boolean;      // true if `inline: true` frontmatter — body is injected
+  oversized: boolean;
+  phaseNumber?: number;
+}
+
+export interface IntentStats {
+  totalDocs: number;
+  totalInlineTokens: number;     // tokens from inline: true docs (full body)
+  totalPreviewTokens: number;    // tokens from preview-only docs (always loaded)
+  totalPerTurnTokens: number;    // sum of what's actually in system prompt
+  inlineDocs: IntentDocStat[];
+  previewDocs: IntentDocStat[];
+  phaseSpecificDocs: IntentDocStat[];
+}
+
+export function buildIntentStats(
+  docs: IntentDoc[],
+  inlineBodies: IntentInlineDoc[],
+): IntentStats {
+  const inlineRelPaths = new Set(inlineBodies.map((d) => d.relPath));
+  const inlineBodyTokens = new Map(inlineBodies.map((d) => [d.relPath, d.tokens]));
+  const stat = (d: IntentDoc): IntentDocStat => ({
+    relPath: d.relPath,
+    kind: d.kind,
+    title: d.title,
+    tokens: d.tokens,
+    previewTokens: Math.ceil(d.preview.length / 4),
+    inline: inlineRelPaths.has(d.relPath),
+    oversized: d.oversized,
+    phaseNumber: d.phaseNumber,
+  });
+  const all = docs.map(stat);
+  const inlineDocs = all.filter((d) => d.inline);
+  const previewDocs = all.filter((d) => !d.inline);
+  const phaseSpecificDocs = all.filter((d) => d.phaseNumber != null);
+  const totalInlineTokens = inlineDocs.reduce(
+    (a, b) => a + (inlineBodyTokens.get(b.relPath) ?? b.tokens),
+    0,
+  );
+  const totalPreviewTokens = previewDocs.reduce((a, b) => a + b.previewTokens, 0);
+  return {
+    totalDocs: all.length,
+    totalInlineTokens,
+    totalPreviewTokens,
+    totalPerTurnTokens: totalInlineTokens + totalPreviewTokens,
+    inlineDocs,
+    previewDocs,
+    phaseSpecificDocs,
+  };
+}
+
+export function formatIntentStats(stats: IntentStats): string {
+  const lines: string[] = [];
+  lines.push(`📚 Docs context stats`);
+  lines.push(``);
+  lines.push(
+    `Loaded: ${stats.totalDocs} doc(s) · ${stats.totalPerTurnTokens} tok every turn`,
+  );
+  lines.push(
+    `  (${stats.totalInlineTokens} from inline bodies + ${stats.totalPreviewTokens} from previews)`,
+  );
+  lines.push(``);
+  if (stats.inlineDocs.length > 0) {
+    lines.push(`INLINE (full body loaded every turn):`);
+    for (const d of stats.inlineDocs) {
+      const title = d.title ? ` — "${d.title}"` : "";
+      lines.push(`  ● ${d.relPath}  ${d.tokens} tok${title}`);
+    }
+    lines.push(``);
+  }
+  if (stats.previewDocs.length > 0) {
+    lines.push(`PREVIEW-ONLY (only title + 180-char preview loaded):`);
+    for (const d of stats.previewDocs) {
+      const title = d.title ? ` — "${d.title}"` : "";
+      const size = d.oversized ? " (oversized)" : "";
+      lines.push(`  ○ ${d.relPath}  ${d.previewTokens} tok preview${title}${size}`);
+    }
+    lines.push(``);
+  }
+  if (stats.phaseSpecificDocs.length > 0) {
+    lines.push(`PHASE-SPECIFIC (only loaded for matching phase):`);
+    for (const d of stats.phaseSpecificDocs) {
+      const title = d.title ? ` — "${d.title}"` : "";
+      lines.push(`  ◐ phase ${d.phaseNumber}: ${d.relPath}${title}`);
+    }
+    lines.push(``);
+  }
+  if (stats.totalDocs === 0) {
+    lines.push(`No intent docs found in .soly/docs/ or ~/.soly/docs/`);
+  }
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Project management framework for pi-coding-agent. Workflows, planning, multi-question picker, agent switcher, live task list — one npm install, zero config.",
   "type": "module",
   "main": "index.ts",