@zauso-ai/capstan-core 0.1.2

package/dist/verify.js

@@ -0,0 +1,837 @@
+import { access, readdir, readFile, stat } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectory(p) {
+    try {
+        const s = await stat(p);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function measureStep(name, fn) {
+    const start = performance.now();
+    try {
+        const diagnostics = await fn();
+        const hasErrors = diagnostics.some((d) => d.severity === "error");
+        return {
+            name,
+            status: hasErrors ? "failed" : "passed",
+            durationMs: Math.round(performance.now() - start),
+            diagnostics,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name,
+            status: "failed",
+            durationMs: Math.round(performance.now() - start),
+            diagnostics: [
+                {
+                    code: "internal_error",
+                    severity: "error",
+                    message: `Step "${name}" threw: ${message}`,
+                    hint: "This is likely a bug in the verifier. Check the stack trace above.",
+                },
+            ],
+        };
+    }
+}
+function skippedStep(name, reason) {
+    return {
+        name,
+        status: "skipped",
+        durationMs: 0,
+        diagnostics: [
+            {
+                code: "step_skipped",
+                severity: "info",
+                message: reason,
+            },
+        ],
+    };
+}
+function buildRepairChecklist(steps) {
+    const items = [];
+    let index = 1;
+    for (const step of steps) {
+        for (const d of step.diagnostics) {
+            if (d.severity === "info")
+                continue;
+            const item = {
+                index,
+                step: step.name,
+                message: d.message,
+            };
+            if (d.file !== undefined)
+                item.file = d.file;
+            if (d.line !== undefined)
+                item.line = d.line;
+            if (d.hint !== undefined)
+                item.hint = d.hint;
+            if (d.fixCategory !== undefined)
+                item.fixCategory = d.fixCategory;
+            if (d.autoFixable !== undefined)
+                item.autoFixable = d.autoFixable;
+            items.push(item);
+            index++;
+        }
+    }
+    return items;
+}
+function buildReport(appRoot, steps) {
+    const hasFailure = steps.some((s) => s.status === "failed");
+    let errorCount = 0;
+    let warningCount = 0;
+    for (const step of steps) {
+        for (const d of step.diagnostics) {
+            if (d.severity === "error")
+                errorCount++;
+            if (d.severity === "warning")
+                warningCount++;
+        }
+    }
+    return {
+        status: hasFailure ? "failed" : "passed",
+        appRoot,
+        timestamp: new Date().toISOString(),
+        steps,
+        repairChecklist: buildRepairChecklist(steps),
+        summary: {
+            totalSteps: steps.length,
+            passedSteps: steps.filter((s) => s.status === "passed").length,
+            failedSteps: steps.filter((s) => s.status === "failed").length,
+            skippedSteps: steps.filter((s) => s.status === "skipped").length,
+            errorCount,
+            warningCount,
+        },
+    };
+}
+/**
+ * Walk a directory recursively and return all file paths relative to root.
+ */
+async function walkFiles(dir, root) {
+    const results = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = await walkFiles(full, root);
+            results.push(...nested);
+        }
+        else if (entry.isFile()) {
+            results.push(relative(root, full));
+        }
+    }
+    return results;
+}
+/**
+ * Suggest an actionable repair hint based on a TypeScript error message.
+ */
+function suggestTypeHint(message) {
+    if (message.includes("Cannot find module")) {
+        return "Check that the import path is correct and the dependency is installed.";
+    }
+    if (message.includes("is not assignable to type")) {
+        return "Align the value with the expected type contract.";
+    }
+    if (message.includes("Property") && message.includes("is missing")) {
+        return `Add the missing property to satisfy the type contract.`;
+    }
+    if (message.includes("Property") && message.includes("does not exist")) {
+        return "Remove the unknown property or update the type definition.";
+    }
+    if (message.includes("Cannot find name")) {
+        return "Import or declare the referenced identifier.";
+    }
+    return "Fix the reported TypeScript error and rerun verification.";
+}
+// ---------------------------------------------------------------------------
+// HTTP methods recognized in API route files
+// ---------------------------------------------------------------------------
+const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"];
+// ---------------------------------------------------------------------------
+// Step implementations
+// ---------------------------------------------------------------------------
+async function checkStructure(appRoot) {
+    const diagnostics = [];
+    // Config file — one of the two must exist
+    const hasConfigTs = await pathExists(join(appRoot, "capstan.config.ts"));
+    const hasConfigJs = await pathExists(join(appRoot, "capstan.config.js"));
+    if (!hasConfigTs && !hasConfigJs) {
+        diagnostics.push({
+            code: "missing_config",
+            severity: "error",
+            message: "Missing capstan.config.ts or capstan.config.js",
+            hint: "Create a capstan.config.ts that exports your app configuration via defineConfig().",
+            fixCategory: "missing_file",
+            autoFixable: true,
+        });
+    }
+    // Routes directory
+    const routesDir = join(appRoot, "app", "routes");
+    if (!(await isDirectory(routesDir))) {
+        diagnostics.push({
+            code: "missing_routes_dir",
+            severity: "error",
+            message: "Missing app/routes/ directory",
+            hint: "Create app/routes/ and add at least one route file (e.g. index.api.ts).",
+            fixCategory: "missing_file",
+            autoFixable: true,
+        });
+    }
+    // package.json
+    if (!(await pathExists(join(appRoot, "package.json")))) {
+        diagnostics.push({
+            code: "missing_package_json",
+            severity: "error",
+            message: "Missing package.json",
+            hint: "Run npm init or create a package.json manually.",
+            fixCategory: "missing_file",
+            autoFixable: true,
+        });
+    }
+    // tsconfig.json
+    if (!(await pathExists(join(appRoot, "tsconfig.json")))) {
+        diagnostics.push({
+            code: "missing_tsconfig",
+            severity: "error",
+            message: "Missing tsconfig.json",
+            hint: "Create a tsconfig.json extending @zauso-ai/capstan-core recommended settings.",
+            fixCategory: "missing_file",
+            autoFixable: true,
+        });
+    }
+    return diagnostics;
+}
+async function checkConfig(appRoot) {
+    const diagnostics = [];
+    // Find the config file
+    let configPath = null;
+    const tsPath = join(appRoot, "capstan.config.ts");
+    const jsPath = join(appRoot, "capstan.config.js");
+    if (await pathExists(tsPath)) {
+        configPath = tsPath;
+    }
+    else if (await pathExists(jsPath)) {
+        configPath = jsPath;
+    }
+    if (!configPath) {
+        diagnostics.push({
+            code: "config_not_found",
+            severity: "error",
+            message: "Config file not found (should have been caught by structure step).",
+            fixCategory: "missing_file",
+        });
+        return diagnostics;
+    }
+    try {
+        const configUrl = pathToFileURL(configPath).href;
+        const mod = (await import(configUrl));
+        if (!mod["default"] && !mod["config"]) {
+            diagnostics.push({
+                code: "config_no_export",
+                severity: "error",
+                message: `Config file ${relative(appRoot, configPath)} does not export a default or named "config" value.`,
+                hint: 'Export a config object via: export default defineConfig({ ... })',
+                file: configPath,
+                fixCategory: "missing_export",
+                autoFixable: false,
+            });
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        diagnostics.push({
+            code: "config_load_error",
+            severity: "error",
+            message: `Failed to load config: ${message}`,
+            hint: "Ensure the config file is valid TypeScript/JavaScript and all imports resolve.",
+            file: configPath,
+            fixCategory: "type_error",
+        });
+    }
+    return diagnostics;
+}
+async function checkRoutes(appRoot) {
+    const diagnostics = [];
+    const routesDir = join(appRoot, "app", "routes");
+    if (!(await isDirectory(routesDir))) {
+        return diagnostics; // Already caught by structure step
+    }
+    // Use the router scanner to discover routes
+    const { scanRoutes } = await import("@zauso-ai/capstan-router");
+    const manifest = await scanRoutes(routesDir);
+    const apiRoutes = manifest.routes.filter((r) => r.type === "api");
+    if (apiRoutes.length === 0) {
+        diagnostics.push({
+            code: "no_api_routes",
+            severity: "warning",
+            message: "No .api.ts route files found in app/routes/",
+            hint: "Create at least one API route (e.g. app/routes/index.api.ts) with exported HTTP handlers.",
+        });
+        return diagnostics;
+    }
+    for (const route of apiRoutes) {
+        const relPath = relative(appRoot, route.filePath);
+        // Read and analyze the route source
+        let source;
+        try {
+            source = await readFile(route.filePath, "utf-8");
+        }
+        catch {
+            diagnostics.push({
+                code: "route_unreadable",
+                severity: "error",
+                message: `Cannot read route file: ${relPath}`,
+                file: route.filePath,
+                fixCategory: "missing_file",
+            });
+            continue;
+        }
+        // Check that at least one HTTP method is exported
+        const exportedMethods = HTTP_METHODS.filter((m) => {
+            // Match: export const GET, export async function GET, export function GET, export { GET }
+            const patterns = [
+                new RegExp(`export\\s+(const|let|var|async\\s+function|function)\\s+${m}\\b`),
+                new RegExp(`export\\s*\\{[^}]*\\b${m}\\b[^}]*\\}`),
+            ];
+            return patterns.some((p) => p.test(source));
+        });
+        if (exportedMethods.length === 0) {
+            diagnostics.push({
+                code: "no_http_exports",
+                severity: "error",
+                message: `${relPath}: No HTTP method exports found (expected GET, POST, PUT, DELETE, or PATCH)`,
+                hint: "Export at least one handler: export const GET = defineAPI({ ... })",
+                file: route.filePath,
+                fixCategory: "missing_export",
+                autoFixable: false,
+            });
+            continue;
+        }
+        // For each exported method, check if it's wrapped in defineAPI()
+        for (const method of exportedMethods) {
+            // Heuristic: look for `export const METHOD = defineAPI({` patterns
+            const defineAPIPattern = new RegExp(`export\\s+const\\s+${method}\\s*=\\s*defineAPI\\s*\\(`);
+            if (!defineAPIPattern.test(source)) {
+                // Also check for two-step: const METHOD = defineAPI(...); export { METHOD }
+                const twoStepPattern = new RegExp(`(?:const|let|var)\\s+${method}\\s*=\\s*defineAPI\\s*\\(`);
+                const exportPattern = new RegExp(`export\\s*\\{[^}]*\\b${method}\\b[^}]*\\}`);
+                if (!(twoStepPattern.test(source) && exportPattern.test(source))) {
+                    diagnostics.push({
+                        code: "handler_not_defineapi",
+                        severity: "warning",
+                        message: `${relPath}: ${method} handler is not wrapped in defineAPI()`,
+                        hint: `Wrap the ${method} handler with defineAPI() for type-safe input/output validation and agent introspection.`,
+                        file: route.filePath,
+                        fixCategory: "schema_mismatch",
+                        autoFixable: true,
+                    });
+                }
+            }
+        }
+        // Check write capability handlers for policy field
+        for (const method of exportedMethods) {
+            // Look for defineAPI blocks that include capability: "write"
+            const writeCapabilityPattern = new RegExp(`(?:export\\s+const\\s+${method}|(?:const|let|var)\\s+${method})\\s*=\\s*defineAPI\\s*\\(\\s*\\{[^}]*capability\\s*:\\s*["']write["']`, "s");
+            if (writeCapabilityPattern.test(source)) {
+                // Check if the same block also has a policy field
+                // We grab from the defineAPI call to the closing of its argument
+                const blockPattern = new RegExp(`(?:export\\s+const\\s+${method}|(?:const|let|var)\\s+${method})\\s*=\\s*defineAPI\\s*\\(\\s*\\{([^]*?)handler\\s*:`, "s");
+                const blockMatch = source.match(blockPattern);
+                const blockContent = blockMatch ? blockMatch[1] ?? "" : "";
+                if (!blockContent.includes("policy")) {
+                    diagnostics.push({
+                        code: "write_missing_policy",
+                        severity: "warning",
+                        message: `${relPath}: ${method} handler has capability: "write" but no "policy" field`,
+                        hint: `Add policy: "requireAuth" to protect write endpoints from unauthorized access.`,
+                        file: route.filePath,
+                        fixCategory: "policy_violation",
+                        autoFixable: true,
+                    });
+                }
+            }
+        }
+    }
+    return diagnostics;
+}
+async function checkModels(appRoot) {
+    const diagnostics = [];
+    const modelsDir = join(appRoot, "app", "models");
+    if (!(await isDirectory(modelsDir))) {
+        // Models directory is optional — not an error
+        return diagnostics;
+    }
+    const files = await walkFiles(modelsDir, modelsDir);
+    const modelFiles = files.filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts") && !f.startsWith("_"));
+    if (modelFiles.length === 0) {
+        diagnostics.push({
+            code: "empty_models_dir",
+            severity: "info",
+            message: "app/models/ exists but contains no model files.",
+        });
+        return diagnostics;
+    }
+    for (const relFile of modelFiles) {
+        const fullPath = join(modelsDir, relFile);
+        const relFromRoot = relative(appRoot, fullPath);
+        let source;
+        try {
+            source = await readFile(fullPath, "utf-8");
+        }
+        catch {
+            diagnostics.push({
+                code: "model_unreadable",
+                severity: "error",
+                message: `Cannot read model file: ${relFromRoot}`,
+                file: fullPath,
+                fixCategory: "missing_file",
+            });
+            continue;
+        }
+        // Check for at least one exported schema or model definition
+        const hasExport = /export\s+(const|function|class|type|interface)\b/.test(source) ||
+            /export\s*\{/.test(source);
+        if (!hasExport) {
+            diagnostics.push({
+                code: "model_no_exports",
+                severity: "warning",
+                message: `${relFromRoot}: No exports found in model file`,
+                hint: "Model files should export at least one schema, type, or class definition.",
+                file: fullPath,
+                fixCategory: "missing_export",
+            });
+        }
+        // Check for common model patterns (Zod schemas, Drizzle tables, etc.)
+        const hasSchema = /z\.\s*(object|string|number|boolean|enum|array)\s*\(/.test(source) ||
+            /sqliteTable|pgTable|mysqlTable/.test(source) ||
+            /defineModel/.test(source);
+        if (!hasSchema && hasExport) {
+            diagnostics.push({
+                code: "model_no_schema",
+                severity: "info",
+                message: `${relFromRoot}: No recognized schema pattern found (Zod, Drizzle, or defineModel)`,
+                hint: "Consider using Zod schemas or Drizzle table definitions for type-safe models.",
+                file: fullPath,
+            });
+        }
+    }
+    return diagnostics;
+}
+async function checkTypeScript(appRoot) {
+    const diagnostics = [];
+    // Locate tsc binary — first check local node_modules, then fall back to
+    // the monorepo root.
+    let tscBinary = join(appRoot, "node_modules", ".bin", "tsc");
+    if (!(await pathExists(tscBinary))) {
+        // Try the monorepo root from @zauso-ai/capstan-core's location
+        const packageDir = dirname(fileURLToPath(import.meta.url));
+        const repoRoot = resolve(packageDir, "../../..");
+        const repoTsc = join(repoRoot, "node_modules", ".bin", "tsc");
+        if (await pathExists(repoTsc)) {
+            tscBinary = repoTsc;
+        }
+        else {
+            diagnostics.push({
+                code: "tsc_not_found",
+                severity: "error",
+                message: "TypeScript compiler (tsc) not found in node_modules",
+                hint: "Install TypeScript: npm install -D typescript",
+                fixCategory: "missing_file",
+            });
+            return diagnostics;
+        }
+    }
+    try {
+        await execFileAsync(tscBinary, ["--noEmit", "--pretty", "false"], {
+            cwd: appRoot,
+            timeout: 60_000,
+        });
+        // Exit code 0 — no errors
+    }
+    catch (err) {
+        // tsc exits with code 1+ when there are errors. The stderr/stdout
+        // contains the diagnostic output.
+        const execError = err;
+        const output = (execError.stdout ?? "") + (execError.stderr ?? "");
+        if (!output.trim()) {
+            diagnostics.push({
+                code: "tsc_unknown_failure",
+                severity: "error",
+                message: "TypeScript compiler exited with an error but produced no output.",
+                hint: "Run tsc --noEmit manually to see what happened.",
+                fixCategory: "type_error",
+            });
+            return diagnostics;
+        }
+        // Parse tsc output: file(line,col): error TSxxxx: message
+        const pattern = /^(?<file>.+?)\((?<line>\d+),(?<column>\d+)\): error (?<tscode>TS\d+): (?<message>.+)$/gm;
+        for (const match of output.matchAll(pattern)) {
+            const groups = match.groups;
+            if (!groups)
+                continue;
+            const file = groups["file"] ?? "";
+            const message = groups["message"] ?? "Unknown TypeScript error";
+            const tsCode = groups["tscode"] ?? "TS0000";
+            diagnostics.push({
+                code: `typescript_${tsCode}`,
+                severity: "error",
+                message: `${relative(appRoot, file)}:${groups["line"]} — ${message}`,
+                hint: suggestTypeHint(message),
+                file: resolve(appRoot, file),
+                line: Number(groups["line"]),
+                column: Number(groups["column"]),
+                fixCategory: "type_error",
+                autoFixable: false,
+            });
+        }
+        // If the pattern didn't match anything, report the raw output
+        if (diagnostics.length === 0) {
+            diagnostics.push({
+                code: "tsc_parse_failure",
+                severity: "error",
+                message: `TypeScript errors detected but could not be parsed. Raw output:\n${output.slice(0, 500)}`,
+                hint: "Run tsc --noEmit manually to see the full output.",
+                fixCategory: "type_error",
+            });
+        }
+    }
+    return diagnostics;
+}
+async function checkContracts(appRoot) {
+    const diagnostics = [];
+    const routesDir = join(appRoot, "app", "routes");
+    const modelsDir = join(appRoot, "app", "models");
+    const policiesDir = join(appRoot, "app", "policies");
+    // Gather route names (directory names under app/routes/)
+    const routeNames = new Set();
+    if (await isDirectory(routesDir)) {
+        try {
+            const entries = await readdir(routesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    routeNames.add(entry.name.toLowerCase());
+                }
+            }
+        }
+        catch {
+            // Ignore read errors — structure step would have caught missing dir
+        }
+    }
+    // Gather model names (filename stems under app/models/)
+    const modelNames = new Set();
+    if (await isDirectory(modelsDir)) {
+        const modelFiles = await walkFiles(modelsDir, modelsDir);
+        for (const f of modelFiles) {
+            if (f.endsWith(".ts") && !f.endsWith(".d.ts")) {
+                // "ticket.ts" -> "ticket"
+                const stem = f.replace(/\.ts$/, "").split("/").pop();
+                if (stem)
+                    modelNames.add(stem.toLowerCase());
+            }
+        }
+    }
+    // Gather defined policy keys
+    const policyKeys = new Set();
+    if (await isDirectory(policiesDir)) {
+        const policyFiles = await walkFiles(policiesDir, policiesDir);
+        for (const f of policyFiles) {
+            if (!f.endsWith(".ts") || f.endsWith(".d.ts"))
+                continue;
+            const fullPath = join(policiesDir, f);
+            try {
+                const source = await readFile(fullPath, "utf-8");
+                // Match: definePolicy({ key: "someKey" ... })
+                const keyPattern = /definePolicy\s*\(\s*\{[^}]*key\s*:\s*["']([^"']+)["']/g;
+                for (const match of source.matchAll(keyPattern)) {
+                    if (match[1])
+                        policyKeys.add(match[1]);
+                }
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+    }
+    // Cross-reference models and routes: if model "ticket" exists and route "tickets" exists,
+    // check they reference each other (informational)
+    for (const model of modelNames) {
+        // Simple pluralization: "ticket" -> "tickets"
+        const plural = model.endsWith("s") ? model : model + "s";
+        if (routeNames.has(plural) || routeNames.has(model)) {
+            // This is expected — no diagnostic needed, they match.
+            continue;
+        }
+        // Model exists without matching route — informational
+        diagnostics.push({
+            code: "model_without_route",
+            severity: "info",
+            message: `Model "${model}" has no matching route directory (expected "${plural}" or "${model}")`,
+            hint: `Consider creating app/routes/${plural}/ with API handlers for this model.`,
+            fixCategory: "contract_drift",
+        });
+    }
+    // Check API route files for meta.resource references to models
+    if (await isDirectory(routesDir)) {
+        const { scanRoutes } = await import("@zauso-ai/capstan-router");
+        const manifest = await scanRoutes(routesDir);
+        const apiRoutes = manifest.routes.filter((r) => r.type === "api");
+        for (const route of apiRoutes) {
+            const relPath = relative(appRoot, route.filePath);
+            let source;
+            try {
+                source = await readFile(route.filePath, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            // Check resource references: resource: "ticket"
+            const resourcePattern = /resource\s*:\s*["']([^"']+)["']/g;
+            for (const match of source.matchAll(resourcePattern)) {
+                const resource = match[1]?.toLowerCase();
+                if (resource && !modelNames.has(resource)) {
+                    diagnostics.push({
+                        code: "resource_no_model",
+                        severity: "warning",
+                        message: `${relPath}: references resource "${resource}" but no matching model file found`,
+                        hint: `Create app/models/${resource}.ts with the schema for this resource.`,
+                        file: route.filePath,
+                        fixCategory: "contract_drift",
+                    });
+                }
+            }
+            // Check policy references: policy: "requireAuth"
+            const policyPattern = /policy\s*:\s*["']([^"']+)["']/g;
+            for (const match of source.matchAll(policyPattern)) {
+                const policyRef = match[1];
+                if (policyRef && !policyKeys.has(policyRef)) {
+                    diagnostics.push({
+                        code: "policy_not_defined",
+                        severity: "error",
+                        message: `${relPath}: references policy "${policyRef}" but it is not defined`,
+                        hint: `Define the "${policyRef}" policy in app/policies/index.ts using definePolicy().`,
+                        file: route.filePath,
+                        fixCategory: "policy_violation",
+                    });
+                }
+            }
+        }
+    }
+    return diagnostics;
+}
+async function checkManifest(appRoot) {
+    const diagnostics = [];
+    const routesDir = join(appRoot, "app", "routes");
+    if (!(await isDirectory(routesDir))) {
+        return diagnostics;
+    }
+    // Generate a fresh manifest from the current routes
+    const { scanRoutes } = await import("@zauso-ai/capstan-router");
+    const { generateRouteManifest } = await import("@zauso-ai/capstan-router");
+    const routeManifest = await scanRoutes(routesDir);
+    const { apiRoutes } = generateRouteManifest(routeManifest);
+    if (apiRoutes.length === 0) {
+        diagnostics.push({
+            code: "manifest_empty",
+            severity: "warning",
+            message: "Agent manifest has no API routes.",
+            hint: "Add at least one .api.ts file under app/routes/ to generate capabilities.",
+        });
+        return diagnostics;
+    }
+    // For each API route, verify basic expectations
+    for (const apiRoute of apiRoutes) {
+        const relPath = relative(appRoot, apiRoute.filePath);
+        // Verify the route file actually exists
+        if (!(await pathExists(apiRoute.filePath))) {
+            diagnostics.push({
+                code: "manifest_orphan_route",
+                severity: "error",
+                message: `Manifest references ${apiRoute.method} ${apiRoute.path} but file is missing: ${relPath}`,
+                file: apiRoute.filePath,
+                fixCategory: "contract_drift",
+            });
+        }
+    }
+    // Check for API route files that exist on disk but are NOT in the manifest
+    const manifestFilePaths = new Set(apiRoutes.map((r) => r.filePath));
+    const diskApiRoutes = routeManifest.routes.filter((r) => r.type === "api");
+    for (const route of diskApiRoutes) {
+        if (!manifestFilePaths.has(route.filePath)) {
+            diagnostics.push({
+                code: "manifest_missing_route",
+                severity: "warning",
+                message: `API route ${relative(appRoot, route.filePath)} exists on disk but not in manifest`,
+                file: route.filePath,
+                fixCategory: "contract_drift",
+            });
+        }
+    }
+    // Check that each route file exports input/output schemas (informational)
+    for (const apiRoute of apiRoutes) {
+        let source;
+        try {
+            source = await readFile(apiRoute.filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        // Look for defineAPI calls with input and output schemas
+        const hasInput = /\binput\s*:/.test(source);
+        const hasOutput = /\boutput\s*:/.test(source);
+        if (!hasInput || !hasOutput) {
+            const missing = [];
+            if (!hasInput)
+                missing.push("input");
+            if (!hasOutput)
+                missing.push("output");
+            diagnostics.push({
+                code: "manifest_missing_schema",
+                severity: "info",
+                message: `${relative(appRoot, apiRoute.filePath)}: ${apiRoute.method} handler missing ${missing.join(" and ")} schema`,
+                hint: "Add Zod input/output schemas to defineAPI() for full agent introspection.",
+                file: apiRoute.filePath,
+                fixCategory: "schema_mismatch",
+            });
+        }
+    }
+    return diagnostics;
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Verify a Capstan runtime application.
+ *
+ * Runs a cascade of checks: structure -> config -> routes -> models ->
+ * typecheck -> contracts -> manifest. If an early step fails, dependent
+ * steps are skipped. Returns a structured VerifyReport suitable for both
+ * human display and AI agent consumption.
+ */
+export async function verifyCapstanApp(appRoot) {
+    const root = resolve(appRoot);
+    const steps = [];
+    // Step 1: structure
+    const structureStep = await measureStep("structure", () => checkStructure(root));
+    steps.push(structureStep);
+    if (structureStep.status === "failed") {
+        steps.push(skippedStep("config", "Skipped: structure check failed."));
+        steps.push(skippedStep("routes", "Skipped: structure check failed."));
+        steps.push(skippedStep("models", "Skipped: structure check failed."));
+        steps.push(skippedStep("typecheck", "Skipped: structure check failed."));
+        steps.push(skippedStep("contracts", "Skipped: structure check failed."));
+        steps.push(skippedStep("manifest", "Skipped: structure check failed."));
+        return buildReport(root, steps);
+    }
+    // Step 2: config
+    const configStep = await measureStep("config", () => checkConfig(root));
+    steps.push(configStep);
+    if (configStep.status === "failed") {
+        steps.push(skippedStep("routes", "Skipped: config check failed."));
+        steps.push(skippedStep("models", "Skipped: config check failed."));
+        steps.push(skippedStep("typecheck", "Skipped: config check failed."));
+        steps.push(skippedStep("contracts", "Skipped: config check failed."));
+        steps.push(skippedStep("manifest", "Skipped: config check failed."));
+        return buildReport(root, steps);
+    }
+    // Step 3: routes
+    const routesStep = await measureStep("routes", () => checkRoutes(root));
+    steps.push(routesStep);
+    // Step 4: models — runs even if routes fail (independent check)
+    const modelsStep = await measureStep("models", () => checkModels(root));
+    steps.push(modelsStep);
+    // Step 5: typecheck — runs even if routes/models have warnings, but skip
+    // if routes had hard errors (broken files will cause tsc noise)
+    if (routesStep.status === "failed") {
+        steps.push(skippedStep("typecheck", "Skipped: routes check failed."));
+        steps.push(skippedStep("contracts", "Skipped: routes check failed."));
+        steps.push(skippedStep("manifest", "Skipped: routes check failed."));
+        return buildReport(root, steps);
+    }
+    const typecheckStep = await measureStep("typecheck", () => checkTypeScript(root));
+    steps.push(typecheckStep);
+    if (typecheckStep.status === "failed") {
+        steps.push(skippedStep("contracts", "Skipped: typecheck failed."));
+        steps.push(skippedStep("manifest", "Skipped: typecheck failed."));
+        return buildReport(root, steps);
+    }
+    // Step 6: contracts
+    const contractsStep = await measureStep("contracts", () => checkContracts(root));
+    steps.push(contractsStep);
+    if (contractsStep.status === "failed") {
+        steps.push(skippedStep("manifest", "Skipped: contracts check failed."));
+        return buildReport(root, steps);
+    }
+    // Step 7: manifest
+    const manifestStep = await measureStep("manifest", () => checkManifest(root));
+    steps.push(manifestStep);
+    return buildReport(root, steps);
+}
+// ---------------------------------------------------------------------------
+// Human-readable report renderer
+// ---------------------------------------------------------------------------
+/**
+ * Render a VerifyReport as human-readable text output.
+ *
+ * Uses simple ASCII indicators: check mark for pass, x for fail, dash for skip.
+ */
+export function renderRuntimeVerifyText(report) {
+    const lines = [];
+    lines.push("Capstan Verify");
+    lines.push("");
+    for (const step of report.steps) {
+        const icon = step.status === "passed" ? "\u2713" : step.status === "failed" ? "\u2717" : "-";
+        const durationLabel = step.status === "skipped" ? "skipped" : `${step.durationMs}ms`;
+        lines.push(`  ${icon} ${step.name.padEnd(14)} (${durationLabel})`);
+        // Show error/warning diagnostics inline
+        for (const d of step.diagnostics) {
+            if (d.severity === "info")
+                continue;
+            const marker = d.severity === "error" ? "\u2717" : "!";
+            lines.push(`    ${marker} ${d.message}`);
+            if (d.hint) {
+                lines.push(`      \u2192 ${d.hint}`);
+            }
+        }
+    }
+    lines.push("");
+    lines.push(`  ${report.summary.errorCount} error${report.summary.errorCount !== 1 ? "s" : ""}, ${report.summary.warningCount} warning${report.summary.warningCount !== 1 ? "s" : ""}`);
+    if (report.repairChecklist.length > 0) {
+        lines.push("");
+        lines.push("  Repair Checklist:");
+        for (const item of report.repairChecklist) {
+            lines.push(`    ${item.index}. [${item.step}] ${item.message}`);
+            if (item.hint) {
+                lines.push(`       \u2192 ${item.hint}`);
+            }
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=verify.js.map