@mastra/factory 0.13.0-alpha.13 → 0.13.0-alpha.14

package/dist/routes/work-items.js

@@ -1,6 +1,7 @@
 import { createBoardRegistry } from "../boards/registry.js";
 import "../boards/index.js";
 import { FACTORY_PULL_REQUEST_RECONCILIATION_KEY, FACTORY_RULE_MATERIALIZATION_KEY, WorkItemRelationError, WorkItemUpdateConflictError } from "../storage/domains/work-items/base.js";
+import { FACTORY_ROUTE_CONTRACTS } from "./contracts.js";
 import { Route } from "./route.js";
 import { factoryDispatchFailureMetadata } from "../rules/dispatch-errors.js";
 import { FactoryStartTransitionError } from "../rules/start-coordinator.js";
@@ -28,124 +29,20 @@ function runningSessionIds(items, liveSessions) {
 function loose(c) {
 	return c;
 }
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const MAX_STAGES = 16;
-const MAX_STAGE_LENGTH = 64;
-const MAX_METADATA_BYTES = 16 * 1024;
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function validStages(value) {
-	return Array.isArray(value) && value.length > 0 && value.length <= MAX_STAGES && value.every((stage) => typeof stage === "string" && stage.length <= MAX_STAGE_LENGTH && /^[a-z0-9][a-z0-9_-]*$/i.test(stage)) && new Set(value).size === value.length;
-}
-function validMetadata(value) {
-	if (value === null) return true;
-	if (!isRecord(value)) return false;
-	try {
-		return JSON.stringify(value).length <= MAX_METADATA_BYTES;
-	} catch {
-		return false;
-	}
-}
 function publicWorkItemMetadata(value) {
 	if (value === null) return null;
 	const { [FACTORY_RULE_MATERIALIZATION_KEY]: _materialization, [FACTORY_PULL_REQUEST_RECONCILIATION_KEY]: _reconciliation, ...metadata } = value;
 	return metadata;
 }
-function parseExternalSource(value) {
-	if (value === void 0 || value === null) return value;
-	if (!isRecord(value)) return void 0;
-	const { integrationId, type, externalId, url } = value;
-	if (typeof integrationId !== "string" || integrationId.length === 0 || integrationId.length > 128) return void 0;
-	if (typeof type !== "string" || type.length === 0 || type.length > 128) return void 0;
-	if (typeof externalId !== "string" || externalId.length === 0 || externalId.length > 512) return void 0;
-	if (url !== void 0 && (typeof url !== "string" || url.length > 2048)) return void 0;
-	return {
-		integrationId,
-		type,
-		externalId,
-		...url !== void 0 ? { url } : {}
-	};
-}
-function parseParentWorkItemId(value) {
-	if (value === null) return null;
-	if (typeof value !== "string" || !UUID_RE.test(value)) return void 0;
-	return value;
-}
-function parseSessions(value) {
-	if (!isRecord(value)) return void 0;
-	const out = {};
-	for (const [role, session] of Object.entries(value)) {
-		if (!role || role.length > 64 || !isRecord(session)) return void 0;
-		const { sessionId, branch, threadId } = session;
-		if (typeof sessionId !== "string" || sessionId.length === 0 || sessionId.length > 512) return void 0;
-		if (typeof branch !== "string" || branch.length === 0 || branch.length > 512) return void 0;
-		if (typeof threadId !== "string" || threadId.length === 0 || threadId.length > 512) return void 0;
-		out[role] = {
-			sessionId,
-			branch,
-			threadId
-		};
-	}
-	return out;
-}
 /** Validate an untrusted create body. Unknown keys are dropped. */
 function parseCreateWorkItem(body) {
-	if (!isRecord(body)) return null;
-	const { board, externalSource, title, stages, sessions, metadata } = body;
-	if (typeof title !== "string" || title.trim().length === 0 || title.length > 500) return null;
-	if (board !== void 0 && (typeof board !== "string" || board.length === 0 || board.length > 128)) return null;
-	const hasParentWorkItemId = "parentWorkItemId" in body;
-	const parentWorkItemId = hasParentWorkItemId ? parseParentWorkItemId(body.parentWorkItemId) : void 0;
-	if (hasParentWorkItemId && parentWorkItemId === void 0) return null;
-	const parsedSource = parseExternalSource(externalSource);
-	if (externalSource !== void 0 && parsedSource === void 0) return null;
-	if (stages !== void 0 && !validStages(stages)) return null;
-	const parsedSessions = sessions === void 0 ? void 0 : parseSessions(sessions);
-	if (sessions !== void 0 && parsedSessions === void 0) return null;
-	let parsedMetadata;
-	if (metadata !== void 0) {
-		if (!validMetadata(metadata)) return null;
-		parsedMetadata = publicWorkItemMetadata(metadata);
-	}
-	return {
-		title: title.trim(),
-		...board !== void 0 ? { board } : {},
-		...parsedSource !== void 0 ? { externalSource: parsedSource } : {},
-		...hasParentWorkItemId ? { parentWorkItemId: parentWorkItemId ?? null } : {},
-		...stages !== void 0 ? { stages } : {},
-		...parsedSessions !== void 0 ? { sessions: parsedSessions } : {},
-		...parsedMetadata !== void 0 ? { metadata: parsedMetadata } : {}
-	};
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemCreate.bodySchema.safeParse(body);
+	return parsed.success ? parsed.data : null;
 }
 /** Validate an untrusted patch body. Unknown keys are dropped. */
 function parseUpdateWorkItem(body) {
-	if (!isRecord(body)) return null;
-	const { board, title, stages, sessions, metadata, plansPreapproved } = body;
-	const hasParentWorkItemId = "parentWorkItemId" in body;
-	if (board === void 0 && title === void 0 && stages === void 0 && sessions === void 0 && metadata === void 0 && plansPreapproved === void 0 && !hasParentWorkItemId) return null;
-	if (board !== void 0 && (typeof board !== "string" || board.length === 0 || board.length > 128)) return null;
-	if (plansPreapproved !== void 0 && plansPreapproved !== true) return null;
-	const parentWorkItemId = hasParentWorkItemId ? parseParentWorkItemId(body.parentWorkItemId) : void 0;
-	if (hasParentWorkItemId && parentWorkItemId === void 0) return null;
-	if (title !== void 0 && (typeof title !== "string" || title.trim().length === 0 || title.length > 500)) return null;
-	if (stages !== void 0 && !validStages(stages)) return null;
-	const parsedSessions = sessions === void 0 ? void 0 : parseSessions(sessions);
-	if (sessions !== void 0 && parsedSessions === void 0) return null;
-	let parsedMetadata;
-	if (metadata !== void 0) {
-		if (!validMetadata(metadata)) return null;
-		parsedMetadata = publicWorkItemMetadata(metadata);
-	}
-	return {
-		...board !== void 0 ? { board } : {},
-		...hasParentWorkItemId ? { parentWorkItemId: parentWorkItemId ?? null } : {},
-		...title !== void 0 ? { title: title.trim() } : {},
-		...stages !== void 0 ? { stages } : {},
-		...parsedSessions !== void 0 ? { sessions: parsedSessions } : {},
-		...parsedMetadata !== void 0 ? { metadata: parsedMetadata } : {},
-		...plansPreapproved === true ? { plansPreapproved: true } : {}
-	};
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemUpdate.bodySchema.safeParse(body);
+	return parsed.success ? parsed.data : null;
 }
 async function readJson(c) {
 	try {
@@ -158,92 +55,21 @@ async function readJson(c) {
 function patchedFields(patch) {
 	return Object.keys(patch).filter((key) => patch[key] !== void 0);
 }
-function boundedText(value, max) {
-	if (typeof value !== "string") return void 0;
-	const normalized = value.trim();
-	return normalized.length > 0 && normalized.length <= max ? normalized : void 0;
-}
 function parseTransitionBody(body) {
-	if (!isRecord(body)) return null;
-	const board = typeof body.board === "string" && body.board.length > 0 ? body.board : void 0;
-	const stage = typeof body.stage === "string" && body.stage.length > 0 ? body.stage : void 0;
-	const requestId = boundedText(body.requestId, 256);
-	const cause = boundedText(body.cause, 256);
-	if (!board || !stage || !requestId || !UUID_RE.test(requestId) || !cause || !Number.isInteger(body.expectedRevision) || Number(body.expectedRevision) < 1) return null;
-	return {
-		board,
-		stage,
-		expectedRevision: Number(body.expectedRevision),
-		ingress: {
-			type: "human",
-			identity: requestId
-		},
-		cause,
-		...body.reenter === true ? { reenter: true } : {}
-	};
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemTransition.bodySchema.safeParse(body);
+	return parsed.success ? parsed.data : null;
 }
 function parseStartBody(body, tenant, factoryProjectId) {
-	if (!isRecord(body) || !isRecord(body.workItem)) return null;
-	const input = parseCreateWorkItem(body.workItem.input);
-	const sessionId = boundedText(body.sessionId, 256);
-	const threadTitle = boundedText(body.threadTitle, 512);
-	const kickoffKey = boundedText(body.kickoffKey, 256);
-	const role = boundedText(body.workItem.role, 32);
-	const id = boundedText(body.workItem.id, 64);
-	if (!input || !sessionId || !UUID_RE.test(sessionId) || !threadTitle || !kickoffKey || !UUID_RE.test(kickoffKey) || !id || !UUID_RE.test(id) || !role) return null;
-	return {
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemStart.bodySchema.safeParse(body);
+	return parsed.success ? {
 		...tenant,
 		factoryProjectId,
-		sessionId,
-		threadTitle,
-		kickoffKey,
-		workItem: {
-			id,
-			role,
-			input
-		}
-	};
-}
-const DECISION_STATUSES = /* @__PURE__ */ new Set([
-	"pending",
-	"proposed",
-	"dismissed",
-	"superseded",
-	"leased",
-	"retry",
-	"succeeded",
-	"failed"
-]);
-const DEFAULT_DECISION_PAGE_SIZE = 25;
-const MAX_DECISION_PAGE_SIZE = 50;
-function parseDecisionStatuses(raw) {
-	if (!raw) return void 0;
-	const statuses = [...new Set(raw.split(",").map((status) => status.trim()))].filter((status) => DECISION_STATUSES.has(status));
-	return statuses.length > 0 ? statuses : void 0;
-}
-function parseDecisionLimit(raw) {
-	const parsed = raw ? Number.parseInt(raw, 10) : DEFAULT_DECISION_PAGE_SIZE;
-	if (!Number.isFinite(parsed)) return DEFAULT_DECISION_PAGE_SIZE;
-	return Math.max(1, Math.min(MAX_DECISION_PAGE_SIZE, parsed));
+		...parsed.data
+	} : null;
 }
 function encodeDecisionCursor(decision) {
 	return Buffer.from(JSON.stringify([decision.createdAt.toISOString(), decision.id]), "utf8").toString("base64url");
 }
-function parseDecisionCursor(raw) {
-	if (!raw) return void 0;
-	try {
-		const decoded = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
-		if (!Array.isArray(decoded) || decoded.length !== 2 || typeof decoded[0] !== "string" || typeof decoded[1] !== "string") return;
-		const createdAt = new Date(decoded[0]);
-		if (Number.isNaN(createdAt.getTime()) || !UUID_RE.test(decoded[1])) return void 0;
-		return {
-			createdAt,
-			id: decoded[1]
-		};
-	} catch {
-		return;
-	}
-}
 /** A proposed transition names the seat its lane addresses, so the card can label what approving starts. */
 function summaryRole(boards, decision) {
 	if (typeof decision.role === "string") return decision.role.slice(0, 32);
@@ -304,8 +130,9 @@ var WorkItemRoutes = class extends Route {
 	async #resolveProject(c) {
 		const tenant = await this.#resolveTenant(c);
 		if ("response" in tenant) return tenant;
-		const projectId = c.req.param("id");
-		if (!projectId || !UUID_RE.test(projectId)) return { response: c.json({ error: "Project not found" }, 404) };
+		const parsedPath = FACTORY_ROUTE_CONTRACTS.projectGet.pathSchema.safeParse({ id: c.req.param("id") });
+		if (!parsedPath.success) return { response: c.json({ error: "Project not found" }, 404) };
+		const projectId = parsedPath.data.id;
 		const { projects } = this.deps;
 		await projects.ensureReady();
 		const project = await projects.get({
@@ -374,15 +201,20 @@ var WorkItemRoutes = class extends Route {
 	/** Releasing a parked run and dropping it: same request, opposite outcomes, both audited as consent. */
 	#proposalRoute({ verb, settle }) {
 		const { audit, workItems } = this.deps;
-		return registerApiRoute(`/web/factory/projects/:id/decisions/:decisionId/${verb}`, {
-			method: "POST",
+		const contract = verb === "approve" ? FACTORY_ROUTE_CONTRACTS.decisionApprove : FACTORY_ROUTE_CONTRACTS.decisionDismiss;
+		return registerApiRoute(contract.path, {
+			method: contract.method,
 			requiresAuth: false,
 			handler: async (c) => {
 				const context = loose(c);
 				const resolved = await this.#resolveProject(context);
 				if ("response" in resolved) return resolved.response;
-				const decisionId = context.req.param("decisionId");
-				if (!decisionId || !UUID_RE.test(decisionId)) return c.json({ error: "invalid_decision_id" }, 422);
+				const parsedPath = contract.pathSchema.safeParse({
+					id: resolved.factoryProjectId,
+					decisionId: context.req.param("decisionId")
+				});
+				if (!parsedPath.success) return c.json({ error: "invalid_decision_id" }, 422);
+				const { decisionId } = parsedPath.data;
 				await workItems.ensureReady();
 				const now = /* @__PURE__ */ new Date();
 				const decision = await settle(resolved.orgId, resolved.factoryProjectId, decisionId, now, resolved.userId);
@@ -413,8 +245,8 @@ var WorkItemRoutes = class extends Route {
 	routes() {
 		const { audit, workItems, queueHealth, transitionService, startCoordinator, liveSessions } = this.deps;
 		return [
-			registerApiRoute("/web/factory/projects/:id/work-items", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemList.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemList.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -430,13 +262,19 @@ var WorkItemRoutes = class extends Route {
 					});
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/metrics", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.metricsGet.path, {
+				method: FACTORY_ROUTE_CONTRACTS.metricsGet.method,
 				requiresAuth: false,
 				handler: async (c) => {
-					const resolved = await this.#resolveProject(loose(c));
+					const context = loose(c);
+					const resolved = await this.#resolveProject(context);
 					if ("response" in resolved) return resolved.response;
-					const { windowStart, windowEnd } = parseMetricsRange(loose(c).req.query("from"), loose(c).req.query("to"), /* @__PURE__ */ new Date());
+					const query = FACTORY_ROUTE_CONTRACTS.metricsGet.querySchema.safeParse({
+						from: context.req.query("from"),
+						to: context.req.query("to")
+					});
+					if (!query.success) return c.json({ error: "invalid_metrics_range" }, 400);
+					const { windowStart, windowEnd } = parseMetricsRange(query.data.from, query.data.to, /* @__PURE__ */ new Date());
 					await workItems.ensureReady();
 					const items = await workItems.list({
 						orgId: resolved.orgId,
@@ -448,8 +286,8 @@ var WorkItemRoutes = class extends Route {
 					}) });
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/health/thresholds", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.healthThresholdsGet.path, {
+				method: FACTORY_ROUTE_CONTRACTS.healthThresholdsGet.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -459,23 +297,29 @@ var WorkItemRoutes = class extends Route {
 					return c.json({ thresholds: thresholdsOrDefault(stored) });
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/decisions", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.decisionList.path, {
+				method: FACTORY_ROUTE_CONTRACTS.decisionList.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const context = loose(c);
 					const resolved = await this.#resolveProject(context);
 					if ("response" in resolved) return resolved.response;
-					const cursorRaw = context.req.query("before");
-					const before = parseDecisionCursor(cursorRaw);
-					if (cursorRaw && !before) return c.json({ error: "invalid_cursor" }, 400);
+					const query = FACTORY_ROUTE_CONTRACTS.decisionList.querySchema.safeParse({
+						statuses: context.req.query("statuses"),
+						before: context.req.query("before"),
+						limit: context.req.query("limit")
+					});
+					if (!query.success) {
+						const field = query.error.issues[0]?.path[0];
+						return c.json({ error: field === "before" ? "invalid_cursor" : "invalid_decision_query" }, 400);
+					}
 					await workItems.ensureReady();
 					const page = await workItems.listDeferredDecisionPage({
 						orgId: resolved.orgId,
 						factoryProjectId: resolved.factoryProjectId,
-						statuses: parseDecisionStatuses(context.req.query("statuses")),
-						before,
-						limit: parseDecisionLimit(context.req.query("limit"))
+						statuses: query.data.statuses,
+						before: query.data.before,
+						limit: query.data.limit
 					});
 					const last = page.decisions.at(-1);
 					return c.json({
@@ -502,15 +346,19 @@ var WorkItemRoutes = class extends Route {
 				verb: "dismiss",
 				settle: workItems.dismissDeferredDecision.bind(workItems)
 			}),
-			registerApiRoute("/web/factory/projects/:id/decisions/:decisionId/retry", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.decisionRetry.path, {
+				method: FACTORY_ROUTE_CONTRACTS.decisionRetry.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const context = loose(c);
 					const resolved = await this.#resolveProject(context);
 					if ("response" in resolved) return resolved.response;
-					const decisionId = context.req.param("decisionId");
-					if (!decisionId || !UUID_RE.test(decisionId)) return c.json({ error: "invalid_decision_id" }, 422);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.decisionRetry.pathSchema.safeParse({
+						id: resolved.factoryProjectId,
+						decisionId: context.req.param("decisionId")
+					});
+					if (!parsedPath.success) return c.json({ error: "invalid_decision_id" }, 422);
+					const { decisionId } = parsedPath.data;
 					await workItems.ensureReady();
 					const current = await workItems.getDeferredDecision(resolved.orgId, resolved.factoryProjectId, decisionId);
 					if (!current || current.status !== "failed" || !factoryDispatchFailureMetadata(current.failureCode).canRetry) return c.json({ error: "decision_not_retryable" }, 409);
@@ -519,8 +367,8 @@ var WorkItemRoutes = class extends Route {
 					return c.json({ decision: decisionSummary(this.#boards, decision) });
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/work-items", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemCreate.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemCreate.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -627,15 +475,20 @@ var WorkItemRoutes = class extends Route {
 					}
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/work-items/:workItemId/transition", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemTransition.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemTransition.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
 					if ("response" in resolved) return resolved.response;
-					const workItemId = loose(c).req.param("workItemId");
-					if (!workItemId || !UUID_RE.test(workItemId)) return c.json({ error: "Work item not found" }, 404);
-					const parsed = parseTransitionBody(await readJson(loose(c)));
+					const context = loose(c);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.workItemTransition.pathSchema.safeParse({
+						id: resolved.factoryProjectId,
+						workItemId: context.req.param("workItemId")
+					});
+					if (!parsedPath.success) return c.json({ error: "Work item not found" }, 404);
+					const { workItemId } = parsedPath.data;
+					const parsed = parseTransitionBody(await readJson(context));
 					if (!parsed) return c.json({ error: "invalid_transition_request" }, 400);
 					if (!transitionService) return c.json({ error: "factory_transition_unavailable" }, 503);
 					await workItems.ensureReady();
@@ -680,8 +533,8 @@ var WorkItemRoutes = class extends Route {
 					return c.json({ result }, result.code === "stale" ? 409 : 422);
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/runs/start", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemStart.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemStart.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -720,15 +573,17 @@ var WorkItemRoutes = class extends Route {
 					return c.json({ prepared }, 202);
 				}
 			}),
-			registerApiRoute("/web/factory/work-items/:id", {
-				method: "PATCH",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemUpdate.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemUpdate.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const tenant = await this.#resolveTenant(loose(c));
 					if ("response" in tenant) return tenant.response;
-					const id = loose(c).req.param("id");
-					if (!id || !UUID_RE.test(id)) return c.json({ error: "Work item not found" }, 404);
-					const body = await readJson(loose(c));
+					const context = loose(c);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.workItemUpdate.pathSchema.safeParse({ id: context.req.param("id") });
+					if (!parsedPath.success) return c.json({ error: "Work item not found" }, 404);
+					const { id } = parsedPath.data;
+					const body = await readJson(context);
 					if (body === void 0) return c.json({ error: "Invalid JSON body" }, 400);
 					const patch = parseUpdateWorkItem(body);
 					if (!patch) return c.json({ error: "invalid_work_item_patch" }, 400);
@@ -777,14 +632,16 @@ var WorkItemRoutes = class extends Route {
 					}
 				}
 			}),
-			registerApiRoute("/web/factory/work-items/:id", {
-				method: "DELETE",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemDelete.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemDelete.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const tenant = await this.#resolveTenant(loose(c));
 					if ("response" in tenant) return tenant.response;
-					const id = loose(c).req.param("id");
-					if (!id || !UUID_RE.test(id)) return c.json({ error: "Work item not found" }, 404);
+					const context = loose(c);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.workItemDelete.pathSchema.safeParse({ id: context.req.param("id") });
+					if (!parsedPath.success) return c.json({ error: "Work item not found" }, 404);
+					const { id } = parsedPath.data;
 					await workItems.ensureReady();
 					const deleted = await workItems.delete({
 						orgId: tenant.orgId,