stageflow 0.32.0 → 0.35.0

package/dist/config/workshopCatalogRepair.js

@@ -0,0 +1,144 @@
+import { readdir, rename, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { readYamlObject } from "./readYamlObject.js";
+import { canonicalCatalogBasenameForDocument, isMisnamedCatalogBasename, legacyBareCatalogFilenames, normalizePipelineCatalogFilename, normalizeTaskCatalogFilename, reconcileWorkshopCatalogFilenames, } from "./workshopCatalogFilenames.js";
+async function fileExists(absPath) {
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function renameIfNeeded(fromAbs, toAbs, renamed) {
+    if (fromAbs === toAbs)
+        return;
+    if (!(await fileExists(fromAbs)))
+        return;
+    if (await fileExists(toAbs)) {
+        await rm(fromAbs, { force: true });
+        return;
+    }
+    await rename(fromAbs, toAbs);
+    renamed.push({
+        from: path.basename(fromAbs),
+        to: path.basename(toAbs),
+    });
+}
+export async function repairMisnamedWorkshopCatalogFiles(packageDirectory) {
+    const renamed = [];
+    const removed = [];
+    let entries;
+    try {
+        entries = await readdir(packageDirectory);
+    }
+    catch {
+        return { renamed, removed };
+    }
+    for (const entry of entries) {
+        if (!isMisnamedCatalogBasename(entry))
+            continue;
+        const absPath = path.join(packageDirectory, entry);
+        let raw;
+        try {
+            raw = await readYamlObject(absPath);
+        }
+        catch {
+            continue;
+        }
+        const canonical = canonicalCatalogBasenameForDocument(raw, entry);
+        if (!canonical || canonical === entry)
+            continue;
+        const targetAbs = path.join(packageDirectory, canonical);
+        await renameIfNeeded(absPath, targetAbs, renamed);
+    }
+    return { renamed, removed };
+}
+export async function reconcileWorkshopCatalogPackageDir(packageDirectory, pipelineId, taskId, options) {
+    const result = await repairMisnamedWorkshopCatalogFiles(packageDirectory);
+    const pipelineBasename = options?.pipelineBasename?.trim() ||
+        normalizePipelineCatalogFilename(pipelineId);
+    const taskBasename = taskId?.trim()
+        ? options?.taskBasename?.trim() ||
+            normalizeTaskCatalogFilename(taskId)
+        : null;
+    for (const legacy of legacyBareCatalogFilenames(pipelineId)) {
+        if (legacy === pipelineBasename)
+            continue;
+        const legacyAbs = path.join(packageDirectory, legacy);
+        const canonicalAbs = path.join(packageDirectory, pipelineBasename);
+        if (!(await fileExists(legacyAbs)))
+            continue;
+        if (!(await fileExists(canonicalAbs))) {
+            let raw;
+            try {
+                raw = await readYamlObject(legacyAbs);
+            }
+            catch {
+                continue;
+            }
+            if (canonicalCatalogBasenameForDocument(raw) === pipelineBasename) {
+                await renameIfNeeded(legacyAbs, canonicalAbs, result.renamed);
+                continue;
+            }
+        }
+        if (await fileExists(canonicalAbs)) {
+            await rm(legacyAbs, { force: true });
+            result.removed.push(legacy);
+        }
+    }
+    if (taskId?.trim() && taskBasename) {
+        for (const legacy of legacyBareCatalogFilenames(taskId)) {
+            if (legacy === taskBasename || legacy === pipelineBasename)
+                continue;
+            const legacyAbs = path.join(packageDirectory, legacy);
+            const canonicalAbs = path.join(packageDirectory, taskBasename);
+            if (!(await fileExists(legacyAbs)))
+                continue;
+            if (!(await fileExists(canonicalAbs))) {
+                let raw;
+                try {
+                    raw = await readYamlObject(legacyAbs);
+                }
+                catch {
+                    continue;
+                }
+                if (canonicalCatalogBasenameForDocument(raw) === taskBasename) {
+                    await renameIfNeeded(legacyAbs, canonicalAbs, result.renamed);
+                    continue;
+                }
+            }
+            if (await fileExists(canonicalAbs)) {
+                await rm(legacyAbs, { force: true });
+                result.removed.push(legacy);
+            }
+        }
+    }
+    const { removeCandidates } = reconcileWorkshopCatalogFilenames(pipelineId, taskId, pipelineBasename, taskBasename);
+    for (const legacy of removeCandidates) {
+        const legacyAbs = path.join(packageDirectory, legacy);
+        const canonicalAbs = path.join(packageDirectory, pipelineBasename);
+        if (!(await fileExists(legacyAbs)))
+            continue;
+        if (legacyAbs === canonicalAbs)
+            continue;
+        if (taskBasename && legacy === taskBasename)
+            continue;
+        if (!(await fileExists(canonicalAbs)))
+            continue;
+        await rm(legacyAbs, { force: true });
+        result.removed.push(legacy);
+    }
+    return result;
+}
+export async function repairWorkshopCatalogTree(projectRoot, relativeDirectories) {
+    const merged = { renamed: [], removed: [] };
+    for (const rel of relativeDirectories) {
+        const dir = path.resolve(projectRoot, rel);
+        const part = await repairMisnamedWorkshopCatalogFiles(dir);
+        merged.renamed.push(...part.renamed);
+        merged.removed.push(...part.removed);
+    }
+    return merged;
+}

package/dist/config/yamlParsePosition.d.ts

@@ -0,0 +1,4 @@
+export declare function yamlParsePosition(err: unknown): {
+    line: number;
+    column: number;
+} | undefined;

package/dist/config/yamlParsePosition.js

@@ -0,0 +1,9 @@
+import { YAMLParseError } from "yaml";
+export function yamlParsePosition(err) {
+    if (!(err instanceof YAMLParseError))
+        return undefined;
+    const pos = err.linePos?.[0];
+    if (!pos)
+        return undefined;
+    return { line: pos.line, column: pos.col };
+}

package/dist/hosted/containment.d.ts

@@ -0,0 +1,3 @@
+export declare function isContained(rootReal: string, candidateReal: string): boolean;
+export declare function resolveDirectory(root: string): Promise<string>;
+export declare function containedRealPath(rootReal: string, target: string): Promise<string>;

package/dist/hosted/containment.js

@@ -0,0 +1,36 @@
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+export function isContained(rootReal, candidateReal) {
+    const relative = path.relative(rootReal, candidateReal);
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)));
+}
+export async function resolveDirectory(root) {
+    const absolute = path.resolve(root);
+    let info;
+    try {
+        info = await stat(absolute);
+    }
+    catch {
+        throw new Error(`package root does not exist: ${absolute}`);
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`package root is not a directory: ${absolute}`);
+    }
+    return realpath(absolute);
+}
+export async function containedRealPath(rootReal, target) {
+    let real;
+    try {
+        real = await realpath(target);
+    }
+    catch {
+        throw new Error(`path is not readable: ${target}`);
+    }
+    if (!isContained(rootReal, real)) {
+        throw new Error(`path escapes package root: ${target}`);
+    }
+    return real;
+}

