@danypops/papyrus 0.38.0 → 0.38.1

package/package.json

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

@@ -28,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";
@@ -204,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. */
@@ -469,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));
@@ -494,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}"`);
@@ -553,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;
+}