@amityco/social-plus-vise 1.1.1 → 1.3.0

package/dist/solutionPath.js

@@ -0,0 +1,274 @@
+const UIKIT_SIGNALS = [
+    {
+        id: "explicit-uikit",
+        label: "Explicit social.plus UIKit / UI Kit mention",
+        strength: "strong",
+        pattern: /\b(?:social\.plus\s+)?(?:ui\s?kit|uikit)\b(?!\s+(?:experience|expertise|knowledge|background|familiarity))/i,
+    },
+    {
+        id: "prebuilt-components",
+        label: "Prebuilt or ready-made social UI components",
+        strength: "strong",
+        pattern: /\b(pre[-\s]?built|ready[-\s]?made)\b|\b(?:ready[-\s]?to[-\s]?use|out[-\s]?of[-\s]?the[-\s]?box|plug[-\s]?and[-\s]?play|drop[-\s]?in|off[-\s]?the[-\s]?shelf)\b(?:\s+(?:social\.plus|social|messaging|message|notifications?|community|communities|chat|feeds?|profiles?|stor(?:y|ies)|comments?|users?|groups?|channels?|posts?|prebuilt|standard|ui\s?kit|uikit))?\s+(?:ui|ui\s?kit|uikit|components?|widgets?|screens?|views?|feed|chat|profile|comments?|communit(?:y|ies)|stor(?:y|ies)|surfaces?)\b/i,
+    },
+    {
+        id: "speed-to-launch",
+        label: "Launch speed / MVP pressure",
+        strength: "medium",
+        pattern: /\b(quick launch|launch quickly|ship quickly|ship fast|mvp|build (?:a |an |the )?prototype|prototype (?:quickly|fast|first)|rapid prototyp\w*|weeks not months|days not months|save (?:development|dev|build|engineering) time|reduce development time)\b/i,
+    },
+    {
+        id: "standard-layout",
+        label: "Standard social app layout or white-label surface",
+        strength: "medium",
+        pattern: /\b(standard social|standard layout|standard feed|standard chat|standard profile|white[-\s]?label|basic styling|minimal customization|moderate customization|brand colors only)\b/i,
+    },
+    {
+        id: "uikit-customization-ladder",
+        label: "UIKit customization mode",
+        strength: "medium",
+        pattern: /\b(dynamic ui|component styling|fork and extend|forked ui\s?kit|fork the ui\s?kit|customi[sz]e the ui\s?kit)\b/i,
+    },
+];
+const REJECT_NEGATOR = "do not|don't|dont|won't|wont|can't|cant|cannot|avoid|skip|no|without|not|never";
+const REJECT_CONNECTOR = "to|use|uses|using|used|want|wants|wanting|adopt|adopts|adopting|leverage|leveraging|rely|relying|touch|build|building|go|going|be|been|with|on";
+const REJECT_UIKIT_NOUN = "(?:the\\s+)?(?:social\\.plus\\s+)?(?:ui\\s?kit|uikit)\\b";
+const REJECT_SKILL_LOOKAHEAD = "(?!\\s+(?:experience|expertise|knowledge|background|familiarity))";
+const REJECT_UIKIT_SOURCE = `\\b(?:${REJECT_NEGATOR})(?:\\s+(?:${REJECT_CONNECTOR}))*\\s+${REJECT_UIKIT_NOUN}${REJECT_SKILL_LOOKAHEAD}` +
+    `|\\b(?:instead of|rather than)(?:\\s+(?:${REJECT_CONNECTOR}))*\\s+${REJECT_UIKIT_NOUN}` +
+    `|\\b(?:anything|everything)\\s+but\\s+${REJECT_UIKIT_NOUN}`;
+const NEGATED_FROM_SCRATCH = /\b(?:not|never|avoid|don't|dont|do not|rather than|instead of)\b[\s\w,]{0,16}?\bfrom scratch\b/i;
+const NEGATED_STANDARD = /\b(?:not|never|avoid|don't|dont|do not|rather than|instead of)\b[\s\w,]{0,12}?\b(?:standard social|standard layout|standard feed|standard chat|standard profile|white[-\s]?label|basic styling|minimal customization|moderate customization)\b/i;
+const SDK_SIGNALS = [
+    {
+        id: "direct-sdk",
+        label: "Direct SDK implementation",
+        strength: "strong",
+        pattern: /\b(?:directly|direct|using|use|with|via|embed|embedding|integrate|integrating)\s+(?:the\s+)?(?:social\.plus\s+)?SDK\b|\b(?:the\s+)?(?:social\.plus\s+)?SDK\s+for\b|\bSDK[-\s]?owned\b|\bSDK[-\s]?custom\b/i,
+    },
+    {
+        id: "reject-uikit",
+        label: "Explicitly rejects UIKit or chooses SDK instead of UIKit",
+        strength: "strong",
+        pattern: new RegExp(REJECT_UIKIT_SOURCE, "i"),
+    },
+    {
+        id: "custom-ui",
+        label: "Custom UI or non-standard experience",
+        strength: "strong",
+        pattern: /\b(?:custom|bespoke|unique|fully[-\s]?custom|completely[-\s]?custom|totally[-\s]?(?:different|custom)|brand[-\s]?new|differentiated)\s+(?:(?:social|messaging|notification|community|chat|feed|profile|story|stories|comment|comments|user|group|channel|post|navigation|onboarding|discovery)\s+)?(?:ui|interface|experience)\b|\b(?:our|my|their|its|your)\s+own\s+(?:\w+\s+){0,2}?(?:component(?:\s+tree)?|components?|screens?|widgets?|ui)\b|\bnon[-\s]?standard (?:ui|layout|flow|experience)\b|\bpixel[-\s]?perfect\b/i,
+    },
+    {
+        id: "custom-flows",
+        label: "Custom user flows or interactions",
+        strength: "strong",
+        pattern: /\b(custom flows?|custom user flows?|custom interactions?|custom workflows?|unique flows?|bespoke flows?|special interaction)\b/i,
+    },
+    {
+        id: "full-control",
+        label: "Full control / design freedom",
+        strength: "strong",
+        pattern: /\b(full control|complete control|maximum flexibility|complete design freedom|full design freedom|build from scratch|hand[-\s]?rolled|from scratch)\b/i,
+    },
+    {
+        id: "deep-app-integration",
+        label: "Deep existing-app integration",
+        strength: "medium",
+        pattern: /\b(deeply integrate|existing app flow|existing navigation|custom backend|server[-\s]?to[-\s]?server|non[-\s]?standard platform|advanced technical requirements)\b/i,
+    },
+];
+const SOURCE_EVIDENCE = [
+    "social.plus UIKit docs: prebuilt UI components, quick launch, and minimal/moderate customization paths.",
+    "social.plus SDK docs: custom experiences, unique user flows, complete design freedom, and existing-app integration.",
+];
+export function recommendSolutionPath(request, answers = {}) {
+    const text = typeof request === "string" ? request : "";
+    const explicitAnswer = normalizeSolutionPathAnswer(answers?.solution_path);
+    const sdkSignals = collectSignals(text, SDK_SIGNALS).filter((signal) => {
+        if (signal.id !== "full-control" || !/scratch/i.test(signal.matched)) {
+            return true;
+        }
+        return !NEGATED_FROM_SCRATCH.test(text);
+    });
+    const negativeUIKitSignals = sdkSignals.filter((signal) => signal.id === "reject-uikit");
+    let uikitScanText = text;
+    if (negativeUIKitSignals.length > 0) {
+        uikitScanText = text.replace(new RegExp(REJECT_UIKIT_SOURCE, "gi"), " ");
+    }
+    let uikitSignals = collectSignals(uikitScanText, UIKIT_SIGNALS).filter((signal) => {
+        if (signal.id !== "standard-layout") {
+            return true;
+        }
+        return !NEGATED_STANDARD.test(text);
+    });
+    if (negativeUIKitSignals.length > 0 && !uikitSignals.some((signal) => signal.strength === "strong")) {
+        uikitSignals = [];
+    }
+    if (explicitAnswer) {
+        return guidanceFor({
+            recommendation: explicitAnswer,
+            confidence: "high",
+            uikitSignals,
+            sdkSignals,
+            answered: explicitAnswer,
+        });
+    }
+    const hasStrongUIKit = uikitSignals.some((signal) => signal.strength === "strong");
+    const hasStrongSdk = sdkSignals.some((signal) => signal.strength === "strong");
+    if (uikitSignals.length > 0 && sdkSignals.length > 0) {
+        return guidanceFor({
+            recommendation: "needs-decision",
+            confidence: hasStrongUIKit || hasStrongSdk ? "medium" : "low",
+            uikitSignals,
+            sdkSignals,
+        });
+    }
+    if (uikitSignals.length > 0) {
+        return guidanceFor({
+            recommendation: "uikit",
+            confidence: hasStrongUIKit ? "high" : "medium",
+            uikitSignals,
+            sdkSignals,
+        });
+    }
+    if (sdkSignals.length > 0) {
+        return guidanceFor({
+            recommendation: "sdk",
+            confidence: hasStrongSdk ? "high" : "medium",
+            uikitSignals,
+            sdkSignals,
+        });
+    }
+    return guidanceFor({
+        recommendation: "sdk",
+        confidence: "medium",
+        uikitSignals,
+        sdkSignals,
+    });
+}
+function guidanceFor(args) {
+    const decision = {
+        requiredBeforeHandRolledUi: !args.answered && (args.recommendation === "uikit" || args.recommendation === "hybrid" || args.recommendation === "needs-decision"),
+        question: "Should this build use social.plus UIKit components, a direct SDK implementation, or a hybrid path?",
+        options: [
+            "uikit: use social.plus UIKit for standard social surfaces and theme/customize it",
+            "sdk: build the experience directly with the social.plus SDK",
+            "hybrid: use UIKit for standard surfaces and SDK/custom code for differentiated app-layer behavior",
+        ],
+    };
+    if (args.recommendation === "uikit") {
+        return {
+            recommendation: "uikit",
+            confidence: args.confidence,
+            summary: args.answered === "uikit"
+                ? "The customer explicitly selected the UIKit path. Confirm scope, then use social.plus UIKit as the primary implementation artifact instead of hand-rolling standard social UI."
+                : "The request sounds UIKit-shaped: favor social.plus UIKit for the standard social surface, then customize within the UIKit theming/component model before considering direct SDK UI.",
+            answerId: "solution_path",
+            signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+            decision,
+            implementationGuidance: [
+                "Confirm `solution_path=uikit` before the host agent hand-rolls standard feed, chat, profile, comments, community, or story UI.",
+                "Use UIKit installation, authentication, customization, and platform build guidance as the implementation source of truth.",
+                "Keep Vise's existing SDK setup, secrets, region, auth, build, and project-sensor guidance around the UIKit integration.",
+                "Do not claim deterministic compliance for UIKit internals hidden outside the customer repo; validate customer wiring, configuration, custom code, and local build evidence.",
+                "Keep design conformance advisory: use Dynamic UI, component styling, or fork-and-extend based on the customer's customization need.",
+            ],
+            evidence: SOURCE_EVIDENCE,
+            advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+        };
+    }
+    if (args.recommendation === "needs-decision") {
+        return {
+            recommendation: "needs-decision",
+            confidence: args.confidence,
+            summary: args.answered === "hybrid"
+                ? "The customer selected a hybrid path. Treat UIKit as the default for standard surfaces and use direct SDK/custom code only for the differentiated behavior."
+                : "The request contains both UIKit-shaped speed/prebuilt signals and SDK-shaped custom-control signals. Ask for the solution path before the agent starts UI implementation.",
+            answerId: "solution_path",
+            signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+            decision,
+            implementationGuidance: [
+                "Resolve `solution_path` before hand-rolling standard social UI.",
+                "Choose UIKit when the standard social surface can be themed or lightly customized.",
+                "Choose SDK when the requested workflow, layout, or interaction model is materially different from UIKit's component model.",
+                "Choose hybrid when UIKit can cover baseline social surfaces and SDK/custom code is needed for app-specific extensions.",
+                "Do not claim deterministic compliance for UIKit internals hidden outside the customer repo; validate customer wiring, configuration, custom code, and local build evidence.",
+            ],
+            evidence: SOURCE_EVIDENCE,
+            advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+        };
+    }
+    if (args.recommendation === "hybrid") {
+        return {
+            recommendation: "hybrid",
+            confidence: args.confidence,
+            summary: "The customer selected a hybrid path. Treat UIKit as the default for standard surfaces and use direct SDK/custom code only for the differentiated behavior.",
+            answerId: "solution_path",
+            signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+            decision,
+            implementationGuidance: [
+                "Use UIKit for standard social surfaces that fit its component and customization model.",
+                "Use direct SDK/custom code only for differentiated app-layer behavior, custom profile/discovery surfaces, or non-standard flows.",
+                "Keep the handoff explicit in the implementation summary: name which surfaces are UIKit-owned and which are SDK/customer-owned.",
+                "Do not claim deterministic compliance for UIKit internals hidden outside the customer repo; validate customer wiring, configuration, custom code, and local build evidence.",
+            ],
+            evidence: SOURCE_EVIDENCE,
+            advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+        };
+    }
+    return {
+        recommendation: "sdk",
+        confidence: args.confidence,
+        summary: args.answered === "sdk"
+            ? "The customer explicitly selected the direct SDK path. Continue with the normal Vise SDK integration harness."
+            : args.sdkSignals.some((signal) => signal.id === "reject-uikit")
+                ? "The request explicitly rejects UIKit or chooses the SDK instead of UIKit, so the normal SDK-first Vise harness is the safer fit."
+                : args.sdkSignals.length > 0
+                    ? "The request asks for custom control, unique flows, or deep app integration, so the normal SDK-first Vise harness is the safer fit."
+                    : "No strong UIKit fast-launch/prebuilt-surface signal was detected, so Vise keeps the existing SDK-first integration flow.",
+        answerId: "solution_path",
+        signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+        decision,
+        implementationGuidance: [
+            "Use the normal Vise SDK integration flow: plan, answer intake, initialize the compliance contract, implement, check, and run sensors.",
+            "If the customer later asks for a standard prebuilt social surface or quick-launch MVP, re-plan with `--answer solution_path=uikit` or a UIKit-specific request.",
+        ],
+        evidence: SOURCE_EVIDENCE,
+        advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+    };
+}
+function collectSignals(request, signals) {
+    return signals.flatMap((signal) => {
+        const match = request.match(signal.pattern);
+        if (!match?.[0]) {
+            return [];
+        }
+        return [{
+                id: signal.id,
+                label: signal.label,
+                strength: signal.strength,
+                matched: match[0],
+            }];
+    });
+}
+const REJECT_UIKIT_IN_ANSWER = new RegExp(REJECT_UIKIT_SOURCE, "i");
+const REJECT_HYBRID_IN_ANSWER = /\b(?:not|no|without|avoid|don't|dont|do not|never|rather than|instead of)\b[\s\w,]{0,12}?\bhybrid\b/;
+function normalizeSolutionPathAnswer(answer) {
+    const normalized = (typeof answer === "string" ? answer : "").trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (/\bhybrid\b/.test(normalized) && !REJECT_HYBRID_IN_ANSWER.test(normalized)) {
+        return "hybrid";
+    }
+    if (REJECT_UIKIT_IN_ANSWER.test(normalized)) {
+        return "sdk";
+    }
+    if (/\b(ui\s?kit|uikit)\b/.test(normalized)) {
+        return "uikit";
+    }
+    if (/\bsdk\b/.test(normalized)) {
+        return "sdk";
+    }
+    return undefined;
+}