stageflow 0.25.0 → 0.30.0

package/dist/config/draftPackage.js

@@ -0,0 +1,550 @@
+import { access, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { loadPipelineOutcome } from "./loadPipeline.js";
+import { parseTaskFile } from "./loadTask.js";
+import { stringifyTargetYaml } from "./printTargetYaml.js";
+import { readYamlObject } from "./readYamlObject.js";
+import { buildValidationResult, findingsFromLoadIssues, loadPipelineValidated, validatePipeline, } from "./validateCatalog.js";
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeStageRelPath(stagePath) {
+    return stagePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function pipelineHasExternalUses(pipeline) {
+    return pipeline.stages.some((stage) => typeof stage.uses === "string" && stage.uses.trim().length > 0);
+}
+function pipelineDocument(pipeline) {
+    const doc = {
+        id: pipeline.id,
+        stages: pipeline.stages,
+    };
+    if (pipeline.agent !== undefined)
+        doc.agent = pipeline.agent;
+    if (pipeline.model !== undefined)
+        doc.model = pipeline.model;
+    if (pipeline.schemas !== undefined)
+        doc.schemas = pipeline.schemas;
+    if (pipeline.requires !== undefined)
+        doc.requires = pipeline.requires;
+    return doc;
+}
+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;
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function materializeDraft(draft, dir, pipelineFilename) {
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, pipelineFilename), stringifyTargetYaml(pipelineDocument(draft.pipeline)), "utf8");
+    for (const stage of draft.stages ?? []) {
+        const rel = normalizeStageRelPath(stage.path);
+        const stagePath = path.join(dir, rel);
+        await mkdir(path.dirname(stagePath), { recursive: true });
+        await writeFile(stagePath, stringifyTargetYaml(stage.body), "utf8");
+    }
+    if (draft.task) {
+        await writeFile(path.join(dir, path.basename(draft.task.filename)), stringifyTargetYaml(draft.task.body), "utf8");
+    }
+}
+function collectTaskFindings(cwd, draft) {
+    if (!draft.task)
+        return [];
+    const outcome = parseTaskFile(draft.task.body, `task ${draft.task.filename}`);
+    if (outcome.ok)
+        return [];
+    const absPath = path.resolve(cwd, path.basename(draft.task.filename));
+    return findingsFromLoadIssues(cwd, absPath, outcome.issues);
+}
+export async function validateDraftPackage(draft, options = {}) {
+    if (!isPlainObject(draft) || !isPlainObject(draft.pipeline)) {
+        return buildValidationResult("pipeline", [
+            {
+                severity: "error",
+                code: "pipeline.invalid_shape",
+                path: "<draft>",
+                message: "draft package must include a pipeline object",
+                category: "pipeline",
+            },
+        ], options.strict ?? false);
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const strict = options.strict ?? false;
+    const findings = [];
+    const needsMaterialize = pipelineHasExternalUses(draft.pipeline) ||
+        (draft.stages !== undefined && draft.stages.length > 0);
+    if (needsMaterialize) {
+        const tempRoot = await mkdtemp(path.join(tmpdir(), "sf-draft-"));
+        try {
+            const pipelineFilename = `${draft.pipeline.id}.pipeline.yaml`;
+            await materializeDraft(draft, tempRoot, pipelineFilename);
+            const pipelineResult = await validatePipeline(pipelineFilename, {
+                cwd: tempRoot,
+                projectRoot: tempRoot,
+                validateStages: true,
+                strict,
+            });
+            findings.push(...pipelineResult.findings);
+        }
+        finally {
+            await rm(tempRoot, { recursive: true, force: true });
+        }
+    }
+    else {
+        const inline = {
+            id: draft.pipeline.id,
+            stages: draft.pipeline.stages,
+            ...(draft.pipeline.agent !== undefined ? { agent: draft.pipeline.agent } : {}),
+            ...(draft.pipeline.model !== undefined ? { model: draft.pipeline.model } : {}),
+            ...(draft.pipeline.schemas !== undefined ? { schemas: draft.pipeline.schemas } : {}),
+            ...(draft.pipeline.requires !== undefined
+                ? { requires: draft.pipeline.requires }
+                : {}),
+        };
+        const result = await loadPipelineValidated(inline, {
+            cwd,
+            projectRoot,
+            validateStages: true,
+        });
+        findings.push(...result.findings);
+    }
+    findings.push(...collectTaskFindings(cwd, draft));
+    return buildValidationResult("pipeline", findings, strict);
+}
+function buildPipelineListing(projectRoot, relPath, loaded) {
+    return {
+        path: relPath,
+        id: loaded.pipeline.id,
+        stages: loaded.stages.map((stage) => {
+            const source = loaded.stageSources?.[stage.id];
+            const listing = {
+                id: stage.id,
+                ...(stage.gate_kinds !== undefined ? { gate_kinds: stage.gate_kinds } : {}),
+            };
+            if (source?.kind === "inline") {
+                return { ...listing, inline: true };
+            }
+            if (source?.kind === "file") {
+                return {
+                    ...listing,
+                    uses_path: path.relative(projectRoot, source.path).replace(/\\/g, "/"),
+                };
+            }
+            return listing;
+        }),
+    };
+}
+function listingFromDraft(pipelineRelPath, draft, stagePaths) {
+    return {
+        path: pipelineRelPath,
+        id: draft.pipeline.id,
+        stages: draft.pipeline.stages.map((stage, index) => {
+            const id = typeof stage.id === "string" ? stage.id : `stage-${index}`;
+            if (typeof stage.uses === "string" && stage.uses.trim()) {
+                const match = stagePaths.find((p) => p.endsWith(normalizeStageRelPath(stage.uses)));
+                return {
+                    id,
+                    ...(match !== undefined ? { uses_path: match } : {}),
+                };
+            }
+            return { id, inline: true };
+        }),
+    };
+}
+function resolveDraftWriteTarget(projectRoot, input) {
+    if (typeof input.directory !== "string" || !input.directory.trim()) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    const directory = input.directory.trim().replace(/\\/g, "/");
+    if (directory.endsWith(".yaml") || directory.endsWith(".yml")) {
+        return {
+            ok: false,
+            status: 400,
+            error: "directory must be a catalog folder, not a pipeline file path",
+        };
+    }
+    const packageDirectory = resolveDirectory(projectRoot, directory);
+    if (!packageDirectory) {
+        return {
+            ok: false,
+            status: 400,
+            error: "directory must be inside the project root",
+        };
+    }
+    const draft = input.draft;
+    if (!isPlainObject(draft?.pipeline) || typeof draft.pipeline.id !== "string") {
+        return { ok: false, status: 400, error: "draft.pipeline.id is required" };
+    }
+    const pipelineFilename = input.pipelineFilename?.trim() || `${draft.pipeline.id}.pipeline.yaml`;
+    const pipelineAbsPath = path.join(packageDirectory, path.basename(pipelineFilename));
+    const pipelineRelPath = path
+        .relative(projectRoot, pipelineAbsPath)
+        .replace(/\\/g, "/");
+    return {
+        ok: true,
+        value: {
+            packageDirectory,
+            draft,
+            pipelineFilename,
+            pipelineAbsPath,
+            pipelineRelPath,
+        },
+    };
+}
+async function gateDraftWrite(projectRoot, draft, allowInvalid) {
+    if (allowInvalid)
+        return null;
+    const validation = await validateDraftPackage(draft, {
+        cwd: projectRoot,
+        projectRoot,
+        strict: true,
+    });
+    if (validation.ok)
+        return null;
+    const errorFinding = validation.findings.find((finding) => finding.severity === "error");
+    return {
+        ok: false,
+        status: 422,
+        error: errorFinding?.message ?? "Package validation failed",
+        findings: validation.findings,
+    };
+}
+async function writeDraftPackageFiles(projectRoot, target, allowInvalid) {
+    const { packageDirectory, draft, pipelineAbsPath, pipelineRelPath } = target;
+    const stagePaths = [];
+    for (const stage of draft.stages ?? []) {
+        const rel = normalizeStageRelPath(stage.path);
+        if (!rel || path.isAbsolute(rel) || rel.split(/[/\\]/).includes("..")) {
+            return {
+                ok: false,
+                status: 400,
+                error: `Stage path escapes package directory (${stage.path})`,
+            };
+        }
+        const stageAbs = path.resolve(packageDirectory, rel);
+        const relToPackage = path.relative(packageDirectory, stageAbs);
+        if (relToPackage.startsWith("..") || path.isAbsolute(relToPackage)) {
+            return {
+                ok: false,
+                status: 400,
+                error: `Stage path escapes package directory (${stage.path})`,
+            };
+        }
+    }
+    try {
+        await mkdir(packageDirectory, { recursive: true });
+        await writeFile(pipelineAbsPath, stringifyTargetYaml(pipelineDocument(draft.pipeline)), "utf8");
+        for (const stage of draft.stages ?? []) {
+            const rel = normalizeStageRelPath(stage.path);
+            const stageAbs = path.resolve(packageDirectory, rel);
+            await mkdir(path.dirname(stageAbs), { recursive: true });
+            await writeFile(stageAbs, stringifyTargetYaml(stage.body), "utf8");
+            stagePaths.push(path.relative(projectRoot, stageAbs).replace(/\\/g, "/"));
+        }
+        let taskPath;
+        if (draft.task) {
+            const taskAbs = path.join(packageDirectory, path.basename(draft.task.filename));
+            await writeFile(taskAbs, stringifyTargetYaml(draft.task.body), "utf8");
+            taskPath = path.relative(projectRoot, taskAbs).replace(/\\/g, "/");
+        }
+        const loadOutcome = await loadPipelineOutcome(pipelineRelPath, {
+            cwd: projectRoot,
+        });
+        const pipeline = loadOutcome.ok
+            ? buildPipelineListing(projectRoot, pipelineRelPath, loadOutcome.value)
+            : listingFromDraft(pipelineRelPath, draft, stagePaths);
+        if (!loadOutcome.ok && !allowInvalid) {
+            return {
+                ok: false,
+                status: 500,
+                error: loadOutcome.issues[0]?.message ?? "Failed to load written pipeline",
+            };
+        }
+        return {
+            ok: true,
+            pipeline,
+            pipelinePath: pipelineRelPath,
+            stagePaths,
+            ...(taskPath !== undefined ? { taskPath } : {}),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 500, error: message };
+    }
+}
+export async function overwriteDraftPackage(projectRoot, input) {
+    const resolved = resolveDraftWriteTarget(projectRoot, input);
+    if (!resolved.ok)
+        return resolved;
+    if (!(await fileExists(resolved.value.pipelineAbsPath))) {
+        return {
+            ok: false,
+            status: 404,
+            error: `Pipeline does not exist (${resolved.value.pipelineRelPath})`,
+        };
+    }
+    const blocked = await gateDraftWrite(projectRoot, resolved.value.draft, input.allowInvalid);
+    if (blocked)
+        return blocked;
+    return writeDraftPackageFiles(projectRoot, resolved.value, input.allowInvalid);
+}
+export async function createDraftPackage(projectRoot, input) {
+    const resolved = resolveDraftWriteTarget(projectRoot, input);
+    if (!resolved.ok)
+        return resolved;
+    if (await fileExists(resolved.value.pipelineAbsPath)) {
+        return {
+            ok: false,
+            status: 409,
+            error: `Pipeline already exists (${resolved.value.pipelineRelPath})`,
+        };
+    }
+    const blocked = await gateDraftWrite(projectRoot, resolved.value.draft, input.allowInvalid);
+    if (blocked)
+        return blocked;
+    return writeDraftPackageFiles(projectRoot, resolved.value, input.allowInvalid);
+}
+export function parseDraftPackageBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "JSON object body required" };
+    }
+    const draftValue = isPlainObject(body.draft) ? body.draft : body;
+    if (!isPlainObject(draftValue.pipeline)) {
+        return { ok: false, status: 400, error: "draft.pipeline is required" };
+    }
+    if (typeof draftValue.pipeline.id !== "string" || !draftValue.pipeline.id.trim()) {
+        return { ok: false, status: 400, error: "draft.pipeline.id is required" };
+    }
+    if (!Array.isArray(draftValue.pipeline.stages)) {
+        return { ok: false, status: 400, error: "draft.pipeline.stages must be an array" };
+    }
+    return draftValue;
+}
+export function parseCreateDraftPackageBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "JSON object body required" };
+    }
+    const draftParsed = parseDraftPackageBody(body);
+    if ("ok" in draftParsed)
+        return draftParsed;
+    if (typeof body.directory !== "string" || !body.directory.trim()) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    return {
+        directory: body.directory.trim(),
+        draft: draftParsed,
+        ...(typeof body.pipelineFilename === "string"
+            ? { pipelineFilename: body.pipelineFilename }
+            : {}),
+        ...(body.allowInvalid === true ? { allowInvalid: true } : {}),
+    };
+}
+export const parseOverwriteDraftPackageBody = parseCreateDraftPackageBody;
+export function parseOpenDraftPackageBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "JSON object body required" };
+    }
+    if (typeof body.path !== "string" || !body.path.trim()) {
+        return { ok: false, status: 400, error: "path is required" };
+    }
+    const pathValue = body.path.trim().replace(/\\/g, "/");
+    const taskRaw = typeof body.task === "string"
+        ? body.task
+        : typeof body.taskPath === "string"
+            ? body.taskPath
+            : undefined;
+    return {
+        path: pathValue,
+        ...(taskRaw?.trim() ? { taskPath: taskRaw.trim().replace(/\\/g, "/") } : {}),
+    };
+}
+function resolveProjectRelativePath(projectRoot, relPath) {
+    const abs = path.resolve(projectRoot, relPath);
+    const rel = path.relative(projectRoot, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return null;
+    }
+    return abs;
+}
+/** Load a catalog task file into a draft task artifact (attach without reloading the pipeline). */
+export async function loadTaskArtifact(projectRoot, taskRelPath) {
+    if (typeof taskRelPath !== "string" || !taskRelPath.trim()) {
+        return { ok: false, status: 400, error: "task path is required" };
+    }
+    const taskRel = taskRelPath.trim().replace(/\\/g, "/");
+    const taskAbs = resolveProjectRelativePath(projectRoot, taskRel);
+    if (!taskAbs) {
+        return {
+            ok: false,
+            status: 400,
+            error: "task path must be inside the project root",
+        };
+    }
+    if (!(await fileExists(taskAbs))) {
+        return {
+            ok: false,
+            status: 404,
+            error: `Task does not exist (${taskRel})`,
+        };
+    }
+    try {
+        const body = await readYamlObject(taskAbs);
+        return {
+            ok: true,
+            task: {
+                filename: path.basename(taskAbs),
+                body,
+            },
+            taskPath: path.relative(projectRoot, taskAbs).replace(/\\/g, "/"),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 400, error: `Failed to read task: ${message}` };
+    }
+}
+export function parseAttachTaskBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "JSON object body required" };
+    }
+    const taskRaw = typeof body.task === "string"
+        ? body.task
+        : typeof body.taskPath === "string"
+            ? body.taskPath
+            : undefined;
+    if (!taskRaw?.trim()) {
+        return { ok: false, status: 400, error: "task path is required" };
+    }
+    return { taskPath: taskRaw.trim().replace(/\\/g, "/") };
+}
+export async function loadDraftPackage(projectRoot, pipelineRelPath, options = {}) {
+    if (typeof pipelineRelPath !== "string" || !pipelineRelPath.trim()) {
+        return { ok: false, status: 400, error: "path is required" };
+    }
+    const normalizedRel = pipelineRelPath.trim().replace(/\\/g, "/");
+    const pipelineAbs = resolveProjectRelativePath(projectRoot, normalizedRel);
+    if (!pipelineAbs) {
+        return {
+            ok: false,
+            status: 400,
+            error: "path must be inside the project root",
+        };
+    }
+    if (!(await fileExists(pipelineAbs))) {
+        return {
+            ok: false,
+            status: 404,
+            error: `Pipeline does not exist (${normalizedRel})`,
+        };
+    }
+    let raw;
+    try {
+        raw = await readYamlObject(pipelineAbs);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 400, error: `Failed to read pipeline: ${message}` };
+    }
+    if (typeof raw.id !== "string" || !raw.id.trim()) {
+        return { ok: false, status: 400, error: "pipeline id is required" };
+    }
+    if (!Array.isArray(raw.stages)) {
+        return { ok: false, status: 400, error: "pipeline stages must be an array" };
+    }
+    const packageDirectory = path.dirname(pipelineAbs);
+    const pipelineFilename = path.basename(pipelineAbs);
+    const directory = path
+        .relative(projectRoot, packageDirectory)
+        .replace(/\\/g, "/") || ".";
+    const pipelinePath = path
+        .relative(projectRoot, pipelineAbs)
+        .replace(/\\/g, "/");
+    const pipelineStages = raw.stages.filter(isPlainObject);
+    const stageArtifacts = [];
+    const seenUses = new Set();
+    for (const stage of pipelineStages) {
+        if (typeof stage.uses !== "string" || !stage.uses.trim())
+            continue;
+        const uses = stage.uses.trim().replace(/\\/g, "/");
+        const key = normalizeStageRelPath(uses);
+        if (seenUses.has(key))
+            continue;
+        seenUses.add(key);
+        const stageAbs = path.resolve(packageDirectory, uses);
+        const stageRelToRoot = path.relative(projectRoot, stageAbs);
+        if (stageRelToRoot.startsWith("..") || path.isAbsolute(stageRelToRoot)) {
+            return {
+                ok: false,
+                status: 400,
+                error: `Stage path escapes project root (${uses})`,
+            };
+        }
+        if (!(await fileExists(stageAbs))) {
+            return {
+                ok: false,
+                status: 404,
+                error: `Stage file does not exist (${path
+                    .relative(projectRoot, stageAbs)
+                    .replace(/\\/g, "/")})`,
+            };
+        }
+        try {
+            const body = await readYamlObject(stageAbs);
+            stageArtifacts.push({ path: uses, body });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                status: 400,
+                error: `Failed to read stage ${uses}: ${message}`,
+            };
+        }
+    }
+    const draft = {
+        pipeline: {
+            id: raw.id,
+            stages: pipelineStages,
+            ...(raw.agent !== undefined ? { agent: raw.agent } : {}),
+            ...(raw.model !== undefined ? { model: raw.model } : {}),
+            ...(raw.schemas !== undefined ? { schemas: raw.schemas } : {}),
+            ...(raw.requires !== undefined ? { requires: raw.requires } : {}),
+        },
+        ...(stageArtifacts.length > 0 ? { stages: stageArtifacts } : {}),
+    };
+    let attachedTaskPath;
+    if (options.taskPath?.trim()) {
+        const loaded = await loadTaskArtifact(projectRoot, options.taskPath);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: loaded.status,
+                error: loaded.error,
+            };
+        }
+        draft.task = loaded.task;
+        attachedTaskPath = loaded.taskPath;
+    }
+    return {
+        ok: true,
+        draft,
+        destination: { directory, pipelineFilename },
+        pipelinePath,
+        ...(attachedTaskPath !== undefined ? { taskPath: attachedTaskPath } : {}),
+    };
+}

