@danypops/papyrus 0.44.9 → 0.44.10

package/src/cli/gates-command.ts

@@ -0,0 +1,46 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import type { GateResult } from "../domain/gate.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type GatesClient = Pick<PapyrusClient, "call">;
+
+interface GatesContext extends CommandContext {
+	readonly client: GatesClient;
+	readonly json: boolean;
+}
+
+const runGateCommand = buildCommand({
+	func: async function (this: GatesContext, _flags: Record<string, never>, id: string) {
+		const results = await this.client.call<Record<string, unknown>, GateResult[]>("gates.run", { id });
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(results));
+			return;
+		}
+		this.process.stdout.write(
+			results.length === 0
+				? "No gates configured."
+				: results.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n"),
+		);
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [{ brief: "Artifact id to run gates against", parse: String, placeholder: "id" }],
+		},
+	},
+	docs: { brief: "Run every gate configured on an artifact" },
+});
+
+const app = buildApplication(buildRouteMap({ routes: { run: runGateCommand }, docs: { brief: "Gate operations" } }), {
+	name: "gates",
+	scanner: { caseStyle: "allow-kebab-for-camel" },
+});
+
+export async function runGatesCli(args: string[], client: GatesClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli/graph-command.ts

@@ -0,0 +1,171 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap, numberParser } from "@stricli/core";
+import type { ArtifactEventPage } from "../artifact/artifact-event.ts";
+import type { PapyrusClient } from "../client.ts";
+import { artifactLabel, type CliArtifact } from "./shared.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type GraphClient = Pick<PapyrusClient, "call">;
+
+interface GraphContext extends CommandContext {
+	readonly client: GraphClient;
+	readonly json: boolean;
+}
+
+const linkCommand = buildCommand({
+	func: async function (this: GraphContext, _flags: Record<string, never>, from: string, relation: string, to: string) {
+		const result = await this.client.call<Record<string, unknown>, { ok: boolean }>("graph.link", { from, relation, to });
+		this.process.stdout.write(this.json ? JSON.stringify(result) : `Linked ${from} --${relation}--> ${to}`);
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Source artifact id", parse: String, placeholder: "from" },
+				{ brief: "Relation name", parse: String, placeholder: "relation" },
+				{ brief: "Target artifact id", parse: String, placeholder: "to" },
+			],
+		},
+	},
+	docs: { brief: "Link two artifacts" },
+});
+
+const unlinkCommand = buildCommand({
+	func: async function (this: GraphContext, _flags: Record<string, never>, from: string, relation: string, to: string) {
+		const result = await this.client.call<Record<string, unknown>, { removed: boolean }>("graph.unlink", { from, relation, to });
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(result));
+			return;
+		}
+		this.process.stdout.write(
+			result.removed ? `Unlinked ${from} --${relation}--> ${to}` : `No such relationship: ${from} --${relation}--> ${to}`,
+		);
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Source artifact id", parse: String, placeholder: "from" },
+				{ brief: "Relation name", parse: String, placeholder: "relation" },
+				{ brief: "Target artifact id", parse: String, placeholder: "to" },
+			],
+		},
+	},
+	docs: { brief: "Remove a relationship between two artifacts" },
+});
+
+const treeCommand = buildCommand({
+	func: async function (this: GraphContext, flags: { depth?: number; maxNodes?: number }, id: string) {
+		const artifact = await this.client.call<
+			Record<string, unknown>,
+			CliArtifact & { edges?: Array<{ from: string; relation: string; to: string }> }
+		>("graph.tree", { id, depth: flags.depth, max_nodes: flags.maxNodes });
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(artifact));
+			return;
+		}
+		const edges = artifact.edges ?? [];
+		this.process.stdout.write(
+			edges.length === 0
+				? `${artifactLabel(artifact)} — no edges`
+				: `${artifactLabel(artifact)}\n${edges.map((edge) => `  ${edge.from} --${edge.relation}--> ${edge.to}`).join("\n")}`,
+		);
+	},
+	parameters: {
+		flags: {
+			depth: { brief: "Traversal depth", kind: "parsed", parse: numberParser, optional: true },
+			maxNodes: { brief: "Maximum nodes to traverse", kind: "parsed", parse: numberParser, optional: true },
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Artifact id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Show an artifact's relationship tree" },
+});
+
+const statusCommand = buildCommand({
+	func: async function (this: GraphContext, _flags: Record<string, never>, id: string, status: string) {
+		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("graph.status", { id, status });
+		this.process.stdout.write(this.json ? JSON.stringify(artifact) : `Updated ${artifact.id} → [${artifact.status}]`);
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Artifact id", parse: String, placeholder: "id" },
+				{ brief: "New status", parse: String, placeholder: "status" },
+			],
+		},
+	},
+	docs: { brief: "Transition an artifact's status" },
+});
+
+const historyCommand = buildCommand({
+	func: async function (
+		this: GraphContext,
+		flags: {
+			id?: string;
+			actor?: string;
+			sessionId?: string;
+			since?: string;
+			limit?: number;
+			cursor?: number;
+			direction?: string;
+		},
+	) {
+		const page = await this.client.call<Record<string, unknown>, ArtifactEventPage>("graph.history", {
+			id: flags.id,
+			actor: flags.actor,
+			session_id: flags.sessionId,
+			since: flags.since,
+			limit: flags.limit,
+			cursor: flags.cursor,
+			direction: flags.direction,
+		});
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(page));
+			return;
+		}
+		if (page.events.length === 0) {
+			this.process.stdout.write("No recorded events.");
+			return;
+		}
+		this.process.stdout.write(
+			page.events
+				.map((event) => {
+					const transition =
+						event.fromStatus || event.toStatus ? ` ${event.fromStatus ?? "\u2205"} \u2192 ${event.toStatus ?? "\u2205"}` : "";
+					const relation = event.relation ? ` ${event.relation} \u2192 ${event.relatedId}` : "";
+					return `${event.occurredAt} ${event.artifactId} ${event.type}${transition}${relation} \u00b7 ${event.actor}/${event.source}${event.sessionId ? ` \u00b7 ${event.sessionId}` : ""}`;
+				})
+				.join("\n"),
+		);
+	},
+	parameters: {
+		flags: {
+			id: { brief: "Filter to one artifact id", kind: "parsed", parse: String, optional: true },
+			actor: { brief: "Filter to one actor", kind: "parsed", parse: String, optional: true },
+			sessionId: { brief: "Filter to one session id", kind: "parsed", parse: String, optional: true },
+			since: { brief: "Filter to events at or after this RFC3339 timestamp", kind: "parsed", parse: String, optional: true },
+			limit: { brief: "Maximum events to return", kind: "parsed", parse: numberParser, optional: true },
+			cursor: { brief: "Pagination cursor", kind: "parsed", parse: numberParser, optional: true },
+			direction: { brief: "Sort direction (asc|desc)", kind: "parsed", parse: String, optional: true },
+		},
+	},
+	docs: { brief: "Query the mutation event history" },
+});
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: { link: linkCommand, unlink: unlinkCommand, tree: treeCommand, status: statusCommand, history: historyCommand },
+		docs: { brief: "Graph operations" },
+	}),
+	{ name: "graph", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runGraphCli(args: string[], client: GraphClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli/graph-projection-command.ts

@@ -0,0 +1,79 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type GraphProjectionClient = Pick<PapyrusClient, "call">;
+
+interface GraphProjectionContext extends CommandContext {
+	readonly client: GraphProjectionClient;
+	readonly json: boolean;
+}
+
+function parseBatchJson(value: string): Record<string, unknown> {
+	const parsed = JSON.parse(value) as unknown;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("--batch-json must be a JSON object");
+	return parsed as Record<string, unknown>;
+}
+
+const applyCommand = buildCommand({
+	func: async function (this: GraphProjectionContext, flags: { batchJson: Record<string, unknown> }) {
+		const result = await this.client.call<Record<string, unknown>, unknown>("graph_projection.apply", flags.batchJson);
+		this.process.stdout.write(this.json ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+	},
+	parameters: {
+		flags: {
+			batchJson: {
+				brief: "JSON-encoded projection batch to apply",
+				kind: "parsed",
+				parse: parseBatchJson,
+				placeholder: "json",
+			},
+		},
+	},
+	docs: {
+		brief: "Apply a projection batch",
+	},
+});
+
+const checkpointCommand = buildCommand({
+	func: async function (this: GraphProjectionContext, flags: { producerId: string }) {
+		const result = await this.client.call<Record<string, unknown>, unknown>("graph_projection.checkpoint", {
+			producer_id: flags.producerId,
+		});
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(result));
+			return;
+		}
+		this.process.stdout.write(
+			result === null ? `No projection checkpoint for producer "${flags.producerId}".` : JSON.stringify(result, null, 2),
+		);
+	},
+	parameters: {
+		flags: {
+			producerId: {
+				brief: "Producer id to look up the checkpoint for",
+				kind: "parsed",
+				parse: String,
+				placeholder: "id",
+			},
+		},
+	},
+	docs: {
+		brief: "Look up a producer's projection checkpoint",
+	},
+});
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: { apply: applyCommand, checkpoint: checkpointCommand },
+		docs: { brief: "Graph projection operations" },
+	}),
+	{ name: "graph-projection", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runGraphProjectionCli(args: string[], client: GraphProjectionClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli/log-command.ts

@@ -0,0 +1,101 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap, numberParser } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type LogClient = Pick<PapyrusClient, "call">;
+
+interface LogContext extends CommandContext {
+	readonly client: LogClient;
+	readonly json: boolean;
+	readonly projectRoot: string;
+}
+
+function parseFieldsJson(value: string): Record<string, unknown> {
+	const parsed = JSON.parse(value) as unknown;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("--fields-json must be a JSON object");
+	return parsed as Record<string, unknown>;
+}
+
+const appendCommand = buildCommand({
+	func: async function (
+		this: LogContext,
+		flags: {
+			source: string;
+			sourceLabel?: string;
+			level: string;
+			message: string;
+			operationId: string;
+			sessionId?: string;
+			occurredAt?: string;
+			fieldsJson?: Record<string, unknown>;
+			global: boolean;
+		},
+	) {
+		const result = await this.client.call("logs.append", {
+			source_id: flags.source,
+			...(flags.sourceLabel ? { source_label: flags.sourceLabel } : {}),
+			...(flags.global ? {} : { project_root: this.projectRoot }),
+			level: flags.level,
+			message: flags.message,
+			operation_id: flags.operationId,
+			...(flags.fieldsJson ? { fields: flags.fieldsJson } : {}),
+			...(flags.sessionId ? { session_id: flags.sessionId } : {}),
+			...(flags.occurredAt ? { occurred_at: flags.occurredAt } : {}),
+		});
+		this.process.stdout.write(this.json ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+	},
+	parameters: {
+		flags: {
+			source: { brief: "Log source id", kind: "parsed", parse: String, placeholder: "id" },
+			sourceLabel: { brief: "Human-readable source label", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			level: { brief: "Log level (debug|info|warning|error)", kind: "parsed", parse: String, placeholder: "level" },
+			message: { brief: "Log message text", kind: "parsed", parse: String, placeholder: "text" },
+			operationId: { brief: "Idempotency key for this append", kind: "parsed", parse: String, placeholder: "id" },
+			sessionId: { brief: "Session id to attribute this entry to", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			occurredAt: { brief: "ISO timestamp override", kind: "parsed", parse: String, placeholder: "iso", optional: true },
+			fieldsJson: { brief: "JSON-encoded structured fields", kind: "parsed", parse: parseFieldsJson, placeholder: "json", optional: true },
+			global: { brief: "Append outside any project scope", kind: "boolean" },
+		},
+	},
+	docs: { brief: "Append a log entry" },
+});
+
+const queryCommand = buildCommand({
+	func: async function (this: LogContext, flags: { source: string; since?: string; level?: string; limit?: number }) {
+		const result = await this.client.call<Record<string, unknown>, { entries: unknown[]; truncated: boolean }>("logs.query", {
+			source_id: flags.source,
+			...(flags.since ? { since: flags.since } : {}),
+			...(flags.level ? { level: flags.level } : {}),
+			...(flags.limit === undefined ? {} : { limit: flags.limit }),
+		});
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(result));
+			return;
+		}
+		const lines = result.entries.map((entry) => JSON.stringify(entry));
+		this.process.stdout.write(
+			[...lines, result.truncated ? "(truncated -- more entries exist beyond this page)" : `(${lines.length} entries)`].join("\n"),
+		);
+	},
+	parameters: {
+		flags: {
+			source: { brief: "Log source id", kind: "parsed", parse: String, placeholder: "id" },
+			since: { brief: "Only entries at or after this ISO timestamp", kind: "parsed", parse: String, placeholder: "iso", optional: true },
+			level: { brief: "Filter to one level", kind: "parsed", parse: String, placeholder: "level", optional: true },
+			limit: { brief: "Maximum entries to return", kind: "parsed", parse: numberParser, optional: true },
+		},
+	},
+	docs: { brief: "Query log entries" },
+});
+
+const app = buildApplication(buildRouteMap({ routes: { append: appendCommand, query: queryCommand }, docs: { brief: "Log operations" } }), {
+	name: "log",
+	scanner: { caseStyle: "allow-kebab-for-camel" },
+});
+
+export async function runLogCli(args: string[], client: LogClient, 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/migration-command.ts

@@ -0,0 +1,40 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type MigrationClient = Pick<PapyrusClient, "call">;
+type MigrationResult = { from: number; to: number; applied: string[] };
+
+interface MigrationContext extends CommandContext {
+	readonly client: MigrationClient;
+	readonly json: boolean;
+}
+
+const schemaCommand = buildCommand({
+	func: async function (this: MigrationContext) {
+		const result = await this.client.call<Record<string, never>, MigrationResult>("system.migrate", {});
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(result));
+			return;
+		}
+		this.process.stdout.write(
+			result.applied.length === 0
+				? `Schema already current at version ${result.to}.`
+				: `Migrated schema ${result.from} → ${result.to}: ${result.applied.join(", ")}`,
+		);
+	},
+	parameters: { flags: {} },
+	docs: { brief: "Run any pending schema migrations" },
+});
+
+const app = buildApplication(buildRouteMap({ routes: { schema: schemaCommand }, docs: { brief: "Migration operations" } }), {
+	name: "migrate",
+	scanner: { caseStyle: "allow-kebab-for-camel" },
+});
+
+export async function runMigrationCli(args: string[], client: MigrationClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli/note-command.ts

@@ -0,0 +1,186 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap, numberParser } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import type { NoteHistoryPage } from "../domain/note-event.ts";
+import { artifactLabel, type CliArtifact } from "./shared.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type NoteClient = Pick<PapyrusClient, "call">;
+
+interface NoteContext extends CommandContext {
+	readonly client: NoteClient;
+	readonly json: boolean;
+	readonly projectRoot: string;
+}
+
+function renderResult(this: NoteContext, result: unknown, human: string): void {
+	this.process.stdout.write(this.json ? JSON.stringify(result) : human);
+}
+
+const captureCommand = buildCommand({
+	func: async function (this: NoteContext, flags: { title?: string }, request: string) {
+		const result = (await this.client.call("notes.capture", {
+			body: request,
+			...(flags.title ? { title: flags.title } : {}),
+			project_root: this.projectRoot,
+			actor: "human",
+			source: "cli",
+		})) as CliArtifact;
+		renderResult.call(this, result, `Captured: ${artifactLabel(result)}`);
+	},
+	parameters: {
+		flags: { title: { brief: "Optional title", kind: "parsed", parse: String, placeholder: "text", optional: true } },
+		positional: { kind: "tuple", parameters: [{ brief: "Request text to capture", parse: String, placeholder: "request" }] },
+	},
+	docs: { brief: "Capture a deferred request as a note, without creating work" },
+});
+
+const listCommand = buildCommand({
+	func: async function (this: NoteContext, flags: { status?: string; text?: string; limit?: number }) {
+		const result = (await this.client.call("notes.list", {
+			project_root: this.projectRoot,
+			...(flags.status ? { status: flags.status } : {}),
+			...(flags.text ? { text: flags.text } : {}),
+			...(flags.limit === undefined ? {} : { limit: flags.limit }),
+		})) as CliArtifact[];
+		renderResult.call(
+			this,
+			result,
+			result.length > 0 ? result.map((note) => `[${note.status}] ${artifactLabel(note)}`).join("\n") : "No open notes.",
+		);
+	},
+	parameters: {
+		flags: {
+			status: { brief: "Filter by status (draft|active|archived)", 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 notes to return", kind: "parsed", parse: numberParser, optional: true },
+		},
+	},
+	docs: { brief: "List open (draft/active) notes, or a specific status" },
+});
+
+const showCommand = buildCommand({
+	func: async function (this: NoteContext, _flags: Record<string, never>, id: string) {
+		const result = (await this.client.call("notes.show", { id, project_root: this.projectRoot })) as CliArtifact;
+		renderResult.call(this, result, `${artifactLabel(result)}\n\n${result.body ?? ""}`.trimEnd());
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Note id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Show one note" },
+});
+
+const historyCommand = buildCommand({
+	func: async function (this: NoteContext, flags: { limit?: number }, id: string) {
+		const page = await this.client.call<Record<string, unknown>, NoteHistoryPage>("notes.history", {
+			id,
+			project_root: this.projectRoot,
+			direction: "desc",
+			...(flags.limit === undefined ? {} : { limit: flags.limit }),
+		});
+		const human =
+			page.events.length === 0
+				? `No recorded history for ${id}.`
+				: [...page.events]
+						.reverse()
+						.map(
+							(event) =>
+								`${event.occurredAt} ${event.type} · ${event.actor}/${event.source}${event.relatedId ? ` · ${event.relatedId}` : ""}${event.disposition ? ` · ${event.disposition}` : ""}${event.reason ? ` · ${event.reason}` : ""}`,
+						)
+						.join("\n");
+		renderResult.call(this, page, human);
+	},
+	parameters: {
+		flags: { limit: { brief: "Maximum events to return", kind: "parsed", parse: numberParser, optional: true } },
+		positional: { kind: "tuple", parameters: [{ brief: "Note id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "This note's own event history" },
+});
+
+const consumeCommand = buildCommand({
+	func: async function (this: NoteContext, flags: { reason?: string }, id: string) {
+		const result = (await this.client.call("notes.consume", {
+			id,
+			project_root: this.projectRoot,
+			actor: "agent",
+			source: "cli",
+			...(flags.reason ? { reason: flags.reason } : {}),
+		})) as CliArtifact;
+		renderResult.call(this, result, `Consumed: ${artifactLabel(result)}`);
+	},
+	parameters: {
+		flags: { reason: { brief: "Why this note was considered", kind: "parsed", parse: String, placeholder: "text", optional: true } },
+		positional: { kind: "tuple", parameters: [{ brief: "Note id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Mark a note as considered" },
+});
+
+const promoteCommand = buildCommand({
+	func: async function (this: NoteContext, flags: { reason?: string }, id: string, targetId: string) {
+		const result = (await this.client.call("notes.promote", {
+			id,
+			target_id: targetId,
+			project_root: this.projectRoot,
+			actor: "agent",
+			source: "cli",
+			...(flags.reason ? { reason: flags.reason } : {}),
+		})) as CliArtifact;
+		renderResult.call(this, result, `Promoted: ${artifactLabel(result)} → ${targetId}`);
+	},
+	parameters: {
+		flags: { reason: { brief: "Why this note was promoted", kind: "parsed", parse: String, placeholder: "text", optional: true } },
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Note id", parse: String, placeholder: "id" },
+				{ brief: "Target artifact id it was promoted into", parse: String, placeholder: "target-id" },
+			],
+		},
+	},
+	docs: { brief: "Link a note to the artifact it was promoted into, then archive it" },
+});
+
+const archiveCommand = buildCommand({
+	func: async function (this: NoteContext, flags: { reason?: string }, id: string, disposition: string) {
+		const result = (await this.client.call("notes.archive", {
+			id,
+			disposition,
+			project_root: this.projectRoot,
+			actor: "human",
+			source: "cli",
+			...(flags.reason ? { reason: flags.reason } : {}),
+		})) as CliArtifact;
+		renderResult.call(this, result, `Archived: ${artifactLabel(result)} · ${disposition}`);
+	},
+	parameters: {
+		flags: { reason: { brief: "Why this note was archived", kind: "parsed", parse: String, placeholder: "text", optional: true } },
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Note id", parse: String, placeholder: "id" },
+				{ brief: "completed|duplicate|declined|superseded", parse: String, placeholder: "disposition" },
+			],
+		},
+	},
+	docs: { brief: "Archive a note with an explicit disposition" },
+});
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: {
+			capture: captureCommand,
+			list: listCommand,
+			show: showCommand,
+			history: historyCommand,
+			consume: consumeCommand,
+			promote: promoteCommand,
+			archive: archiveCommand,
+		},
+		docs: { brief: "Note operations" },
+	}),
+	{ name: "notes", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runNoteCli(args: string[], client: NoteClient, 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 });
+}