@beignet/cli 0.0.40 → 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")
@@ -308,7 +400,7 @@ function parseContracts(source, file) {
     const exportRegex = /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=([\s\S]*?)(?=\nexport const\s+[A-Za-z_$][\w$]*\s*=|$)/g;
     for (const exportMatch of source.matchAll(exportRegex)) {
         const block = exportMatch[2];
-        const methodMatch = /([A-Za-z_$][\w$]*)(?:\s*\.\s*[A-Za-z_$][\w$]*\([^)]*\))*\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["']\s*\)/.exec(block);
+        const methodMatch = /([A-Za-z_$][\w$]*)(?:\s*\.\s*[A-Za-z_$][\w$]*\([^)]*\))*\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["'](?:\s*,\s*["'][^"']+["'])?\s*\)/.exec(block);
         if (methodMatch) {
             const receiver = methodMatch[1];
             const pathPrefix = groupPrefixes.get(receiver) ?? "";
@@ -911,7 +1003,7 @@ async function inspectDiagnostics(targetDir, files, config, convention, contract
             diagnostics.push(unmatchedRouteDiagnostic(routeHandler));
         }
     }
-    diagnostics.push(...(await inspectPackageScripts(targetDir, files, convention)), ...(await inspectOpenApiDrift(targetDir, files, config, convention, contracts, matchedRoutes)), ...(await inspectFeatureRouteRegistration(targetDir, files, config, convention, contracts)), ...(await inspectRouteErrorCatalogDrift(targetDir, files, config, convention, contracts, strict)), ...(await inspectCanonicalConformance(targetDir, files, config, convention, strict)), ...(await inspectVersionSkew(targetDir, files)), ...(await inspectProviderMetadataDrift(targetDir, files, convention)), ...(await inspectPortProviderDrift(targetDir, files, config, convention)), ...(await inspectProviderRegistrationDrift(targetDir, files, config, convention)), ...(await inspectDatabaseLifecycleDrift(targetDir, files, config, convention, strict)), ...(await inspectAuthzAuditDrift(targetDir, files, config, convention, contracts)), ...(await inspectServerlessFootguns(targetDir, files, config, convention)), ...(await inspectProductionReadiness(targetDir, files, config, convention)), ...(await inspectFeatureArtifactDrift(targetDir, files, config, convention)), ...(await inspectWorkflowRegistrationDrift(targetDir, files, config, convention)), ...(await inspectRuntimeManifestDrift(targetDir, files, config, convention)), ...(await inspectResourceSlices(targetDir, files, config, convention, strict)));
+    diagnostics.push(...(await inspectPackageScripts(targetDir, files, convention)), ...(await inspectOpenApiDrift(targetDir, files, config, convention, contracts, matchedRoutes)), ...(await inspectFeatureRouteRegistration(targetDir, files, config, convention, contracts)), ...(await inspectRouteErrorCatalogDrift(targetDir, files, config, convention, contracts, strict)), ...(await inspectCanonicalConformance(targetDir, files, config, convention, strict)), ...(await inspectVersionSkew(targetDir, files)), ...(await inspectProviderMetadataDrift(targetDir, files, convention)), ...(await inspectPortProviderDrift(targetDir, files, config, convention)), ...(await inspectProviderRegistrationDrift(targetDir, files, config, convention)), ...(await inspectInngestProductionPath(targetDir, files, config)), ...(await inspectDatabaseLifecycleDrift(targetDir, files, config, convention, strict)), ...(await inspectAuthzAuditDrift(targetDir, files, config, convention, contracts)), ...(await inspectServerlessFootguns(targetDir, files, config, convention)), ...(await inspectProductionReadiness(targetDir, files, config, convention)), ...(await inspectFeatureArtifactDrift(targetDir, files, config, convention)), ...(await inspectWorkflowRegistrationDrift(targetDir, files, config, convention)), ...(await inspectRuntimeManifestDrift(targetDir, files, config, convention)), ...(await inspectResourceSlices(targetDir, files, config, convention, strict)));
     return dedupeDiagnostics(diagnostics);
 }
 async function inspectFrameworkAdapter(targetDir, files, config) {
@@ -1900,6 +1992,56 @@ async function inspectProviderRegistrationDrift(targetDir, files, config, conven
     }
     return diagnostics;
 }
+async function inspectInngestProductionPath(targetDir, files, config) {
+    const packageJson = await readPackageJson(targetDir, files);
+    if (!installedPackageNames(packageJson).has("@beignet/provider-jobs-inngest")) {
+        return [];
+    }
+    const diagnostics = [];
+    const serverDir = directoryPath(path.dirname(config.paths.server));
+    const registryFile = `${serverDir}/inngest.ts`;
+    const routeFile = `${directoryPath(config.paths.routes)}/inngest/route.ts`;
+    if (!files.includes(registryFile)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_INNGEST_REGISTRY_MISSING",
+            file: registryFile,
+            message: `@beignet/provider-jobs-inngest is installed, but ${registryFile} is missing. Run beignet provider add jobs-inngest or create a central createInngestJobFunctions(...) registry so dispatched jobs can execute.`,
+        });
+    }
+    else {
+        const registrySource = await readFile(path.join(targetDir, registryFile), "utf8");
+        const registry = arrayInitializerInfo(registrySource, "inngestJobs");
+        const registeredJobs = registry
+            ? identifiersFromArrayExpression(registry.text)
+            : new Set();
+        const featureRoot = directoryPath(config.paths.features);
+        const jobIndexes = files.filter((file) => new RegExp(`^${escapeRegExp(featureRoot)}/[^/]+/jobs/index\\.ts$`).test(file));
+        for (const jobIndex of jobIndexes) {
+            const source = await readFile(path.join(targetDir, jobIndex), "utf8");
+            const match = source.match(/export const\s+([A-Za-z_$][\w$]*Jobs)\s*=/);
+            const registryName = match?.[1];
+            if (!registryName || registeredJobs.has(registryName)) {
+                continue;
+            }
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_INNGEST_JOB_REGISTRATION_MISSING",
+                file: registryFile,
+                message: `${jobIndex} exports ${registryName}, but it is not registered in inngestJobs in ${registryFile}. Add ...${registryName} so Inngest can execute the job.`,
+            });
+        }
+    }
+    if (config.framework === "next" && !files.includes(routeFile)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_INNGEST_ROUTE_MISSING",
+            file: routeFile,
+            message: `@beignet/provider-jobs-inngest is installed in a Next.js app, but ${routeFile} is missing. Expose the shared Inngest client and function registry with serve(...) so Inngest can discover and invoke jobs.`,
+        });
+    }
+    return diagnostics;
+}
 function isFeatureUploadDefinition(file, config) {
     const featuresPath = directoryPath(config.paths.features);
     return new RegExp(`^${escapeRegExp(featuresPath)}/[^/]+/uploads/[^/]+\\.ts$`).test(file);
@@ -2672,7 +2814,7 @@ function callReferencesCentralListenerRegistry(args) {
     }
     for (const identifier of args.callIdentifiers) {
         const imported = args.namedImports.get(identifier);
-        if (!imported || imported.importedName !== "listeners")
+        if (imported?.importedName !== "listeners")
             continue;
         const importedFile = sourceFileFromImport(imported.sourcePath, args.importerFile, args.files);
         if (importedFile === args.listenerRegistryFile)
@@ -3674,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
@@ -3685,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) &&
@@ -3711,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;
     }
@@ -3727,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);
@@ -3744,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) {
@@ -3799,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(", ")}.`,
@@ -4157,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 {
@@ -4181,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);
@@ -4233,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,
@@ -4256,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,
@@ -4270,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
@@ -4281,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;
@@ -4357,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 {
@@ -4419,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);
@@ -4440,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) {