stageflow 0.25.0 → 0.30.0

package/dist/config/catalogRelativePath.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { findCatalogRoot, resolveCatalogRoots } from "./resolveCatalogRoots.js";
+export class CatalogPathError extends Error {
+    code;
+    registered_roots;
+    constructor(message, code, registered_roots) {
+        super(message);
+        this.name = "CatalogPathError";
+        this.code = code;
+        this.registered_roots = registered_roots;
+    }
+}
+function realOrResolve(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+export function isInsideProjectRoot(projectRoot, candidate) {
+    const rootReal = realOrResolve(projectRoot);
+    const candidateReal = realOrResolve(candidate);
+    const rel = path.relative(rootReal, candidateReal);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * Network-surface path contract: refuse absolute paths; resolve relative under
+ * a selected catalog root; refuse `..` escape via realpath containment.
+ */
+export function resolveCatalogRelativePath(input) {
+    const field = input.fieldName ?? "path";
+    const registered = input.roots.map((r) => r.project_root);
+    if (path.isAbsolute(input.inputPath)) {
+        const rootsList = registered.length > 0
+            ? registered.join(", ")
+            : "(none — register a project or use seeded examples)";
+        throw new CatalogPathError(`Absolute ${field} is not allowed on network surfaces. Use a catalog-relative path under project_root (registered or seeded roots: ${rootsList}). Local CLI may pass absolute paths and auto-registers the project folder.`, "absolute_path_not_allowed", registered);
+    }
+    const root = selectCatalogRootForStart(input.roots, input.projectRoot);
+    const absolutePath = path.resolve(root.path, input.inputPath);
+    if (!isInsideProjectRoot(root.path, absolutePath)) {
+        throw new CatalogPathError(`${field} escapes project_root ${root.project_root}`, "path_outside_project_root", registered);
+    }
+    return {
+        absolutePath,
+        root,
+        relativePath: path.relative(root.path, absolutePath).replace(/\\/g, "/"),
+    };
+}
+export function catalogPathErrorBody(err) {
+    const body = {
+        error: err.message,
+        code: err.code,
+        registered_roots: err.registered_roots,
+    };
+    if (err.code === "absolute_path_not_allowed") {
+        body.hint =
+            "MCP/HTTP: relative path under project_root; CLI may pass absolute paths and auto-register.";
+    }
+    return body;
+}
+/**
+ * Pick the catalog root for start_run / POST /api/runs.
+ * Wire project_root (symbolic seeded id or absolute) maps to CatalogRoot.path
+ * (absolute store key). When omitted: sole root, or sole non-seeded root;
+ * otherwise require explicit — no invent.
+ */
+export function selectCatalogRootForStart(roots, projectRoot) {
+    const registered = roots.map((r) => r.project_root);
+    if (projectRoot !== undefined) {
+        const found = findCatalogRoot(roots, projectRoot);
+        if (found === undefined) {
+            throw new CatalogPathError(`Unknown project_root: ${projectRoot}`, "unknown_project_root", registered);
+        }
+        return found;
+    }
+    if (roots.length === 0) {
+        throw new CatalogPathError("No catalog roots configured; ensure a project_root first", "unknown_project_root", registered);
+    }
+    if (roots.length === 1) {
+        return roots[0];
+    }
+    const writable = roots.filter((r) => r.kind !== "seeded");
+    if (writable.length === 1) {
+        return writable[0];
+    }
+    throw new CatalogPathError("project_root is required when multiple catalog roots are configured", "unknown_project_root", registered);
+}
+/**
+ * Shared helper: resolveCatalogRoots → selectCatalogRootForStart.
+ * All network-surface start-input call sites use this to avoid the hand-copy sequence.
+ */
+export async function resolveCatalogStartInput(options, projectRoot) {
+    const roots = await resolveCatalogRoots(options);
+    const wireRoot = selectCatalogRootForStart(roots, projectRoot);
+    return { roots, wireRoot };
+}
+/**
+ * Like resolveCatalogStartInput but additionally refuses read-only roots.
+ * Used by write surfaces (POST /api/stages, POST /api/pipelines).
+ */
+export async function resolveWritableCatalogRoot(options, projectRoot) {
+    const { roots, wireRoot } = await resolveCatalogStartInput(options, projectRoot);
+    if (wireRoot.read_only) {
+        throw new CatalogPathError(`Catalog root ${wireRoot.project_root} is read-only`, "catalog_root_read_only", roots.map((r) => r.project_root));
+    }
+    return { roots, wireRoot };
+}
+/**
+ * Local CLI control: turn a cwd-resolved filesystem path into a catalog-relative
+ * wire path + project_root so the network surface does not see an absolute path.
+ */
+export function relativizeLocalPathForNetwork(cwd, inputPath) {
+    const abs = realOrResolve(path.resolve(cwd, inputPath));
+    const cwdAbs = realOrResolve(cwd);
+    const rel = path.relative(cwdAbs, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`Path ${abs} is outside CLI cwd ${cwdAbs}; run from the project root, pass a path under cwd, or use an inline definition on the Host API`);
+    }
+    return {
+        path: rel === "" ? "." : rel.replace(/\\/g, "/"),
+        project_root: cwdAbs,
+    };
+}

package/dist/config/configOrigin.d.ts

@@ -0,0 +1,27 @@
+export type ConfigOriginKind = "catalog" | "inline" | "workspace" | "seeded";
+export type ConfigOriginRecord = {
+    name: string;
+    origin: ConfigOriginKind;
+    path?: string;
+};
+export type BindingKindForOrigin = "repository" | "checkout" | "none";
+export type TrustWorkspaceDecision = {
+    allow: boolean;
+    origin: ConfigOriginKind;
+    code?: "untrusted_config_origin";
+    message?: string;
+};
+export declare function bindingKindForOrigin(kind: "repository" | "checkout" | "unbound" | "none" | undefined): BindingKindForOrigin;
+/**
+ * Decide whether workspace-sourced config (.mcp.json / skills under checkout)
+ * is permitted. Default: refuse for repository bindings; allow for checkout;
+ * host trust_workspace_config can allowlisted roots.
+ */
+export declare function decideWorkspaceConfigTrust(options: {
+    bindingKind: BindingKindForOrigin;
+    projectRoot: string;
+    trustWorkspaceConfig?: string[];
+    source: "workspace" | "catalog" | "inline" | "seeded";
+}): TrustWorkspaceDecision;
+export declare function skillOriginKind(scope: "user" | "project" | "temporary", filePath: string, checkoutRoot: string | undefined): ConfigOriginKind;
+export declare function catalogOrSeededOrigin(projectRoot: string | undefined, seededRoots: readonly string[]): ConfigOriginKind;

package/dist/config/configOrigin.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+export function bindingKindForOrigin(kind) {
+    if (kind === "repository" || kind === "checkout")
+        return kind;
+    return "none";
+}
+/**
+ * Decide whether workspace-sourced config (.mcp.json / skills under checkout)
+ * is permitted. Default: refuse for repository bindings; allow for checkout;
+ * host trust_workspace_config can allowlisted roots.
+ */
+export function decideWorkspaceConfigTrust(options) {
+    if (options.source !== "workspace") {
+        return { allow: true, origin: options.source };
+    }
+    const trusted = (options.trustWorkspaceConfig ?? []).some((root) => root === options.projectRoot);
+    if (trusted) {
+        return { allow: true, origin: "workspace" };
+    }
+    if (options.bindingKind === "checkout") {
+        return { allow: true, origin: "workspace" };
+    }
+    if (options.bindingKind === "repository") {
+        return {
+            allow: false,
+            origin: "workspace",
+            code: "untrusted_config_origin",
+            message: `Workspace config is not trusted for repository binding at ${options.projectRoot}; set trust_workspace_config in HostConfig to allowlist this root`,
+        };
+    }
+    return {
+        allow: false,
+        origin: "workspace",
+        code: "untrusted_config_origin",
+        message: `Workspace config is not trusted at ${options.projectRoot}`,
+    };
+}
+function isUnderRoot(candidate, root) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(candidate);
+    const rel = path.relative(resolvedRoot, resolved);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+export function skillOriginKind(scope, filePath, checkoutRoot) {
+    if (scope === "temporary")
+        return "inline";
+    if (scope === "project" &&
+        checkoutRoot !== undefined &&
+        isUnderRoot(filePath, checkoutRoot)) {
+        return "workspace";
+    }
+    return "catalog";
+}
+export function catalogOrSeededOrigin(projectRoot, seededRoots) {
+    if (projectRoot !== undefined && seededRoots.some((root) => root === projectRoot)) {
+        return "seeded";
+    }
+    return "catalog";
+}

package/dist/config/createTrigger.d.ts

@@ -0,0 +1,27 @@
+import type { TriggerEvent, TriggerSchedule } from "../types/trigger.js";
+import type { TriggerListItem } from "./triggerCatalog.js";
+export type CreateTriggerInput = {
+    directory: string;
+    id: string;
+    pipeline: string;
+    task?: string;
+    kind: "manual" | "schedule" | "event";
+    schedule?: TriggerSchedule;
+    event?: TriggerEvent;
+    enabled?: boolean;
+};
+export type CreateTriggerParseError = {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export type CreateTriggerResult = {
+    ok: true;
+    trigger: TriggerListItem;
+} | {
+    ok: false;
+    status: 400 | 409 | 422 | 500;
+    error: string;
+};
+export declare function parseCreateTriggerBody(body: unknown): CreateTriggerInput | CreateTriggerParseError;
+export declare function createTrigger(rawProjectRoot: string, input: CreateTriggerInput): Promise<CreateTriggerResult>;

package/dist/config/createTrigger.js

@@ -0,0 +1,232 @@
+import { mkdir, realpath, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Cron } from "croner";
+import { stringify as stringifyYaml } from "yaml";
+import { STAGE_ID_PATTERN } from "./createStage.js";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { loadTriggerOutcome } from "./loadTrigger.js";
+import { collectPipelineIdsFromPaths, collectTaskIdsFromPaths } from "./validateCatalog.js";
+import { findCatalogPathById } from "../runtime/triggerCatalog.js";
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateTriggerId(id) {
+    if (id.length === 0 || id.length > 64) {
+        return "id must be 1-64 characters";
+    }
+    if (!STAGE_ID_PATTERN.test(id)) {
+        return "id must be lowercase kebab-case";
+    }
+    return null;
+}
+function parseScheduleField(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!isPlainObject(raw)) {
+        return { ok: false, message: "schedule must be an object" };
+    }
+    if (typeof raw.cron !== "string" || raw.cron.trim().length === 0) {
+        return { ok: false, message: "schedule.cron is required" };
+    }
+    if (raw.timezone !== undefined && typeof raw.timezone !== "string") {
+        return { ok: false, message: "schedule.timezone must be a string" };
+    }
+    return {
+        ok: true,
+        value: {
+            cron: raw.cron,
+            ...(typeof raw.timezone === "string" ? { timezone: raw.timezone } : {}),
+        },
+    };
+}
+function parseEventField(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!isPlainObject(raw)) {
+        return { ok: false, message: "event must be an object" };
+    }
+    if (typeof raw.source !== "string" || raw.source.trim().length === 0) {
+        return { ok: false, message: "event.source is required" };
+    }
+    if (raw.match !== undefined && !isPlainObject(raw.match)) {
+        return { ok: false, message: "event.match must be an object" };
+    }
+    if (raw.config !== undefined && !isPlainObject(raw.config)) {
+        return { ok: false, message: "event.config must be an object" };
+    }
+    return {
+        ok: true,
+        value: {
+            source: raw.source,
+            ...(isPlainObject(raw.match) ? { match: raw.match } : {}),
+            ...(isPlainObject(raw.config) ? { config: raw.config } : {}),
+        },
+    };
+}
+export function parseCreateTriggerBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "Request body must be an object" };
+    }
+    if (typeof body.directory !== "string" || !body.directory.trim()) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    const directory = body.directory.trim().replace(/\\/g, "/");
+    if (typeof body.id !== "string") {
+        return { ok: false, status: 400, error: "id is required" };
+    }
+    const idError = validateTriggerId(body.id);
+    if (idError) {
+        return { ok: false, status: 400, error: idError };
+    }
+    if (typeof body.pipeline !== "string" || !body.pipeline.trim()) {
+        return { ok: false, status: 400, error: "pipeline is required" };
+    }
+    if (body.task !== undefined && (typeof body.task !== "string" || !body.task.trim())) {
+        return { ok: false, status: 400, error: "task must be a non-empty string" };
+    }
+    if (body.kind !== "manual" && body.kind !== "schedule" && body.kind !== "event") {
+        return {
+            ok: false,
+            status: 400,
+            error: "kind must be one of: manual, schedule, event",
+        };
+    }
+    const schedule = parseScheduleField(body.schedule);
+    if (!schedule.ok) {
+        return { ok: false, status: 400, error: schedule.message };
+    }
+    const event = parseEventField(body.event);
+    if (!event.ok) {
+        return { ok: false, status: 400, error: event.message };
+    }
+    if (body.kind === "schedule" && schedule.value === undefined) {
+        return { ok: false, status: 400, error: "schedule.cron is required for kind=schedule" };
+    }
+    if (body.kind === "event" && event.value === undefined) {
+        return { ok: false, status: 400, error: "event.source is required for kind=event" };
+    }
+    if (body.enabled !== undefined && typeof body.enabled !== "boolean") {
+        return { ok: false, status: 400, error: "enabled must be a boolean" };
+    }
+    return {
+        directory,
+        id: body.id,
+        pipeline: body.pipeline,
+        ...(typeof body.task === "string" ? { task: body.task } : {}),
+        kind: body.kind,
+        ...(schedule.value !== undefined ? { schedule: schedule.value } : {}),
+        ...(event.value !== undefined ? { event: event.value } : {}),
+        ...(body.enabled !== undefined ? { enabled: body.enabled } : {}),
+    };
+}
+function resolveDirectory(projectRoot, directory) {
+    const absDirectory = path.resolve(projectRoot, directory);
+    const rel = path.relative(projectRoot, absDirectory);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return null;
+    }
+    return absDirectory;
+}
+function triggerInputToYaml(input, enabled) {
+    const doc = {
+        id: input.id,
+        pipeline: input.pipeline,
+        ...(input.task !== undefined ? { task: input.task } : {}),
+        kind: input.kind,
+    };
+    if (input.kind === "schedule" && input.schedule) {
+        doc.schedule = input.schedule;
+    }
+    if (input.kind === "event" && input.event) {
+        doc.event = input.event;
+    }
+    doc.enabled = enabled;
+    return stringifyYaml(doc);
+}
+export async function createTrigger(rawProjectRoot, input) {
+    const idError = validateTriggerId(input.id);
+    if (idError) {
+        return { ok: false, status: 400, error: idError };
+    }
+    const projectRoot = await realpath(rawProjectRoot).catch(() => rawProjectRoot);
+    const directory = resolveDirectory(projectRoot, input.directory);
+    if (!directory) {
+        return { ok: false, status: 400, error: "directory must be inside the project root" };
+    }
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(projectRoot));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return {
+            ok: false,
+            status: 422,
+            error: "Catalog manifest not found; cannot validate trigger references",
+        };
+    }
+    const collisionPath = await findCatalogPathById(scanPaths.triggerPaths, input.id);
+    if (collisionPath) {
+        return {
+            ok: false,
+            status: 409,
+            error: `Trigger id already exists (${path.relative(projectRoot, collisionPath).replace(/\\/g, "/")})`,
+        };
+    }
+    const pipelineIds = await collectPipelineIdsFromPaths(scanPaths.pipelinePaths);
+    if (!pipelineIds.has(input.pipeline)) {
+        return {
+            ok: false,
+            status: 422,
+            error: `Trigger references unknown pipeline "${input.pipeline}"`,
+        };
+    }
+    if (input.task !== undefined) {
+        const taskIds = await collectTaskIdsFromPaths(scanPaths.taskPaths);
+        if (!taskIds.has(input.task)) {
+            return {
+                ok: false,
+                status: 422,
+                error: `Trigger references unknown task "${input.task}"`,
+            };
+        }
+    }
+    if (input.kind === "schedule") {
+        if (!input.schedule) {
+            return { ok: false, status: 422, error: "schedule.cron is required for kind=schedule" };
+        }
+        try {
+            new Cron(input.schedule.cron, input.schedule.timezone !== undefined ? { timezone: input.schedule.timezone } : {});
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { ok: false, status: 422, error: `Invalid schedule.cron: ${message}` };
+        }
+    }
+    const filePath = path.join(directory, `${input.id}.trigger.yaml`);
+    const relPath = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+    const enabled = input.enabled ?? true;
+    try {
+        await mkdir(directory, { recursive: true });
+        await writeFile(filePath, triggerInputToYaml(input, enabled), "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 500, error: message };
+    }
+    const loadOutcome = await loadTriggerOutcome(filePath);
+    if (!loadOutcome.ok) {
+        await unlink(filePath).catch(() => { });
+        return {
+            ok: false,
+            status: 500,
+            error: loadOutcome.issues[0]?.message ?? "Failed to load created trigger",
+        };
+    }
+    return {
+        ok: true,
+        trigger: {
+            ...loadOutcome.value,
+            definition_ref: relPath,
+        },
+    };
+}

