stageflow 0.25.0 → 0.30.0

package/dist/config/multiProjectCatalog.js

@@ -0,0 +1,150 @@
+import { listModelsForContext, listPipelinesForContext, listTasksForContext, } from "./browseCatalog.js";
+import { loadStageflowManifestOutcome, } from "./loadStageflowManifest.js";
+import { findCatalogRoot, isRootReadable, resolveCatalogRoots, } from "./resolveCatalogRoots.js";
+export const EMPTY_CATALOG_LIST_TIP = "No catalog entries listed. Register a project root (POST /api/projects or local sf run / ensure), ensure stageflow.yaml exists at that root, then retry list_pipelines / list_tasks. Packaged examples use project_root \"examples\" when present. Git is not required for discovery.";
+function listTip(itemsLength, root_errors) {
+    if (itemsLength > 0)
+        return undefined;
+    if (root_errors.some((e) => e.code === "unknown_project_root")) {
+        return undefined;
+    }
+    return EMPTY_CATALOG_LIST_TIP;
+}
+async function catalogContextForRoot(root) {
+    const outcome = await loadStageflowManifestOutcome(root.path);
+    if (!outcome.ok) {
+        return {
+            projectRoot: root.path,
+            manifest: null,
+            manifestStatus: "invalid",
+            issues: outcome.issues,
+        };
+    }
+    return {
+        projectRoot: root.path,
+        manifest: outcome.value,
+        manifestStatus: "ok",
+        issues: [],
+    };
+}
+async function selectRoots(options) {
+    const roots = await resolveCatalogRoots(options);
+    const root_errors = [];
+    if (options.projectRootFilter !== undefined) {
+        const match = findCatalogRoot(roots, options.projectRootFilter);
+        if (match === undefined) {
+            return {
+                roots,
+                selected: [],
+                root_errors: [
+                    {
+                        project_root: options.projectRootFilter,
+                        code: "unknown_project_root",
+                        message: `Unknown project_root: ${options.projectRootFilter}`,
+                    },
+                ],
+            };
+        }
+        if (!(await isRootReadable(match.path))) {
+            return {
+                roots,
+                selected: [],
+                root_errors: [
+                    {
+                        project_root: match.project_root,
+                        code: "catalog_root_unreadable",
+                        message: `Catalog root is unreadable: ${match.project_root}`,
+                    },
+                ],
+            };
+        }
+        return { roots, selected: [match], root_errors };
+    }
+    const selected = [];
+    for (const root of roots) {
+        if (!(await isRootReadable(root.path))) {
+            root_errors.push({
+                project_root: root.project_root,
+                code: "catalog_root_unreadable",
+                message: `Catalog root is unreadable: ${root.project_root}`,
+            });
+            continue;
+        }
+        selected.push(root);
+    }
+    return { roots, selected, root_errors };
+}
+function withListTip(result) {
+    const tip = listTip(result.items.length, result.root_errors);
+    return tip !== undefined ? { ...result, tip } : result;
+}
+export async function listPipelinesMultiProject(options) {
+    const { roots, selected, root_errors } = await selectRoots(options);
+    const items = [];
+    for (const root of selected) {
+        try {
+            const ctx = await catalogContextForRoot(root);
+            const pipelines = await listPipelinesForContext(ctx);
+            for (const p of pipelines) {
+                items.push({ ...p, project_root: root.project_root });
+            }
+        }
+        catch (err) {
+            root_errors.push({
+                project_root: root.project_root,
+                code: "catalog_root_unreadable",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return withListTip({ items, root_errors, roots });
+}
+export async function listTasksMultiProject(options) {
+    const { roots, selected, root_errors } = await selectRoots(options);
+    const items = [];
+    for (const root of selected) {
+        try {
+            const ctx = await catalogContextForRoot(root);
+            const tasks = await listTasksForContext(ctx);
+            for (const t of tasks) {
+                items.push({ ...t, project_root: root.project_root });
+            }
+        }
+        catch (err) {
+            root_errors.push({
+                project_root: root.project_root,
+                code: "catalog_root_unreadable",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return withListTip({ items, root_errors, roots });
+}
+export async function listModelsMultiProject(options) {
+    const { roots, selected, root_errors } = await selectRoots(options);
+    const items = [];
+    const modelSet = new Set();
+    for (const root of selected) {
+        try {
+            const ctx = await catalogContextForRoot(root);
+            const models = await listModelsForContext(ctx);
+            for (const id of models) {
+                modelSet.add(id);
+                items.push({ id, project_root: root.project_root });
+            }
+        }
+        catch (err) {
+            root_errors.push({
+                project_root: root.project_root,
+                code: "catalog_root_unreadable",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return {
+        items,
+        models: [...modelSet].sort((a, b) => a.localeCompare(b)),
+        root_errors,
+        roots,
+    };
+}

package/dist/config/normalizePipelineStageEntry.js

@@ -7,6 +7,9 @@
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseStageMcp } from "./loadStage.js";
+import { parseStageSecrets } from "../runtime/stageSecretDecl.js";
+import { parseStageBrowser } from "./stageBrowser.js";
+import { parseToolRequires } from "./toolRequires.js";
 import { legacyAuthoringRejected, presentLegacyKeys } from "./legacyYaml.js";
 import { compileTargetContract, dialectFromKeys, mixedDialectIssue, } from "./yamlDialect.js";
 import { BODY_KEYS, isAllowedPipelineStageEntryKey, } from "./pipelineStageKeys.js";
@@ -39,7 +42,12 @@ function extractBodyRaw(raw) {
     return body;
 }
 function hasBodyKey(raw) {
-    return Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill" && key !== "mcp");
+    return Object.keys(raw).some((key) => BODY_KEYS.has(key) &&
+        key !== "skill" &&
+        key !== "mcp" &&
+        key !== "secrets" &&
+        key !== "requires" &&
+        key !== "browser");
 }
 function readSkill(raw) {
     if (raw.skill === undefined)
@@ -112,6 +120,21 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
         if (!mcpOutcome.ok)
             return mcpOutcome;
         const mcp = mcpOutcome.value;
+        const secretsOutcome = parseStageSecrets(raw.secrets, `entry at index ${index} in ${declaringPath}`);
+        if (!secretsOutcome.ok)
+            return secretsOutcome;
+        const secrets = secretsOutcome.value;
+        const requiresOutcome = parseToolRequires(raw.requires, `stage entry at index ${index} in ${declaringPath}`, {
+            code: "stage.invalid_requires",
+            category: "stage",
+        });
+        if (!requiresOutcome.ok)
+            return requiresOutcome;
+        const requires = requiresOutcome.value;
+        const browserOutcome = parseStageBrowser(raw.browser, `entry at index ${index} in ${declaringPath}`, typeof raw.id === "string" ? raw.id : undefined);
+        if (!browserOutcome.ok)
+            return browserOutcome;
+        const browser = browserOutcome.value;
         if (uses && hasBody) {
             return loadFailure([
                 {
@@ -339,6 +362,9 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             ...(entryFlag !== undefined ? { entry: entryFlag } : {}),
             ...(skill !== undefined ? { skill } : {}),
             ...(mcp !== undefined ? { mcp } : {}),
+            ...(secrets !== undefined ? { secrets } : {}),
+            ...(requires !== undefined ? { requires } : {}),
+            ...(browser !== undefined ? { browser } : {}),
             ...(cloneCap !== undefined ? { clone_cap: cloneCap } : {}),
             ...(cloneMode !== undefined ? { clone_mode: cloneMode } : {}),
         };

package/dist/config/parseCompletionContract.js

@@ -124,6 +124,12 @@ function parseCheck(raw, stageId, index) {
             return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
         return loadSuccess({ id, type: "payload_schema" });
     }
+    if (raw.type === "browser_login") {
+        const unknown = hasOnlyKeys(raw, ["id", "type"]);
+        if (unknown)
+            return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
+        return loadSuccess({ id, type: "browser_login" });
+    }
     if (raw.type === "gate") {
         const unknown = hasOnlyKeys(raw, ["id", "type", "kind"]);
         if (unknown)

package/dist/config/pipelineStageKeys.js

@@ -37,6 +37,9 @@ export const BODY_KEYS = new Set([
     "timeout_ms",
     "skill",
     "mcp",
+    "secrets",
+    "requires",
+    "browser",
     "io",
     "verify",
 ]);

package/dist/config/publishDraftPackage.d.ts

@@ -0,0 +1,7 @@
+import { type CreateDraftPackageInput, type DraftPackageWriteResult } from "./draftPackage.js";
+export type PublishDraftPackageMode = "create" | "overwrite" | "auto";
+export type PublishDraftPackageResult = {
+    write: DraftPackageWriteResult;
+    catalogChanged: boolean;
+};
+export declare function publishDraftPackage(projectRoot: string, input: CreateDraftPackageInput, mode: PublishDraftPackageMode): Promise<PublishDraftPackageResult>;

package/dist/config/publishDraftPackage.js

@@ -0,0 +1,25 @@
+import { createDraftPackage, overwriteDraftPackage, } from "./draftPackage.js";
+import { ensureCatalogScanRoot } from "./ensureCatalogScanRoot.js";
+export async function publishDraftPackage(projectRoot, input, mode) {
+    let write;
+    if (mode === "create") {
+        write = await createDraftPackage(projectRoot, input);
+    }
+    else if (mode === "overwrite") {
+        write = await overwriteDraftPackage(projectRoot, input);
+    }
+    else {
+        const created = await createDraftPackage(projectRoot, input);
+        if (created.ok || created.status !== 409) {
+            write = created;
+        }
+        else {
+            write = await overwriteDraftPackage(projectRoot, input);
+        }
+    }
+    if (!write.ok) {
+        return { write, catalogChanged: false };
+    }
+    const catalogChanged = await ensureCatalogScanRoot(projectRoot, input.directory);
+    return { write, catalogChanged };
+}

package/dist/config/resolveCatalogContext.js

@@ -1,7 +1,7 @@
 import { resolveStageflowContext, } from "../project/resolveStageflowContext.js";
 export function catalogContextFromStageflow(ctx) {
     return {
-        projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
+        projectRoot: ctx.manifestStatus === "not_git" ? null : ctx.projectRoot,
         manifest: ctx.manifest,
         manifestStatus: ctx.manifestStatus,
         issues: ctx.manifestIssues,

package/dist/config/resolveCatalogRoots.d.ts

@@ -0,0 +1,27 @@
+import type { RunStore } from "../runstore/port.js";
+export type CatalogRootKind = "registered" | "seeded";
+export type CatalogRoot = {
+    /** Wire id: absolute path for registered; symbolic id for seeded (e.g. "examples"). */
+    project_root: string;
+    /** Absolute filesystem path used for browsing. */
+    path: string;
+    kind: CatalogRootKind;
+    read_only: boolean;
+};
+export type ResolveCatalogRootsOptions = {
+    store: RunStore;
+    /** Unused for catalog membership; retained so call sites may still pass Host cwd. */
+    bootCwd?: string;
+    /** Optional seeded roots (U10); default none. */
+    seededRoots?: Array<{
+        id: string;
+        path: string;
+    }>;
+};
+/**
+ * Root set = registered store roots ∪ seeded roots.
+ * Wire project_root for seeded is the symbolic id; store/capacity use absolute paths.
+ */
+export declare function resolveCatalogRoots(options: ResolveCatalogRootsOptions): Promise<CatalogRoot[]>;
+export declare function isRootReadable(rootPath: string): Promise<boolean>;
+export declare function findCatalogRoot(roots: CatalogRoot[], projectRoot: string): CatalogRoot | undefined;

package/dist/config/resolveCatalogRoots.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { realpathSync, constants } from "node:fs";
+import { access } from "node:fs/promises";
+function realOrResolve(p) {
+    const resolved = path.resolve(p);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * Root set = registered store roots ∪ seeded roots.
+ * Wire project_root for seeded is the symbolic id; store/capacity use absolute paths.
+ */
+export async function resolveCatalogRoots(options) {
+    const roots = [];
+    const seenPaths = new Set();
+    const seededRoots = options.seededRoots ??
+        (await import("./seededCatalog.js")).defaultSeededRoots();
+    let registered = [];
+    try {
+        registered = await options.store.listRegisteredProjects();
+    }
+    catch {
+        registered = [];
+    }
+    for (const root of registered) {
+        const abs = realOrResolve(root);
+        if (seenPaths.has(abs))
+            continue;
+        seenPaths.add(abs);
+        roots.push({
+            project_root: abs,
+            path: abs,
+            kind: "registered",
+            read_only: false,
+        });
+    }
+    for (const seeded of seededRoots) {
+        const abs = realOrResolve(seeded.path);
+        if (seenPaths.has(abs))
+            continue;
+        seenPaths.add(abs);
+        roots.push({
+            project_root: seeded.id,
+            path: abs,
+            kind: "seeded",
+            read_only: true,
+        });
+    }
+    return roots;
+}
+export async function isRootReadable(rootPath) {
+    try {
+        await access(rootPath, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function findCatalogRoot(roots, projectRoot) {
+    if (!path.isAbsolute(projectRoot)) {
+        return roots.find((r) => r.project_root === projectRoot);
+    }
+    const normalized = realOrResolve(projectRoot);
+    const resolved = path.resolve(projectRoot);
+    return roots.find((r) => r.project_root === projectRoot ||
+        r.path === projectRoot ||
+        r.project_root === resolved ||
+        r.path === resolved ||
+        r.project_root === normalized ||
+        r.path === normalized);
+}

package/dist/config/resolveModel.d.ts

@@ -8,6 +8,12 @@ export type ModelSelection = {
     /** Stage yaml / inline `model`; overrides pipeline/global. */
     stage?: string;
 };
+export type ModelAuthoredTier = "stage" | "pipeline" | "global";
+export type ResolvedModelSelection = {
+    model: string;
+    tier: ModelAuthoredTier;
+};
+export declare function modelAuthoredTier(selection: ModelSelection): ModelAuthoredTier;
 /**
  * stage > pipeline > global. No silent hardcoded fallback — unset is a load error.
  * Present-but-empty / whitespace follows parseModelField (load failure, not "").
@@ -15,6 +21,6 @@ export type ModelSelection = {
 export declare function resolveModelOutcome(selection: ModelSelection, ctx: {
     stageId: string;
     pipelineId: string;
-}): LoadOutcome<string>;
+}): LoadOutcome<ResolvedModelSelection>;
 /** The global tier's model id from an already-loaded manifest, or undefined when missing/unset. */
 export declare function globalModelFromManifest(loaded: LoadedManifest | null): string | undefined;

package/dist/config/resolveModel.js

@@ -1,5 +1,12 @@
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseModelField } from "./modelField.js";
+export function modelAuthoredTier(selection) {
+    if (selection.stage !== undefined)
+        return "stage";
+    if (selection.pipeline !== undefined)
+        return "pipeline";
+    return "global";
+}
 /**
  * stage > pipeline > global. No silent hardcoded fallback — unset is a load error.
  * Present-but-empty / whitespace follows parseModelField (load failure, not "").
@@ -27,7 +34,10 @@ export function resolveModelOutcome(selection, ctx) {
             },
         ]);
     }
-    return loadSuccess(parsed.value);
+    return loadSuccess({
+        model: parsed.value,
+        tier: modelAuthoredTier(selection),
+    });
 }
 /** The global tier's model id from an already-loaded manifest, or undefined when missing/unset. */
 export function globalModelFromManifest(loaded) {

package/dist/config/resolvePipelineDag.js

@@ -18,7 +18,7 @@ function wrapRawStagesForNormalize(rawStages, ctx) {
         }
         const id = typeof raw.id === "string" && raw.id ? raw.id : undefined;
         const hasUses = typeof raw.uses === "string";
-        const hasBody = Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill" && key !== "mcp");
+        const hasBody = Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill" && key !== "mcp" && key !== "browser");
         if (hasUses || hasBody || !id) {
             return { raw, declaringPath: ctx.path };
         }

package/dist/config/resolveStageMcpServers.d.ts

@@ -1,4 +1,4 @@
-export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "connect_failed";
+export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "untrusted_config_origin" | "connect_failed";
 export declare class StageMcpError extends Error {
     readonly code: StageMcpErrorCode;
     constructor(message: string, code: StageMcpErrorCode);
@@ -15,6 +15,7 @@ export type InspectedMcpCatalog = {
 };
 export declare function mcpCatalogPath(projectRoot: string): string;
 export declare function parseMcpCatalog(raw: string, catalogPath?: string): McpCatalogServers;
+export declare function mcpCatalogExists(projectRoot: string): Promise<boolean>;
 export declare function loadMcpCatalog(projectRoot: string): Promise<InspectedMcpCatalog>;
 export type ProjectMcpCatalogTransport = "stdio" | "http";
 export type ProjectMcpCatalogEntry = {
@@ -32,4 +33,11 @@ export declare function resolveStageMcpServers(options: {
     projectRoot: string;
     allowlist?: readonly string[];
     env: NodeJS.ProcessEnv;
+    stageId?: string;
+    bindingKind?: "repository" | "checkout" | "none";
+    trustWorkspaceConfig?: string[];
+    /** Host project root used for trust_workspace_config allowlist matching. */
+    trustProjectRoot?: string;
+    /** When true, .mcp.json is treated as workspace-sourced. */
+    workspaceSourced?: boolean;
 }): Promise<ResolvedMcpServers>;

package/dist/config/resolveStageMcpServers.js

@@ -51,6 +51,18 @@ export function parseMcpCatalog(raw, catalogPath = MCP_CATALOG_FILENAME) {
     }
     return servers;
 }
+export async function mcpCatalogExists(projectRoot) {
+    try {
+        await readFile(mcpCatalogPath(projectRoot), "utf8");
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
 export async function loadMcpCatalog(projectRoot) {
     const catalogPath = mcpCatalogPath(projectRoot);
     let raw;
@@ -108,7 +120,7 @@ export function assertMcpAllowlistKnown(servers, allowlist) {
 const INTERPOLATION_TOKEN = /\$\{([^}]*)\}/g;
 const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ENV_VAR_WITH_DEFAULT = /^([A-Za-z_][A-Za-z0-9_]*):-(.*)$/;
-function interpolateString(value, env, serverName) {
+function interpolateString(value, env, serverName, stageId) {
     return value.replace(INTERPOLATION_TOKEN, (_match, inner) => {
         const withDefault = ENV_VAR_WITH_DEFAULT.exec(inner);
         if (withDefault) {
@@ -120,24 +132,27 @@ function interpolateString(value, env, serverName) {
             if (found !== undefined) {
                 return found;
             }
-            throw new StageMcpError(`Unresolved MCP catalog variable "${inner}"`, "unresolved_var");
+            const stagePart = stageId !== undefined ? ` (stage "${stageId}")` : "";
+            throw new StageMcpError(`Unresolved MCP catalog variable "${inner}" for server "${serverName}"${stagePart}. Declare it in secrets: (use as: env for tokens needed in MCP env) or use \${${inner}:-default}.`, "unresolved_var");
         }
         throw new StageMcpError(`MCP catalog server "${serverName}" has an invalid interpolation form`, "invalid_config");
     });
 }
-function interpolateField(key, value, env, serverName) {
+function interpolateField(key, value, env, serverName, stageId) {
     if ((key === "command" || key === "url" || key === "cwd") && typeof value === "string") {
-        return interpolateString(value, env, serverName);
+        return interpolateString(value, env, serverName, stageId);
     }
     if (key === "args" && Array.isArray(value)) {
-        return value.map((item) => typeof item === "string" ? interpolateString(item, env, serverName) : item);
+        return value.map((item) => typeof item === "string"
+            ? interpolateString(item, env, serverName, stageId)
+            : item);
     }
     if ((key === "env" || key === "headers") && isPlainObject(value)) {
         const copied = {};
         for (const [field, fieldValue] of Object.entries(value)) {
             copied[field] =
                 typeof fieldValue === "string"
-                    ? interpolateString(fieldValue, env, serverName)
+                    ? interpolateString(fieldValue, env, serverName, stageId)
                     : fieldValue;
         }
         return copied;
@@ -185,10 +200,10 @@ function stampSpawnRoot(resolved, projectRoot, serverName) {
     }
     return resolved;
 }
-function interpolateServer(entry, env, serverName, projectRoot) {
+function interpolateServer(entry, env, serverName, projectRoot, stageId) {
     const resolved = {};
     for (const [key, value] of Object.entries(entry)) {
-        resolved[key] = interpolateField(key, value, env, serverName);
+        resolved[key] = interpolateField(key, value, env, serverName, stageId);
     }
     return stampSpawnRoot(resolved, projectRoot, serverName);
 }
@@ -197,11 +212,23 @@ export async function resolveStageMcpServers(options) {
     if (allowlist.length === 0) {
         return {};
     }
+    if (options.workspaceSourced === true) {
+        const { decideWorkspaceConfigTrust } = await import("./configOrigin.js");
+        const decision = decideWorkspaceConfigTrust({
+            bindingKind: options.bindingKind ?? "none",
+            projectRoot: options.trustProjectRoot ?? options.projectRoot,
+            trustWorkspaceConfig: options.trustWorkspaceConfig,
+            source: "workspace",
+        });
+        if (!decision.allow) {
+            throw new StageMcpError(decision.message ?? "untrusted_config_origin", "untrusted_config_origin");
+        }
+    }
     const catalog = await loadMcpCatalog(options.projectRoot);
     assertMcpAllowlistKnown(catalog.servers, allowlist);
     const resolved = {};
     for (const name of allowlist) {
-        resolved[name] = interpolateServer(catalog.servers[name], options.env, name, options.projectRoot);
+        resolved[name] = interpolateServer(catalog.servers[name], options.env, name, options.projectRoot, options.stageId);
     }
     return resolved;
 }

package/dist/config/scanCatalogPaths.d.ts

@@ -1,4 +1,4 @@
 import type { LoadedManifest } from "../types/stageflowManifest.js";
-export type CatalogPathKind = "pipeline" | "task";
+export type CatalogPathKind = "pipeline" | "task" | "trigger";
 export declare function isExcluded(repoRelPath: string, exclude: string[] | undefined): boolean;
 export declare function scanCatalogPaths(manifest: LoadedManifest, kind: CatalogPathKind): Promise<string[]>;

package/dist/config/scanCatalogPaths.js

@@ -60,8 +60,12 @@ async function expandCatalogEntry(projectRoot, entry, kind, pattern) {
 }
 export async function scanCatalogPaths(manifest, kind) {
     const { projectRoot, manifest: doc, patterns } = manifest;
-    const entries = kind === "pipeline" ? doc.catalog.pipelines : doc.catalog.tasks;
-    const pattern = kind === "pipeline" ? patterns.pipeline : patterns.task;
+    const entries = kind === "pipeline"
+        ? doc.catalog.pipelines
+        : kind === "task"
+            ? doc.catalog.tasks
+            : (doc.catalog.triggers ?? []);
+    const pattern = kind === "pipeline" ? patterns.pipeline : kind === "task" ? patterns.task : patterns.trigger;
     const exclude = doc.catalog.exclude;
     const seen = new Set();
     const resolved = [];

package/dist/config/secretFromEnvOrFile.d.ts

@@ -0,0 +1,9 @@
+export declare class SecretFromEnvError extends Error {
+    readonly code = "config_invalid";
+    constructor(message: string);
+}
+/**
+ * Read a secret from `NAME` or `NAME_FILE`. Both set → error.
+ * File values trim exactly one trailing newline (`\n` or `\r\n`).
+ */
+export declare function readSecretFromEnvOrFile(env: NodeJS.ProcessEnv, name: string): string | undefined;

package/dist/config/secretFromEnvOrFile.js

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+export class SecretFromEnvError extends Error {
+    code = "config_invalid";
+    constructor(message) {
+        super(message);
+        this.name = "SecretFromEnvError";
+    }
+}
+/**
+ * Read a secret from `NAME` or `NAME_FILE`. Both set → error.
+ * File values trim exactly one trailing newline (`\n` or `\r\n`).
+ */
+export function readSecretFromEnvOrFile(env, name) {
+    const fileKey = `${name}_FILE`;
+    const plain = env[name];
+    const filePath = env[fileKey];
+    const hasPlain = plain !== undefined && plain.length > 0;
+    const hasFile = filePath !== undefined && filePath.length > 0;
+    if (hasPlain && hasFile) {
+        throw new SecretFromEnvError(`Set only one of ${name} or ${fileKey}, not both`);
+    }
+    if (hasFile) {
+        try {
+            return readFileSync(filePath, "utf8").replace(/\r?\n$/, "");
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new SecretFromEnvError(`Failed to read ${fileKey}=${filePath}: ${detail}`);
+        }
+    }
+    if (hasPlain)
+        return plain;
+    return undefined;
+}

package/dist/config/seededCatalog.d.ts

@@ -0,0 +1,11 @@
+/** Symbolic wire id for the packaged examples catalog root. */
+export declare 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 declare function resolveSeededExamplesPath(fromUrl?: string): string | undefined;
+export declare function defaultSeededRoots(): Array<{
+    id: string;
+    path: string;
+}>;