@danypops/papyrus 0.45.1 → 0.45.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.45.1",
+  "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/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),
+				),
 			),
 		),
 	];