stageflow 0.32.0 → 0.35.0

package/dist/server/readCatalogFile.d.ts

@@ -0,0 +1,29 @@
+import { type ResolveCatalogRelativePathInput } from "../config/catalogRelativePath.js";
+import { type ValidationFinding } from "../config/validateCatalog.js";
+export declare const CATALOG_FILE_MAX_BYTES: number;
+export type CatalogFileReadErrorCode = "unsupported_file_type" | "path_outside_project_root" | "catalog_file_not_found" | "catalog_file_too_large";
+export type ReadCatalogFileResult = {
+    ok: true;
+    path: string;
+    content: string;
+} | {
+    ok: false;
+    status: 400 | 404 | 413;
+    error: string;
+    code: CatalogFileReadErrorCode;
+};
+export type WriteCatalogFileResult = {
+    ok: true;
+    path: string;
+    content: string;
+} | {
+    ok: false;
+    status: 400 | 404 | 413;
+    error: string;
+    code: CatalogFileReadErrorCode | "stage_invalid";
+    findings?: ValidationFinding[];
+};
+export declare function readCatalogFileForHttp(input: ResolveCatalogRelativePathInput): Promise<ReadCatalogFileResult>;
+export declare function writeCatalogFileForHttp(input: ResolveCatalogRelativePathInput & {
+    content: string;
+}): Promise<WriteCatalogFileResult>;

package/dist/server/readCatalogFile.js

@@ -0,0 +1,215 @@
+import { readFile, realpath, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CatalogPathError, isInsideProjectRoot, resolveCatalogRelativePath, } from "../config/catalogRelativePath.js";
+import { loadStageOutcome } from "../config/loadStage.js";
+import { findingsFromLoadIssues, } from "../config/validateCatalog.js";
+export const CATALOG_FILE_MAX_BYTES = 512 * 1024;
+function isCatalogYamlExtension(inputPath) {
+    const ext = path.extname(inputPath).toLowerCase();
+    return ext === ".yaml" || ext === ".yml";
+}
+export async function readCatalogFileForHttp(input) {
+    if (!isCatalogYamlExtension(input.inputPath)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be read",
+            code: "unsupported_file_type",
+        };
+    }
+    let resolved;
+    try {
+        resolved = resolveCatalogRelativePath(input);
+    }
+    catch (err) {
+        if (err instanceof CatalogPathError) {
+            if (err.code === "path_outside_project_root") {
+                return {
+                    ok: false,
+                    status: 400,
+                    error: err.message,
+                    code: "path_outside_project_root",
+                };
+            }
+            throw err;
+        }
+        throw err;
+    }
+    let rootReal;
+    let fileReal;
+    try {
+        rootReal = await realpath(resolved.root.path);
+        fileReal = await realpath(resolved.absolutePath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!isInsideProjectRoot(rootReal, fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: `path escapes project_root ${resolved.root.project_root}`,
+            code: "path_outside_project_root",
+        };
+    }
+    if (!isCatalogYamlExtension(fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be read",
+            code: "unsupported_file_type",
+        };
+    }
+    let fileStat;
+    try {
+        fileStat = await stat(fileReal);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!fileStat.isFile()) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be read",
+            code: "unsupported_file_type",
+        };
+    }
+    if (fileStat.size > CATALOG_FILE_MAX_BYTES) {
+        return {
+            ok: false,
+            status: 413,
+            error: `Catalog file exceeds ${CATALOG_FILE_MAX_BYTES} byte limit`,
+            code: "catalog_file_too_large",
+        };
+    }
+    const content = await readFile(fileReal, "utf8");
+    return { ok: true, path: resolved.relativePath, content };
+}
+export async function writeCatalogFileForHttp(input) {
+    if (!isCatalogYamlExtension(input.inputPath)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be written",
+            code: "unsupported_file_type",
+        };
+    }
+    if (Buffer.byteLength(input.content, "utf8") > CATALOG_FILE_MAX_BYTES) {
+        return {
+            ok: false,
+            status: 413,
+            error: `Catalog file exceeds ${CATALOG_FILE_MAX_BYTES} byte limit`,
+            code: "catalog_file_too_large",
+        };
+    }
+    let resolved;
+    try {
+        resolved = resolveCatalogRelativePath(input);
+    }
+    catch (err) {
+        if (err instanceof CatalogPathError) {
+            if (err.code === "path_outside_project_root") {
+                return {
+                    ok: false,
+                    status: 400,
+                    error: err.message,
+                    code: "path_outside_project_root",
+                };
+            }
+            throw err;
+        }
+        throw err;
+    }
+    let rootReal;
+    let fileReal;
+    try {
+        rootReal = await realpath(resolved.root.path);
+        fileReal = await realpath(resolved.absolutePath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!isInsideProjectRoot(rootReal, fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: `path escapes project_root ${resolved.root.project_root}`,
+            code: "path_outside_project_root",
+        };
+    }
+    if (!isCatalogYamlExtension(fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be written",
+            code: "unsupported_file_type",
+        };
+    }
+    let fileStat;
+    try {
+        fileStat = await stat(fileReal);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!fileStat.isFile()) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be written",
+            code: "unsupported_file_type",
+        };
+    }
+    const original = await readFile(fileReal, "utf8");
+    await writeFile(fileReal, input.content, "utf8");
+    const outcome = await loadStageOutcome(fileReal);
+    if (!outcome.ok) {
+        await writeFile(fileReal, original, "utf8");
+        const findings = findingsFromLoadIssues(resolved.root.path, fileReal, outcome.issues);
+        return {
+            ok: false,
+            status: 400,
+            error: findings[0]?.message ?? "Invalid stage YAML",
+            code: "stage_invalid",
+            findings,
+        };
+    }
+    return { ok: true, path: resolved.relativePath, content: input.content };
+}

