@danypops/papyrus 0.44.9 → 0.44.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.44.9",
+  "version": "0.44.11",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -36,6 +36,7 @@
   "dependencies": {
     "@danypops/vehicle-client": "^0.6.1",
     "@danypops/vehicle-core": "^0.12.3",
-    "@danypops/vehicle-server": "^0.18.1"
+    "@danypops/vehicle-server": "^0.18.1",
+    "@stricli/core": "^1.3.0"
   }
 }

package/src/artifact/artifact.ts

@@ -20,6 +20,29 @@ export interface Artifact {
 	edges?: ArtifactEdge[];
 }
 
+/**
+ * A list operation's default projection: everything needed to identify, browse, and pick
+ * one artifact out of many, without its body/extra -- the same fields show()'s own full
+ * Artifact carries minus the two that make listing dozens of rows as expensive as showing
+ * each one individually (a Playbook's full runbook body, a Rule's condition/action text).
+ */
+export interface ArtifactSummary {
+	id: string;
+	kind: string;
+	title: string;
+	status: string;
+	subtype: string;
+	labels: string[];
+	created_at: string;
+	updated_at: string;
+	alias: string;
+}
+
+export function summarizeArtifact(artifact: Artifact): ArtifactSummary {
+	const { id, kind, title, status, subtype, labels, created_at, updated_at, alias } = artifact;
+	return { id, kind, title, status, subtype, labels, created_at, updated_at, alias };
+}
+
 export interface CreateArtifactInput {
 	kind?: string;
 	title?: string;

package/src/cli/artifact-command.ts

@@ -0,0 +1,210 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap, numberParser } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import { artifactLabel, type CliArtifact } from "./shared.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type ArtifactClient = Pick<PapyrusClient, "call">;
+
+interface ArtifactContext extends CommandContext {
+	readonly client: ArtifactClient;
+	readonly json: boolean;
+	readonly projectRoot: string;
+}
+
+function parseStringArray(value: string): string[] {
+	const parsed = JSON.parse(value) as unknown;
+	if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== "string")) throw new Error("value must be a JSON string array");
+	return parsed as string[];
+}
+
+function parseObject(value: string): Record<string, unknown> {
+	const parsed = JSON.parse(value) as unknown;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("value must be a JSON object");
+	return parsed as Record<string, unknown>;
+}
+
+function render(this: ArtifactContext, result: unknown, human: string): void {
+	this.process.stdout.write(this.json ? JSON.stringify(result) : human);
+}
+
+const createCommand = buildCommand({
+	func: async function (
+		this: ArtifactContext,
+		flags: {
+			kind?: string;
+			title?: string;
+			body?: string;
+			status?: string;
+			subtype?: string;
+			labelsJson?: string[];
+			extraJson?: Record<string, unknown>;
+			templateId?: string;
+		},
+	) {
+		if (!flags.kind && !flags.templateId) throw new Error("artifact create requires --kind (or --template-id)");
+		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("artifact.create", {
+			kind: flags.kind,
+			title: flags.title,
+			body: flags.body,
+			status: flags.status,
+			subtype: flags.subtype,
+			labels: flags.labelsJson,
+			extra: flags.extraJson,
+			template_id: flags.templateId,
+			...(flags.kind === "task" ? { project_root: this.projectRoot } : {}),
+		});
+		render.call(this, artifact, `Created: ${artifactLabel(artifact)}`);
+	},
+	parameters: {
+		flags: {
+			kind: { brief: "Artifact kind", kind: "parsed", parse: String, placeholder: "kind", optional: true },
+			title: { brief: "Title", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			body: { brief: "Body", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			status: { brief: "Initial status", kind: "parsed", parse: String, placeholder: "status", optional: true },
+			subtype: { brief: "Subtype", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			labelsJson: { brief: "JSON string array of labels", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+			extraJson: { brief: "JSON object of extra fields", kind: "parsed", parse: parseObject, placeholder: "json", optional: true },
+			templateId: { brief: "Template to instantiate from", kind: "parsed", parse: String, placeholder: "id", optional: true },
+		},
+	},
+	docs: { brief: "Create an artifact of any kind" },
+});
+
+const queryCommand = buildCommand({
+	func: async function (this: ArtifactContext, flags: { kind?: string; status?: string; text?: string; limit?: number }) {
+		const rows = await this.client.call<Record<string, unknown>, CliArtifact[]>("artifact.query", {
+			kind: flags.kind,
+			status: flags.status,
+			text: flags.text,
+			limit: flags.limit,
+		});
+		render.call(this, rows, rows.length === 0 ? "No artifacts found." : rows.map((row) => artifactLabel(row)).join("\n"));
+	},
+	parameters: {
+		flags: {
+			kind: { brief: "Filter by kind", kind: "parsed", parse: String, placeholder: "kind", optional: true },
+			status: { brief: "Filter by status", kind: "parsed", parse: String, placeholder: "status", optional: true },
+			text: { brief: "Substring match against title/body", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Maximum artifacts to return", kind: "parsed", parse: numberParser, optional: true },
+		},
+	},
+	docs: { brief: "Query artifacts across every kind" },
+});
+
+const showCommand = buildCommand({
+	func: async function (this: ArtifactContext, flags: { depth?: number; maxNodes?: number }, id: string) {
+		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("artifact.show", {
+			id,
+			depth: flags.depth,
+			max_nodes: flags.maxNodes,
+		});
+		render.call(this, artifact, `${artifactLabel(artifact)}\n\n${artifact.body ?? ""}`);
+	},
+	parameters: {
+		flags: {
+			depth: { brief: "Edge traversal depth", kind: "parsed", parse: numberParser, optional: true },
+			maxNodes: { brief: "Maximum traversed nodes", kind: "parsed", parse: numberParser, optional: true },
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Artifact id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Show one artifact by id, regardless of kind" },
+});
+
+const removeCommand = buildCommand({
+	func: async function (this: ArtifactContext, flags: { reason?: string }, id: string) {
+		const record = await this.client.call<
+			Record<string, unknown>,
+			{ artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }
+		>("artifact.remove", { id, reason: flags.reason });
+		render.call(this, record, `Trashed ${record.artifactId}: eligible for purge at ${record.purgeAfter}`);
+	},
+	parameters: {
+		flags: { reason: { brief: "Why this artifact was removed", kind: "parsed", parse: String, placeholder: "text", optional: true } },
+		positional: { kind: "tuple", parameters: [{ brief: "Artifact id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Move an artifact to a time-gated trash" },
+});
+
+const removeSubtreeCommand = buildCommand({
+	func: async function (this: ArtifactContext, flags: { reason?: string }, id: string) {
+		const outcome = await this.client.call<Record<string, unknown>, { removed: string[]; skipped: string[] }>("artifact.remove_subtree", {
+			id,
+			reason: flags.reason,
+		});
+		render.call(
+			this,
+			outcome,
+			`Trashed ${outcome.removed.length} artifact(s)${outcome.skipped.length > 0 ? `, skipped ${outcome.skipped.length} already-trashed` : ""}.`,
+		);
+	},
+	parameters: {
+		flags: { reason: { brief: "Why this subtree was removed", kind: "parsed", parse: String, placeholder: "text", optional: true } },
+		positional: { kind: "tuple", parameters: [{ brief: "Artifact id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Trash an artifact and its whole contains subtree" },
+});
+
+const restoreCommand = buildCommand({
+	func: async function (this: ArtifactContext, _flags: Record<string, never>, id: string) {
+		const outcome = await this.client.call<Record<string, unknown>, { restored: boolean }>("artifact.restore", { id });
+		render.call(this, outcome, outcome.restored ? `Restored ${id}` : `${id} was not trashed`);
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Artifact id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Restore a trashed artifact" },
+});
+
+const trashStatusCommand = buildCommand({
+	func: async function (this: ArtifactContext, _flags: Record<string, never>, id: string) {
+		const record = await this.client.call<
+			Record<string, unknown>,
+			{ artifactId: string; trashedAt: string; purgeAfter: string; reason?: string } | null
+		>("artifact.trash_status", { id });
+		render.call(
+			this,
+			record,
+			record ? `${record.artifactId}: trashed at ${record.trashedAt}, purge eligible at ${record.purgeAfter}` : `${id} is not trashed`,
+		);
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Artifact id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Show one artifact's trash status" },
+});
+
+const trashListCommand = buildCommand({
+	func: async function (this: ArtifactContext) {
+		const rows = await this.client.call<
+			Record<string, unknown>,
+			Array<{ artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }>
+		>("artifact.trash_list", {});
+		render.call(
+			this,
+			rows,
+			rows.length === 0 ? "Trash is empty." : rows.map((row) => `${row.artifactId}: purge eligible at ${row.purgeAfter}`).join("\n"),
+		);
+	},
+	parameters: { flags: {} },
+	docs: { brief: "List every trashed artifact" },
+});
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: {
+			create: createCommand,
+			query: queryCommand,
+			show: showCommand,
+			remove: removeCommand,
+			"remove-subtree": removeSubtreeCommand,
+			restore: restoreCommand,
+			"trash-status": trashStatusCommand,
+			"trash-list": trashListCommand,
+		},
+		docs: { brief: "Artifact operations" },
+	}),
+	{ name: "artifact", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runArtifactCli(args: string[], client: ArtifactClient, projectRoot: string = process.cwd()): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json, projectRoot });
+}

package/src/cli/discuss-command.ts

@@ -0,0 +1,256 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap, numberParser } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import type { OperationName } from "../service.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type DiscussClient = Pick<PapyrusClient, "call">;
+
+interface DiscussContext extends CommandContext {
+	readonly client: DiscussClient;
+	readonly json: boolean;
+}
+
+function parseStringArray(value: string): string[] {
+	const parsed = JSON.parse(value) as unknown;
+	if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== "string")) throw new Error("value must be a JSON string array");
+	return parsed as string[];
+}
+
+function render(this: DiscussContext, result: unknown): void {
+	this.process.stdout.write(this.json ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+}
+
+async function call(this: DiscussContext, operation: OperationName, input: Record<string, unknown>): Promise<void> {
+	render.call(this, await this.client.call<Record<string, unknown>, unknown>(operation, input));
+}
+
+const openCommand = buildCommand({
+	func: async function (
+		this: DiscussContext,
+		flags: {
+			title: string;
+			actor: string;
+			content: string;
+			body?: string;
+			labelsJson?: string[];
+			blocksJson?: string[];
+			optionsJson?: string[];
+			optionsMode?: string;
+			optionDescriptionsJson?: string[];
+		},
+	) {
+		await call.call(this, "discuss.open", {
+			title: flags.title,
+			actor: flags.actor,
+			content: flags.content,
+			body: flags.body,
+			labels: flags.labelsJson,
+			blocks_task_ids: flags.blocksJson,
+			options: flags.optionsJson,
+			options_mode: flags.optionsMode,
+			option_descriptions: flags.optionDescriptionsJson,
+		});
+	},
+	parameters: {
+		flags: {
+			title: { brief: "Discussion title", kind: "parsed", parse: String, placeholder: "text" },
+			actor: { brief: "Actor opening the discussion", kind: "parsed", parse: String, placeholder: "text" },
+			content: { brief: "First round's content", kind: "parsed", parse: String, placeholder: "text" },
+			body: { brief: "Longer body text", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			labelsJson: { brief: "JSON string array of labels", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+			blocksJson: {
+				brief: "JSON string array of task ids to block",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			optionsJson: {
+				brief: "JSON string array of posed options",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			optionsMode: { brief: "single or multi", kind: "parsed", parse: String, placeholder: "mode", optional: true },
+			optionDescriptionsJson: {
+				brief: "JSON string array of option descriptions",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+		},
+	},
+	docs: { brief: "Open a new discussion" },
+});
+
+const replyCommand = buildCommand({
+	func: async function (
+		this: DiscussContext,
+		flags: {
+			actor: string;
+			content: string;
+			selectedJson?: string[];
+			optionsJson?: string[];
+			optionsMode?: string;
+			optionDescriptionsJson?: string[];
+		},
+		id: string,
+	) {
+		await call.call(this, "discuss.reply", {
+			id,
+			actor: flags.actor,
+			content: flags.content,
+			selected: flags.selectedJson,
+			options: flags.optionsJson,
+			options_mode: flags.optionsMode,
+			option_descriptions: flags.optionDescriptionsJson,
+		});
+	},
+	parameters: {
+		flags: {
+			actor: { brief: "Actor replying", kind: "parsed", parse: String, placeholder: "text" },
+			content: { brief: "Reply content", kind: "parsed", parse: String, placeholder: "text" },
+			selectedJson: {
+				brief: "JSON string array answering a pending posed choice",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			optionsJson: {
+				brief: "JSON string array of posed options",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			optionsMode: { brief: "single or multi", kind: "parsed", parse: String, placeholder: "mode", optional: true },
+			optionDescriptionsJson: {
+				brief: "JSON string array of option descriptions",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Add a round to an existing discussion" },
+});
+
+const deferCommand = buildCommand({
+	func: async function (this: DiscussContext, flags: { reason?: string }, id: string) {
+		await call.call(this, "discuss.defer", { id, reason: flags.reason });
+	},
+	parameters: {
+		flags: {
+			reason: { brief: "Why this discussion is being deferred", kind: "parsed", parse: String, placeholder: "text", optional: true },
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Pause a discussion without settling it" },
+});
+
+const resumeCommand = buildCommand({
+	func: async function (this: DiscussContext, _flags: Record<string, never>, id: string) {
+		await call.call(this, "discuss.resume", { id });
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Resume a deferred discussion" },
+});
+
+const settleCommand = buildCommand({
+	func: async function (this: DiscussContext, flags: { settlement: string }, id: string) {
+		await call.call(this, "discuss.settle", { id, settlement: flags.settlement });
+	},
+	parameters: {
+		flags: { settlement: { brief: "Final settlement text", kind: "parsed", parse: String, placeholder: "text" } },
+		positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Settle a discussion" },
+});
+
+const blockCommand = buildCommand({
+	func: async function (this: DiscussContext, flags: { taskId: string }, id: string) {
+		await call.call(this, "discuss.block", { id, task_id: flags.taskId });
+	},
+	parameters: {
+		flags: { taskId: { brief: "Task id to block", kind: "parsed", parse: String, placeholder: "id" } },
+		positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Block a task's completion on this discussion" },
+});
+
+const unblockCommand = buildCommand({
+	func: async function (this: DiscussContext, flags: { taskId: string }, id: string) {
+		await call.call(this, "discuss.unblock", { id, task_id: flags.taskId });
+	},
+	parameters: {
+		flags: { taskId: { brief: "Task id to unblock", kind: "parsed", parse: String, placeholder: "id" } },
+		positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Remove a discussion's block on a task" },
+});
+
+const showCommand = buildCommand({
+	func: async function (this: DiscussContext, _flags: Record<string, never>, id: string) {
+		await call.call(this, "discuss.show", { id });
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Show a discussion's full transcript" },
+});
+
+const roundsCommand = buildCommand({
+	func: async function (this: DiscussContext, flags: { afterRound?: number; limit?: number }, id: string) {
+		await call.call(this, "discuss.rounds", { id, after_round: flags.afterRound, limit: flags.limit });
+	},
+	parameters: {
+		flags: {
+			afterRound: { brief: "Only rounds after this number", kind: "parsed", parse: numberParser, optional: true },
+			limit: { brief: "Maximum rounds to return", kind: "parsed", parse: numberParser, optional: true },
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "List a discussion's rounds" },
+});
+
+const listCommand = buildCommand({
+	func: async function (this: DiscussContext, flags: { state?: string; limit?: number }) {
+		await call.call(this, "discuss.list", { state: flags.state, limit: flags.limit });
+	},
+	parameters: {
+		flags: {
+			state: { brief: "Filter to active|deferred|settled", kind: "parsed", parse: String, placeholder: "state", optional: true },
+			limit: { brief: "Maximum discussions to return", kind: "parsed", parse: numberParser, optional: true },
+		},
+	},
+	docs: { brief: "List discussions" },
+});
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: {
+			open: openCommand,
+			reply: replyCommand,
+			defer: deferCommand,
+			resume: resumeCommand,
+			settle: settleCommand,
+			block: blockCommand,
+			unblock: unblockCommand,
+			show: showCommand,
+			rounds: roundsCommand,
+			list: listCommand,
+		},
+		docs: { brief: "Discussion operations" },
+	}),
+	{ name: "discuss", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runDiscussCli(args: string[], client: DiscussClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}