@danypops/papyrus 0.45.0 → 0.45.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.45.0",
+  "version": "0.45.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/cli/rules-command.ts

@@ -124,8 +124,12 @@ const showCommand = buildCommand({
 
 const previewCommand = buildCommand({
 	func: async function (this: RulesContext, _flags: Record<string, never>, id: string) {
-		const preview = await this.client.call<Record<string, unknown>, string>("rules.preview", { id });
-		render.call(this, preview, preview);
+		const result = await this.client.call<Record<string, unknown>, { preview: string; combinedLength: number; warning?: string }>(
+			"rules.preview",
+			{ id },
+		);
+		const text = result.warning === undefined ? result.preview : `${result.preview}\n\n⚠ ${result.warning}`;
+		render.call(this, result, text);
 	},
 	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Rule id", parse: String, placeholder: "id" }] } },
 	docs: { brief: "Render a Rule's own condition/action/body preview text" },

package/src/client.ts

@@ -1,6 +1,11 @@
 import { spawn as spawnProcess } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { connectWithVersionCheck, type ExpectedVersion, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
+import {
+	connectWithVersionCheck,
+	type ExpectedVersion,
+	type SpawnPlatformOptions,
+	spawnDetachedDaemon,
+} from "@danypops/vehicle-client/daemon-client";
 import { createLiveVersionExpectation } 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/daemon-state.ts";
@@ -74,6 +79,25 @@ function papyrusCliPath(): string {
 	return fileURLToPath(new URL("cli.ts", import.meta.url));
 }
 
+/**
+ * spawnDetachedDaemon's injected spawn() callback, factored out for a direct unit test.
+ *
+ * A spawn() failure (missing binPath, no exec permission, wrong interpreter) surfaces
+ * asynchronously as an "error" event on the ChildProcess -- with no listener, Node treats it
+ * as an uncaught exception and kills the whole host process, not just this one connect
+ * attempt (a real incident: auto-spawning against a since-deleted binPath crashed Pi itself).
+ * The listener below turns that into an ordinary logged failure instead: the handle file
+ * simply never appears, and connectWithPolicy's own poll-then-timeout already reports that
+ * as its usual, catchable fallbackMessage error.
+ */
+export function spawnPapyrusDaemonProcess(command: string, args: string[], spawnOptions: SpawnPlatformOptions): void {
+	const child = spawnProcess(command, args, spawnOptions);
+	child.on("error", (error) => {
+		console.error(`Papyrus daemon auto-spawn failed: ${error instanceof Error ? error.message : String(error)}`);
+	});
+	child.unref();
+}
+
 /** 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.
@@ -123,10 +147,7 @@ export async function connectPapyrusClient(
 					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();
-					},
+					spawn: spawnPapyrusDaemonProcess,
 				});
 			},
 			fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",

package/src/domain-services.ts

@@ -16,6 +16,7 @@ import {
 	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
 	PLAYBOOK_MAX_STEPS,
 	RULE_TEXT_HARD_LIMIT_CHARACTERS,
+	RULE_TEXT_SOFT_TARGET_CHARACTERS,
 	SKILL_MAX_ENUM_VALUES,
 } from "./constants.ts";
 import {
@@ -312,8 +313,26 @@ export type RuleTransition = "enable" | "disable";
  * reviewed, and a warning nobody reads is not a bound. See RULE_TEXT_HARD_LIMIT_CHARACTERS's
  * own comment in constants.ts for the research this threshold is grounded in.
  */
+export function ruleCombinedLength(condition: string | undefined, action: string | undefined, body: string | undefined): number {
+	return (condition ?? "").length + (action ?? "").length + (body ?? "").length;
+}
+
+/**
+ * Non-blocking counterpart to assertRuleTextWithinBounds's hard rejection: the same combined
+ * length, informational once it crosses the soft target, so a caller doesn't have to self-police
+ * with a manual character count before every rules.create/update. Returns undefined at or under
+ * the target -- the common case, not worth a field only ever seen as "undefined" on the wire.
+ */
+export function ruleCombinedLengthWarning(combinedLength: number): string | undefined {
+	if (combinedLength <= RULE_TEXT_SOFT_TARGET_CHARACTERS) return undefined;
+	return (
+		`condition+action+body is ${combinedLength} characters, over the ${RULE_TEXT_SOFT_TARGET_CHARACTERS}-character soft target ` +
+		`(hard limit ${RULE_TEXT_HARD_LIMIT_CHARACTERS}) -- consider moving detail into a linked Doc.`
+	);
+}
+
 function assertRuleTextWithinBounds(condition: string | undefined, action: string | undefined, body: string | undefined): void {
-	const combined = (condition ?? "").length + (action ?? "").length + (body ?? "").length;
+	const combined = ruleCombinedLength(condition, action, body);
 	if (combined > RULE_TEXT_HARD_LIMIT_CHARACTERS) {
 		throw new Error(
 			`rule condition+action+body is ${combined} characters, exceeding the ${RULE_TEXT_HARD_LIMIT_CHARACTERS}-character bound. ` +

package/src/handlers/rules.ts

@@ -49,7 +49,7 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 
 	define(
 		"create",
-		"Creates a Rule -- a standing constraint injected into the agent system prompt while active. project_root is optional (omitted = unscoped).",
+		"Creates a Rule -- a standing constraint injected into the agent system prompt while active. project_root is optional (omitted = unscoped). The response includes combinedLength (condition+action+body character count) and a non-blocking warning once it exceeds the ~600-character soft target (hard-rejected past 4000).",
 		"local-write",
 		{
 			title: stringProp,
@@ -77,14 +77,21 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 		(input) => input,
 	);
 
-	define("show", "Shows one Rule by id or title.", "read", { id: stringProp, name: stringProp, project_root: stringProp }, [], (input) => ({
-		...input,
-		id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name),
-	}));
+	define(
+		"show",
+		"Shows one Rule by id or title. The response includes combinedLength (condition+action+body character count) and a non-blocking warning once it exceeds the ~600-character soft target.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({
+			...input,
+			id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name),
+		}),
+	);
 
 	define(
 		"preview",
-		"Renders a Rule's own condition/action/body preview text with no side effects.",
+		"Renders a Rule's own condition/action/body preview text with no side effects. Response: { preview, combinedLength, warning? } -- warning is present only once combinedLength exceeds the ~600-character soft target.",
 		"read",
 		{ id: stringProp, name: stringProp, project_root: stringProp },
 		[],
@@ -146,7 +153,7 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 
 	define(
 		"update",
-		"Changes a Rule's title/body/labels (at least one required). Body updates still enforce the same combined condition+action+body context-tax bound as creation.",
+		"Changes a Rule's title/body/labels (at least one required). Body updates still enforce the same combined condition+action+body context-tax bound as creation. The response includes combinedLength and a non-blocking warning once it exceeds the ~600-character soft target.",
 		"local-write",
 		{
 			id: stringProp,

package/src/modules/rules.ts

@@ -11,7 +11,7 @@
  * registry" convention.
  */
 
-import { summarizeArtifact } from "../artifact/artifact.ts";
+import { type Artifact, summarizeArtifact } from "../artifact/artifact.ts";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import {
@@ -20,6 +20,8 @@ import {
 	gateTaskWithRule,
 	listRules,
 	previewRule,
+	ruleCombinedLength,
+	ruleCombinedLengthWarning,
 	showRule,
 	transitionRule,
 	updateRule,
@@ -42,6 +44,22 @@ const artifactFilter = (input: OperationInput) => ({
 	projectRoot: optionalString(input, "project_root"),
 });
 
+/**
+ * Adds a rule's own combinedLength (and, past the soft target, a non-blocking warning) to any
+ * response shaped as its own Artifact -- additive fields alongside every existing one, so a
+ * caller reading .id/.title/... unchanged still works. Removes the need for a manual
+ * len(condition)+len(action)+len(body) count before every rules.create/update call.
+ */
+function withRuleLengthInfo(rule: Artifact): Artifact & { combinedLength: number; warning?: string } {
+	const combinedLength = ruleCombinedLength(
+		typeof rule.extra.condition === "string" ? rule.extra.condition : undefined,
+		typeof rule.extra.action === "string" ? rule.extra.action : undefined,
+		rule.body,
+	);
+	const warning = ruleCombinedLengthWarning(combinedLength);
+	return { ...rule, combinedLength, ...(warning === undefined ? {} : { warning }) };
+}
+
 /** Registers every rules.* operation except rules.injectable (see module comment). Behavior is unchanged from the prior inline handlers in src/service.ts. */
 /** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. rules.injectable is deliberately absent -- see the module comment above. */
 export const RULES_OPERATION_NAMES = [
@@ -64,28 +82,39 @@ export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeS
 	});
 	return [
 		define("rules.create", (input: OperationInput) =>
-			createRule(
-				artifacts,
-				scopes,
-				{
-					title: string(input, "title"),
-					body: optionalString(input, "body"),
-					condition: optionalString(input, "condition"),
-					action: optionalString(input, "rule_action") ?? optionalString(input, "governance_action"),
-					severity: optionalString(input, "severity") as "block" | "warn" | "info" | undefined,
-					labels: input.labels as string[] | undefined,
-					extra: input.extra as Record<string, unknown> | undefined,
-					projectRoot: optionalString(input, "project_root"),
-				},
-				eventContext(input),
+			withRuleLengthInfo(
+				createRule(
+					artifacts,
+					scopes,
+					{
+						title: string(input, "title"),
+						body: optionalString(input, "body"),
+						condition: optionalString(input, "condition"),
+						action: optionalString(input, "rule_action") ?? optionalString(input, "governance_action"),
+						severity: optionalString(input, "severity") as "block" | "warn" | "info" | undefined,
+						labels: input.labels as string[] | undefined,
+						extra: input.extra as Record<string, unknown> | undefined,
+						projectRoot: optionalString(input, "project_root"),
+					},
+					eventContext(input),
+				),
 			),
 		),
 		define("rules.list", (input: OperationInput) => {
 			const rules = listRules(artifacts, scopes, artifactFilter(input));
 			return optionalBoolean(input, "full") === true ? rules : rules.map(summarizeArtifact);
 		}),
-		define("rules.show", (input: OperationInput) => showRule(artifacts, string(input, "id"))),
-		define("rules.preview", (input: OperationInput) => previewRule(artifacts, string(input, "id"))),
+		define("rules.show", (input: OperationInput) => withRuleLengthInfo(showRule(artifacts, string(input, "id")))),
+		define("rules.preview", (input: OperationInput) => {
+			const rule = showRule(artifacts, string(input, "id"));
+			const combinedLength = ruleCombinedLength(
+				typeof rule.extra.condition === "string" ? rule.extra.condition : undefined,
+				typeof rule.extra.action === "string" ? rule.extra.action : undefined,
+				rule.body,
+			);
+			const warning = ruleCombinedLengthWarning(combinedLength);
+			return { preview: previewRule(artifacts, string(input, "id")), combinedLength, ...(warning === undefined ? {} : { warning }) };
+		}),
 		define("rules.enable", (input: OperationInput) => transitionRule(artifacts, string(input, "id"), "enable", eventContext(input))),
 		define("rules.disable", (input: OperationInput) => transitionRule(artifacts, string(input, "id"), "disable", eventContext(input))),
 		define("rules.gate", (input: OperationInput) =>
@@ -95,15 +124,17 @@ export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeS
 			assignRuleProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root")),
 		),
 		define("rules.update", (input: OperationInput) =>
-			updateRule(
-				artifacts,
-				string(input, "id"),
-				{
-					title: optionalString(input, "title"),
-					body: optionalString(input, "body"),
-					labels: input.labels as string[] | undefined,
-				},
-				eventContext(input),
+			withRuleLengthInfo(
+				updateRule(
+					artifacts,
+					string(input, "id"),
+					{
+						title: optionalString(input, "title"),
+						body: optionalString(input, "body"),
+						labels: input.labels as string[] | undefined,
+					},
+					eventContext(input),
+				),
 			),
 		),
 	];