stageflow 0.25.0 → 0.27.0

package/dist/config/loadPipeline.js

@@ -12,6 +12,7 @@ import { recoveryRequiresCompletionIssue } from "./parseCompletionContract.js";
 import { validateCompletionContractForStage } from "./validateCompletionContract.js";
 import { applyCloneChains } from "./cloneChain.js";
 import { collectRouteIfSchemaIssues, collectRouteIfIllegalCombos, collectRouteAllGatedWarnings, } from "./routeIf.js";
+import { mergeToolRequires } from "./toolRequires.js";
 function schemaCompileIssue(stageId, field, err, pipelineId) {
     const message = err instanceof Error ? err.message : String(err);
     if (err instanceof UnresolvedSchemaRefError) {
@@ -128,7 +129,7 @@ export async function loadPipelineFromObject(raw, options = {}) {
 }
 async function buildLoadedPipelineFromMerge(merge, options) {
     const { projectRoot, requireIo, pipelinePath } = options;
-    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, warnings: mergeWarnings, } = merge;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, requires: pipelineRequires, warnings: mergeWarnings, } = merge;
     const ctx = { pipelineId, path: pipelinePath };
     const warnings = [...mergeWarnings];
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
@@ -181,7 +182,14 @@ async function buildLoadedPipelineFromMerge(merge, options) {
             if (!inlineOutcome.ok) {
                 return loadFailure(inlineOutcome.issues);
             }
-            stages.push(inlineOutcome.value);
+            let stage = inlineOutcome.value;
+            if (entry.requires !== undefined) {
+                const merged = mergeToolRequires([stage.requires, entry.requires], { pipelineId, label: `stage "${entry.id}"` });
+                if (!merged.ok)
+                    return loadFailure(merged.issues);
+                stage = { ...stage, requires: merged.value };
+            }
+            stages.push(stage);
             stageSources[stageId] = { kind: "inline" };
             continue;
         }
@@ -229,10 +237,19 @@ async function buildLoadedPipelineFromMerge(merge, options) {
                 },
             ]);
         }
+        let stageRequires = stageOutcome.value.requires;
+        if (entry.requires !== undefined) {
+            const merged = mergeToolRequires([stageRequires, entry.requires], { pipelineId, label: `stage "${entry.id}"` });
+            if (!merged.ok)
+                return loadFailure(merged.issues);
+            stageRequires = merged.value;
+        }
         const stage = {
             ...stageOutcome.value,
             ...(entry.skill !== undefined ? { skill: entry.skill } : {}),
             ...(entry.mcp !== undefined ? { mcp: entry.mcp } : {}),
+            ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
+            ...(stageRequires !== undefined ? { requires: stageRequires } : {}),
         };
         stages.push(stage);
         stageSources[stageId] = { kind: "file", path: entry.body.absolutePath };
@@ -282,7 +299,11 @@ async function buildLoadedPipelineFromMerge(merge, options) {
         ...(pipelineAgent !== undefined ? { agent: pipelineAgent } : {}),
         ...(pipelineModel !== undefined ? { model: pipelineModel } : {}),
         ...(pipelineSchemas !== undefined ? { schemas: pipelineSchemas } : {}),
+        ...(pipelineRequires !== undefined ? { requires: pipelineRequires } : {}),
     };
