@beignet/cli 0.0.41 → 0.0.42

package/dist/inspect.js

@@ -1,13 +1,14 @@
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { parseProviderPackageMetadata } from "@beignet/core/providers";
 import { createPainter } from "./ansi.js";
 import { clientDirPath, clientFormsPath, clientIndexPath, defaultBeignetConfig, directoryPath, loadBeignetConfig, normalizePath, resolveConfig, } from "./config.js";
+import { applyPlannedDoctorFixes, createDoctorFixPlan, planDoctorFixFileChange, publicDoctorFixPlan, } from "./doctor-fixes.js";
 import { formatGithubAnnotation, } from "./github-annotations.js";
 import { createListenersRegistrySource, listenersFilePath, providersFilePath, updateListenersRegistrySource, wireListenersProviderSource, } from "./make/shared.js";
 import { detectedProviderVariants, diagnosticPackageJsonFile, formatProviderMetadataIssues, installedPackageNames, providerDoctorRulesForInstalledPackages, providerOperationalConfigFiles, providerRequiredEnvExists, providerRequiredTableExists, providerVariantRegistrationSeverity, readProviderListEntries, readProviderPackageMetadataSource, registrationTokenHint, serverProviderFiles, } from "./provider-audit.js";
 import { appendToArrayExpression, appendToNamedArray, appendToOutboxRegistryArray, arrayInitializerInfo, identifiersFromArrayExpression, insertAfterImports, matchingDelimiterIndex, outboxRegistryValueInfo, } from "./registry-edits.js";
-import { currentGeneratedPackageScripts, externalVersions, legacyGeneratedPackageScripts, } from "./templates/shared.js";
+import { currentGeneratedPackageScripts, externalVersions, isLegacyGeneratedPackageScript, legacyGeneratedPackageScripts, } from "./templates/shared.js";
 import { testSupportTemplateFiles } from "./templates/testing.js";
 import { getCliVersion } from "./version.js";
 export async function inspectApp(options = {}) {
@@ -33,7 +34,40 @@ export async function inspectApp(options = {}) {
         fixes: [],
     };
 }
