@danypops/papyrus 0.42.2 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.42.2",
+  "version": "0.43.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -34,8 +34,8 @@
   },
   "files": ["src", "README.md"],
   "dependencies": {
-    "@danypops/vehicle-core": "^0.2.0",
-    "@danypops/vehicle-client": "^0.1.1",
-    "@danypops/vehicle-server": "^0.4.1"
+    "@danypops/vehicle-core": "^0.10.0",
+    "@danypops/vehicle-client": "^0.5.0",
+    "@danypops/vehicle-server": "^0.11.0"
   }
 }

package/src/vehicle/artifact-trash-vehicle.ts

@@ -8,7 +8,7 @@ import type { VehicleRegistry } from "@danypops/vehicle-server";
 import { removeArtifactSubtree } from "../artifact-subtree.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
 import type { ArtifactTrashStore } from "../ports/artifact-trash-store.ts";
-import { looseObjectSchema, numberProp, passthroughOutput, stringProp } from "./artifact-vehicle-shared.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, stringProp, validationError } from "./artifact-vehicle-shared.ts";
 
 const OWNER = "artifact";
 const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
@@ -26,7 +26,7 @@ function eventContext(input: Record<string, unknown>): { actor?: string; source?
 
 function requireId(input: Record<string, unknown>): string {
 	const id = input.id;
-	if (typeof id !== "string" || id.length === 0) throw new Error("id is required");
+	if (typeof id !== "string" || id.length === 0) throw validationError("id is required");
 	return id;
 }
 

package/src/vehicle/artifact-vehicle-shared.ts

@@ -3,7 +3,7 @@
  * VehicleRegistry projection (notes-vehicle.ts, rules-vehicle.ts, docs-vehicle.ts,
  * artifact-trash-vehicle.ts).
  */
-import { defineVehicleSchema, type VehicleContentBlock, type VehicleSchemaCodec } from "@danypops/vehicle-core";
+import { defineVehicleSchema, VehicleError, type VehicleContentBlock, type VehicleSchemaCodec } from "@danypops/vehicle-core";
 import type { Artifact } from "../domain/artifact.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
 import type { TaskExecutionPlan } from "../task-execution.ts";
@@ -47,6 +47,19 @@ export const passthroughOutput: VehicleSchemaCodec<unknown> = defineVehicleSchem
 export const stringProp = { type: "string" } as const;
 export const numberProp = { type: "number" } as const;
 
+/**
+ * A plain `throw new Error(...)` inside any resolve()/execute() step here is caught by
+ * vehicle-registry.ts's generic dispatch and re-wrapped as VehicleError("handler-failed",
+ * `${key} handler failed`, {category: "internal"}) -- built to catch a genuine crash, but
+ * it can't distinguish that from an ordinary, expected validation/lookup failure, so it
+ * discards the original message and category either way. Every guard clause and name
+ * resolution below must throw a VehicleError directly so it passes through that dispatch
+ * unchanged (vehicle-registry.ts only rewraps errors that are NOT already a VehicleError).
+ */
+export function validationError(message: string): VehicleError {
+	return new VehicleError("validation-failed", message, { category: "validation" });
+}
+
 /** A known LLM tool-calling quirk: a nested-object field arrives JSON-stringified rather than as a real object. Mutates input[key] in place when it's a string, leaves it untouched otherwise. */
 export function normalizeJsonEncodedField(input: Record<string, unknown>, key: string): void {
 	const value = input[key];
@@ -54,7 +67,7 @@ export function normalizeJsonEncodedField(input: Record<string, unknown>, key: s
 	try {
 		input[key] = JSON.parse(value);
 	} catch {
-		throw new Error(`${key} must be valid JSON`);
+		throw validationError(`${key} must be valid JSON`);
 	}
 }
 
@@ -62,10 +75,14 @@ export function normalizeJsonEncodedField(input: Record<string, unknown>, key: s
 export 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 === 0) {
+		throw new VehicleError("artifact-not-found", `no artifact named "${name}" found in this scope`, { category: "not_found" });
+	}
 	if (matches.length > 1) {
-		throw new Error(
+		throw new VehicleError(
+			"artifact-name-ambiguous",
 			`${matches.length} artifacts are named "${name}": ${matches.map((a) => `${a.title} (${a.id})`).join(", ")} -- use id to disambiguate`,
+			{ category: "conflict" },
 		);
 	}
 	return matches[0]!.id;
@@ -85,7 +102,7 @@ export function resolveArtifactIdWidened(
 	try {
 		return matchArtifactByName(fetchCandidates(), name);
 	} catch (error) {
-		if (!(error instanceof Error) || !error.message.startsWith("no artifact named") || !fetchWidened) throw error;
+		if (!(error instanceof VehicleError) || error.code !== "artifact-not-found" || !fetchWidened) throw error;
 		return matchArtifactByName(fetchWidened(), name);
 	}
 }

package/src/vehicle/docs-vehicle.ts

@@ -10,7 +10,7 @@ import { listDocuments } from "../domain-services.ts";
 import { docsOperations } from "../modules/docs.ts";
 import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
-import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp, validationError } from "./artifact-vehicle-shared.ts";
 
 const OWNER = "docs";
 const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
@@ -23,7 +23,7 @@ function resolveDocId(
 	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");
+	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
 	return resolveArtifactIdWidened(
 		name,
 		() => listDocuments(artifacts, scopes, { text: name, projectRoot }),
@@ -34,7 +34,7 @@ function resolveDocId(
 /** Cross-kind resolution for a link target -- can be a doc, task, rule, or playbook. Unscoped, matching the exact behavior of the artifact.query-backed resolution it replaces. */
 function resolveTargetId(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");
+	if (typeof name !== "string" || name.length === 0) throw validationError("target_id or target_name is required");
 	return resolveArtifactIdWidened(name, () => artifacts.query({ text: name }));
 }
 

package/src/vehicle/notes-vehicle.ts

@@ -12,7 +12,7 @@ import type { VehicleRegistry } from "@danypops/vehicle-server";
 import { notesOperations } from "../modules/notes.ts";
 import { NOTE_DISPOSITIONS, type Notes } from "../note-service.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
-import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp, validationError } from "./artifact-vehicle-shared.ts";
 
 const OWNER = "notes";
 
@@ -21,14 +21,14 @@ const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes:
 /** 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");
+	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
 	return resolveArtifactIdWidened(name, () => notes.list({ projectRoot, text: name }));
 }
 
 /** Cross-kind equivalent for a promotion target -- a target can be a task, doc, rule, or playbook, 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");
+	if (typeof name !== "string" || name.length === 0) throw validationError("target_id or target_name is required");
 	return resolveArtifactIdWidened(name, () => artifacts.query({ text: name }));
 }
 

package/src/vehicle/playbooks-vehicle.ts

@@ -37,6 +37,7 @@ import {
 	passthroughOutput,
 	resolveArtifactIdWidened,
 	stringProp,
+	validationError,
 } from "./artifact-vehicle-shared.ts";
 
 const OWNER = "playbooks";
@@ -54,7 +55,7 @@ export interface PlaybooksVehicleDeps {
 /** Unscoped resolution -- a Playbook is commonly cross-project (e.g. a lab-deploy playbook), matching the hand-rolled tool's own resolutionRequest choice. */
 function resolvePlaybookId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, 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");
+	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
 	return resolveArtifactIdWidened(name, () => listPlaybooks(artifacts, scopes, { text: name }));
 }
 

package/src/vehicle/rules-vehicle.ts

@@ -10,7 +10,7 @@ import { listRules } from "../domain-services.ts";
 import { rulesOperations } from "../modules/rules.ts";
 import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
-import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp, validationError } from "./artifact-vehicle-shared.ts";
 
 const OWNER = "rules";
 const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
@@ -24,7 +24,7 @@ function resolveRuleId(
 	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");
+	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
 	return resolveArtifactIdWidened(
 		name,
 		() => listRules(artifacts, scopes, { text: name, projectRoot }),
@@ -151,7 +151,7 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 		[],
 		(input) => {
 			const taskId = resolveTaskId(artifacts, input.project_root as string | undefined, input.task_id, input.task_name);
-			if (!taskId) throw new Error("task_id or task_name is required");
+			if (!taskId) throw validationError("task_id or task_name is required");
 			return {
 				...input,
 				id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name),

package/src/vehicle/tasks-vehicle.ts

@@ -34,6 +34,7 @@ import {
 	passthroughOutput,
 	resolveArtifactIdWidened,
 	stringProp,
+	validationError,
 } from "./artifact-vehicle-shared.ts";
 
 const OWNER = "tasks";
@@ -70,8 +71,8 @@ function resolveTaskId(
 	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");
-	if (!filter.projectRoot) throw new Error("project_root is required when resolving a task by name");
+	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
+	if (!filter.projectRoot) throw validationError("project_root is required when resolving a task by name");
 	return resolveArtifactIdWidened(
 		name,
 		() => tasks.list({ ...filter, text: name }),