@beignet/cli 0.0.3 → 0.0.5

package/dist/inspect.js

@@ -1,6 +1,11 @@
 import { readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseProviderPackageMetadata, } from "@beignet/core/providers";
+import { createPainter } from "./ansi.js";
 import { directoryPath, loadBeignetConfig, normalizePath, resolveConfig, } from "./config.js";
+import { formatGithubAnnotation, } from "./github-annotations.js";
+import { getCliVersion } from "./version.js";
 export async function inspectApp(options = {}) {
     const targetDir = path.resolve(options.cwd ?? process.cwd());
     await assertDirectory(targetDir);
@@ -16,6 +21,7 @@ export async function inspectApp(options = {}) {
     const matchedRoutes = matchRoutes(contracts, routeExports);
     const diagnostics = await inspectDiagnostics(targetDir, files, config, convention, contracts, matchedRoutes, Boolean(options.strict));
     return {
+        schemaVersion: 1,
         targetDir,
         config,
         strict: Boolean(options.strict),
@@ -35,11 +41,18 @@ export async function applyDoctorFixes(options = {}) {
         : await loadBeignetConfig(targetDir, files);
     const convention = inspectConvention(files, config);
     const contracts = await readContracts(targetDir, files, config);
+    const routeFiles = files.filter((file) => file.startsWith(`${directoryPath(config.paths.routes)}/`) &&
+        file.endsWith("/route.ts"));
+    const routeExports = await readRouteExports(targetDir, routeFiles, config);
+    const matchedRoutes = matchRoutes(contracts, routeExports);
     const fixes = [];
     const packageFix = await fixMissingTestScript(targetDir, files, convention);
     if (packageFix)
         fixes.push(packageFix);
-    const openApiFix = await fixDirectOpenApiArrayDrift(targetDir, config, contracts);
+    const routeGroupFix = await fixUnregisteredRouteGroups(targetDir, files, config);
+    if (routeGroupFix)
+        fixes.push(routeGroupFix);
+    const openApiFix = await fixDirectOpenApiArrayDrift(targetDir, files, config, convention, contracts, matchedRoutes);
     if (openApiFix)
         fixes.push(openApiFix);
     return fixes;
@@ -67,29 +80,77 @@ export function formatRoutes(result) {
 /**
  * Format doctor diagnostics and applied fixes for CLI output.
  */
-export function formatDoctor(result) {
+export function formatDoctor(result, options = {}) {
+    const paint = createPainter(options.color);
     const fixLines = result.fixes.length === 0
         ? []
         : [
             `Applied ${result.fixes.length} Beignet fix${result.fixes.length === 1 ? "" : "es"}:`,
             "",
-            ...result.fixes.map((fix) => `FIXED ${fix.code} ${fix.file}
+            ...result.fixes.map((fix) => `${paint("FIXED", "green")} ${fix.code} ${fix.file}
   ${fix.message}`),
             "",
         ];
     if (result.diagnostics.length === 0) {
         return [...fixLines, `No Beignet drift found in ${result.targetDir}.`].join("\n");
     }
-    return [
+    const groups = [
+        {
+            severity: "error",
+            header: "Errors",
+            label: paint("ERROR", "red"),
+        },
+        {
+            severity: "warning",
+            header: "Warnings",
+            label: paint("WARNING", "yellow"),
+        },
+        {
+            severity: "hint",
+            header: "Hints",
+            label: paint("HINT", "cyan"),
+        },
+    ];
+    const lines = [
         ...fixLines,
         `Found ${result.diagnostics.length} Beignet issue${result.diagnostics.length === 1 ? "" : "s"} in ${result.targetDir}:`,
-        "",
-        ...result.diagnostics.map((diagnostic) => {
+    ];
+    for (const group of groups) {
+        const diagnostics = result.diagnostics.filter((diagnostic) => diagnostic.severity === group.severity);
+        if (diagnostics.length === 0)
+            continue;
+        lines.push("", paint(`${group.header}:`, "bold"), "");
+        lines.push(...diagnostics.map((diagnostic) => {
             const location = diagnostic.file ? ` ${diagnostic.file}` : "";
-            return `${diagnostic.severity.toUpperCase()} ${diagnostic.code}${location}
+            return `${group.label} ${diagnostic.code}${location}
   ${diagnostic.message}`;
-        }),
-    ].join("\n");
+        }));
+    }
+    lines.push("", formatDoctorFooter(result));
+    return lines.join("\n");
+}
+function formatDoctorFooter(result) {
+    const count = (severity) => result.diagnostics.filter((diagnostic) => diagnostic.severity === severity)
+        .length;
+    const footer = `${count("error")} error(s), ${count("warning")} warning(s), ${count("hint")} hint(s)`;
+    return result.strict ? `${footer} (strict: warnings fail)` : footer;
+}
+/**
+ * Format doctor diagnostics as GitHub Actions annotations.
+ */
+export function formatDoctorGithub(result) {
+    return result.diagnostics
+        .map((diagnostic) => formatGithubAnnotation({
+        severity: githubAnnotationSeverity(diagnostic.severity),
+        file: diagnostic.file,
+        message: `${diagnostic.code}: ${diagnostic.message}`,
+    }))
+        .join("\n");
+}
+function githubAnnotationSeverity(severity) {
+    if (severity === "hint")
+        return "notice";
+    return severity;
 }
 async function assertDirectory(targetDir) {
     try {
@@ -176,10 +237,11 @@ function hasRequirement(files, requirement) {
 function parseContracts(source, file) {
     const contracts = [];
     const groupPrefixes = parseContractGroupPrefixes(source);
+    const groupErrorRefs = parseContractGroupErrorRefs(source);
     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*(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*\)/.exec(block);
         if (methodMatch) {
             const receiver = methodMatch[1];
             const pathPrefix = groupPrefixes.get(receiver) ?? "";
@@ -187,6 +249,7 @@ function parseContracts(source, file) {
             contracts.push({
                 exportName: exportMatch[1],
                 file,
+                metadata: parseContractMetadata(block, groupErrorRefs.get(receiver) ?? []),
                 method: methodMatch[2].toUpperCase(),
                 path: routePath,
             });
@@ -197,6 +260,7 @@ function parseContracts(source, file) {
             contracts.push({
                 exportName: exportMatch[1],
                 file,
+                metadata: parseContractMetadata(block),
                 method: directContract.method,
                 path: normalizeContractPath(directContract.path),
             });
@@ -204,8 +268,30 @@ function parseContracts(source, file) {
     }
     return contracts;
 }
+function parseContractMetadata(block, inheritedCatalogErrors = []) {
+    const authRequired = /\bauth\s*:\s*["']required["']/.test(block);
+    const authorizationAbility = /\bauthorization\s*:\s*\{[\s\S]*?\bability\s*:\s*["']([^"']+)["']/.exec(block)?.[1];
+    const auditRequired = /\baudit\s*:\s*["']required["']/.test(block) ||
+        /\bauditRequired\s*:\s*true\b/.test(block);
+    const catalogErrors = dedupeCatalogErrorRefs([
+        ...inheritedCatalogErrors,
+        ...parseCatalogErrorRefs(block),
+    ]);
+    if (!authRequired &&
+        !authorizationAbility &&
+        !auditRequired &&
+        catalogErrors.length === 0) {
+        return undefined;
+    }
+    return {
+        authRequired,
+        authorizationAbility,
+        auditRequired,
+        catalogErrors,
+    };
+}
 function parseDirectContract(block) {
-    const configMatch = /createContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
+    const configMatch = /defineContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
     if (!configMatch)
         return undefined;
     const configSource = configMatch[1];
@@ -245,8 +331,42 @@ function parseContractGroupPrefixes(source) {
     }
     return prefixes;
 }
+function parseContractGroupErrorRefs(source) {
+    const assignments = [
+        ...source.matchAll(/(?:^|\n)(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*([\s\S]*?);/g),
+    ].map((match) => ({
+        name: match[1],
+        expression: match[2],
+    }));
+    const groupErrors = new Map();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const assignment of assignments) {
+            if (groupErrors.has(assignment.name))
+                continue;
+            const baseErrors = baseGroupErrors(assignment.expression, groupErrors);
+            if (baseErrors === undefined)
+                continue;
+            groupErrors.set(assignment.name, dedupeCatalogErrorRefs([
+                ...baseErrors,
+                ...parseCatalogErrorRefs(assignment.expression),
+            ]));
+            changed = true;
+        }
+    }
+    return groupErrors;
+}
+function baseGroupErrors(expression, groupErrors) {
+    if (expression.includes("defineContractGroup("))
+        return [];
+    const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
+    if (!baseMatch)
+        return undefined;
+    return groupErrors.get(baseMatch[1]);
+}
 function baseGroupPrefix(expression, prefixes) {
-    if (expression.includes("createContractGroup("))
+    if (expression.includes("defineContractGroup("))
         return "";
     const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
     if (!baseMatch)
@@ -256,6 +376,152 @@ function baseGroupPrefix(expression, prefixes) {
 function prefixCalls(expression) {
     return [...expression.matchAll(/\.prefix\(\s*["']([^"']+)["']\s*\)/g)].map((match) => match[1]);
 }
+function parseCatalogErrorRefs(source) {
+    return dedupeCatalogErrorRefs(objectArgumentBodies(source, /\.errors\s*\(/g).flatMap((body) => [...body.matchAll(errorCatalogRefRegex)].map((match) => ({
+        key: match[1],
+        catalog: match[2],
+        catalogKey: match[3],
+    }))));
+}
+const errorCatalogRefRegex = /(?:^|[,{])\s*([A-Za-z_$][\w$]*)\s*:\s*([A-Za-z_$][\w$]*)\s*\.\s*([A-Za-z_$][\w$]*)/g;
+function parseErrorCatalogKeys(source) {
+    const keys = new Set();
+    const catalogBodies = objectArgumentBodies(source, /\bdefineErrors\s*\(/g);
+    for (const body of catalogBodies) {
+        if (/\.\.\.\s*httpErrors\b/.test(body)) {
+            for (const key of httpErrorCatalogKeys)
+                keys.add(key);
+        }
+        for (const key of topLevelObjectKeys(body))
+            keys.add(key);
+    }
+    return keys;
+}
+const httpErrorCatalogKeys = [
+    "BadRequest",
+    "Unauthorized",
+    "Forbidden",
+    "NotFound",
+    "Conflict",
+    "IdempotencyConflict",
+    "IdempotencyInProgress",
+    "TooManyRequests",
+    "UnprocessableEntity",
+    "ValidationError",
+    "InternalServerError",
+];
+function objectArgumentBodies(source, callPattern) {
+    const bodies = [];
+    const pattern = new RegExp(callPattern.source, callPattern.flags);
+    for (const match of source.matchAll(pattern)) {
+        const callIndex = match.index ?? 0;
+        const openParen = source.indexOf("(", callIndex);
+        if (openParen === -1)
+            continue;
+        const objectStart = source.indexOf("{", openParen);
+        if (objectStart === -1)
+            continue;
+        const objectSource = balancedObjectSource(source, objectStart);
+        if (!objectSource)
+            continue;
+        bodies.push(objectSource.slice(1, -1));
+    }
+    return bodies;
+}
+function balancedObjectSource(source, startIndex) {
+    if (source[startIndex] !== "{")
+        return undefined;
+    let depth = 0;
+    let quote;
+    let escaped = false;
+    for (let index = startIndex; index < source.length; index += 1) {
+        const char = source[index];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'" || char === "`") {
+            quote = char;
+            continue;
+        }
+        if (char === "{") {
+            depth += 1;
+            continue;
+        }
+        if (char === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return source.slice(startIndex, index + 1);
+        }
+    }
+    return undefined;
+}
+function topLevelObjectKeys(body) {
+    const keys = [];
+    let depth = 0;
+    let quote;
+    let escaped = false;
+    for (let index = 0; index < body.length; index += 1) {
+        const char = body[index];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'" || char === "`") {
+            quote = char;
+            continue;
+        }
+        if (char === "{" || char === "[" || char === "(") {
+            depth += 1;
+            continue;
+        }
+        if (char === "}" || char === "]" || char === ")") {
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (depth !== 0)
+            continue;
+        const identifier = /^[A-Za-z_$][\w$]*/.exec(body.slice(index));
+        if (!identifier)
+            continue;
+        const name = identifier[0];
+        const next = body.slice(index + name.length).match(/^\s*:/);
+        if (next)
+            keys.push(name);
+        index += name.length - 1;
+    }
+    return keys;
+}
+function dedupeCatalogErrorRefs(refs) {
+    const seen = new Set();
+    const deduped = [];
+    for (const ref of refs) {
+        const key = `${ref.key}:${ref.catalog}:${ref.catalogKey}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(ref);
+    }
+    return deduped;
+}
 function joinContractPaths(prefix, routePath) {
     if (!prefix)
         return normalizeContractPath(routePath);
@@ -336,6 +602,22 @@ function parseNamedImports(source, config, importerFile) {
     }
     return imports;
 }
+function parseNamedImportSources(source) {
+    const imports = new Map();
+    const importRegex = /import\s+\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
+    for (const match of source.matchAll(importRegex)) {
+        for (const member of match[1].split(",")) {
+            const parsed = parseImportMember(member);
+            if (!parsed)
+                continue;
+            imports.set(parsed.localName, {
+                importedName: parsed.importedName,
+                sourcePath: match[2],
+            });
+        }
+    }
+    return imports;
+}
 function parseImportMember(member) {
     const trimmed = member.trim();
     if (!trimmed)
@@ -355,6 +637,23 @@ function parseImportMember(member) {
     }
     return undefined;
 }
+function sourceFileFromImport(sourcePath, importerFile = "index.ts", files) {
+    const resolveCandidate = (candidate) => {
+        if (path.extname(candidate))
+            return candidate;
+        const candidates = [`${candidate}.ts`, `${candidate}/index.ts`];
+        return files
+            ? candidates.find((file) => files.includes(file))
+            : candidates[0];
+    };
+    if (sourcePath.startsWith("@/")) {
+        return resolveCandidate(sourcePath.slice("@/".length));
+    }
+    if (sourcePath.startsWith(".")) {
+        return resolveCandidate(normalizePath(path.join(path.dirname(importerFile), sourcePath)));
+    }
+    return undefined;
+}
 function contractFileFromImport(sourcePath, config, importerFile) {
     const contractsPath = directoryPath(config.paths.contracts);
     const aliasPrefix = `@/${contractsPath}/`;
@@ -445,39 +744,955 @@ function findContracts(contracts, routeExport) {
         return contracts.filter((contract) => contract.method === routeExport.method &&
             contractPathMatchesCatchAll(contract.path, catchAllPrefix));
     }
-    const contract = contracts.find((contract) => contract.path === routeExport.contractRef &&
-        contract.method === routeExport.method);
-    return contract ? [contract] : [];
+    const contract = contracts.find((contract) => contract.path === routeExport.contractRef &&
+        contract.method === routeExport.method);
+    return contract ? [contract] : [];
+}
+function contractPathMatchesCatchAll(contractPath, catchAllPrefix) {
+    return (contractPath === catchAllPrefix ||
+        contractPath.startsWith(`${catchAllPrefix}/`));
+}
+async function inspectDiagnostics(targetDir, files, config, convention, contracts, matchedRoutes, strict) {
+    const diagnostics = [];
+    if (!convention.nextLayout) {
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_APP_LAYOUT_NOT_FOUND",
+            message: `This directory does not match the standard Beignet app layout. CLI inspection expects ${directoryPath(config.paths.contracts)}/, ${directoryPath(config.paths.routes)}/, and ${config.paths.server}. Missing: ${convention.missingNextLayout.join(", ")}. Add the missing app files or configure their paths in beignet.config.ts.`,
+        });
+    }
+    for (const route of matchedRoutes.routes) {
+        if (route.handlerSource !== "missing")
+            continue;
+        diagnostics.push({
+            severity: "error",
+            code: "BEIGNET_ROUTE_MISSING",
+            file: route.file,
+            contract: route.exportName,
+            message: `${route.exportName} (${route.method} ${route.path}) has no matching Next route handler. Add ${methodArticle(route.method)} ${route.method} export to ${directoryPath(config.paths.routes)}/[[...path]]/route.ts or a matching route file, or remove the unused contract.`,
+        });
+    }
+    for (const routeHandler of matchedRoutes.unmatchedRouteHandlers) {
+        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)), ...(await inspectProductionReadiness(targetDir, files, config, convention)), ...(await inspectFeatureArtifactDrift(targetDir, files, config, convention)), ...(await inspectResourceSlices(targetDir, files, config, convention, strict)));
+    return dedupeDiagnostics(diagnostics);
+}
+async function inspectCanonicalConformance(targetDir, files, config, convention, strict) {
+    if (!strict || !convention.resourceGenerator)
+        return [];
+    const diagnostics = [];
+    const serverDir = directoryPath(path.dirname(config.paths.server));
+    const routeRegistryFile = `${serverDir}/routes.ts`;
+    const providerRegistryFile = `${serverDir}/providers.ts`;
+    const packageJson = await readPackageJson(targetDir, files);
+    const installedPackages = installedPackageNames(packageJson);
+    const featuresPath = directoryPath(config.paths.features);
+    const hasClientSurface = files.some((file) => file.startsWith(`${featuresPath}/`) && file.includes("/components/")) ||
+        files.some((file) => file.startsWith("client/")) ||
+        [
+            "@beignet/react-query",
+            "@beignet/react-hook-form",
+            "@beignet/react-uploads",
+            "@beignet/nuqs",
+        ].some((packageName) => installedPackages.has(packageName));
+    const requiredFiles = [
+        {
+            file: config.paths.appContext,
+            reason: "Beignet apps should define the shared AppContext type once in app-context.ts.",
+        },
+        {
+            file: config.paths.server,
+            reason: "server/index.ts should compose ports, providers, hooks, routes, and request context.",
+        },
+        {
+            file: routeRegistryFile,
+            reason: "server/routes.ts should own the central route registry and exported contract list.",
+        },
+        {
+            file: providerRegistryFile,
+            reason: "server/providers.ts should own provider registration, even when the provider list is small.",
+        },
+        {
+            file: config.paths.infrastructurePorts,
+            reason: "infra/app-ports.ts should wire concrete app ports for the selected runtime.",
+        },
+    ];
+    if (hasClientSurface) {
+        requiredFiles.push({
+            file: "client/index.ts",
+            reason: "client/index.ts should own the typed client and frontend adapter setup.",
+        });
+    }
+    if (installedPackages.has("@beignet/react-hook-form") ||
+        files.includes("client/forms.ts")) {
+        requiredFiles.push({
+            file: "client/forms.ts",
+            reason: "client/forms.ts should own React Hook Form adapter setup when form helpers are used.",
+        });
+    }
+    for (const required of requiredFiles) {
+        if (files.includes(required.file))
+            continue;
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_CANONICAL_FILE_MISSING",
+            file: required.file,
+            message: `${required.file} is missing. ${required.reason}`,
+        });
+    }
+    const sourceCache = new Map();
+    const appContextSource = files.includes(config.paths.appContext)
+        ? await readCachedSource(targetDir, config.paths.appContext, sourceCache)
+        : "";
+    const expectedContextFields = canonicalContextFields(appContextSource);
+    if (files.includes(routeRegistryFile)) {
+        const routeRegistrySource = await readCachedSource(targetDir, routeRegistryFile, sourceCache);
+        if (!importsAppContext(routeRegistrySource, routeRegistryFile, config, files)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_ROUTE_REGISTRY_APP_CONTEXT",
+                file: routeRegistryFile,
+                message: `${routeRegistryFile} should import type { AppContext } from ${config.paths.appContext} so the central route registry uses the app-wide context type.`,
+            });
+        }
+        if (!/\bexport\s+const\s+routes\s*=\s*defineRoutes\s*<\s*AppContext\s*>/.test(routeRegistrySource)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_ROUTE_REGISTRY_ROUTES_EXPORT",
+                file: routeRegistryFile,
+                message: `${routeRegistryFile} should export routes with defineRoutes<AppContext>([...]) so route registration follows the canonical Beignet path.`,
+            });
+        }
+        if (!/\bexport\s+const\s+contracts\s*=\s*contractsFromRoutes\s*\(\s*routes\s*\)/.test(routeRegistrySource)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_ROUTE_REGISTRY_CONTRACTS_EXPORT",
+                file: routeRegistryFile,
+                message: `${routeRegistryFile} should export contracts = contractsFromRoutes(routes) so OpenAPI, typed clients, and devtools derive from the central route registry.`,
+            });
+        }
+    }
+    if (files.includes(config.paths.server)) {
+        const serverSource = await readCachedSource(targetDir, config.paths.server, sourceCache);
+        const importedRouteRegistry = routeRegistryFileFromServerSource(serverSource, config.paths.server, files);
+        if (importedRouteRegistry !== routeRegistryFile) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_SERVER_ROUTE_REGISTRY",
+                file: config.paths.server,
+                message: `${config.paths.server} should import routes from ./${path.basename(routeRegistryFile, ".ts")} so server setup uses the central route registry.`,
+            });
+        }
+        if (!importsAppContext(serverSource, config.paths.server, config, files)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_SERVER_APP_CONTEXT",
+                file: config.paths.server,
+                message: `${config.paths.server} should import type { AppContext } from ${config.paths.appContext} and thread that context through createNextServer and hooks.`,
+            });
+        }
+        // Apps may keep the context blueprint in a sibling server/context.ts
+        // (defineServerContext) instead of inline in the server file.
+        const serverContextFile = `${serverDir}/context.ts`;
+        const serverContextSource = files.includes(serverContextFile)
+            ? await readCachedSource(targetDir, serverContextFile, sourceCache)
+            : "";
+        const contextBlueprintFile = files.includes(serverContextFile)
+            ? serverContextFile
+            : config.paths.server;
+        const contextBlueprintSource = `${serverSource}\n${serverContextSource}`;
+        for (const field of expectedContextFields) {
+            if (new RegExp(`\\b${escapeRegExp(field)}\\s*[:,]`).test(contextBlueprintSource)) {
+                continue;
+            }
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_CONTEXT_FIELD_MISSING",
+                file: contextBlueprintFile,
+                message: `${contextBlueprintFile} context factories do not appear to return ${field}. Keep the canonical AppContext shape aligned with app-context.ts.`,
+            });
+        }
+    }
+    const featureRoutesPath = `${featuresPath}/`;
+    for (const file of files) {
+        if (!file.startsWith(featureRoutesPath) || !file.endsWith("/routes.ts")) {
+            continue;
+        }
+        const source = await readCachedSource(targetDir, file, sourceCache);
+        if (!source.includes("defineRouteGroup"))
+            continue;
+        if (!importsAppContext(source, file, config, files)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_FEATURE_ROUTE_APP_CONTEXT",
+                file,
+                message: `${file} should import type { AppContext } from ${config.paths.appContext} so feature routes use the app-wide context type.`,
+            });
+        }
+        if (!/defineRouteGroup\s*<\s*AppContext\s*>/.test(source)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_FEATURE_ROUTE_GROUP_CONTEXT",
+                file,
+                message: `${file} should call defineRouteGroup<AppContext>(...) for ordinary feature route groups, or defineRouteGroup<AppContext>()({ ... }) when group-level hooks enrich ctx.`,
+            });
+        }
+    }
+    for (const file of files) {
+        if (file === config.paths.appContext ||
+            !file.endsWith(".ts") ||
+            file.endsWith(".d.ts")) {
+            continue;
+        }
+        const source = await readCachedSource(targetDir, file, sourceCache);
+        if (!/\b(?:type|interface)\s+AppContext\b/.test(source))
+            continue;
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_APP_CONTEXT_REDECLARED",
+            file,
+            message: `${file} declares AppContext locally. Import AppContext from "@/app-context" so routes, hooks, use cases, jobs, schedules, and tests share one context model.`,
+        });
+    }
+    return diagnostics;
+}
+function canonicalContextFields(appContextSource) {
+    const fields = ["requestId", "ports"];
+    for (const field of ["actor", "auth", "gate"]) {
+        if (appContextSource.includes(`${field}:`))
+            fields.push(field);
+    }
+    return fields;
+}
+function importsAppContext(source, importerFile, config, files) {
+    const importRegex = /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
+    for (const match of source.matchAll(importRegex)) {
+        const sourceFile = sourceFileFromImport(match[2], importerFile, files);
+        if (sourceFile !== config.paths.appContext)
+            continue;
+        for (const member of match[1].split(",")) {
+            const parsed = parseImportMember(member);
+            if (parsed?.importedName === "AppContext" &&
+                parsed.localName === "AppContext") {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+async function inspectAuthzAuditDrift(targetDir, files, config, convention, contracts) {
+    if (!convention.resourceGenerator)
+        return [];
+    const diagnostics = [];
+    const featuresPath = directoryPath(config.paths.features);
+    const sourceCache = new Map();
+    for (const contract of contracts) {
+        const feature = featureNameFromContractFile(contract.file, config);
+        if (!feature)
+            continue;
+        const ability = contract.metadata?.authorizationAbility;
+        if (ability) {
+            const policyFile = `${featuresPath}/${feature}/policy.ts`;
+            if (!files.includes(policyFile)) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "BEIGNET_AUTHZ_POLICY_MISSING",
+                    file: contract.file,
+                    contract: contract.exportName,
+                    message: `${contract.exportName} declares authorization ability "${ability}", but ${policyFile} is missing. Add a feature policy for the ability or remove stale authorization metadata from the contract.`,
+                });
+            }
+            else {
+                const policySource = await readCachedSource(targetDir, policyFile, sourceCache);
+                if (!policySource.includes(ability)) {
+                    diagnostics.push({
+                        severity: "warning",
+                        code: "BEIGNET_AUTHZ_POLICY_DRIFT",
+                        file: policyFile,
+                        contract: contract.exportName,
+                        message: `${contract.exportName} declares authorization ability "${ability}", but ${policyFile} does not mention that ability. Keep contract metadata aligned with the feature policy.`,
+                    });
+                }
+            }
+            const policyTestFiles = featureTestFiles(files, featuresPath, feature, {
+                policyOnly: true,
+            });
+            if (policyTestFiles.length === 0 ||
+                !(await anyFileContains(targetDir, policyTestFiles, ability, sourceCache))) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "BEIGNET_AUTHZ_POLICY_TEST_MISSING",
+                    file: policyTestFiles[0] ??
+                        `${featuresPath}/${feature}/tests/policy.test.ts`,
+                    contract: contract.exportName,
+                    message: `${contract.exportName} declares authorization ability "${ability}", but no feature policy test appears to cover it. Add policy matrix coverage so authorization metadata, policy behavior, and tests stay aligned.`,
+                });
+            }
+        }
+        if (contract.metadata?.auditRequired) {
+            const featureSourceFiles = featureRuntimeFiles(files, featuresPath, feature);
+            if (featureSourceFiles.length === 0 ||
+                !(await anyFileMatches(targetDir, featureSourceFiles, /\baudit\.record\s*\(/, sourceCache))) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "BEIGNET_AUDIT_WRITE_MISSING",
+                    file: contract.file,
+                    contract: contract.exportName,
+                    message: `${contract.exportName} declares audit-required metadata, but no feature runtime file appears to record through ctx.ports.audit or a transaction audit port. Record the audited business action in the use case, listener, job, schedule, or upload completion hook.`,
+                });
+            }
+            const testFiles = featureTestFiles(files, featuresPath, feature);
+            if (testFiles.length === 0 ||
+                !(await anyFileMatches(targetDir, testFiles, /\b(assertAuditEntry|assertAuditEntries|audit\.entries)\b/, sourceCache))) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "BEIGNET_AUDIT_TEST_MISSING",
+                    file: testFiles[0] ?? `${featuresPath}/${feature}/tests/`,
+                    contract: contract.exportName,
+                    message: `${contract.exportName} declares audit-required metadata, but no feature test appears to assert audit behavior. Add an audit assertion for the sensitive workflow so contract metadata and durable activity logging stay aligned.`,
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+async function inspectRouteErrorCatalogDrift(targetDir, files, config, convention, contracts, strict) {
+    if (!convention.resourceGenerator)
+        return [];
+    const diagnostics = [];
+    const featuresPath = directoryPath(config.paths.features);
+    const sharedErrorsFile = `${featuresPath}/shared/errors.ts`;
+    const sourceCache = new Map();
+    const sharedErrorKeys = files.includes(sharedErrorsFile)
+        ? parseErrorCatalogKeys(await readCachedSource(targetDir, sharedErrorsFile, sourceCache))
+        : undefined;
+    const declaredByFeature = new Map();
+    const contractFiles = new Set(contracts.map((contract) => contract.file));
+    const sharedCatalogBindingsByFile = new Map();
+    for (const file of contractFiles) {
+        const source = await readCachedSource(targetDir, file, sourceCache);
+        sharedCatalogBindingsByFile.set(file, sharedErrorCatalogBindings(source, file, files, sharedErrorsFile));
+    }
+    for (const contract of contracts) {
+        const catalogErrors = contract.metadata?.catalogErrors ?? [];
+        if (catalogErrors.length === 0)
+            continue;
+        const feature = featureNameFromContractFile(contract.file, config);
+        if (feature) {
+            const declared = declaredByFeature.get(feature) ?? new Set();
+            for (const error of catalogErrors)
+                declared.add(error.key);
+            declaredByFeature.set(feature, declared);
+        }
+        const sharedBindings = sharedCatalogBindingsByFile.get(contract.file) ?? new Set();
+        for (const error of catalogErrors) {
+            if (!sharedBindings.has(error.catalog))
+                continue;
+            if (!sharedErrorKeys) {
+                diagnostics.push({
+                    severity: "error",
+                    code: "BEIGNET_ROUTE_ERROR_CATALOG_MISSING",
+                    file: sharedErrorsFile,
+                    contract: contract.exportName,
+                    message: `${contract.exportName} declares route-owned error ${error.key} from ${sharedErrorsFile}, but the shared error catalog file is missing. Add ${sharedErrorsFile} or remove the stale contract .errors(...) entry.`,
+                });
+                continue;
+            }
+            if (!sharedErrorKeys.has(error.catalogKey)) {
+                diagnostics.push({
+                    severity: "error",
+                    code: "BEIGNET_ROUTE_ERROR_CATALOG_ENTRY_MISSING",
+                    file: sharedErrorsFile,
+                    contract: contract.exportName,
+                    message: `${contract.exportName} declares route-owned error ${error.key}, but ${sharedErrorsFile} does not define ${error.catalogKey}. Add it to defineErrors(...) or remove the stale contract .errors(...) entry.`,
+                });
+            }
+        }
+    }
+    for (const feature of featureNamesFromContracts(contracts, config)) {
+        const featureRuntime = featureErrorRuntimeFiles(files, featuresPath, feature);
+        const declared = declaredByFeature.get(feature) ?? new Set();
+        const used = await featureAppErrorUses(targetDir, featureRuntime, sourceCache);
+        for (const [errorName, file] of used) {
+            if (sharedErrorKeys && !sharedErrorKeys.has(errorName)) {
+                diagnostics.push({
+                    severity: "error",
+                    code: "BEIGNET_APP_ERROR_CATALOG_ENTRY_MISSING",
+                    file: sharedErrorsFile,
+                    message: `${file} creates appError("${errorName}"), but ${sharedErrorsFile} does not define ${errorName}. Add it to the shared error catalog or fix the stale appError(...) call.`,
+                });
+            }
+            if (!declared.has(errorName)) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "BEIGNET_APP_ERROR_CONTRACT_MISSING",
+                    file,
+                    message: `${file} creates appError("${errorName}"), but no ${feature} contract declares ${errorName} with .errors(...). Declare the route-owned error on the contract that can surface it, or move the non-HTTP error out of route-backed workflows.`,
+                });
+            }
+        }
+        if (!strict)
+            continue;
+        for (const errorName of declared) {
+            if (!isFeatureOwnedErrorName(errorName, feature))
+                continue;
+            if (used.has(errorName))
+                continue;
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_ROUTE_ERROR_UNUSED",
+                file: `${featuresPath}/${feature}/contracts.ts`,
+                message: `${feature} contracts declare ${errorName}, but no ${feature} runtime file appears to create appError("${errorName}"). Remove the stale .errors(...) entry or add runtime coverage for the route-owned error.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+async function inspectProductionReadiness(targetDir, files, config, convention) {
+    if (!convention.resourceGenerator)
+        return [];
+    const diagnostics = [];
+    const sourceCache = new Map();
+    const packageJson = await readPackageJson(targetDir, files);
+    const installedPackages = installedPackageNames(packageJson);
+    const providerDoctorRules = await providerDoctorRulesForInstalledPackages(targetDir, packageJson);
+    const configFiles = operationalConfigFiles(files, config);
+    for (const file of files) {
+        if (!file.endsWith(".ts") || file.endsWith(".test.ts"))
+            continue;
+        const source = await readCachedSource(targetDir, file, sourceCache);
+        if (containsCallExpression(source, "createDevtoolsRoute") &&
+            /\benabled\s*:\s*true\b/.test(source) &&
+            !/\bauthorize\s*:/.test(source)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_DEVTOOLS_ROUTE_EXPOSED",
+                file,
+                message: `${file} enables devtools with enabled: true and no authorize callback. Keep devtools disabled in production or add app-owned authorization before exposing diagnostic data.`,
+            });
+        }
+        if (file.startsWith("app/api/cron/") &&
+            file.endsWith("/route.ts") &&
+            !/\bCRON_SECRET\b/.test(source) &&
+            !/\bcreateOutboxDrainRoute\s*\(/.test(source)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_CRON_SECRET_MISSING",
+                file,
+                message: `${file} looks like a cron route that does not reference CRON_SECRET. Protect cron entrypoints with a shared secret or a framework helper such as createOutboxDrainRoute(...).`,
+            });
+        }
+        if (isFeatureUploadDefinition(file, config) &&
+            containsCallExpression(source, "defineUpload") &&
+            !/\bmaxSizeBytes\s*:/.test(source)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_UPLOAD_SIZE_LIMIT_MISSING",
+                file,
+                message: `${file} defines an upload without maxSizeBytes. Add an explicit size limit so upload behavior is predictable before deployment.`,
+            });
+        }
+        if (isRouteServerOrInfraFile(file, config) &&
+            containsCallExpression(source, "createCorsHooks") &&
+            /\bcredentials\s*:\s*true\b/.test(source) &&
+            /(?:\borigin\b|\borigins\b)\s*:\s*(?:["']\*["']|\[\s*["']\*["'])/.test(source)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_CORS_CREDENTIALS_WILDCARD",
+                file,
+                message: `${file} enables credentialed CORS with a wildcard origin. Use an explicit origin allow-list so cookies and authorization headers are not exposed to arbitrary origins.`,
+            });
+        }
+    }
+    for (const provider of providerDoctorRules) {
+        if (!installedPackages.has(provider.packageName))
+            continue;
+        for (const envVar of provider.requiredEnv ?? []) {
+            if (await anyFileContains(targetDir, configFiles, envVar, sourceCache)) {
+                continue;
+            }
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_PROVIDER_ENV_MISSING",
+                file: "package.json",
+                message: `${provider.packageName} is installed, but ${envVar} is not mentioned in app env/config files. Add the expected environment variable or remove the unused provider package.`,
+            });
+        }
+    }
+    if (installedPackages.has("@beignet/provider-auth-better-auth")) {
+        if (!hasBetterAuthRoute(files, config)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_AUTH_ROUTE_MISSING",
+                file: directoryPath(config.paths.routes),
+                message: "@beignet/provider-auth-better-auth is installed, but no Better Auth route was found. Expose Better Auth through app/api/auth/[...all]/route.ts or remove the unused auth provider.",
+            });
+        }
+        if (!(await anyFileContains(targetDir, configFiles, "BETTER_AUTH_TRUSTED_ORIGINS", sourceCache))) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_AUTH_TRUSTED_ORIGINS_MISSING",
+                file: "package.json",
+                message: "@beignet/provider-auth-better-auth is installed, but BETTER_AUTH_TRUSTED_ORIGINS is not mentioned in app env/config files. Add it before deploying across multiple origins or document why the app is single-origin only.",
+            });
+        }
+    }
+    return diagnostics;
+}
+// Local-dev ranges such as the generated-app conformance vendoring point each
+// @beignet/* package at a different path on purpose, so they are exempt from
+// the declared-range comparison. Their installed versions still participate in
+// the installed-version comparison.
+const localOnlyRangePrefixes = ["file:", "link:", "workspace:"];
+async function inspectVersionSkew(targetDir, files) {
+    const packageJson = await readPackageJson(targetDir, files);
+    const declaredRanges = new Map();
+    for (const section of [
+        packageJson?.dependencies,
+        packageJson?.devDependencies,
+    ]) {
+        for (const [name, range] of Object.entries(section ?? {})) {
+            if (name.startsWith("@beignet/"))
+                declaredRanges.set(name, range);
+        }
+    }
+    if (declaredRanges.size === 0)
+        return [];
+    const diagnostics = [];
+    const comparableRanges = [...declaredRanges].filter(([, range]) => !localOnlyRangePrefixes.some((prefix) => range.startsWith(prefix)));
+    const distinctRanges = new Set(comparableRanges.map(([, range]) => range));
+    if (distinctRanges.size > 1) {
+        const pairs = comparableRanges
+            .map(([name, range]) => `${name}@${range}`)
+            .join(", ");
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_VERSION_SKEW",
+            file: "package.json",
+            message: `package.json declares mixed @beignet/* version ranges: ${pairs}. Align all @beignet/* packages to one version; they release together.`,
+        });
+    }
+    const installedVersions = await readInstalledBeignetVersions(targetDir);
+    const distinctInstalled = new Set(installedVersions.values());
+    if (distinctInstalled.size > 1) {
+        const pairs = [...installedVersions]
+            .map(([name, version]) => `${name}@${version}`)
+            .join(", ");
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_VERSION_SKEW",
+            file: "package.json",
+            message: `node_modules contains mixed @beignet/* versions: ${pairs}. Align the declared @beignet/* ranges to one version, then reinstall so a single version is installed.`,
+        });
+    }
+    const coreVersion = installedVersions.get("@beignet/core");
+    const cliVersion = getCliVersion();
+    if (coreVersion !== undefined &&
+        cliVersion !== "0.0.0" &&
+        coreVersion !== cliVersion) {
+        diagnostics.push({
+            severity: "hint",
+            code: "BEIGNET_CLI_VERSION_SKEW",
+            file: "package.json",
+            message: `This CLI is ${cliVersion} but the app uses @beignet/core ${coreVersion}. Prefer the app-local CLI via \`bun beignet\` so the CLI and framework versions stay aligned.`,
+        });
+    }
+    return diagnostics;
+}
+async function readInstalledBeignetVersions(targetDir) {
+    const scopeDir = path.join(targetDir, "node_modules", "@beignet");
+    let entries;
+    try {
+        entries = await readdir(scopeDir);
+    }
+    catch {
+        return new Map();
+    }
+    const versions = new Map();
+    for (const entry of entries.sort()) {
+        if (entry.startsWith("."))
+            continue;
+        const installedPackageJson = await readJsonIfExists(path.join(scopeDir, entry, "package.json"));
+        if (installedPackageJson?.version) {
+            versions.set(`@beignet/${entry}`, installedPackageJson.version);
+        }
+    }
+    return versions;
+}
+async function inspectProviderMetadataDrift(targetDir, files, convention) {
+    if (!convention.resourceGenerator)
+        return [];
+    const packageJson = await readPackageJson(targetDir, files);
+    const packageNames = [...installedPackageNames(packageJson)];
+    const diagnostics = [];
+    for (const packageName of packageNames) {
+        const source = await readProviderPackageMetadataSource(targetDir, packageName);
+        if (!source)
+            continue;
+        const result = parseProviderPackageMetadata(source.metadata);
+        if (result.success)
+            continue;
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_PROVIDER_METADATA_INVALID",
+            file: diagnosticPackageJsonFile(targetDir, source.file),
+            message: `${packageName} declares invalid beignet.provider metadata: ${formatProviderMetadataIssues(result.issues)}. Fix the provider package metadata or remove the package until it publishes a valid manifest.`,
+        });
+    }
+    return diagnostics;
+}
+async function inspectProviderRegistrationDrift(targetDir, files, config, convention) {
+    if (!convention.resourceGenerator)
+        return [];
+    const diagnostics = [];
+    const packageJson = await readPackageJson(targetDir, files);
+    const installedPackages = installedPackageNames(packageJson);
+    const providerDoctorRules = await providerDoctorRulesForInstalledPackages(targetDir, packageJson);
+    const providerFiles = serverProviderFiles(files, config);
+    const sourceCache = new Map();
+    const providerSource = (await Promise.all(providerFiles.map((file) => readCachedSource(targetDir, file, sourceCache)))).join("\n");
+    const providerListSource = extractProviderListSource(providerSource);
+    const providerEntries = providerListSource === undefined
+        ? []
+        : providerListEntries(providerListSource);
+    for (const provider of providerDoctorRules) {
+        const severity = provider.registrationSeverity;
+        if (severity === undefined)
+            continue;
+        if (!installedPackages.has(provider.packageName))
+            continue;
+        if (provider.tokens.some((token) => providerEntries.some((entry) => entry.includes(token)))) {
+            continue;
+        }
+        diagnostics.push({
+            severity,
+            code: "BEIGNET_PROVIDER_REGISTRATION_MISSING",
+            file: providerFiles[0] ?? config.paths.server,
+            message: severity === "hint"
+                ? `${provider.packageName} is installed, but ${provider.displayName} is not registered in server/providers.ts. Register ${registrationTokenHint(provider.tokens)} in the exported providers array or remove the dependency.`
+                : `${provider.packageName} is installed, but ${provider.displayName} is not registered in server/providers.ts. Add it to the exported providers array or remove the unused package.`,
+        });
+    }
+    const drizzleIndex = findProviderEntryIndex(providerEntries, [
+        "drizzleTursoProvider",
+        "createDrizzleTursoProvider",
+    ]);
+    const appDatabaseProviderIndex = findProviderEntryIndex(providerEntries, [
+        "starterDatabaseProvider",
+        "exampleDatabaseProvider",
+        "twitterDatabaseProvider",
+        "databaseProvider",
+    ]);
+    if (appDatabaseProviderIndex >= 0 &&
+        drizzleIndex >= 0 &&
+        appDatabaseProviderIndex < drizzleIndex) {
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_PROVIDER_ORDER",
+            file: providerFiles[0] ?? config.paths.server,
+            message: "An app database provider is registered before createDrizzleTursoProvider(...). Register the Drizzle/Turso provider first so app-owned database wiring can read ctx.ports.db during setup.",
+        });
+    }
+    return diagnostics;
+}
+function isFeatureUploadDefinition(file, config) {
+    const featuresPath = directoryPath(config.paths.features);
+    return new RegExp(`^${escapeRegExp(featuresPath)}/[^/]+/uploads/[^/]+\\.ts$`).test(file);
+}
+function operationalConfigFiles(files, config) {
+    return files.filter((file) => {
+        if (file === ".env.example")
+            return true;
+        if (file === "drizzle.config.ts")
+            return true;
+        if (file === "lib/env.ts" || file === "lib/better-auth.ts")
+            return true;
+        if (isInfraOrServerFile(file, config) && file.endsWith(".ts"))
+            return true;
+        return false;
+    });
+}
+async function readPackageJson(targetDir, files) {
+    if (!files.includes("package.json"))
+        return undefined;
+    return JSON.parse(await readFile(path.join(targetDir, "package.json"), "utf8"));
+}
+async function providerDoctorRulesForInstalledPackages(targetDir, packageJson) {
+    const packageNames = [...installedPackageNames(packageJson)];
+    const rules = await Promise.all(packageNames.map(async (packageName) => {
+        const source = await readProviderPackageMetadataSource(targetDir, packageName);
+        if (!source)
+            return undefined;
+        const result = parseProviderPackageMetadata(source.metadata);
+        if (!result.success)
+            return undefined;
+        return providerDoctorRuleFromMetadata(packageName, result.metadata);
+    }));
+    return rules.filter((rule) => Boolean(rule));
+}
+async function readProviderPackageMetadataSource(targetDir, packageName) {
+    for (const candidate of providerPackageJsonCandidates(targetDir, packageName)) {
+        const packageJson = await readJsonIfExists(candidate);
+        const metadata = packageJson?.beignet?.provider;
+        if (metadata !== undefined) {
+            return { packageName, file: candidate, metadata };
+        }
+    }
+    return undefined;
+}
+function providerPackageJsonCandidates(targetDir, packageName) {
+    const candidates = [
+        path.join(targetDir, "node_modules", ...packageName.split("/"), "package.json"),
+    ];
+    if (packageName.startsWith("@beignet/")) {
+        candidates.push(path.resolve(
+        // import.meta.dir is Bun-only; the published bin also runs under
+        // plain Node, where only import.meta.url is available.
+        path.dirname(fileURLToPath(import.meta.url)), "../../..", "packages", packageName.slice("@beignet/".length), "package.json"));
+    }
+    return candidates;
+}
+async function readJsonIfExists(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function providerDoctorRuleFromMetadata(packageName, metadata) {
+    const registration = metadata.registration;
+    return {
+        packageName,
+        displayName: metadata.displayName ?? packageName,
+        tokens: registration?.tokens ?? [],
+        appPorts: metadata.appPorts ?? [],
+        requiredEnv: metadata.requiredEnv ?? [],
+        registrationSeverity: registration?.severity ??
+            (registration?.required === true ? "warning" : undefined),
+    };
+}
+function registrationTokenHint(tokens) {
+    const token = tokens[0];
+    if (!token)
+        return "the provider";
+    return token.startsWith("create") ? `${token}()` : token;
+}
+function diagnosticPackageJsonFile(targetDir, file) {
+    const relative = normalizePath(path.relative(targetDir, file));
+    if (relative.startsWith("../"))
+        return "package.json";
+    return relative;
+}
+function formatProviderMetadataIssues(issues) {
+    return issues.map((issue) => `${issue.path} ${issue.message}`).join("; ");
+}
+function installedPackageNames(packageJson) {
+    return new Set([
+        ...Object.keys(packageJson?.dependencies ?? {}),
+        ...Object.keys(packageJson?.devDependencies ?? {}),
+        ...Object.keys(packageJson?.peerDependencies ?? {}),
+    ]);
+}
+function serverProviderFiles(files, config) {
+    const serverDir = directoryPath(path.dirname(config.paths.server));
+    const candidates = [`${serverDir}/providers.ts`, config.paths.server];
+    return candidates.filter((file) => files.includes(file));
+}
+function extractProviderListSource(source) {
+    const listMatches = [
+        ...source.matchAll(/\bproviders\s*=\s*\[([\s\S]*?)\]\s*(?:;|as const)/g),
+        ...source.matchAll(/\bproviders\s*:\s*\[([\s\S]*?)\]/g),
+    ];
+    if (listMatches.length === 0)
+        return undefined;
+    return listMatches.map((match) => match[1]).join("\n");
+}
+function providerListEntries(source) {
+    const entries = [];
+    let current = "";
+    let depth = 0;
+    let quote;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    for (let index = 0; index < source.length; index += 1) {
+        const char = source[index];
+        const next = source[index + 1];
+        if (lineComment) {
+            if (char === "\n") {
+                lineComment = false;
+                current += char;
+            }
+            continue;
+        }
+        if (blockComment) {
+            if (char === "*" && next === "/") {
+                blockComment = false;
+                index += 1;
+            }
+            continue;
+        }
+        if (quote) {
+            current += char;
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (char === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            lineComment = true;
+            index += 1;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            blockComment = true;
+            index += 1;
+            continue;
+        }
+        if (char === '"' || char === "'" || char === "`") {
+            quote = char;
+            current += char;
+            continue;
+        }
+        if (char === "(" || char === "[" || char === "{") {
+            depth += 1;
+        }
+        else if (char === ")" || char === "]" || char === "}") {
+            depth = Math.max(0, depth - 1);
+        }
+        if (char === "," && depth === 0) {
+            const entry = current.trim();
+            if (entry)
+                entries.push(entry);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    const entry = current.trim();
+    if (entry)
+        entries.push(entry);
+    return entries;
+}
+function findProviderEntryIndex(entries, tokens) {
+    return entries.findIndex((entry) => tokens.some((token) => entry.includes(token)));
+}
+function hasBetterAuthRoute(files, config) {
+    const routesPath = directoryPath(config.paths.routes);
+    return files.some((file) => file.startsWith(`${routesPath}/auth/`) && file.endsWith("/route.ts"));
+}
+function featureNameFromContractFile(file, config) {
+    const featuresPath = directoryPath(config.paths.features);
+    const match = new RegExp(`^${escapeRegExp(featuresPath)}/([^/]+)/contracts\\.ts$`).exec(file);
+    return match?.[1];
+}
+function featureRuntimeFiles(files, featuresPath, feature) {
+    const runtimeFolders = [
+        "jobs",
+        "listeners",
+        "schedules",
+        "uploads",
+        "use-cases",
+    ];
+    return files.filter((file) => {
+        if (!file.endsWith(".ts") || file.endsWith(".test.ts"))
+            return false;
+        return runtimeFolders.some((folder) => file.startsWith(`${featuresPath}/${feature}/${folder}/`));
+    });
+}
+function featureTestFiles(files, featuresPath, feature, options = {}) {
+    return files.filter((file) => {
+        if (!file.startsWith(`${featuresPath}/${feature}/`) ||
+            !file.endsWith(".test.ts")) {
+            return false;
+        }
+        return !options.policyOnly || file.endsWith("/policy.test.ts");
+    });
+}
+function featureNamesFromContracts(contracts, config) {
+    return [
+        ...new Set(contracts
+            .map((contract) => featureNameFromContractFile(contract.file, config))
+            .filter((feature) => feature !== undefined)),
+    ].sort();
+}
+function sharedErrorCatalogBindings(source, file, files, sharedErrorsFile) {
+    const bindings = new Set();
+    const imports = parseNamedImportSources(source);
+    for (const [localName, imported] of imports) {
+        if (imported.importedName !== "errors")
+            continue;
+        if (importResolvesToFile(imported.sourcePath, file, files, sharedErrorsFile)) {
+            bindings.add(localName);
+        }
+    }
+    return bindings;
 }
-function contractPathMatchesCatchAll(contractPath, catchAllPrefix) {
-    return (contractPath === catchAllPrefix ||
-        contractPath.startsWith(`${catchAllPrefix}/`));
+function importResolvesToFile(sourcePath, importerFile, files, expectedFile) {
+    return (sourceFileFromImport(sourcePath, importerFile, files) === expectedFile ||
+        sourceFileFromImport(sourcePath, importerFile) === expectedFile);
 }
-async function inspectDiagnostics(targetDir, files, config, convention, contracts, matchedRoutes, strict) {
-    const diagnostics = [];
-    if (!convention.nextLayout) {
-        diagnostics.push({
-            severity: "warning",
-            code: "CK_APP_LAYOUT_NOT_FOUND",
-            message: `This directory does not match the standard Beignet app layout. CLI inspection expects ${directoryPath(config.paths.contracts)}/, ${directoryPath(config.paths.routes)}/, and ${config.paths.server}. Missing: ${convention.missingNextLayout.join(", ")}. Add the missing app files or configure their paths in beignet.config.ts.`,
-        });
+function featureErrorRuntimeFiles(files, featuresPath, feature) {
+    const runtimeFiles = new Set(featureRuntimeFiles(files, featuresPath, feature));
+    const policyFile = `${featuresPath}/${feature}/policy.ts`;
+    if (files.includes(policyFile))
+        runtimeFiles.add(policyFile);
+    return [...runtimeFiles].sort();
+}
+async function featureAppErrorUses(targetDir, files, sourceCache) {
+    const uses = new Map();
+    for (const file of files) {
+        const source = await readCachedSource(targetDir, file, sourceCache);
+        for (const match of source.matchAll(/\bappError\s*\(\s*["']([^"']+)["']/g)) {
+            if (!uses.has(match[1]))
+                uses.set(match[1], file);
+        }
     }
-    for (const route of matchedRoutes.routes) {
-        if (route.handlerSource !== "missing")
-            continue;
-        diagnostics.push({
-            severity: "error",
-            code: "CK_ROUTE_MISSING",
-            file: route.file,
-            contract: route.exportName,
-            message: `${route.exportName} (${route.method} ${route.path}) has no matching Next route handler. Add ${methodArticle(route.method)} ${route.method} export to ${directoryPath(config.paths.routes)}/[[...path]]/route.ts or a matching route file, or remove the unused contract.`,
-        });
+    return uses;
+}
+function isFeatureOwnedErrorName(errorName, feature) {
+    const singularPascal = pascalCase(singularize(feature));
+    const pluralPascal = pascalCase(feature);
+    return (errorName.startsWith(singularPascal) || errorName.startsWith(pluralPascal));
+}
+async function anyFileContains(targetDir, files, needle, sourceCache) {
+    for (const file of files) {
+        const source = await readCachedSource(targetDir, file, sourceCache);
+        if (source.includes(needle))
+            return true;
     }
-    for (const routeHandler of matchedRoutes.unmatchedRouteHandlers) {
-        diagnostics.push(unmatchedRouteDiagnostic(routeHandler));
+    return false;
+}
+async function anyFileMatches(targetDir, files, pattern, sourceCache) {
+    for (const file of files) {
+        const source = await readCachedSource(targetDir, file, sourceCache);
+        if (pattern.test(source))
+            return true;
     }
-    diagnostics.push(...(await inspectPackageScripts(targetDir, files, convention)), ...(await inspectOpenApiDrift(targetDir, files, config, contracts)), ...(await inspectFeatureRouteRegistration(targetDir, files, config, convention, contracts)), ...(await inspectPortProviderDrift(targetDir, files, config, convention)), ...(await inspectDatabaseLifecycleDrift(targetDir, files, config, convention, strict)), ...(await inspectServerlessFootguns(targetDir, files)), ...(await inspectFeatureArtifactDrift(targetDir, files, config, convention)), ...(await inspectResourceSlices(targetDir, files, config, convention, strict)));
-    return dedupeDiagnostics(diagnostics);
+    return false;
+}
+async function readCachedSource(targetDir, file, sourceCache) {
+    const cached = sourceCache.get(file);
+    if (cached !== undefined)
+        return cached;
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    sourceCache.set(file, source);
+    return source;
 }
 async function inspectFeatureArtifactDrift(targetDir, files, config, convention) {
     if (!convention.resourceGenerator)
@@ -489,11 +1704,22 @@ async function inspectFeatureArtifactDrift(targetDir, files, config, convention)
         !(await appHasUploadRoute(targetDir, files, config))) {
         diagnostics.push({
             severity: "warning",
-            code: "CK_UPLOAD_ROUTE_MISSING",
+            code: "BEIGNET_UPLOAD_ROUTE_MISSING",
             file: uploadDefinitions[0],
             message: "This app defines feature uploads but no known upload route. Register the upload registry with createUploadRouter(...) and expose it through createUploadRoute(...) so browser uploads can reach the workflow.",
         });
     }
+    for (const file of files) {
+        const match = new RegExp(`^${escapeRegExp(featuresPath)}/([^/]+)/[^/]+\\.test\\.ts$`).exec(file);
+        if (!match)
+            continue;
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_FEATURE_TEST_PLACEMENT",
+            file,
+            message: `${file} places a test directly under ${featuresPath}/${match[1]}/. Move feature behavior tests into ${featuresPath}/${match[1]}/tests/ so feature suites stay in the canonical folder; adjacent *.test.ts files are for infra and server modules.`,
+        });
+    }
     for (const file of files) {
         if (!file.endsWith(".ts") ||
             file.endsWith(".test.ts") ||
@@ -504,7 +1730,7 @@ async function inspectFeatureArtifactDrift(targetDir, files, config, convention)
         if (misplaced) {
             diagnostics.push({
                 severity: "warning",
-                code: "CK_FEATURE_ARTIFACT_FOLDER",
+                code: "BEIGNET_FEATURE_ARTIFACT_FOLDER",
                 file,
                 message: `${file} uses ${misplaced.actual}, but Beignet expects ${misplaced.expected}. Keep feature-owned workflow artifacts in the canonical feature folders so CLI generators, docs, and architecture lint stay aligned.`,
             });
@@ -517,7 +1743,7 @@ async function inspectFeatureArtifactDrift(targetDir, files, config, convention)
         if (containsCallExpression(source, "createInlineNotificationDispatcher")) {
             diagnostics.push({
                 severity: "warning",
-                code: "CK_NOTIFICATION_PORT_BYPASS",
+                code: "BEIGNET_NOTIFICATION_PORT_BYPASS",
                 file,
                 message: `${file} creates a notification dispatcher directly. Application workflows should send notifications through ctx.ports.notifications so delivery can be swapped, tested, instrumented, and run through jobs/outbox consistently.`,
             });
@@ -549,6 +1775,8 @@ function misplacedFeatureArtifactFolder(file, featuresPath) {
         return undefined;
     const folder = match[2];
     const mappings = {
+        command: "tasks/",
+        commands: "tasks/",
         event: "domain/events/",
         events: "domain/events/",
         job: "jobs/",
@@ -556,6 +1784,7 @@ function misplacedFeatureArtifactFolder(file, featuresPath) {
         notification: "notifications/",
         schedule: "schedules/",
         scheduled: "schedules/",
+        task: "tasks/",
         upload: "uploads/",
     };
     const expected = mappings[folder];
@@ -598,7 +1827,7 @@ async function inspectServerlessFootguns(targetDir, files) {
             /\bset(?:Interval|Timeout)\s*\(/.test(source)) {
             diagnostics.push({
                 severity: "warning",
-                code: "CK_PROVIDER_BACKGROUND_WORK",
+                code: "BEIGNET_PROVIDER_BACKGROUND_WORK",
                 file,
                 message: `${file} starts timer-based work from provider/server setup. Serverless apps should expose bounded runtime entrypoints such as cron routes, scheduled handlers, job functions, or worker processes instead of provider polling loops.`,
             });
@@ -609,7 +1838,7 @@ async function inspectServerlessFootguns(targetDir, files) {
             /\bdrainOutbox\s*\(/.test(source)) {
             diagnostics.push({
                 severity: "warning",
-                code: "CK_PROVIDER_OUTBOX_DRAIN",
+                code: "BEIGNET_PROVIDER_OUTBOX_DRAIN",
                 file,
                 message: `${file} drains the outbox from provider lifecycle code. Move outbox delivery to createOutboxDrainRoute(...) or another bounded runtime entrypoint so imports and serverless cold starts do not run background work.`,
             });
@@ -617,12 +1846,13 @@ async function inspectServerlessFootguns(targetDir, files) {
         if (file.startsWith("app/api/cron/") &&
             file.endsWith("/route.ts") &&
             !/\bauthorization\b/i.test(source) &&
-            !/\bcreateOutboxDrainRoute\s*\(/.test(source)) {
+            !/\bcreateOutboxDrainRoute\s*\(/.test(source) &&
+            !/\bcreateScheduleRoute\s*\(/.test(source)) {
             diagnostics.push({
                 severity: "warning",
-                code: "CK_CRON_ROUTE_AUTH_MISSING",
+                code: "BEIGNET_CRON_ROUTE_AUTH_MISSING",
                 file,
-                message: `${file} looks like a cron route without an authorization check. Require a shared secret or use a framework route helper such as createOutboxDrainRoute(...).`,
+                message: `${file} looks like a cron route without an authorization check. Require a shared secret or use a framework route helper such as createOutboxDrainRoute(...) or createScheduleRoute(...).`,
             });
         }
     }
@@ -630,7 +1860,7 @@ async function inspectServerlessFootguns(targetDir, files) {
         !(await appHasOutboxDrainEntrypoint(targetDir, files))) {
         diagnostics.push({
             severity: "warning",
-            code: "CK_OUTBOX_DRAIN_MISSING",
+            code: "BEIGNET_OUTBOX_DRAIN_MISSING",
             message: "This app defines an outbox registry but no known drain entrypoint. Add a cron/schedule/job route with createOutboxDrainRoute(...) so durable events and jobs are delivered in serverless deployments.",
         });
     }
@@ -667,21 +1897,27 @@ async function inspectPortProviderDrift(targetDir, files, config, convention) {
         ? await readFile(path.join(targetDir, config.paths.ports), "utf8")
         : "";
     const packageJson = files.includes("package.json")
-        ? JSON.parse(await readFile(path.join(targetDir, "package.json"), "utf8"))
+        ? await readPackageJson(targetDir, files)
         : undefined;
     const installedPackages = new Set([
         ...Object.keys(packageJson?.dependencies ?? {}),
         ...Object.keys(packageJson?.devDependencies ?? {}),
         ...Object.keys(packageJson?.peerDependencies ?? {}),
     ]);
-    for (const expected of canonicalProviderPorts) {
+    const providerDoctorRules = await providerDoctorRulesForInstalledPackages(targetDir, packageJson);
+    const providerPortRequirements = providerDoctorRules.flatMap((provider) => (provider.appPorts ?? []).map((port) => ({
+        packageName: provider.packageName,
+        portName: port.name,
+        portType: port.type,
+    })));
+    for (const expected of providerPortRequirements) {
         if (!installedPackages.has(expected.packageName))
             continue;
         if (portsSource.includes(`${expected.portName}:`))
             continue;
         diagnostics.push({
             severity: "warning",
-            code: "CK_PROVIDER_PORT_MISSING",
+            code: "BEIGNET_PROVIDER_PORT_MISSING",
             file: config.paths.ports,
             message: `${expected.packageName} is installed, but AppPorts does not declare ${expected.portName}: ${expected.portType}. Add the canonical port to AppPorts or remove the unused provider package.`,
         });
@@ -703,7 +1939,7 @@ async function inspectPortProviderDrift(targetDir, files, config, convention) {
             continue;
         diagnostics.push({
             severity: "warning",
-            code: "CK_PORT_TEST_FAKE_MISSING",
+            code: "BEIGNET_PORT_TEST_FAKE_MISSING",
             file,
             message: `${file} looks like a generated port, but it does not export ${fakeFactory}(). Re-run make port with --force or add a small fake adapter so use-case tests can stay vendor-free.`,
         });
@@ -721,6 +1957,111 @@ async function inspectDatabaseLifecycleDrift(targetDir, files, config, conventio
     const repositoriesSource = files.includes(repositoriesPath)
         ? await readFile(path.join(targetDir, repositoriesPath), "utf8")
         : "";
+    const packageScripts = await readPackageScripts(targetDir, files);
+    const schemaDir = `${infrastructurePath}/db/schema`;
+    const schemaIndexFile = `${schemaDir}/index.ts`;
+    const schemaFiles = files.filter((file) => file.startsWith(`${schemaDir}/`) &&
+        file.endsWith(".ts") &&
+        file !== schemaIndexFile);
+    const hasDrizzleArtifacts = hasDrizzleConfig(files) ||
+        files.includes(repositoriesPath) ||
+        files.includes(schemaIndexFile) ||
+        schemaFiles.length > 0 ||
+        files.some((file) => file.startsWith(`${infrastructurePath}/`) &&
+            file.endsWith("-repository.ts") &&
+            file.includes("/drizzle-"));
+    if (hasDrizzleArtifacts &&
+        !hasDrizzleConfig(files) &&
+        hasDrizzleLifecycleScriptNeedingRootConfig(packageScripts)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_DRIZZLE_CONFIG_MISSING",
+            file: "drizzle.config.ts",
+            message: "This app has Drizzle database artifacts, but no drizzle.config.ts, drizzle.config.mts, drizzle.config.js, or drizzle.config.mjs exists at the app root. Add a Drizzle config so beignet db generate and beignet db migrate can run.",
+        });
+    }
+    if (hasDrizzleArtifacts) {
+        for (const script of ["db:generate", "db:migrate"]) {
+            if (packageScripts[script])
+                continue;
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_DB_SCRIPT_MISSING",
+                file: "package.json",
+                message: `This app has Drizzle database artifacts, but package.json does not define "${script}". Add an app-owned ${script} script so beignet db ${script.replace("db:", "")} can run the database lifecycle command.`,
+            });
+        }
+    }
+    const schemaFilePath = `${infrastructurePath}/db/schema.ts`;
+    if (files.includes(schemaFilePath)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_DB_SCHEMA_FILE_FORM",
+            file: schemaFilePath,
+            message: `${schemaFilePath} keeps the Drizzle schema in a single file. Move it to ${schemaIndexFile} so feature tables can live in separate modules under ${schemaDir}/.`,
+        });
+    }
+    if (schemaFiles.length > 0 && !files.includes(schemaIndexFile)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_DB_SCHEMA_INDEX_MISSING",
+            file: schemaIndexFile,
+            message: `${schemaDir} contains table schema files, but ${schemaIndexFile} is missing. Add the schema index so Drizzle config and generated repositories can import one schema module.`,
+        });
+    }
+    else if (schemaFiles.length > 0) {
+        const schemaIndexSource = await readFile(path.join(targetDir, schemaIndexFile), "utf8");
+        for (const schemaFile of schemaFiles) {
+            const moduleName = path.basename(schemaFile, ".ts");
+            if (schemaIndexSource.includes(`"./${moduleName}"`))
+                continue;
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_DB_SCHEMA_EXPORT_MISSING",
+                file: schemaIndexFile,
+                message: `${schemaFile} is not exported from ${schemaIndexFile}. Export it so Drizzle config, migrations, and repository factories see the same schema module.`,
+            });
+        }
+    }
+    const standardEntrypoints = [
+        {
+            script: "db:seed",
+            command: "seed",
+            file: `${infrastructurePath}/db/seed.ts`,
+            code: "BEIGNET_DB_SEED_ENTRYPOINT_MISSING",
+        },
+        {
+            script: "db:reset",
+            command: "reset",
+            file: `${infrastructurePath}/db/reset.ts`,
+            code: "BEIGNET_DB_RESET_ENTRYPOINT_MISSING",
+        },
+    ];
+    for (const entrypoint of standardEntrypoints) {
+        const script = packageScripts[entrypoint.script];
+        if (!script?.includes(entrypoint.file) || files.includes(entrypoint.file)) {
+            continue;
+        }
+        diagnostics.push({
+            severity: "warning",
+            code: entrypoint.code,
+            file: entrypoint.file,
+            message: `package.json script "${entrypoint.script}" runs ${entrypoint.file}, but that file is missing. Restore ${entrypoint.file} or update the script before running beignet db ${entrypoint.command}.`,
+        });
+    }
+    const resetEntrypoint = `${infrastructurePath}/db/reset.ts`;
+    if (packageScripts["db:reset"]?.includes(resetEntrypoint) &&
+        files.includes(resetEntrypoint)) {
+        const resetSource = await readFile(path.join(targetDir, resetEntrypoint), "utf8");
+        if (!resetSource.includes("BEIGNET_ALLOW_DATABASE_RESET")) {
+            diagnostics.push({
+                severity: "warning",
+                code: "BEIGNET_DB_RESET_GUARD_MISSING",
+                file: resetEntrypoint,
+                message: "The standard database reset entrypoint does not mention BEIGNET_ALLOW_DATABASE_RESET. Keep destructive reset behavior guarded so non-local databases are not reset accidentally.",
+            });
+        }
+    }
     for (const resource of resources) {
         const singular = singularize(resource);
         const pascal = pascalCase(singular);
@@ -732,7 +2073,7 @@ async function inspectDatabaseLifecycleDrift(targetDir, files, config, conventio
         if (files.includes(portFile) && !hasRepositoryAdapter) {
             diagnostics.push({
                 severity: "warning",
-                code: "CK_REPOSITORY_ADAPTER_MISSING",
+                code: "BEIGNET_REPOSITORY_ADAPTER_MISSING",
                 file: portFile,
                 message: `${portFile} declares a repository port, but ${infrastructureDir} does not contain a repository adapter. Add an infra adapter such as drizzle-${singular}-repository.ts and wire it through app ports.`,
             });
@@ -744,7 +2085,7 @@ async function inspectDatabaseLifecycleDrift(targetDir, files, config, conventio
                     !new RegExp(`\\b${pluralCamel}\\s*:`).test(repositoriesSource))) {
                 diagnostics.push({
                     severity: "warning",
-                    code: "CK_DRIZZLE_REPOSITORY_UNWIRED",
+                    code: "BEIGNET_DRIZZLE_REPOSITORY_UNWIRED",
                     file: repositoriesPath,
                     message: `${drizzleRepositoryAdapter} exists, but ${repositoriesPath} does not appear to import and return ${factoryName}(db). Wire the repository through createRepositories(...) so normal and transaction-scoped ports stay aligned.`,
                 });
@@ -755,7 +2096,7 @@ async function inspectDatabaseLifecycleDrift(targetDir, files, config, conventio
             !hasFeatureFactories(files, featuresPath, resource)) {
             diagnostics.push({
                 severity: "warning",
-                code: "CK_FACTORY_MISSING",
+                code: "BEIGNET_FACTORY_MISSING",
                 file: `${featuresPath}/${resource}/seeds/`,
                 message: `${resource} defines feature seeds but no feature factory. Add a factory under ${featuresPath}/${resource}/tests/factories/ so seeds and tests share the same app-owned data setup path.`,
             });
@@ -765,7 +2106,7 @@ async function inspectDatabaseLifecycleDrift(targetDir, files, config, conventio
         !(await packageScriptExists(targetDir, files, "db:seed"))) {
         diagnostics.push({
             severity: "warning",
-            code: "CK_DB_SEED_SCRIPT_MISSING",
+            code: "BEIGNET_DB_SEED_SCRIPT_MISSING",
             file: "package.json",
             message: 'This app defines feature seeds, but package.json does not define "db:seed". Add an app-owned db:seed script so beignet db seed can run the seed entrypoint.',
         });
@@ -798,53 +2139,34 @@ function hasFeatureFactories(files, featuresPath, resource) {
             !file.endsWith("/index.ts")));
 }
 async function packageScriptExists(targetDir, files, script) {
+    const scripts = await readPackageScripts(targetDir, files);
+    return Boolean(scripts[script]);
+}
+async function readPackageScripts(targetDir, files) {
     if (!files.includes("package.json"))
-        return false;
+        return {};
     const packageJson = JSON.parse(await readFile(path.join(targetDir, "package.json"), "utf8"));
-    return Boolean(packageJson.scripts?.[script]);
-}
-const canonicalProviderPorts = [
-    {
-        packageName: "@beignet/provider-auth-better-auth",
-        portName: "auth",
-        portType: "AuthPort",
-    },
-    {
-        packageName: "@beignet/provider-event-bus-memory",
-        portName: "eventBus",
-        portType: "EventBusPort",
-    },
-    {
-        packageName: "@beignet/provider-inngest",
-        portName: "jobs",
-        portType: "JobDispatcherPort",
-    },
-    {
-        packageName: "@beignet/provider-logger-pino",
-        portName: "logger",
-        portType: "LoggerPort",
-    },
-    {
-        packageName: "@beignet/provider-mail-resend",
-        portName: "mailer",
-        portType: "MailerPort",
-    },
-    {
-        packageName: "@beignet/provider-mail-smtp",
-        portName: "mailer",
-        portType: "MailerPort",
-    },
-    {
-        packageName: "@beignet/provider-rate-limit-upstash",
-        portName: "rateLimit",
-        portType: "RateLimitPort",
-    },
-    {
-        packageName: "@beignet/provider-redis",
-        portName: "cache",
-        portType: "CachePort",
-    },
-];
+    return packageJson.scripts ?? {};
+}
+function hasDrizzleConfig(files) {
+    return [
+        "drizzle.config.ts",
+        "drizzle.config.mts",
+        "drizzle.config.js",
+        "drizzle.config.mjs",
+    ].some((file) => files.includes(file));
+}
+function hasDrizzleLifecycleScriptNeedingRootConfig(scripts) {
+    const lifecycleScripts = ["db:generate", "db:migrate"]
+        .map((script) => scripts[script])
+        .filter((script) => Boolean(script));
+    if (lifecycleScripts.length === 0)
+        return true;
+    return lifecycleScripts.some((script) => /\bdrizzle-kit\b/.test(script) && !hasExplicitDrizzleConfigFlag(script));
+}
+function hasExplicitDrizzleConfigFlag(script) {
+    return /(?:^|\s)--config(?:=|\s)/.test(script);
+}
 async function inspectPackageScripts(targetDir, files, convention) {
     if (!convention.resourceGenerator || !files.includes("package.json")) {
         return [];
@@ -855,7 +2177,7 @@ async function inspectPackageScripts(targetDir, files, convention) {
     return [
         {
             severity: "warning",
-            code: "CK_PACKAGE_TEST_SCRIPT_MISSING",
+            code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
             file: "package.json",
             message: 'package.json does not define a test script. Add "test": "bun test" or run beignet doctor --fix.',
         },
@@ -877,7 +2199,7 @@ async function fixMissingTestScript(targetDir, files, convention) {
         return undefined;
     await writeFile(filePath, next);
     return {
-        code: "CK_PACKAGE_TEST_SCRIPT_MISSING",
+        code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
         file: "package.json",
         message: 'Added "test": "bun test".',
     };
@@ -886,7 +2208,7 @@ function unmatchedRouteDiagnostic(routeHandler) {
     if (routeHandler.source === "next-route") {
         return {
             severity: "error",
-            code: "CK_ROUTE_HANDLER_ORPHANED",
+            code: "BEIGNET_ROUTE_HANDLER_ORPHANED",
             file: routeHandler.handlerFile,
             message: `${routeHandler.handlerFile} exports ${routeHandler.method} = server.api, but no known contract matches ${routeHandler.method} ${routeHandler.contractRef}. Add the matching contract, update the route file path, or remove the handler export.`,
         };
@@ -896,7 +2218,7 @@ function unmatchedRouteDiagnostic(routeHandler) {
         : routeHandler.contractRef;
     return {
         severity: "error",
-        code: "CK_ROUTE_HANDLER_UNKNOWN_CONTRACT",
+        code: "BEIGNET_ROUTE_HANDLER_UNKNOWN_CONTRACT",
         file: routeHandler.handlerFile,
         contract: routeHandler.contractRef,
         message: `${routeHandler.handlerFile} references ${contractLabel}, but that contract was not found under the configured contracts path. Fix the import/export or remove the route handler.`,
@@ -919,7 +2241,7 @@ function dedupeDiagnostics(diagnostics) {
     }
     return deduped;
 }
-async function inspectOpenApiDrift(targetDir, files, config, contracts) {
+async function inspectOpenApiDrift(targetDir, files, config, convention, contracts, matchedRoutes) {
     const routePath = path.join(targetDir, config.paths.openapiRoute);
     try {
         await stat(routePath);
@@ -928,19 +2250,52 @@ async function inspectOpenApiDrift(targetDir, files, config, contracts) {
         return [];
     }
     const source = await readFile(routePath, "utf8");
+    const routeSurface = await routeSurfaceContracts(targetDir, files, config, convention, contracts, matchedRoutes);
     const listedContracts = await openApiContracts(targetDir, files, config, source);
     if (!listedContracts) {
         return [];
     }
-    return contracts
-        .filter((contract) => !listedContracts.has(contract.exportName))
-        .map((contract) => ({
-        severity: "warning",
-        code: "CK_OPENAPI_MISSING",
-        file: config.paths.openapiRoute,
-        contract: contract.exportName,
-        message: `${contract.exportName} (${contract.method} ${contract.path}) is not listed in createOpenAPIHandler. Add it to the OpenAPI contract array/list or remove the contract from the documented API surface.`,
-    }));
+    const contractByName = new Map(contracts.map((contract) => [contract.exportName, contract]));
+    const routeSurfaceNames = new Set(routeSurface.map((contract) => contract.exportName));
+    return [
+        ...routeSurface
+            .filter((contract) => !listedContracts.has(contract.exportName))
+            .map((contract) => ({
+            severity: "warning",
+            code: "BEIGNET_OPENAPI_MISSING",
+            file: config.paths.openapiRoute,
+            contract: contract.exportName,
+            message: `${contract.exportName} (${contract.method} ${contract.path}) is not listed in createOpenAPIHandler. Add it to the OpenAPI contract array/list or remove the contract from the documented API surface.`,
+        })),
+        ...[...listedContracts]
+            .filter((contractName) => !routeSurfaceNames.has(contractName))
+            .flatMap((contractName) => {
+            const contract = contractByName.get(contractName);
+            if (!contract)
+                return [];
+            return [
+                {
+                    severity: "warning",
+                    code: "BEIGNET_OPENAPI_UNROUTED",
+                    file: config.paths.openapiRoute,
+                    contract: contract.exportName,
+                    message: `${contract.exportName} (${contract.method} ${contract.path}) is listed in createOpenAPIHandler, but it is not part of the registered route surface. Register the feature route group or remove the contract from OpenAPI.`,
+                },
+            ];
+        }),
+    ];
+}
+async function routeSurfaceContracts(targetDir, files, config, convention, contracts, matchedRoutes) {
+    if (convention.resourceGenerator && files.includes(config.paths.server)) {
+        const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
+        const serverSource = await readFile(path.join(targetDir, config.paths.server), "utf8");
+        const registeredGroups = await registeredRouteGroupsForServer(targetDir, files, config, serverSource);
+        const routeGroupContracts = contractsForRegisteredRouteGroups(contracts, routeGroups, registeredGroups);
+        if (routeGroups.length > 0) {
+            return routeGroupContracts;
+        }
+    }
+    return matchedRoutes.routes.filter((route) => route.handlerSource !== "missing");
 }
 async function inspectFeatureRouteRegistration(targetDir, files, config, convention, contracts) {
     if (!convention.resourceGenerator)
@@ -953,6 +2308,34 @@ async function inspectFeatureRouteRegistration(targetDir, files, config, convent
     const serverSource = await readFile(path.join(targetDir, config.paths.server), "utf8");
     const registeredGroups = await registeredRouteGroupsForServer(targetDir, files, config, serverSource);
     const diagnostics = [];
+    const featuresPath = directoryPath(config.paths.features);
+    for (const contract of contracts) {
+        const feature = featureNameFromContractFile(contract.file, config);
+        if (!feature)
+            continue;
+        const routeFile = `${featuresPath}/${feature}/routes.ts`;
+        const featureRouteGroups = routeGroups.filter((routeGroup) => routeGroup.file === routeFile);
+        if (featureRouteGroups.length === 0) {
+            diagnostics.push({
+                severity: "error",
+                code: "BEIGNET_FEATURE_ROUTE_GROUP_MISSING",
+                file: contract.file,
+                contract: contract.exportName,
+                message: `${contract.exportName} (${contract.method} ${contract.path}) is declared in ${contract.file}, but ${routeFile} is missing. Add a feature route group that maps the contract to a use case, or remove the unused contract.`,
+            });
+            continue;
+        }
+        const routeGroupHasContract = featureRouteGroups.some((routeGroup) => routeGroup.contracts.some((routeGroupContract) => findRouteGroupContract([contract], routeGroupContract) !== undefined));
+        if (routeGroupHasContract)
+            continue;
+        diagnostics.push({
+            severity: "error",
+            code: "BEIGNET_ROUTE_GROUP_CONTRACT_MISSING",
+            file: routeFile,
+            contract: contract.exportName,
+            message: `${contract.exportName} (${contract.method} ${contract.path}) is declared in ${contract.file}, but no route in ${routeFile} references it. Add the contract to the feature route group or remove the unused contract.`,
+        });
+    }
     for (const routeGroup of routeGroups) {
         if (registeredGroups.has(routeGroup.name))
             continue;
@@ -960,7 +2343,7 @@ async function inspectFeatureRouteRegistration(targetDir, files, config, convent
             const contract = findRouteGroupContract(contracts, routeGroupContract);
             diagnostics.push({
                 severity: "error",
-                code: "CK_ROUTE_GROUP_UNREGISTERED",
+                code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
                 file: config.paths.server,
                 contract: routeGroupContract.exportName,
                 message: contract
@@ -971,6 +2354,25 @@ async function inspectFeatureRouteRegistration(targetDir, files, config, convent
     }
     return diagnostics;
 }
+function contractsForRegisteredRouteGroups(contracts, routeGroups, registeredGroups) {
+    const seen = new Set();
+    const registeredContracts = [];
+    for (const routeGroup of routeGroups) {
+        if (!registeredGroups.has(routeGroup.name))
+            continue;
+        for (const routeGroupContract of routeGroup.contracts) {
+            const contract = findRouteGroupContract(contracts, routeGroupContract);
+            if (!contract)
+                continue;
+            const key = contractKey(contract);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            registeredContracts.push(contract);
+        }
+    }
+    return registeredContracts.sort(compareContracts);
+}
 async function readFeatureRouteGroups(targetDir, files, config) {
     const featuresPath = `${directoryPath(config.paths.features)}/`;
     const routeFiles = files.filter((file) => file.startsWith(featuresPath) && file.endsWith("/routes.ts"));
@@ -984,9 +2386,13 @@ async function readFeatureRouteGroups(targetDir, files, config) {
 }
 function parseFeatureRouteGroups(source, file, imports) {
     const routeGroups = [];
-    const exportRegex = /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=\s*defineRouteGroup(?:<[^>]+>)?\(\s*(?:\)\s*\(\s*)?(?:\{[\s\S]*?routes:\s*)?\[([\s\S]*?)\]\s*(?:,?\s*\})?\s*\)\s*;?/g;
+    const exportRegex = /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=\s*defineRouteGroup(?:<[^>]+>)?\(/g;
     for (const match of source.matchAll(exportRegex)) {
-        const contracts = [...match[2].matchAll(/contract:\s*([^,\n}]+)/g)]
+        const callStart = (match.index ?? 0) + match[0].length;
+        const routesBody = routeGroupRoutesArrayBody(source, callStart);
+        if (routesBody === undefined)
+            continue;
+        const contracts = [...routesBody.matchAll(/contract:\s*([^,\n}]+)/g)]
             .map((contractMatch) => routeGroupContractRef(contractMatch[1].trim(), imports))
             .filter((contract) => Boolean(contract));
         routeGroups.push({
@@ -997,6 +2403,67 @@ function parseFeatureRouteGroups(source, file, imports) {
     }
     return routeGroups;
 }
+/**
+ * Extract the body of the `routes: [...]` array for a route group call.
+ *
+ * Both binder routes (`{ contract, useCase }`) and full handler routes
+ * (`{ contract, handle }`) can contain nested brackets, strings, and arrow
+ * functions, so the array is scanned with balanced-bracket tracking instead
+ * of a regular expression.
+ */
+function routeGroupRoutesArrayBody(source, callStart) {
+    const objectStart = source.indexOf("{", callStart);
+    if (objectStart === -1)
+        return undefined;
+    const groupObject = balancedObjectSource(source, objectStart);
+    if (!groupObject)
+        return undefined;
+    const routesIndex = groupObject.indexOf("routes:");
+    if (routesIndex === -1)
+        return undefined;
+    const arrayStart = groupObject.indexOf("[", routesIndex);
+    if (arrayStart === -1)
+        return undefined;
+    const arraySource = balancedArraySource(groupObject, arrayStart);
+    return arraySource?.slice(1, -1);
+}
+function balancedArraySource(source, startIndex) {
+    if (source[startIndex] !== "[")
+        return undefined;
+    let depth = 0;
+    let quote;
+    let escaped = false;
+    for (let index = startIndex; index < source.length; index += 1) {
+        const char = source[index];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'" || char === "`") {
+            quote = char;
+            continue;
+        }
+        if (char === "[") {
+            depth += 1;
+            continue;
+        }
+        if (char === "]") {
+            depth -= 1;
+            if (depth === 0)
+                return source.slice(startIndex, index + 1);
+        }
+    }
+    return undefined;
+}
 function routeGroupContractRef(expression, imports) {
     const namedMatch = /^([A-Za-z_$][\w$]*)$/.exec(expression);
     if (namedMatch) {
@@ -1060,7 +2527,7 @@ function findRouteGroupContract(contracts, routeGroupContract) {
             contract.file ===
                 routeGroupContract.file.replace(/\.ts$/, "/index.ts")));
 }
-async function fixDirectOpenApiArrayDrift(targetDir, config, contracts) {
+async function fixDirectOpenApiArrayDrift(targetDir, files, config, convention, contracts, matchedRoutes) {
     const routePath = path.join(targetDir, config.paths.openapiRoute);
     let source;
     try {
@@ -1072,8 +2539,9 @@ async function fixDirectOpenApiArrayDrift(targetDir, config, contracts) {
     const firstArg = firstCreateOpenAPIHandlerArgInfo(source);
     if (!firstArg?.text.startsWith("["))
         return undefined;
+    const routeSurface = await routeSurfaceContracts(targetDir, files, config, convention, contracts, matchedRoutes);
     const listedContracts = contractsFromArrayExpression(firstArg.text);
-    const missingContracts = contracts.filter((contract) => !listedContracts.has(contract.exportName));
+    const missingContracts = routeSurface.filter((contract) => !listedContracts.has(contract.exportName));
     if (missingContracts.length === 0)
         return undefined;
     if (missingContracts.some((contract) => !hasImportedIdentifier(source, contract.exportName))) {
@@ -1085,13 +2553,77 @@ async function fixDirectOpenApiArrayDrift(targetDir, config, contracts) {
         return undefined;
     await writeFile(routePath, next);
     return {
-        code: "CK_OPENAPI_MISSING",
+        code: "BEIGNET_OPENAPI_MISSING",
         file: config.paths.openapiRoute,
         message: `Added ${missingContracts
             .map((contract) => contract.exportName)
             .join(", ")} to the direct createOpenAPIHandler contract array.`,
     };
 }
+async function fixUnregisteredRouteGroups(targetDir, files, config) {
+    if (!files.includes(config.paths.server))
+        return undefined;
+    const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
+    if (routeGroups.length === 0)
+        return undefined;
+    const serverSource = await readFile(path.join(targetDir, config.paths.server), "utf8");
+    const registeredGroups = await registeredRouteGroupsForServer(targetDir, files, config, serverSource);
+    const missingGroups = routeGroups
+        .filter((routeGroup) => !registeredGroups.has(routeGroup.name))
+        .sort((left, right) => left.file.localeCompare(right.file));
+    if (missingGroups.length === 0)
+        return undefined;
+    const targetFile = routeRegistryFileFromServerSource(serverSource, config.paths.server, files) ?? config.paths.server;
+    if (!files.includes(targetFile))
+        return undefined;
+    const targetPath = path.join(targetDir, targetFile);
+    const original = await readFile(targetPath, "utf8");
+    const firstArg = firstDefineRoutesArgInfo(original);
+    if (!firstArg?.text.startsWith("["))
+        return undefined;
+    const registeredInTarget = contractsFromArrayExpression(firstArg.text);
+    const groupsToAppend = missingGroups.filter((routeGroup) => !registeredInTarget.has(routeGroup.name));
+    if (groupsToAppend.length === 0)
+        return undefined;
+    let next = original;
+    for (const routeGroup of groupsToAppend) {
+        const imported = parseNamedImportSources(next).get(routeGroup.name);
+        if (imported) {
+            const importedFile = sourceFileFromImport(imported.sourcePath, targetFile, files);
+            if (importedFile !== routeGroup.file)
+                return undefined;
+            continue;
+        }
+        next = insertAfterImports(next, `import { ${routeGroup.name} } from "${relativeModule(targetFile, routeGroup.file)}";`);
+    }
+    const nextFirstArg = firstDefineRoutesArgInfo(next);
+    if (!nextFirstArg?.text.startsWith("["))
+        return undefined;
+    const nextArray = appendToArrayExpression(nextFirstArg.text, groupsToAppend.map((routeGroup) => routeGroup.name));
+    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.`,
+    };
+}
+function routeRegistryFileFromServerSource(source, serverFile, files) {
+    const imports = parseNamedImportSources(source);
+    for (const identifier of routeOptionIdentifiers(source)) {
+        const imported = imports.get(identifier);
+        if (!imported)
+            continue;
+        const importedFile = sourceFileFromImport(imported.sourcePath, serverFile, files);
+        if (importedFile && files.includes(importedFile))
+            return importedFile;
+    }
+    return undefined;
+}
 async function openApiContracts(targetDir, files, config, source) {
     const firstArg = firstCreateOpenAPIHandlerArg(source);
     if (!firstArg)
@@ -1102,22 +2634,75 @@ async function openApiContracts(targetDir, files, config, source) {
     const identifier = /^([A-Za-z_$][\w$]*)$/.exec(firstArg)?.[1];
     if (!identifier)
         return undefined;
+    const routeContracts = await contractsFromRoutesExport(targetDir, files, config, config.paths.openapiRoute, source, identifier);
+    if (routeContracts)
+        return routeContracts;
     const imports = parseNamedImports(source, config);
     const imported = imports.get(identifier);
     const listFile = imported?.contractFile ?? config.paths.openapiRoute;
     return resolveContractList(await readContractLists(targetDir, files, config), listFile, imported?.importedName ?? identifier);
 }
+async function contractsFromRoutesExport(targetDir, files, config, importerFile, source, identifier) {
+    const localRouteContracts = await contractsFromRoutesSource(targetDir, files, config, importerFile, source, identifier);
+    if (localRouteContracts)
+        return localRouteContracts;
+    const imports = parseNamedImportSources(source);
+    const imported = imports.get(identifier);
+    if (!imported)
+        return undefined;
+    const importedFile = sourceFileFromImport(imported.sourcePath, importerFile, files);
+    if (!importedFile || !files.includes(importedFile))
+        return undefined;
+    const importedSource = await readFile(path.join(targetDir, importedFile), {
+        encoding: "utf8",
+    });
+    return contractsFromRoutesSource(targetDir, files, config, importedFile, importedSource, imported.importedName);
+}
+async function contractsFromRoutesSource(targetDir, files, config, file, source, exportName) {
+    const routeIdentifier = contractsFromRoutesIdentifier(source, exportName);
+    if (!routeIdentifier)
+        return undefined;
+    const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
+    const registeredGroups = await registeredRouteGroupsForSource(targetDir, files, file, source, routeIdentifier);
+    const registeredContracts = contractsForRegisteredRouteGroups(await readContracts(targetDir, files, config), routeGroups, registeredGroups);
+    return new Set(registeredContracts.map((contract) => contract.exportName));
+}
+function contractsFromRoutesIdentifier(source, exportName) {
+    return new RegExp(`(?:export\\s+)?const\\s+${escapeRegExp(exportName)}\\s*=\\s*contractsFromRoutes(?:<[^>]+>)?\\(\\s*([A-Za-z_$][\\w$]*)\\s*\\)`).exec(source)?.[1];
+}
+async function registeredRouteGroupsForSource(targetDir, files, file, source, routeIdentifier) {
+    if (new RegExp(`(?:export\\s+)?const\\s+${escapeRegExp(routeIdentifier)}\\s*=\\s*defineRoutes`).test(source)) {
+        return registeredRouteGroups(source);
+    }
+    const imports = parseNamedImportSources(source);
+    const imported = imports.get(routeIdentifier);
+    if (!imported)
+        return registeredRouteGroups(source);
+    const importedFile = sourceFileFromImport(imported.sourcePath, file, files);
+    if (!importedFile || !files.includes(importedFile)) {
+        return registeredRouteGroups(source);
+    }
+    return registeredRouteGroups(await readFile(path.join(targetDir, importedFile), "utf8"));
+}
 function firstCreateOpenAPIHandlerArg(source) {
     return firstCreateOpenAPIHandlerArgInfo(source)?.text;
 }
+function firstDefineRoutesArgInfo(source) {
+    const start = /defineRoutes(?:<[^>]+>)?\(/.exec(source);
+    if (!start)
+        return undefined;
+    return firstCallArgInfo(source, start.index + start[0].length);
+}
 function firstCreateOpenAPIHandlerArgInfo(source) {
     const start = source.indexOf("createOpenAPIHandler(");
     if (start === -1)
         return undefined;
+    return firstCallArgInfo(source, start + "createOpenAPIHandler(".length);
+}
+function firstCallArgInfo(source, argStart) {
     let depth = 0;
     let inString;
     let escaped = false;
-    const argStart = start + "createOpenAPIHandler(".length;
     for (let index = argStart; index < source.length; index++) {
         const char = source[index];
         if (inString) {
@@ -1197,6 +2782,20 @@ function appendToArrayExpression(expression, names) {
     }
     return `${trimmedBeforeClosingBracket},\n${itemIndent}${appendedNames}${closingBracketText}`;
 }
+function insertAfterImports(source, line) {
+    const lines = source.split("\n");
+    let lastImportIndex = -1;
+    for (let index = 0; index < lines.length; index++) {
+        if (lines[index].startsWith("import ")) {
+            lastImportIndex = index;
+        }
+    }
+    if (lastImportIndex === -1) {
+        return `${line}\n${source}`;
+    }
+    lines.splice(lastImportIndex + 1, 0, line);
+    return lines.join("\n");
+}
 function hasImportedIdentifier(source, identifier) {
     const importRegex = /import\s+\{([^}]+)\}\s+from\s+["'][^"']+["']/g;
     for (const match of source.matchAll(importRegex)) {
@@ -1208,6 +2807,21 @@ function hasImportedIdentifier(source, identifier) {
     }
     return false;
 }
+function relativeModule(fromFile, toFile) {
+    const fromDir = path.posix.dirname(normalizePath(fromFile));
+    const relative = path.posix.relative(fromDir, normalizePath(toFile));
+    const specifier = modulePath(relative);
+    if (specifier.startsWith("../"))
+        return specifier;
+    if (specifier === "..")
+        return specifier;
+    return specifier.startsWith(".") ? specifier : `./${specifier}`;
+}
+function modulePath(filePath) {
+    return directoryPath(filePath)
+        .replace(/\.(?:[cm]?[jt]sx?)$/, "")
+        .replace(/\/index$/, "");
+}
 async function readContractLists(targetDir, files, config) {
     const lists = new Map();
     const contractFiles = contractListSourceFiles(files, config);
@@ -1312,38 +2926,229 @@ async function inspectResourceSlices(targetDir, files, config, convention, stric
     const diagnostics = [];
     for (const resource of resources) {
         const singular = singularize(resource);
+        const pluralCamel = camelCase(resource);
+        const singularPascal = pascalCase(singular);
         const contractFile = resourceContractFile(resource, config);
         const useCaseDir = resourceUseCaseDir(resource, config);
         const portFile = resourcePortFile(resource, singular, config);
+        const featureRouteFile = path.join(config.paths.features, resource, "routes.ts");
+        const sharedErrorsFile = path.join(config.paths.features, "shared", "errors.ts");
         const infrastructureDir = `${directoryPath(path.dirname(config.paths.infrastructurePorts))}/${resource}/`;
+        const drizzleSchemaFile = path.join(path.dirname(config.paths.infrastructurePorts), "db", "schema", `${resource}.ts`);
+        const drizzleRepositoryFile = path.join(path.dirname(config.paths.infrastructurePorts), resource, `drizzle-${singular}-repository.ts`);
+        const memoryRepositoryFile = path.join(path.dirname(config.paths.infrastructurePorts), resource, `in-memory-${singular}-repository.ts`);
         const routeFile = path.join(config.paths.routes, resource, "route.ts");
         const catchAllRouteFile = path.join(config.paths.routes, "[[...path]]", "route.ts");
         const testFile = resourceTestFile(resource, config);
         if (!hasRequirement(files, contractFile)) {
-            diagnostics.push(resourceDiagnostic("CK_RESOURCE_CONTRACT_MISSING", resource, contractFile));
+            diagnostics.push(resourceDiagnostic("BEIGNET_RESOURCE_CONTRACT_MISSING", resource, contractFile));
         }
         if (!hasRequirement(files, useCaseDir)) {
-            diagnostics.push(resourceDiagnostic("CK_RESOURCE_USE_CASES_MISSING", resource, useCaseDir));
+            diagnostics.push(resourceDiagnostic("BEIGNET_RESOURCE_USE_CASES_MISSING", resource, useCaseDir));
         }
         if (!hasRequirement(files, portFile)) {
-            diagnostics.push(resourceDiagnostic("CK_RESOURCE_PORT_MISSING", resource, portFile));
+            diagnostics.push(resourceDiagnostic("BEIGNET_RESOURCE_PORT_MISSING", resource, portFile));
         }
         if (!hasRequirement(files, infrastructureDir)) {
-            diagnostics.push(resourceDiagnostic("CK_RESOURCE_INFRASTRUCTURE_MISSING", resource, infrastructureDir));
+            diagnostics.push(resourceDiagnostic("BEIGNET_RESOURCE_INFRASTRUCTURE_MISSING", resource, infrastructureDir));
         }
         if (!hasRequirement(files, routeFile) &&
             !hasRequirement(files, catchAllRouteFile)) {
-            diagnostics.push(resourceDiagnostic("CK_RESOURCE_ROUTE_MISSING", resource, routeFile));
+            diagnostics.push(resourceDiagnostic("BEIGNET_RESOURCE_ROUTE_MISSING", resource, routeFile));
         }
         if (strict && !hasRequirement(files, testFile)) {
             diagnostics.push({
-                ...resourceDiagnostic("CK_RESOURCE_TEST_MISSING", resource, testFile),
+                ...resourceDiagnostic("BEIGNET_RESOURCE_TEST_MISSING", resource, testFile),
+                severity: "warning",
+            });
+        }
+        const contractSource = await readSourceIfPresent(targetDir, files, contractFile);
+        const portSource = await readSourceIfPresent(targetDir, files, portFile);
+        const routeSource = await readSourceIfPresent(targetDir, files, featureRouteFile);
+        const testSource = await readSourceIfPresent(targetDir, files, testFile);
+        const drizzleSchemaSource = await readSourceIfPresent(targetDir, files, drizzleSchemaFile);
+        const drizzleRepositorySource = await readSourceIfPresent(targetDir, files, drizzleRepositoryFile);
+        const memoryRepositorySource = await readSourceIfPresent(targetDir, files, memoryRepositoryFile);
+        const sharedErrorsSource = await readSourceIfPresent(targetDir, files, sharedErrorsFile);
+        const crudUseCaseFiles = [
+            path.join(useCaseDir, `get-${singular}.ts`),
+            path.join(useCaseDir, `update-${singular}.ts`),
+            path.join(useCaseDir, `delete-${singular}.ts`),
+        ];
+        const hasCrudSignals = crudUseCaseFiles.slice(1).some((file) => files.includes(file)) ||
+            sourceIncludesAny(contractSource, [
+                `export const update${singularPascal}`,
+                `export const delete${singularPascal}`,
+            ]) ||
+            sourceIncludesAny(portSource, [
+                `update(input: Update${singularPascal}Input)`,
+                `update(input: Update${singularPascal}RepositoryInput)`,
+                "delete(id: string): Promise<boolean>",
+            ]);
+        if (!hasCrudSignals)
+            continue;
+        for (const exportName of [
+            `get${singularPascal}`,
+            `update${singularPascal}`,
+            `delete${singularPascal}`,
+        ]) {
+            if (contractSource?.includes(`export const ${exportName}`))
+                continue;
+            diagnostics.push({
+                severity: "error",
+                code: "BEIGNET_RESOURCE_CONTRACT_EXPORT_MISSING",
+                file: contractFile,
+                contract: exportName,
+                message: `${resource} appears to be a CRUD resource, but ${contractFile} does not export ${exportName}. Restore the generated ${exportName} contract or remove the partial CRUD wiring.`,
+            });
+        }
+        for (const file of crudUseCaseFiles) {
+            if (files.includes(file))
+                continue;
+            diagnostics.push({
+                severity: "error",
+                code: "BEIGNET_RESOURCE_CRUD_USE_CASE_MISSING",
+                file,
+                message: `${resource} appears to be a CRUD resource, but ${file} is missing. Restore the generated CRUD use case or remove the partial CRUD wiring.`,
+            });
+        }
+        const expectedRepositoryMethods = [
+            {
+                display: `findById(id: string): Promise<${singularPascal} | null>`,
+                alternatives: [
+                    `findById(id: string): Promise<${singularPascal} | null>`,
+                    `findById(id: string, filter: ${singularPascal}TenantFilter): Promise<${singularPascal} | null>`,
+                ],
+            },
+            {
+                display: `update(input: Update${singularPascal}Input)`,
+                alternatives: [
+                    `update(input: Update${singularPascal}Input)`,
+                    `update(input: Update${singularPascal}RepositoryInput)`,
+                ],
+            },
+            {
+                display: "delete(id: string): Promise<boolean>",
+                alternatives: [
+                    "delete(id: string): Promise<boolean>",
+                    `delete(id: string, filter: ${singularPascal}TenantFilter): Promise<boolean>`,
+                ],
+            },
+        ];
+        for (const method of expectedRepositoryMethods) {
+            if (sourceIncludesAny(portSource, method.alternatives))
+                continue;
+            diagnostics.push({
+                severity: "error",
+                code: "BEIGNET_RESOURCE_REPOSITORY_METHOD_MISSING",
+                file: portFile,
+                message: `${resource} appears to be a CRUD resource, but ${portFile} does not declare ${method.display}. Restore the generated repository method or remove the partial CRUD wiring.`,
+            });
+        }
+        for (const exportName of [
+            `get${singularPascal}`,
+            `update${singularPascal}`,
+            `delete${singularPascal}`,
+        ]) {
+            if (routeSource?.includes(`contract: ${exportName}`))
+                continue;
+            diagnostics.push({
+                severity: "error",
+                code: "BEIGNET_RESOURCE_ROUTE_CONTRACT_MISSING",
+                file: featureRouteFile,
+                contract: exportName,
+                message: `${resource} appears to be a CRUD resource, but ${featureRouteFile} does not route ${exportName}. Add the contract to the feature route group or remove the partial CRUD wiring.`,
+            });
+        }
+        const notFoundError = `${singularPascal}NotFound`;
+        const conflictError = `${singularPascal}Conflict`;
+        if (!sharedErrorsSource?.includes(notFoundError)) {
+            diagnostics.push({
+                severity: "error",
+                code: "BEIGNET_RESOURCE_ERROR_CATALOG_MISSING",
+                file: sharedErrorsFile,
+                message: `${resource} appears to be a CRUD resource, but ${sharedErrorsFile} does not declare ${notFoundError}. Add the generated not-found catalog error or remove the partial CRUD wiring.`,
+            });
+        }
+        if (!sharedErrorsSource?.includes(conflictError)) {
+            diagnostics.push({
+                severity: "error",
+                code: "BEIGNET_RESOURCE_ERROR_CATALOG_MISSING",
+                file: sharedErrorsFile,
+                message: `${resource} appears to be a CRUD resource, but ${sharedErrorsFile} does not declare ${conflictError}. Add the generated conflict catalog error or remove the partial CRUD wiring.`,
+            });
+        }
+        if (strict &&
+            testSource &&
+            !sourceIncludesAll(testSource, [
+                `get${singularPascal}`,
+                `update${singularPascal}`,
+                `delete${singularPascal}`,
+                `${notFoundError}`,
+                `${conflictError}`,
+            ])) {
+            diagnostics.push({
                 severity: "warning",
+                code: "BEIGNET_RESOURCE_CRUD_TEST_COVERAGE_MISSING",
+                file: testFile,
+                message: `${resource} appears to be a CRUD resource, but ${testFile} does not exercise get, update, delete, ${notFoundError}, and ${conflictError}. Expand the generated resource test or remove the partial CRUD wiring.`,
             });
         }
+        const hasDrizzleSoftDeleteSignals = sourceIncludesAny(drizzleSchemaSource, ["deletedAt", "deleted_at"]) ||
+            sourceIncludesAny(drizzleRepositorySource, ["deletedAt", "isNull"]);
+        const hasSoftDeleteSignals = hasDrizzleSoftDeleteSignals ||
+            sourceIncludesAny(memoryRepositorySource, ["deletedAt"]);
+        if (hasSoftDeleteSignals) {
+            if (hasDrizzleSoftDeleteSignals) {
+                if (!sourceIncludesAny(drizzleSchemaSource, ["deletedAt", "deleted_at"])) {
+                    diagnostics.push({
+                        severity: "error",
+                        code: "BEIGNET_RESOURCE_SOFT_DELETE_SCHEMA_MISSING",
+                        file: drizzleSchemaFile,
+                        message: `${resource} appears to use soft delete, but ${drizzleSchemaFile} does not declare deletedAt. Restore the generated deletedAt column or remove the partial soft-delete wiring.`,
+                    });
+                }
+                if (!sourceIncludesAll(drizzleRepositorySource ?? "", [
+                    "isNull",
+                    "deletedAt",
+                    `.update(schema.${pluralCamel})`,
+                ])) {
+                    diagnostics.push({
+                        severity: "error",
+                        code: "BEIGNET_RESOURCE_SOFT_DELETE_REPOSITORY_DRIFT",
+                        file: drizzleRepositoryFile,
+                        message: `${resource} appears to use soft delete, but ${drizzleRepositoryFile} does not consistently filter active rows and archive deletes. Restore the generated soft-delete repository behavior or remove the partial soft-delete wiring.`,
+                    });
+                }
+            }
+            if (strict &&
+                testSource &&
+                !sourceIncludesAll(testSource, [
+                    "afterDelete",
+                    "listedAfterDeleteViaRoute",
+                ])) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "BEIGNET_RESOURCE_SOFT_DELETE_TEST_COVERAGE_MISSING",
+                    file: testFile,
+                    message: `${resource} appears to use soft delete, but ${testFile} does not assert that deleted records disappear from reads. Expand the generated resource test or remove the partial soft-delete wiring.`,
+                });
+            }
+        }
     }
     return diagnostics;
 }
+async function readSourceIfPresent(targetDir, files, file) {
+    if (!files.includes(file))
+        return undefined;
+    return readFile(path.join(targetDir, file), "utf8");
+}
+function sourceIncludesAny(source, snippets) {
+    return source ? snippets.some((snippet) => source.includes(snippet)) : false;
+}
+function sourceIncludesAll(source, snippets) {
+    return snippets.every((snippet) => source.includes(snippet));
+}
 async function collectResourceNames(targetDir, files, config) {
     const resources = new Set();
     const portsPath = directoryPath(path.dirname(config.paths.ports));
@@ -1380,11 +3185,13 @@ async function isGeneratedResourcePort(targetDir, file, resource) {
     const singular = singularize(resource);
     const singularPascal = pascalCase(singular);
     const pluralPascal = pascalCase(resource);
+    const hasCursorList = source.includes("CursorPage") &&
+        source.includes(`list(query: List${pluralPascal}Query)`);
+    const hasOffsetList = source.includes("OffsetPage") && source.includes("list(page: OffsetPage)");
     return (source.includes(`Create${singularPascal}Input`) &&
         source.includes(`List${pluralPascal}Result`) &&
-        source.includes("OffsetPage") &&
+        (hasCursorList || hasOffsetList) &&
         source.includes(`interface ${singularPascal}Repository`) &&
-        source.includes("list(page: OffsetPage)") &&
         source.includes(`create(input: Create${singularPascal}Input)`));
 }
 async function isGeneratedInfrastructureRepository(targetDir, file, resource) {