@danypops/papyrus 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# Papyrus
+
+Graph artifact service for Pi — enforced SQLite schema, domain facades, and native interactive frontends.
+
+Artifacts are rows in SQLite. Edges are typed relations. Kinds and relations are **registered and enforced**—the schema is the protocol. A supervised Bun daemon is the sole database owner; Pi extensions and other clients use its authenticated loopback service API.
+
+## Architecture
+
+```text
+Pi tools + TUI
+      ↓
+tasks / docs / rules / skills facades
+      ↓
+Papyrus client → authenticated loopback daemon
+      ↓
+operation registry + lifecycle services
+      ↓
+graph-store operations → SQLite (WAL)
+```
+
+The `papyrus_*` tools remain low-level administration escape hatches. Normal agent work should use the domain facade tools.
+
+## Storage and service
+
+```text
+$XDG_DATA_HOME/papyrus/papyrus.db       # durable graph
+$XDG_RUNTIME_DIR/papyrus/{port,token}   # private daemon discovery
+```
+
+```bash
+bun src/cli.ts service install   # install, enable, and start user service
+bun src/cli.ts service status
+bun src/cli.ts service restart
+```
+
+For repository work, install the versioned ownership guard once:
+
+```bash
+bun run guard:install
+```
+
+It blocks every Papyrus push whose destination is not `DanyPops/papyrus`, including explicit fallback URLs that bypass `origin`.
+
+The daemon uses WAL, foreign keys, a bounded busy timeout, versioned migrations, periodic passive checkpoints, and periodic `PRAGMA optimize`. Keep the database on a local filesystem; SQLite WAL does not support network filesystems.
+
+## Schema protocol (enforceable)
+
+Papyrus enforces four artifact kinds:
+
+- `doc` — knowledge: specifications, decisions, and research
+- `task` — work: desired outcomes, gates, checklists, and dependencies
+- `rule` — governance injected into the Pi system prompt
+- `skill` — reusable procedural knowledge
+
+Each kind has an enforced status vocabulary. Every edge endpoint must exist, and every edge relation must be registered in `relation_names`. Relations are universal: any artifact kind can link to any other kind.
+
+### Hierarchy and traversal
+
+Use `contains` and `part_of` for explicit parent/child structure; use `depends_on` for execution ordering. Graph reads are cycle-safe and bounded by `depth` and `max_nodes` (defaults: depth 4, 100 nodes; hard ceilings: depth 20, 1,000 nodes).
+
+### Artifact templates
+
+Templates remain inside the four-kind model: create a `skill` with subtype `artifact-template` and metadata `{targetKind, defaults, required}`. Instantiate it through `papyrus_create` with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
+
+## Tools
+
+The `papyrus_*` tools are the low-level graph-store API:
+
+- **`papyrus_create`** — create directly or instantiate via `template_id`
+- **`papyrus_query`** — filter by kind/status or search title and body
+- **`papyrus_graph`** — link artifacts, perform bounded traversal, or update status
+- **`papyrus_show`** — read nested metadata and bounded edges, optionally running gates
+
+Agent-facing facade tools own domain lifecycle invariants and sit above this store API:
+
+- **`tasks`** — create/list/show, replace evidence-bearing checklists, hierarchy/dependencies, start/fail/retry, non-blocking gates, and gate-enforced completion
+- **`docs`** — create/list/show, activate/archive/reopen, and document-safe graph links
+- **`rules`** — create/list/show/preview, enable/disable, and attach governance gates to tasks
+- **`skills`** — create/list/show/invoke, enable/disable, create templates, and instantiate templates
+
+Every tool operation is registered in the daemon’s `/api/v1/ops` registry; parity is verified in tests. The task consumer uses the `tasks.graph` operation, which returns task nodes with explicit parent, child, and dependency IDs rather than leaking SQLite rows or asking the UI to reconstruct relationships.
+
+Internally, application services depend on the `ArtifactStore` and `GateRunner` ports. SQLite and subprocess execution are adapters composed only by the daemon; task behavior is unit-tested against fakes without a database. Task visualization projects the same `TaskGraph` into semantic display graphs and sends them through a `GraphRenderer` port; the Pi adapter uses `beautiful-mermaid` for terminal Unicode output without leaking Mermaid syntax into the task domain.
+
+## Interactive frontends
+
+- `/tasks` — task lifecycle, gates, dependencies, and nested metadata
+- `/docs` — searchable documents, lifecycle, details, and graph links
+- `/rules` — severity/condition rows, exact injection preview, enable/disable, and task gating
+- `/skills` — trigger/tools rows, invocation into the editor, and artifact templates
+
+All four use daemon-backed domain operations; none opens SQLite from the Pi process.
+
+## Tasks
+
+Run `/tasks` for the interactive task panel:
+
+- `/` filters; arrow keys navigate; Enter opens task actions
+- `g` opens the programmatic Unicode graph; Tab switches dependency/composition views and arrow keys pan
+- advance the `pending → active → done` lifecycle or retry `failed → pending`
+- inspect a nested task hierarchy, composition, dependencies, evidence-bearing checklists, and verification gates
+- Show details keeps Checklist and Validation gates separate from incidental Metadata, then renders relationships as a Unicode graph footer; `↑/↓` scrolls and `←/→` pans wide graphs
+- the compact persistent widget shows active work in containment order, indents active children beneath active parents, and points to `/tasks` for the complete graph
+
+Checklist criteria are an item-to-proof map. Every new item requires one or more typed references to inspectable evidence; proof presence does not imply that the evidence passed an executable gate:
+
+```ts
+checklist: {
+  "Write failing skill-row tests": {
+    proof: [
+      { type: "file", target: "test/frontends.test.ts" },
+      { type: "symbol", target: "test/frontends.test.ts#skill row test" }
+    ]
+  }
+}
+```
+
+Proof types are `file`, `symbol`, `code`, `test`, `command`, `artifact`, and `url`. Existing array checklists remain readable as legacy items with `proof: missing`; Papyrus does not invent evidence.
+
+Papyrus also injects an Alef-style reconciliation block on every agent turn while work remains: `Current`, `Desired`, `Verify`, and `Next`. The agent is explicitly instructed to ask **“Did we accomplish this task?”** and run gates before marking it done. The injection disappears when every task is complete.
+
+## Why
+
+Papyrus keeps SQLite’s local simplicity while centralizing writes, migrations, lifecycle invariants, gate execution, and maintenance in one small supervised process. The loopback bearer token prevents unrelated local HTTP callers from mutating the graph, while the native Pi extension provides richer domain tools and TUI integration.
+
+## Install
+
+Install the published Pi package, then install its supervised user service:
+
+```bash
+pi install npm:@danypops/papyrus
+~/.pi/agent/npm/node_modules/.bin/papyrus service install
+```
+
+Reload Pi once the service is active. Git installs remain available for development builds:
+
+```bash
+pi install git:github.com/DanyPops/papyrus
+```

