@danypops/papyrus 0.58.1 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.58.1",
+  "version": "0.59.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/cli/batch-command.ts

@@ -0,0 +1,54 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type BatchClient = Pick<PapyrusClient, "call">;
+type BatchItemResult = { ok: true; result: unknown } | { ok: false; error: string };
+type BatchResult = { results: BatchItemResult[] };
+
+interface BatchContext extends CommandContext {
+	readonly client: BatchClient;
+	readonly json: boolean;
+}
+
+/** No further shape assertion here -- the service validates each item's own {op, input} shape;
+ * this only needs a real JSON array to hand off. */
+function parseItems(value: string): unknown[] {
+	const parsed = JSON.parse(value) as unknown;
+	if (!Array.isArray(parsed)) throw new Error("--items-json must be a JSON array");
+	return parsed;
+}
+
+const runCommand = buildCommand({
+	func: async function (this: BatchContext, flags: { itemsJson: unknown[] }) {
+		const result = await this.client.call<Record<string, unknown>, BatchResult>("batch.execute", { items: flags.itemsJson });
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(result));
+			return;
+		}
+		const lines = result.results.map((entry, index) =>
+			entry.ok ? `[${index}] ok: ${JSON.stringify(entry.result)}` : `[${index}] failed: ${entry.error}`,
+		);
+		this.process.stdout.write(lines.join("\n"));
+	},
+	parameters: {
+		flags: {
+			itemsJson: {
+				brief: 'JSON array of {"op": "<operation>", "input": {...}} entries -- each fans out exactly like a direct call to that operation',
+				kind: "parsed",
+				parse: parseItems,
+				placeholder: "json",
+			},
+		},
+	},
+	docs: { brief: "Fan out N independent operations in one call, so N artifact mutations don't need N separate round-trips" },
+});
+
+const app = buildApplication(runCommand, { name: "batch", scanner: { caseStyle: "allow-kebab-for-camel" } });
+
+export async function runBatchCli(args: string[], client: BatchClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli.ts

@@ -4,6 +4,7 @@ import { copyFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFi
 import { fileURLToPath } from "node:url";
 import { createNodeServiceInstallDeps, generateSystemdUnit, installUserService, type ServiceSpec } from "@danypops/vehicle-server/service";
 import { runArtifactCli } from "./cli/artifact-command.ts";
+import { runBatchCli } from "./cli/batch-command.ts";
 import { runDaemonCli } from "./cli/daemon-command.ts";
 import { runDiscussCli } from "./cli/discuss-command.ts";
 import { runDocsCli } from "./cli/docs-command.ts";
@@ -353,6 +354,7 @@ export function runIdMigrationCli(args: string[]): string {
 
 export {
 	runArtifactCli,
+	runBatchCli,
 	runDiscussCli,
 	runDocsCli,
 	runGatesCli,
@@ -419,6 +421,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runMigrationCli(args.slice(1), client));
 		return;
 	}
+	if (command === "batch") {
+		const client = await connectPapyrusClient();
+		console.log(await runBatchCli(args.slice(1), client));
+		return;
+	}
 	if (command === "daemon") {
 		const client = await connectPapyrusClient();
 		console.log(await runDaemonCli(args.slice(1), client));

package/src/constants.ts

@@ -325,6 +325,10 @@ export const TOOL_COLLAPSED_ROW_LIMIT = 5;
 export const TOOL_DETAILS_MAX_ITEMS = 100;
 export const TOOL_DETAILS_MAX_EDGES = 200;
 
+/** batch.execute's own bound on items.length -- a caller should get a clear rejection above
+ * this, not an unbounded server-side fan-out loop. */
+export const BATCH_MAX_ITEMS = 100;
+
 /** Reconciliation instruction appended whenever Papyrus has open work. */
 export const TASK_RECONCILIATION_INSTRUCTION = [
 	"Reconcile before concluding or moving on:",

package/src/handlers/artifact-helpers.ts

@@ -1,9 +1,4 @@
-/**
- * Cross-domain artifact name/id resolution and workflow-run narrative building, split out of
- * handlers/shared.ts as part of a SOLID-audit-driven decomposition (see Doc "Modularity playbook:
- * building-block-shaped TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts
- * split" child of "Epic: Modularize papyrus/pi-papyrus god-files into building-block modules").
- */
+/** Cross-domain artifact name/id resolution and workflow-run narrative building. */
 import { type VehicleContentBlock, VehicleError } from "@danypops/vehicle-core";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";

package/src/handlers/batch.ts

@@ -0,0 +1,134 @@
+/**
+ * batch.execute -- a generic fan-out over N independent operations in one Vehicle call, so a
+ * caller doing N artifact mutations (e.g. renaming 45 tasks/docs) doesn't need N separate tool
+ * round-trips. Reuses each item's existing single-operation validation/execute path unchanged:
+ * a thin fan-out over registry.invoke() -- this same VehicleRegistry, self-referenced, so every
+ * item goes through the exact same schema/permission/effect enforcement a direct call would --
+ * not a parallel reimplementation of any domain's own update logic.
+ *
+ * Partial failure, not all-or-nothing: every item is attempted regardless of an earlier item's
+ * own failure, and the response reports one {ok, result} or {ok, error} entry per item, in the
+ * SAME order as the request -- an artifact-not-found on item 12 of 45 never rolls back or skips
+ * items 1-11 or 13-45.
+ *
+ * Deliberately scoped to fan out N INDEPENDENT calls, nothing more. A caller whose own items are
+ * NOT independent (e.g. item 2 needs item 1's just-created id) needs a genuinely different
+ * feature (transactional/dependent-batch chaining) -- out of scope here.
+ */
+import { bindVehicleOperation, defineVehicleOperation, isVehicleError, type VehicleInvocationOptions } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { BATCH_MAX_ITEMS } from "../constants.ts";
+import { looseObjectSchema, passthroughOutput, stringProp, validationError } from "./shared.ts";
+
+const OWNER = "batch";
+const LIMITS = { defaultTimeoutMs: 30_000, maxTimeoutMs: 60_000, maxRequestBytes: 262_144, maxResponseBytes: 1_048_576 };
+
+export interface BatchItem {
+	readonly op: string;
+	readonly version?: number;
+	readonly input: Record<string, unknown>;
+}
+
+export type BatchItemResult = { readonly ok: true; readonly result: unknown } | { readonly ok: false; readonly error: string };
+
+/** Shared validation for both this file's own Vehicle-native registration and service.ts's
+ * moduleRegistry/composition-root-facing "batch.execute" entry -- one bounds/shape check, not
+ * two independently-drifting copies. */
+export function parseBatchItems(input: Record<string, unknown>): BatchItem[] {
+	const raw = input.items;
+	if (!Array.isArray(raw) || raw.length === 0) throw validationError("items must be a non-empty array");
+	if (raw.length > BATCH_MAX_ITEMS) throw validationError(`items cannot contain more than ${BATCH_MAX_ITEMS} entries`);
+	return raw.map((entry, index) => {
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+			throw validationError(`items[${index}] must be an object`);
+		}
+		const record = entry as Record<string, unknown>;
+		if (typeof record.op !== "string" || record.op.length === 0) throw validationError(`items[${index}].op is required`);
+		if (record.version !== undefined && typeof record.version !== "number") {
+			throw validationError(`items[${index}].version must be a number`);
+		}
+		if (record.input !== undefined && (typeof record.input !== "object" || record.input === null || Array.isArray(record.input))) {
+			throw validationError(`items[${index}].input must be an object`);
+		}
+		return {
+			op: record.op,
+			version: record.version as number | undefined,
+			input: (record.input as Record<string, unknown> | undefined) ?? {},
+		};
+	});
+}
+
+/** Turns any per-item failure (a real VehicleError, or an unexpected throw) into the same plain
+ * message string every {ok:false, error} entry reports -- a caller reading the aggregate result
+ * needs one consistent shape regardless of which layer the failure came from. */
+export function batchItemErrorMessage(error: unknown): string {
+	if (isVehicleError(error)) return error.message;
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Registers batch.execute as a real VehicleOperation -- the path an actual Pi tool call
+ * reaches. Each item is dispatched via registry.invoke() (this same registry, self-referenced),
+ * propagating the OUTER batch call's own granted permissions/principal/correlation identity to
+ * every item unchanged -- a caller with a narrower permission set than some item requires gets
+ * that item reported as a normal {ok:false} permission-denied failure, never a silent escalation
+ * granted by batch.execute's own (deliberately empty) permission requirement.
+ */
+export function registerBatchVehicleOperation(registry: VehicleRegistry): void {
+	const operation = defineVehicleOperation({
+		name: "batch.execute",
+		version: 1,
+		description:
+			'Fans out N independent operations (each an existing {op, input} pair, e.g. {"op":"tasks.update","input":{"id":"...","title":"..."}}) in one call, so N artifact mutations don\'t need N separate tool round-trips. Every item is attempted regardless of another item\'s own failure; the response is {results: [{ok, result} | {ok, error}, ...]}, one entry per item, in request order. Not transactional and not for dependent items (e.g. one item needing another\'s just-created id) -- only for independent operations that would otherwise be called one at a time.',
+		input: looseObjectSchema(
+			{
+				items: {
+					type: "array",
+					minItems: 1,
+					maxItems: BATCH_MAX_ITEMS,
+					description: "Each entry names an existing operation and its own input, exactly as a direct call would receive it.",
+					items: {
+						type: "object",
+						properties: {
+							op: stringProp,
+							version: { type: "number" },
+							input: { type: "object" },
+						},
+						required: ["op"],
+						additionalProperties: false,
+					},
+				},
+			},
+			["items"],
+		),
+		output: passthroughOutput,
+		// Deliberately empty: batch.execute itself gates nothing -- every fanned-out item is
+		// re-checked against the caller's own real granted permissions via registry.invoke() below.
+		permissions: [],
+		effect: "local-write",
+		idempotency: { mode: "unsafe" },
+		limits: LIMITS,
+	});
+	registry.register(
+		OWNER,
+		bindVehicleOperation(operation, () => async (context) => {
+			const items = parseBatchItems(context.input as Record<string, unknown>);
+			const propagated: VehicleInvocationOptions = {
+				permissions: context.permissions,
+				principal: context.principal,
+				correlationId: context.correlationId,
+				signal: context.signal,
+			};
+			const results: BatchItemResult[] = [];
+			for (const item of items) {
+				try {
+					const result = await registry.invoke(item.op, item.version ?? 1, item.input, propagated);
+					results.push({ ok: true, result });
+				} catch (error) {
+					results.push({ ok: false, error: batchItemErrorMessage(error) });
+				}
+			}
+			return { results };
+		}),
+	);
+}

package/src/handlers/operation-schema.ts

@@ -1,10 +1,7 @@
 /**
- * Generic, domain-agnostic operation-input schema DSL, split out of handlers/shared.ts as part of
- * a SOLID-audit-driven decomposition (see Doc "Modularity playbook: building-block-shaped
- * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
- * Modularize papyrus/pi-papyrus god-files into building-block modules"). Nothing here references
- * a specific Papyrus domain (tasks/docs/rules/...) -- a real candidate to eventually become its
- * own building block other Vehicle-backed daemons could reuse directly.
+ * Generic, domain-agnostic operation-input schema DSL. Nothing here references a specific
+ * Papyrus domain (tasks/docs/rules/...) -- a real candidate to eventually become its own building
+ * block other Vehicle-backed daemons could reuse directly.
  */
 import {
 	defineVehicleSchema,

package/src/handlers/paired-mutation.ts

@@ -1,10 +1,4 @@
-/**
- * Vehicle-operation-definer DSL (createOperationDefiner) and the paired add/remove mutation shape
- * built on top of it (definePairedMutation), split out of handlers/shared.ts as part of a
- * SOLID-audit-driven decomposition (see Doc "Modularity playbook: building-block-shaped
- * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
- * Modularize papyrus/pi-papyrus god-files into building-block modules").
- */
+/** Vehicle-operation-definer DSL (createOperationDefiner) and the paired add/remove mutation shape built on top of it (definePairedMutation). */
 import { bindVehicleOperation, defineVehicleOperation, type VehicleLimits, type VehicleOperationContext } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import { looseObjectSchema, passthroughOutput } from "./operation-schema.ts";

package/src/handlers/registry.ts

@@ -20,6 +20,7 @@ import type { TaskEventStore } from "../task/event/task-event-store.ts";
 import type { TaskScopeStore } from "../task/scope/task-scope-store.ts";
 import type { Tasks } from "../task/task-service.ts";
 import { registerArtifactTrashOperations } from "./artifact-trash.ts";
+import { registerBatchVehicleOperation } from "./batch.ts";
 import { registerDiscussVehicleOperations } from "./discuss.ts";
 import { registerDocsVehicleOperations } from "./docs.ts";
 import { registerNotesVehicleOperations } from "./notes.ts";
@@ -72,5 +73,6 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 	registerScopeGroupsVehicleOperations(registry, deps.scopeGroups, deps.projectRegistry, deps.scopes);
 	registerDiscussVehicleOperations(registry, deps.discussions, deps.artifacts);
 	registerArtifactTrashOperations(registry, deps.artifacts);
+	registerBatchVehicleOperation(registry);
 	return registry;
 }

package/src/handlers/shared.ts

@@ -1,20 +1,11 @@
 /**
  * Barrel re-exporting the shared schema helpers and name->id resolution used by every per-domain
- * VehicleRegistry projection (notes-vehicle.ts, rules-vehicle.ts, docs-vehicle.ts,
- * artifact-trash-vehicle.ts, ...). Kept as a real file (not a `shared/index.ts` subdirectory) so
- * every existing `from "./shared.ts"` import across the 8 handler files that depend on it keeps
- * resolving unchanged -- this codebase's imports always carry an explicit `.ts` extension, which
- * does not implicitly resolve a bare specifier to a directory's own index file the way Node's
- * CJS `require()` does.
- *
- * The real implementation now lives in four focused sibling modules instead of one 435-line file
- * mixing four unrelated concerns -- see Doc "Modularity playbook: building-block-shaped
- * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
- * Modularize papyrus/pi-papyrus god-files into building-block modules":
- *   - operation-schema.ts: generic, domain-agnostic operation-input schema DSL
- *   - paired-mutation.ts: the Vehicle-operation-definer DSL and the paired add/remove shape built on it
- *   - task-classifiers.ts: business-rule error classifiers specific to this package's own domain errors
- *   - artifact-helpers.ts: cross-domain artifact name/id resolution and workflow-run narrative building
+ * VehicleRegistry projection. Kept as a real file (not a `shared/index.ts` subdirectory) so every
+ * existing `from "./shared.ts"` import keeps resolving unchanged -- this codebase's imports
+ * always carry an explicit `.ts` extension, which does not implicitly resolve a bare specifier to
+ * a directory's own index file the way Node's CJS `require()` does. Real implementation lives in
+ * operation-schema.ts (schema DSL), paired-mutation.ts (operation-definer DSL), task-classifiers.ts
+ * (domain error classifiers), artifact-helpers.ts (name/id resolution, workflow-run narrative).
  */
 export {
 	buildWorkflowRunContent,

package/src/service.ts

@@ -19,6 +19,7 @@ import { SQLiteDiscussionRoundStore } from "./discussion/sqlite-discussion-round
 import type { GateRunner } from "./gate/gate-runner.ts";
 import { SQLiteGateRunner } from "./gate/sqlite-gate-runner.ts";
 import { SQLiteGraphProjectionStore } from "./graph-projection/sqlite-graph-projection-store.ts";
+import { batchItemErrorMessage, parseBatchItems } from "./handlers/batch.ts";
 import { createPapyrusVehicleRegistry } from "./handlers/registry.ts";
 import { logEvent } from "./log/log.ts";
 import { Logs } from "./log/log-service.ts";
@@ -68,6 +69,7 @@ import { VERSION } from "./version.ts";
  */
 const COMPOSITION_ROOT_OPERATION_NAMES = [
 	"system.migrate",
+	"batch.execute",
 	"artifact.create",
 	"artifact.query",
 	"artifact.show",
@@ -260,8 +262,31 @@ function handlers(
 		rootTaskId: optionalString(input, "root_task_id"),
 		sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
 	});
-	return {
+	const table: Record<OperationName, OperationHandler> = {
 		"system.migrate": () => migrate(),
+		// A thin fan-out over this SAME table (self-referenced via closure -- `table` is fully
+		// assigned by the time this handler is ever actually called, well after this object
+		// literal finishes constructing), covering both module-forwarded and composition-root
+		// operations alike. Deliberately bypasses execute()'s own migration-required check per
+		// item -- that check already ran once for the outer "batch.execute" call itself, and
+		// migration state cannot change mid-request. This path has no permission model of its
+		// own (matching every other operation reached through this same table via /api/v1/ops or
+		// in-process execute()) -- see handlers/batch.ts's registerBatchVehicleOperation for the
+		// permission-propagating counterpart real Pi tool calls actually reach.
+		"batch.execute": async (input) => {
+			const items = parseBatchItems(input);
+			const results: Array<{ ok: true; result: unknown } | { ok: false; error: string }> = [];
+			for (const item of items) {
+				try {
+					const itemHandler = table[item.op as OperationName];
+					if (!itemHandler) throw new UnknownOperationError(`unknown operation "${item.op}"`);
+					results.push({ ok: true, result: await itemHandler(item.input) });
+				} catch (error) {
+					results.push({ ok: false, error: batchItemErrorMessage(error) });
+				}
+			}
+			return { results };
+		},
 		"artifact.create": (input) => {
 			const normalized = normalizeCreateInput(input);
 			authority.requireArtifactAllowed(
@@ -495,6 +520,7 @@ function handlers(
 		"discuss.rounds": forwardToModule("discuss.rounds"),
 		"discuss.list": forwardToModule("discuss.list"),
 	};
+	return table;
 }
 
 export function createPapyrusService(path: string): PapyrusService {