@edgehero/pi-dispatch-receiver 0.2.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Webhook receiver for pi-dispatch: the always-on edge that verifies GitHub, GitLab, Forgejo and Azure DevOps deliveries and enqueues (at most) one job per event for the worker.",
   "keywords": [
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "14.2.0",
-    "@edgehero/pi-dispatch": "^0.2.0",
+    "@edgehero/pi-dispatch": "^1.0.0",
     "bullmq": "5.80.4",
     "ioredis": "5.11.1"
   }

package/src/config.mjs

@@ -226,11 +226,13 @@ function loadAzureConfig(env) {
  * The shared `parseTriggers` validates the WHOLE file (including the on x run matrix and cron entries the
  * worker owns); this loader keeps only the webhook types and groups them PER FORGE, so `cfg.triggers` is
  * `{ github: <group>, gitlab: <group>, knownFlows }` where each group is:
- *   - `label`:       ordered `{ index, predicate, flow, packages, image }` rules (first match wins in the filter).
- *   - `comment`:     the single `{ index, phrase, defaultFlow, packages, image }` (or null when no comment trigger is configured).
- *   - `pullRequest`: ordered `{ index, actions:Set, predicate, flow, packages, image }` rules.
+ *   - `label`:       ordered `{ index, predicate, flow, command, packages, image }` rules (first match wins in the filter).
+ *   - `comment`:     the single `{ index, phrase, defaultFlow, command, packages, image }` (or null when no comment trigger is configured).
+ *   - `pullRequest`: ordered `{ index, actions:Set, predicate, flow, command, packages, image }` rules.
  * and `knownFlows` is every webhook `run.flow`, so a comment's `<phrase> <flow>` override cannot summon an
- * unlisted flow.
+ * unlisted flow. A rule carries EITHER `flow` or `command` (issue #189; the shared parser enforces the
+ * exclusivity): a command rule's match dispatches a registered pi extension command in the container, so
+ * it resolves no flow and contributes nothing to the flow vocabulary.
  *
  * Grouping by forge FIRST is what keeps each forge's gate reading only its own rules: a GitLab delivery
  * can never match a rule an operator wrote for GitHub, even when both name the same label. `knownFlows`
@@ -272,16 +274,22 @@ function loadTriggers(env, readFile, fileExists) {
 
 	for (const [index, { on, run }] of parsed.entries()) {
 		if (on.type === "cron") continue; // the worker owns cron; the receiver never fires it -- but it keeps its index
-		knownFlows.add(run.flow);
+		// Guarded because a command trigger (issue #189) has NO run.flow, and `Set.add(undefined)` would put
+		// undefined into the comment `<phrase> <flow>` override allowlist. That set exists to bound which
+		// names a collaborator's comment may summon; polluting it with a non-name is how a later loose
+		// membership test (or a `[...set]` enumeration in a message) starts treating "no flow" as a flow.
+		if (typeof run.flow === "string") {
+			knownFlows.add(run.flow);
+		}
 		const group = groups[run.kind];
 		if (on.type === "label") {
-			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository });
+			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository });
 		} else if (on.type === "comment") {
-			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
+			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
 		} else if (on.type === "pull_request") {
 			// `reviewStates` is null rather than an empty Set when unnarrowed: the filter tests it for
 			// presence, and an empty Set would read as "no verdict matches" and silently refuse everything.
-			group.pullRequest.push({ index, actions: new Set(on.action), reviewStates: on.reviewState ? new Set(on.reviewState) : null, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas });
+			group.pullRequest.push({ index, actions: new Set(on.action), reviewStates: on.reviewState ? new Set(on.reviewState) : null, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas });
 		}
 	}
 

package/src/filter-azure.mjs

@@ -102,7 +102,11 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		// gitlab makes when it carries `projectId` next to `repo`.
 		azure: resolved.azure,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all. The spread keeps a flow rule's