+/** Plan every currently available low-risk doctor repair without writing. */
+export async function planDoctorFixes(options = {}) {
+    const plan = publicDoctorFixPlan(await buildDoctorFixPlan(options));
+    const inspected = await inspectApp(options);
+    return {
+        ...plan,
+        convention: inspected.convention,
+        diagnostics: inspected.diagnostics,
+    };
+}
+/** Apply a current doctor fix plan after verifying its plan ID. */
+export async function applyDoctorFixPlan(options) {
+    const plan = await buildDoctorFixPlan(options);
+    if (plan.planId !== options.planId) {
+        throw new Error("Doctor fix plan is stale because the available repairs changed. No files were changed; run beignet doctor --fix --dry-run again.");
+    }
+    return applyPlannedDoctorFixes(plan, options.fixIds);
+}
 export async function applyDoctorFixes(options = {}) {
+    return (await applyDoctorFixesWithResult(options)).fixes;
+}
+export async function applyDoctorFixesWithResult(options = {}) {
+    const plan = await buildDoctorFixPlan(options);
+    return applyPlannedDoctorFixes(plan);
+}
+export function createDoctorFixInspectionResult(inspected, applied) {
+    return {
+        ...inspected,
+        planId: applied.planId,
+        operationIds: applied.operationIds,
+        fixes: applied.fixes,
+    };
+}
+async function buildDoctorFixPlan(options = {}) {
     const targetDir = path.resolve(options.cwd ?? process.cwd());
     await assertDirectory(targetDir);
     const files = await listFiles(targetDir);
@@ -43,28 +77,41 @@ export async function applyDoctorFixes(options = {}) {
     const convention = inspectConvention(files, config);
     const contracts = await readContracts(targetDir, files, config);
     const matchedRoutes = await inspectRouteSurface(targetDir, files, config, contracts);
-    const fixes = [];
-    const packageFix = await fixPackageScripts(targetDir, files, convention);
+    const operations = [];
+    const packageFix = await planPackageScripts(targetDir, files, convention);
     if (packageFix)
-        fixes.push(packageFix);
-    const routeGroupFix = await fixUnregisteredRouteGroups(targetDir, files, config);
+        operations.push(packageFix);
+    const routeGroupFix = await planUnregisteredRouteGroups(targetDir, files, config);
     if (routeGroupFix)
-        fixes.push(routeGroupFix);
+        operations.push(routeGroupFix);
     const drift = await workflowRegistrationDrift(targetDir, files, config);
-    const scheduleFix = await fixUnregisteredSchedules(targetDir, files, drift, config);
-    if (scheduleFix)
-        fixes.push(scheduleFix);
-    const taskFix = await fixUnregisteredTasks(targetDir, files, drift, config);
-    if (taskFix)
-        fixes.push(taskFix);
-    fixes.push(...(await fixUnregisteredOutboxEntries(targetDir, files, drift, config)));
-    const listenerFix = await fixUnregisteredListeners(targetDir, files, drift, config);
+    if (config.paths.schedules === config.paths.tasks) {
+        const workflowFix = await planCoLocatedScheduleAndTaskRegistries(targetDir, files, drift, config);
+        if (workflowFix)
+            operations.push(workflowFix);
+    }
+    else {
+        const scheduleFix = await planUnregisteredSchedules(targetDir, files, drift, config);
+        if (scheduleFix)
+            operations.push(scheduleFix);
+        const taskFix = await planUnregisteredTasks(targetDir, files, drift, config);
+        if (taskFix)
+            operations.push(taskFix);
+    }
+    const outboxFix = await planUnregisteredOutboxEntries(targetDir, files, drift, config);
+    if (outboxFix)
+        operations.push(outboxFix);
+    const listenerFix = await planUnregisteredListeners(targetDir, files, drift, config);
     if (listenerFix)
-        fixes.push(listenerFix);
-    const openApiFix = await fixDirectOpenApiArrayDrift(targetDir, files, config, convention, contracts, matchedRoutes);
+        operations.push(listenerFix);
+    const openApiFix = await planDirectOpenApiArrayDrift(targetDir, files, config, convention, contracts, matchedRoutes);
     if (openApiFix)
-        fixes.push(openApiFix);
-    return fixes;
+        operations.push(openApiFix);
+    return createDoctorFixPlan({
+        targetDir,
+        strict: Boolean(options.strict),
+        operations,
+    });
 }
 /**
  * Format inspected routes as a CLI table.
@@ -88,10 +135,54 @@ export function formatRoutes(result) {
         ...rows.map((row) => [row.method, row.path, row.contract, row.handler]),
     ]);
 }
+/**
+ * Format a read-only doctor fix plan with exact patches and apply commands.
+ */
+export function formatDoctorFixPlan(plan, options = {}) {
+    const paint = createPainter(options.color);
+    const lines = [];
+    if (plan.operations.length === 0) {
+        lines.push(`No applicable Beignet fixes found in ${plan.targetDir}.`);
+    }
+    else {
+        const strictFlag = plan.strict ? " --strict" : "";
+        lines.push(`Planned ${plan.operations.length} Beignet fix operation${plan.operations.length === 1 ? "" : "s"} in ${plan.targetDir}:`, "");
+        for (const operation of plan.operations) {
+            lines.push(`${paint("PLAN", "cyan")} ${operation.id}`, ...operation.fixes.map((fix) => `  ${fix.code} ${fix.file}\n    ${fix.message}`), ...operation.changes.flatMap((change) => [
+                `  ${change.kind === "create" ? "Create" : "Update"} ${change.file}`,
+                change.patch.trimEnd(),
+            ]), "");
+        }
+        lines.push(`Plan ID: ${plan.planId}`, "", "Apply the complete plan:", `  beignet doctor --fix${strictFlag} --plan ${plan.planId}`, "", "Apply selected operations:", `  beignet doctor --fix${strictFlag} --plan ${plan.planId} --only ${plan.operations.map((operation) => operation.id).join(",")}`);
+    }
+    lines.push("", formatDoctorResult({
+        targetDir: plan.targetDir,
+        strict: plan.strict,
+        diagnostics: plan.diagnostics,
+        fixes: [],
+    }, options));
+    return lines.join("\n");
+}
+/**
+ * Format planned fixes as GitHub Actions notice annotations.
+ */
+export function formatDoctorFixPlanGithub(plan) {
+    return [
+        ...plan.operations.map((operation) => formatGithubAnnotation({
+            severity: "notice",
+            file: operation.changes[0]?.file,
+            message: `${operation.id}: ${operation.fixes.map((fix) => fix.message).join(" ")} Plan ${plan.planId}.`,
+        })),
+        ...formatDoctorDiagnosticsGithub(plan.diagnostics),
+    ].join("\n");
+}
 /**
  * Format doctor diagnostics and applied fixes for CLI output.
  */
 export function formatDoctor(result, options = {}) {
+    return formatDoctorResult(result, options);
+}
+function formatDoctorResult(result, options = {}) {
     const paint = createPainter(options.color);
     const fixLines = result.fixes.length === 0
         ? []
@@ -193,13 +284,14 @@ function formatDoctorFooter(result) {
  * Format doctor diagnostics as GitHub Actions annotations.
  */
 export function formatDoctorGithub(result) {
-    return result.diagnostics
-        .map((diagnostic) => formatGithubAnnotation({
+    return formatDoctorDiagnosticsGithub(result.diagnostics).join("\n");
+}
+function formatDoctorDiagnosticsGithub(diagnostics) {
+    return diagnostics.map((diagnostic) => formatGithubAnnotation({
         severity: githubAnnotationSeverity(diagnostic.severity),
         file: diagnostic.file,
         message: `${diagnostic.code}: ${diagnostic.message}`,
-    }))
-        .join("\n");
+    }));
 }
 function githubAnnotationSeverity(severity) {
     if (severity === "hint")
@@ -3724,7 +3816,7 @@ async function inspectPackageScripts(targetDir, files, convention) {
             severity: "warning",
             code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
             file: "package.json",
-            message: 'package.json does not define a test script. Add "test": "tsx lib/beignet-test-runner.ts" or run beignet doctor --fix.',
+            message: `package.json does not define a test script. Add "test": "${currentGeneratedPackageScripts.test}" or run beignet doctor --fix.`,
         });
     }
     const legacyScripts = hasDirectBunTestImports
@@ -3735,7 +3827,7 @@ async function inspectPackageScripts(targetDir, files, convention) {
             severity: "warning",
             code: "BEIGNET_PACKAGE_SCRIPT_LEGACY",
             file: "package.json",
-            message: `package.json still uses legacy generated Bun scripts for ${legacyScripts.join(", ")}. Run beignet doctor --fix to migrate them to package-manager-neutral tsx scripts.`,
+            message: `package.json still uses legacy generated scripts for ${legacyScripts.join(", ")}. Run beignet doctor --fix to migrate them to the current package-manager-neutral scripts.`,
         });
     }
     const needsTsx = hasCurrentGeneratedTsxScript(scripts) &&
