stageflow 0.32.0 → 0.35.0

package/dist/config/installSkillRequest.js

@@ -0,0 +1,286 @@
+import { access, mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { installProjectSkill, } from "../cli/skillsCommand.js";
+import { runGit } from "../git/exec.js";
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function tokenizeCommand(command) {
+    return command.trim().split(/\s+/).filter((part) => part.length > 0);
+}
+export function parseSkillsAddCommand(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, status: 400, error: "command must be a non-empty string" };
+    }
+    const tokens = tokenizeCommand(trimmed);
+    let rest;
+    if (tokens[0] === "npx" && tokens[1] === "skills" && tokens[2] === "add") {
+        rest = tokens.slice(3);
+    }
+    else if (tokens[0] === "skills" && tokens[1] === "add") {
+        rest = tokens.slice(2);
+    }
+    else {
+        return {
+            ok: false,
+            status: 400,
+            error: "command must be 'npx skills add <source> [--skill <name>]' or 'skills add …'",
+        };
+    }
+    let source;
+    let skillName;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--skill") {
+            const value = rest[++i];
+            if (value === undefined || value.length === 0) {
+                return { ok: false, status: 400, error: "missing value for --skill" };
+            }
+            if (value.startsWith("-")) {
+                return { ok: false, status: 400, error: "missing value for --skill" };
+            }
+            skillName = value;
+        }
+        else if (arg.startsWith("-")) {
+            return { ok: false, status: 400, error: `unknown flag: ${arg}` };
+        }
+        else if (source === undefined) {
+            source = arg;
+        }
+        else {
+            return { ok: false, status: 400, error: `unexpected argument: ${arg}` };
+        }
+    }
+    if (source === undefined) {
+        return { ok: false, status: 400, error: "missing skill source after 'add'" };
+    }
+    return {
+        source,
+        ...(skillName !== undefined ? { skillName } : {}),
+    };
+}
+export function parseInstallSkillBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "Request body must be an object" };
+    }
+    if (typeof body.command !== "string" || body.command.trim().length === 0) {
+        return { ok: false, status: 400, error: "command must be a non-empty string" };
+    }
+    const parsed = parseSkillsAddCommand(body.command);
+    if ("ok" in parsed) {
+        return parsed;
+    }
+    return { command: body.command.trim() };
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readFrontmatterName(skillMdPath) {
+    try {
+        const raw = await readFile(skillMdPath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+        if (!match)
+            return undefined;
+        const nameLine = /^name:\s*(.+)\s*$/m.exec(match[1] ?? "");
+        const value = nameLine?.[1]?.trim();
+        if (value === undefined || value.length === 0)
+            return undefined;
+        return value.replace(/^['"]|['"]$/g, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function locateSkillDirectory(checkoutRoot, skillName) {
+    const candidates = [];
+    const seen = new Set();
+    const pushCandidate = (name, root) => {
+        const key = path.resolve(root);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        candidates.push({ name, root: key });
+    };
+    const rootSkillMd = path.join(checkoutRoot, "SKILL.md");
+    if (await pathExists(rootSkillMd)) {
+        const name = (await readFrontmatterName(rootSkillMd)) ?? path.basename(path.resolve(checkoutRoot));
+        pushCandidate(name, checkoutRoot);
+    }
+    let entries;
+    try {
+        entries = await readdir(checkoutRoot, { withFileTypes: true });
+    }
+    catch {
+        throw new Error("skill source directory not found");
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "skills") {
+            continue;
+        }
+        const skillMd = path.join(checkoutRoot, entry.name, "SKILL.md");
+        if (await pathExists(skillMd)) {
+            pushCandidate(entry.name, path.join(checkoutRoot, entry.name));
+        }
+    }
+    const skillsDir = path.join(checkoutRoot, "skills");
+    try {
+        const skillsStat = await stat(skillsDir);
+        if (skillsStat.isDirectory()) {
+            const skillEntries = await readdir(skillsDir, { withFileTypes: true });
+            for (const entry of skillEntries) {
+                if (!entry.isDirectory())
+                    continue;
+                const skillMd = path.join(skillsDir, entry.name, "SKILL.md");
+                if (await pathExists(skillMd)) {
+                    pushCandidate(entry.name, path.join(skillsDir, entry.name));
+                }
+            }
+        }
+    }
+    catch {
+        // no skills/ directory
+    }
+    if (skillName !== undefined) {
+        const namedPaths = [
+            path.join(checkoutRoot, skillName, "SKILL.md"),
+            path.join(checkoutRoot, "skills", skillName, "SKILL.md"),
+        ];
+        for (const skillMd of namedPaths) {
+            if (await pathExists(skillMd)) {
+                return { name: skillName, root: path.dirname(skillMd) };
+            }
+        }
+        const match = candidates.find((candidate) => candidate.name === skillName);
+        if (match !== undefined) {
+            return match;
+        }
+        throw new Error(`skill "${skillName}" not found in source`);
+    }
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    if (candidates.length === 0) {
+        throw new Error("no SKILL.md found in source");
+    }
+    const names = candidates.map((candidate) => candidate.name).join(", ");
+    throw new Error(`multiple skills found (${names}); pass --skill <name>`);
+}
+export function resolveGitCloneUrl(source) {
+    const githubHttps = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?(?:\/|$)/i.exec(source);
+    if (githubHttps) {
+        return `https://github.com/${githubHttps[1]}/${githubHttps[2]}.git`;
+    }
+    if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(source)) {
+        return `https://github.com/${source}.git`;
+    }
+    throw new Error("source must be a GitHub HTTPS URL, owner/repo slug, or file: URL");
+}
+export async function defaultCloneSkillRepo(cloneUrl, destDir) {
+    await runGit({
+        args: ["clone", "--depth", "1", "--single-branch", cloneUrl, destDir],
+        timeoutMs: 120_000,
+    });
+}
+function resolveFileSource(source) {
+    if (source.startsWith("file:")) {
+        return fileURLToPath(source);
+    }
+    throw new Error("source must be a GitHub HTTPS URL, owner/repo slug, or file: URL");
+}
+export async function installSkillFromCommand(input) {
+    const parsed = parseSkillsAddCommand(input.command);
+    if ("ok" in parsed) {
+        return { ok: false, error: parsed.error, status: parsed.status };
+    }
+    let cleanup;
+    try {
+        let checkoutRoot;
+        if (parsed.source.startsWith("file:")) {
+            checkoutRoot = resolveFileSource(parsed.source);
+            try {
+                const sourceStat = await stat(checkoutRoot);
+                if (!sourceStat.isDirectory()) {
+                    return { ok: false, error: "skill source path not found", status: 400 };
+                }
+            }
+            catch {
+                return { ok: false, error: "skill source path not found", status: 400 };
+            }
+        }
+        else {
+            let cloneUrl;
+            try {
+                cloneUrl = resolveGitCloneUrl(parsed.source);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                    status: 400,
+                };
+            }
+            const tempRoot = await mkdtemp(path.join(tmpdir(), "sf-skill-clone-"));
+            cleanup = async () => {
+                await rm(tempRoot, { recursive: true, force: true });
+            };
+            const cloneDest = path.join(tempRoot, "repo");
+            const cloneRepo = input.cloneRepo ?? defaultCloneSkillRepo;
+            await cloneRepo(cloneUrl, cloneDest);
+            checkoutRoot = cloneDest;
+        }
+        const located = await locateSkillDirectory(checkoutRoot, parsed.skillName);
+        const result = await installProjectSkill({
+            projectRoot: input.projectRoot,
+            fromPath: located.root,
+            skillName: located.name,
+            io: {
+                log: () => undefined,
+                error: () => undefined,
+            },
+        });
+        if (!result.ok) {
+            return {
+                ok: false,
+                error: result.error,
+                ...(result.doctorFailed ? { doctorFailed: true, status: 422 } : { status: 400 }),
+            };
+        }
+        return {
+            ok: true,
+            skill_name: result.skillName,
+            dest_path: result.destPath,
+            project_root: input.projectRoot,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+            status: 400,
+        };
+    }
+    finally {
+        if (cleanup !== undefined) {
+            await cleanup();
+        }
+    }
+}
+/** Test helper: build a file: command for a local skill tree. */
+export function skillsAddFileCommand(fromPath, skillName) {
+    const source = pathToFileURL(path.resolve(fromPath)).href;
+    if (skillName === undefined) {
+        return `npx skills add ${source}`;
+    }
+    return `npx skills add ${source} --skill ${skillName}`;
+}

package/dist/config/listConfig.d.ts

@@ -1,28 +1,12 @@
-import type { StageGateKind } from "../types/stage.js";
 import type { LoadedManifest } from "../types/stageflowManifest.js";
 import { type PipelineListing, type TaskListing } from "./browseCatalog.js";
 import { type StageflowContext } from "../project/resolveStageflowContext.js";
 import { type CatalogContext } from "./resolveCatalogContext.js";
 export type { PipelineListing, PipelineStageListing, TaskListing } from "./browseCatalog.js";
-export type ValidStageListing = {
-    path: string;
-    id: string;
-    used_by_pipeline_ids: string[];
-    gate_kinds?: StageGateKind[];
-};
-export type BrokenStageListing = {
-    path: string;
-    error: string;
-    id?: string;
-    model?: string;
-    gate_kinds?: StageGateKind[];
-};
-export type StageListing = ValidStageListing | BrokenStageListing;
 export type CatalogListOptions = {
     projectRoot: string;
     manifest: LoadedManifest;
 };
 export declare function listTasks(options: CatalogListOptions): Promise<TaskListing[]>;
 export declare function listPipelines(options: CatalogListOptions): Promise<PipelineListing[]>;
-export declare function listStages(_options?: unknown): Promise<StageListing[]>;
 export declare function listModels(cwdOrContext: string | CatalogContext | StageflowContext): Promise<string[]>;

package/dist/config/listConfig.js

@@ -17,9 +17,6 @@ export async function listPipelines(options) {
         issues: [],
     });
 }
