@danypops/pi-papyrus 0.35.0

package/extension/src/artifact-detail-view.ts

@@ -0,0 +1,121 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, sliceByColumn, truncateToWidth, visibleWidth, wrapTextWithAnsi, type TUI } from "@earendil-works/pi-tui";
+import {
+	ARTIFACT_DETAIL_HORIZONTAL_PAN_COLUMNS,
+	ARTIFACT_DETAIL_MAX_VISIBLE_LINES,
+	ARTIFACT_DETAIL_MIN_VISIBLE_LINES,
+	ARTIFACT_DETAIL_RESERVED_ROWS,
+	type Artifact,
+	type GraphRenderer,
+} from "@danypops/papyrus";
+import { artifactDetailContent, artifactDetailsText, type ArtifactDetailContent } from "./artifact-detail-format.ts";
+import { buildArtifactRelationshipLines } from "./artifact-relationship-lines.ts";
+import { BeautifulMermaidRenderer } from "./beautiful-mermaid-renderer.ts";
+import { renderMarkdownBody, type ActiveTheme } from "./markdown.ts";
+
+interface ArtifactDetailLine {
+	text: string;
+	wide: boolean;
+}
+
+class ArtifactDetailViewport {
+	private offsetX = 0;
+	private offsetY = 0;
+	private renderedWidth = 0;
+	private lines: ArtifactDetailLine[] = [];
+	private readonly visibleLines: number;
+	private readonly content: ArtifactDetailContent;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly activeTheme: ActiveTheme,
+		artifact: Artifact,
+		relationshipLines: string[],
+		private readonly close: () => void,
+	) {
+		this.visibleLines = Math.max(
+			ARTIFACT_DETAIL_MIN_VISIBLE_LINES,
+			Math.min(ARTIFACT_DETAIL_MAX_VISIBLE_LINES, tui.terminal.rows - ARTIFACT_DETAIL_RESERVED_ROWS),
+		);
+		this.content = artifactDetailContent(artifact, relationshipLines);
+	}
+
+	invalidate(): void { this.renderedWidth = 0; }
+
+	render(width: number): string[] {
+		const contentWidth = Math.max(1, width - 2);
+		this.buildLines(contentWidth);
+		const wideWidth = this.content.relationships.reduce((maximum, line) => Math.max(maximum, visibleWidth(line)), 0);
+		this.offsetX = Math.min(this.offsetX, Math.max(0, wideWidth - contentWidth));
+		this.offsetY = Math.min(this.offsetY, Math.max(0, this.lines.length - this.visibleLines));
+		const end = Math.min(this.lines.length, this.offsetY + this.visibleLines);
+		const theme = this.activeTheme();
+		const border = theme.fg("borderMuted", "─".repeat(Math.max(1, width)));
+		const footer = [
+			wideWidth > contentWidth ? `←/→ relationships · column ${this.offsetX + 1}/${wideWidth}` : "",
+			this.lines.length > this.visibleLines ? `↑/↓ scroll · ${this.offsetY + 1}-${end}/${this.lines.length}` : "",
+			"Esc back",
+		].filter(Boolean).join(" · ");
+		return [
+			border,
+			truncateToWidth(theme.fg("accent", theme.bold("Artifact details")), width, ""),
+			border,
+			...this.lines.slice(this.offsetY, end).map((line) => line.wide
+				? ` ${sliceByColumn(line.text, this.offsetX, contentWidth, true)}`
+				: truncateToWidth(` ${line.text}`, width, "")),
+			truncateToWidth(theme.fg("dim", footer), width, ""),
+			border,
+		];
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) { this.close(); return; }
+		if (matchesKey(data, "up")) this.offsetY = Math.max(0, this.offsetY - 1);
+		else if (matchesKey(data, "down")) this.offsetY = Math.min(Math.max(0, this.lines.length - this.visibleLines), this.offsetY + 1);
+		else if (matchesKey(data, "left")) this.offsetX = Math.max(0, this.offsetX - ARTIFACT_DETAIL_HORIZONTAL_PAN_COLUMNS);
+		else if (matchesKey(data, "right")) this.offsetX += ARTIFACT_DETAIL_HORIZONTAL_PAN_COLUMNS;
+		else return;
+		this.tui.requestRender();
+	}
+
+	private buildLines(width: number): void {
+		if (this.renderedWidth === width) return;
+		this.renderedWidth = width;
+		const theme = this.activeTheme();
+		const wrap = (text: string, color: "text" | "muted" | "dim" = "text"): ArtifactDetailLine[] =>
+			(text.length === 0 ? [""] : wrapTextWithAnsi(theme.fg(color, text), width)).map((line) => ({ text: line, wide: false }));
+		const identity = [
+			...wrap(theme.bold(this.content.title)),
+			...wrap(this.content.identity, "muted"),
+			{ text: "", wide: false },
+		];
+		const body = renderMarkdownBody(this.content.body, width, this.activeTheme).map((text) => ({ text, wide: false }));
+		const labels = this.content.labels.length > 0
+			? [{ text: "", wide: false }, ...wrap("Labels:", "muted"), ...wrap(this.content.labels.join(", "))]
+			: [];
+		const metadata = this.content.metadata.length > 0
+			? [{ text: "", wide: false }, ...wrap("Metadata:", "muted"), ...this.content.metadata.flatMap((line) => wrap(`  ${line}`, "dim"))]
+			: [];
+		const relationships = this.content.relationships.length > 0
+			? [
+				{ text: "", wide: false },
+				...wrap("Relationships:", "muted"),
+				...this.content.relationships.map((text) => ({ text: theme.fg("text", text), wide: true })),
+			]
+			: [];
+		this.lines = [...identity, ...body, ...labels, ...metadata, ...relationships];
+		this.offsetY = Math.min(this.offsetY, Math.max(0, this.lines.length - this.visibleLines));
+	}
+}
+
+export async function showArtifactDetailView(
+	ctx: ExtensionCommandContext,
+	artifact: Artifact,
+	renderer: GraphRenderer = new BeautifulMermaidRenderer(),
+): Promise<void> {
+	const relationshipLines = buildArtifactRelationshipLines(artifact, renderer);
+	const output = artifactDetailsText(artifact, relationshipLines);
+	if (ctx.mode !== "tui") { ctx.ui.notify(output, "info"); return; }
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) =>
+		new ArtifactDetailViewport(tui, () => ctx.ui.theme ?? theme, artifact, relationshipLines, done));
+}

