stageflow 0.33.0 → 0.36.0

package/dist/config/catalogRelativePath.js

@@ -82,11 +82,43 @@ export function selectCatalogRootForStart(roots, projectRoot) {
     if (roots.length === 1) {
         return roots[0];
     }
-    const writable = roots.filter((r) => r.kind !== "seeded");
-    if (writable.length === 1) {
-        return writable[0];
+    const registeredOnly = roots.filter((r) => r.kind === "registered");
+    if (registeredOnly.length === 1) {
+        return registeredOnly[0];
     }
-    throw new CatalogPathError("project_root is required when multiple catalog roots are configured", "unknown_project_root", registered);
+    const nonSeeded = roots.filter((r) => r.kind !== "seeded");
+    if (nonSeeded.length === 1) {
+        return nonSeeded[0];
+    }
+    const ids = roots.map((r) => r.project_root).join(", ");
+    throw new CatalogPathError(`project_root is required when multiple catalog roots are configured (${ids})`, "unknown_project_root", registered);
+}
+function workspaceRoot(roots) {
+    return roots.find((r) => r.kind === "workspace");
+}
+export async function resolveDefaultWriteRoot(options, projectRoot) {
+    const roots = await resolveCatalogRoots(options);
+    const registered = roots.map((r) => r.project_root);
+    if (projectRoot !== undefined) {
+        const found = findCatalogRoot(roots, projectRoot);
+        if (found === undefined) {
+            throw new CatalogPathError(`Unknown project_root: ${projectRoot}`, "unknown_project_root", registered);
+        }
+        if (found.read_only) {
+            throw new CatalogPathError(`Catalog root ${found.project_root} is read-only`, "catalog_root_read_only", registered);
+        }
+        if (found.kind === "workspace" && found.available === false) {
+            throw new CatalogPathError(found.unavailable_reason ??
+                `Workspace catalog is not writable (${found.path})`, "unknown_project_root", registered);
+        }
+        return { roots, wireRoot: found };
+    }
+    const ws = workspaceRoot(roots);
+    if (ws === undefined || ws.available === false) {
+        throw new CatalogPathError(ws?.unavailable_reason ??
+            "Workspace catalog is unavailable; set project_root explicitly", "unknown_project_root", registered);
+    }
+    return { roots, wireRoot: ws };
 }
 /**
  * Shared helper: resolveCatalogRoots → selectCatalogRootForStart.
@@ -102,11 +134,7 @@ export async function resolveCatalogStartInput(options, projectRoot) {
  * Used by write surfaces (POST /api/stages, POST /api/pipelines).
  */
 export async function resolveWritableCatalogRoot(options, projectRoot) {
-    const { roots, wireRoot } = await resolveCatalogStartInput(options, projectRoot);
-    if (wireRoot.read_only) {
-        throw new CatalogPathError(`Catalog root ${wireRoot.project_root} is read-only`, "catalog_root_read_only", roots.map((r) => r.project_root));
-    }
-    return { roots, wireRoot };
+    return resolveDefaultWriteRoot(options, projectRoot);
 }
 /**
  * Local CLI control: turn a cwd-resolved filesystem path into a catalog-relative

package/dist/config/createStage.d.ts

@@ -7,6 +7,7 @@ export type CreateStageInput = {
     system_prompt: string;
     model?: string;
     gate_kinds?: StageGateKind[];
+    skill?: string;
 };
 export type CreatedStageListing = {
     path: string;

package/dist/config/createStage.js

@@ -41,8 +41,12 @@ export function parseCreateStageBody(body) {
     if ("payload_schema" in body) {
         return { ok: false, status: 400, error: "payload_schema is not supported" };
     }
-    if ("skill" in body) {
-        return { ok: false, status: 400, error: "skill is not supported" };
+    let skill;
+    if (body.skill !== undefined) {
+        if (typeof body.skill !== "string" || body.skill.trim() === "") {
+            return { ok: false, status: 400, error: "skill must be a non-empty string" };
+        }
+        skill = body.skill.trim();
     }
     if (typeof body.pipeline_directory !== "string" || !body.pipeline_directory.trim()) {
         return { ok: false, status: 400, error: "pipeline_directory is required" };
@@ -84,6 +88,7 @@ export function parseCreateStageBody(body) {
         system_prompt: body.system_prompt,
         ...(model !== undefined ? { model } : {}),
         ...(gateKinds !== undefined ? { gate_kinds: gateKinds } : {}),
+        ...(skill !== undefined ? { skill } : {}),
     };
 }
 function formatInlineYamlScalar(value) {
@@ -122,6 +127,9 @@ export function stageConfigToYaml(stage) {
     if (stage.model !== undefined && stage.model.length > 0) {
         lines.push(`model: ${formatInlineYamlScalar(stage.model)}`);
     }
+    if (stage.skill !== undefined && stage.skill.length > 0) {
+        lines.push(`skill: ${formatInlineYamlScalar(stage.skill)}`);
+    }
     lines.push("io:");
     lines.push("  input:");
     lines.push("    schema:");
@@ -204,6 +212,7 @@ export async function createStage(projectRoot, input) {
             system_prompt: input.system_prompt,
             ...(input.model !== undefined && input.model.length > 0 ? { model: input.model } : {}),
             ...(input.gate_kinds !== undefined ? { gate_kinds: input.gate_kinds } : {}),
+            ...(input.skill !== undefined && input.skill.length > 0 ? { skill: input.skill } : {}),
         }), "utf8");
     }
     catch (err) {

package/dist/config/createTask.d.ts

@@ -0,0 +1,30 @@
+import type { TaskDetail } from "./findTaskInCatalog.js";
+export type CreateTaskInput = {
+    directory: string;
+    id: string;
+    goal: string;
+    context?: string;
+    constraints?: string;
+    checkout?: string;
+    repository?: string;
+    ref?: string;
+};
+export type CreateTaskParseError = {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export type CreateTaskResult = {
+    ok: true;
+    task: TaskDetail;
+} | {
+    ok: false;
+    status: 400 | 404 | 409 | 500 | 502;
+    error: string;
+};
+export declare function validateTaskId(id: string): string | null;
+export declare function parseCreateTaskBody(body: unknown): CreateTaskInput | CreateTaskParseError;
+export declare function resolveTaskDirectory(projectRoot: string, directory: string): string | null;
+export declare function taskFieldsToYaml(fields: CreateTaskInput): string;
+export declare function findTaskIdCollision(projectRoot: string, id: string, targetPath: string): Promise<string | null>;
+export declare function createTask(rawProjectRoot: string, input: CreateTaskInput): Promise<CreateTaskResult>;

package/dist/config/createTask.js

@@ -0,0 +1,161 @@
+import { access, mkdir, realpath, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { STAGE_ID_PATTERN } from "./createStage.js";
+import { loadTaskOutcome } from "./loadTask.js";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+const OPTIONAL_KEYS = ["context", "constraints", "checkout", "repository", "ref"];
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function validateTaskId(id) {
+    if (id.length === 0 || id.length > 64) {
+        return "id must be 1-64 characters";
+    }
+    if (!STAGE_ID_PATTERN.test(id)) {
+        return "id must be lowercase kebab-case";
+    }
+    return null;
+}
+function optionalCreateString(body, key) {
+    if (!Object.hasOwn(body, key) || body[key] === undefined || body[key] === null) {
+        return { ok: true };
+    }
+    if (typeof body[key] !== "string") {
+        return { ok: false, error: `${key} must be a string` };
+    }
+    if (body[key].length === 0)
+        return { ok: true };
+    return { ok: true, value: body[key] };
+}
+export function parseCreateTaskBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "Request body must be an object" };
+    }
+    if (typeof body.directory !== "string" || body.directory.trim().length === 0) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    const directory = body.directory.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    if (directory.length === 0) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    if (typeof body.id !== "string") {
+        return { ok: false, status: 400, error: "id is required" };
+    }
+    const idError = validateTaskId(body.id);
+    if (idError) {
+        return { ok: false, status: 400, error: idError };
+    }
+    if (typeof body.goal !== "string" || body.goal.length === 0) {
+        return { ok: false, status: 400, error: "goal is required" };
+    }
+    const input = {
+        directory,
+        id: body.id,
+        goal: body.goal,
+    };
+    for (const key of OPTIONAL_KEYS) {
+        const parsed = optionalCreateString(body, key);
+        if (!parsed.ok) {
+            return { ok: false, status: 400, error: parsed.error };
+        }
+        if (parsed.value !== undefined)
+            input[key] = parsed.value;
+    }
+    return input;
+}
+export function resolveTaskDirectory(projectRoot, directory) {
+    const absDirectory = path.resolve(projectRoot, directory);
+    const rel = path.relative(projectRoot, absDirectory);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return null;
+    }
+    return absDirectory;
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function taskFieldsToYaml(fields) {
+    const doc = {
+        id: fields.id,
+        goal: fields.goal,
+    };
+    for (const key of OPTIONAL_KEYS) {
+        const value = fields[key];
+        if (typeof value === "string" && value.length > 0)
+            doc[key] = value;
+    }
+    const text = stringifyYaml(doc, { indent: 2, lineWidth: 0 });
+    return text.endsWith("\n") ? text : `${text}\n`;
+}
+export async function findTaskIdCollision(projectRoot, id, targetPath) {
+    if (await fileExists(targetPath)) {
+        return path.relative(projectRoot, targetPath).replace(/\\/g, "/");
+    }
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(projectRoot));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths)
+        return null;
+    const resolvedTarget = path.resolve(targetPath);
+    for (const filePath of scanPaths.taskPaths) {
+        if (path.resolve(filePath) === resolvedTarget)
+            continue;
+        const outcome = await loadTaskOutcome(filePath);
+        if (outcome.ok && outcome.value.id === id) {
+            return path.relative(projectRoot, filePath).replace(/\\/g, "/");
+        }
+    }
+    return null;
+}
+function taskDetail(task, projectRoot, filePath) {
+    return {
+        ...task,
+        path: path.relative(projectRoot, filePath).replace(/\\/g, "/"),
+    };
+}
+export async function createTask(rawProjectRoot, input) {
+    const idError = validateTaskId(input.id);
+    if (idError) {
+        return { ok: false, status: 400, error: idError };
+    }
+    const projectRoot = await realpath(rawProjectRoot).catch(() => rawProjectRoot);
+    const directory = resolveTaskDirectory(projectRoot, input.directory);
+    if (!directory) {
+        return { ok: false, status: 400, error: "directory must be inside the project root" };
+    }
+    const filePath = path.join(directory, `${input.id}.task.yaml`);
+    const collision = await findTaskIdCollision(projectRoot, input.id, filePath);
+    if (collision) {
+        const targetRel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+        const error = collision === targetRel
+            ? `Task file already exists (${collision})`
+            : `Task id already exists (${collision})`;
+        return { ok: false, status: 409, error };
+    }
+    try {
+        await mkdir(directory, { recursive: true });
+        await writeFile(filePath, taskFieldsToYaml(input), "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 500, error: message };
+    }
+    const outcome = await loadTaskOutcome(filePath);
+    if (!outcome.ok) {
+        await unlink(filePath).catch(() => { });
+        return {
+            ok: false,
+            status: 400,
+            error: outcome.issues[0]?.message ?? "Invalid task",
+        };
+    }
+    return { ok: true, task: taskDetail(outcome.value, projectRoot, filePath) };
+}

package/dist/config/createTrigger.d.ts

@@ -23,5 +23,20 @@ export type CreateTriggerResult = {
     status: 400 | 409 | 422 | 500;
     error: string;
 };
+type ParsedField<T> = {
+    ok: true;
+    value: T | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseScheduleField(raw: unknown): ParsedField<TriggerSchedule>;
+export declare function parseEventField(raw: unknown): ParsedField<TriggerEvent>;
 export declare function parseCreateTriggerBody(body: unknown): CreateTriggerInput | CreateTriggerParseError;
+export declare function scheduleCronError(schedule: TriggerSchedule): string | null;
+export declare function triggerReferenceError(scanPaths: {
+    pipelinePaths: string[];
+    taskPaths: string[];
+}, pipeline: string, task: string | undefined): Promise<string | null>;
 export declare function createTrigger(rawProjectRoot: string, input: CreateTriggerInput): Promise<CreateTriggerResult>;
+export {};

package/dist/config/createTrigger.js

@@ -21,7 +21,7 @@ function validateTriggerId(id) {
     }
     return null;
 }
-function parseScheduleField(raw) {
+export function parseScheduleField(raw) {
     if (raw === undefined)
         return { ok: true, value: undefined };
     if (!isPlainObject(raw)) {
@@ -41,7 +41,7 @@ function parseScheduleField(raw) {
         },
     };
 }
-function parseEventField(raw) {
+export function parseEventField(raw) {
     if (raw === undefined)
         return { ok: true, value: undefined };
     if (!isPlainObject(raw)) {
@@ -129,6 +129,29 @@ function resolveDirectory(projectRoot, directory) {
     }
     return absDirectory;
 }
+export function scheduleCronError(schedule) {
+    try {
+        new Cron(schedule.cron, schedule.timezone !== undefined ? { timezone: schedule.timezone } : {});
+        return null;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `Invalid schedule.cron: ${message}`;
+    }
+}
+export async function triggerReferenceError(scanPaths, pipeline, task) {
+    const pipelineIds = await collectPipelineIdsFromPaths(scanPaths.pipelinePaths);
+    if (!pipelineIds.has(pipeline)) {
+        return `Trigger references unknown pipeline "${pipeline}"`;
+    }
+    if (task !== undefined) {
+        const taskIds = await collectTaskIdsFromPaths(scanPaths.taskPaths);
+        if (!taskIds.has(task)) {
+            return `Trigger references unknown task "${task}"`;
+        }
+    }
+    return null;
+}
 function triggerInputToYaml(input, enabled) {
     const doc = {
         id: input.id,
@@ -172,34 +195,17 @@ export async function createTrigger(rawProjectRoot, input) {
             error: `Trigger id already exists (${path.relative(projectRoot, collisionPath).replace(/\\/g, "/")})`,
         };
     }
-    const pipelineIds = await collectPipelineIdsFromPaths(scanPaths.pipelinePaths);
-    if (!pipelineIds.has(input.pipeline)) {
-        return {
-            ok: false,
-            status: 422,
-            error: `Trigger references unknown pipeline "${input.pipeline}"`,
-        };
-    }
-    if (input.task !== undefined) {
-        const taskIds = await collectTaskIdsFromPaths(scanPaths.taskPaths);
-        if (!taskIds.has(input.task)) {
-            return {
-                ok: false,
-                status: 422,
-                error: `Trigger references unknown task "${input.task}"`,
-            };
-        }
+    const refError = await triggerReferenceError(scanPaths, input.pipeline, input.task);
+    if (refError) {
+        return { ok: false, status: 422, error: refError };
     }
     if (input.kind === "schedule") {
         if (!input.schedule) {
             return { ok: false, status: 422, error: "schedule.cron is required for kind=schedule" };
         }
-        try {
-            new Cron(input.schedule.cron, input.schedule.timezone !== undefined ? { timezone: input.schedule.timezone } : {});
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return { ok: false, status: 422, error: `Invalid schedule.cron: ${message}` };
+        const cronError = scheduleCronError(input.schedule);
+        if (cronError) {
+            return { ok: false, status: 422, error: cronError };
         }
     }
     const filePath = path.join(directory, `${input.id}.trigger.yaml`);
@@ -227,6 +233,7 @@ export async function createTrigger(rawProjectRoot, input) {
         trigger: {
             ...loadOutcome.value,
             definition_ref: relPath,
+            project_root: projectRoot,
         },
     };
 }

package/dist/config/draftPackage.d.ts

@@ -12,6 +12,7 @@ export type DraftPackage = {
         model?: unknown;
         schemas?: unknown;
         requires?: unknown;
+        channels?: unknown;
     };
     stages?: DraftStageArtifact[];
     task?: {
@@ -81,9 +82,50 @@ export type LoadTaskArtifactResult = {
     status: 400 | 404;
     error: string;
 };
+/** Move uses-wrapper skill: onto the matching stage artifact body, then clear the wrapper. */
+export declare function hoistUsesWrapperSkills(draft: DraftPackage): DraftPackage;
 export declare function validateDraftPackage(draft: DraftPackage, options?: ValidateDraftPackageOptions): Promise<ValidationResult>;
 export declare function overwriteDraftPackage(projectRoot: string, input: OverwriteDraftPackageInput): Promise<OverwriteDraftPackageResult>;
 export declare function createDraftPackage(projectRoot: string, input: CreateDraftPackageInput): Promise<CreateDraftPackageResult>;
+export type DraftPlanMode = "create" | "overwrite";
+export type DraftPlanFile = {
+    path: string;
+    kind: "pipeline" | "stage" | "task";
+    action: "new" | "overwrite" | "unchanged";
+    added: number;
+    removed: number;
+};
+export type DraftPlanResult = {
+    pipelinePath: string;
+    directory: string;
+    files: DraftPlanFile[];
+    pipelineIdTaken: boolean;
+};
+export type PlanDraftPackageOptions = {
+    mode?: DraftPlanMode;
+    catalogPipelines?: ReadonlyArray<{
+        id: string;
+        path: string;
+    }>;
+};
+export declare function countLineChanges(before: string, after: string): {
+    added: number;
+    removed: number;
+};
+export declare function planDraftPackage(projectRoot: string, input: CreateDraftPackageInput, options?: PlanDraftPackageOptions): Promise<({
+    ok: true;
+} & DraftPlanResult) | {
+    ok: false;
+    status: 400;
+    error: string;
+}>;
+export declare function parsePlanDraftPackageBody(body: unknown): (CreateDraftPackageInput & {
+    mode: DraftPlanMode;
+}) | {
+    ok: false;
+    status: 400;
+    error: string;
+};
 export declare function parseDraftPackageBody(body: unknown): DraftPackage | {
     ok: false;
     status: 400;