stageflow 0.32.0 → 0.35.0

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

@@ -81,9 +81,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;

package/dist/config/draftPackage.js

@@ -1,4 +1,4 @@
-import { access, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { loadPipelineOutcome } from "./loadPipeline.js";
@@ -6,6 +6,8 @@ import { parseTaskFile } from "./loadTask.js";
 import { stringifyTargetYaml } from "./printTargetYaml.js";
 import { readYamlObject } from "./readYamlObject.js";
 import { buildValidationResult, findingsFromLoadIssues, loadPipelineValidated, validatePipeline, } from "./validateCatalog.js";
+import { normalizeDraftCatalogFilenames, taskIdFromDraftTask, } from "./workshopCatalogFilenames.js";
+import { reconcileWorkshopCatalogPackageDir } from "./workshopCatalogRepair.js";
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -15,10 +17,57 @@ function normalizeStageRelPath(stagePath) {
 function pipelineHasExternalUses(pipeline) {
     return pipeline.stages.some((stage) => typeof stage.uses === "string" && stage.uses.trim().length > 0);
 }
+function stripUsesWrapperSkill(stages) {
+    return stages.map((stage) => {
+        if (typeof stage.uses !== "string" || stage.skill === undefined)
+            return stage;
+        const { skill: _skill, ...rest } = stage;
+        return rest;
+    });
+}
+/** Move uses-wrapper skill: onto the matching stage artifact body, then clear the wrapper. */
+export function hoistUsesWrapperSkills(draft) {
+    const artifacts = draft.stages ? [...draft.stages] : [];
+    const byPath = new Map(artifacts.map((artifact, index) => [
+        normalizeStageRelPath(artifact.path),
+        index,
+    ]));
+    const stages = draft.pipeline.stages.map((stage) => {
+        if (typeof stage.uses !== "string" || stage.skill === undefined)
+            return stage;
+        const skill = typeof stage.skill === "string" && stage.skill.trim()
+            ? stage.skill.trim()
+            : undefined;
+        if (skill === undefined) {
+            const { skill: _skill, ...rest } = stage;
+            return rest;
+        }
+        const key = normalizeStageRelPath(stage.uses);
+        const index = byPath.get(key);
+        if (index !== undefined) {
+            const current = artifacts[index];
+            const bodySkill = current.body.skill;
+            const bodyHasSkill = typeof bodySkill === "string" && bodySkill.trim().length > 0;
+            if (!bodyHasSkill) {
+                artifacts[index] = {
+                    ...current,
+                    body: { ...current.body, skill },
+                };
+            }
+        }
+        const { skill: _skill, ...rest } = stage;
+        return rest;
+    });
+    return {
+        ...draft,
+        pipeline: { ...draft.pipeline, stages },
+        ...(artifacts.length > 0 ? { stages: artifacts } : {}),
+    };
+}
 function pipelineDocument(pipeline) {
     const doc = {
         id: pipeline.id,
-        stages: pipeline.stages,
+        stages: stripUsesWrapperSkill(pipeline.stages),
     };
     if (pipeline.agent !== undefined)
         doc.agent = pipeline.agent;
@@ -48,9 +97,10 @@ async function fileExists(filePath) {
     }
 }
 async function materializeDraft(draft, dir, pipelineFilename) {
+    const migrated = hoistUsesWrapperSkills(draft);
     await mkdir(dir, { recursive: true });
-    await writeFile(path.join(dir, pipelineFilename), stringifyTargetYaml(pipelineDocument(draft.pipeline)), "utf8");
-    for (const stage of draft.stages ?? []) {
+    await writeFile(path.join(dir, pipelineFilename), stringifyTargetYaml(pipelineDocument(migrated.pipeline)), "utf8");
+    for (const stage of migrated.stages ?? []) {
         const rel = normalizeStageRelPath(stage.path);
         const stagePath = path.join(dir, rel);
         await mkdir(path.dirname(stagePath), { recursive: true });
@@ -185,11 +235,13 @@ function resolveDraftWriteTarget(projectRoot, input) {
             error: "directory must be inside the project root",
         };
     }
-    const draft = input.draft;
-    if (!isPlainObject(draft?.pipeline) || typeof draft.pipeline.id !== "string") {
+    const rawDraft = input.draft;
+    if (!isPlainObject(rawDraft?.pipeline) || typeof rawDraft.pipeline.id !== "string") {
         return { ok: false, status: 400, error: "draft.pipeline.id is required" };
     }
-    const pipelineFilename = input.pipelineFilename?.trim() || `${draft.pipeline.id}.pipeline.yaml`;
+    const normalized = normalizeDraftCatalogFilenames(rawDraft, input.pipelineFilename?.trim());
+    const draft = hoistUsesWrapperSkills(normalized.draft);
+    const pipelineFilename = normalized.pipelineFilename;
     const pipelineAbsPath = path.join(packageDirectory, path.basename(pipelineFilename));
     const pipelineRelPath = path
         .relative(projectRoot, pipelineAbsPath)
@@ -223,9 +275,17 @@ async function gateDraftWrite(projectRoot, draft, allowInvalid) {
         findings: validation.findings,
     };
 }
-async function writeDraftPackageFiles(projectRoot, target, allowInvalid) {
+function resolveDraftWriteFiles(projectRoot, target) {
     const { packageDirectory, draft, pipelineAbsPath, pipelineRelPath } = target;
-    const stagePaths = [];
+    const toRel = (abs) => path.relative(projectRoot, abs).replace(/\\/g, "/");
+    const files = [
+        {
+            kind: "pipeline",
+            absPath: pipelineAbsPath,
+            relPath: pipelineRelPath,
+            content: stringifyTargetYaml(pipelineDocument(draft.pipeline)),
+        },
+    ];
     for (const stage of draft.stages ?? []) {
         const rel = normalizeStageRelPath(stage.path);
         if (!rel || path.isAbsolute(rel) || rel.split(/[/\\]/).includes("..")) {
@@ -244,23 +304,39 @@ async function writeDraftPackageFiles(projectRoot, target, allowInvalid) {
                 error: `Stage path escapes package directory (${stage.path})`,
             };
         }
+        files.push({
+            kind: "stage",
+            absPath: stageAbs,
+            relPath: toRel(stageAbs),
+            content: stringifyTargetYaml(stage.body),
+        });
     }
+    if (draft.task) {
+        const taskAbs = path.join(packageDirectory, path.basename(draft.task.filename));
+        files.push({
+            kind: "task",
+            absPath: taskAbs,
+            relPath: toRel(taskAbs),
+            content: stringifyTargetYaml(draft.task.body),
+        });
+    }
+    return { ok: true, files };
+}
+async function writeDraftPackageFiles(projectRoot, target, allowInvalid) {
+    const { packageDirectory, draft, pipelineRelPath } = target;
+    const resolved = resolveDraftWriteFiles(projectRoot, target);
+    if (!resolved.ok)
+        return resolved;
     try {
         await mkdir(packageDirectory, { recursive: true });
-        await writeFile(pipelineAbsPath, stringifyTargetYaml(pipelineDocument(draft.pipeline)), "utf8");
-        for (const stage of draft.stages ?? []) {
-            const rel = normalizeStageRelPath(stage.path);
-            const stageAbs = path.resolve(packageDirectory, rel);
-            await mkdir(path.dirname(stageAbs), { recursive: true });
-            await writeFile(stageAbs, stringifyTargetYaml(stage.body), "utf8");
-            stagePaths.push(path.relative(projectRoot, stageAbs).replace(/\\/g, "/"));
-        }
-        let taskPath;
-        if (draft.task) {
-            const taskAbs = path.join(packageDirectory, path.basename(draft.task.filename));
-            await writeFile(taskAbs, stringifyTargetYaml(draft.task.body), "utf8");
-            taskPath = path.relative(projectRoot, taskAbs).replace(/\\/g, "/");
+        for (const file of resolved.files) {
+            await mkdir(path.dirname(file.absPath), { recursive: true });
+            await writeFile(file.absPath, file.content, "utf8");
         }
+        const stagePaths = resolved.files
+            .filter((file) => file.kind === "stage")
+            .map((file) => file.relPath);
+        const taskPath = resolved.files.find((file) => file.kind === "task")?.relPath;
         const loadOutcome = await loadPipelineOutcome(pipelineRelPath, {
             cwd: projectRoot,
         });
@@ -274,6 +350,11 @@ async function writeDraftPackageFiles(projectRoot, target, allowInvalid) {
                 error: loadOutcome.issues[0]?.message ?? "Failed to load written pipeline",
             };
         }
+        const taskId = draft.task ? taskIdFromDraftTask(draft.task) : null;
+        await reconcileWorkshopCatalogPackageDir(packageDirectory, draft.pipeline.id, taskId, {
+            pipelineBasename: path.basename(target.pipelineAbsPath),
+            taskBasename: draft.task ? path.basename(draft.task.filename) : null,
+        });
         return {
             ok: true,
             pipeline,
@@ -287,10 +368,22 @@ async function writeDraftPackageFiles(projectRoot, target, allowInvalid) {
         return { ok: false, status: 500, error: message };
     }
 }
+async function prepareDraftPackageDirectory(target) {
+    const taskId = target.draft.task
+        ? taskIdFromDraftTask(target.draft.task)
+        : null;
+    await reconcileWorkshopCatalogPackageDir(target.packageDirectory, target.draft.pipeline.id, taskId, {
+        pipelineBasename: path.basename(target.pipelineAbsPath),
+        taskBasename: target.draft.task
+            ? path.basename(path.join(target.packageDirectory, path.basename(target.draft.task.filename)))
+            : null,
+    });
+}
 export async function overwriteDraftPackage(projectRoot, input) {
     const resolved = resolveDraftWriteTarget(projectRoot, input);
     if (!resolved.ok)
         return resolved;
+    await prepareDraftPackageDirectory(resolved.value);
     if (!(await fileExists(resolved.value.pipelineAbsPath))) {
         return {
             ok: false,
@@ -307,6 +400,7 @@ export async function createDraftPackage(projectRoot, input) {
     const resolved = resolveDraftWriteTarget(projectRoot, input);
     if (!resolved.ok)
         return resolved;
+    await prepareDraftPackageDirectory(resolved.value);
     if (await fileExists(resolved.value.pipelineAbsPath)) {
         return {
             ok: false,
@@ -319,6 +413,104 @@ export async function createDraftPackage(projectRoot, input) {
         return blocked;
     return writeDraftPackageFiles(projectRoot, resolved.value, input.allowInvalid);
 }
+function splitLines(text) {
+    if (!text)
+        return [];
+    return (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
+}
+export function countLineChanges(before, after) {
+    const a = splitLines(before);
+    const b = splitLines(after);
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start += 1;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA -= 1;
+        endB -= 1;
+    }
+    const midA = a.slice(start, endA);
+    const midB = b.slice(start, endB);
+    let prev = new Uint32Array(midB.length + 1);
+    let curr = new Uint32Array(midB.length + 1);
+    for (const lineA of midA) {
+        for (let j = 1; j <= midB.length; j += 1) {
+            curr[j] =
+                lineA === midB[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], curr[j - 1]);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    const common = prev[midB.length];
+    return { added: midB.length - common, removed: midA.length - common };
+}
+async function readExisting(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export async function planDraftPackage(projectRoot, input, options = {}) {
+    const resolved = resolveDraftWriteTarget(projectRoot, input);
+    if (!resolved.ok)
+        return resolved;
+    const writeFiles = resolveDraftWriteFiles(projectRoot, resolved.value);
+    if (!writeFiles.ok)
+        return writeFiles;
+    const files = [];
+    for (const file of writeFiles.files) {
+        const existing = await readExisting(file.absPath);
+        if (existing === null) {
+            files.push({
+                path: file.relPath,
+                kind: file.kind,
+                action: "new",
+                added: splitLines(file.content).length,
+                removed: 0,
+            });
+        }
+        else if (existing === file.content) {
+            files.push({
+                path: file.relPath,
+                kind: file.kind,
+                action: "unchanged",
+                added: 0,
+                removed: 0,
+            });
+        }
+        else {
+            files.push({
+                path: file.relPath,
+                kind: file.kind,
+                action: "overwrite",
+                ...countLineChanges(existing, file.content),
+            });
+        }
+    }
+    const { pipelineRelPath, packageDirectory, draft } = resolved.value;
+    const pipelineIdTaken = (options.mode ?? "create") === "create" &&
+        (options.catalogPipelines ?? []).some((listing) => listing.id === draft.pipeline.id &&
+            listing.path.replace(/\\/g, "/") !== pipelineRelPath);
+    return {
+        ok: true,
+        pipelinePath: pipelineRelPath,
+        directory: path.relative(projectRoot, packageDirectory).replace(/\\/g, "/") || ".",
+        files,
+        pipelineIdTaken,
+    };
+}
+export function parsePlanDraftPackageBody(body) {
+    const parsed = parseCreateDraftPackageBody(body);
+    if ("ok" in parsed)
+        return parsed;
+    const mode = isPlainObject(body) ? body.mode : undefined;
+    if (mode !== undefined && mode !== "create" && mode !== "overwrite") {
+        return { ok: false, status: 400, error: 'mode must be "create" or "overwrite"' };
+    }
+    return { ...parsed, mode: mode ?? "create" };
+}
 export function parseDraftPackageBody(body) {
     if (!isPlainObject(body)) {
         return { ok: false, status: 400, error: "JSON object body required" };
@@ -540,9 +732,10 @@ export async function loadDraftPackage(projectRoot, pipelineRelPath, options = {
         draft.task = loaded.task;
         attachedTaskPath = loaded.taskPath;
     }
+    const migrated = hoistUsesWrapperSkills(draft);
     return {
         ok: true,
-        draft,
+        draft: migrated,
         destination: { directory, pipelineFilename },
         pipelinePath,
         ...(attachedTaskPath !== undefined ? { taskPath: attachedTaskPath } : {}),

package/dist/config/ensureCatalogScanRoot.d.ts

@@ -1,8 +1,9 @@
+import type { CatalogRootKind } from "./resolveCatalogRoots.js";
 /** Directory scanned for workshop-authored pipelines and tasks. */
 export declare const WORKSHOP_PACKAGE_ROOT = "workshop";
 export declare function normalizeCatalogDir(directory: string): string;
 /** Untitled workshop saves land here so Run can see them without a new catalog edit. */
-export declare function defaultWorkshopPackageDirectory(pipelineId: string | undefined): string;
+export declare function defaultWorkshopPackageDirectory(pipelineId: string | undefined, catalogRootKind?: CatalogRootKind): string;
 /**
  * Catalog root that covers this package directory.
  * Packages under `workshop/` share one root. Any other folder is listed itself