@roodriigoooo/pi-docket 0.4.0

package/extensions/event-log.ts

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import type { CheckpointIndexEntry } from "./types.js";
+
+export type CheckpointEvent =
+	| { type: "checkpoint_saved"; timestamp: string; entry: CheckpointIndexEntry }
+	| { type: "checkpoint_consumed"; timestamp: string; id: string; consumedAt: string }
+	| { type: "checkpoint_unconsumed"; timestamp: string; id: string }
+	| { type: "checkpoint_purged"; timestamp: string; id: string }
+	| { type: "checkpoint_swept"; timestamp: string; ids: string[]; retentionDays: number };
+
+export type EventLog = {
+	append(event: CheckpointEvent): Promise<void>;
+	read(): Promise<CheckpointEvent[]>;
+	rebuildIndex(): Promise<CheckpointIndexEntry[]>;
+	backfillFromIndex(entries: CheckpointIndexEntry[]): Promise<void>;
+	path(): string;
+};
+
+function eventLogFile(): string {
+	return path.join(getAgentDir(), "docket", "events.ndjson");
+}
+
+async function ensureParent(file: string): Promise<void> {
+	await fs.mkdir(path.dirname(file), { recursive: true });
+}
+
+async function fileExists(file: string): Promise<boolean> {
+	try {
+		await fs.access(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function applyEvent(state: Map<string, CheckpointIndexEntry>, event: CheckpointEvent): void {
+	if (event.type === "checkpoint_saved") {
+		state.set(event.entry.id, { ...event.entry });
+		return;
+	}
+	if (event.type === "checkpoint_consumed") {
+		const entry = state.get(event.id);
+		if (entry && !entry.consumedAt) state.set(event.id, { ...entry, consumedAt: event.consumedAt });
+		return;
+	}
+	if (event.type === "checkpoint_unconsumed") {
+		const entry = state.get(event.id);
+		if (entry?.consumedAt) {
+			const { consumedAt: _drop, ...rest } = entry;
+			state.set(event.id, rest);
+		}
+		return;
+	}
+	if (event.type === "checkpoint_purged") {
+		state.delete(event.id);
+		return;
+	}
+	if (event.type === "checkpoint_swept") {
+		for (const id of event.ids) state.delete(id);
+		return;
+	}
+}
+
+export function replayEvents(events: CheckpointEvent[]): CheckpointIndexEntry[] {
+	const state = new Map<string, CheckpointIndexEntry>();
+	for (const event of events) applyEvent(state, event);
+	return [...state.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+function parseLine(line: string): CheckpointEvent | undefined {
+	const trimmed = line.trim();
+	if (!trimmed) return undefined;
+	try {
+		const parsed = JSON.parse(trimmed) as Partial<CheckpointEvent> & { type?: string };
+		if (typeof parsed.type !== "string") return undefined;
+		return parsed as CheckpointEvent;
+	} catch {
+		return undefined;
+	}
+}
+
+export function createEventLog(): EventLog {
+	const file = eventLogFile();
+	return {
+		path() {
+			return file;
+		},
+		async append(event: CheckpointEvent): Promise<void> {
+			await ensureParent(file);
+			await fs.appendFile(file, `${JSON.stringify(event)}\n`, "utf8");
+		},
+		async read(): Promise<CheckpointEvent[]> {
+			if (!(await fileExists(file))) return [];
+			const raw = await fs.readFile(file, "utf8");
+			const events: CheckpointEvent[] = [];
+			for (const line of raw.split("\n")) {
+				const event = parseLine(line);
+				if (event) events.push(event);
+			}
+			return events;
+		},
+		async rebuildIndex(): Promise<CheckpointIndexEntry[]> {
+			return replayEvents(await this.read());
+		},
+		async backfillFromIndex(entries: CheckpointIndexEntry[]): Promise<void> {
+			if (entries.length === 0) return;
+			if (await fileExists(file)) return;
+			await ensureParent(file);
+			const lines: string[] = [];
+			for (const entry of entries) {
+				lines.push(JSON.stringify({ type: "checkpoint_saved", timestamp: entry.createdAt, entry } satisfies CheckpointEvent));
+				if (entry.consumedAt) {
+					lines.push(JSON.stringify({ type: "checkpoint_consumed", timestamp: entry.consumedAt, id: entry.id, consumedAt: entry.consumedAt } satisfies CheckpointEvent));
+				}
+			}
+			await fs.writeFile(file, `${lines.join("\n")}\n`, "utf8");
+		},
+	};
+}

package/extensions/git-context.ts

@@ -0,0 +1,44 @@
+import { spawnSync } from "node:child_process";
+import type { GitSnapshot } from "./types.js";
+
+function runGit(cwd: string, args: string[]): string | undefined {
+	const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+	if (result.error || result.status !== 0) return undefined;
+	return result.stdout.trim();
+}
+
+export function parseGitPorcelain(output: string): Pick<GitSnapshot, "dirty" | "staged" | "unstaged" | "untracked"> {
+	const lines = output.split(/\r?\n/).filter((line) => line.length > 0);
+	let staged = 0;
+	let unstaged = 0;
+	let untracked = 0;
+	for (const line of lines) {
+		if (line.startsWith("??")) {
+			untracked++;
+			continue;
+		}
+		if (line[0] && line[0] !== " ") staged++;
+		if (line[1] && line[1] !== " ") unstaged++;
+	}
+	return { dirty: lines.length, staged, unstaged, untracked };
+}
+
+export function readGitSnapshot(cwd: string): GitSnapshot | undefined {
+	if (runGit(cwd, ["rev-parse", "--is-inside-work-tree"]) !== "true") return undefined;
+	const branch = runGit(cwd, ["branch", "--show-current"]);
+	const head = runGit(cwd, ["rev-parse", "--short", "HEAD"]);
+	const porcelain = runGit(cwd, ["status", "--porcelain"]);
+	const counts = parseGitPorcelain(porcelain ?? "");
+	return {
+		branch: branch || undefined,
+		head: head || undefined,
+		...counts,
+	};
+}
+
+export function gitSnapshotLabel(git: GitSnapshot | undefined): string | undefined {
+	if (!git) return undefined;
+	const base = git.branch || (git.head ? `@${git.head}` : undefined);
+	if (!base) return undefined;
+	return git.dirty && git.dirty > 0 ? `${base} ±${git.dirty}` : base;
+}

package/extensions/loaded-artifact-context.ts

@@ -0,0 +1,228 @@
+import { createArtifactCatalog, type ArtifactCatalog, type DocketRuntimeContext } from "./artifact-catalog.js";
+import { loadConfig, type DocketConfig } from "./docket-config.js";
+import type { Artifact, ArtifactKind, CheckpointIndexEntry } from "./types.js";
+import { workerShortLabel, type WorkerStatus } from "./background-work.js";
+
+export type ChipMode = "ref" | "full";
+
+export type Chip = {
+	displayId: string;
+	ref: string;
+	mode: ChipMode;
+	kind: ArtifactKind;
+	title: string;
+};
+
+export type ChipToggleResult = "added" | "removed" | "upgraded" | "downgraded";
+
+export type CarryoverKind = "checkpoint" | "worker";
+
+export type CarryoverSlot = {
+	slot: string;
+	kind: CarryoverKind;
+	sourceId: string;
+	artifacts: Artifact[];
+	checkpoint?: CheckpointIndexEntry;
+};
+
+export type LoadableSource =
+	| { kind: "checkpoint"; checkpoint: CheckpointIndexEntry }
+	| { kind: "worker"; worker: WorkerStatus };
+
+export type LoadableSourceCandidates = {
+	checkpoints: CheckpointIndexEntry[];
+	workers: WorkerStatus[];
+};
+
+export type LoadResult = {
+	source: LoadableSource;
+	slot: CarryoverSlot;
+	queuedConsume: boolean;
+};
+
+export type ChipExpansion = {
+	text: string;
+	expanded: number;
+	missing: string[];
+};
+
+export type LoadedArtifactContextDeps = {
+	loadConfig?: (cwd: string) => Promise<DocketConfig>;
+	createCatalog?: (ctx: DocketRuntimeContext, config: DocketConfig, carryover: Artifact[]) => ArtifactCatalog;
+	readCheckpointArtifacts: (checkpoint: CheckpointIndexEntry) => Promise<Artifact[]>;
+	readWorkerArtifacts: (worker: WorkerStatus) => Promise<Artifact[]>;
+};
+
+export type LoadedArtifactContext = {
+	chips(): Chip[];
+	slots(): CarryoverSlot[];
+	carryoverArtifacts(): Artifact[];
+	reset(): void;
+	defaultLoadSource(candidates: LoadableSourceCandidates): LoadableSource | undefined;
+	loadSource(source: LoadableSource): Promise<LoadResult>;
+	loadCheckpoint(checkpoint: CheckpointIndexEntry): Promise<CarryoverSlot>;
+	loadWorker(worker: WorkerStatus): Promise<CarryoverSlot>;
+	unloadSlot(slot: string): CarryoverSlot | undefined;
+	unloadSource(kind: CarryoverKind, sourceId: string): CarryoverSlot | undefined;
+	queueCheckpointConsume(checkpoint: CheckpointIndexEntry): void;
+	drainCheckpointConsumes(markConsumed: (checkpoint: CheckpointIndexEntry) => Promise<void>): Promise<void>;
+	toggleChip(artifact: Artifact, mode: ChipMode): ChipToggleResult;
+	clearChips(): boolean;
+	expandChipsForSubmit(ctx: DocketRuntimeContext, userText: string): Promise<ChipExpansion>;
+};
+
+function namespaceCarryover(artifacts: Artifact[], slot: string): Artifact[] {
+	return artifacts.map((artifact) => {
+		const namespacedId = `${slot}.${artifact.displayId}`;
+		return { ...artifact, id: namespacedId, displayId: namespacedId, source: slot };
+	});
+}
+
+function renderChipBlock(chip: Chip, content: string): string {
+	const opener = `<<docket @${chip.displayId} ${chip.mode}>>`;
+	const closer = `<</docket>>`;
+	return `${opener}\n${content}\n${closer}`;
+}
+
+export function createLoadedArtifactContext(deps: LoadedArtifactContextDeps): LoadedArtifactContext {
+	let chips: Chip[] = [];
+	let carryover: Map<string, CarryoverSlot> = new Map();
+	let pendingCheckpointConsumes: Map<string, CheckpointIndexEntry> = new Map();
+	let nextCheckpointSlotIndex = 1;
+
+	const findSlotForSource = (kind: CarryoverKind, sourceId: string): CarryoverSlot | undefined => {
+		for (const slot of carryover.values()) {
+			if (slot.kind === kind && slot.sourceId === sourceId) return slot;
+		}
+		return undefined;
+	};
+
+	const carryoverArtifacts = (): Artifact[] => {
+		const out: Artifact[] = [];
+		for (const slot of carryover.values()) out.push(...slot.artifacts);
+		return out;
+	};
+
+	const unloadSlot = (slot: string): CarryoverSlot | undefined => {
+		const entry = carryover.get(slot);
+		if (!entry) return undefined;
+		carryover.delete(slot);
+		if (entry.kind === "checkpoint") pendingCheckpointConsumes.delete(entry.sourceId);
+		return entry;
+	};
+
+	const loadCheckpoint = async (checkpoint: CheckpointIndexEntry): Promise<CarryoverSlot> => {
+		const existing = findSlotForSource("checkpoint", checkpoint.id);
+		if (existing) return existing;
+		const raw = await deps.readCheckpointArtifacts(checkpoint);
+		const slot = `c${nextCheckpointSlotIndex++}`;
+		const entry: CarryoverSlot = { slot, kind: "checkpoint", sourceId: checkpoint.id, artifacts: namespaceCarryover(raw, slot), checkpoint };
+		carryover.set(slot, entry);
+		return entry;
+	};
+
+	const loadWorker = async (worker: WorkerStatus): Promise<CarryoverSlot> => {
+		const existing = findSlotForSource("worker", worker.id);
+		if (existing) return existing;
+		const raw = await deps.readWorkerArtifacts(worker);
+		const slot = workerShortLabel(worker.index);
+		const entry: CarryoverSlot = { slot, kind: "worker", sourceId: worker.id, artifacts: namespaceCarryover(raw, slot) };
+		carryover.set(slot, entry);
+		return entry;
+	};
+
+	const loadSource = async (source: LoadableSource): Promise<LoadResult> => {
+		const slot = source.kind === "checkpoint" ? await loadCheckpoint(source.checkpoint) : await loadWorker(source.worker);
+		const queuedConsume = source.kind === "checkpoint" && source.checkpoint.consumeOnUse === true;
+		if (queuedConsume) pendingCheckpointConsumes.set(source.checkpoint.id, source.checkpoint);
+		return { source, slot, queuedConsume };
+	};
+
+	return {
+		chips() {
+			return [...chips];
+		},
+		slots() {
+			return [...carryover.values()];
+		},
+		carryoverArtifacts,
+		reset() {
+			chips = [];
+			carryover = new Map();
+			pendingCheckpointConsumes = new Map();
+			nextCheckpointSlotIndex = 1;
+		},
+		defaultLoadSource(candidates: LoadableSourceCandidates): LoadableSource | undefined {
+			const checkpoint = candidates.checkpoints[candidates.checkpoints.length - 1];
+			if (checkpoint) return { kind: "checkpoint", checkpoint };
+			const worker = candidates.workers[candidates.workers.length - 1];
+			return worker ? { kind: "worker", worker } : undefined;
+		},
+		loadSource,
+		loadCheckpoint(checkpoint: CheckpointIndexEntry): Promise<CarryoverSlot> {
+			return loadSource({ kind: "checkpoint", checkpoint }).then((result) => result.slot);
+		},
+		loadWorker(worker: WorkerStatus): Promise<CarryoverSlot> {
+			return loadSource({ kind: "worker", worker }).then((result) => result.slot);
+		},
+		unloadSlot,
+		unloadSource(kind: CarryoverKind, sourceId: string): CarryoverSlot | undefined {
+			const entry = findSlotForSource(kind, sourceId);
+			if (!entry) return undefined;
+			return unloadSlot(entry.slot);
+		},
+		queueCheckpointConsume(checkpoint: CheckpointIndexEntry): void {
+			pendingCheckpointConsumes.set(checkpoint.id, checkpoint);
+		},
+		async drainCheckpointConsumes(markConsumed: (checkpoint: CheckpointIndexEntry) => Promise<void>): Promise<void> {
+			if (pendingCheckpointConsumes.size === 0) return;
+			const pending = [...pendingCheckpointConsumes.values()];
+			pendingCheckpointConsumes = new Map();
+			await Promise.all(pending.map(async (checkpoint) => {
+				try { await markConsumed(checkpoint); }
+				catch { /* best-effort */ }
+			}));
+		},
+		toggleChip(artifact: Artifact, mode: ChipMode): ChipToggleResult {
+			const idx = chips.findIndex((c) => c.ref === artifact.ref);
+			if (idx === -1) {
+				chips = [...chips, { displayId: artifact.displayId, ref: artifact.ref, mode, kind: artifact.kind, title: artifact.title }];
+				return "added";
+			}
+			const existing = chips[idx]!;
+			if (existing.mode === mode) {
+				chips = chips.filter((_, i) => i !== idx);
+				return "removed";
+			}
+			chips = chips.map((c, i) => (i === idx ? { ...c, mode } : c));
+			return mode === "full" ? "upgraded" : "downgraded";
+		},
+		clearChips(): boolean {
+			if (chips.length === 0) return false;
+			chips = [];
+			return true;
+		},
+		async expandChipsForSubmit(ctx: DocketRuntimeContext, userText: string): Promise<ChipExpansion> {
+			if (chips.length === 0) return { text: userText, expanded: 0, missing: [] };
+			const config = await (deps.loadConfig ?? loadConfig)(ctx.cwd);
+			const catalog = (deps.createCatalog ?? createArtifactCatalog)(ctx, config, carryoverArtifacts());
+			const blocks: string[] = [];
+			const missing: string[] = [];
+			for (const chip of chips) {
+				const artifact = catalog.find(chip.ref) ?? catalog.find(chip.displayId);
+				if (!artifact) {
+					missing.push(chip.displayId);
+					continue;
+				}
+				const body = chip.mode === "full" ? catalog.fullText(artifact) : catalog.reference(artifact);
+				blocks.push(renderChipBlock(chip, body));
+			}
+			if (blocks.length === 0) return { text: userText, expanded: 0, missing };
+			const header = `<<docket-context: ${blocks.length} reference${blocks.length === 1 ? "" : "s"}>>`;
+			const footer = `<</docket-context>>`;
+			const wrapped = `${header}\n${blocks.join("\n\n")}\n${footer}`;
+			const text = userText.trim() ? `${wrapped}\n\n${userText}` : wrapped;
+			return { text, expanded: blocks.length, missing };
+		},
+	};
+}

package/extensions/search-index.ts

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { Artifact, ArtifactKind } from "./types.js";
+
+export type ArtifactSearchDocument = {
+	id: string;
+	artifact: Artifact;
+	title: string;
+	body: string;
+	rankText: {
+		primary: string;
+		body: string;
+		metadata: string;
+	};
+	content: string;
+};
+
+export type RipgrepAdapter = (query: string, documents: ArtifactSearchDocument[]) => Promise<Set<string>>;
+
+export type ArtifactSearchOptions = {
+	runRipgrep?: RipgrepAdapter;
+};
+
+const KIND_WEIGHT: Record<ArtifactKind, number> = {
+	error: 700,
+	file: 600,
+	command: 500,
+	code: 400,
+	checkpoint: 300,
+	prompt: 200,
+	response: 100,
+};
+
+function includes(text: string, query: string): boolean {
+	return text.toLowerCase().includes(query);
+}
+
+function formatSearchDocument(artifact: Artifact, metadata: string): string {
+	return [
+		`# Docket artifact ${artifact.displayId}`,
+		`ref: ${artifact.ref}`,
+		`kind: ${artifact.kind}`,
+		artifact.entryId ? `entry: ${artifact.entryId}` : undefined,
+		artifact.title ? `title: ${artifact.title}` : undefined,
+		artifact.subtitle ? `subtitle: ${artifact.subtitle}` : undefined,
+		"",
+		artifact.title,
+		"",
+		artifact.body,
+		"",
+		"metadata:",
+		metadata,
+	].filter((line): line is string => line !== undefined).join("\n");
+}
+
+export function buildArtifactSearchDocument(artifact: Artifact): ArtifactSearchDocument {
+	const metadata = JSON.stringify(artifact.meta ?? {}, null, 2);
+	const primary = [artifact.displayId, artifact.ref, artifact.kind, artifact.title, artifact.subtitle].filter(Boolean).join("\n");
+	return {
+		id: artifact.displayId,
+		artifact,
+		title: artifact.title,
+		body: artifact.body,
+		rankText: { primary, body: artifact.body, metadata },
+		content: formatSearchDocument(artifact, metadata),
+	};
+}
+
+async function runCommand(command: string, args: string[]): Promise<{ code: number | null; stdout: string; stderr: string }> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args);
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (data) => (stdout += data.toString("utf8")));
+		child.stderr.on("data", (data) => (stderr += data.toString("utf8")));
+		child.on("error", reject);
+		child.on("close", (code) => resolve({ code, stdout, stderr }));
+		child.stdin.end();
+	});
+}
+
+function safeFileName(index: number, document: ArtifactSearchDocument): string {
+	const id = document.artifact.displayId.replace(/[^a-zA-Z0-9._-]/g, "_") || "artifact";
+	return `${index}-${id}.md`;
+}
+
+async function runRipgrepAdapter(query: string, documents: ArtifactSearchDocument[]): Promise<Set<string>> {
+	const tempDir = await fs.mkdtemp(path.join(tmpdir(), "pi-docket-search-"));
+	try {
+		const byFile = new Map<string, string>();
+		for (let i = 0; i < documents.length; i++) {
+			const document = documents[i]!;
+			const fileName = safeFileName(i, document);
+			byFile.set(fileName, document.id);
+			await fs.writeFile(path.join(tempDir, fileName), document.content, "utf8");
+		}
+
+		const result = await runCommand("rg", ["--files-with-matches", "--fixed-strings", "--ignore-case", "-e", query, tempDir]);
+		if (result.code === 0) {
+			return new Set(result.stdout.split("\n").map((line) => byFile.get(path.basename(line))).filter((id): id is string => Boolean(id)));
+		}
+		if (result.code === 1) return new Set();
+		throw new Error(result.stderr || `rg exited ${result.code}`);
+	} finally {
+		await fs.rm(tempDir, { recursive: true, force: true });
+	}
+}
+
+function scoreDocument(query: string, document: ArtifactSearchDocument): number {
+	const primary = includes(document.rankText.primary, query);
+	const body = includes(document.rankText.body, query);
+	const metadata = includes(document.rankText.metadata, query);
+	if (!primary && !body && !metadata) return 0;
+	return KIND_WEIGHT[document.artifact.kind] + (primary ? 50 : 0) + (body ? 20 : 0) + (metadata ? 10 : 0);
+}
+
+function rankDocuments(query: string, documents: ArtifactSearchDocument[]): Artifact[] {
+	return documents
+		.map((document, index) => ({ document, index, score: scoreDocument(query, document) }))
+		.filter((result) => result.score > 0)
+		.sort((a, b) => b.score - a.score || a.index - b.index)
+		.map((result) => result.document.artifact);
+}
+
+export async function searchArtifacts(query: string, artifacts: Artifact[], options: ArtifactSearchOptions = {}): Promise<Artifact[]> {
+	const needle = query.trim().toLowerCase();
+	if (!needle) return [];
+
+	const documents = artifacts.map(buildArtifactSearchDocument);
+	const runRipgrep = options.runRipgrep ?? runRipgrepAdapter;
+	try {
+		const ids = await runRipgrep(query, documents);
+		const matches = documents.filter((document) => ids.has(document.id));
+		return rankDocuments(needle, matches);
+	} catch {
+		return rankDocuments(needle, documents);
+	}
+}

