@danypops/papyrus 0.54.4 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.54.4",
+  "version": "0.55.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/playbooks-command.ts

@@ -319,14 +319,26 @@ const replaceProjectsCommand = buildCommand({
 });
 
 const updateCommand = buildCommand({
-	func: async function (this: PlaybooksContext, flags: { title?: string; body?: string; labelsJson?: string[] }, id: string) {
-		if (flags.title === undefined && flags.body === undefined && flags.labelsJson === undefined)
-			throw new Error("playbooks update requires --title, --body, or --labels-json");
+	func: async function (
+		this: PlaybooksContext,
+		flags: { title?: string; body?: string; labelsJson?: string[]; trigger?: string; stepsJson?: unknown[] | Record<string, unknown> },
+		id: string,
+	) {
+		if (
+			flags.title === undefined &&
+			flags.body === undefined &&
+			flags.labelsJson === undefined &&
+			flags.trigger === undefined &&
+			flags.stepsJson === undefined
+		)
+			throw new Error("playbooks update requires --title, --body, --labels-json, --trigger, or --steps-json");
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("playbooks.update", {
 			id,
 			title: flags.title,
 			body: flags.body,
 			labels: flags.labelsJson,
+			trigger: flags.trigger,
+			steps: flags.stepsJson,
 		});
 		render.call(this, artifact, artifactLabel(artifact));
 	},
@@ -335,10 +347,18 @@ const updateCommand = buildCommand({
 			title: { brief: "New title", kind: "parsed", parse: String, placeholder: "text", optional: true },
 			body: { brief: "New body", kind: "parsed", parse: String, placeholder: "text", optional: true },
 			labelsJson: { brief: "JSON string array of labels", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+			trigger: { brief: "New trigger -- replaces the existing one", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			stepsJson: {
+				brief: "JSON array of steps -- REPLACES the entire existing step list, same shape as create's --steps-json",
+				kind: "parsed",
+				parse: parseAny,
+				placeholder: "json",
+				optional: true,
+			},
 		},
 		positional: { kind: "tuple", parameters: [{ brief: "Playbook id", parse: String, placeholder: "id" }] },
 	},
-	docs: { brief: "Change a Playbook's title/body/labels" },
+	docs: { brief: "Change a Playbook's title/body/labels/trigger/steps" },
 });
 
 function buildPairedIdCommand(

package/src/client.ts

@@ -126,18 +126,31 @@ export interface ConnectPapyrusClientOptions {
 	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?: ExpectedVersion;
+	/**
+	 * Overrides the default fail-closed behavior (see connectPapyrusClient's own doc comment for
+	 * why that default changed). Test-only -- covers the auto-spawn mechanism itself
+	 * (connect-client-auto-spawn.test.ts) and lets other real-daemon integration tests keep using
+	 * it as convenient bootstrap. A real, non-Armada-supervised standalone deployment could also
+	 * set this explicitly, but that is not this option's primary purpose.
+	 */
+	autoStart?: boolean;
 }
 
 /**
- * Transparently starts the daemon first if it is not already running -- matches
- * every other daemon-backed ecosystem package that opted into auto-start (see
- * @danypops/vehicle-client's connectWithPolicy doc comment: web-spider opts in,
- * lector/pi-packed fail closed by design). Papyrus previously failed closed with
- * "install/start papyrus.service", requiring a human to separately discover and
- * run `papyrus service install` before the very first tool call could succeed.
- * A handle file that exists but points at a dead/unreachable daemon is a distinct
- * failure (stale, not "never started") and is NOT auto-recovered here -- it still
- * throws its own actionable "restart manually" error, unchanged from before.
+ * Fails closed if nothing is reachable at all -- matches lector/pi-packed (see
+ * @danypops/vehicle-client's connectWithPolicy doc comment). Papyrus used to auto-start here
+ * (autoStart: true) because it predated being a properly Armada-supervised Vehicle; that flag
+ * is now a genuine liability, not a convenience: a real, live race was traced to it directly --
+ * Armada's own systemd unit and THIS client's auto-spawn each independently tried to be "the one
+ * that starts Papyrus" whenever no daemon was momentarily reachable (e.g. mid-restart), and
+ * whichever one's child won the OS-level single-instance-lock race became an orphan invisible to
+ * systemd's own tracking, permanently confusing `armada status`. Now that Armada's systemd unit
+ * (Restart=on-failure) is the one and only thing responsible for keeping Papyrus running, a
+ * client that finds nothing reachable should say so plainly, not compete to fix it.
+ *
+ * Stale-VERSION self-healing (an already-running daemon reporting an older version than this
+ * client expects) is unrelated to autoStart and still works: connectWithVersionCheck's own kill-
+ * and-replace path only requires `spawn` to be defined, independent of the autoStart flag above.
  */
 export async function connectPapyrusClient(
 	dir: string = daemonStateDir(),
@@ -147,7 +160,7 @@ export async function connectPapyrusClient(
 		{
 			readHandle: () => readDaemonHandle(dir) ?? null,
 			buildClient: probedPapyrusClient,
-			autoStart: true,
+			autoStart: options.autoStart ?? false,
 			spawn: () => {
 				spawnDetachedDaemon({
 					binPath: papyrusCliPath(),
@@ -156,7 +169,8 @@ export async function connectPapyrusClient(
 					spawn: spawnPapyrusDaemonProcess,
 				});
 			},
-			fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",
+			fallbackMessage:
+				"Papyrus daemon is not running; Armada should be supervising it -- run `armada status`/`armada reconcile`, or `papyrus serve` directly if this is a standalone (non-Armada) setup.",
 		},
 		{
 			expectedVersion: options.expectedVersion ?? papyrusExpectedVersion,

package/src/handlers/playbooks.ts

@@ -265,7 +265,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 
 	define(
 		"update",
-		"Changes a Playbook's title/body/labels (at least one required). Refused for a read-only external projection.",
+		"Changes a Playbook's title/body/labels/trigger/steps (at least one required). `steps` accepts the exact same shape playbooks.create does and REPLACES the entire step list -- the way to fix a mistake or generalize a Playbook's steps after creation instead of the create-new+supersedes+disable workaround. Refused for a read-only external projection.",
 		"local-write",
 		{
 			id: stringProp,
@@ -273,6 +273,8 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 			title: stringProp,
 			body: stringProp,
 			labels: { type: "array" },
+			trigger: stringProp,
+			steps: { type: "array" },
 			actor: stringProp,
 			source: stringProp,
 			session_id: stringProp,

package/src/modules/playbooks.ts

@@ -202,6 +202,8 @@ export function playbooksOperations({
 					title: optionalString(input, "title"),
 					body: optionalString(input, "body"),
 					labels: input.labels as string[] | undefined,
+					trigger: optionalString(input, "trigger"),
+					steps: input.steps,
 				},
 				eventContext(input),
 			),

package/src/playbook/playbook-service.ts

@@ -53,7 +53,6 @@ import {
 	assignArtifactProject,
 	type ListFilter,
 	listScoped,
-	requireContentUpdateFields,
 	requireKind,
 	runTransition,
 	type TransitionTable,
@@ -228,7 +227,20 @@ export interface CreatePlaybookInput {
 }
 
 export type PlaybookTransition = "enable" | "disable";
-export type UpdatePlaybookInput = UpdateContentInput;
+/**
+ * Extends the shared {title,body,labels} content-update shape with the two fields that make a
+ * Playbook a Playbook -- steps and trigger -- previously settable only at creation. Before this,
+ * revising either after creation had no supported path: the only workaround was create-new +
+ * supersedes-link + disable-original, purely to fix a typo in one step or generalize a
+ * project-specific Playbook for reuse. `steps` accepts the exact same shape playbooks.create
+ * does (validated the same way, via validatePlaybookSteps) and REPLACES the Playbook's entire
+ * step list when given, matching replace_projects' own "replace the whole thing" semantics
+ * rather than a per-step edit -- Playbooks are typically short and hand-authored, so a full
+ * replace is simpler to reason about than a step-index-addressed patch. */
+export interface UpdatePlaybookInput extends UpdateContentInput {
+	trigger?: string;
+	steps?: unknown;
+}
 
 const PLAYBOOK_TRANSITIONS: TransitionTable<PlaybookTransition, string> = {
 	enable: { from: ["deprecated"], to: "active" },
@@ -357,14 +369,37 @@ export function showPlaybook(artifacts: ArtifactStore, id: string): Artifact {
 }
 
 export function updatePlaybook(artifacts: ArtifactStore, id: string, input: UpdatePlaybookInput, context?: ArtifactEventContext): Artifact {
-	requireContentUpdateFields(input);
+	if (
+		input.title === undefined &&
+		input.body === undefined &&
+		input.labels === undefined &&
+		input.trigger === undefined &&
+		input.steps === undefined
+	) {
+		throw new Error("update requires title, body, labels, trigger, or steps");
+	}
 	assertTitleBounds(input.title);
 	assertBodyBounds(input.body);
 	assertLabelsBounds(input.labels);
+	// Validated the same way create does, BEFORE any write -- an invalid steps array must never
+	// partially apply a title/body/labels change alongside a rejected steps change.
+	const declaredSteps = validatePlaybookSteps(input.steps);
 	const playbook = requireLocallyOwnedContent(requireKind(artifacts, id, "playbook"));
-	const updated = artifacts.updateContent(playbook.id, input, context);
+	const hasContentFields = input.title !== undefined || input.body !== undefined || input.labels !== undefined;
+	const updated = hasContentFields ? artifacts.updateContent(playbook.id, input, context) : playbook;
 	if (!updated) throw new Error(`playbook "${id}" not found`);
-	return updated;
+	if (declaredSteps === undefined && input.trigger === undefined) return updated;
+	const withExtra = artifacts.setExtra(
+		updated.id,
+		{
+			...updated.extra,
+			...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
+			...(declaredSteps !== undefined ? { steps: declaredSteps } : {}),
+		},
+		context,
+	);
+	if (!withExtra) throw new Error(`playbook "${id}" not found`);
+	return withExtra;
 }
 
 export function transitionPlaybook(