@amityco/foundry-mcp 0.1.0

package/dist/tools/project.js

@@ -0,0 +1,571 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readIfExists(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+export async function inspectProject(repoPath, surfacePath) {
+    const repoRoot = path.resolve(repoPath);
+    const surfaces = await detectProjectSurfaces(repoRoot);
+    const effectiveRoot = resolveSurfaceRoot(repoRoot, surfacePath);
+    const selectedSurface = surfacePath ? await surfaceForPath(repoRoot, effectiveRoot) : surfaceMatchingRoot(surfaces, repoRoot);
+    const { platforms, signals, designSignals } = await inspectRoot(effectiveRoot);
+    return {
+        repoRoot,
+        effectiveRoot,
+        selectedSurface,
+        platforms,
+        signals,
+        designSignals,
+        surfaces,
+    };
+}
+function resolveSurfaceRoot(repoRoot, surfacePath) {
+    if (!surfacePath) {
+        return repoRoot;
+    }
+    const resolved = path.resolve(repoRoot, surfacePath);
+    const relative = path.relative(repoRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("surfacePath must stay inside repoPath.");
+    }
+    return resolved;
+}
+async function inspectRoot(root) {
+    const signals = [];
+    const candidates = [
+        ["android", "settings.gradle", "Gradle project settings"],
+        ["android", "settings.gradle.kts", "Gradle Kotlin project settings"],
+        ["android", "app/build.gradle", "Android app Gradle file"],
+        ["android", "app/build.gradle.kts", "Android app Gradle Kotlin file"],
+        ["flutter", "pubspec.yaml", "Flutter/Dart package manifest"],
+        ["ios", "Podfile", "CocoaPods project manifest"],
+        ["ios", "Package.swift", "Swift package manifest"],
+        ["typescript", "package.json", "JavaScript or TypeScript package manifest"],
+        ["typescript", "tsconfig.json", "TypeScript project config"],
+    ];
+    for (const [platform, relativeFile, reason] of candidates) {
+        if (await exists(path.join(root, relativeFile))) {
+            signals.push({ platform, file: relativeFile, reason });
+        }
+    }
+    const packageJson = await readIfExists(path.join(root, "package.json"));
+    if (packageJson.includes("react-native")) {
+        signals.push({
+            platform: "react-native",
+            file: "package.json",
+            reason: "react-native dependency or script signal",
+        });
+    }
+    const platforms = Array.from(new Set(signals.map((signal) => signal.platform)));
+    return { platforms, signals, designSignals: await detectDesignSignals(root) };
+}
+export const inspectProjectTool = {
+    name: "inspect_project",
+    description: "Inspect a customer repository and detect likely platform/framework signals.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: {
+                type: "string",
+                description: "Absolute or relative path to the customer repository root.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await inspectProject(stringField(args, "repoPath"), optionalStringField(args, "surfacePath")));
+    },
+};
+export const validateSetupTool = {
+    name: "validate_setup",
+    description: "Check common social.plus setup risks for a detected platform.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            platform: {
+                type: "string",
+                description: "Optional platform override. If omitted, Foundry uses project inspection.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const inspection = await inspectProject(repoPath, optionalStringField(args, "surfacePath"));
+        const platform = optionalStringField(args, "platform") ?? inspection.platforms[0] ?? "unknown";
+        const findings = await validateSetup(inspection.effectiveRoot, platform);
+        return textResult({
+            platform,
+            surfacePath: inspection.selectedSurface?.path,
+            status: statusForFindings(findings),
+            findings,
+        });
+    },
+};
+async function validateSetup(repoPath, platform) {
+    const root = path.resolve(repoPath);
+    const findings = [];
+    if (platform === "android") {
+        findings.push(...(await validateAndroid(root)));
+    }
+    if (platform === "flutter") {
+        findings.push(...(await validateFlutter(root)));
+    }
+    if (platform === "typescript" || platform === "react-native") {
+        findings.push(...(await validateTypeScript(root, platform)));
+    }
+    if (platform === "ios") {
+        findings.push(...(await validateIos(root)));
+    }
+    if (platform === "unknown") {
+        findings.push({
+            ruleId: "project.platform.detected",
+            severity: "warning",
+            message: "Could not detect a supported project platform.",
+            recommendation: "Point repoPath at the app root or provide a platform override.",
+        });
+    }
+    return findings;
+}
+async function validateAndroid(root) {
+    const findings = [];
+    const manifestPath = "app/src/main/AndroidManifest.xml";
+    const manifest = await readIfExists(path.join(root, manifestPath));
+    const buildFiles = await existingFiles(root, ["app/build.gradle", "app/build.gradle.kts", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts"]);
+    const buildContent = await readMany(buildFiles);
+    const sourceFiles = await findFiles(root, [".kt", ".java"], 300);
+    const sourceContent = await readMany(sourceFiles);
+    const setupFiles = filesMatching(sourceContent, [/AmityCoreClient\s*\.\s*setup/, /AmityClient\s*\.\s*setup/]);
+    const loginFiles = filesMatching(sourceContent, [/AmityCoreClient\s*\.\s*login/, /AmityClient\s*\.\s*login/]);
+    const pushRegistrationFiles = filesMatching(sourceContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
+    const pushUnregisterFiles = filesMatching(sourceContent, [/unregisterPushNotification/, /disablePushNotification/, /unregister.*DeviceToken/i]);
+    const liveDataFiles = filesMatching(sourceContent, [/LiveCollection/, /LiveObject/, /\.observe\s*\(/, /\.subscribe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/]);
+    if (!manifest) {
+        findings.push(finding("android.manifest.present", "warning", "No AndroidManifest.xml found at the default app path.", manifestPath, "Confirm the Android app module path, then validate permissions and Application wiring."));
+    }
+    else {
+        if (!manifest.includes("android.permission.INTERNET")) {
+            findings.push(finding("android.permission.internet", "error", "Android INTERNET permission is missing.", manifestPath, "Add `<uses-permission android:name=\"android.permission.INTERNET\" />` to the app manifest."));
+        }
+        if (!/<application\b[^>]*android:name=/.test(manifest)) {
+            findings.push(finding("android.application.class", "warning", "No custom Application class is declared in AndroidManifest.xml.", manifestPath, "Initialize social.plus once from an Application class instead of an Activity or composable lifecycle."));
+        }
+    }
+    if (!containsAny(buildContent, [/co\.amity\.android:amity-sdk/, /Amity-Social-Cloud-Android-SDK/, /com\.github\.AmityCo/])) {
+        findings.push(finding("android.dependency.sdk", "warning", "No obvious social.plus Android SDK dependency was found in Gradle files.", relativeFile(root, buildFiles[0]), "Add the SDK dependency from the Android quick-start docs and keep all Amity dependencies on compatible versions."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("android.setup.present", "warning", "No obvious AmityCoreClient.setup call was found in Kotlin/Java files.", undefined, "Call SDK setup once during application startup before any social.plus API usage."));
+    }
+    else {
+        const activitySetup = setupFiles.find((file) => /Activity|Fragment|Composable|onCreateView/.test(sourceContent.get(file) ?? ""));
+        if (activitySetup) {
+            findings.push(finding("android.setup.lifecycle", "warning", "SDK setup appears near Activity/Fragment/UI lifecycle code.", relativeFile(root, activitySetup), "Prefer Application.onCreate so the SDK is initialized once and not reinitialized on screen recreation."));
+        }
+        if (!containsAnyForFiles(sourceContent, setupFiles, [/AmityEndpoint\./, /AmityRegion\./, /\bendpoint\s*=/, /\bregion\s*=/])) {
+            findings.push(finding("android.setup.region", "warning", "SDK setup was found but no explicit region/endpoint marker was detected.", relativeFile(root, setupFiles[0]), "Set the region/endpoint explicitly to match the customer's social.plus console project."));
+        }
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("android.login.present", "warning", "No obvious social.plus login call was found.", undefined, "Call login after the app has a known user identity, and before subscribing to social.plus collections."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding("android.push.unregister.present", "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(sourceContent, [/dispose\s*\(/, /Disposable/, /CompositeDisposable/, /clear\s*\(/, /removeObserver/, /unsubscribe/])) {
+        findings.push(finding("android.live.cleanup", "warning", "Live Object/Collection observation was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Dispose or unsubscribe observers when the Activity, Fragment, ViewModel, or composable lifecycle ends."));
+    }
+    return findings;
+}
+async function validateFlutter(root) {
+    const findings = [];
+    const pubspec = await readIfExists(path.join(root, "pubspec.yaml"));
+    const dartFiles = await findFiles(path.join(root, "lib"), [".dart"], 300);
+    const dartContent = await readMany(dartFiles);
+    const setupFiles = filesMatching(dartContent, [/AmityCoreClient\s*\.\s*setup/]);
+    const loginFiles = filesMatching(dartContent, [/AmityCoreClient\s*\.\s*login/]);
+    const pushRegistrationFiles = filesMatching(dartContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
+    const pushUnregisterFiles = filesMatching(dartContent, [/unregisterPushNotification/, /disablePushNotification/]);
+    const liveDataFiles = filesMatching(dartContent, [/LiveCollection/, /LiveObject/, /\.listen\s*\(/, /\.observe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/]);
+    if (!pubspec) {
+        findings.push(finding("flutter.pubspec.present", "warning", "No pubspec.yaml file was found.", "pubspec.yaml", "Point repoPath at the Flutter project root."));
+    }
+    else if (!/\bamity_sdk\s*:/.test(pubspec) && !pubspec.toLowerCase().includes("amity")) {
+        findings.push(finding("flutter.dependency.sdk", "warning", "No obvious social.plus/Amity dependency was found in pubspec.yaml.", "pubspec.yaml", "Add the Flutter SDK dependency from the Flutter quick-start docs."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("flutter.setup.present", "warning", "No obvious AmityCoreClient.setup call was found in lib/*.dart.", undefined, "Call AmityCoreClient.setup before any social.plus API usage."));
+    }
+    else {
+        if (!containsAny(dartContent, [/WidgetsFlutterBinding\.ensureInitialized\s*\(/])) {
+            findings.push(finding("flutter.binding.initialized", "warning", "SDK setup was found but WidgetsFlutterBinding.ensureInitialized was not detected.", relativeFile(root, setupFiles[0]), "Call WidgetsFlutterBinding.ensureInitialized before async SDK setup in main()."));
+        }
+        if (!containsAnyForFiles(dartContent, setupFiles, [/AmityEndpoint\./, /\bendpoint\s*:/, /\bregion\s*:/])) {
+            findings.push(finding("flutter.setup.region", "warning", "SDK setup was found but no explicit endpoint/region marker was detected.", relativeFile(root, setupFiles[0]), "Set the endpoint/region explicitly to match the customer's social.plus console project."));
+        }
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("flutter.login.present", "warning", "No obvious AmityCoreClient.login call was found.", undefined, "Call login after the app has a known user identity and before social.plus queries/subscriptions."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding("flutter.push.unregister.present", "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(dartContent, [/StreamSubscription/, /\.cancel\s*\(/, /dispose\s*\(/])) {
+        findings.push(finding("flutter.live.cleanup", "warning", "Live Object/Collection stream observation was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Store the subscription and cancel it from dispose or the owning lifecycle cleanup."));
+    }
+    return findings;
+}
+async function validateTypeScript(root, platform) {
+    const findings = [];
+    const packageJson = await readIfExists(path.join(root, "package.json"));
+    const sourceFiles = await findFiles(root, [".ts", ".tsx", ".js", ".jsx"], 500);
+    const sourceContent = await readMany(sourceFiles);
+    const setupFiles = filesMatching(sourceContent, [/Client\s*\.\s*createClient/, /createClient\s*\(/]);
+    const loginFiles = filesMatching(sourceContent, [/Client\s*\.\s*login/, /\.login\s*\(/]);
+    const pushRegistrationFiles = filesMatching(sourceContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
+    const pushUnregisterFiles = filesMatching(sourceContent, [/unregisterPushNotification/, /disablePushNotification/]);
+    const liveDataFiles = filesMatching(sourceContent, [/LiveCollection/, /LiveObject/, /\.subscribe\s*\(/, /\.observe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/, /onSnapshot/]);
+    if (!packageJson) {
+        findings.push(finding("typescript.package.present", "warning", "No package.json file was found.", "package.json", "Point repoPath at the TypeScript or React Native project root."));
+    }
+    else if (!packageJson.includes("@amityco/ts-sdk") && !packageJson.toLowerCase().includes("amity")) {
+        findings.push(finding("typescript.dependency.sdk", "warning", "No obvious social.plus/Amity package was found in package.json.", "package.json", "Add the TypeScript SDK dependency from the web quick-start docs."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("typescript.client.create", "warning", "No obvious TypeScript client initialization pattern was found.", undefined, "Create the social.plus client before login and before API usage."));
+    }
+    else {
+        if (!containsAnyForFiles(sourceContent, setupFiles, [/\bregion\s*:/, /\bapiRegion\b/, /\bapiEndpoint\b/])) {
+            findings.push(finding("typescript.client.region", "warning", "Client initialization was found but no explicit region or endpoint marker was detected.", relativeFile(root, setupFiles[0]), "Pass the region or endpoint that matches the customer's social.plus console project."));
+        }
+        const renderCycleSetup = setupFiles.find((file) => /useEffect|function\s+[A-Z]\w*\s*\(|const\s+[A-Z]\w*\s*=/.test(sourceContent.get(file) ?? ""));
+        if (renderCycleSetup && platform === "react-native") {
+            findings.push(finding("react-native.setup.lifecycle", "warning", "Client setup appears near component lifecycle code.", relativeFile(root, renderCycleSetup), "Keep client setup in a stable app initialization module to avoid duplicate initialization on remount."));
+        }
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("typescript.login.present", "warning", "No obvious social.plus login call was found.", undefined, "Call login after the app has a known user identity, and await it before subscribing to live collections."));
+    }
+    if (loginFiles.length > 0 && !containsAnyForFiles(sourceContent, loginFiles, [/sessionWillRenewAccessToken/, /sessionHandler/, /renewal\.renew/])) {
+        findings.push(finding("typescript.session.renewal", "info", "Login was found but no access-token renewal handler marker was detected.", relativeFile(root, loginFiles[0]), "For production authentication, verify the session handler renews tokens according to the authentication docs."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding(`${platform}.push.unregister.present`, "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(sourceContent, [/unsubscribe\s*\(/, /\.unsubscribe\s*\(/, /return\s*\(\s*\)\s*=>/, /return\s+unsubscribe/, /AbortController/, /cleanup/i])) {
+        findings.push(finding(`${platform}.live.cleanup`, "warning", "Live Object/Collection subscription was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Return or call the unsubscribe cleanup from the owning component, route, or store lifecycle."));
+    }
+    return findings;
+}
+async function validateIos(root) {
+    const findings = [];
+    const manifestFiles = await existingFiles(root, ["Podfile", "Package.swift"]);
+    const manifestContent = await readMany(manifestFiles);
+    const swiftFiles = await findFiles(root, [".swift"], 400);
+    const swiftContent = await readMany(swiftFiles);
+    const setupFiles = filesMatching(swiftContent, [/AmityClient\s*\(/, /AmityClient\s*\.\s*setup/]);
+    const loginFiles = filesMatching(swiftContent, [/\.login\s*\(/, /client\.login\s*\(/]);
+    const pushRegistrationFiles = filesMatching(swiftContent, [/registerPushNotification/, /enablePushNotification/, /didRegisterForRemoteNotifications/]);
+    const pushUnregisterFiles = filesMatching(swiftContent, [/unregisterPushNotification/, /disablePushNotification/]);
+    const liveDataFiles = filesMatching(swiftContent, [/AmityCollection/, /AmityObject/, /\.observe\s*\(/, /getPost\s*\(/, /queryPosts\s*\(/]);
+    if (manifestFiles.length === 0) {
+        findings.push(finding("ios.dependency.manifest", "warning", "No Podfile or Package.swift was found.", undefined, "Point repoPath at the iOS project root or verify the dependency manager manually."));
+    }
+    else if (!containsAny(manifestContent, [/Amity/i, /AmitySDK/i])) {
+        findings.push(finding("ios.dependency.sdk", "warning", "No obvious social.plus/Amity dependency was found in Podfile or Package.swift.", relativeFile(root, manifestFiles[0]), "Add the iOS SDK dependency from the iOS quick-start docs."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("ios.setup.present", "warning", "No obvious AmityClient initialization was found in Swift files.", undefined, "Initialize AmityClient before login and before social.plus API usage."));
+    }
+    else if (!containsAnyForFiles(swiftContent, setupFiles, [/\bregion\s*:/, /\.SG\b|\.EU\b|\.US\b/])) {
+        findings.push(finding("ios.setup.region", "warning", "AmityClient initialization was found but no explicit region marker was detected.", relativeFile(root, setupFiles[0]), "Set the region explicitly to match the customer's social.plus console project."));
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("ios.login.present", "warning", "No obvious social.plus login call was found.", undefined, "Call login after the app has a known user identity and handle session renewal for production auth."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding("ios.push.unregister.present", "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(swiftContent, [/AmityNotificationToken/, /\.invalidate\s*\(/, /deinit/, /viewWillDisappear/])) {
+        findings.push(finding("ios.live.cleanup", "warning", "Live Object/Collection observation was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Keep the notification token and invalidate or release it when the view/controller lifecycle ends."));
+    }
+    return findings;
+}
+function statusForFindings(findings) {
+    if (findings.some((finding) => finding.severity === "error")) {
+        return "blocked";
+    }
+    return findings.length === 0 ? "no-obvious-issues" : "needs-review";
+}
+function finding(ruleId, severity, message, file, recommendation) {
+    return { ruleId, severity, message, file, recommendation };
+}
+async function existingFiles(root, relativeFiles) {
+    const files = [];
+    for (const relativePath of relativeFiles) {
+        const absolutePath = path.join(root, relativePath);
+        if (await exists(absolutePath)) {
+            files.push(absolutePath);
+        }
+    }
+    return files;
+}
+async function detectProjectSurfaces(repoRoot) {
+    const candidateDirectories = await findSurfaceCandidateDirectories(repoRoot, 3);
+    const surfaces = [];
+    for (const directory of candidateDirectories) {
+        const { platforms, signals, designSignals } = await inspectRoot(directory);
+        if (platforms.length === 0) {
+            continue;
+        }
+        const relativePath = normalizeSurfacePath(path.relative(repoRoot, directory));
+        surfaces.push({
+            id: relativePath === "." ? "root" : relativePath,
+            path: relativePath,
+            platforms,
+            signals: signals.map((signal) => ({
+                ...signal,
+                file: relativePath === "." ? signal.file : path.posix.join(relativePath, signal.file),
+            })),
+            designSignalCount: designSignals.length,
+        });
+    }
+    return surfaces.sort((a, b) => {
+        if (a.path === ".") {
+            return -1;
+        }
+        if (b.path === ".") {
+            return 1;
+        }
+        return a.path.localeCompare(b.path);
+    });
+}
+async function findSurfaceCandidateDirectories(root, maxDepth) {
+    const found = new Set([root]);
+    async function walk(directory, depth) {
+        if (depth >= maxDepth) {
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || shouldSkipDirectory(entry.name)) {
+                continue;
+            }
+            const entryPath = path.join(directory, entry.name);
+            found.add(entryPath);
+            await walk(entryPath, depth + 1);
+        }
+    }
+    await walk(root, 0);
+    return Array.from(found);
+}
+async function surfaceForPath(repoRoot, effectiveRoot) {
+    const { platforms, signals, designSignals } = await inspectRoot(effectiveRoot);
+    const relativePath = normalizeSurfacePath(path.relative(repoRoot, effectiveRoot));
+    return {
+        id: relativePath === "." ? "root" : relativePath,
+        path: relativePath,
+        platforms,
+        signals,
+        designSignalCount: designSignals.length,
+    };
+}
+function surfaceMatchingRoot(surfaces, repoRoot) {
+    return surfaces.find((surface) => surface.path === normalizeSurfacePath(path.relative(repoRoot, repoRoot)));
+}
+function normalizeSurfacePath(relativePath) {
+    if (!relativePath || relativePath === ".") {
+        return ".";
+    }
+    return relativePath.split(path.sep).join(path.posix.sep);
+}
+function shouldSkipDirectory(name) {
+    return ["node_modules", ".git", "build", ".dart_tool", "dist", "coverage", ".next"].includes(name);
+}
+async function detectDesignSignals(root) {
+    const signals = [];
+    const candidateFiles = [
+        ["styles", "tailwind.config.js", "Tailwind design configuration"],
+        ["styles", "tailwind.config.cjs", "Tailwind design configuration"],
+        ["styles", "tailwind.config.mjs", "Tailwind design configuration"],
+        ["styles", "tailwind.config.ts", "Tailwind design configuration"],
+        ["theme", "src/theme.ts", "TypeScript theme module"],
+        ["theme", "src/theme.tsx", "TypeScript theme module"],
+        ["theme", "src/theme/index.ts", "TypeScript theme module"],
+        ["theme", "src/theme/index.tsx", "TypeScript theme module"],
+        ["tokens", "src/tokens.ts", "TypeScript design token module"],
+        ["tokens", "src/tokens/index.ts", "TypeScript design token module"],
+        ["tokens", "src/design-tokens.ts", "TypeScript design token module"],
+        ["tokens", "src/design-system/tokens.ts", "TypeScript design system token module"],
+        ["components", "src/design-system/components.ts", "TypeScript design system component registry"],
+        ["theme", "src/styles/theme.ts", "TypeScript theme module"],
+        ["theme", "src/styles/theme/index.ts", "TypeScript theme module"],
+        ["tokens", "src/styles/tokens.ts", "TypeScript design token module"],
+        ["styles", "src/styles/globals.css", "Global stylesheet"],
+        ["styles", "src/app/globals.css", "Global stylesheet"],
+        ["styles", "app/globals.css", "Global stylesheet"],
+        ["theme", "theme/index.ts", "TypeScript theme module"],
+        ["tokens", "tokens/index.ts", "TypeScript design token module"],
+        ["components", "components/ui/button.tsx", "Reusable UI component convention"],
+        ["components", "src/components/ui/button.tsx", "Reusable UI component convention"],
+        ["theme", "lib/theme.dart", "Flutter theme module"],
+        ["theme", "lib/app_theme.dart", "Flutter app theme module"],
+        ["theme", "lib/theme/app_theme.dart", "Flutter app theme module"],
+        ["theme", "lib/core/theme/app_theme.dart", "Flutter app theme module"],
+        ["theme", "lib/presentation/theme/app_theme.dart", "Flutter app theme module"],
+        ["tokens", "lib/design_tokens.dart", "Flutter design token module"],
+        ["tokens", "lib/theme/design_tokens.dart", "Flutter design token module"],
+        ["tokens", "app/src/main/res/values/colors.xml", "Android color resources"],
+        ["theme", "app/src/main/res/values/themes.xml", "Android theme resources"],
+    ];
+    for (const [kind, relativePath, reason] of candidateFiles) {
+        if (await exists(path.join(root, relativePath))) {
+            signals.push({ kind, file: relativePath, reason });
+        }
+    }
+    const sourceFiles = await findFiles(root, [".ts", ".tsx", ".js", ".jsx", ".dart", ".css"], 400);
+    const sourceContent = await readMany(sourceFiles);
+    const tokenLikeFiles = filesMatching(sourceContent, [
+        /ThemeData\s*\(/,
+        /ColorScheme\./,
+        /createTheme\s*\(/,
+        /extendTheme\s*\(/,
+        /createMuiTheme\s*\(/,
+        /ThemeProvider\b/,
+        /ChakraProvider\b/,
+        /TamaguiProvider\b/,
+        /NativeWindStyleSheet\b/,
+        /designTokens/,
+        /designSystem/,
+        /tokens\s*=/,
+        /\btheme\s*=\s*{/,
+        /\btheme\s*:\s*{/,
+        /\bcolors\s*:\s*{/,
+        /\bspacing\s*:\s*{/,
+        /\bradius\s*:\s*{/,
+        /--[a-z0-9-]+:\s*[^;]+;/i,
+    ]);
+    for (const file of tokenLikeFiles) {
+        const relativePath = relativeFile(root, file);
+        if (relativePath && !signals.some((signal) => signal.file === relativePath)) {
+            signals.push({
+                kind: inferDesignKind(relativePath),
+                file: relativePath,
+                reason: "Source content contains theme, token, or CSS custom property markers.",
+            });
+        }
+    }
+    return signals.slice(0, 20);
+}
+function inferDesignKind(relativePath) {
+    const normalized = relativePath.toLowerCase();
+    if (normalized.includes("token")) {
+        return "tokens";
+    }
+    if (normalized.includes("component")) {
+        return "components";
+    }
+    if (normalized.endsWith(".css")) {
+        return "styles";
+    }
+    return "theme";
+}
+async function findFiles(root, extensions, maxFiles) {
+    const found = [];
+    async function walk(directory) {
+        if (found.length >= maxFiles) {
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (found.length >= maxFiles) {
+                return;
+            }
+            if (shouldSkipDirectory(entry.name)) {
+                continue;
+            }
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+            }
+            else if (extensions.some((extension) => entry.name.endsWith(extension))) {
+                found.push(entryPath);
+            }
+        }
+    }
+    await walk(root);
+    return found;
+}
+async function readMany(files) {
+    const contents = new Map();
+    for (const file of files) {
+        contents.set(file, await readIfExists(file));
+    }
+    return contents;
+}
+function filesMatching(contents, patterns) {
+    const matches = [];
+    for (const [file, content] of contents) {
+        if (patterns.some((pattern) => pattern.test(content))) {
+            matches.push(file);
+        }
+    }
+    return matches;
+}
+function containsAny(contents, patterns) {
+    for (const content of contents.values()) {
+        if (patterns.some((pattern) => pattern.test(content))) {
+            return true;
+        }
+    }
+    return false;
+}
+function containsAnyForFiles(contents, files, patterns) {
+    return files.some((file) => {
+        const content = contents.get(file) ?? "";
+        return patterns.some((pattern) => pattern.test(content));
+    });
+}
+function relativeFile(root, file) {
+    return file ? path.relative(root, file) : undefined;
+}