@amityco/social-plus-vise 0.4.0

package/dist/tools/integration.js

@@ -0,0 +1,332 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { BROAD_SOCIAL_REGEX, DESIGN_REGEX, classifyOutcome, getOutcomeDefinition, hasAnswer, planContextFor, } from "../outcomes.js";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { applicableComplianceRuleSummaries } from "./compliance.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.",
+            },
+            answers: {
+                type: "object",
+                description: "Map of intake-question id to the customer's answer. Answered questions are removed from intake and matching stop conditions are suppressed so the host agent can re-plan after the user replies.",
+                additionalProperties: { type: "string" },
+            },
+        },
+        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"), answersFromInput(args.answers)));
+    },
+};
+function answersFromInput(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return {};
+    }
+    const answers = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === "string" && value.trim() !== "") {
+            answers[key] = value;
+        }
+    }
+    return answers;
+}
+async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}) {
+    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);
+    const ctx = planContextFor({
+        request,
+        outcome,
+        platform,
+        platforms: inspection.platforms,
+        designSignals: inspection.designSignals,
+        answers,
+    });
+    const definition = getOutcomeDefinition(outcome);
+    return {
+        outcome,
+        platform,
+        surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
+        availableSurfaces: inspection.surfaces,
+        supportLevel,
+        intent: intentFor(request, definition.interpretation),
+        intake: intakeFor(ctx, definition.intakeQuestions(ctx)),
+        docs: definition.docs(platform).filter((doc) => doc.path !== "unknown"),
+        requiredInputs: composeRequiredInputs(ctx, definition.requiredInputs(ctx)),
+        targetFiles: await targetFilesFor(root, outcome, platform, inspection.designSignals),
+        implementationRules: composeImplementationRules(ctx, definition.implementationRules(ctx)),
+        implementationSteps: definition.implementationSteps(ctx),
+        validation: ["validate_setup", "run_sensors", ...definition.validation(platform)],
+        applicableRules: await applicableComplianceRuleSummaries(outcome, inspection.platforms),
+        sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
+        stopConditions: composeStopConditions(ctx, definition.stopConditions(ctx), 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 intentFor(request, interpretation) {
+    const broadSocialRequest = BROAD_SOCIAL_REGEX.test(request);
+    const designRequest = DESIGN_REGEX.test(request);
+    return {
+        rawRequest: request,
+        interpretation,
+        ambiguity: broadSocialRequest || designRequest ? "high" : "medium",
+    };
+}
+function intakeFor(ctx, outcomeQuestions) {
+    const questions = [...outcomeQuestions];
+    if (ctx.mentionsDesign && ctx.designSignals.length === 0 && !hasAnswer(ctx.answers, "design_source")) {
+        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 (ctx.mentionsDesign && ctx.designSignals.length > 0 && !hasAnswer(ctx.answers, "confirm_design_source")) {
+        questions.push({
+            id: "confirm_design_source",
+            question: `Should the social UI use the detected design source(s): ${ctx.designSignals.map((signal) => signal.file).join(", ")}?`,
+            why: "Vise 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"],
+        });
+    }
+    const remainingBlocking = questions.filter((question) => question.blocksImplementationWhenMissing).length;
+    return {
+        status: remainingBlocking > 0 ? "needs-clarification" : "ready",
+        questions,
+        answers: ctx.answers,
+        remainingBlocking,
+    };
+}
+function composeRequiredInputs(ctx, outcomeInputs) {
+    const inputs = [
+        "social.plus API key local env/config variable name and placeholder; do not collect the secret value in chat",
+        "social.plus region: US, EU, or SG",
+        "user identity source for login",
+        ...outcomeInputs,
+    ];
+    if ((ctx.mentionsDesign || ctx.broadSocialRequest) && ctx.designSignals.length > 0) {
+        inputs.push(`confirm detected design source(s): ${ctx.designSignals.map((signal) => signal.file).join(", ")}`);
+    }
+    if ((ctx.mentionsDesign || ctx.broadSocialRequest) && ctx.designSignals.length === 0) {
+        inputs.push("design token or theme source file", "UI framework/design system used by the host app");
+    }
+    if (ctx.platform === "android") {
+        inputs.push("Android application module path");
+    }
+    if (ctx.platform === "ios") {
+        inputs.push("iOS dependency manager: Swift Package Manager or CocoaPods");
+    }
+    return inputs;
+}
+function composeImplementationRules(ctx, outcomeRules) {
+    const rules = [
+        "Do not ask the user to paste API keys, Firebase/APNS credentials, server-issued auth tokens, or other secrets into chat.",
+        "Do not invent API keys, app IDs, regions, user IDs, Firebase files, APNS keys, or server-issued auth tokens.",
+        "Create or update an env/config placeholder for required secrets and tell the user to fill the real value locally; only write local env files when they are ignored by git.",
+        "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.",
+    ];
+    if (ctx.platform === "android") {
+        rules.push("Do not initialize the SDK from an Activity, Fragment, or composable lifecycle when Application startup is available.");
+    }
+    if (ctx.platform === "flutter") {
+        rules.push("Call WidgetsFlutterBinding.ensureInitialized before async SDK setup in main().");
+    }
+    if (ctx.platform === "react-native") {
+        rules.push("Do not create the client inside a remounting React component body.");
+    }
+    rules.push(...outcomeRules);
+    if (ctx.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 composeStopConditions(ctx, outcomeStops, surfaces, surfacePath) {
+    const stops = [
+        "A required secret is missing and no safe ignored local env file or non-secret template path is clear.",
+        "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 (ctx.platform === "unknown" || ctx.outcome === "unknown") {
+        stops.push("The request or platform is unsupported; do not implement until clarified.");
+    }
+    if (ctx.platforms.length > 1 && !surfacePath) {
+        stops.push(`Multiple platform signals detected (${ctx.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.`);
+    }
+    stops.push(...outcomeStops);
+    if (ctx.broadSocialRequest && !hasAnswer(ctx.answers, "feature_surface")) {
+        stops.push("The requested social feature is too broad; confirm the first feature surface before implementing.");
+    }
+    if (ctx.mentionsDesign && ctx.designSignals.length === 0 && !hasAnswer(ctx.answers, "design_source")) {
+        stops.push("No design token, theme, or component source has been identified from the customer repo.");
+    }
+    return stops;
+}
+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";
+}
+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 dedupeTargetsByPath([
+            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 dedupeTargetsByPath([
+            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 dedupeTargetsByPath([
+            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 dedupeTargetsByPath([
+            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." }];
+}
+function dedupeTargetsByPath(targets) {
+    const seen = new Set();
+    const out = [];
+    for (const target of targets) {
+        if (seen.has(target.path)) {
+            continue;
+        }
+        seen.add(target.path);
+        out.push(target);
+    }
+    return out;
+}
+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.` };
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tools/patch.js

@@ -0,0 +1,67 @@
+import { objectInput, stringField, textResult } from "../types.js";
+export const generateGuardedPatchTool = {
+    name: "generate_guarded_patch",
+    description: "Yields a structured diff for the host AI agent to apply safely, rejecting any inline API keys or hardcoded IDs.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            targetFile: { type: "string", description: "Relative path to the file." },
+            diffContent: { type: "string", description: "The proposed code change." },
+        },
+        required: ["repoPath", "targetFile", "diffContent"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const targetFile = stringField(args, "targetFile");
+        const diffContent = stringField(args, "diffContent");
+        // Guardrail: Inline API Keys
+        const inlineApiKeyPattern = /\b(api[_-]?key)\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i;
+        const apiKeyMatch = inlineApiKeyPattern.exec(diffContent);
+        if (apiKeyMatch && !isAllowedPlaceholder(apiKeyMatch[2] ?? "")) {
+            return textResult({
+                status: "rejected",
+                reason: "The patch contains an inline API key. Please use environment variables or a configuration placeholder instead.",
+            });
+        }
+        // Guardrail: Hardcoded IDs
+        const hardcodedIdPattern = /\b(communityId|targetId|feedId|channelId)\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i;
+        const idMatch = hardcodedIdPattern.exec(diffContent);
+        if (idMatch && !isAllowedPlaceholder(idMatch[2] ?? "")) {
+            return textResult({
+                status: "rejected",
+                reason: `The patch contains a hardcoded literal for ${idMatch[1]}. Please do not invent or hardcode feed targets.`,
+            });
+        }
+        return textResult({
+            status: "approved",
+            repoPath,
+            targetFile,
+            diffContent,
+            instruction: "Host agent: This patch has passed Foundry guardrails. You may now apply this diff securely.",
+        });
+    },
+};
+function isAllowedPlaceholder(value) {
+    const normalized = value.toLowerCase().trim();
+    return [
+        "",
+        "api-key",
+        "your-api-key",
+        "your_api_key",
+        "provided-by-customer",
+        "customer-provided",
+        "replace-me",
+        "todo",
+        "community-id",
+        "community_id",
+        "target-id",
+        "target_id",
+        "feed-id",
+        "feed_id",
+        "channel-id",
+        "channel_id",
+    ].includes(normalized);
+}