-export async function listStages(_options) {
-    return [];
-}
 export async function listModels(cwdOrContext) {
     const ctx = typeof cwdOrContext === "string"
         ? catalogContextFromStageflow(await resolveStageflowContext(cwdOrContext))

package/dist/config/loadOutcome.d.ts

@@ -1,32 +1,36 @@
 import type { ValidationFindingCode } from "./validateCatalog.js";
 export type TaskLoadCode = "task.invalid_shape" | "task.load_error" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid";
 export type TriggerLoadCode = "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task";
-export type LoadIssue = {
+type LoadIssueLocation = {
+    line?: number;
+    column?: number;
+};
+export type LoadIssue = ({
     code: ValidationFindingCode;
     message: string;
     category: "pipeline";
     pipelineId?: string;
     stageId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: ValidationFindingCode;
     message: string;
     category: "stage";
     stageId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: TaskLoadCode;
     message: string;
     category: "task";
     taskId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: TriggerLoadCode;
     message: string;
     category: "trigger";
     triggerId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: ValidationFindingCode | string;
     message: string;
     category: "catalog";
-};
+} & LoadIssueLocation);
 export type LoadOutcome<T> = {
     ok: true;
     value: T;
@@ -37,3 +41,4 @@ export type LoadOutcome<T> = {
 };
 export declare function loadFailure<T>(issues: LoadIssue[]): LoadOutcome<T>;
 export declare function loadSuccess<T>(value: T, issues?: LoadIssue[]): LoadOutcome<T>;
+export {};

package/dist/config/loadPipeline.js

@@ -262,7 +262,6 @@ async function buildLoadedPipelineFromMerge(merge, options) {
         const stage = {
             ...stageOutcome.value,
             ...(browser !== undefined ? { browser } : {}),
-            ...(entry.skill !== undefined ? { skill: entry.skill } : {}),
             ...(entry.mcp !== undefined ? { mcp: entry.mcp } : {}),
             ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
             ...(stageRequires !== undefined ? { requires: stageRequires } : {}),

package/dist/config/loadStage.js

@@ -7,6 +7,7 @@ import { parseModelField } from "./modelField.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 import { z } from "zod";
 import { parseStageSecrets } from "../runtime/stageSecretDecl.js";
 import { parseToolRequires } from "./toolRequires.js";
@@ -436,6 +437,7 @@ export async function loadStageOutcome(filePath, options = {}) {
                 code: "stage.load_error",
                 message,
                 category: "stage",
+                ...yamlParsePosition(err),
             },
         ]);
     }

package/dist/config/loadStageflowManifest.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 import { parseModelField } from "./modelField.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
@@ -87,7 +88,9 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return loadFailure([catalogIssue("catalog.manifest_load_error", message)]);
+        return loadFailure([
+            { ...catalogIssue("catalog.manifest_load_error", message), ...yamlParsePosition(err) },
+        ]);
     }
     const issues = [];
     const record = raw;