package/extensions/types.ts

@@ -0,0 +1,40 @@
+export type ArtifactKind = "command" | "error" | "file" | "code" | "prompt" | "response" | "checkpoint";
+export type CheckpointMode = "handoff" | "compact" | "debug" | "review";
+
+export type GitSnapshot = {
+	branch?: string;
+	head?: string;
+	dirty?: number;
+	staged?: number;
+	unstaged?: number;
+	untracked?: number;
+};
+
+export type Artifact = {
+	id: string; // displayId alias, kept for command compatibility
+	displayId: string;
+	ref: string;
+	kind: ArtifactKind;
+	title: string;
+	subtitle: string;
+	body: string;
+	entryId?: string;
+	timestamp?: number;
+	meta?: Record<string, unknown>;
+	source?: string; // undefined = current session; otherwise carryover slot id (e.g. "c1")
+};
+
+export type ArtifactSummary = Pick<Artifact, "displayId" | "ref" | "kind" | "title" | "subtitle" | "timestamp">;
+
+export type CheckpointIndexEntry = {
+	id: string;
+	mode: CheckpointMode;
+	file: string;
+	createdAt: string;
+	cwd: string;
+	sourceSession?: string;
+	note?: string;
+	consumeOnUse?: boolean;
+	consumedAt?: string;
+	git?: GitSnapshot;
+};