package/dist/hosted/errors.d.ts

@@ -0,0 +1,21 @@
+export declare const HOSTED_ERROR_CODES: readonly ["invalid_input", "package_invalid", "agent_failed", "event_sink_failed", "cancelled", "timed_out", "hitl_unsupported", "internal"];
+export type HostedErrorCode = (typeof HOSTED_ERROR_CODES)[number];
+export type HostedRuntimeErrorDetails = {
+    code: HostedErrorCode;
+    externalRunId: string;
+    externalAttemptId: string;
+    runId?: string;
+    eventType?: string;
+    sequence?: number;
+    localResult?: import("./types.js").HostedPipelineResult;
+};
+export declare class HostedRuntimeError extends Error {
+    readonly code: HostedErrorCode;
+    readonly externalRunId: string;
+    readonly externalAttemptId: string;
+    readonly runId?: string;
+    readonly eventType?: string;
+    readonly sequence?: number;
+    readonly localResult?: import("./types.js").HostedPipelineResult;
+    constructor(message: string, details: HostedRuntimeErrorDetails);
+}

package/dist/hosted/errors.js

@@ -0,0 +1,30 @@
+export const HOSTED_ERROR_CODES = [
+    "invalid_input",
+    "package_invalid",
+    "agent_failed",
+    "event_sink_failed",
+    "cancelled",
+    "timed_out",
+    "hitl_unsupported",
+    "internal",
+];
+export class HostedRuntimeError extends Error {
+    code;
+    externalRunId;
+    externalAttemptId;
+    runId;
+    eventType;
+    sequence;
+    localResult;
+    constructor(message, details) {
+        super(message);
+        this.name = "HostedRuntimeError";
+        this.code = details.code;
+        this.externalRunId = details.externalRunId;
+        this.externalAttemptId = details.externalAttemptId;
+        this.runId = details.runId;
+        this.eventType = details.eventType;
+        this.sequence = details.sequence;
+        this.localResult = details.localResult;
+    }
+}