+		// literal byte-identical to what it always was -- the same move filter.mjs makes.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -167,7 +171,8 @@ function matchLabelRules(subset, triggers, labels, action) {
 	return {
 		enqueue: true,
 		action,
-		flow: rule.flow,
+		// A command rule (issue #189) skips flow resolution entirely: the tag match IS the dispatch.
+		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		repository: rule.repository,
 		packages: rule.packages,
 		image: rule.image,
@@ -186,18 +191,28 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) {
-		flow = match[1];
-	}
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
+	// trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase alone
+	// fires, and trailing comment text stays DATA (the handler reads the delivery via /job/event.json). An
+	// active override would hand any authorized member two levers the trigger's author never granted:
+	// retarget the command onto a known flow by appending its name, or veto it (the `no-flow` arm) with a
+	// word that resolves nowhere. Same rationale, same shape as filter.mjs's routeComment.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		flow = triggers.comment?.defaultFlow;
+		const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) {
+			flow = match[1];
+		}
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	return {
 		enqueue: true,
 		action: "commented",
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		repository: triggers.comment.repository,
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
@@ -225,7 +240,8 @@ function routePullRequest(subset, triggers, action) {
 		return {
 			enqueue: true,
 			action,
-			flow: rule.flow,
+			// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
+			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			repository: rule.repository,
 			packages: rule.packages,
 			image: rule.image,

package/src/filter-forgejo.mjs

@@ -104,7 +104,11 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 	const job = {
 		repo: subset.repository?.full_name,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all. The spread keeps a flow rule's
+		// literal byte-identical to what it always was -- the same move filter.mjs makes.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -136,7 +140,8 @@ function routeIssueLabel(subset, triggers) {
 	}
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// A command rule (issue #189) skips flow resolution entirely: the label match IS the dispatch.
+		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 		image: rule.image,
 		skillsDir: rule.skillsDir,
@@ -154,15 +159,25 @@ function routeComment(subset, triggers, knownFlows) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a known
-	// flow name, so a comment cannot summon an unlisted flow.
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) {
-		flow = match[1];
-	}
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
+	// trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase alone
+	// fires, and trailing comment text stays DATA (the handler reads the delivery via /job/event.json). An
+	// active override would hand any authorized collaborator two levers the trigger's author never granted:
+	// retarget the command onto a known flow by appending its name, or veto it (the `no-flow` arm) with a
+	// word that resolves nowhere. Same rationale, same shape as filter.mjs's routeComment.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a known
+		// flow name, so a comment cannot summon an unlisted flow.
+		flow = triggers.comment?.defaultFlow;
+		const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) {
+			flow = match[1];
+		}
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	// `is_pull` is TOP-LEVEL on Forgejo, where GitHub carries `issue.pull_request`. Reading the wrong one
 	// routes every pull-request comment as an issue, and the envelope then tells the agent to open
@@ -171,7 +186,7 @@ function routeComment(subset, triggers, knownFlows) {
 	const isPR = subset.isPull === true;
 	return {
 		enqueue: true,
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
@@ -197,7 +212,8 @@ function routePullRequest(subset, triggers, action) {
 		if (rule.predicate && !matchesRule(L, rule.predicate)) continue;
 		return {
 			enqueue: true,
-			flow: rule.flow,
+			// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
+			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			packages: rule.packages,
 			image: rule.image,
 			skillsDir: rule.skillsDir,

package/src/filter-gitlab.mjs

@@ -95,7 +95,11 @@ export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, d
 		repo: subset.project?.path,
 		projectId: subset.project?.id,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all. The spread keeps a flow rule's
+		// literal byte-identical to what it always was -- the same move filter.mjs makes.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -134,7 +138,8 @@ function routeLabel(subset, triggers, targetType) {
 	if (!rule) return { enqueue: false, reason: "no-allowlisted-label" };
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// A command rule (issue #189) skips flow resolution entirely: the label match IS the dispatch.
+		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages,
 		image: rule.image,
 		skillsDir: rule.skillsDir,
@@ -193,7 +198,8 @@ function routeMergeRequest(subset, triggers) {
 function mrResult(subset, rule, matched) {
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
+		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages,
 		image: rule.image,
 		skillsDir: rule.skillsDir,
@@ -218,18 +224,28 @@ function routeNote(subset, triggers, knownFlows) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
-	// known flow name, so a comment cannot summon an unlisted flow.
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeLiteral(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) flow = match[1];
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
+	// trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase alone
+	// fires, and trailing note text stays DATA (the handler reads the delivery via /job/event.json). An
+	// active override would hand any authorized member two levers the trigger's author never granted:
+	// retarget the command onto a known flow by appending its name, or veto it (the `no-flow` arm) with a
+	// word that resolves nowhere. Same rationale, same shape as filter.mjs's routeComment.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
+		// known flow name, so a comment cannot summon an unlisted flow.
+		flow = triggers.comment?.defaultFlow;
+		const match = body.match(new RegExp(escapeLiteral(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) flow = match[1];
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	const targetType = subset.noteableType === "MergeRequest" ? "pull_request" : "issue";
 	return {
 		enqueue: true,
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,

package/src/filter.mjs

@@ -108,7 +108,12 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 	const job = {
 		repo: subset.repository?.full_name,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all -- a present-and-undefined flow would
+		// change the enqueued bytes for every consumer that serializes the job. The spread keeps a flow
+		// rule's literal byte-identical to what it always was.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -156,7 +161,8 @@ function routeIssueLabel(subset, triggers) {
 	}
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// A command rule (issue #189) skips flow resolution entirely: the label match IS the dispatch.
+		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 		image: rule.image,
 		skillsDir: rule.skillsDir,
@@ -183,15 +189,26 @@ function routeComment(subset, triggers, knownFlows) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
-	// known flow name, so a comment cannot summon an unlisted flow.
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) {
-		flow = match[1];
-	}
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the whole flow-resolution block below -- default flow, the `<phrase>
+	// <flow>` trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase
+	// alone fires the command, and everything after it is comment DATA (the handler can read the full
+	// delivery via /job/event.json), never a flow lookup. Routing trailing words through the override
+	// would hand any collaborator two levers this trigger's author never granted: retarget the command
+	// trigger onto a known flow by appending its name, or suppress it outright (the `no-flow` arm) with a
+	// word that resolves nowhere. Which flows exist is the operator's file's business, not the commenter's.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
+		// known flow name, so a comment cannot summon an unlisted flow.
+		flow = triggers.comment.defaultFlow;
+		const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) {
+			flow = match[1];
+		}
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	// An issue_comment on a PR carries issue.pull_request; its issue.number IS the PR number and the
 	// issue title/body are the PR's. Route it as a pull_request target so the flow gets PR context and
@@ -200,7 +217,7 @@ function routeComment(subset, triggers, knownFlows) {
 	const isPR = subset.issue?.pull_request === true;
 	return {
 		enqueue: true,
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		// The single comment trigger IS the matched rule here, so its opt-in is the job's. A `<phrase>
 		// <flow>` override changes WHICH flow runs, never which triggers.json entry authorized it.
 		packages: triggers.comment.packages,
@@ -296,7 +313,8 @@ function routePullRequest(subset, triggers, action) {
 		}
 		return {
 			enqueue: true,
-			flow: rule.flow,
+			// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
+			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 			image: rule.image,
 			skillsDir: rule.skillsDir,