@danypops/papyrus 0.37.0 → 0.38.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -34,6 +34,8 @@
   },
   "files": ["src", "README.md"],
   "dependencies": {
-    "@danypops/daemon-kit": "^0.10.0"
+    "@danypops/daemon-kit": "^0.10.0",
+    "@danypops/vehicle-core": "^0.1.0",
+    "@danypops/vehicle-server": "^0.1.0"
   }
 }

package/src/artifact-subtree.ts

@@ -0,0 +1,54 @@
+/**
+ * Bulk trash of a `contains` subtree, any artifact kind -- a whole materialized Task run
+ * (root container + steps + nested playbook children) or a Playbook's own nested-playbook
+ * tree can be moved to trash in one call instead of enumerating every id by hand. Mirrors
+ * Tasks.cancelSubtree's traversal shape but performs trash(), not a lifecycle transition,
+ * so it applies to any kind that participates in `contains` (task, playbook), not just Task.
+ */
+import { ARTIFACT_REMOVE_SUBTREE_MAX_NODES } from "./constants.ts";
+import type { ArtifactEventContext } from "./domain/artifact-event.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import type { ArtifactTrashStore } from "./ports/artifact-trash-store.ts";
+
+export interface RemoveSubtreeResult {
+	removed: string[];
+	/** Already trashed -- a real no-op, not an error, matching trash()/restore()'s own idempotence elsewhere. */
+	skipped: string[];
+}
+
+/**
+ * Trashes `id` and every artifact reachable by following `contains` edges outward from it,
+ * transitively. An already-trashed node is skipped rather than re-trashed (trash() itself is
+ * idempotent, but skipping keeps the result's `removed` list meaningful -- only nodes newly
+ * moved to trash by this call). A node that is the live Task Focus in some scope still throws
+ * (the same guard trash() always enforces for a single artifact) rather than being silently
+ * skipped -- an active Focus is a real conflict to surface, not routine already-done state.
+ */
+export function removeArtifactSubtree(
+	store: ArtifactStore & ArtifactTrashStore,
+	id: string,
+	options: { reason?: string; context?: ArtifactEventContext } = {},
+): RemoveSubtreeResult {
+	if (!store.get(id)) throw new Error(`artifact "${id}" not found`);
+	const visited = new Set<string>();
+	const queue = [id];
+	const removed: string[] = [];
+	const skipped: string[] = [];
+	while (queue.length > 0) {
+		const current = queue.shift()!;
+		if (visited.has(current)) continue;
+		visited.add(current);
+		if (visited.size > ARTIFACT_REMOVE_SUBTREE_MAX_NODES) throw new Error(`remove_subtree exceeds ${ARTIFACT_REMOVE_SUBTREE_MAX_NODES} artifacts`);
+		const childIds = store.relationships({ artifactIds: [current] })
+			.filter((edge) => edge.from === current && edge.relation === "contains")
+			.map((edge) => edge.to);
+		queue.push(...childIds);
+		if (store.trashStatus(current)) {
+			skipped.push(current);
+			continue;
+		}
+		store.trash(current, { reason: options.reason, context: options.context });
+		removed.push(current);
+	}
+	return { removed, skipped };
+}

package/src/cli.ts