package/dist/config/loadTask.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 import { resolveWorkspaceBinding } from "../runtime/workspaceBinding.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -86,6 +87,7 @@ export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {
                 code: "task.load_error",
                 message,
                 category: "task",
+                ...yamlParsePosition(err),
             },
         ]);
     }

package/dist/config/loadTrigger.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -84,6 +85,7 @@ export function loadTriggerFromYamlOutcome(yamlText, source = "trigger yaml") {
                 code: "trigger.load_error",
                 message,
                 category: "trigger",
+                ...yamlParsePosition(err),
             },
         ]);
     }

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 { yamlParsePosition } from "./yamlParsePosition.js";
 import { parseToolRequires } from "./toolRequires.js";
 import { classifyYamlDocument, collectDocumentKeys, mixedDialectIssue, } from "./yamlDialect.js";
 function isPlainObject(value) {
@@ -39,6 +40,7 @@ async function visitPipelineFile(filePath, stack, idLocations, entries, warnings
                 code: "pipeline.load_error",
                 message,
                 category: "pipeline",
+                ...yamlParsePosition(err),
             },
         ]);
     }
@@ -128,6 +130,7 @@ export async function mergePipelineStages(rootPath) {
                 code: "pipeline.load_error",
                 message,
                 category: "pipeline",
+                ...yamlParsePosition(err),
             },
         ]);
     }