+    const effectiveRequires = mergeToolRequires([pipelineRequires, ...loadedStages.map((s) => s.requires)], { pipelineId });
+    if (!effectiveRequires.ok)
+        return loadFailure(effectiveRequires.issues);
     const nodeById = new Map(dag.nodes.map((node) => [node.id, node]));
     for (const [stageId, after] of fileAfterById) {
         const node = nodeById.get(stageId);

package/dist/config/loadStage.js

@@ -7,6 +7,8 @@ import { parseModelField } from "./modelField.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { parseStageSecrets } from "../runtime/stageSecretDecl.js";
+import { parseToolRequires } from "./toolRequires.js";
 import { classifyYamlDocument, compileTargetContract, dialectFromKeys, mixedDialectIssue, STAGE_FILE_WIRING_KEYS, } from "./yamlDialect.js";
 const afterCompletionByStage = new WeakMap();
 /** After-phase IR from target `verify` (`when` includes after). Stamped onto DAG `completion`. */
@@ -348,6 +350,22 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs, requireIo, compi
     if (mcpOutcome.value !== undefined) {
         stage.mcp = mcpOutcome.value;
     }
+    const secretsOutcome = parseStageSecrets(raw.secrets, label, entryId);
+    if (!secretsOutcome.ok)
+        return secretsOutcome;
+    if (secretsOutcome.value !== undefined) {
+        stage.secrets = secretsOutcome.value;
+    }
+    const requiresOutcome = parseToolRequires(raw.requires, `stage ${label}`, {
+        code: "stage.invalid_requires",
+        category: "stage",
+        stageId: entryId,
+    });
+    if (!requiresOutcome.ok)
+        return requiresOutcome;
+    if (requiresOutcome.value !== undefined) {
+        stage.requires = requiresOutcome.value;
+    }
     const agentField = parseAgentField(raw.agent);
     if (!agentField.ok) {
         return loadFailure([

package/dist/config/loadTask.d.ts

@@ -1,5 +1,7 @@
 import type { TaskFile } from "../types/task.js";
 import { type LoadOutcome } from "./loadOutcome.js";
+/** Structural TaskFile shape only — does not enforce workspace binding XOR. */
+export declare function coerceTaskFile(raw: unknown): TaskFile | undefined;
 export declare function parseTaskFile(raw: unknown, source?: string): LoadOutcome<TaskFile>;
 export declare function loadTaskFromYamlOutcome(yamlText: string, source?: string): LoadOutcome<TaskFile>;
 export declare function loadTaskOutcome(filePath: string): Promise<LoadOutcome<TaskFile>>;

package/dist/config/loadTask.js

@@ -1,12 +1,60 @@
 import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
+import { resolveWorkspaceBinding } from "../runtime/workspaceBinding.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-export function parseTaskFile(raw, source = "task") {
+function parseGitIdentity(raw) {
+    if (!isPlainObject(raw))
+        return undefined;
+    const identity = {};
+    if (typeof raw.name === "string")
+        identity.name = raw.name;
+    if (typeof raw.email === "string")
+        identity.email = raw.email;
+    return identity;
+}
+/** Structural TaskFile shape only — does not enforce workspace binding XOR. */
+export function coerceTaskFile(raw) {
     const record = raw;
     if (typeof record?.id !== "string" || typeof record?.goal !== "string") {
+        return undefined;
+    }
+    if (record.input !== undefined && !isPlainObject(record.input)) {
+        return undefined;
+    }
+    return {
+        id: record.id,
+        goal: record.goal,
+        context: typeof record.context === "string" ? record.context : undefined,
+        constraints: typeof record.constraints === "string" ? record.constraints : undefined,
+        checkout: typeof record.checkout === "string" ? record.checkout : undefined,
+        ...(typeof record.repository === "string" ? { repository: record.repository } : {}),
+        ...(typeof record.ref === "string" ? { ref: record.ref } : {}),
+        ...(typeof record.run_branch_template === "string"
+            ? { run_branch_template: record.run_branch_template }
+            : {}),
+        ...(isPlainObject(record.git_identity)
+            ? { git_identity: parseGitIdentity(record.git_identity) }
+            : {}),
+        ...(record.input !== undefined ? { input: record.input } : {}),
+    };
+}
+export function parseTaskFile(raw, source = "task") {
+    const record = raw;
+    const task = coerceTaskFile(raw);
+    if (task === undefined) {
+        if (typeof record?.id === "string" && typeof record?.goal === "string") {
+            return loadFailure([
+                {
+                    code: "task.invalid_shape",
+                    message: `Invalid ${source}: input must be an object`,
+                    category: "task",
+                    taskId: record.id,
+                },
+            ]);
+        }
         return loadFailure([
             {
                 code: "task.invalid_shape",
@@ -16,24 +64,15 @@ export function parseTaskFile(raw, source = "task") {
             },
         ]);
     }
-    if (record.input !== undefined && !isPlainObject(record.input)) {
-        return loadFailure([
-            {
-                code: "task.invalid_shape",
-                message: `Invalid ${source}: input must be an object`,
-                category: "task",
-                taskId: record.id,
-            },
-        ]);
+    const binding = resolveWorkspaceBinding(task);
+    if (!binding.ok) {
+        return loadFailure(binding.issues.map((issue) => {
+            if (issue.category !== "task")
+                return issue;
+            return { ...issue, taskId: task.id };
+        }));
     }
-    return loadSuccess({
-        id: record.id,
-        goal: record.goal,
-        context: typeof record.context === "string" ? record.context : undefined,
-        constraints: typeof record.constraints === "string" ? record.constraints : undefined,
-        checkout: typeof record.checkout === "string" ? record.checkout : undefined,
-        ...(record.input !== undefined ? { input: record.input } : {}),
-    });
+    return loadSuccess(task);
 }
 export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {
     let raw;

package/dist/config/materializeStageModels.js

@@ -29,7 +29,11 @@ export async function materializeStageModels(stages, options) {
         if (!modelOutcome.ok) {
             return loadFailure(modelOutcome.issues);
         }
-        materialized.push({ ...stage, model: modelOutcome.value });
+        materialized.push({
+            ...stage,
+            model: modelOutcome.value.model,
+            model_tier: modelOutcome.value.tier,
+        });
     }
     return loadSuccess(materialized);
 }

package/dist/config/mergePipelineIncludes.d.ts

@@ -1,6 +1,7 @@
 import type { PayloadSchemaMap } from "../envelope/payloadSchema.js";
 import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
+import { type ToolRequirement } from "./toolRequires.js";
 export type RawMergedEntry = {
     raw: unknown;
     declaringPath: string;
@@ -11,6 +12,7 @@ export declare function mergePipelineStages(rootPath: string): Promise<LoadOutco
     agent?: string;
     model?: string;
     schemas?: PayloadSchemaMap;
+    requires?: ToolRequirement[];
     warnings: LoadIssue[];
 }>>;
 /** Synthetic `declaringPath` for stage entries with no backing file. */
@@ -21,5 +23,6 @@ export declare function mergeInlinePipelineStages(raw: InlinePipelineDefinition)
     agent?: string;
     model?: string;
     schemas?: PayloadSchemaMap;
+    requires?: ToolRequirement[];
     warnings: LoadIssue[];
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -4,6 +4,7 @@ import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parseModelField } from "./modelField.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { parseToolRequires } from "./toolRequires.js";
 import { classifyYamlDocument, collectDocumentKeys, mixedDialectIssue, } from "./yamlDialect.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -177,6 +178,14 @@ export async function mergePipelineStages(rootPath) {
     if (!schemasOutcome.ok)
         return schemasOutcome;
     const schemas = schemasOutcome.value;
+    const requiresOutcome = parseToolRequires(raw.requires, `pipeline ${absRoot}`, {
+        code: "pipeline.invalid_requires",
+        category: "pipeline",
+        pipelineId,
+    });
+    if (!requiresOutcome.ok)
+        return requiresOutcome;
+    const requires = requiresOutcome.value;
     const idLocations = new Map();
     const entries = [];
     const warnings = [];
@@ -198,6 +207,7 @@ export async function mergePipelineStages(rootPath) {
         ...(agent !== undefined ? { agent } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
+        ...(requires !== undefined ? { requires } : {}),
         warnings,
     });
 }
@@ -252,6 +262,14 @@ export async function mergeInlinePipelineStages(raw) {
     if (!schemasOutcome.ok)
         return schemasOutcome;
     const schemas = schemasOutcome.value;
+    const requiresOutcome = parseToolRequires(raw.requires, `inline pipeline ${pipelineId}`, {
+        code: "pipeline.invalid_requires",
+        category: "pipeline",
+        pipelineId,
+    });
+    if (!requiresOutcome.ok)
+        return requiresOutcome;
+    const requires = requiresOutcome.value;
     const entries = [];
     for (let index = 0; index < raw.stages.length; index++) {
         const entry = raw.stages[index];
@@ -273,6 +291,7 @@ export async function mergeInlinePipelineStages(raw) {
         ...(agent !== undefined ? { agent } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
+        ...(requires !== undefined ? { requires } : {}),
         warnings: [],
     });
 }

package/dist/config/migrateYaml.js

@@ -1,7 +1,8 @@
-import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { runGitSync } from "../git/exec.js";
+import { statusPorcelain } from "../git/operations.js";
 import { loadPipelineOutcome } from "./loadPipeline.js";
 import { afterCompletionForStage, loadStageOutcome } from "./loadStage.js";
 import { withLegacyYamlAllowedAsync } from "./legacyYaml.js";
@@ -104,11 +105,10 @@ function verifyFingerprint(items) {
 }
 function gitToplevel(cwd) {
     try {
-        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        return runGitSync({
             cwd,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
+            args: ["rev-parse", "--show-toplevel"],
+        }).stdout.trim();
     }
     catch {
         return null;
@@ -119,12 +119,7 @@ export function fileDirtyVsHead(absPath) {
     if (top === null)
         return true;
     try {
-        const status = execFileSync("git", ["status", "--porcelain", "--", absPath], {
-            cwd: top,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return status.trim().length > 0;
+        return statusPorcelain(top, absPath).trim().length > 0;
     }
     catch {
         return true;

package/dist/config/multiProjectCatalog.d.ts

@@ -0,0 +1,30 @@
+import { type PipelineListing, type TaskListing } from "./browseCatalog.js";
+import { type CatalogRoot, type ResolveCatalogRootsOptions } from "./resolveCatalogRoots.js";
+export type CatalogRootError = {
+    project_root: string;
+    code: "catalog_root_unreadable" | "unknown_project_root";
+    message: string;
+};
+export type MultiProjectListResult<T> = {
+    items: T[];
+    root_errors: CatalogRootError[];
+    roots: CatalogRoot[];
+};
+export declare function listPipelinesMultiProject(options: ResolveCatalogRootsOptions & {
+    projectRootFilter?: string;
+}): Promise<MultiProjectListResult<PipelineListing & {
+    project_root: string;
+}>>;
+export declare function listTasksMultiProject(options: ResolveCatalogRootsOptions & {
+    projectRootFilter?: string;
+}): Promise<MultiProjectListResult<TaskListing & {
+    project_root: string;
+}>>;
+export declare function listModelsMultiProject(options: ResolveCatalogRootsOptions & {
+    projectRootFilter?: string;
+}): Promise<MultiProjectListResult<{
+    id: string;
+    project_root: string;
+}> & {
+    models: string[];
+}>;

package/dist/config/multiProjectCatalog.js

@@ -0,0 +1,142 @@
+import { listModelsForContext, listPipelinesForContext, listTasksForContext, } from "./browseCatalog.js";
+import { loadStageflowManifestOutcome, } from "./loadStageflowManifest.js";
+import { findCatalogRoot, isRootReadable, resolveCatalogRoots, } from "./resolveCatalogRoots.js";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+async function catalogContextForRoot(root) {
+    if (root.kind === "seeded") {
+        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: [],
+        };
+    }
+    return catalogContextFromStageflow(await resolveStageflowContext(root.path));
+}
+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 };
+}
+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 { 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 { 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,8 @@
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseStageMcp } from "./loadStage.js";
+import { parseStageSecrets } from "../runtime/stageSecretDecl.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 +41,11 @@ 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");
 }
 function readSkill(raw) {
     if (raw.skill === undefined)
@@ -112,6 +118,17 @@ 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;
         if (uses && hasBody) {
             return loadFailure([
                 {
@@ -339,6 +356,8 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             ...(entryFlag !== undefined ? { entry: entryFlag } : {}),
             ...(skill !== undefined ? { skill } : {}),
             ...(mcp !== undefined ? { mcp } : {}),
+            ...(secrets !== undefined ? { secrets } : {}),
+            ...(requires !== undefined ? { requires } : {}),
             ...(cloneCap !== undefined ? { clone_cap: cloneCap } : {}),
             ...(cloneMode !== undefined ? { clone_mode: cloneMode } : {}),
         };

package/dist/config/pipelineStageKeys.js

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

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);
+}