@danypops/papyrus 0.42.1 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.42.1",
+  "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/client.ts

@@ -1,10 +1,14 @@
 import { spawn as spawnProcess } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { connectWithPolicy, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
+import { connectWithVersionCheck, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
+import { readPackageVersion } from "@danypops/vehicle-client/version";
 import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_DIR_ENV, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
 import { type DaemonHandle, daemonStateDir, readDaemonHandle } from "./daemon-state.ts";
 import type { OperationName, SchemaState } from "./service.ts";
 
+/** Compared against the running daemon's /health-reported version by connectWithVersionCheck below -- a long-lived daemon holds whatever code was loaded at its own start. */
+const PAPYRUS_VERSION = readPackageVersion(new URL("../package.json", import.meta.url), "Papyrus");
+
 export type FetchAdapter = (request: Request) => Promise<Response>;
 
 export class PapyrusClient {
@@ -64,6 +68,16 @@ function papyrusCliPath(): string {
 	return fileURLToPath(new URL("cli.ts", import.meta.url));
 }
 
+/** connectWithVersionCheck's killStaleProcess callback, factored out for a direct unit test -- a real spawned daemon can't be made to report a mismatched version without a second build. */
+export function killStalePapyrusDaemon(handle: Pick<DaemonHandle, "pid">): void {
+	if (handle.pid <= 0) return; // daemon-state.ts's inert "unknown pid" sentinel -- never a real process.
+	try {
+		process.kill(handle.pid, "SIGTERM");
+	} catch {
+		// Caller's handle-file poll is the real guarantee, not this call succeeding.
+	}
+}
+
 export interface ConnectPapyrusClientOptions {
 	/**
 	 * Environment passed to an auto-spawned daemon child. Defaults to the current
@@ -74,6 +88,8 @@ export interface ConnectPapyrusClientOptions {
 	 * silently diverge from wherever the child actually starts writing its handle.
 	 */
 	env?: Record<string, string | undefined>;
+	/** Overrides the version connectWithVersionCheck compares against. Defaults to PAPYRUS_VERSION; test-only -- lets a test force a mismatch against a real daemon without a second build. */
+	expectedVersion?: string;
 }
 
 /**
@@ -91,23 +107,30 @@ export async function connectPapyrusClient(
 	dir: string = daemonStateDir(),
 	options: ConnectPapyrusClientOptions = {},
 ): Promise<PapyrusClient> {
-	return connectWithPolicy({
-		readHandle: () => readDaemonHandle(dir) ?? null,
-		buildClient: probedPapyrusClient,
-		autoStart: true,
-		spawn: () => {
-			spawnDetachedDaemon({
-				binPath: papyrusCliPath(),
-				args: ["serve"],
-				env: { ...(options.env ?? process.env), [DAEMON_DIR_ENV]: dir },
-				spawn: (command, args, spawnOptions) => {
-					const child = spawnProcess(command, args, spawnOptions);
-					child.unref();
-				},
-			});
+	return connectWithVersionCheck(
+		{
+			readHandle: () => readDaemonHandle(dir) ?? null,
+			buildClient: probedPapyrusClient,
+			autoStart: true,
+			spawn: () => {
+				spawnDetachedDaemon({
+					binPath: papyrusCliPath(),
+					args: ["serve"],
+					env: { ...(options.env ?? process.env), [DAEMON_DIR_ENV]: dir },
+					spawn: (command, args, spawnOptions) => {
+						const child = spawnProcess(command, args, spawnOptions);
+						child.unref();
+					},
+				});
+			},
+			fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",
+		},
+		{
+			expectedVersion: options.expectedVersion ?? PAPYRUS_VERSION,
+			readVersion: async (client) => (await client.health()).version,
+			killStaleProcess: killStalePapyrusDaemon,
 		},
-		fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",
-	});
+	);
 }
 
 export interface PushChannelTarget {

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 }),