package/extension/src/artifact-format.ts

@@ -0,0 +1,79 @@
+import { DEFAULT_METADATA_DEPTH, DEFAULT_METADATA_ITEMS, MAX_METADATA_DEPTH, MAX_METADATA_ITEMS } from "@danypops/papyrus";
+
+const STATUS_GLYPHS: Record<string, string> = {
+	todo: "○",
+	"in-progress": "●",
+	review: "◆",
+	rejected: "▲",
+	done: "■",
+	canceled: "×",
+};
+
+export interface MetadataFormatOptions {
+	maxDepth?: number;
+	maxItems?: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function scalar(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (value === null) return "null";
+	if (value === undefined) return "undefined";
+	return JSON.stringify(value);
+}
+
+/** Render arbitrary nested artifact metadata into bounded, human-readable lines. */
+export function formatMetadata(value: unknown, options: MetadataFormatOptions = {}): string[] {
+	const maxDepth = Math.min(MAX_METADATA_DEPTH, Math.max(0, Math.floor(options.maxDepth ?? DEFAULT_METADATA_DEPTH)));
+	const maxItems = Math.min(MAX_METADATA_ITEMS, Math.max(1, Math.floor(options.maxItems ?? DEFAULT_METADATA_ITEMS)));
+	let renderedItems = 0;
+
+	function render(current: unknown, indent: number, depth: number): string[] {
+		const pad = "  ".repeat(indent);
+		if (renderedItems >= maxItems) return [`${pad}…`];
+		if ((Array.isArray(current) || isRecord(current)) && depth >= maxDepth) return [`${pad}…`];
+
+		if (Array.isArray(current)) {
+			const lines: string[] = [];
+			for (const item of current) {
+				if (renderedItems >= maxItems) { lines.push(`${pad}…`); break; }
+				renderedItems++;
+				if (isRecord(item) && typeof item["title"] === "string") {
+					const status = typeof item["status"] === "string" ? item["status"] : "";
+					const glyph = STATUS_GLYPHS[status];
+					lines.push(`${pad}- ${glyph ? `${glyph} ` : ""}${item["title"]}`);
+					const rest = Object.fromEntries(Object.entries(item).filter(([key]) => key !== "title" && key !== "status"));
+					if (Object.keys(rest).length > 0) lines.push(...render(rest, indent + 1, depth + 1));
+				} else if (Array.isArray(item) || isRecord(item)) {
+					lines.push(`${pad}-`);
+					lines.push(...render(item, indent + 1, depth + 1));
+				} else {
+					lines.push(`${pad}- ${scalar(item)}`);
+				}
+			}
+			return lines;
+		}
+
+		if (isRecord(current)) {
+			const lines: string[] = [];
+			for (const [key, item] of Object.entries(current)) {
+				if (renderedItems >= maxItems) { lines.push(`${pad}…`); break; }
+				renderedItems++;
+				if (Array.isArray(item) || isRecord(item)) {
+					lines.push(`${pad}${key}:`);
+					lines.push(...render(item, indent + 1, depth + 1));
+				} else {
+					lines.push(`${pad}${key}: ${scalar(item)}`);
+				}
+			}
+			return lines;
+		}
+
+		return [`${pad}${scalar(current)}`];
+	}
+
+	return render(value, 0, 0);
+}

package/extension/src/artifact-relationship-lines.ts

@@ -0,0 +1,27 @@
+import {
+	GRAPH_RENDER_MAX_ROUTED_EDGES,
+	GRAPH_RENDER_MAX_ROUTED_NODES,
+	projectArtifactRelationships,
+	type Artifact,
+	type GraphRenderer,
+} from "@danypops/papyrus";
+
+/**
+ * Renders an artifact's direct relationships as a small graph when the neighbor set is real
+ * (more than one node) and within the same bound Task graph rendering already enforces;
+ * otherwise falls back to a plain, still name-resolved arrow list -- never the renderer's own
+ * separate box-style fallback, so this view has exactly two shapes, not three.
+ */
+export function buildArtifactRelationshipLines(artifact: Artifact, renderer: GraphRenderer): string[] {
+	const graph = projectArtifactRelationships(artifact);
+	if (graph.edges.length === 0) return [];
+	const withinBounds = graph.nodes.length > 1
+		&& graph.nodes.length <= GRAPH_RENDER_MAX_ROUTED_NODES
+		&& graph.edges.length <= GRAPH_RENDER_MAX_ROUTED_EDGES;
+	if (withinBounds) {
+		const rendered = renderer.render(graph);
+		if (rendered.lines.length > 0) return rendered.lines;
+	}
+	const labelById = new Map(graph.nodes.map((node) => [node.id, node.label]));
+	return graph.edges.map((edge) => `${labelById.get(edge.from) ?? edge.from} --${edge.label}--> ${labelById.get(edge.to) ?? edge.to}`);
+}

package/extension/src/artifact-status-presentation.ts

@@ -0,0 +1,71 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Shared {label, glyph, color} shape, mirroring task-presentation.ts's TASK_STATUS_PRESENTATION
+ * for every other artifact kind's status. Centralizing this closes a real gap: every artifact
+ * browser (Rules, Docs, Notes, Skills) previously rendered status as a bare glyph with no color at
+ * all, which is exactly why "hard to understand which rules are active" was a real complaint --
+ * an active rule's "●" and a deprecated rule's "○" differ only by one filled-vs-hollow pixel shape,
+ * easy to miss at a glance across a scrolling list.
+ */
+export interface StatusPresentation {
+	label: string;
+	glyph: string;
+	color: ThemeColor;
+}
+
+export const RULE_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
+export const DOC_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	draft: { label: "draft", glyph: "○", color: "muted" },
+	active: { label: "active", glyph: "●", color: "success" },
+	archived: { label: "archived", glyph: "■", color: "dim" },
+};
+
+export const NOTE_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	draft: { label: "draft", glyph: "○", color: "muted" },
+	active: { label: "active", glyph: "●", color: "success" },
+	archived: { label: "archived", glyph: "■", color: "dim" },
+};
+
+export const SKILL_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
+export const PLAYBOOK_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
+/**
+ * Keyed by extra.discussion.state, not the shared Doc status column -- a settled Discussion's
+ * doc.status becomes "archived", but a deferred one stays "active" at the doc level (see
+ * domain/discussion.ts's header comment). Reusing DOC_STATUS_PRESENTATION here would render
+ * "deferred" and "active" Discussions with the identical glyph, silently losing the one piece
+ * of state this feature exists to distinguish.
+ */
+export const DISCUSSION_STATE_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "accent" },
+	deferred: { label: "deferred", glyph: "⏸", color: "warning" },
+	settled: { label: "settled", glyph: "✓", color: "success" },
+};
+
+/** Rule severity gets its own color independent of status -- block is the loudest, info the quietest. */
+export const RULE_SEVERITY_PRESENTATION: Record<string, ThemeColor> = {
+	block: "error",
+	warn: "warning",
+	info: "accent",
+};
+
+export function severityColor(severity: string): ThemeColor {
+	return RULE_SEVERITY_PRESENTATION[severity.toLowerCase()] ?? "muted";
+}
+
+/** Plain glyph lookup, for callers that build uncolored text first and colorize it later (e.g. task-graph's colorizeTaskGraphLine pattern). */
+export function glyphOf(presentation: Record<string, StatusPresentation>, status: string): string {
+	return presentation[status]?.glyph ?? "?";
+}

