stageflow 0.25.0 → 0.30.0

package/dist/config/seededCatalog.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+/** Symbolic wire id for the packaged examples catalog root. */
+export const SEEDED_EXAMPLES_ID = "examples";
+/**
+ * Absolute path to packaged `examples/` when present next to the package root.
+ * Does not git-init; callers build CatalogContext with fixed projectRoot + manifest.
+ */
+export function resolveSeededExamplesPath(fromUrl = import.meta.url) {
+    const here = path.dirname(fileURLToPath(fromUrl));
+    const candidates = [
+        path.resolve(here, "../../examples"),
+        path.resolve(here, "../../../examples"),
+        path.resolve(process.cwd(), "examples"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(path.join(candidate, "README.md"))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+export function defaultSeededRoots() {
+    const examples = resolveSeededExamplesPath();
+    if (examples === undefined)
+        return [];
+    return [{ id: SEEDED_EXAMPLES_ID, path: examples }];
+}

package/dist/config/stageBrowser.d.ts

@@ -0,0 +1,12 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+import { type ToolRequirement } from "./toolRequires.js";
+export declare const BROWSER_TOOL_NAME = "agent-browser";
+export declare function parseStageBrowser(raw: unknown, label: string, stageId?: string): LoadOutcome<StageBrowserConfig | undefined>;
+export declare function withBrowserRequires(stage: {
+    browser?: StageBrowserConfig;
+    requires?: ToolRequirement[];
+}, ctx: {
+    pipelineId: string;
+    stageId: string;
+}): LoadOutcome<ToolRequirement[] | undefined>;

package/dist/config/stageBrowser.js

@@ -0,0 +1,118 @@
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { mergeToolRequires } from "./toolRequires.js";
+export const BROWSER_TOOL_NAME = "agent-browser";
+const ALLOWED_KEYS = new Set(["profile", "headed", "allow_domains", "login_url", "check"]);
+const CHECK_KEYS = new Set(["url", "logged_in_url", "logged_out_url"]);
+const REJECTED_KEYS = new Set(["path", "scope", "secret"]);
+const PROFILE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const DOMAIN = /^(\*\.)?[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(label, stageId, message) {
+    return loadFailure([
+        {
+            code: "stage.invalid_browser",
+            message: `Invalid stage ${label}: browser ${message}`,
+            category: "stage",
+            ...(stageId !== undefined ? { stageId } : {}),
+        },
+    ]);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function parseCheck(raw, label, stageId) {
+    if (!isPlainObject(raw)) {
+        return fail(label, stageId, "check must be an object");
+    }
+    for (const key of Object.keys(raw)) {
+        if (!CHECK_KEYS.has(key)) {
+            return fail(label, stageId, `check unknown key "${key}" (allowed: url, logged_in_url, logged_out_url)`);
+        }
+    }
+    if (!nonEmptyString(raw.url)) {
+        return fail(label, stageId, "check.url must be a non-empty string");
+    }
+    const check = {
+        url: raw.url.trim(),
+    };
+    if (raw.logged_in_url !== undefined) {
+        if (!nonEmptyString(raw.logged_in_url)) {
+            return fail(label, stageId, "check.logged_in_url must be a non-empty string");
+        }
+        check.logged_in_url = raw.logged_in_url.trim();
+    }
+    if (raw.logged_out_url !== undefined) {
+        const list = Array.isArray(raw.logged_out_url)
+            ? raw.logged_out_url
+            : [raw.logged_out_url];
+        if (list.length === 0 || !list.every(nonEmptyString)) {
+            return fail(label, stageId, "check.logged_out_url must be a non-empty string or a non-empty list of strings");
+        }
+        const trimmed = list.map((item) => item.trim());
+        check.logged_out_url = Array.isArray(raw.logged_out_url)
+            ? trimmed
+            : trimmed[0];
+    }
+    return loadSuccess(check);
+}
+export function parseStageBrowser(raw, label, stageId) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!isPlainObject(raw)) {
+        return fail(label, stageId, "must be an object");
+    }
+    for (const key of Object.keys(raw)) {
+        if (REJECTED_KEYS.has(key)) {
+            return fail(label, stageId, `"${key}" is not allowed (the Host chooses profile location and scope)`);
+        }
+        if (!ALLOWED_KEYS.has(key)) {
+            return fail(label, stageId, `unknown key "${key}" (allowed: profile, headed, allow_domains, login_url, check)`);
+        }
+    }
+    const browser = {};
+    if (raw.profile !== undefined) {
+        if (typeof raw.profile !== "string" || !PROFILE_NAME.test(raw.profile)) {
+            return fail(label, stageId, "profile must be 1-64 characters of letters, digits, dash, or underscore");
+        }
+        browser.profile = raw.profile;
+    }
+    if (raw.headed !== undefined) {
+        if (typeof raw.headed !== "boolean") {
+            return fail(label, stageId, "headed must be a boolean");
+        }
+        browser.headed = raw.headed;
+    }
+    if (raw.allow_domains !== undefined) {
+        if (!Array.isArray(raw.allow_domains) || raw.allow_domains.length === 0) {
+            return fail(label, stageId, "allow_domains must be a non-empty array of domain names");
+        }
+        const domains = [];
+        for (const item of raw.allow_domains) {
+            if (typeof item !== "string" || !DOMAIN.test(item.trim())) {
+                return fail(label, stageId, `allow_domains entry ${JSON.stringify(item)} must be a bare domain such as "example.com" or "*.example.com" (no scheme, port, or path)`);
+            }
+            domains.push(item.trim());
+        }
+        browser.allow_domains = domains;
+    }
+    if (raw.login_url !== undefined) {
+        if (!nonEmptyString(raw.login_url)) {
+            return fail(label, stageId, "login_url must be a non-empty string");
+        }
+        browser.login_url = raw.login_url.trim();
+    }
+    if (raw.check !== undefined) {
+        const check = parseCheck(raw.check, label, stageId);
+        if (!check.ok)
+            return check;
+        browser.check = check.value;
+    }
+    return loadSuccess(browser);
+}
+export function withBrowserRequires(stage, ctx) {
+    if (stage.browser === undefined)
+        return loadSuccess(stage.requires);
+    return mergeToolRequires([stage.requires, [{ tool: BROWSER_TOOL_NAME }]], { pipelineId: ctx.pipelineId, label: `stage "${ctx.stageId}"` });
+}

package/dist/config/toolRequires.d.ts

@@ -0,0 +1,24 @@
+import { type LoadOutcome } from "./loadOutcome.js";
+export type ToolRequirement = {
+    tool: string;
+    version?: string;
+};
+export declare function parseToolRequires(raw: unknown, label: string, options: {
+    code: "pipeline.invalid_requires" | "stage.invalid_requires";
+    category: "pipeline" | "stage";
+    pipelineId?: string;
+    stageId?: string;
+}): LoadOutcome<ToolRequirement[] | undefined>;
+/**
+ * Merge requirement lists: same tool → intersect version ranges (stricter).
+ * Non-intersecting ranges fail with pipeline.requires_conflict.
+ */
+export declare function mergeToolRequires(lists: Array<readonly ToolRequirement[] | undefined>, ctx: {
+    pipelineId: string;
+    label?: string;
+}): LoadOutcome<ToolRequirement[]>;
+export declare function collectEffectiveRequires(options: {
+    pipelineRequires?: readonly ToolRequirement[];
+    stageRequires: Array<readonly ToolRequirement[] | undefined>;
+    pipelineId: string;
+}): LoadOutcome<ToolRequirement[]>;

package/dist/config/toolRequires.js

@@ -0,0 +1,115 @@
+import semver from "semver";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+const ALLOWED_KEYS = new Set(["tool", "version"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiresIssue(options, message) {
+    if (options.category === "pipeline") {
+        return {
+            code: options.code,
+            message,
+            category: "pipeline",
+            ...(options.pipelineId !== undefined
+                ? { pipelineId: options.pipelineId }
+                : {}),
+            ...(options.stageId !== undefined ? { stageId: options.stageId } : {}),
+        };
+    }
+    return {
+        code: options.code,
+        message,
+        category: "stage",
+        ...(options.stageId !== undefined ? { stageId: options.stageId } : {}),
+    };
+}
+export function parseToolRequires(raw, label, options) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw)) {
+        return loadFailure([
+            requiresIssue(options, `Invalid ${label}: requires must be an array of { tool, version? }`),
+        ]);
+    }
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (!isPlainObject(item)) {
+            return loadFailure([
+                requiresIssue(options, `Invalid ${label}: requires[${i}] must be an object`),
+            ]);
+        }
+        for (const key of Object.keys(item)) {
+            if (!ALLOWED_KEYS.has(key)) {
+                return loadFailure([
+                    requiresIssue(options, `Invalid ${label}: requires[${i}] unknown key "${key}" (allowed: tool, version)`),
+                ]);
+            }
+        }
+        if (typeof item.tool !== "string" || item.tool.trim() === "") {
+            return loadFailure([
+                requiresIssue(options, `Invalid ${label}: requires[${i}].tool must be a non-empty string`),
+            ]);
+        }
+        const tool = item.tool.trim();
+        if (item.version !== undefined) {
+            if (typeof item.version !== "string" || item.version.trim() === "") {
+                return loadFailure([
+                    requiresIssue(options, `Invalid ${label}: requires[${i}].version must be a non-empty semver range string`),
+                ]);
+            }
+            const range = item.version.trim();
+            if (!semver.validRange(range)) {
+                return loadFailure([
+                    requiresIssue(options, `Invalid ${label}: requires[${i}].version "${range}" is not a valid semver range`),
+                ]);
+            }
+            out.push({ tool, version: range });
+        }
+        else {
+            out.push({ tool });
+        }
+    }
+    return loadSuccess(out);
+}
+/**
+ * Merge requirement lists: same tool → intersect version ranges (stricter).
+ * Non-intersecting ranges fail with pipeline.requires_conflict.
+ */
+export function mergeToolRequires(lists, ctx) {
+    const byTool = new Map();
+    for (const list of lists) {
+        if (!list)
+            continue;
+        for (const req of list) {
+            const prior = byTool.get(req.tool);
+            if (!byTool.has(req.tool)) {
+                byTool.set(req.tool, req.version);
+                continue;
+            }
+            if (prior === undefined && req.version === undefined)
+                continue;
+            if (prior === undefined) {
+                byTool.set(req.tool, req.version);
+                continue;
+            }
+            if (req.version === undefined)
+                continue;
+            if (!semver.intersects(prior, req.version)) {
+                return loadFailure([
+                    {
+                        code: "pipeline.requires_conflict",
+                        message: `Pipeline ${ctx.pipelineId}${ctx.label ? ` (${ctx.label})` : ""}: tool "${req.tool}" has non-intersecting version ranges "${prior}" and "${req.version}"`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+            byTool.set(req.tool, `${prior} ${req.version}`);
+        }
+    }
+    return loadSuccess([...byTool.entries()].map(([tool, version]) => version !== undefined ? { tool, version } : { tool }));
+}
+export function collectEffectiveRequires(options) {
+    return mergeToolRequires([options.pipelineRequires, ...options.stageRequires], { pipelineId: options.pipelineId });
+}

package/dist/config/triggerCatalog.d.ts

@@ -0,0 +1,10 @@
+import type { RunStore } from "../runstore/port.js";
+import type { TriggerFile } from "../types/trigger.js";
+export type TriggerListItem = TriggerFile & {
+    definition_ref: string;
+    last_fired_at?: string;
+    last_run_id?: string;
+    next_run_at?: string;
+};
+/** Catalog-authoritative trigger list, overlaid with each trigger's store-recorded fire state (if any). */
+export declare function loadCatalogTriggers(cwd: string, store: RunStore): Promise<TriggerListItem[] | undefined>;

package/dist/config/triggerCatalog.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { loadTriggerOutcome } from "./loadTrigger.js";
+/** Catalog-authoritative trigger list, overlaid with each trigger's store-recorded fire state (if any). */
+export async function loadCatalogTriggers(cwd, store) {
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths)
+        return undefined;
+    const projectRoot = ctx.projectRoot ?? undefined;
+    const items = [];
+    for (const filePath of scanPaths.triggerPaths) {
+        const outcome = await loadTriggerOutcome(filePath);
+        if (!outcome.ok)
+            continue;
+        const definitionRef = projectRoot !== undefined
+            ? path.relative(projectRoot, filePath).replace(/\\/g, "/")
+            : filePath;
+        const record = await store.getTrigger(outcome.value.id);
+        items.push({
+            ...outcome.value,
+            definition_ref: definitionRef,
+            ...(record?.last_fired_at !== undefined
+                ? { last_fired_at: record.last_fired_at }
+                : {}),
+            ...(record?.last_run_id !== undefined
+                ? { last_run_id: record.last_run_id }
+                : {}),
+            ...(record?.next_run_at !== undefined
+                ? { next_run_at: record.next_run_at }
+                : {}),
+        });
+    }
+    return items.sort((a, b) => a.id.localeCompare(b.id));
+}

package/dist/config/validateCatalog.d.ts

@@ -1,8 +1,9 @@
 import type { InlinePipelineDefinition, LoadedPipeline } from "../types/pipeline.js";
+import type { TriggerFile } from "../types/trigger.js";
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
-export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml";
+export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task" | "trigger";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_browser" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;
@@ -12,13 +13,14 @@ export type ValidationFinding = {
     pipelineId?: string;
     stageId?: string;
 };
-export type ValidationScope = "full" | "pipeline" | "task";
+export type ValidationScope = "full" | "pipeline" | "task" | "trigger";
 export type ValidateCatalogOptions = {
     cwd?: string;
     projectRoot?: string;
     scope: ValidationScope;
     pipeline?: string;
     task?: string;
+    trigger?: string;
     strict?: boolean;
 };
 export type ValidationResult = {
@@ -35,6 +37,10 @@ export declare function effectiveSeverity(finding: ValidationFinding, strict: bo
 export declare function buildValidationResult(scope: ValidationScope, findings: ValidationFinding[], strict: boolean): ValidationResult;
 export declare function findingsFromLoadIssues(cwd: string, absPath: string, issues: LoadIssue[]): ValidationFinding[];
 export declare function findingStageIdFilenameMismatch(cwd: string, absPath: string, fileStem: string, declaredId: string): ValidationFinding;
+/** Parent readdir case check — warn by default; error under --strict. */
+export declare function findingPathCaseMismatch(cwd: string, referencedPath: string): Promise<ValidationFinding | null>;
+export declare function collectAbsolutePathCandidates(text: string): string[];
+export declare function isPathUnderStageflowHome(candidate: string, home: string): boolean;
 export type ValidatePipelineOptions = {
     cwd?: string;
     projectRoot?: string;
@@ -55,4 +61,12 @@ export declare function loadPipelineValidated(nameOrPath: string | InlinePipelin
     projectRoot?: string;
     validateStages?: boolean;
 }): Promise<LoadPipelineValidatedResult>;
+export declare function collectPipelineIdsFromPaths(pipelinePaths: string[]): Promise<Map<string, string[]>>;
+export declare function collectTaskIdsFromPaths(taskPaths: string[]): Promise<Set<string>>;
+export type TriggerCatalogRefs = {
+    pipelineIds: ReadonlySet<string>;
+    taskIds: ReadonlySet<string>;
+};
+/** Confirms a trigger's `pipeline`/`task` refs resolve against known catalog ids. */
+export declare function findingsForTriggerRefs(cwd: string, absPath: string, trigger: TriggerFile, refs: TriggerCatalogRefs): ValidationFinding[];
 export declare function validateCatalog(options: ValidateCatalogOptions): Promise<ValidationResult>;