@amityco/foundry-mcp 0.1.0

package/dist/tools/integration.js

@@ -0,0 +1,544 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { detectCommandSensors } from "./harness.js";
+import { inspectProject } from "./project.js";
+export const planIntegrationTool = {
+    name: "plan_integration",
+    description: "Create a grounded, evidence-backed implementation packet before an AI coding agent edits a customer project.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: {
+                type: "string",
+                description: "Absolute or relative path to the customer repository root.",
+            },
+            request: {
+                type: "string",
+                description: "Natural-language integration request.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath", "request"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const request = stringField(args, "request");
+        return textResult(await buildIntegrationPlan(repoPath, request, optionalStringField(args, "surfacePath")));
+    },
+};
+async function buildIntegrationPlan(repoPath, request, surfacePath) {
+    const repoRoot = path.resolve(repoPath);
+    const inspection = await inspectProject(repoRoot, surfacePath);
+    const root = inspection.effectiveRoot;
+    const outcome = classifyOutcome(request);
+    const platform = preferredPlatform(inspection.platforms);
+    const supportLevel = supportFor(outcome, platform);
+    const sensors = await detectCommandSensors(root, inspection.platforms);
+    return {
+        outcome,
+        platform,
+        surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
+        availableSurfaces: inspection.surfaces,
+        supportLevel,
+        intent: intentFor(request, outcome),
+        intake: intakeFor(request, outcome, inspection.designSignals),
+        docs: docsFor(outcome, platform),
+        requiredInputs: requiredInputsFor(request, outcome, platform, inspection.designSignals),
+        targetFiles: await targetFilesFor(root, outcome, platform, inspection.designSignals),
+        implementationRules: implementationRulesFor(request, outcome, platform),
+        implementationSteps: implementationStepsFor(outcome, platform, inspection.designSignals),
+        validation: validationFor(outcome, platform),
+        sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
+        stopConditions: stopConditionsFor(request, outcome, platform, inspection.platforms, inspection.designSignals, inspection.surfaces, surfacePath),
+        evidencePolicy: "Every implementation step must cite at least one detected file, docs page, validator rule, or required user input. If evidence is missing, stop and ask the user instead of inventing details.",
+    };
+}
+function classifyOutcome(request) {
+    const normalized = request.toLowerCase();
+    if (/\b(push|notification|firebase|fcm|apns)\b/.test(normalized)) {
+        return "setup-push";
+    }
+    if (/\b(live object|live objects|live collection|live collections|realtime collection|real-time collection|observe|observer|subscribe|subscription|unsubscribe|live update|live updates)\b/.test(normalized)) {
+        return "setup-live-data";
+    }
+    if (/\b(social feature|social features|feed|timeline|post list|news feed)\b/.test(normalized)) {
+        return "add-feed";
+    }
+    if (/\b(error|broken|crash|not working|fail|timeout|401|403)\b/.test(normalized)) {
+        return "troubleshoot";
+    }
+    if (/\b(validate|check|correct|setup right|initiali[sz])\b/.test(normalized)) {
+        return "validate-setup";
+    }
+    if (/\b(setup|set up|install|integrate|wire|configure)\b/.test(normalized)) {
+        return "setup-sdk";
+    }
+    return "unknown";
+}
+function intentFor(request, outcome) {
+    const broadSocialRequest = /\b(nice|social features|social feature|engagement|community experience)\b/i.test(request);
+    const designRequest = /\bdesign token|design tokens|theme|same design|design system|brand/i.test(request);
+    return {
+        rawRequest: request,
+        interpretation: interpretationFor(outcome),
+        ambiguity: broadSocialRequest || designRequest ? "high" : "medium",
+    };
+}
+function interpretationFor(outcome) {
+    if (outcome === "add-feed") {
+        return "Add a social feed or social content surface using the customer app's existing design system.";
+    }
+    if (outcome === "setup-push") {
+        return "Set up push notifications with platform credentials, user permission/token handling, device registration after login, and unregister on logout or user switch.";
+    }
+    if (outcome === "setup-live-data") {
+        return "Set up Live Object or Live Collection observation with loading/error states, granular updates, and cleanup when the view/component lifecycle ends.";
+    }
+    return `Implement ${outcome}.`;
+}
+function intakeFor(request, outcome, designSignals) {
+    const broadSocialRequest = /\b(nice|social features|social feature|engagement|community experience)\b/i.test(request);
+    const mentionsDesign = /\bdesign token|design tokens|theme|same design|design system|brand/i.test(request);
+    const questions = [];
+    if (outcome === "add-feed" && broadSocialRequest) {
+        questions.push({
+            id: "feature_surface",
+            question: "Which social surface should be implemented first?",
+            why: "The request is broad, so the coding agent needs one product surface before it can choose SDK docs, UI states, and target files.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+            options: ["feed", "profile", "community", "chat", "notifications"],
+        });
+    }
+    if (outcome === "add-feed") {
+        questions.push({
+            id: "feed_scope",
+            question: "What scope should the first feed use?",
+            why: "Feed APIs and query shape depend on whether the content is global, user-specific, or community-specific.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+            options: ["global", "user", "community"],
+        });
+        questions.push({
+            id: "target_screen_or_route",
+            question: "Which screen, route, or component should receive the social UI?",
+            why: "Foundry can identify platform files, but the host app owns navigation and product placement.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+        });
+    }
+    if (outcome === "setup-push") {
+        questions.push({
+            id: "push_platform",
+            question: "Which push platform and credentials are already configured for this app?",
+            why: "Device registration only works after platform push setup is complete in the app and social.plus console.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+            options: ["FCM", "APNS", "web push", "cross-platform FCM/APNS"],
+        });
+        questions.push({
+            id: "device_token_source",
+            question: "Where does the host app request notification permission and obtain the device token?",
+            why: "The social.plus SDK registers a token; the host app remains responsible for permission prompts and token creation.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+        });
+        questions.push({
+            id: "logout_user_switch_flow",
+            question: "Which logout or user-switch flow should unregister the device token?",
+            why: "A registered device is associated with one user at a time, so cleanup prevents notifications going to the wrong user.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+        });
+    }
+    if (outcome === "setup-live-data") {
+        questions.push({
+            id: "live_data_shape",
+            question: "Is the UI observing one object or a collection?",
+            why: "Live Objects and Live Collections have different callback shapes, update semantics, and UI handling.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+            options: ["single object", "collection"],
+        });
+        questions.push({
+            id: "live_data_domain",
+            question: "Which domain should be observed?",
+            why: "The docs and SDK entrypoints differ for posts, comments, messages, channels, users, and communities.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+            options: ["posts", "comments", "messages", "channels", "users", "communities", "stories"],
+        });
+        questions.push({
+            id: "lifecycle_owner",
+            question: "Which component, screen, ViewModel, or controller owns the subscription lifecycle?",
+            why: "Observers must be cleaned up when the UI lifecycle ends to avoid duplicate subscriptions and memory leaks.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+        });
+    }
+    if (mentionsDesign && designSignals.length === 0) {
+        questions.push({
+            id: "design_source",
+            question: "Where are the app's design tokens, theme, or reusable UI components defined?",
+            why: "The user asked to match the existing design, and no local design source was detected.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+        });
+    }
+    if (mentionsDesign && designSignals.length > 0) {
+        questions.push({
+            id: "confirm_design_source",
+            question: `Should the social UI use the detected design source(s): ${designSignals.map((signal) => signal.file).join(", ")}?`,
+            why: "Foundry found likely design evidence, but the user or host agent should confirm it is the right source before UI edits.",
+            required: true,
+            blocksImplementationWhenMissing: false,
+            options: ["yes", "use another source"],
+        });
+    }
+    return {
+        status: questions.some((question) => question.blocksImplementationWhenMissing) ? "needs-clarification" : "ready",
+        questions,
+    };
+}
+function preferredPlatform(platforms) {
+    const order = ["flutter", "android", "typescript", "react-native", "ios"];
+    return order.find((platform) => platforms.includes(platform)) ?? platforms[0] ?? "unknown";
+}
+function supportFor(outcome, platform) {
+    if (outcome === "unknown" || platform === "unknown") {
+        return "unsupported";
+    }
+    if (platform === "ios") {
+        return "guided";
+    }
+    if (["android", "flutter", "typescript", "react-native"].includes(platform)) {
+        return "supported";
+    }
+    return "guided";
+}
+function docsFor(outcome, platform) {
+    const docs = [];
+    if (outcome === "setup-sdk" || outcome === "validate-setup") {
+        docs.push(platformQuickStart(platform));
+        docs.push({
+            path: "social-plus-sdk/getting-started/authentication",
+            reason: "Canonical login, session, and authentication ordering guidance.",
+        });
+    }
+    if (outcome === "setup-push") {
+        docs.push({
+            path: "social-plus-sdk/core-concepts/realtime-communication/push-notifications/overview",
+            reason: "Push notification architecture, delivery options, and cross-platform setup overview.",
+        });
+        docs.push({
+            path: pushSetupPath(platform),
+            reason: "Canonical push notification setup for the detected platform.",
+        });
+        docs.push({
+            path: "social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device",
+            reason: "Device registration and logout/user-switch cleanup guidance.",
+        });
+        docs.push({
+            path: "social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/overview",
+            reason: "Notification preference settings for user/channel/community controls.",
+        });
+    }
+    if (outcome === "add-feed" || outcome === "setup-live-data") {
+        if (outcome === "add-feed") {
+            docs.push({
+                path: "social-plus-sdk/social/posts",
+                reason: "Canonical social post/feed concepts and API entrypoint.",
+            });
+        }
+        docs.push({
+            path: "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview",
+            reason: "Live Object and Live Collection lifecycle, snapshots, loading/error states, and cleanup guidance.",
+        });
+        docs.push({
+            path: liveDataPlatformPath(platform),
+            reason: "Platform-specific Live Object and Live Collection implementation patterns.",
+        });
+        docs.push({
+            path: "social-plus-sdk/core-concepts/realtime-communication/realtime-events/overview",
+            reason: "Real-time event subscription context for live data updates.",
+        });
+    }
+    if (outcome === "troubleshoot") {
+        docs.push({
+            path: "social-plus-sdk/getting-started/authentication",
+            reason: "Authentication and session issues are common setup failure causes.",
+        });
+        docs.push({
+            path: "social-plus-sdk/core-concepts/foundation/logging",
+            reason: "Logging and diagnostics guidance for debugging integration failures.",
+        });
+    }
+    return docs.filter((doc) => doc.path !== "unknown");
+}
+function platformQuickStart(platform) {
+    const paths = {
+        android: "social-plus-sdk/getting-started/platform-setup/mobile/android-quick-start",
+        flutter: "social-plus-sdk/getting-started/platform-setup/mobile/flutter-quick-start",
+        ios: "social-plus-sdk/getting-started/platform-setup/mobile/ios-quick-start",
+        typescript: "social-plus-sdk/getting-started/platform-setup/web/web-quick-start",
+        "react-native": "social-plus-sdk/getting-started/platform-setup/web/web-quick-start",
+    };
+    return {
+        path: paths[platform] ?? "unknown",
+        reason: "Canonical SDK setup guidance for the detected platform.",
+    };
+}
+function pushSetupPath(platform) {
+    const paths = {
+        android: "social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/android-setup",
+        flutter: "social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/flutter-setup",
+        ios: "social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/ios-setup",
+        typescript: "social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/web-setup",
+        "react-native": "social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/react-native-setup",
+    };
+    return paths[platform] ?? "unknown";
+}
+function liveDataPlatformPath(platform) {
+    const paths = {
+        android: "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/android",
+        flutter: "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/flutter",
+        ios: "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/ios",
+        typescript: "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/typescript",
+        "react-native": "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/typescript",
+    };
+    return paths[platform] ?? "unknown";
+}
+function requiredInputsFor(request, outcome, platform, designSignals) {
+    const inputs = ["social.plus API key", "social.plus region: US, EU, or SG", "user identity source for login"];
+    const mentionsDesign = /\bdesign token|design tokens|theme|same design|design system|brand/i.test(request);
+    const broadSocialRequest = /\b(nice|social features|social feature|engagement|community experience)\b/i.test(request);
+    const hasDesignSignal = designSignals.length > 0;
+    if (outcome === "setup-push") {
+        inputs.push("customer-owned Firebase/APNS/Web Push configuration", "device token source from the host app", "notification permission request flow", "device registration and logout/user-switch behavior");
+    }
+    if (outcome === "add-feed" || outcome === "setup-live-data") {
+        inputs.push("live data shape: single object or collection", "lifecycle owner for subscribe/unsubscribe cleanup");
+    }
+    if (outcome === "add-feed") {
+        inputs.push("feature choice: feed, profile, community, chat, notifications, or another social surface", "feed scope: global, user, or community", "target screen or route for the feed UI");
+    }
+    if (outcome === "setup-live-data") {
+        inputs.push("observed domain: posts, comments, messages, channels, users, communities, or stories", "query/filter/sort and pagination requirements", "UI handling for loading, empty, error, insertion, deletion, and modification states");
+    }
+    if ((mentionsDesign || broadSocialRequest) && hasDesignSignal) {
+        inputs.push(`confirm detected design source(s): ${designSignals.map((signal) => signal.file).join(", ")}`);
+    }
+    if ((mentionsDesign || broadSocialRequest) && !hasDesignSignal) {
+        inputs.push("design token or theme source file", "UI framework/design system used by the host app");
+    }
+    if (platform === "android") {
+        inputs.push("Android application module path");
+    }
+    if (platform === "ios") {
+        inputs.push("iOS dependency manager: Swift Package Manager or CocoaPods");
+    }
+    return inputs;
+}
+async function targetFilesFor(root, outcome, platform, designSignals) {
+    const designTargets = outcome === "add-feed" ? designSignals.map((signal) => ({
+        path: signal.file,
+        operation: "Reuse existing design tokens, theme values, component conventions, spacing, typography, and colors for the social UI.",
+        confidence: "high",
+        evidence: signal.reason,
+    })) : [];
+    const pushTargets = outcome === "setup-push" ? [
+        { path: "push token/permission flow", operation: "Request permission, obtain the platform device token, and handle token refresh.", confidence: "low", evidence: "Required device token source from the host app." },
+        { path: "login/auth flow", operation: "Register the device token only after social.plus login succeeds.", confidence: "low", evidence: "Device registration requires an authenticated client." },
+        { path: "logout/user-switch flow", operation: "Unregister the device token before logout or user switch completes.", confidence: "low", evidence: "Device association is user-specific." },
+    ] : [];
+    const liveTargets = outcome === "setup-live-data" ? [
+        { path: "target screen/component/controller", operation: "Observe the Live Object or Live Collection and render loading, empty, error, and data states.", confidence: "low", evidence: "Required lifecycle owner and target UI." },
+        { path: "data source/repository module", operation: "Encapsulate query/get calls and expose a cleanup-aware subscription API.", confidence: "low", evidence: "Live Objects and Collections require lifecycle cleanup." },
+    ] : [];
+    if (platform === "android") {
+        return [
+            await target(root, ["app/build.gradle.kts", "app/build.gradle"], "Add or verify the social.plus Android SDK dependency.", "Detected Android app Gradle module.", "medium"),
+            await target(root, ["app/src/main/AndroidManifest.xml"], "Verify permissions and Application class wiring.", "Detected default Android manifest path.", "medium"),
+            { path: "Application class", operation: "Initialize social.plus once at app startup.", confidence: "low", evidence: "Required by Android setup lifecycle rule; exact file must be detected by the coding agent." },
+            { path: "login/auth flow", operation: "Call social.plus login after user identity is known.", confidence: "low", evidence: "Required user identity source." },
+            ...pushTargets,
+            ...liveTargets,
+            ...designTargets,
+        ];
+    }
+    if (platform === "flutter") {
+        return [
+            await target(root, ["pubspec.yaml"], "Add or verify the Flutter SDK dependency.", "Detected Flutter package manifest.", "high"),
+            await target(root, ["lib/main.dart"], "Initialize Flutter binding and SDK before runApp.", "Conventional Flutter app entrypoint.", "medium"),
+            { path: "login/auth flow", operation: "Call AmityCoreClient.login after user identity is known.", confidence: "low", evidence: "Required user identity source." },
+            ...pushTargets,
+            ...liveTargets,
+            ...designTargets,
+        ];
+    }
+    if (platform === "typescript" || platform === "react-native") {
+        return [
+            await target(root, ["package.json"], "Add or verify the TypeScript SDK dependency.", "Detected JavaScript package manifest.", "high"),
+            { path: "client initialization module", operation: "Create the social.plus client with API key and region.", confidence: "low", evidence: "Validator rule: typescript.client.create." },
+            { path: "login/auth flow", operation: "Await login after user identity is known and before live subscriptions.", confidence: "low", evidence: "Required user identity source." },
+            ...pushTargets,
+            ...liveTargets,
+            ...designTargets,
+        ];
+    }
+    if (platform === "ios") {
+        return [
+            await target(root, ["Package.swift", "Podfile"], "Add or verify the iOS SDK dependency.", "Detected iOS dependency manifest if present.", "medium"),
+            { path: "app initialization flow", operation: "Initialize AmityClient with API key and region.", confidence: "low", evidence: "iOS quick-start docs." },
+            { path: "login/auth flow", operation: "Call login after user identity is known and handle session renewal.", confidence: "low", evidence: "Authentication docs." },
+            ...pushTargets,
+            ...liveTargets,
+            ...designTargets,
+        ];
+    }
+    return [{ path: "unknown", operation: "No safe target files can be selected until platform is detected.", confidence: "low", evidence: "No platform signal." }];
+}
+async function target(root, candidates, operation, evidence, fallbackConfidence) {
+    for (const candidate of candidates) {
+        if (await exists(path.join(root, candidate))) {
+            return { path: candidate, operation, confidence: "high", evidence };
+        }
+    }
+    return { path: candidates[0], operation, confidence: fallbackConfidence, evidence: `${evidence} File was not found at the conventional path; verify before editing.` };
+}
+function implementationRulesFor(request, outcome, platform) {
+    const rules = [
+        "Do not invent API keys, app IDs, regions, user IDs, Firebase files, APNS keys, or server-issued auth tokens.",
+        "Do not silently default the social.plus region; ask for US, EU, or SG if it is not known.",
+        "Do not make SDK calls before setup and login ordering is established.",
+        "Every code edit should be tied to a target file and validation step from this plan.",
+    ];
+    const mentionsDesign = /\bdesign token|design tokens|theme|same design|design system|brand/i.test(request);
+    if (platform === "android") {
+        rules.push("Do not initialize the SDK from an Activity, Fragment, or composable lifecycle when Application startup is available.");
+    }
+    if (platform === "flutter") {
+        rules.push("Call WidgetsFlutterBinding.ensureInitialized before async SDK setup in main().");
+    }
+    if (platform === "react-native") {
+        rules.push("Do not create the client inside a remounting React component body.");
+    }
+    if (outcome === "setup-push") {
+        rules.push("Do not fabricate Firebase/APNS/Web Push configuration. Use customer-provided push credentials and files only.");
+        rules.push("Do not register a device token before social.plus login succeeds.");
+        rules.push("Always unregister the device token on logout or user switch so a device is not tied to the wrong user.");
+        rules.push("Do not implement platform permission prompts or token creation unless the host app's push library and ownership are identified.");
+    }
+    if (outcome === "setup-live-data") {
+        rules.push("Do not replace Live Object or Live Collection observation with polling unless the docs or user explicitly require it.");
+        rules.push("Always clean up observers/subscriptions when the owning component, screen, ViewModel, or controller is destroyed.");
+        rules.push("Handle loading and error states from the live data API before rendering data as ready.");
+        rules.push("For collections, use insertion/deletion/modification changes for targeted UI updates instead of assuming a full list replacement.");
+    }
+    if (mentionsDesign) {
+        rules.push("Do not create a new visual system. Inspect and reuse the host app's existing design tokens, theme files, components, spacing, typography, and color conventions.");
+    }
+    return rules;
+}
+function implementationStepsFor(outcome, platform, designSignals) {
+    if (outcome === "setup-sdk") {
+        return [
+            { step: "Verify or add the platform SDK dependency.", evidence: [platformQuickStart(platform).path, "targetFiles.dependency"] },
+            { step: "Initialize the social.plus client exactly once with API key and explicit region.", evidence: [platformQuickStart(platform).path, "requiredInputs.social.plus API key", "requiredInputs.social.plus region"] },
+            { step: "Wire login after user identity is known and before social.plus API queries/subscriptions.", evidence: ["social-plus-sdk/getting-started/authentication", "requiredInputs.user identity source for login"] },
+            { step: "Run validate_setup and detected command sensors after edits.", evidence: ["validate_setup", "run_sensors"] },
+        ];
+    }
+    if (outcome === "setup-push") {
+        return [
+            { step: "Verify SDK setup and login are already correct before push work.", evidence: ["validate_setup", "social-plus-sdk/getting-started/authentication"] },
+            { step: "Confirm platform push credentials and app-side permission/token ownership.", evidence: ["requiredInputs.customer-owned Firebase/APNS/Web Push configuration", "requiredInputs.device token source from the host app", pushSetupPath(platform)] },
+            { step: "Wire platform push config using only customer-provided Firebase/APNS/Web Push material.", evidence: [pushSetupPath(platform), "requiredInputs.customer-owned Firebase/APNS/Web Push configuration"] },
+            { step: "Register device after login and unregister on logout/user switch.", evidence: ["social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device"] },
+            { step: "Run validate_setup and detected command sensors after edits.", evidence: ["validate_setup", "run_sensors"] },
+        ];
+    }
+    if (outcome === "add-feed") {
+        const designEvidence = designSignals.length > 0 ? designSignals.map((signal) => signal.file) : ["requiredInputs.design token or theme source file"];
+        return [
+            { step: "Confirm the target route/screen and feed scope before writing code.", evidence: ["requiredInputs.feed scope", "requiredInputs.target screen or route"] },
+            { step: "Fetch the canonical social/feed docs and use platform-appropriate live collection patterns.", evidence: ["social-plus-sdk/social/posts", "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview"] },
+            { step: "Reuse the host app's existing visual system for the social surface.", evidence: designEvidence },
+            { step: "Implement loading, empty, error, and data states.", evidence: ["implementationRules.file-specific edits"] },
+            { step: "Run validate_setup and detected command sensors after edits.", evidence: ["validate_setup", "run_sensors"] },
+        ];
+    }
+    if (outcome === "setup-live-data") {
+        return [
+            { step: "Confirm whether the UI needs a Live Object or Live Collection and which domain it observes.", evidence: ["requiredInputs.live data shape", "requiredInputs.observed domain"] },
+            { step: "Fetch Live Objects/Collections docs plus platform-specific implementation guidance.", evidence: ["social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview", liveDataPlatformPath(platform)] },
+            { step: "Implement the subscription in the owning lifecycle scope and render loading, empty, error, and data states.", evidence: ["requiredInputs.lifecycle owner for subscribe/unsubscribe cleanup", "implementationRules.loading-error-states"] },
+            { step: "For collections, apply insertion, deletion, and modification changes without unnecessary full-list rerenders.", evidence: ["social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview"] },
+            { step: "Clean up the observer/subscription when the owner unmounts, disposes, or disappears.", evidence: ["implementationRules.cleanup", "validate_setup"] },
+            { step: "Run validate_setup and detected command sensors after edits.", evidence: ["validate_setup", "run_sensors"] },
+        ];
+    }
+    return [{ step: "Gather more evidence before implementation.", evidence: ["stopConditions", "search_docs", "inspect_project"] }];
+}
+function validationFor(outcome, platform) {
+    const validation = ["validate_setup", "run_sensors"];
+    if (outcome === "setup-sdk") {
+        validation.push(`${platform}.setup.present`, `${platform}.login.present`, `${platform}.region.explicit`);
+    }
+    if (outcome === "setup-push") {
+        validation.push("push permission and token source identified", "device registration after login", "unregister on logout/user switch", `${platform}.push.unregister.present`);
+    }
+    if (outcome === "setup-live-data") {
+        validation.push("live data owner identified", "loading and error states handled", "subscription cleanup on lifecycle end", `${platform}.live.cleanup`);
+    }
+    return validation;
+}
+function stopConditionsFor(request, outcome, platform, platforms, designSignals, surfaces, surfacePath) {
+    const mentionsDesign = /\bdesign token|design tokens|theme|same design|design system|brand/i.test(request);
+    const broadSocialRequest = /\b(nice|social features|social feature|engagement|community experience)\b/i.test(request);
+    const stops = [
+        "Required customer secrets or credentials are missing.",
+        "The target file is ambiguous or missing and no safe conventional location is detected.",
+        "Docs lookup does not return the canonical page named in this plan.",
+    ];
+    if (platform === "unknown" || outcome === "unknown") {
+        stops.push("The request or platform is unsupported; do not implement until clarified.");
+    }
+    if (platforms.length > 1 && !surfacePath) {
+        stops.push(`Multiple platform signals detected (${platforms.join(", ")}); confirm which app surface should be modified.`);
+    }
+    if (surfaces.length > 1 && !surfacePath) {
+        stops.push(`Multiple app surfaces detected (${surfaces.map((surface) => surface.path).join(", ")}); call this tool again with surfacePath set to the target app surface.`);
+    }
+    if (outcome === "setup-push") {
+        stops.push("Firebase/APNS/Web Push configuration is not present or not provided by the customer.");
+        stops.push("The host app's notification permission and device-token source is unknown.");
+        stops.push("No logout or user-switch cleanup point is identified for unregistering device tokens.");
+    }
+    if (outcome === "setup-live-data") {
+        stops.push("The request does not identify whether the UI needs a Live Object or Live Collection.");
+        stops.push("The lifecycle owner for subscription cleanup is unknown.");
+    }
+    if (broadSocialRequest) {
+        stops.push("The requested social feature is too broad; confirm the first feature surface before implementing.");
+    }
+    if (mentionsDesign && designSignals.length === 0) {
+        stops.push("No design token, theme, or component source has been identified from the customer repo.");
+    }
+    return stops;
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}