@danypops/papyrus 0.55.0 → 0.57.0

package/src/cli/docs-command.ts

@@ -210,6 +210,73 @@ const replaceProjectsCommand = buildCommand({
 	docs: { brief: "Replace a Doc's entire project membership" },
 });
 
+const setNoneCommand = buildCommand({
+	func: async function (this: DocsContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.set_none", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Document id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Fully hide a Doc -- never applicable, never context-injected, regardless of project" },
+});
+
+const addGroupCommand = buildCommand({
+	func: async function (this: DocsContext, _flags: Record<string, never>, id: string, group: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.add_group", { id, group });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Document id", parse: String, placeholder: "id" },
+				{ brief: "Scope group id/name/alias to add", parse: String, placeholder: "group" },
+			],
+		},
+	},
+	docs: { brief: "Add one scope group to a Doc's explicit scope" },
+});
+
+const removeGroupCommand = buildCommand({
+	func: async function (this: DocsContext, _flags: Record<string, never>, id: string, group: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.remove_group", { id, group });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Document id", parse: String, placeholder: "id" },
+				{ brief: "Scope group id/name/alias to remove", parse: String, placeholder: "group" },
+			],
+		},
+	},
+	docs: { brief: "Remove one scope group from a Doc's explicit scope" },
+});
+
+const replaceGroupsCommand = buildCommand({
+	func: async function (this: DocsContext, flags: { groupsJson: string[] }, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.replace_groups", {
+			id,
+			groups: flags.groupsJson,
+		});
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {
+			groupsJson: {
+				brief: "JSON string array of scope group id/name/alias references",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Document id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Replace a Doc's entire scope-group membership" },
+});
+
 function buildStatusTransitionCommand(action: "activate" | "archive" | "reopen") {
 	return buildCommand({
 		func: async function (this: DocsContext, _flags: Record<string, never>, id: string) {
@@ -271,9 +338,13 @@ const app = buildApplication(
 			"assign-project": assignProjectCommand,
 			scope: scopeCommand,
 			"set-global": setGlobalCommand,
+			"set-none": setNoneCommand,
 			"add-project": addProjectCommand,
 			"remove-project": removeProjectCommand,
 			"replace-projects": replaceProjectsCommand,
+			"add-group": addGroupCommand,
+			"remove-group": removeGroupCommand,
+			"replace-groups": replaceGroupsCommand,
 			show: showCommand,
 			activate: buildStatusTransitionCommand("activate"),
 			archive: buildStatusTransitionCommand("archive"),

package/src/cli/gates-command.ts

@@ -1,7 +1,7 @@
 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 type { GateResult } from "../gate/gate.ts";
 import { runStricliToString } from "./stricli-run.ts";
 
 type GatesClient = Pick<PapyrusClient, "call">;

package/src/cli/note-command.ts

@@ -1,7 +1,7 @@
 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 type { NoteHistoryPage } from "../note/note-event.ts";
 import { artifactLabel, type CliArtifact } from "./shared.ts";
 import { runStricliToString } from "./stricli-run.ts";
 

package/src/cli/playbooks-command.ts

@@ -318,6 +318,73 @@ const replaceProjectsCommand = buildCommand({
 	docs: { brief: "Replace a Playbook's entire project membership" },
 });
 
+const setNoneCommand = buildCommand({
+	func: async function (this: PlaybooksContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.set_none", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Playbook id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Fully hide a Playbook -- never applicable, never injected, regardless of project" },
+});
+
+const addGroupCommand = buildCommand({
+	func: async function (this: PlaybooksContext, _flags: Record<string, never>, id: string, group: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.add_group", { id, group });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Playbook id", parse: String, placeholder: "id" },
+				{ brief: "Scope group id/name/alias to add", parse: String, placeholder: "group" },
+			],
+		},
+	},
+	docs: { brief: "Add one scope group to a Playbook's explicit scope" },
+});
+
+const removeGroupCommand = buildCommand({
+	func: async function (this: PlaybooksContext, _flags: Record<string, never>, id: string, group: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.remove_group", { id, group });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Playbook id", parse: String, placeholder: "id" },
+				{ brief: "Scope group id/name/alias to remove", parse: String, placeholder: "group" },
+			],
+		},
+	},
+	docs: { brief: "Remove one scope group from a Playbook's explicit scope" },
+});
+
+const replaceGroupsCommand = buildCommand({
+	func: async function (this: PlaybooksContext, flags: { groupsJson: string[] }, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.replace_groups", {
+			id,
+			groups: flags.groupsJson,
+		});
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {
+			groupsJson: {
+				brief: "JSON string array of scope group id/name/alias references",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Playbook id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Replace a Playbook's entire scope-group membership" },
+});
+
 const updateCommand = buildCommand({
 	func: async function (
 		this: PlaybooksContext,
@@ -402,9 +469,13 @@ const app = buildApplication(
 			"assign-project": assignProjectCommand,
 			scope: scopeCommand,
 			"set-global": setGlobalCommand,
+			"set-none": setNoneCommand,
 			"add-project": addProjectCommand,
 			"remove-project": removeProjectCommand,
 			"replace-projects": replaceProjectsCommand,
+			"add-group": addGroupCommand,
+			"remove-group": removeGroupCommand,
+			"replace-groups": replaceGroupsCommand,
 			update: updateCommand,
 			contain: buildPairedIdCommand(
 				"playbooks.contain",

package/src/cli/rules-command.ts

@@ -200,6 +200,73 @@ const replaceProjectsCommand = buildCommand({
 	docs: { brief: "Replace a Rule's entire project membership" },
 });
 
+const setNoneCommand = buildCommand({
+	func: async function (this: RulesContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.set_none", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Rule id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Fully hide a Rule -- never applicable, never injected, regardless of project" },
+});
+
+const addGroupCommand = buildCommand({
+	func: async function (this: RulesContext, _flags: Record<string, never>, id: string, group: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.add_group", { id, group });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Rule id", parse: String, placeholder: "id" },
+				{ brief: "Scope group id/name/alias to add", parse: String, placeholder: "group" },
+			],
+		},
+	},
+	docs: { brief: "Add one scope group to a Rule's explicit scope" },
+});
+
+const removeGroupCommand = buildCommand({
+	func: async function (this: RulesContext, _flags: Record<string, never>, id: string, group: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.remove_group", { id, group });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Rule id", parse: String, placeholder: "id" },
+				{ brief: "Scope group id/name/alias to remove", parse: String, placeholder: "group" },
+			],
+		},
+	},
+	docs: { brief: "Remove one scope group from a Rule's explicit scope" },
+});
+
+const replaceGroupsCommand = buildCommand({
+	func: async function (this: RulesContext, flags: { groupsJson: string[] }, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.replace_groups", {
+			id,
+			groups: flags.groupsJson,
+		});
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {
+			groupsJson: {
+				brief: "JSON string array of scope group id/name/alias references",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Rule id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Replace a Rule's entire scope-group membership" },
+});
+
 const showCommand = buildCommand({
 	func: async function (this: RulesContext, _flags: Record<string, never>, id: string) {
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("rules.show", { id });
@@ -293,9 +360,13 @@ const app = buildApplication(
 			"assign-project": assignProjectCommand,
 			scope: scopeCommand,
 			"set-global": setGlobalCommand,
+			"set-none": setNoneCommand,
 			"add-project": addProjectCommand,
 			"remove-project": removeProjectCommand,
 			"replace-projects": replaceProjectsCommand,
+			"add-group": addGroupCommand,
+			"remove-group": removeGroupCommand,
+			"replace-groups": replaceGroupsCommand,
 			show: showCommand,
 			preview: previewCommand,
 			enable: buildEnableDisableCommand("enable"),

package/src/cli/scope-groups-command.ts

@@ -0,0 +1,197 @@
+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 ScopeGroupsClient = Pick<PapyrusClient, "call">;
+
+interface ScopeGroupsContext extends CommandContext {
+	readonly client: ScopeGroupsClient;
+	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[];
+}
+
+interface CliScopeGroup {
+	id: string;
+	name: string;
+	aliases: string[];
+}
+
+interface CliScopeMember {
+	type: "project" | "group";
+	id: string;
+}
+
+function render(this: ScopeGroupsContext, result: unknown, human: string): void {
+	this.process.stdout.write(this.json ? JSON.stringify(result) : human);
+}
+
+const listCommand = buildCommand({
+	func: async function (this: ScopeGroupsContext, flags: { query?: string; limit?: number }) {
+		const groups = await this.client.call<Record<string, unknown>, CliScopeGroup[]>("scope_groups.list", {
+			query: flags.query,
+			limit: flags.limit,
+		});
+		render.call(this, groups, groups.length === 0 ? "No registered scope groups." : groups.map((group) => group.name).join("\n"));
+	},
+	parameters: {
+		flags: {
+			query: { brief: "Filter by scope group name or alias", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Maximum results", kind: "parsed", parse: numberParser, placeholder: "n", optional: true },
+		},
+	},
+	docs: { brief: "List registered scope groups" },
+});
+
+const resolveCommand = buildCommand({
+	func: async function (this: ScopeGroupsContext, _flags: Record<string, never>, reference: string) {
+		const group = await this.client.call<Record<string, unknown>, CliScopeGroup>("scope_groups.resolve", { reference });
+		render.call(this, group, group.name);
+	},
+	parameters: {
+		flags: {},
+		positional: { kind: "tuple", parameters: [{ brief: "Scope group id, name, or alias", parse: String, placeholder: "reference" }] },
+	},
+	docs: { brief: "Resolve a scope group reference to its canonical identity" },
+});
+
+const registerCommand = buildCommand({
+	func: async function (this: ScopeGroupsContext, flags: { aliasesJson?: string[]; existingId?: string }, name: string) {
+		const registered = await this.client.call<Record<string, unknown>, CliScopeGroup>("scope_groups.register", {
+			name,
+			aliases: flags.aliasesJson,
+			existing_id: flags.existingId,
+		});
+		render.call(this, registered, registered.name);
+	},
+	parameters: {
+		flags: {
+			aliasesJson: { brief: "JSON string array of aliases", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+			existingId: {
+				brief: "Existing scope group id when renaming",
+				kind: "parsed",
+				parse: String,
+				placeholder: "id",
+				optional: true,
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Scope group name", parse: String, placeholder: "name" }] },
+	},
+	docs: { brief: "Register a new scope group, or rename an existing one" },
+});
+
+const showCommand = buildCommand({
+	func: async function (this: ScopeGroupsContext, _flags: Record<string, never>, group: string) {
+		const result = await this.client.call<Record<string, unknown>, { group: CliScopeGroup; members: CliScopeMember[] }>(
+			"scope_groups.show",
+			{ group },
+		);
+		render.call(
+			this,
+			result,
+			`${result.group.name}: ${result.members.length === 0 ? "(no members)" : result.members.map((m) => `${m.type}:${m.id}`).join(", ")}`,
+		);
+	},
+	parameters: {
+		flags: {},
+		positional: { kind: "tuple", parameters: [{ brief: "Scope group id, name, or alias", parse: String, placeholder: "group" }] },
+	},
+	docs: { brief: "Show a scope group's identity and its own direct membership" },
+});
+
+const addMemberCommand = buildCommand({
+	func: async function (
+		this: ScopeGroupsContext,
+		_flags: Record<string, never>,
+		group: string,
+		memberType: string,
+		memberReference: string,
+	) {
+		const result = await this.client.call<Record<string, unknown>, { group: CliScopeGroup; members: CliScopeMember[] }>(
+			"scope_groups.add_member",
+			{ group, member_type: memberType, member_reference: memberReference },
+		);
+		render.call(this, result, `${result.group.name}: ${result.members.length} member(s)`);
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Scope group id, name, or alias", parse: String, placeholder: "group" },
+				{ brief: '"project" or "group"', parse: String, placeholder: "member-type" },
+				{ brief: "Exact project or scope group id/name/alias/root reference", parse: String, placeholder: "member-reference" },
+			],
+		},
+	},
+	docs: { brief: "Add one member (a project, or another scope group) to a scope group" },
+});
+
+const removeMemberCommand = buildCommand({
+	func: async function (
+		this: ScopeGroupsContext,
+		_flags: Record<string, never>,
+		group: string,
+		memberType: string,
+		memberReference: string,
+	) {
+		const result = await this.client.call<Record<string, unknown>, { group: CliScopeGroup; members: CliScopeMember[] }>(
+			"scope_groups.remove_member",
+			{ group, member_type: memberType, member_reference: memberReference },
+		);
+		render.call(this, result, `${result.group.name}: ${result.members.length} member(s)`);
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Scope group id, name, or alias", parse: String, placeholder: "group" },
+				{ brief: '"project" or "group"', parse: String, placeholder: "member-type" },
+				{ brief: "Exact project or scope group id/name/alias/root reference", parse: String, placeholder: "member-reference" },
+			],
+		},
+	},
+	docs: { brief: "Remove one member from a scope group" },
+});
+
+const deleteCommand = buildCommand({
+	func: async function (this: ScopeGroupsContext, _flags: Record<string, never>, group: string) {
+		const result = await this.client.call<Record<string, unknown>, { deleted: boolean; id: string }>("scope_groups.delete", { group });
+		render.call(this, result, `Deleted scope group ${result.id}`);
+	},
+	parameters: {
+		flags: {},
+		positional: { kind: "tuple", parameters: [{ brief: "Scope group id, name, or alias", parse: String, placeholder: "group" }] },
+	},
+	docs: { brief: "Delete a scope group outright (refuses if still referenced)" },
+});
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: {
+			list: listCommand,
+			resolve: resolveCommand,
+			register: registerCommand,
+			show: showCommand,
+			"add-member": addMemberCommand,
+			"remove-member": removeMemberCommand,
+			delete: deleteCommand,
+		},
+		docs: {
+			brief: "Scope group operations -- named, reusable, possibly-nested collections of projects/groups for Doc/Rule/Playbook scoping",
+		},
+	}),
+	{ name: "scope-groups", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runScopeGroupsCli(args: string[], client: ScopeGroupsClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli/task-command.ts

@@ -2,7 +2,7 @@ import type { CommandContext } from "@stricli/core";
 import { buildApplication, buildCommand, buildRouteMap, numberParser } from "@stricli/core";
 import type { PapyrusClient } from "../client.ts";
 import { TASK_EXECUTION_MAX_NODES } from "../constants.ts";
-import type { GateResult } from "../domain/gate.ts";
+import type { GateResult } from "../gate/gate.ts";
 import type { OperationName } from "../service.ts";
 import type { TaskExecutionPlan } from "../task/task-execution.ts";
 import type { TaskBlockage, TaskCompletion } from "../task/task-service.ts";

package/src/cli.ts

@@ -16,6 +16,7 @@ import { runNoteCli } from "./cli/note-command.ts";
 import { runPlaybooksCli } from "./cli/playbooks-command.ts";
 import { runProjectsCli } from "./cli/projects-command.ts";
 import { runRulesCli } from "./cli/rules-command.ts";
+import { runScopeGroupsCli } from "./cli/scope-groups-command.ts";
 import { runSessionIdentityCli } from "./cli/session-identity-command.ts";
 import { runTaskCli } from "./cli/task-command.ts";
 import { connectPapyrusClient } from "./client.ts";
@@ -362,6 +363,7 @@ export {
 	runPlaybooksCli,
 	runProjectsCli,
 	runRulesCli,
+	runScopeGroupsCli,
 	runSessionIdentityCli,
 	runTaskCli,
 };
@@ -387,6 +389,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runProjectsCli(args.slice(1), client));
 		return;
 	}
+	if (command === "scope-groups") {
+		const client = await connectPapyrusClient();
+		console.log(await runScopeGroupsCli(args.slice(1), client));
+		return;
+	}
 	if (command === "notes") {
 		const client = await connectPapyrusClient();
 		console.log(await runNoteCli(args.slice(1), client));

package/src/constants.ts

@@ -17,7 +17,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 28;
+export const SQLITE_SCHEMA_VERSION = 29;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -278,12 +278,20 @@ export const ARTIFACT_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 export const TASK_SCOPE_MAX_TASKS = 1_000;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */
 export const ARTIFACT_SCOPE_MAX_ARTIFACTS = 1_000;
-/** How many distinct registered projects a single Doc/Rule/Playbook may belong to at once, in "projects" scope mode. */
+/** How many distinct registered projects a single Doc/Rule/Playbook may belong to at once, in "projects" scope mode. Kept alongside ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT (identical value) for the pure-project call sites/tests that predate mixed project+group membership. */
 export const ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT = 50;
+/** How many total members (projects and/or scope groups combined) a single Doc/Rule/Playbook may have at once, in "explicit" scope mode. */
+export const ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT = 50;
 export const TASK_PROJECT_ROOT_MAX_LENGTH = 4_096;
 export const TASK_PROJECT_NAME_MAX_LENGTH = 200;
 export const TASK_PROJECT_ALIAS_MAX_COUNT = 20;
 export const TASK_PROJECT_LIST_MAX_RESULTS = 100;
+export const SCOPE_GROUP_NAME_MAX_LENGTH = 200;
+export const SCOPE_GROUP_ALIAS_MAX_COUNT = 20;
+export const SCOPE_GROUP_MAX_MEMBERS = 50;
+/** Bounds recursive group-in-group expansion at both add-time (refuses a nesting that would exceed it) and resolution time. */
+export const SCOPE_GROUP_MAX_NESTING_DEPTH = 5;
+export const SCOPE_GROUP_LIST_MAX_RESULTS = 100;
 export const TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH = 200;
 export const TASK_CREATE_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 export const TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH = 200;