package/extension/src/base-prompt-breakdown.ts

@@ -0,0 +1,55 @@
+import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "@danypops/papyrus";
+import type { ContextSegmentItem } from "./context-budget.ts";
+
+/**
+ * Splits Pi's base system prompt into real structural sub-segments instead of one opaque
+ * number, using BeforeAgentStartEvent's own systemPromptOptions field -- Pi's own doc comment
+ * on it: "Extensions can inspect this to understand what Pi loaded without re-discovering
+ * resources." No new hook, no new risk: before_agent_start is already wired.
+ *
+ * Deliberately measures each INPUT's raw content size (tool snippet text, skill metadata,
+ * context file content) rather than attempting to byte-for-byte reproduce Pi's internal
+ * wrapping/tag format -- buildSystemPrompt() and formatSkillsForPrompt() are Pi-internal
+ * functions, not part of the public extension API Papyrus can call, so reproducing their
+ * exact template text here would be a real, silent drift risk if Pi ever changes it. The
+ * remainder item absorbs whatever wrapping/template text this doesn't attribute, so the
+ * segment's total always still matches the real observed prompt length exactly -- honesty
+ * preserved even though individual sub-segment sizes are approximate, matching the same
+ * known-segments-plus-honest-remainder pattern used everywhere else in this breakdown.
+ */
+export function buildBasePromptItems(options: BuildSystemPromptOptions, totalCharacters: number): ContextSegmentItem[] {
+	const items: ContextSegmentItem[] = [];
+
+	const toolSnippetEntries = Object.entries(options.toolSnippets ?? {});
+	// Mirrors buildSystemPrompt()'s own "- name: snippet\n" line shape closely enough to be a
+	// fair estimate without importing Pi-internal formatting code.
+	const toolSnippetsCharacters = toolSnippetEntries.reduce((sum, [name, snippet]) => sum + name.length + snippet.length + 4, 0);
+	if (toolSnippetsCharacters > 0) {
+		items.push({ label: `Tool snippets (${toolSnippetEntries.length} tools)`, estimatedTokens: toCeilTokens(toolSnippetsCharacters) });
+	}
+
+	const visibleSkills = (options.skills ?? []).filter((skill) => !skill.disableModelInvocation);
+	const skillsCharacters = visibleSkills.reduce((sum, skill) => sum + skill.name.length + skill.description.length + skill.filePath.length + 20, 0);
+	if (skillsCharacters > 0) {
+		items.push({ label: `Skills catalog (${visibleSkills.length} skills)`, estimatedTokens: toCeilTokens(skillsCharacters) });
+	}
+
+	const contextFiles = options.contextFiles ?? [];
+	const contextFilesCharacters = contextFiles.reduce((sum, file) => sum + file.path.length + file.content.length + 40, 0);
+	if (contextFilesCharacters > 0) {
+		items.push({ label: `Project context files (${contextFiles.length}, e.g. AGENTS.md)`, estimatedTokens: toCeilTokens(contextFilesCharacters) });
+	}
+
+	const knownCharacters = toolSnippetsCharacters + skillsCharacters + contextFilesCharacters;
+	const remainderCharacters = Math.max(0, totalCharacters - knownCharacters);
+	if (remainderCharacters > 0 || items.length === 0) {
+		items.push({ label: "Base template, guidelines, and formatting", estimatedTokens: toCeilTokens(remainderCharacters) });
+	}
+
+	return items;
+}
+
+function toCeilTokens(characters: number): number {
+	return Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+}