package/extension/src/artifact-browser.ts

@@ -0,0 +1,213 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, rawKeyHint } from "@earendil-works/pi-coding-agent";
+import { Container, Input, Spacer, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { SEED_RELATIONS } from "../../src/constants.ts";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import type { OperationName } from "../../src/service.ts";
+import { formatMetadata } from "./artifact-format.ts";
+import { callService } from "./service-client.ts";
+
+const BROWSER_QUERY_LIMIT = 500;
+const BROWSER_VISIBLE_ROWS = 20;
+const DETAIL_GRAPH_DEPTH = 4;
+const DETAIL_GRAPH_NODES = 100;
+
+export interface ArtifactBrowserConfig {
+	kind: string;
+	title: string;
+	statusOrder: string[];
+	glyphs: Record<string, string>;
+	listOperation?: OperationName;
+	rowMeta(row: Artifact): string;
+	actions(row: Artifact): string[];
+	handleAction(choice: string, row: Artifact, ctx: ExtensionCommandContext): Promise<void>;
+}
+
+export function filterArtifactRows(rows: Artifact[], query: string): Artifact[] {
+	const needle = query.trim().toLowerCase();
+	if (!needle) return [...rows];
+	return rows.filter((row) => [
+		row.id,
+		row.title,
+		row.body,
+		row.subtype,
+		row.labels.join(" "),
+		JSON.stringify(row.extra),
+	].some((value) => value.toLowerCase().includes(needle)));
+}
+
+export function statusSummary(rows: Artifact[], order: string[]): Array<{ status: string; count: number }> {
+	const counts = new Map<string, number>();
+	for (const row of rows) counts.set(row.status, (counts.get(row.status) ?? 0) + 1);
+	return order.filter((status) => counts.has(status)).map((status) => ({ status, count: counts.get(status)! }));
+}
+
+async function loadArtifacts(config: ArtifactBrowserConfig): Promise<Artifact[]> {
+	return callService<Record<string, unknown>, Artifact[]>(config.listOperation ?? "artifact.query", {
+		kind: config.kind,
+		limit: BROWSER_QUERY_LIMIT,
+	});
+}
+
+export async function showArtifactDetails(
+	ctx: ExtensionCommandContext,
+	id: string,
+	operation: OperationName = "artifact.show",
+): Promise<void> {
+	const artifact = await callService<Record<string, unknown>, Artifact | null>(operation, {
+		id,
+		tree: true,
+		depth: DETAIL_GRAPH_DEPTH,
+		max_nodes: DETAIL_GRAPH_NODES,
+	});
+	if (!artifact) { ctx.ui.notify(`Artifact ${id} not found`, "error"); return; }
+	let output = `${artifact.title}\n${artifact.id} [${artifact.kind}|${artifact.status}]`;
+	if (artifact.subtype) output += ` · ${artifact.subtype}`;
+	if (artifact.body) output += `\n\n${artifact.body}`;
+	if (artifact.labels.length > 0) output += `\n\nLabels: ${artifact.labels.join(", ")}`;
+	if (Object.keys(artifact.extra).length > 0) {
+		output += `\n\nMetadata:\n${formatMetadata(artifact.extra).map((line) => `  ${line}`).join("\n")}`;
+	}
+	if (artifact.edges?.length) {
+		output += `\n\nEdges:\n${artifact.edges.map((edge) => `  ${edge.from} --${edge.relation}--> ${edge.to}`).join("\n")}`;
+	}
+	ctx.ui.notify(output, "info");
+}
+
+export async function linkFromArtifact(ctx: ExtensionCommandContext, fromId: string, fixedRelation?: string): Promise<void> {
+	const target = await ctx.ui.input("Target artifact id:", "");
+	if (!target) return;
+	const relation = fixedRelation ?? await ctx.ui.select("Relation", [...SEED_RELATIONS]);
+	if (!relation) return;
+	try {
+		await callService("graph.link", { from: fromId, relation, to: target });
+		ctx.ui.notify(`Linked ${fromId} --${relation}--> ${target}`, "info");
+	} catch (error) {
+		ctx.ui.notify(`Link failed: ${error instanceof Error ? error.message : error}`, "error");
+	}
+}
+
+export async function setArtifactStatus(ctx: ExtensionCommandContext, id: string, status: string): Promise<void> {
+	try {
+		const artifact = await callService<Record<string, unknown>, Artifact | null>("graph.status", { id, status });
+		if (!artifact) { ctx.ui.notify(`Artifact ${id} not found`, "error"); return; }
+		ctx.ui.notify(`${artifact.id} → [${artifact.status}]`, "info");
+	} catch (error) {
+		ctx.ui.notify(`Status change failed: ${error instanceof Error ? error.message : error}`, "error");
+	}
+}
+
+export async function showArtifactBrowser(ctx: ExtensionCommandContext, config: ArtifactBrowserConfig): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(`/${config.kind}s requires interactive mode`, "warning");
+		return;
+	}
+	let rows = await loadArtifacts(config);
+	if (rows.length === 0) {
+		ctx.ui.notify(`No ${config.kind} artifacts yet. Ask the agent to create one.`, "info");
+		return;
+	}
+
+	for (;;) {
+		const selected = await renderPanel(ctx, rows, config);
+		if (selected === undefined) return;
+		if (selected === "refresh") { rows = await loadArtifacts(config); continue; }
+		const choices = config.actions(selected);
+		const choice = await ctx.ui.select(selected.title, choices);
+		if (!choice) continue;
+		await config.handleAction(choice, selected, ctx);
+		rows = await loadArtifacts(config);
+	}
+}
+
+function renderPanel(
+	ctx: ExtensionCommandContext,
+	rows: Artifact[],
+	config: ArtifactBrowserConfig,
+): Promise<Artifact | "refresh" | undefined> {
+	return ctx.ui.custom<Artifact | "refresh" | undefined>((tui, theme, _keybindings, done) => {
+		const input = new Input();
+		let searchActive = false;
+		let filtered = [...rows];
+		let selectedIndex = 0;
+
+		function applyFilter(): void {
+			filtered = filterArtifactRows(rows, input.getValue());
+			selectedIndex = 0;
+		}
+
+		const header = {
+			invalidate() {},
+			render(width: number): string[] {
+				const title = theme.bold(config.title);
+				const hint = searchActive
+					? rawKeyHint("esc", "clear")
+					: [rawKeyHint("enter", "actions"), rawKeyHint("/", "filter"), rawKeyHint("r", "refresh"), rawKeyHint("esc", "close")]
+						.join(theme.fg("muted", " · "));
+				const spacing = Math.max(1, width - visibleWidth(title) - visibleWidth(hint));
+				const summary = statusSummary(rows, config.statusOrder)
+					.map(({ status, count }) => `${config.glyphs[status] ?? status} ${count} ${status}`)
+					.join(", ");
+				return [
+					truncateToWidth(`${title}${" ".repeat(spacing)}${hint}`, width, ""),
+					truncateToWidth(theme.fg("muted", summary), width, ""),
+				];
+			},
+		};
+
+		const list = {
+			invalidate() {},
+			render(width: number): string[] {
+				const lines = searchActive ? [...input.render(width), ""] : [""];
+				if (filtered.length === 0) return [...lines, theme.fg("muted", `  No matching ${config.kind}s`)];
+				const start = Math.max(0, Math.min(selectedIndex - Math.floor(BROWSER_VISIBLE_ROWS / 2), filtered.length - BROWSER_VISIBLE_ROWS));
+				const end = Math.min(start + BROWSER_VISIBLE_ROWS, filtered.length);
+				for (let index = start; index < end; index++) {
+					const row = filtered[index]!;
+					const selected = index === selectedIndex;
+					const cursor = selected ? theme.fg("accent", "❯") : " ";
+					const glyph = config.glyphs[row.status] ?? "?";
+					const title = selected ? theme.bold(row.title) : row.title;
+					const meta = config.rowMeta(row);
+					lines.push(truncateToWidth(`${cursor} ${glyph} ${title}${meta ? theme.fg("dim", ` · ${meta}`) : ""}`, width, ""));
+				}
+				lines.push(theme.fg("muted", `  ${selectedIndex + 1}/${filtered.length} ${config.kind}`));
+				return lines;
+			},
+		};
+
+		const container = new Container();
+		container.addChild(new Spacer(1));
+		container.addChild(new DynamicBorder());
+		container.addChild(new Spacer(1));
+		container.addChild(header);
+		container.addChild(new Spacer(1));
+		container.addChild(list);
+		container.addChild(new Spacer(1));
+		container.addChild(new DynamicBorder());
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput(data: string) {
+				if (searchActive) {
+					if (data === "\x1b") { searchActive = false; applyFilter(); }
+					else if (data === "\r") searchActive = false;
+					else { input.handleInput(data); applyFilter(); }
+					tui.requestRender();
+					return;
+				}
+				switch (data) {
+					case "\x1b[A": selectedIndex = (selectedIndex - 1 + filtered.length) % Math.max(filtered.length, 1); break;
+					case "\x1b[B": selectedIndex = (selectedIndex + 1) % Math.max(filtered.length, 1); break;
+					case "/": searchActive = true; break;
+					case "r": done("refresh"); return;
+					case "\r": { const row = filtered[selectedIndex]; if (row) done(row); return; }
+					case "\x1b": done(undefined); return;
+					default: return;
+				}
+				tui.requestRender();
+			},
+		};
+	});
+}