package/dist/server/triggerRoutes.d.ts

@@ -3,6 +3,7 @@ import type { Logger } from "../logging/logger.js";
 import type { RunManager } from "../runtime/runManager.js";
 import type { RunStore } from "../runstore/port.js";
 export type { TriggerListItem } from "../config/triggerCatalog.js";
+export type { TriggerAdapterStatus } from "../config/triggerAdapterStatus.js";
 export type TriggerRoutesCtx = {
     cwd: string;
     manager: RunManager;

package/dist/server/triggerRoutes.js

@@ -1,18 +1,40 @@
 import { fireTrigger } from "../runtime/triggerRunner.js";
-import { findTriggerDefinition } from "../runtime/triggerCatalog.js";
-import { matchesEventFilter } from "../runtime/triggerEventMatch.js";
-import { verifyHmacSignature } from "../runtime/webhookSignature.js";
+import { acceptWebhook } from "../runtime/webhookAccept.js";
 import { mapStartFailure } from "./operatorResults.js";
 import { writeAudit } from "../logging/audit.js";
 import { callerIdFromRequestAuth, getRequestAuth, } from "./requestAuthContext.js";
-import { loadCatalogTriggers } from "../config/triggerCatalog.js";
+import { findCatalogTrigger, loadCatalogTriggers, triggerStoreId, } from "../config/triggerCatalog.js";
 import { createTrigger, parseCreateTriggerBody } from "../config/createTrigger.js";
+import { parsePatchTriggerBody, parsePutTriggerBody, updateTriggerDefinition, updateTriggerEnabled, projectRootFilterFromBody, } from "../config/updateTrigger.js";
+import { readTriggerAdapterStatus, } from "../config/triggerAdapterStatus.js";
 import { CatalogPathError, catalogPathErrorBody, resolveWritableCatalogRoot, } from "../config/catalogRelativePath.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
-import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
-import { getCatalogScanPaths } from "../config/browseCatalog.js";
-import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
 import { coerceTaskFile } from "../config/loadTask.js";
+async function enrichTriggerListItem(item, store) {
+    const adapter_status = await readTriggerAdapterStatus(item, store);
+    return { ...item, adapter_status };
+}
+function resolveListedTrigger(items, id, projectRootWire) {
+    if (projectRootWire) {
+        const found = items.find((item) => item.id === id && item.project_root === projectRootWire);
+        if (!found) {
+            return { error: `Trigger not found: ${id}`, status: 404 };
+        }
+        return found;
+    }
+    const matches = items.filter((item) => item.id === id);
+    if (matches.length === 0) {
+        return { error: `Trigger not found: ${id}`, status: 404 };
+    }
+    if (matches.length > 1) {
+        return {
+            error: `Trigger id is ambiguous across catalog roots: ${id}`,
+            status: 409,
+            project_roots: [...new Set(matches.map((m) => m.project_root))].sort((a, b) => a.localeCompare(b)),
+        };
+    }
+    return matches[0];
+}
 export async function handleTriggerRoutes(req, res, ctx) {
     const { cwd, manager, store, json, readJsonBody, readRawBody, auditLog } = ctx;
     const method = req.method ?? "GET";
@@ -78,12 +100,9 @@ export async function handleTriggerRoutes(req, res, ctx) {
         return true;
     }
     if (method === "GET" && pathname === "/api/triggers") {
-        const items = await loadCatalogTriggers(cwd, store);
-        if (items === undefined) {
-            json(res, 404, { error: "No Stageflow catalog found" });
-            return true;
-        }
-        json(res, 200, { triggers: items });
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const triggers = await Promise.all(items.map((item) => enrichTriggerListItem(item, store)));
+        json(res, 200, { triggers });
         return true;
     }
     const fireMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/fire$/);
@@ -107,8 +126,14 @@ export async function handleTriggerRoutes(req, res, ctx) {
             }
         }
         const id = decodeURIComponent(fireMatch[1] ?? "");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
         const callerId = callerIdFromRequestAuth();