@@ -83,6 +83,7 @@ const USAGE = `Usage:
   papyrus artifact query [--kind <kind>] [--status <status>] [--text <query>] [--limit <count>] [--json]
   papyrus artifact show <id> [--depth <n>] [--max-nodes <n>] [--json]
   papyrus artifact remove <id> [--reason <text>] [--json]
+  papyrus artifact remove-subtree <id> [--reason <text>] [--json]
   papyrus artifact restore <id> [--json]
   papyrus artifact trash-status <id> [--json]
   papyrus artifact trash-list [--json]
@@ -1023,6 +1024,13 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 			human = `Trashed ${record.artifactId}: eligible for purge at ${record.purgeAfter}`;
 			break;
 		}
+		case "remove-subtree": {
+			if (!id) throw new Error("artifact remove-subtree requires exactly one artifact id");
+			const outcome = await client.call<Record<string, unknown>, { removed: string[]; skipped: string[] }>("artifact.remove_subtree", { id, reason });
+			result = outcome;
+			human = `Trashed ${outcome.removed.length} artifact(s)${outcome.skipped.length > 0 ? `, skipped ${outcome.skipped.length} already-trashed` : ""}.`;
+			break;
+		}
 		case "restore": {
 			if (!id) throw new Error("artifact restore requires exactly one artifact id");
 			const outcome = await client.call<Record<string, unknown>, { restored: boolean }>("artifact.restore", { id });
@@ -1045,7 +1053,7 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 			break;
 		}
 		default:
-			throw new Error("artifact action must be create, query, show, remove, restore, trash-status, or trash-list");
+			throw new Error("artifact action must be create, query, show, remove, remove-subtree, restore, trash-status, or trash-list");
 	}
 	return json ? JSON.stringify(result) : human;
 }

package/src/client.ts

@@ -78,3 +78,22 @@ export function resolvePushChannelTarget(dir: string = daemonStateDir()): PushCh
 	if (!handle) return undefined;
 	return { url: `${handle.baseUrl.replace(/^http/, "ws")}/push`, token: handle.token };
 }
+
+export interface VehicleClientTarget {
+	/** Base URL for a domain migrated onto VehicleRegistry (see src/vehicle/*.ts) -- @danypops/vehicle-client's RemoteVehicleClient mounts its own /vehicle/manifest, /vehicle/invoke, /vehicle/cancel routes under this. */
+	baseUrl: string;
+	token: string;
+}
+
+/**
+ * Narrow surface for a Vehicle-projected domain consumer -- same daemon, same
+ * handle file, same Bearer token every other Papyrus RPC call already uses (see
+ * service.ts's createApp, which mounts the Vehicle HTTP app at /vehicle/* on
+ * this same port). Returns undefined rather than throwing when the daemon has
+ * never started, matching resolvePushChannelTarget's own tolerance.
+ */
+export function resolveVehicleClientTarget(dir: string = daemonStateDir()): VehicleClientTarget | undefined {
+	const handle = readDaemonHandle(dir);
+	if (!handle) return undefined;
+	return { baseUrl: handle.baseUrl, token: handle.token };
+}

package/src/constants.ts

@@ -123,6 +123,8 @@ export const PLAYBOOK_INVOCATION_MAX_CREATED_TASKS = 200;
 
 /** Tasks.cancelSubtree walks `contains` edges transitively (a whole materialized playbook run can be torn down in one call instead of enumerating every task id by hand) -- bounded the same way PLAYBOOK_INVOCATION_MAX_CREATED_TASKS bounds the forward direction. */
 export const TASK_CANCEL_SUBTREE_MAX_NODES = 500;
+/** artifact.remove_subtree walks `contains` transitively across any artifact kind (a task tree, or a playbook's own nested-playbook children) -- same bound rationale as TASK_CANCEL_SUBTREE_MAX_NODES, kept separate since the two traversals serve different operations. */
+export const ARTIFACT_REMOVE_SUBTREE_MAX_NODES = 500;
 
 /**
  * At the core, a workflow Skill creates Tasks and begins a pipeline -- an Ansible playbook or

package/src/index.ts

@@ -19,7 +19,7 @@ export type { TaskViewSelection } from "./domain/task-scope.ts";
 export type { ArtifactStore } from "./ports/artifact-store.ts";
 export type { GraphRenderer } from "./ports/graph-renderer.ts";
 
-export { connectPapyrusClient, resolvePushChannelTarget, type PapyrusClient, type PushChannelTarget } from "./client.ts";
+export { connectPapyrusClient, resolvePushChannelTarget, resolveVehicleClientTarget, type PapyrusClient, type PushChannelTarget, type VehicleClientTarget } from "./client.ts";
 export type { DiscussionAndRounds } from "./discussion-service.ts";
 export { NOTE_DISPOSITIONS } from "./note-service.ts";
 export type { OperationName, SchemaState } from "./service.ts";

package/src/service.ts

@@ -1,6 +1,7 @@
 import { SERVICE_MAX_BODY_BYTES, SQLITE_SCHEMA_VERSION } from "./constants.ts";
 import { VERSION } from "./version.ts";
 import { migrateDb, openDb, schemaVersion } from "./db.ts";
+import { removeArtifactSubtree } from "./artifact-subtree.ts";
 import { SQLiteArtifactStore } from "./adapters/sqlite-artifact-store.ts";
 import { SQLiteGateRunner } from "./adapters/sqlite-gate-runner.ts";
 import { SQLiteArtifactScopeStore } from "./adapters/sqlite-artifact-scope-store.ts";
@@ -27,6 +28,9 @@ import {
 	listInjectableRules,
 } from "./domain-services.ts";
 import { Notes, NOTE_SUBTYPE } from "./note-service.ts";
+import { createNotesVehicleRegistry } from "./vehicle/notes-vehicle.ts";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
 import { Logs } from "./log-service.ts";
 import { SQLiteLogStore } from "./adapters/sqlite-log-store.ts";
 import { SessionIdentity, InvalidSessionSecretError } from "./session-identity-service.ts";
@@ -57,7 +61,7 @@ import { SQLiteDiscussionRoundStore } from "./adapters/sqlite-discussion-round-s
  */
 const COMPOSITION_ROOT_OPERATION_NAMES = [
 	"system.migrate", "artifact.create", "artifact.query", "artifact.show",
-	"artifact.remove", "artifact.restore", "artifact.trash_status", "artifact.trash_list",
+	"artifact.remove", "artifact.remove_subtree", "artifact.restore", "artifact.trash_status", "artifact.trash_list",
 	"graph.link", "graph.unlink", "graph.tree", "graph.status", "graph.history", "gates.run",
 	"rules.injectable", "skills.instantiate",
 ] as const;
@@ -203,6 +207,13 @@ export interface PapyrusService {
 	operationNames(): OperationName[];
 	schemaState(): SchemaState;
 	execute(operation: string, input?: OperationInput): Promise<unknown>;
+	/**
+	 * Notes projected as a real VehicleRegistry (see ./vehicle/notes-vehicle.ts) --
+	 * one honest VehicleOperation per real action, replacing the Pi extension's old
+	 * `notes(action=X)` mega-tool. The first domain migrated this way; not every
+	 * domain has one yet.
+	 */
+	readonly notesVehicle: VehicleRegistry;
 	checkpoint(): void;
 	optimize(): void;
 	/** Time-based Task Focus reclamation (see Tasks.reapStaleFocus); returns how many rows were removed, for daemon logging. */
@@ -280,6 +291,7 @@ function handlers(
 			maxNodes: optionalNumber(input, "max_nodes") ?? optionalNumber(input, "maxNodes"),
 		}),
 		"artifact.remove": (input) => artifacts.trash(string(input, "id"), { reason: optionalString(input, "reason"), context: eventContext(input) }),
+		"artifact.remove_subtree": (input) => removeArtifactSubtree(artifacts, string(input, "id"), { reason: optionalString(input, "reason"), context: eventContext(input) }),
 		"artifact.restore": (input) => artifacts.restore(string(input, "id"), eventContext(input)),
 		"artifact.trash_status": (input) => artifacts.trashStatus(string(input, "id")),
 		"artifact.trash_list": () => artifacts.listTrash(),
@@ -467,6 +479,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases);
 	const noteEvents = new SQLiteNoteEventStore(db);
 	const notes = new Notes(artifacts, noteEvents);
+	const notesVehicle = createNotesVehicleRegistry(notes, artifacts);
 	const projections = new SQLiteGraphProjectionStore(db);
 	const artifactScopes = new SQLiteArtifactScopeStore(db);
 	const logs = new Logs(new SQLiteLogStore(db));
@@ -492,6 +505,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	return {
 		operationNames: () => [...EXPECTED_OPERATION_NAMES],
 		schemaState: state,
+		notesVehicle,
 		async execute(operation, input = {}) {
 			const handler = registry[operation as OperationName];
 			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
@@ -551,12 +565,17 @@ export function createApp(deps: {
 	 */
 	onOperationExecuted?: (operation: string, input: OperationInput) => void;
 }): { fetch(request: Request): Promise<Response> } {
+	// Same Bearer token as the rest of this API -- a Vehicle-projected domain (see
+	// ./vehicle/notes-vehicle.ts) rides the same daemon, same auth, same port; it is
+	// not a second service to stand up or authenticate against separately.
+	const vehicleApp = createVehicleHttpApp({ registry: deps.service.notesVehicle, token: deps.token });
 	return {
 		async fetch(request: Request): Promise<Response> {
 			if (request.headers.get("authorization") !== `Bearer ${deps.token}`) {
 				return json({ error: "missing or invalid bearer token" }, { status: 401 });
 			}
 			const url = new URL(request.url);
+			if (url.pathname.startsWith("/vehicle/")) return vehicleApp.fetch(request);
 			if (request.method === "GET" && url.pathname === "/health") {
 				return json({ ok: true, version: VERSION, schema: deps.service.schemaState() });
 			}

package/src/vehicle/notes-vehicle.ts

@@ -0,0 +1,210 @@
+/**
+ * Notes projected as a real VehicleRegistry: one VehicleOperation per real
+ * action (capture/list/show/history/consume/promote/archive), each with its
+ * own honest effect and narrow schema -- replacing pi-papyrus's hand-rolled
+ * `notes(action=X)` mega-tool (unconstrained `action: Type.String()`, 14
+ * fields unioned across all 7 branches, the "God Parameters"/"Kitchen Sink
+ * tool" anti-pattern @danypops/vehicle's own README documents).
+ *
+ * Wraps modules/notes.ts's existing operation definitions rather than
+ * reimplementing their input parsing -- this is a projection/contract layer
+ * on top of the existing domain logic, not a second copy of it. Adds the
+ * one thing those definitions don't do: resolving a human-readable
+ * `name`/`target_name` to the `id`/`target_id` the domain logic actually
+ * needs, server-side in the same call. The Pi-extension-side
+ * `resolveNameFields` helper it replaces needed a separate round trip per
+ * name before the real call; this does it in one.
+ */
+import { defineVehicleOperation, defineVehicleSchema, bindVehicleOperation, type VehicleSchemaCodec } from "@danypops/vehicle-core";
+import { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import { Notes, NOTE_DISPOSITIONS } from "../note-service.ts";
+import type { Artifact } from "../domain/artifact.ts";
+import { notesOperations } from "../modules/notes.ts";
+
+const OWNER = "notes";
+
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+/**
+ * VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
+ * descriptive metadata surfaced to a client/Pi projection, never itself
+ * enforced at runtime -- so a declared `enum` has to be checked here for
+ * real, or it's a documentation gesture, not an honest contract.
+ */
+function looseObjectSchema(properties: Record<string, { type: string; enum?: readonly string[] }>, required: readonly string[] = []): VehicleSchemaCodec<Record<string, unknown>> {
+	return defineVehicleSchema<Record<string, unknown>>({
+		jsonSchema: { type: "object", properties, required: [...required], additionalProperties: false },
+		safeParse(value) {
+			if (typeof value !== "object" || value === null || Array.isArray(value)) {
+				return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+			}
+			const input = value as Record<string, unknown>;
+			for (const key of required) {
+				if (!(key in input)) return { success: false, issues: [{ path: [key], message: `${key} is required` }] };
+			}
+			for (const [key, schema] of Object.entries(properties)) {
+				if (!schema.enum || !(key in input)) continue;
+				if (!schema.enum.includes(input[key] as string)) {
+					return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
+				}
+			}
+			return { success: true, value: input };
+		},
+	});
+}
+
+const passthroughOutput = defineVehicleSchema<unknown>({
+	jsonSchema: { type: "object" },
+	safeParse: (value) => ({ success: true, value }),
+});
+
+/** Exact match semantics as the Pi-extension helper it replaces (domain-tools.ts's matchArtifactByName) -- case-insensitive exact title match, refuses to guess between ambiguous matches. */
+function matchArtifactByName(candidates: readonly Artifact[], name: string): string {
+	const needle = name.trim().toLowerCase();
+	const matches = candidates.filter((artifact) => artifact.title.trim().toLowerCase() === needle);
+	if (matches.length === 0) throw new Error(`no artifact named "${name}" found in this scope`);
+	if (matches.length > 1) {
+		throw new Error(`${matches.length} artifacts are named "${name}": ${matches.map((a) => `${a.title} (${a.id})`).join(", ")} -- use id to disambiguate`);
+	}
+	return matches[0]!.id;
+}
+
+/** Resolves a note's id from either an explicit id or its title within projectRoot. */
+function resolveNoteId(notes: Notes, projectRoot: string, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("id or name is required");
+	return matchArtifactByName(notes.list({ projectRoot, text: name }), name);
+}
+
+/** Cross-kind equivalent for a promotion target -- a target can be a task, doc, rule, or skill, not just a note. Unscoped by project, matching the exact behavior of the artifact.query-backed resolution it replaces. */
+function resolveArtifactId(artifacts: ArtifactStore, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("target_id or target_name is required");
+	return matchArtifactByName(artifacts.query({ text: name }), name);
+}
+
+/**
+ * Builds a VehicleRegistry exposing every notes.* action as its own honest
+ * operation. `artifacts` is only needed for promote's cross-kind
+ * target_name resolution -- every other operation only ever touches notes
+ * themselves via `notes`.
+ */
+export function createNotesVehicleRegistry(notes: Notes, artifacts: ArtifactStore): VehicleRegistry {
+	const registry = new VehicleRegistry({ name: "papyrus-notes", version: "1.0.0", description: "Papyrus's deferred human-intent inbox." });
+	const moduleOperations = new Map(notesOperations(notes).map((op) => [op.name, op]));
+	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `notes.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["notes:read", "notes:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => call(`notes.${action}`, resolve(context.input))));
+	};
+
+	const stringProp = { type: "string" } as const;
+	const numberProp = { type: "number" } as const;
+
+	define(
+		"capture",
+		"Stores a deferred request without creating work. Returns the created note.",
+		"local-write",
+		{ body: stringProp, title: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["body", "project_root"],
+		(input) => input,
+	);
+
+	define(
+		"list",
+		"Lists open (draft/active) notes, or a specific status, in a project.",
+		"read",
+		{ project_root: stringProp, status: { type: "string", enum: ["draft", "active", "archived"] }, text: stringProp, limit: numberProp },
+		["project_root"],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one note by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		["project_root"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	define(
+		"history",
+		"This note's own real append-only event log (captured/consumed/promoted/archived).",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp, limit: numberProp, cursor: numberProp, direction: { type: "string", enum: ["asc", "desc"] } },
+		["project_root"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	define(
+		"consume",
+		"Marks a note as considered.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp, reason: stringProp },
+		["project_root"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	define(
+		"promote",
+		"Links a note to the Task, Doc, Rule, or Skill it was promoted into, then archives it.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			target_id: stringProp,
+			target_name: stringProp,
+			project_root: stringProp,
+			actor: stringProp,
+			source: stringProp,
+			session_id: stringProp,
+			reason: stringProp,
+		},
+		["project_root"],
+		(input) => ({
+			...input,
+			id: resolveNoteId(notes, input.project_root as string, input.id, input.name),
+			target_id: resolveArtifactId(artifacts, input.target_id, input.target_name),
+		}),
+	);
+
+	define(
+		"archive",
+		"Archives a note with an explicit disposition.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			project_root: stringProp,
+			disposition: { type: "string", enum: [...NOTE_DISPOSITIONS] },
+			actor: stringProp,
+			source: stringProp,
+			session_id: stringProp,
+			reason: stringProp,
+		},
+		["project_root", "disposition"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	return registry;
+}