package/dist/hosted/packageSkills.d.ts

@@ -0,0 +1,3 @@
+import { type SkillsPayload } from "../runtime/runSkills.js";
+/** Skills shipped with a hosted package live at `<packageRoot>/.pi/skills/<name>/`. */
+export declare function loadPackageSkills(packageRoot: string): Promise<SkillsPayload | undefined>;

package/dist/hosted/packageSkills.js

@@ -0,0 +1,80 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { assertValidSkillName, assertValidSkillRelativePath, validateSkillsPayload, } from "../runtime/runSkills.js";
+import { isContained } from "./containment.js";
+/** Skills shipped with a hosted package live at `<packageRoot>/.pi/skills/<name>/`. */
+export async function loadPackageSkills(packageRoot) {
+    const skillsRoot = path.join(packageRoot, ".pi", "skills");
+    let entries;
+    try {
+        entries = await readdir(skillsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const skillsRootReal = await realpath(skillsRoot);
+    if (!isContained(packageRoot, skillsRootReal)) {
+        throw new Error("package skills directory escapes the package root");
+    }
+    const skills = {};
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const nameCheck = assertValidSkillName(entry.name);
+        if (!nameCheck.ok)
+            throw new Error(nameCheck.reason);
+        const skillDir = path.join(skillsRoot, entry.name);
+        let info;
+        try {
+            info = await stat(skillDir);
+        }
+        catch {
+            continue;
+        }
+        if (!info.isDirectory())
+            continue;
+        const skillReal = await realpath(skillDir);
+        if (!isContained(skillsRootReal, skillReal)) {
+            throw new Error(`package skill "${entry.name}" escapes the package root`);
+        }
+        const files = await readSkillFiles(skillDir, skillReal);
+        if (files["SKILL.md"] === undefined)
+            continue;
+        skills[entry.name] = files;
+    }
+    if (Object.keys(skills).length === 0)
+        return undefined;
+    const validated = validateSkillsPayload(skills);
+    if (!validated.ok)
+        throw new Error(validated.reason);
+    return validated.skills;
+}
+async function readSkillFiles(skillDir, skillReal) {
+    const files = {};
+    await walk(skillDir);
+    return files;
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = path.join(dir, entry.name);
+            const rel = path.relative(skillDir, abs);
+            const real = await realpath(abs);
+            if (!isContained(skillReal, real)) {
+                throw new Error(`package skill file "${rel}" escapes the package root`);
+            }
+            const target = await stat(real);
+            if (target.isDirectory()) {
+                await walk(abs);
+                continue;
+            }
+            if (!target.isFile())
+                continue;
+            const pathCheck = assertValidSkillRelativePath(rel);
+            if (!pathCheck.ok)
+                throw new Error(pathCheck.reason);
+            files[rel] = await readFile(real, "utf8");
+        }
+    }
+}

package/dist/hosted/runtime.d.ts

@@ -0,0 +1,12 @@
+import type { StagePort } from "../agent/port.js";
+import type { RunStore } from "../runstore/port.js";
+import { type HostedEventSink, type HostedPipelineInput, type HostedPipelineResult } from "./types.js";
+export type HostedRuntime = {
+    run(input: HostedPipelineInput): Promise<HostedPipelineResult>;
+};
+export declare function createHostedRuntime(dependencies: {
+    agent: StagePort;
+    localStore: RunStore;
+    eventSink: HostedEventSink;
+    eventDeliveryTimeoutMs?: number;
+}): HostedRuntime;