@@ -3761,7 +3853,7 @@ async function inspectPackageScripts(targetDir, files, convention) {
     }
     return diagnostics;
 }
-async function fixPackageScripts(targetDir, files, convention) {
+async function planPackageScripts(targetDir, files, convention) {
     if (!convention.resourceGenerator || !files.includes("package.json")) {
         return undefined;
     }
@@ -3777,8 +3869,8 @@ async function fixPackageScripts(targetDir, files, convention) {
         updatedScripts.push("test");
     }
     if (!hasDirectBunTestImports) {
-        for (const [name, legacyCommand] of Object.entries(legacyGeneratedPackageScripts)) {
-            if (packageJson.scripts[name] === legacyCommand) {
+        for (const name of Object.keys(legacyGeneratedPackageScripts)) {
+            if (isLegacyGeneratedPackageScript(name, packageJson.scripts[name])) {
                 packageJson.scripts[name] = currentGeneratedPackageScripts[name];
                 if (!updatedScripts.includes(name))
                     updatedScripts.push(name);
@@ -3794,47 +3886,65 @@ async function fixPackageScripts(targetDir, files, convention) {
         packageJson.devDependencies.tsx = externalVersions.tsx;
     }
     const next = `${JSON.stringify(packageJson, null, "\t")}\n`;
-    const createdSupportFiles = await createMissingTestSupportFiles(targetDir, files, packageJson.scripts.test === currentGeneratedPackageScripts.test);
+    const createdSupportFiles = packageJson.scripts.test === currentGeneratedPackageScripts.test
+        ? missingTestSupportFiles(files)
+        : [];
     if (next === original && createdSupportFiles.length === 0)
         return undefined;
-    if (next !== original)
-        await writeFile(filePath, next);
+    let fix;
     if (addedTestScript) {
-        return {
+        fix = {
             code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
             file: "package.json",
             message: createdSupportFiles.length > 0
-                ? `Added "test": "tsx lib/beignet-test-runner.ts" and ${createdSupportFiles.join(", ")}.`
-                : 'Added "test": "tsx lib/beignet-test-runner.ts".',
+                ? `Added "test": "${currentGeneratedPackageScripts.test}" and ${createdSupportFiles.join(", ")}.`
+                : `Added "test": "${currentGeneratedPackageScripts.test}".`,
         };
     }
-    if (updatedScripts.length > 0) {
-        return {
+    else if (updatedScripts.length > 0) {
+        fix = {
             code: "BEIGNET_PACKAGE_SCRIPT_LEGACY",
             file: "package.json",
             message: packageScriptFixMessage(updatedScripts, createdSupportFiles, addedTsx),
         };
     }
-    if (createdSupportFiles.length > 0) {
-        return {
+    else if (createdSupportFiles.length > 0) {
+        fix = {
             code: "BEIGNET_PACKAGE_TEST_SUPPORT_MISSING",
             file: "package.json",
             message: `Restored ${createdSupportFiles.join(", ")}.`,
         };
     }
-    if (addedTsx) {
-        return {
+    else if (addedTsx) {
+        fix = {
             code: "BEIGNET_PACKAGE_TSX_DEPENDENCY_MISSING",
             file: "package.json",
             message: 'Added "tsx" to devDependencies.',
         };
     }
-    return undefined;
+    if (!fix)
+        return undefined;
+    return {
+        id: "package.repair-generated-support",
+        fixes: [fix],
+        changes: [
+            ...(next === original
+                ? []
+                : [
+                    planDoctorFixFileChange({
+                        file: "package.json",
+                        before: original,
+                        after: next,
+                    }),
+                ]),
+            ...testSupportTemplateFiles
+                .filter((file) => createdSupportFiles.includes(file.path))
+                .map((file) => planDoctorFixFileChange({ file: file.path, after: file.content })),
+        ],
+    };
 }
 function legacyGeneratedScriptNames(scripts) {
-    return Object.entries(legacyGeneratedPackageScripts)
-        .filter(([name, command]) => scripts[name] === command)
-        .map(([name]) => name);
+    return Object.keys(legacyGeneratedPackageScripts).filter((name) => isLegacyGeneratedPackageScript(name, scripts[name]));
 }
 async function appUsesDirectBunTestImports(targetDir, files) {
     for (const file of files) {
@@ -3849,27 +3959,14 @@ async function appUsesDirectBunTestImports(targetDir, files) {
     return false;
 }
 function hasCurrentGeneratedTsxScript(scripts) {
-    return Object.values(currentGeneratedPackageScripts).some((command) => command.startsWith("tsx ") && Object.values(scripts).includes(command));
+    return Object.values(currentGeneratedPackageScripts).some((command) => (command.startsWith("tsx ") || command.includes("--import tsx")) &&
+        Object.values(scripts).includes(command));
 }
 function missingTestSupportFiles(files) {
     return testSupportTemplateFiles
         .map((file) => file.path)
         .filter((file) => !files.includes(file));
 }
-async function createMissingTestSupportFiles(targetDir, files, shouldCreate) {
-    if (!shouldCreate)
-        return [];
-    const createdSupportFiles = [];
-    for (const file of testSupportTemplateFiles) {
-        if (files.includes(file.path))
-            continue;
-        const destination = path.join(targetDir, file.path);
-        await mkdir(path.dirname(destination), { recursive: true });
-        await writeFile(destination, file.content);
-        createdSupportFiles.push(file.path);
-    }
-    return createdSupportFiles;
-}
 function packageScriptFixMessage(updatedScripts, createdSupportFiles, addedTsx) {
     const parts = [
         `Updated generated package scripts: ${updatedScripts.join(", ")}.`,
@@ -4207,7 +4304,7 @@ function findRouteGroupContract(contracts, routeGroupContract) {
             contract.file ===
                 routeGroupContract.file.replace(/\.ts$/, "/index.ts")));
 }
-async function fixDirectOpenApiArrayDrift(targetDir, files, config, convention, contracts, matchedRoutes) {
+async function planDirectOpenApiArrayDrift(targetDir, files, config, convention, contracts, matchedRoutes) {
     const routePath = path.join(targetDir, config.paths.openapiRoute);
     let source;
     try {
@@ -4231,16 +4328,27 @@ async function fixDirectOpenApiArrayDrift(targetDir, files, config, convention,
     const next = `${source.slice(0, firstArg.start)}${nextArray}${source.slice(firstArg.end)}`;
     if (next === source)
         return undefined;
-    await writeFile(routePath, next);
     return {
-        code: "BEIGNET_OPENAPI_MISSING",
-        file: config.paths.openapiRoute,
-        message: `Added ${missingContracts
-            .map((contract) => contract.exportName)
-            .join(", ")} to the direct createOpenAPIHandler contract array.`,
+        id: "openapi.register-missing",
+        fixes: [
+            {
+                code: "BEIGNET_OPENAPI_MISSING",
+                file: config.paths.openapiRoute,
+                message: `Added ${missingContracts
+                    .map((contract) => contract.exportName)
+                    .join(", ")} to the direct createOpenAPIHandler contract array.`,
+            },
+        ],
+        changes: [
+            planDoctorFixFileChange({
+                file: config.paths.openapiRoute,
+                before: source,
+                after: next,
+            }),
+        ],
     };
 }
-async function fixUnregisteredRouteGroups(targetDir, files, config) {
+async function planUnregisteredRouteGroups(targetDir, files, config) {
     if (!files.includes(config.paths.server))
         return undefined;
     const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
@@ -4283,19 +4391,30 @@ async function fixUnregisteredRouteGroups(targetDir, files, config) {
     next = `${next.slice(0, nextFirstArg.start)}${nextArray}${next.slice(nextFirstArg.end)}`;
     if (next === original)
         return undefined;
-    await writeFile(targetPath, next);
     return {
-        code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
-        file: targetFile,
-        message: `Registered ${groupsToAppend
-            .map((routeGroup) => routeGroup.name)
-            .join(", ")} in the central route list.`,
+        id: "routes.register-missing",
+        fixes: [
+            {
+                code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
+                file: targetFile,
+                message: `Registered ${groupsToAppend
+                    .map((routeGroup) => routeGroup.name)
+                    .join(", ")} in the central route list.`,
+            },
+        ],
+        changes: [
+            planDoctorFixFileChange({
+                file: targetFile,
+                before: original,
+                after: next,
+            }),
+        ],
     };
 }
-async function fixUnregisteredSchedules(targetDir, files, drift, config) {
+async function planUnregisteredSchedules(targetDir, files, drift, config) {
     if (!drift.schedules.centralExists)
         return undefined;
-    return applyWorkflowRegistryFix({
+    return planWorkflowRegistryOperation("schedules.register-missing", {
         targetDir,
         files,
         centralFile: config.paths.schedules,
@@ -4306,10 +4425,10 @@ async function fixUnregisteredSchedules(targetDir, files, drift, config) {
         append: (source, entry, importLine) => appendToNamedArray(source, "schedules", entry, importLine),
     });
 }
-async function fixUnregisteredTasks(targetDir, files, drift, config) {
+async function planUnregisteredTasks(targetDir, files, drift, config) {
     if (!drift.tasks.centralExists)
         return undefined;
-    return applyWorkflowRegistryFix({
+    return planWorkflowRegistryOperation("tasks.register-missing", {
         targetDir,
         files,
         centralFile: config.paths.tasks,
@@ -4320,6 +4439,70 @@ async function fixUnregisteredTasks(targetDir, files, drift, config) {
         append: (source, entry, importLine) => appendToNamedArray(source, "tasks", entry, importLine),
     });
 }
+async function planCoLocatedScheduleAndTaskRegistries(targetDir, files, drift, config) {
+    if (!drift.schedules.centralExists || !drift.tasks.centralExists) {
+        return undefined;
+    }
+    const centralFile = config.paths.schedules;
+    let original;
+    try {
+        original = await readFile(path.join(targetDir, centralFile), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let next = original;
+    const fixes = [];
+    const repairedKinds = [];
+    const scheduleEdit = planWorkflowRegistryEdit({
+        files,
+        centralFile,
+        source: next,
+        unregistered: drift.schedules.unregistered,
+        code: "BEIGNET_SCHEDULE_UNREGISTERED",
+        listName: "the schedules array",
+        importSpecifier: (indexFile) => `@/${modulePath(indexFile)}`,
+        append: (source, entry, importLine) => appendToNamedArray(source, "schedules", entry, importLine),
+    });
+    if (scheduleEdit) {
+        next = scheduleEdit.after;
+        fixes.push(scheduleEdit.fix);
+        repairedKinds.push("schedules");
+    }
+    const taskEdit = planWorkflowRegistryEdit({
+        files,
+        centralFile,
+        source: next,
+        unregistered: drift.tasks.unregistered,
+        code: "BEIGNET_TASK_UNREGISTERED",
+        listName: "defineTasks([...])",
+        importSpecifier: (indexFile) => relativeModule(centralFile, indexFile),
+        append: (source, entry, importLine) => appendToNamedArray(source, "tasks", entry, importLine),
+    });
+    if (taskEdit) {
+        next = taskEdit.after;
+        fixes.push(taskEdit.fix);
+        repairedKinds.push("tasks");
+    }
+    if (fixes.length === 0 || next === original)
+        return undefined;
+    const id = repairedKinds.length === 2
+        ? "workflows.register-missing"
+        : repairedKinds[0] === "schedules"
+            ? "schedules.register-missing"
+            : "tasks.register-missing";
+    return {
+        id,
+        fixes,
+        changes: [
+            planDoctorFixFileChange({
+                file: centralFile,
+                before: original,
+                after: next,
+            }),
+        ],
+    };
+}
 /**
  * Wire fully unregistered feature listener registries into the central
  * listener registry and ensure the providers file registers that central
@@ -4331,7 +4514,7 @@ async function fixUnregisteredTasks(targetDir, files, drift, config) {
  * register against, or when the registry name is already imported from another
  * file. The diagnostic stays in every bail case.
  */
-async function fixUnregisteredListeners(targetDir, files, drift, config) {
+async function planUnregisteredListeners(targetDir, files, drift, config) {
     const candidates = drift.listeners.unregistered.filter((entry) => entry.fullyUnregistered);
     if (candidates.length === 0)
         return undefined;
@@ -4407,60 +4590,93 @@ async function fixUnregisteredListeners(targetDir, files, drift, config) {
         nextProviders === originalProviders) {
         return undefined;
     }
-    await mkdir(path.dirname(listenersPath), { recursive: true });
-    await writeFile(listenersPath, nextListeners);
-    if (nextProviders !== originalProviders) {
-        await writeFile(providersPath, nextProviders);
-    }
     return {
-        code: "BEIGNET_LISTENER_UNREGISTERED",
-        file: listenersFile,
-        message: `Registered ${candidateNames.join(", ")} in ${listenersFile} and wired listeners with registerListeners(...) in ${providersFile}.`,
+        id: "listeners.register-missing",
+        fixes: [
+            {
+                code: "BEIGNET_LISTENER_UNREGISTERED",
+                file: listenersFile,
+                message: `Registered ${candidateNames.join(", ")} in ${listenersFile} and wired listeners with registerListeners(...) in ${providersFile}.`,
+            },
+        ],
+        changes: [
+            ...(nextListeners === originalListeners
+                ? []
+                : [
+                    planDoctorFixFileChange({
+                        file: listenersFile,
+                        before: originalListeners,
+                        after: nextListeners,
+                    }),
+                ]),
+            ...(nextProviders === originalProviders
+                ? []
+                : [
+                    planDoctorFixFileChange({
+                        file: providersFile,
+                        before: originalProviders,
+                        after: nextProviders,
+                    }),
+                ]),
+        ],
     };
 }
-async function fixUnregisteredOutboxEntries(targetDir, files, drift, config) {
+async function planUnregisteredOutboxEntries(targetDir, files, drift, config) {
     if (!drift.outbox.exists)
-        return [];
+        return undefined;
+    const outboxPath = path.join(targetDir, config.paths.outbox);
+    let original;
+    try {
+        original = await readFile(outboxPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let next = original;
     const fixes = [];
-    const eventFix = await applyWorkflowRegistryFix({
-        targetDir,
+    const eventFix = planWorkflowRegistryEdit({
         files,
         centralFile: config.paths.outbox,
+        source: next,
         unregistered: drift.outbox.events,
         code: "BEIGNET_OUTBOX_EVENT_UNREGISTERED",
         listName: "the outbox events list",
         importSpecifier: (indexFile) => `@/${modulePath(indexFile)}`,
         append: (source, entry, importLine) => appendToOutboxRegistryArray(source, "events", entry, importLine),
     });
-    if (eventFix)
-        fixes.push(eventFix);
-    const jobFix = await applyWorkflowRegistryFix({
-        targetDir,
+    if (eventFix) {
+        next = eventFix.after;
+        fixes.push(eventFix.fix);
+    }
+    const jobFix = planWorkflowRegistryEdit({
         files,
         centralFile: config.paths.outbox,
+        source: next,
         unregistered: drift.outbox.jobs,
         code: "BEIGNET_OUTBOX_JOB_UNREGISTERED",
         listName: "the outbox jobs list",
         importSpecifier: (indexFile) => `@/${modulePath(indexFile)}`,
         append: (source, entry, importLine) => appendToOutboxRegistryArray(source, "jobs", entry, importLine),
     });
-    if (jobFix)
-        fixes.push(jobFix);
-    return fixes;
-}
-/**
- * Append `...<feature><Kind>` registry spreads to an existing central
- * registry file.
- *
- * Bails without writing when an import for the registry name resolves to a
- * different file, when the registry anchor is missing or unparseable, or when
- * some members are already individually registered (appending the registry
- * spread would run those members twice). The diagnostic stays in that case.
- */
-async function applyWorkflowRegistryFix(options) {
-    const candidates = options.unregistered.filter((entry) => entry.fullyUnregistered);
-    if (candidates.length === 0)
+    if (jobFix) {
+        next = jobFix.after;
+        fixes.push(jobFix.fix);
+    }
+    if (fixes.length === 0 || next === original)
         return undefined;
+    return {
+        id: "outbox.register-missing",
+        fixes,
+        changes: [
+            planDoctorFixFileChange({
+                file: config.paths.outbox,
+                before: original,
+                after: next,
+            }),
+        ],
+    };
+}
+async function planWorkflowRegistryOperation(id, options) {
     const centralPath = path.join(options.targetDir, options.centralFile);
     let original;
     try {
@@ -4469,7 +4685,26 @@ async function applyWorkflowRegistryFix(options) {
     catch {
         return undefined;
     }
-    let next = original;
+    const edit = planWorkflowRegistryEdit({ ...options, source: original });
+    if (!edit)
+        return undefined;
+    return {
+        id,
+        fixes: [edit.fix],
+        changes: [
+            planDoctorFixFileChange({
+                file: options.centralFile,
+                before: original,
+                after: edit.after,
+            }),
+        ],
+    };
+}
+function planWorkflowRegistryEdit(options) {
+    const candidates = options.unregistered.filter((entry) => entry.fullyUnregistered);
+    if (candidates.length === 0)
+        return undefined;
+    let next = options.source;
     const registeredNames = [];
     for (const { registry } of candidates) {
         const imported = parseNamedImportSources(next).get(registry.registryName);
@@ -4490,13 +4725,15 @@ async function applyWorkflowRegistryFix(options) {
             registeredNames.push(registry.registryName);
         }
     }
-    if (next === original || registeredNames.length === 0)
+    if (next === options.source || registeredNames.length === 0)
         return undefined;
-    await writeFile(centralPath, next);
     return {
-        code: options.code,
-        file: options.centralFile,
-        message: `Registered ${registeredNames.join(", ")} in ${options.listName}.`,
+        after: next,
+        fix: {
+            code: options.code,
+            file: options.centralFile,
+            message: `Registered ${registeredNames.join(", ")} in ${options.listName}.`,
+        },
     };
 }
 function routeRegistryFileFromServerSource(source, serverFile, files) {