package/dist/config/ensureCatalogScanRoot.d.ts

@@ -0,0 +1,16 @@
+/** Directory scanned for workshop-authored pipelines and tasks. */
+export declare const WORKSHOP_PACKAGE_ROOT = "workshop";
+export declare function normalizeCatalogDir(directory: string): string;
+/** Untitled workshop saves land here so Run can see them without a new catalog edit. */
+export declare function defaultWorkshopPackageDirectory(pipelineId: string | undefined): string;
+/**
+ * Catalog root that covers this package directory.
+ * Packages under `workshop/` share one root. Any other folder is listed itself
+ * so a named save still shows up without scanning a whole parent tree.
+ */
+export declare function catalogScanRootForDirectory(directory: string): string;
+/**
+ * Make sure `stageflow.yaml` scans `directory` for both pipelines and tasks.
+ * Returns true when the manifest changed. Missing or unreadable manifests are left alone.
+ */
+export declare function ensureCatalogScanRoot(projectRoot: string, directory: string): Promise<boolean>;

package/dist/config/ensureCatalogScanRoot.js

@@ -0,0 +1,73 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { isSeq, parseDocument } from "yaml";
+import { manifestPathForProject } from "./loadStageflowManifest.js";
+/** Directory scanned for workshop-authored pipelines and tasks. */
+export const WORKSHOP_PACKAGE_ROOT = "workshop";
+export function normalizeCatalogDir(directory) {
+    return directory.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+/** Untitled workshop saves land here so Run can see them without a new catalog edit. */
+export function defaultWorkshopPackageDirectory(pipelineId) {
+    const slug = (pipelineId ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return `${WORKSHOP_PACKAGE_ROOT}/${slug || "untitled"}`;
+}
+/**
+ * Catalog root that covers this package directory.
+ * Packages under `workshop/` share one root. Any other folder is listed itself
+ * so a named save still shows up without scanning a whole parent tree.
+ */
+export function catalogScanRootForDirectory(directory) {
+    const normalized = normalizeCatalogDir(directory);
+    if (normalized === WORKSHOP_PACKAGE_ROOT ||
+        normalized.startsWith(`${WORKSHOP_PACKAGE_ROOT}/`)) {
+        return WORKSHOP_PACKAGE_ROOT;
+    }
+    return normalized;
+}
+function isCovered(entries, root) {
+    return entries.some((entry) => {
+        const normalized = normalizeCatalogDir(entry);
+        return root === normalized || root.startsWith(`${normalized}/`);
+    });
+}
+/**
+ * Make sure `stageflow.yaml` scans `directory` for both pipelines and tasks.
+ * Returns true when the manifest changed. Missing or unreadable manifests are left alone.
+ */
+export async function ensureCatalogScanRoot(projectRoot, directory) {
+    const root = catalogScanRootForDirectory(directory);
+    if (!root || root.split("/").includes(".."))
+        return false;
+    const manifestPath = manifestPathForProject(projectRoot);
+    let text;
+    try {
+        text = await readFile(manifestPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const doc = parseDocument(text);
+    let changed = false;
+    for (const key of ["pipelines", "tasks"]) {
+        const seq = doc.getIn(["catalog", key]);
+        if (!isSeq(seq))
+            continue;
+        const values = seq.toJSON();
+        const entries = Array.isArray(values)
+            ? values.filter((item) => typeof item === "string")
+            : [];
+        if (isCovered(entries, root))
+            continue;
+        seq.add(root);
+        changed = true;
+    }
+    if (!changed)
+        return false;
+    const next = String(doc);
+    await writeFile(manifestPath, next.endsWith("\n") ? next : `${next}\n`, "utf8");
+    return true;
+}

package/dist/config/hostConfig.d.ts

@@ -0,0 +1,57 @@
+export declare class HostConfigError extends Error {
+    readonly code: "config_unknown_key" | "config_invalid";
+    readonly key?: string;
+    constructor(message: string, code: "config_unknown_key" | "config_invalid", key?: string);
+}
+/** Env keys that are known STAGEFLOW_* (or dynamic families) so unknown-key check accepts them. */
+export declare const KNOWN_STAGEFLOW_ENV_KEYS: Set<string>;
+/** Per-caller concurrent-active quota from host `callers:` config. */
+export type CallerQuotaConfig = {
+    maxConcurrent: number;
+};
+export type HostConfig = {
+    maxConcurrentRuns: number;
+    maxConcurrentRunsPerProject: number | undefined;
+    maxQueued: number;
+    requireProviders: string[];
+    trustWorkspaceConfig: string[];
+    allowUnknownConfig: boolean;
+    controlToken: string | undefined;
+    readToken: string | undefined;
+    /** caller_id → quota; empty when unset. */
+    callers: Record<string, CallerQuotaConfig>;
+    /** Domains no browser stage may use (`browser.blocked_sites` in config.yaml). */
+    browserBlockedSites: string[];
+    /** Absolute path of config.yaml when loaded; undefined if absent. */
+    configFilePath: string | undefined;
+    warnings: string[];
+    /** True when maxConcurrentRuns came from override, env, or file (not bare default). */
+    maxConcurrentRunsExplicit: boolean;
+};
+export type HostConfigOverrides = {
+    maxConcurrentRuns?: number;
+};
+export type HostConfigSecretsEcho = {
+    controlToken: "set" | "unset";
+    readToken: "set" | "unset";
+};
+export type HostConfigPublicEcho = {
+    maxConcurrentRuns: number;
+    maxConcurrentRunsPerProject: number | undefined;
+    maxQueued: number;
+    requireProviders: string[];
+    trustWorkspaceConfig: string[];
+    allowUnknownConfig: boolean;
+    callers: Record<string, CallerQuotaConfig>;
+    secrets: HostConfigSecretsEcho;
+};
+/**
+ * Assemble HostConfig once at boot. Precedence: overrides (CLI flags) > env > file > default.
+ */
+export declare function loadHostConfig(options?: {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    overrides?: HostConfigOverrides;
+    configFilePath?: string | null;
+}): HostConfig;
+export declare function redactHostConfig(config: HostConfig): HostConfigPublicEcho;