-        const result = await fireTrigger(id, store, manager, { cwd, task });
+        const result = await fireTrigger(id, store, manager, {
+            cwd,
+            task,
+            ...(projectRootWire ? { project_root: projectRootWire } : {}),
+        });
         if (!result.ok) {
             writeAudit(auditLog, {
                 caller_id: callerId,
@@ -145,41 +170,45 @@ export async function handleTriggerRoutes(req, res, ctx) {
     if (method === "POST" && webhookMatch) {
         const id = decodeURIComponent(webhookMatch[1] ?? "");
         const callerId = callerIdFromRequestAuth();
-        const catalogCtx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
-        const scanPaths = await getCatalogScanPaths(catalogCtx);
-        const found = scanPaths
-            ? await findTriggerDefinition(scanPaths.triggerPaths, id)
-            : undefined;
-        if (!found) {
-            json(res, 404, { error: `Trigger not found: ${id}` });
-            return true;
-        }
-        const { definition: trigger } = found;
-        const config = trigger.event?.config;
-        const secretRef = typeof config?.secretRef === "string" ? config.secretRef : undefined;
-        const header = typeof config?.header === "string" ? config.header : undefined;
-        if (secretRef === undefined || header === undefined) {
-            json(res, 400, { error: "this trigger has no webhook signing configured" });
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const located = await findCatalogTrigger({
+            store,
+            bootCwd: cwd,
+            triggerId: id,
+            ...(projectRootWire ? { projectRootFilter: projectRootWire } : {}),
+        });
+        if (!located.ok) {
+            if (located.status === 409 && located.code === "ambiguous_trigger") {
+                json(res, located.status, {
+                    error: located.reason,
+                    code: located.code,
+                    project_roots: located.project_roots,
+                });
+            }
+            else if (located.status === 400 && located.code === "unknown_project_root") {
+                json(res, located.status, {
+                    error: located.reason,
+                    code: located.code,
+                });
+            }
+            else {
+                json(res, located.status, { error: located.reason });
+            }
             return true;
         }
-        const scheme = config?.scheme === "base64" ? "base64" : "hex";
-        let secret;
-        try {
-            secret = readSecretFromEnvOrFile(process.env, secretRef);
-        }
-        catch {
-            secret = undefined;
-        }
-        if (secret === undefined) {
+        const rawBody = await readRawBody(req);
+        const accepted = acceptWebhook({
+            trigger: located.match.definition,
+            rawBody,
+            headers: req.headers,
+            env: process.env,
+        });
+        if (accepted.kind === "not_configured") {
             json(res, 400, { error: "this trigger has no webhook signing configured" });
             return true;
         }
-        const rawBody = await readRawBody(req);
-        const headerValue = req.headers[header.toLowerCase()];
-        const signature = Array.isArray(headerValue) ? headerValue[0] : headerValue;
-        if (typeof signature !== "string" ||
-            signature.length === 0 ||
-            !verifyHmacSignature(rawBody, signature, secret, scheme)) {
+        if (accepted.kind === "bad_signature") {
             writeAudit(auditLog, {
                 caller_id: callerId,
                 surface: "webhook",
@@ -190,31 +219,19 @@ export async function handleTriggerRoutes(req, res, ctx) {
             json(res, 401, { error: "Invalid webhook signature" });
             return true;
         }
-        let payload;
-        try {
-            payload = rawBody.length === 0 ? {} : JSON.parse(rawBody.toString("utf8"));
-        }
-        catch {
-            json(res, 400, { error: "Invalid JSON body" });
+        if (accepted.kind === "bad_json") {
+            json(res, 400, { error: accepted.error });
             return true;
         }
-        if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
-            json(res, 400, { error: "Invalid JSON body: expected an object" });
-            return true;
-        }
-        const payloadRecord = payload;
-        if (!matchesEventFilter(trigger.event?.match, payloadRecord)) {
+        if (accepted.kind === "no_match") {
             json(res, 200, { fired: false });
             return true;
         }
-        const task = trigger.task === undefined
-            ? {
-                id: `${id}-webhook-${Date.now()}`,
-                goal: `Handle webhook event for trigger "${id}"`,
-                input: payloadRecord,
-            }
-            : undefined;
-        const result = await fireTrigger(id, store, manager, { cwd, task });
+        const result = await fireTrigger(id, store, manager, {
+            cwd,
+            task: accepted.task,
+            project_root: located.match.project_root,
+        });
         if (!result.ok) {
             writeAudit(auditLog, {
                 caller_id: callerId,
@@ -248,20 +265,130 @@ export async function handleTriggerRoutes(req, res, ctx) {
         });
         return true;
     }
+    const statusMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/status$/);
+    if (method === "GET" && statusMatch) {
+        const id = decodeURIComponent(statusMatch[1] ?? "");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const found = resolveListedTrigger(items, id, projectRootWire);
+        if ("error" in found) {
+            json(res, found.status, { error: found.error, ...(found.project_roots ? { project_roots: found.project_roots } : {}) });
+            return true;
+        }
+        const adapter_status = await readTriggerAdapterStatus(found, store);
+        json(res, 200, adapter_status);
+        return true;
+    }
+    const firesMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/fires$/);
+    if (method === "GET" && firesMatch) {
+        const id = decodeURIComponent(firesMatch[1] ?? "");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const found = resolveListedTrigger(items, id, projectRootWire);
+        if ("error" in found) {
+            json(res, found.status, { error: found.error, ...(found.project_roots ? { project_roots: found.project_roots } : {}) });
+            return true;
+        }
+        const fires = await store.listTriggerFires(triggerStoreId(found.project_root, found.id), 20);
+        json(res, 200, { fires });
+        return true;
+    }
+    const putMatch = pathname.match(/^\/api\/triggers\/([^/]+)$/);
+    if (method === "PUT" && putMatch) {
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return true;
+        }
+        const id = decodeURIComponent(putMatch[1] ?? "");
+        const parsed = parsePutTriggerBody(body, id);
+        if ("ok" in parsed) {
+            json(res, parsed.status, { error: parsed.error });
+            return true;
+        }
+        const projectRootFilter = projectRootFilterFromBody(body);
+        const callerId = callerIdFromRequestAuth();
+        const result = await updateTriggerDefinition(cwd, store, id, parsed, {
+            projectRootFilter,
+        });
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "rest",
+                action: "trigger_update",
+                outcome: "error",
+            });
+            json(res, result.status, { error: result.error });
+            return true;
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "rest",
+            action: "trigger_update",
+            outcome: "ok",
+        });
+        const enriched = await enrichTriggerListItem(result.trigger, store);
+        json(res, 200, enriched);
+        return true;
+    }
+    const patchMatch = pathname.match(/^\/api\/triggers\/([^/]+)$/);
+    if (method === "PATCH" && patchMatch) {
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return true;
+        }
+        const parsed = parsePatchTriggerBody(body);
+        if ("ok" in parsed) {
+            json(res, parsed.status, { error: parsed.error });
+            return true;
+        }
+        const id = decodeURIComponent(patchMatch[1] ?? "");
+        const projectRootFilter = projectRootFilterFromBody(body);
+        const callerId = callerIdFromRequestAuth();
+        const result = await updateTriggerEnabled(cwd, store, id, parsed.enabled, {
+            projectRootFilter,
+        });
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "rest",
+                action: "trigger_patch",
+                outcome: "error",
+            });
+            json(res, result.status, { error: result.error });
+            return true;
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "rest",
+            action: "trigger_patch",
+            outcome: "ok",
+        });
+        const enriched = await enrichTriggerListItem(result.trigger, store);
+        json(res, 200, enriched);
+        return true;
+    }
     const idMatch = pathname.match(/^\/api\/triggers\/([^/]+)$/);
     if (method === "GET" && idMatch) {
         const id = decodeURIComponent(idMatch[1] ?? "");
-        const items = await loadCatalogTriggers(cwd, store);
-        if (items === undefined) {
-            json(res, 404, { error: "No Stageflow catalog found" });
-            return true;
-        }
-        const found = items.find((item) => item.id === id);
-        if (!found) {
-            json(res, 404, { error: `Trigger not found: ${id}` });
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const found = resolveListedTrigger(items, id, projectRootWire);
+        if ("error" in found) {
+            json(res, found.status, { error: found.error, ...(found.project_roots ? { project_roots: found.project_roots } : {}) });
             return true;
         }
-        json(res, 200, found);
+        json(res, 200, await enrichTriggerListItem(found, store));
         return true;
     }
     return false;

package/dist/tools/readEmail.d.ts

@@ -6,12 +6,12 @@ export declare function createSearchEmailTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
+        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
-        isError?: undefined;
     } | {
         content: {
             type: "text";
@@ -31,12 +31,12 @@ export declare function createGetEmailTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
+        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
-        isError?: undefined;
     } | {
         content: {
             type: "text";
@@ -56,12 +56,12 @@ export declare function createDownloadEmailAttachmentTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
+        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
-        isError?: undefined;
     } | {
         content: {
             type: "text";

package/dist/tools/writeStageArtifact.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Custom Pi tool for writing factory stage artifact files under the run
+ * workspace. Paths are relative to
+ * `stages/<stageId>/attempts/<attempt>/artifacts/` and must resolve inside
+ * that directory.
+ *
+ * Parameter schemas use `typebox` (Pi's `defineTool` TSchema), not
+ * `@sinclair/typebox`. Unlike emit, this tool does not terminate the turn.
+ */
 import { Type } from "typebox";
 export type WriteStageArtifactOptions = {
     runWorkspaceDir: string;