pi-prompt-template-model-enhanced 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.12.0](https://github.com/Nabsku/pi-prompt-template-model-enhanced/compare/v0.11.2...v0.12.0) (2026-06-20)
+
+
+### Features
+
+* add includes pane to dry-run TUI ([50624a4](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/50624a46a5722d2ca74ebcb0423e5e99f75dbad1))
+* attach include graphs to dry runs ([a1d7eba](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/a1d7eba676158faed0c4e9cf889e5525cf5e5923))
+* attach include graphs to validation ([d694724](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/d69472452a6af1b7f94f75df3002b65d5bdc62c8))
+* collect prompt include graphs ([be7c726](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/be7c726fb17a43524068ef8da819306304e79091))
+* collect prompt source records ([0d0df7a](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/0d0df7a38a460fb1d890596e8f334a9be5772892))
+* expose prompt include parsing helpers ([3e784a6](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/3e784a672304100e70ae3a6603a05be6c2744e5e))
+* report prompt include graphs ([5332c8e](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/5332c8e8c49925aec20ebe2ba913e6b6a13f814f))
+
+
+### Bug Fixes
+
+* avoid duplicate include graph diagnostics ([adb6c97](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/adb6c971fa3e1faea902aead4493fd47cf4121a6))
+* preserve skipped include graphs for overrides ([2b0e69f](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/2b0e69f3f158c8e5e8ef3bae45053cdd267a19e7))
+
 ## [0.11.2](https://github.com/Nabsku/pi-prompt-template-model-enhanced/compare/v0.11.1...v0.11.2) (2026-06-19)
 
 
@@ -39,10 +58,11 @@
 
 ### Added
 - Added `/print-prompt` and `/dry-run-prompt` to preview rendered prompt templates without execution.
-- Added a Pi-native dry-run TUI: no-name dry-run commands open a searchable template picker in Pi TUI mode, while named templates open a read-only inspector for prompt body, metadata, skills, warnings, and the raw report.
+- Added a Pi-native dry-run TUI: no-name dry-run commands open a searchable template picker in Pi TUI mode, while named templates open a read-only inspector for prompt body, metadata, skills, includes, warnings, and the raw report.
+- Added a static, permanent `Includes` pane to the dry-run TUI inspector. It shows the include graph captured during dry-run rendering, or `No includes.` for prompts without include metadata or inline include directives.
 
 ### Changed
-- Added `/validate-prompts` to validate prompt templates, includes, chain declarations, and skill references before runtime.
+- Added `/validate-prompts` to validate prompt templates, includes, chain declarations, and skill references before runtime, including include graph reporting for prompt dependencies and include failures.
 - Updated development-only Pi packages from the deprecated `@mariozechner/*` namespace to `@earendil-works/*` `0.79.7`, and bumped `tsx` to `^4.22.4`.
 - Added Dependabot version updates for npm development dependencies and GitHub Actions.
 - Added Release Please release automation and npm trusted publishing workflow.

package/README.md

@@ -83,10 +83,15 @@ Start a Python REPL session and help me debug: $@
 
 Run `/validate-prompts` to check prompt templates before using them. It reloads the project and user prompt directories, validates frontmatter, include paths, include cycles, chain declarations, reserved command names, and skill references that can be resolved from registered or filesystem skills.
 
+Validation also reports an include graph for prompts that declare frontmatter includes (`include` / `includes`), use inline include directives, or fail include processing. Each relevant prompt is listed with its include dependencies, including nested partial-to-partial includes.
+
 A clean library reports success:
 
 ```text
 [pi-prompt-template-model-enhanced] Prompt validation passed: 4 prompt template(s) loaded.
+Include graph:
+- review [ok] /repo/.pi/prompts/review.md
+  - review -> /repo/.pi/prompts/shared/rules.md (frontmatter shared/rules.md) [ok]
 ```
 
 Invalid libraries fail with explicit diagnostics:
@@ -95,8 +100,14 @@ Invalid libraries fail with explicit diagnostics:
 [pi-prompt-template-model-enhanced] Prompt validation failed: 2 issue(s) found across 3 loaded prompt template(s).
 - include-not-found (project) /repo/.pi/prompts/review.md: Prompt include "shared/rules.md" was not found ...
 - skill-not-found (project) /repo/.pi/prompts/debug.md: Prompt template ... references skill "tmux", but it was not found ...
+Include graph:
+- review [skipped] /repo/.pi/prompts/review.md
+  - review -> unresolved:shared/rules.md (frontmatter shared/rules.md) [failed]
+    ! include-not-found: Prompt include "shared/rules.md" was not found ...
 ```
 
+Include graph statuses are concise: `[ok]` means the prompt or edge resolved successfully, `[skipped]` means the loader skipped that prompt because include processing failed or was invalid, and `[failed]` marks a failed edge or root diagnostic. Prompts skipped for missing, cyclic, or invalid includes still appear in the include graph with `[skipped]`, failed include edges, and diagnostic codes such as `include-not-found` or `include-cycle`.
+
 ## Dry-run and TUI preview
 
 Use `/print-prompt` or `/dry-run-prompt` to preview what a prompt template would send before it executes. The preview uses the same include rendering, model conditionals, argument substitution, skill resolution, loop metadata, delegation metadata, and runtime flags as normal execution, but it does not switch models, send user messages, run deterministic commands, or start subagents.
@@ -126,7 +137,8 @@ TUI behavior:
 - a template name opens the inspector directly;
 - `--plain` forces the stdout/plain report even in TUI mode;
 - unsupported templates, such as deterministic or chain templates, show the same diagnostic as the plain path;
-- full skill content remains hidden unless the dry-run result was created with `--show-skills`.
+- full skill content remains hidden unless the dry-run result was created with `--show-skills`;
+- the inspector always includes a static `Includes` pane. Prompts with include metadata or inline include directives show the include graph captured during dry-run rendering; prompts without includes show `No includes.`.
 
 The inspector is read-only. It has no execute button and does not mutate the session.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-prompt-template-model-enhanced",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "type": "module",
   "description": "Prompt template model selector extension for pi coding agent",
   "author": "Nico Bailon",

package/prompt-dry-run-tui.ts

@@ -1,5 +1,7 @@
 import { decodeKittyPrintable, Key, matchesKey, truncateToWidth, type Component } from "@earendil-works/pi-tui";
 import type { PromptDryRunResult } from "./prompt-dry-run.js";
+import type { PromptIncludeGraph, PromptIncludeGraphEdge, PromptIncludeGraphNode } from "./prompt-includes.js";
+import type { PromptLoaderDiagnostic } from "./prompt-loader.js";
 
 export interface PromptTemplateCatalogItem {
 	name: string;
@@ -20,6 +22,7 @@ export interface PromptDryRunTuiViewModel {
 		prompt: string;
 		metadata: string;
 		skills: string;
+		includes: string;
 		warnings: string;
 		raw: string;
 	};
@@ -83,6 +86,69 @@ function formatSkills(result: PromptDryRunResult): string {
 	return lines.join("\n");
 }
 
+function lexicalCompare(a: string, b: string): number {
+	if (a < b) return -1;
+	if (a > b) return 1;
+	return 0;
+}
+
+function diagnosticKey(diagnostic: PromptLoaderDiagnostic): string {
+	return diagnostic.key || `${diagnostic.code}:${diagnostic.source}:${diagnostic.filePath}:${diagnostic.message}`;
+}
+
+function sortDiagnostics(diagnostics: PromptLoaderDiagnostic[]): PromptLoaderDiagnostic[] {
+	return [...diagnostics].sort((a, b) => lexicalCompare(a.filePath, b.filePath) || lexicalCompare(a.code, b.code) || lexicalCompare(a.message, b.message));
+}
+
+function sortIncludeGraphEdges(edges: PromptIncludeGraphEdge[]): PromptIncludeGraphEdge[] {
+	return [...edges].sort((a, b) => a.order - b.order || lexicalCompare(a.fromNodeId, b.fromNodeId) || lexicalCompare(a.toNodeId, b.toNodeId) || lexicalCompare(a.includePath, b.includePath));
+}
+
+function includeGraphNodeLabel(nodes: Map<string, PromptIncludeGraphNode>, nodeId: string): string {
+	const node = nodes.get(nodeId);
+	if (!node) return nodeId;
+	if (node.filePath) return node.filePath;
+	if (node.includePath) return `unresolved:${node.includePath}`;
+	return node.id;
+}
+
+function formatIncludeDiagnostic(prefix: string, diagnostic: PromptLoaderDiagnostic): string {
+	return `${prefix}${diagnostic.code}: ${diagnostic.message}`;
+}
+
+function rootOnlyIncludeDiagnostics(graph: PromptIncludeGraph): PromptLoaderDiagnostic[] {
+	const edgeDiagnosticKeys = new Set(graph.edges.flatMap((edge) => edge.diagnostics.map(diagnosticKey)));
+	return graph.diagnostics.filter((diagnostic) => !edgeDiagnosticKeys.has(diagnosticKey(diagnostic)));
+}
+
+function formatIncludes(result: PromptDryRunResult): string {
+	const graph = result.status === "ok" ? result.includeGraph : undefined;
+	if (!graph) return "No includes.";
+
+	const rootDiagnostics = sortDiagnostics(rootOnlyIncludeDiagnostics(graph));
+	if (graph.edges.length === 0 && rootDiagnostics.length === 0) return "No includes.";
+
+	const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+	const rootNode = graph.nodes.find((node) => node.kind === "prompt" && node.filePath === graph.root.filePath);
+	const rootStatus = rootNode?.status ?? (rootDiagnostics.length ? "failed" : "ok");
+	const lines = [`- ${graph.root.promptName} [${rootStatus}] ${graph.root.filePath}`];
+
+	for (const diagnostic of rootDiagnostics) {
+		lines.push(formatIncludeDiagnostic("  ! ", diagnostic));
+	}
+
+	for (const edge of sortIncludeGraphEdges(graph.edges)) {
+		const from = includeGraphNodeLabel(nodes, edge.fromNodeId);
+		const to = includeGraphNodeLabel(nodes, edge.toNodeId);
+		lines.push(`  - ${from} -> ${to} (${edge.kind} ${edge.includePath}) [${edge.status}]`);
+		for (const diagnostic of sortDiagnostics(edge.diagnostics)) {
+			lines.push(formatIncludeDiagnostic("    ! ", diagnostic));
+		}
+	}
+
+	return lines.join("\n");
+}
+
 export function createPromptDryRunTuiViewModel(result: PromptDryRunResult, plainReport: string): PromptDryRunTuiViewModel {
 	const warnings = result.warnings.length ? result.warnings.map((warning) => `- ${warning}`).join("\n") : "No warnings.";
 	const prompt = result.status === "ok" ? `# Prompt body\n${result.content}` : `# Error\n${result.error}`;
@@ -100,6 +166,7 @@ export function createPromptDryRunTuiViewModel(result: PromptDryRunResult, plain
 			prompt,
 			metadata,
 			skills: formatSkills(result),
+			includes: formatIncludes(result),
 			warnings,
 			raw: plainReport,
 		},
@@ -191,7 +258,7 @@ export class PromptDryRunPicker implements Component {
 	invalidate(): void {}
 }
 
-const PANE_NAMES = ["Prompt", "Metadata", "Skills", "Warnings", "Raw"] as const;
+const PANE_NAMES = ["Prompt", "Metadata", "Skills", "Includes", "Warnings", "Raw"] as const;
 type PaneName = typeof PANE_NAMES[number];
 
 export class PromptDryRunInspector implements Component {
@@ -229,7 +296,7 @@ export class PromptDryRunInspector implements Component {
 			"",
 			...body,
 			"",
-			`pane ${this.paneIndex + 1}/5 · line ${Math.min(this.scroll + 1, paneLines.length)}/${paneLines.length} · j/down scroll · tab next · b back · q quit`,
+			`pane ${this.paneIndex + 1}/${PANE_NAMES.length} · line ${Math.min(this.scroll + 1, paneLines.length)}/${paneLines.length} · j/down scroll · tab next · b back · q quit`,
 		];
 		return linesSafe(lines, width);
 	}
@@ -248,7 +315,7 @@ export class PromptDryRunInspector implements Component {
 			this.scroll = 0;
 			return;
 		}
-		const paneKey = (["1", "2", "3", "4", "5"] as const).find((key) => matchesKey(data, key));
+		const paneKey = Array.from({ length: PANE_NAMES.length }, (_, index) => String(index + 1)).find((key) => matchesKey(data, key));
 		if (paneKey) {
 			this.paneIndex = Number(paneKey) - 1;
 			this.scroll = 0;

package/prompt-dry-run.ts

@@ -11,6 +11,7 @@ import {
 import type { RegistryLike } from "./model-selection.js";
 import { preparePromptExecution } from "./prompt-execution.js";
 import { expandCwdPath, type PromptWithModel } from "./prompt-loader.js";
+import type { PromptIncludeGraph } from "./prompt-includes.js";
 import { getRequestedSkills, resolvePromptSkills, type RuntimeSkillCommand } from "./prompt-skills.js";
 import { DEFAULT_SUBAGENT_NAME } from "./subagent-runtime.js";
 
@@ -53,6 +54,7 @@ export interface PromptDryRunRuntimeMetadata {
 
 export interface PromptDryRunDetails {
 	skills: PromptDryRunSkillPreview[];
+	includeGraph?: PromptIncludeGraph;
 }
 
 export interface PromptDryRunSuccess {
@@ -65,6 +67,7 @@ export interface PromptDryRunSuccess {
 	warnings: string[];
 	skills: PromptDryRunSkillPreview[];
 	details: PromptDryRunDetails;
+	includeGraph?: PromptIncludeGraph;
 	runtime: PromptDryRunRuntimeMetadata;
 }
 
@@ -379,7 +382,8 @@ export async function createPromptDryRun(
 		modelAlreadyActive: prepared.selectedModel.alreadyActive,
 		warnings,
 		skills: skillPreviews,
-		details: { skills: skillPreviews },
+		includeGraph: effectivePrompt.includeGraph,
+		details: { skills: skillPreviews, includeGraph: effectivePrompt.includeGraph },
 		runtime,
 	};
 }