package/extension/src/artifact-format.ts

@@ -0,0 +1,82 @@
+import {
+	DEFAULT_METADATA_DEPTH,
+	DEFAULT_METADATA_ITEMS,
+	MAX_METADATA_DEPTH,
+	MAX_METADATA_ITEMS,
+} from "../../src/constants.ts";
+
+const STATUS_GLYPHS: Record<string, string> = {
+	pending: "○",
+	active: "●",
+	done: "■",
+	failed: "▲",
+};
+
+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/beautiful-mermaid-renderer.ts

@@ -0,0 +1,45 @@
+import { renderMermaidASCII } from "beautiful-mermaid";
+import {
+	GRAPH_RENDER_BOX_PADDING,
+	GRAPH_RENDER_PADDING_X,
+	GRAPH_RENDER_PADDING_Y,
+} from "../../src/constants.ts";
+import type { DisplayGraph, RenderedGraph } from "../../src/domain/display-graph.ts";
+import type { GraphRenderer } from "../../src/ports/graph-renderer.ts";
+
+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");
+}
+
+export class BeautifulMermaidRenderer implements GraphRenderer {
+	render(graph: DisplayGraph): RenderedGraph {
+		if (graph.nodes.length === 0) return { lines: [] };
+		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/docs.ts

@@ -0,0 +1,48 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { callService } from "./service-client.ts";
+
+const DOC_GLYPHS: Record<string, string> = { draft: "○", active: "●", archived: "■" };
+const DOC_ACTIONS: Record<string, string[]> = {
+	draft: ["Activate", "Archive"],
+	active: ["Archive"],
+	archived: ["Reopen"],
+};
+const DOC_RELATIONS = ["references", "documents", "supersedes", "relates_to", "contains", "part_of"];
+
+export function documentRowMeta(document: Artifact): string {
+	return [document.subtype, document.labels.join(", ")].filter(Boolean).join(" · ");
+}
+
+export async function showDocs(ctx: ExtensionCommandContext): Promise<void> {
+	await showArtifactBrowser(ctx, {
+		kind: "doc",
+		title: "Documents",
+		listOperation: "docs.list",
+		statusOrder: ["draft", "active", "archived"],
+		glyphs: DOC_GLYPHS,
+		rowMeta: documentRowMeta,
+		actions: (document) => ["Show details", "Link artifact", ...(DOC_ACTIONS[document.status] ?? [])],
+		handleAction: async (choice, document, commandCtx) => {
+			if (choice === "Show details") {
+				await showArtifactDetails(commandCtx, document.id, "docs.show");
+				return;
+			}
+			if (choice === "Link artifact") {
+				const targetId = await commandCtx.ui.input("Target artifact id:", "");
+				if (!targetId) return;
+				const relation = await commandCtx.ui.select("Relation", DOC_RELATIONS);
+				if (!relation) return;
+				await callService("docs.link", { id: document.id, relation, target_id: targetId });
+				commandCtx.ui.notify(`Linked ${document.id} --${relation}--> ${targetId}`, "info");
+				return;
+			}
+			const operation = choice === "Activate" ? "docs.activate" : choice === "Archive" ? "docs.archive" : choice === "Reopen" ? "docs.reopen" : undefined;
+			if (operation) {
+				const updated = await callService<Record<string, unknown>, Artifact>(operation, { id: document.id });
+				commandCtx.ui.notify(`${updated.id} → [${updated.status}]`, "info");
+			}
+		},
+	});
+}