package/dist/config/normalizePipelineStageEntry.js

@@ -43,7 +43,6 @@ function extractBodyRaw(raw) {
 }
 function hasBodyKey(raw) {
     return Object.keys(raw).some((key) => BODY_KEYS.has(key) &&
-        key !== "skill" &&
         key !== "mcp" &&
         key !== "secrets" &&
         key !== "requires" &&
@@ -116,6 +115,16 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             return skillOutcome;
         }
         const skill = skillOutcome?.ok ? skillOutcome.value : undefined;
+        if (uses && skill !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.stage_wrapper_skill_rejected",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage entry at index ${index} sets skill: on a uses: wrapper; put skill: on the stage file (${uses}) instead`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
         const mcpOutcome = parseStageMcp(raw.mcp, `entry at index ${index} in ${declaringPath}`);
         if (!mcpOutcome.ok)
             return mcpOutcome;

package/dist/config/printTargetYaml.js

@@ -163,7 +163,6 @@ const STAGE_BODY_ORDER = [
 const PIPELINE_WIRING_ORDER = [
     "id",
     "uses",
-    "skill",
     "mcp",
     "needs",
     "fork",

package/dist/config/publishDraftPackage.d.ts

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

package/dist/config/publishDraftPackage.js

@@ -1,6 +1,6 @@
 import { createDraftPackage, overwriteDraftPackage, } from "./draftPackage.js";
 import { ensureCatalogScanRoot } from "./ensureCatalogScanRoot.js";
-export async function publishDraftPackage(projectRoot, input, mode) {
+export async function publishDraftPackage(projectRoot, input, mode, options = {}) {
     let write;
     if (mode === "create") {
         write = await createDraftPackage(projectRoot, input);
@@ -20,6 +20,9 @@ export async function publishDraftPackage(projectRoot, input, mode) {
     if (!write.ok) {
         return { write, catalogChanged: false };
     }
+    if (options.catalogRootKind === "workspace") {
+        return { write, catalogChanged: false };
+    }
     const catalogChanged = await ensureCatalogScanRoot(projectRoot, input.directory);
     return { write, catalogChanged };
 }

package/dist/config/resolveCatalogRoots.d.ts

@@ -1,5 +1,5 @@
 import type { RunStore } from "../runstore/port.js";
-export type CatalogRootKind = "registered" | "seeded";
+export type CatalogRootKind = "registered" | "seeded" | "workspace";
 export type CatalogRoot = {
     /** Wire id: absolute path for registered; symbolic id for seeded (e.g. "examples"). */
     project_root: string;
@@ -7,6 +7,9 @@ export type CatalogRoot = {
     path: string;
     kind: CatalogRootKind;
     read_only: boolean;
+    /** False when workspace provisioning failed at boot. */
+    available?: boolean;
+    unavailable_reason?: string;
 };
 export type ResolveCatalogRootsOptions = {
     store: RunStore;

package/dist/config/resolveCatalogRoots.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { realpathSync, constants } from "node:fs";
 import { access } from "node:fs/promises";
+import { WORKSPACE_CATALOG_ID, lastWorkspaceProvisionResult, workspaceCatalogPath, } from "../project/workspaceCatalog.js";
 function realOrResolve(p) {
     const resolved = path.resolve(p);
     try {
@@ -19,6 +20,7 @@ export async function resolveCatalogRoots(options) {
     const seenPaths = new Set();
     const seededRoots = options.seededRoots ??
         (await import("./seededCatalog.js")).defaultSeededRoots();
+    const workspaceAbs = realOrResolve(workspaceCatalogPath());
     let registered = [];
     try {
         registered = await options.store.listRegisteredProjects();
@@ -28,7 +30,7 @@ export async function resolveCatalogRoots(options) {
     }
     for (const root of registered) {
         const abs = realOrResolve(root);
-        if (seenPaths.has(abs))
+        if (seenPaths.has(abs) || abs === workspaceAbs)
             continue;
         seenPaths.add(abs);
         roots.push({
@@ -38,6 +40,21 @@ export async function resolveCatalogRoots(options) {
             read_only: false,
         });
     }
+    if (!seenPaths.has(workspaceAbs)) {
+        seenPaths.add(workspaceAbs);
+        const provision = lastWorkspaceProvisionResult();
+        const available = provision === undefined || provision.ok;
+        roots.push({
+            project_root: WORKSPACE_CATALOG_ID,
+            path: workspaceCatalogPath(),
+            kind: "workspace",
+            read_only: false,
+            available,
+            ...(provision !== undefined && !provision.ok && provision.reason
+                ? { unavailable_reason: provision.reason }
+                : {}),
+        });
+    }
     for (const seeded of seededRoots) {
         const abs = realOrResolve(seeded.path);
         if (seenPaths.has(abs))

package/dist/config/skillUsageIndex.d.ts

@@ -0,0 +1,6 @@
+export type SkillUsageEntry = {
+    stage_ids: string[];
+    pipeline_ids: string[];
+};
+export type SkillUsageIndex = Record<string, SkillUsageEntry>;
+export declare function buildSkillUsageIndex(cwd: string): Promise<SkillUsageIndex | null>;

package/dist/config/skillUsageIndex.js

@@ -0,0 +1,39 @@
+import { loadPipelineOutcome } from "./loadPipeline.js";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+function addUsage(index, skillName, pipelineId, stageId) {
+    const entry = index[skillName] ?? { stage_ids: [], pipeline_ids: [] };
+    if (!entry.pipeline_ids.includes(pipelineId)) {
+        entry.pipeline_ids.push(pipelineId);
+        entry.pipeline_ids.sort((a, b) => a.localeCompare(b));
+    }
+    if (!entry.stage_ids.includes(stageId)) {
+        entry.stage_ids.push(stageId);
+        entry.stage_ids.sort((a, b) => a.localeCompare(b));
+    }
+    index[skillName] = entry;
+}
+export async function buildSkillUsageIndex(cwd) {
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return null;
+    }
+    const index = {};
+    const loadCwd = ctx.projectRoot ?? cwd;
+    for (const pipelinePath of scanPaths.pipelinePaths) {
+        const outcome = await loadPipelineOutcome(pipelinePath, { cwd: loadCwd });
+        if (!outcome.ok) {
+            continue;
+        }
+        const pipelineId = outcome.value.pipeline.id;
+        for (const stage of outcome.value.stages) {
+            if (stage.skill === undefined) {
+                continue;
+            }
+            addUsage(index, stage.skill, pipelineId, stage.id);
+        }
+    }
+    return index;
+}