package/extension/src/beautiful-mermaid-renderer.ts

@@ -0,0 +1,69 @@
+import { renderMermaidASCII } from "beautiful-mermaid";
+import {
+	GRAPH_RENDER_BOX_PADDING,
+	GRAPH_RENDER_MAX_FALLBACK_LINES,
+	GRAPH_RENDER_MAX_ROUTED_EDGES,
+	GRAPH_RENDER_MAX_ROUTED_NODES,
+	GRAPH_RENDER_PADDING_X,
+	GRAPH_RENDER_PADDING_Y,
+	type DisplayGraph,
+	type GraphRenderer,
+	type RenderedGraph,
+} from "@danypops/papyrus";
+
+function nodeLabel(label: string): string {
+	return label.replace(/\s+/g, " ").trim().replaceAll('"', "'");
+}
+
+function edgeLabel(label: string): string {
+	return label.replace(/\s+/g, " ").trim().replaceAll("|", "/");
+}
+
+export function mermaidSource(graph: DisplayGraph): string {
+	const aliases = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
+	const lines = [`flowchart ${graph.direction}`];
+	for (const node of graph.nodes) lines.push(`  ${aliases.get(node.id)}["${nodeLabel(node.label)}"]`);
+	for (const edge of graph.edges) {
+		const from = aliases.get(edge.from);
+		const to = aliases.get(edge.to);
+		if (!from || !to) continue;
+		lines.push(edge.label
+			? `  ${from} -->|${edgeLabel(edge.label)}| ${to}`
+			: `  ${from} --> ${to}`);
+	}
+	return lines.join("\n");
+}
+
+function boundedLineFallback(graph: DisplayGraph): RenderedGraph {
+	const candidates = [
+		"┌─ Task graph ─",
+		`│ ${graph.nodes.length} nodes · ${graph.edges.length} edges · routed layout skipped above ${GRAPH_RENDER_MAX_ROUTED_NODES} nodes`,
+		"├─ Nodes",
+		...graph.nodes.map((node) => `│ ${node.label}`),
+		"├─ Edges",
+		...graph.edges.map((edge) => `│ ${edge.from} ─${edge.label ? `${edge.label}─` : ""}→ ${edge.to}`),
+	];
+	const contentLimit = Math.max(1, GRAPH_RENDER_MAX_FALLBACK_LINES - 1);
+	const lines = candidates.slice(0, contentLimit);
+	const omitted = candidates.length - lines.length;
+	if (omitted > 0) lines[lines.length - 1] = `│ … ${omitted + 1} lines omitted`;
+	lines.push("└─");
+	return { lines };
+}
+
+export class BeautifulMermaidRenderer implements GraphRenderer {
+	render(graph: DisplayGraph): RenderedGraph {
+		if (graph.nodes.length === 0) return { lines: [] };
+		if (graph.nodes.length > GRAPH_RENDER_MAX_ROUTED_NODES || graph.edges.length > GRAPH_RENDER_MAX_ROUTED_EDGES) {
+			return boundedLineFallback(graph);
+		}
+		const output = renderMermaidASCII(mermaidSource(graph), {
+			useAscii: false,
+			paddingX: GRAPH_RENDER_PADDING_X,
+			paddingY: GRAPH_RENDER_PADDING_Y,
+			boxBorderPadding: GRAPH_RENDER_BOX_PADDING,
+			colorMode: "none",
+		});
+		return { lines: output.replace(/\s+$/g, "").split("\n") };
+	}
+}

package/extension/src/bounded-poll.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared idempotent start/stop wrapper over setInterval, extracted once TaskOverlay and
+ * NoteOverlay both needed the identical "fallback refresh for a mutation no event announces"
+ * behavior -- a second start() is a no-op rather than a competing timer, and stop() is safe
+ * to call even if never started.
+ */
+export class BoundedPoll {
+	private timer: ReturnType<typeof setInterval> | undefined;
+
+	start(intervalMs: number, tick: () => void): void {
+		if (this.timer) return;
+		this.timer = setInterval(tick, intervalMs);
+	}
+
+	stop(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = undefined;
+	}
+}