@danypops/papyrus 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

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/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/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";
@@ -57,7 +58,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;
@@ -280,6 +281,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(),