@danypops/papyrus 0.51.0 → 0.52.0

package/README.md

@@ -9,6 +9,7 @@ The daemon, CLI, and domain services behind Papyrus's graph artifact store: evid
 - [Schema protocol](#schema-protocol)
 - [Hierarchy and traversal](#hierarchy-and-traversal)
 - [Playbooks](#playbooks)
+- [Project scope](#project-scope)
 - [Naming vs. ids](#naming-vs-ids)
 - [Mutability](#mutability)
 - [Idempotent lifecycle mutations](#idempotent-lifecycle-mutations)
@@ -75,6 +76,23 @@ papyrus playbooks invoke <playbook-id> \
   --json
 ```
 
+## Project scope
+
+A Doc, Rule, or Playbook is either global (applies everywhere) or bound to a bounded, non-empty set of registered projects — never both, and never inferred from an accidentally empty membership. `scope` inspects an artifact's own mode and membership; `add_project`/`remove_project` mutate one membership at a time (`add_project` is idempotent for an already-present project; `remove_project` for an absent one); `replace_projects` swaps the whole set atomically; `set_global` is the only way back to global — removing an artifact's last remaining membership through `remove_project` is rejected instead of silently widening it. `assign_project` remains a documented compatibility delegate for the pre-multi-project single-root shape (replace, not add).
+
+Listing follows the same distinction: an omitted project filter keeps the existing bounded all-artifacts search; `project_root` alone means exact membership (audit semantics — only artifacts actually bound to that project); `project_root` plus `applicable: true` means every artifact *applicable* to that project instead — global artifacts plus artifacts whose membership includes it. `pi-papyrus`'s own context injection uses `applicable` for both Rules (`rules.injectable`) and Playbooks, so a project-bound artifact never leaks into an unrelated project's prompt. Project scope governs applicability and discovery, never authorization: exact-id access works regardless of scope, the same as it always has.
+
+A Playbook's own definition scope is a separate concern from where `playbooks.invoke` sends its generated artifacts. An unscoped or global Playbook can still be invoked with a destination `project_root`; the generated Tasks, Docs, and Rules inherit that destination, while the Playbook definition itself is untouched. A run-created Rule's injection requires both its own run to be active *and* its generated project membership to match — either alone is not enough.
+
+The shared project catalog behind all of this (`projects.list`/`projects.resolve`/`projects.register`) is the exact one Tasks has always used, and `tasks.projects`/`tasks.resolve_project`/`tasks.register_project` remain fully working, documented compatibility delegates over it.
+
+```bash
+papyrus docs scope <doc-id> --json
+papyrus rules add-project <rule-id> Lector --json
+papyrus playbooks list --project-root <root> --applicable --json
+papyrus projects register /path/to/project --name Lector --json
+```
+
 ## Naming vs. ids
 
 Every agent-facing domain (tasks, docs, rules, playbooks, notes, discuss) addresses artifacts by `name` (the exact title) anywhere `id` would otherwise be required — `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` (tasks), `target_name` (docs link, searched across every kind), `task_name` (rules gate, discuss block/unblock), and `blocks_task_names` (discuss open). Resolution is an exact, case-insensitive, trimmed title match scoped like a plain list call; an ambiguous name's error lists the real ids, the one place disambiguation needs them. A returned result leads with name and status; id surfaces only when two artifacts in the same result share a title. `id` itself keeps working, in every tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/cli/projects-command.ts

@@ -0,0 +1,105 @@
+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 ProjectsClient = Pick<PapyrusClient, "call">;
+
+interface ProjectsContext extends CommandContext {
+	readonly client: ProjectsClient;
+	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 CliProject {
+	id: string;
+	name: string;
+	aliases: string[];
+	projectRoot: string;
+}
+
+function render(this: ProjectsContext, result: unknown, human: string): void {
+	this.process.stdout.write(this.json ? JSON.stringify(result) : human);
+}
+
+const listCommand = buildCommand({
+	func: async function (this: ProjectsContext, flags: { query?: string; limit?: number }) {
+		const projects = await this.client.call<Record<string, unknown>, CliProject[]>("projects.list", {
+			query: flags.query,
+			limit: flags.limit,
+		});
+		render.call(
+			this,
+			projects,
+			projects.length === 0 ? "No registered projects." : projects.map((project) => `${project.name} — ${project.projectRoot}`).join("\n"),
+		);
+	},
+	parameters: {
+		flags: {
+			query: { brief: "Filter by project name, alias, or root", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Maximum results", kind: "parsed", parse: numberParser, placeholder: "n", optional: true },
+		},
+	},
+	docs: { brief: "List registered projects (shared by Tasks, Docs, Rules, and Playbooks)" },
+});
+
+const resolveCommand = buildCommand({
+	func: async function (this: ProjectsContext, _flags: Record<string, never>, reference: string) {
+		const project = await this.client.call<Record<string, unknown>, CliProject>("projects.resolve", { reference });
+		render.call(this, project, `${project.name} — ${project.projectRoot}`);
+	},
+	parameters: {
+		flags: {},
+		positional: { kind: "tuple", parameters: [{ brief: "Project id, name, alias, or root", parse: String, placeholder: "reference" }] },
+	},
+	docs: { brief: "Resolve a project reference to its canonical identity" },
+});
+
+const registerCommand = buildCommand({
+	func: async function (this: ProjectsContext, flags: { name?: string; aliasesJson?: string[]; existingId?: string }, projectRoot: string) {
+		const registered = await this.client.call<Record<string, unknown>, CliProject>("projects.register", {
+			project_root: projectRoot,
+			name: flags.name,
+			aliases: flags.aliasesJson,
+			existing_id: flags.existingId,
+		});
+		render.call(this, registered, `${registered.name} — ${registered.projectRoot}`);
+	},
+	parameters: {
+		flags: {
+			name: { brief: "Stable project display name", kind: "parsed", parse: String, placeholder: "name", optional: true },
+			aliasesJson: { brief: "JSON string array of aliases", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+			existingId: {
+				brief: "Existing project id when renaming or moving",
+				kind: "parsed",
+				parse: String,
+				placeholder: "id",
+				optional: true,
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Project root path", parse: String, placeholder: "project-root" }] },
+	},
+	docs: { brief: "Register a new project, or rename/move an existing one" },
+});
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: { list: listCommand, resolve: resolveCommand, register: registerCommand },
+		docs: {
+			brief:
+				"Shared project catalog operations (compatibility delegates: tasks projects/resolve-project/register-project do the identical thing)",
+		},
+	}),
+	{ name: "projects", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runProjectsCli(args: string[], client: ProjectsClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli.ts

@@ -14,6 +14,7 @@ import { runLogCli } from "./cli/log-command.ts";
 import { runMigrationCli } from "./cli/migration-command.ts";
 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 { runSessionIdentityCli } from "./cli/session-identity-command.ts";
 import { runTaskCli } from "./cli/task-command.ts";
@@ -359,6 +360,7 @@ export {
 	runLogCli,
 	runNoteCli,
 	runPlaybooksCli,
+	runProjectsCli,
 	runRulesCli,
 	runSessionIdentityCli,
 	runTaskCli,
@@ -380,6 +382,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runPlaybooksCli(args.slice(1), client));
 		return;
 	}
+	if (command === "projects") {
+		const client = await connectPapyrusClient();
+		console.log(await runProjectsCli(args.slice(1), client));
+		return;
+	}
 	if (command === "notes") {
 		const client = await connectPapyrusClient();
 		console.log(await runNoteCli(args.slice(1), client));

package/src/domain/project-registry.ts

@@ -1,3 +1,5 @@
+import { TASK_PROJECT_ALIAS_MAX_COUNT, TASK_PROJECT_NAME_MAX_LENGTH } from "../constants.ts";
+
 /**
  * A registered project identity, shared across every artifact kind (Tasks, Docs, Rules,
  * Playbooks) rather than owned by Tasks alone -- extracted so a Doc/Rule/Playbook can resolve
@@ -20,6 +22,29 @@ export interface RegisterProjectInput {
 	existingId?: string;
 }
 
+/**
+ * The one bounded schema vocabulary for a registered project name/alias set -- shared by Tasks'
+ * own registerProject and the kind-neutral projects.register operation, rather than each domain
+ * enforcing a slightly different bound. Reuses constants.ts's existing TASK_PROJECT_* bounds
+ * (unchanged names -- the underlying catalog is Tasks' own historical one, just no longer
+ * Tasks-exclusive) rather than introducing a second, parallel set of the same numbers.
+ * Store-level registerProject (SQLiteProjectRegistryStore) does not itself validate
+ * length/count, so every caller must go through this first.
+ */
+export function assertRegisterProjectInputBounds(name: string | undefined, aliases: string[] | undefined): void {
+	if (name !== undefined && (name.trim().length === 0 || name.length > TASK_PROJECT_NAME_MAX_LENGTH)) {
+		throw new Error(`project name must be between 1 and ${TASK_PROJECT_NAME_MAX_LENGTH} characters`);
+	}
+	if ((aliases?.length ?? 0) > TASK_PROJECT_ALIAS_MAX_COUNT) {
+		throw new Error(`project aliases cannot exceed ${TASK_PROJECT_ALIAS_MAX_COUNT} entries`);
+	}
+	for (const alias of aliases ?? []) {
+		if (alias.trim().length === 0 || alias.length > TASK_PROJECT_NAME_MAX_LENGTH) {
+			throw new Error(`each project alias must be between 1 and ${TASK_PROJECT_NAME_MAX_LENGTH} characters`);
+		}
+	}
+}
+
 export class ProjectNotFoundError extends Error {}
 export class ProjectAmbiguousError extends Error {}
 

package/src/handlers/projects.ts

@@ -0,0 +1,45 @@
+/**
+ * The shared project catalog projected as a real VehicleRegistry: one VehicleOperation per real
+ * action, fronting the same ProjectRegistryStore every Docs/Rules/Playbooks scope operation
+ * already resolves against. tasks.projects/tasks.resolve_project/tasks.register_project remain
+ * unchanged, documented compatibility delegates -- see handlers/tasks.ts.
+ */
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { projectsOperations } from "../modules/projects.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
+import { createOperationDefiner, numberProp, stringProp } from "./shared.ts";
+
+const OWNER = "projects";
+
+export function registerProjectsVehicleOperations(registry: VehicleRegistry, projectRegistry: ProjectRegistryStore): void {
+	const moduleOperations = new Map(projectsOperations(projectRegistry).map((op) => [op.name, op]));
+	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+	const define = createOperationDefiner(registry, OWNER, "projects", ["projects:read", "projects:write"], call);
+
+	define(
+		"list",
+		"Lists registered projects (shared by Tasks, Docs, Rules, and Playbooks), optionally filtered by a name/alias/root substring. Compatibility delegate: tasks.projects does the identical thing.",
+		"read",
+		{ query: stringProp, limit: numberProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"resolve",
+		"Resolves an exact project reference (id, name, alias, or registered root) to its full identity, failing closed with bounded candidates when unknown or ambiguous. Compatibility delegate: tasks.resolve_project does the identical thing.",
+		"read",
+		{ reference: stringProp },
+		["reference"],
+		(input) => input,
+	);
+
+	define(
+		"register",
+		"Registers a new project, or renames/moves an existing one when project_root (or existing_id) already resolves to one. Compatibility delegate: tasks.register_project does the identical thing.",
+		"local-write",
+		{ project_root: stringProp, name: stringProp, aliases: { type: "array" } as unknown as { type: string }, existing_id: stringProp },
+		["project_root"],
+		(input) => input,
+	);
+}

package/src/handlers/registry.ts

@@ -22,6 +22,7 @@ import { registerDiscussVehicleOperations } from "./discuss.ts";
 import { registerDocsVehicleOperations } from "./docs.ts";
 import { registerNotesVehicleOperations } from "./notes.ts";
 import { registerPlaybooksVehicleOperations } from "./playbooks.ts";
+import { registerProjectsVehicleOperations } from "./projects.ts";
 import { registerRulesVehicleOperations } from "./rules.ts";
 import { registerTasksVehicleOperations } from "./tasks.ts";
 
@@ -62,6 +63,7 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 		projectRegistry: deps.projectRegistry,
 	});
 	registerTasksVehicleOperations(registry, { tasks: deps.tasks, artifacts: deps.artifacts, sessionIdentity: deps.sessionIdentity });
+	registerProjectsVehicleOperations(registry, deps.projectRegistry);
 	registerDiscussVehicleOperations(registry, deps.discussions, deps.artifacts);
 	registerArtifactTrashOperations(registry, deps.artifacts);
 	return registry;

package/src/modules/projects.ts

@@ -0,0 +1,48 @@
+/**
+ * modules/projects.ts — the shared project catalog as its own Papyrus-native registered module,
+ * fronting the same ProjectRegistryStore Docs/Rules/Playbooks scope operations and Tasks'
+ * project catalog already share underneath (see ports/project-registry-store.ts). Tasks'
+ * own tasks.projects/tasks.resolve_project/tasks.register_project remain fully working,
+ * documented compatibility delegates -- this module gives every other domain (and any caller
+ * with no reason to go through tasks.*) the identical operations under a kind-neutral name.
+ */
+
+import { TASK_PROJECT_LIST_MAX_RESULTS } from "../constants.ts";
+import { assertRegisterProjectInputBounds, resolveProjectReference } from "../domain/project-registry.ts";
+import { normalizeProjectRoot } from "../domain/task-scope.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
+import { type OperationInput, optionalNumber, optionalString, optionalStringArray, string } from "./operation-input.ts";
+
+const MODULE_ID = "projects";
+
+export const PROJECTS_OPERATION_NAMES = ["projects.list", "projects.resolve", "projects.register"] as const;
+
+export function projectsOperations(registry: ProjectRegistryStore): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name,
+		moduleId: MODULE_ID,
+		execute,
+	});
+	return [
+		define("projects.list", (input: OperationInput) => {
+			const limit = optionalNumber(input, "limit") ?? 20;
+			if (!Number.isInteger(limit) || limit < 1 || limit > TASK_PROJECT_LIST_MAX_RESULTS) {
+				throw new Error(`project list limit must be between 1 and ${TASK_PROJECT_LIST_MAX_RESULTS}`);
+			}
+			return registry.projects(optionalString(input, "query"), limit);
+		}),
+		define("projects.resolve", (input: OperationInput) => resolveProjectReference(registry, string(input, "reference"))),
+		define("projects.register", (input: OperationInput) => {
+			const name = optionalString(input, "name");
+			const aliases = optionalStringArray(input, "aliases");
+			assertRegisterProjectInputBounds(name, aliases);
+			return registry.registerProject({
+				projectRoot: normalizeProjectRoot(string(input, "project_root")),
+				name,
+				aliases,
+				existingId: optionalString(input, "existing_id"),
+			});
+		}),
+	];
+}

package/src/service.ts

@@ -28,6 +28,7 @@ import { LOGS_OPERATION_NAMES, logsOperations } from "./modules/logs.ts";
 import { NOTES_OPERATION_NAMES, notesOperations } from "./modules/notes.ts";
 import { type OperationInput, optionalNumber, optionalString, string } from "./modules/operation-input.ts";
 import { PLAYBOOKS_OPERATION_NAMES, playbooksOperations } from "./modules/playbooks.ts";
+import { PROJECTS_OPERATION_NAMES, projectsOperations } from "./modules/projects.ts";
 import { RULES_OPERATION_NAMES, rulesOperations } from "./modules/rules.ts";
 import { SESSION_IDENTITY_OPERATION_NAMES, sessionIdentityOperations } from "./modules/session-identity.ts";
 import { TASKS_OPERATION_NAMES, tasksOperations } from "./modules/tasks.ts";
@@ -98,6 +99,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	...NOTES_OPERATION_NAMES,
 	...RULES_OPERATION_NAMES,
 	...PLAYBOOKS_OPERATION_NAMES,
+	...PROJECTS_OPERATION_NAMES,
 	...GRAPH_PROJECTION_OPERATION_NAMES,
 	...LOGS_OPERATION_NAMES,
 	...SESSION_IDENTITY_OPERATION_NAMES,
@@ -451,6 +453,9 @@ function handlers(
 		"playbooks.uncontain": forwardToModule("playbooks.uncontain"),
 		"playbooks.depend": forwardToModule("playbooks.depend"),
 		"playbooks.undepend": forwardToModule("playbooks.undepend"),
+		"projects.list": forwardToModule("projects.list"),
+		"projects.resolve": forwardToModule("projects.resolve"),
+		"projects.register": forwardToModule("projects.register"),
 		"graph_projection.apply": forwardToModule("graph_projection.apply"),
 		"graph_projection.checkpoint": forwardToModule("graph_projection.checkpoint"),
 		"logs.append": forwardToModule("logs.append"),
@@ -513,6 +518,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	moduleRegistry.registerAll(
 		playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity, registry: projectRegistry }),
 	);
+	moduleRegistry.registerAll(projectsOperations(projectRegistry));
 	moduleRegistry.registerAll(graphProjectionOperations(artifacts, projections, authority));
 	const registry = handlers(artifacts, gates, tasks, notes, events, scopes, artifactScopes, () => migrateDb(db), moduleRegistry, authority);
 	const state = (): SchemaState => {

package/src/task/task-service.ts

@@ -14,15 +14,14 @@ import {
 	TASK_LABEL_MAX_LENGTH,
 	TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH,
 	TASK_MUTATION_IDEMPOTENCY_RETENTION_MS,
-	TASK_PROJECT_ALIAS_MAX_COUNT,
 	TASK_PROJECT_LIST_MAX_RESULTS,
-	TASK_PROJECT_NAME_MAX_LENGTH,
 	TASK_SCOPE_MAX_TASKS,
 	TASK_TITLE_MAX_LENGTH,
 } from "../constants.ts";
 import { type Checklist, checklistEntries, type ProofReference, validateChecklist } from "../domain/checklist.ts";
 import { DISCUSSION_SUBTYPE, isDiscussionArtifact, readDiscussionExtra } from "../domain/discussion.ts";
 import { type Gate, type GateResult, validateGates } from "../domain/gate.ts";
+import { assertRegisterProjectInputBounds } from "../domain/project-registry.ts";
 import type {
 	AppendTaskEvent,
 	TaskEventContext,
@@ -549,17 +548,7 @@ export class Tasks {
 	registerProject(input: RegisterTaskProjectInput, existingReference?: string): TaskProject {
 		const projectRoot = normalizeProjectRoot(input.projectRoot);
 		const name = input.name?.trim();
-		if (name !== undefined && (name.length === 0 || name.length > TASK_PROJECT_NAME_MAX_LENGTH)) {
-			throw new Error(`project name must be between 1 and ${TASK_PROJECT_NAME_MAX_LENGTH} characters`);
-		}
-		if ((input.aliases?.length ?? 0) > TASK_PROJECT_ALIAS_MAX_COUNT) {
-			throw new Error(`project aliases cannot exceed ${TASK_PROJECT_ALIAS_MAX_COUNT} entries`);
-		}
-		for (const alias of input.aliases ?? []) {
-			if (alias.trim().length === 0 || alias.length > TASK_PROJECT_NAME_MAX_LENGTH) {
-				throw new Error(`each project alias must be between 1 and ${TASK_PROJECT_NAME_MAX_LENGTH} characters`);
-			}
-		}
+		assertRegisterProjectInputBounds(name, input.aliases);
 		const existingId = existingReference ? this.resolveProject(existingReference).id : input.existingId;
 		return this.scopes.registerProject({ projectRoot, ...(name ? { name } : {}), aliases: input.aliases, existingId });
 	}