package/dist/config/draftPackage.d.ts

@@ -0,0 +1,117 @@
+import type { PipelineListing } from "./listConfig.js";
+import { type ValidationFinding, type ValidationResult } from "./validateCatalog.js";
+export type DraftStageArtifact = {
+    path: string;
+    body: Record<string, unknown>;
+};
+export type DraftPackage = {
+    pipeline: {
+        id: string;
+        stages: Array<Record<string, unknown>>;
+        agent?: unknown;
+        model?: unknown;
+        schemas?: unknown;
+        requires?: unknown;
+    };
+    stages?: DraftStageArtifact[];
+    task?: {
+        filename: string;
+        body: Record<string, unknown>;
+    };
+};
+export type ValidateDraftPackageOptions = {
+    cwd?: string;
+    projectRoot?: string;
+    strict?: boolean;
+};
+export type OverwriteDraftPackageInput = {
+    directory: string;
+    draft: DraftPackage;
+    pipelineFilename?: string;
+    /**
+     * Escape hatch for Workshop “Save invalid anyway” (ticket 07).
+     * When true, skips the validate gate and writes the package as-is.
+     */
+    allowInvalid?: boolean;
+};
+export type CreateDraftPackageInput = OverwriteDraftPackageInput;
+export type DraftPackageWriteResult = {
+    ok: true;
+    pipeline: PipelineListing;
+    pipelinePath: string;
+    stagePaths: string[];
+    taskPath?: string;
+} | {
+    ok: false;
+    status: 400 | 404 | 409 | 422 | 500;
+    error: string;
+    findings?: ValidationFinding[];
+};
+export type OverwriteDraftPackageResult = DraftPackageWriteResult;
+export type CreateDraftPackageResult = DraftPackageWriteResult;
+export type DraftPackageDestination = {
+    directory: string;
+    pipelineFilename: string;
+};
+export type LoadDraftPackageOptions = {
+    /** When set, attach this task file into the draft. Otherwise task stays absent. */
+    taskPath?: string;
+};
+export type LoadDraftPackageResult = {
+    ok: true;
+    draft: DraftPackage;
+    destination: DraftPackageDestination;
+    pipelinePath: string;
+    taskPath?: string;
+} | {
+    ok: false;
+    status: 400 | 404;
+    error: string;
+};
+export type DraftTaskArtifact = {
+    filename: string;
+    body: Record<string, unknown>;
+};
+export type LoadTaskArtifactResult = {
+    ok: true;
+    task: DraftTaskArtifact;
+    taskPath: string;
+} | {
+    ok: false;
+    status: 400 | 404;
+    error: string;
+};
+export declare function validateDraftPackage(draft: DraftPackage, options?: ValidateDraftPackageOptions): Promise<ValidationResult>;
+export declare function overwriteDraftPackage(projectRoot: string, input: OverwriteDraftPackageInput): Promise<OverwriteDraftPackageResult>;
+export declare function createDraftPackage(projectRoot: string, input: CreateDraftPackageInput): Promise<CreateDraftPackageResult>;
+export declare function parseDraftPackageBody(body: unknown): DraftPackage | {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export declare function parseCreateDraftPackageBody(body: unknown): CreateDraftPackageInput | {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export declare const parseOverwriteDraftPackageBody: typeof parseCreateDraftPackageBody;
+export type OpenDraftPackageInput = {
+    path: string;
+    taskPath?: string;
+};
+export declare function parseOpenDraftPackageBody(body: unknown): OpenDraftPackageInput | {
+    ok: false;
+    status: 400;
+    error: string;
+};
+/** Load a catalog task file into a draft task artifact (attach without reloading the pipeline). */
+export declare function loadTaskArtifact(projectRoot: string, taskRelPath: string): Promise<LoadTaskArtifactResult>;
+export type AttachTaskBody = {
+    taskPath: string;
+};
+export declare function parseAttachTaskBody(body: unknown): AttachTaskBody | {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export declare function loadDraftPackage(projectRoot: string, pipelineRelPath: string, options?: LoadDraftPackageOptions): Promise<LoadDraftPackageResult>;