@amityco/social-plus-vise 1.1.0 → 1.2.0

package/dist/tools/sensors.js

@@ -112,7 +112,7 @@ async function runSensor(cwd, sensor, timeoutMs) {
                 durationMs: Date.now() - startedAt,
                 stdout: truncate(stdout),
                 stderr: truncate(stderr),
-                reason: `Timed out after ${timeoutMs}ms.`,
+                reason: sensor.timeoutReason ?? `Timed out after ${timeoutMs}ms.`,
             });
         }, timeoutMs);
         child.stdout?.on("data", (chunk) => {

package/dist/uikitCustomization.js

@@ -0,0 +1,370 @@
+const SIGNALS = [
+    {
+        id: "dynamic-ui",
+        level: "dynamic-ui",
+        label: "Minimal, server-driven brand or theme updates",
+        strength: "strong",
+        pattern: /\b(dynamic ui|remote config|network config|syncNetworkConfig|without (?:an? )?(?:app )?(?:release|update|rebuild)|real[-\s]?time theme|brand colors?|theme tokens?|palette|console[-\s]?driven)\b/i,
+    },
+    {
+        id: "component-styling",
+        level: "component-styling",
+        label: "Config-driven page/component/element styling",
+        strength: "strong",
+        pattern: /\b(component styling|config\.json|uikit\.config|customizations?\s+(?:map|key|path|object)|page\/component\/element|page id|component id|element id|preferred_theme|primary_color|exclu(?:de|des|ded|ding|sion|sions)|(?:hide|remove)(?!\s+(?:\w+\s+){0,2}?(?:members?|users?|people|participants?|admins?|accounts?|followers?))|button text|icons?|dark mode|light mode|feature flags?|reactions?)\b/i,
+    },
+    {
+        id: "localization",
+        level: "localization",
+        label: "Localized strings, copy, or terminology",
+        strength: "strong",
+        pattern: /\b(locali[sz](?:e|es|ed|ing|ation|ations)?|translat(?:e|es|ed|ing|ion|ions)|locale|(?<!\b(?:swift|kotlin|java|javascript|typescript|dart|objective[-\s]?c|programming|coding|markup|query|design|visual|brand|domain|ubiquitous)\s)language|strings?|copywriting|copy text|copy changes|wording|rename|setLocale|setOverrides|locale bundle|resource overlay|StringProvider|AmityStringProvider)\b/i,
+    },
+    {
+        id: "behavior-overrides",
+        level: "behavior-overrides",
+        label: "Navigation, route, click, or tap behavior override",
+        strength: "strong",
+        pattern: /\b(behavio[u]?r|navigation|route|deep link|on click|onclick|on tap|tap action|click action|clicks?|taps?|presses?|run custom code|custom code|custom handler|analytics (?:hook|callback|event|events|tracking|integration)|track(?:ing)? events?|permission gate|custom action|pageBehavior|BehaviourProvider|AmityPageRenderer)\b/i,
+    },
+    {
+        id: "fork-and-extend",
+        level: "fork-and-extend",
+        label: "Source-level UIKit extension",
+        strength: "strong",
+        pattern: /\b(fork(?: and extend)?|forked ui\s?kit|source code|own version|modify ui\s?kit source|custom layout|new component|internal view composition|custom data flow|logic injection|maintain upstream)\b|\b(?:restructure|rebuild|re[-\s]?architect|rework|overhaul)\s+(?:the\s+)?(?:\w+\s+){0,3}?(?:layout|structure|hierarchy|composition|thread)\b|\b(?:ui\s?kit|uikit)\s+(?:(?:doesn'?t|does not|can'?t|cannot|won'?t)\s+(?:have|provide|support|offer|include)|lacks?|is missing|has no)\b/i,
+    },
+    {
+        id: "sdk-custom-ui",
+        level: "sdk-custom-ui",
+        label: "Custom UI beyond UIKit's customization model",
+        strength: "strong",
+        pattern: /\b(totally different ui|brand[-\s]?new ui|bespoke ui|unique ui|complete design freedom|build from scratch|hand[-\s]?rolled)\b/i,
+    },
+    {
+        id: "basic-theme",
+        level: "dynamic-ui",
+        label: "Basic brand styling",
+        strength: "medium",
+        pattern: /\b(theme|theming|brand|colors?|style|styling|look and feel)\b/i,
+    },
+    {
+        id: "specific-element",
+        level: "component-styling",
+        label: "Specific UIKit element/page/component tweak",
+        strength: "medium",
+        pattern: /\b(feed header|composer button|story tab|comment tray|community card|profile header|share button|close button|target page|story_page|community_profile_page|global_feed_component)\b/i,
+    },
+];
+const DOCS = [
+    "https://learn.social.plus/uikit/overview",
+    "https://learn.social.plus/uikit/customization/dynamic-ui",
+    "https://learn.social.plus/uikit/customization/component-styling",
+    "https://learn.social.plus/uikit/customization/localization",
+    "https://learn.social.plus/uikit/getting-started/installation",
+];
+const SOURCE_EVIDENCE = [
+    "social.plus UIKit overview: minimal customization uses Dynamic UI, moderate customization uses Component Styling, advanced customization uses Fork and Extend, and totally different UI should use SDK/API directly.",
+    "social.plus Dynamic UI docs: use Console-managed configuration for low-risk brand/theme changes and sync network config in the client.",
+    "social.plus Component Styling docs: use config path overrides at page/component/element level, with exclusions and behavior overrides for supported navigation/action changes.",
+    "social.plus Localization docs: override strings or provide locale bundles while preserving English fallback behavior.",
+    "Local UIKit source study: Web provider exposes configs, pageBehavior, syncNetworkConfig, and localization props; React Native, Android, and Flutter repos use config files plus behavior managers/providers.",
+];
+const FEATURE_CAPABILITY = /\b(livestream(?:ing)?|live[-\s]?stream(?:ing)?|video call(?:ing|s)?|voice call(?:ing|s)?|video chat|broadcast(?:ing)?|go live)\b/i;
+export function recommendUIKitCustomization(args) {
+    const answers = args.answers ?? {};
+    const request = typeof args.request === "string" ? args.request : "";
+    const rawCustomizationAnswer = typeof answers.uikit_customization === "string" ? answers.uikit_customization.trim() : "";
+    const explicitAnswer = normalizeCustomizationAnswer(rawCustomizationAnswer);
+    const unrecognizedExplicitAnswer = rawCustomizationAnswer.length > 0 && !explicitAnswer;
+    const matches = collectSignals(request);
+    const grouped = groupedSignals(matches);
+    const hasCustomizationSignal = matches.length > 0;
+    const sdkCustomUiOnly = hasCustomizationSignal && matches.every((match) => match.level === "sdk-custom-ui");
+    const solutionNeedsUIKitAttention = args.solutionPath?.recommendation === "uikit" ||
+        args.solutionPath?.recommendation === "hybrid" ||
+        args.solutionPath?.recommendation === "needs-decision";
+    if (!explicitAnswer && args.solutionPath?.recommendation === "sdk") {
+        return undefined;
+    }
+    if (!explicitAnswer && !unrecognizedExplicitAnswer && (!hasCustomizationSignal || sdkCustomUiOnly) && !solutionNeedsUIKitAttention) {
+        return undefined;
+    }
+    const featureCapabilityOnly = !explicitAnswer && !unrecognizedExplicitAnswer && !hasCustomizationSignal && FEATURE_CAPABILITY.test(request);
+    const matchedLevels = levelsFromMatches(matches);
+    const answeredLevel = explicitAnswer;
+    const recommendedLevel = answeredLevel
+        ?? (unrecognizedExplicitAnswer || featureCapabilityOnly ? "needs-decision" : chooseRecommendedLevel(matches, args.solutionPath));
+    const additionalLevels = matchedLevels.filter((level) => level !== recommendedLevel);
+    const status = statusFor(recommendedLevel, matchedLevels, args.solutionPath, explicitAnswer, unrecognizedExplicitAnswer);
+    const confidence = confidenceFor({ explicitAnswer, matches, recommendedLevel, status, solutionPath: args.solutionPath, unrecognizedExplicitAnswer });
+    const platformGuidance = platformGuidanceFor(args.platform);
+    return {
+        status,
+        recommendedLevel,
+        confidence,
+        summary: summaryFor(recommendedLevel, status, explicitAnswer, additionalLevels),
+        answerId: "uikit_customization",
+        signals: grouped,
+        additionalLevels,
+        decision: {
+            requiredBeforeCustomization: status === "needs-decision" || recommendedLevel === "fork-and-extend" || recommendedLevel === "sdk-custom-ui",
+            question: "Which UIKit customization route should this customer use?",
+            options: [
+                "dynamic-ui: server-driven brand/theme changes without app releases",
+                "component-styling: config.json/uikit.config.json page, component, element, theme, exclude, and feature-flag overrides",
+                "localization: locale bundles, string overrides, or resource overlays for copy/language changes",
+                "behavior-overrides: supported navigation, route, click, tap, analytics, or permission behavior hooks",
+                "fork-and-extend: modify UIKit source while owning an upstream update strategy",
+                "sdk-custom-ui: leave UIKit for direct SDK/API when the desired UI is materially different",
+                "hybrid: combine UIKit configuration with SDK/custom code for differentiated app-layer behavior",
+            ],
+        },
+        implementationGuidance: implementationGuidanceFor(recommendedLevel, additionalLevels),
+        platformGuidance,
+        docs: DOCS,
+        evidence: SOURCE_EVIDENCE,
+        advisoryOnly: "This is advisory UIKit customization guidance. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+    };
+}
+function collectSignals(request) {
+    return SIGNALS.flatMap((signal) => {
+        const match = request.match(signal.pattern);
+        if (!match?.[0]) {
+            return [];
+        }
+        return [{
+                id: signal.id,
+                level: signal.level,
+                label: signal.label,
+                strength: signal.strength,
+                matched: match[0],
+            }];
+    });
+}
+function groupedSignals(matches) {
+    return {
+        dynamicUi: matches.filter((match) => match.level === "dynamic-ui"),
+        componentStyling: matches.filter((match) => match.level === "component-styling"),
+        localization: matches.filter((match) => match.level === "localization"),
+        behaviorOverrides: matches.filter((match) => match.level === "behavior-overrides"),
+        forkAndExtend: matches.filter((match) => match.level === "fork-and-extend"),
+        sdkCustomUi: matches.filter((match) => match.level === "sdk-custom-ui"),
+    };
+}
+function levelsFromMatches(matches) {
+    return [
+        "dynamic-ui",
+        "component-styling",
+        "localization",
+        "behavior-overrides",
+        "fork-and-extend",
+        "sdk-custom-ui",
+    ].filter((level) => matches.some((match) => match.level === level));
+}
+function chooseRecommendedLevel(matches, solutionPath) {
+    const matchedLevels = levelsFromMatches(matches);
+    const strongLevels = levelsFromMatches(matches.filter((match) => match.strength === "strong"));
+    const pool = strongLevels.length > 0 ? strongLevels : matchedLevels;
+    if (pool.includes("sdk-custom-ui")) {
+        return "sdk-custom-ui";
+    }
+    if (pool.includes("fork-and-extend")) {
+        return "fork-and-extend";
+    }
+    if (pool.includes("behavior-overrides")) {
+        return "behavior-overrides";
+    }
+    if (pool.includes("component-styling")) {
+        return "component-styling";
+    }
+    if (pool.includes("dynamic-ui")) {
+        return "dynamic-ui";
+    }
+    if (pool.includes("localization")) {
+        return "localization";
+    }
+    if (solutionPath?.recommendation === "needs-decision") {
+        return "needs-decision";
+    }
+    return "dynamic-ui";
+}
+function statusFor(recommendedLevel, matchedLevels, solutionPath, explicitAnswer, unrecognizedExplicitAnswer) {
+    if (explicitAnswer) {
+        return "ready";
+    }
+    if (unrecognizedExplicitAnswer) {
+        return "needs-decision";
+    }
+    if (solutionPath?.recommendation === "needs-decision") {
+        return "needs-decision";
+    }
+    if (recommendedLevel === "needs-decision") {
+        return "needs-decision";
+    }
+    if (matchedLevels.includes("sdk-custom-ui") && matchedLevels.some((level) => level !== "sdk-custom-ui")) {
+        return "needs-decision";
+    }
+    return "ready";
+}
+function confidenceFor(args) {
+    if (args.explicitAnswer) {
+        return "high";
+    }
+    if (args.unrecognizedExplicitAnswer) {
+        return "low";
+    }
+    if (args.matches.some((match) => match.strength === "strong")) {
+        return args.status === "needs-decision" ? "medium" : "high";
+    }
+    if (args.solutionPath?.recommendation === "uikit" && args.recommendedLevel === "dynamic-ui") {
+        return "medium";
+    }
+    return "low";
+}
+function summaryFor(recommendedLevel, status, explicitAnswer, additionalLevels) {
+    if (explicitAnswer === "hybrid") {
+        return "The customer selected a hybrid UIKit customization path. Combine UIKit configuration or behavior hooks for standard surfaces with SDK/custom code for differentiated app-layer behavior.";
+    }
+    if (status === "needs-decision") {
+        return "The request crosses UIKit customization boundaries. Decide whether to stay within UIKit configuration/behavior hooks, fork UIKit, or build the custom surface directly with SDK/API.";
+    }
+    const suffix = additionalLevels.length > 0
+        ? ` Also account for ${additionalLevels.map(labelForLevel).join(", ")}.`
+        : "";
+    switch (recommendedLevel) {
+        case "dynamic-ui":
+            return `Use Dynamic UI for low-risk brand/theme changes that should be updated through configuration rather than app releases.${suffix}`;
+        case "component-styling":
+            return `Use Component Styling for config-driven page, component, element, theme, exclude, reaction, or feature-flag overrides while staying inside UIKit.${suffix}`;
+        case "localization":
+            return `Use UIKit localization for copy, terminology, locale, and string override goals while preserving default fallback behavior.${suffix}`;
+        case "behavior-overrides":
+            return `Use UIKit behavior overrides for supported navigation, route, click, tap, analytics, or permission behavior changes.${suffix}`;
+        case "fork-and-extend":
+            return `Use Fork and Extend only when the customer accepts source ownership and an upstream update strategy.${suffix}`;
+        case "sdk-custom-ui":
+            return `Use direct SDK/API custom UI when the desired experience is materially outside UIKit's configuration, behavior, and fork-friendly model.${suffix}`;
+        case "hybrid":
+            return `Use a hybrid UIKit + SDK route when standard surfaces can stay in UIKit but differentiated behavior belongs in customer-owned SDK/custom code.${suffix}`;
+        case "needs-decision":
+            return "Decide the UIKit customization route before implementation.";
+    }
+}
+function implementationGuidanceFor(recommendedLevel, additionalLevels) {
+    const shared = [
+        "Start with the lowest UIKit customization level that satisfies the customer goal; escalate only when the requested change cannot be expressed there.",
+        "Keep customer-owned configuration, behavior overrides, locale bundles, and fork deltas explicit so future UIKit upgrades are reviewable.",
+        "Validate the host app build and UX manually after UIKit customization; Vise compliance still covers customer wiring and deterministic SDK/config evidence, not hidden UIKit internals.",
+    ];
+    const levelGuidance = {
+        "dynamic-ui": [
+            "For Dynamic UI, configure brand/theme values in Console or network config, enable the client sync hook where supported, test launch/resume refresh, and verify cached fallback behavior offline.",
+        ],
+        "component-styling": [
+            "For Component Styling, edit the UIKit config file with page/component/element paths, keep wildcard overrides broad only when intentional, avoid structural exclusions that break usability, and test light and dark themes.",
+        ],
+        localization: [
+            "For Localization, use locale bundles, resource overlays, or string override APIs; keep placeholders intact and rely on default English fallback for untranslated keys.",
+        ],
+        "behavior-overrides": [
+            "For Behavior Overrides, override only the specific navigation/action method needed and leave default behavior in place for everything else.",
+        ],
+        "fork-and-extend": [
+            "For Fork and Extend, fork the UIKit source, document every customer delta, keep upstream merge strategy visible, and run the UIKit sample/build before integrating the fork into the customer app.",
+        ],
+        "sdk-custom-ui": [
+            "For SDK Custom UI, switch back to the SDK-first Vise flow and use UIKit only as reference material unless the customer explicitly chooses a hybrid path.",
+        ],
+        hybrid: [
+            "For Hybrid, use UIKit configuration or behavior hooks for standard social surfaces and direct SDK/custom code only for differentiated app-layer behavior.",
+        ],
+        "needs-decision": [
+            "For mixed requests, resolve whether the team accepts UIKit constraints before editing UI code.",
+        ],
+    };
+    return [
+        ...shared,
+        ...levelGuidance[recommendedLevel],
+        ...additionalLevels.flatMap((level) => levelGuidance[level]),
+    ];
+}
+function platformGuidanceFor(platform) {
+    const normalized = (platform ?? "").toLowerCase();
+    if (normalized.includes("react-native")) {
+        return [
+            "React Native UIKit: pass `uikit.config.json` through `AmityUiKitProvider configs`, use `BehaviourProvider`/`behaviour` for runtime navigation overrides, and use `AmityPageRenderer` when embedding standalone pages.",
+            "React Native source anchors: `Amity-Social-UIKit-React-Native-CLI-OpenSource/Onboarding.md`, `src/core/providers/AmityUIKitProvider.tsx`, `src/social/providers/BehaviourProvider.tsx`, and `src/social/enums/enumUIKitID.ts`.",
+        ];
+    }
+    if (normalized.includes("android")) {
+        return [
+            "Android UIKit: customize `common/src/main/assets/config.json`, set behavior through `AmityUIKit4Manager.behavior`/`AmityUIKit4Behaviour`, and use the string providers or resource overlays for localization.",
+            "Android source anchors: `Amity-Social-Cloud-UIKit-Android/common/src/main/assets/config.json`, `AmityUIKit4Behaviour.kt`, sample customization behavior files, and `LOCALIZATION_GUIDE.md`.",
+        ];
+    }
+    if (normalized.includes("flutter") || normalized.includes("dart")) {
+        return [
+            "Flutter UIKit: customize the packaged config asset, rely on `ConfigRepository` path/wildcard resolution, and assign behavior overrides through `AmityUIKit4Manager.behavior` where supported.",
+            "Flutter source anchors: `Amity-Social-Cloud-UIKit-Flutter/assets/config/config.json`, `lib/v4/core/config_repository.dart`, `uikit_behavior.dart`, and the behavior examples in `example/lib/main.dart`.",
+        ];
+    }
+    if (normalized.includes("ios") || normalized.includes("swift")) {
+        return [
+            "iOS UIKit: use the official Dynamic UI, Component Styling, Localization, behavior override, and fork guidance; the local UIKit source snapshot used for this research did not include an iOS repo.",
+        ];
+    }
+    return [
+        "Web/TypeScript UIKit: pass local config through `AmityUIKitProvider configs`, enable `syncNetworkConfig` for Dynamic UI, pass `pageBehavior` for navigation/action overrides, and use the `localization` prop for locale bundles or string overrides.",
+        "Web source anchors: `Amity-Social-Cloud-UIKit-Web/readme.md`, `src/v4/core/providers/AmityUIKitProvider.tsx`, `src/v4/core/providers/CustomizationProvider`, `src/v4/core/providers/PageBehaviorProvider.tsx`, and `src/v4/constants/customization.ts`.",
+    ];
+}
+function labelForLevel(level) {
+    switch (level) {
+        case "dynamic-ui":
+            return "Dynamic UI";
+        case "component-styling":
+            return "Component Styling";
+        case "localization":
+            return "Localization";
+        case "behavior-overrides":
+            return "Behavior Overrides";
+        case "fork-and-extend":
+            return "Fork and Extend";
+        case "sdk-custom-ui":
+            return "SDK Custom UI";
+        case "hybrid":
+            return "Hybrid";
+    }
+}
+function normalizeCustomizationAnswer(raw) {
+    const normalized = (typeof raw === "string" ? raw : "").trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (/\bhybrid\b|\bmixed\b|\bboth\b/.test(normalized)) {
+        return "hybrid";
+    }
+    if (/\bsdk\b|\bcustom ui\b|\bfrom scratch\b|\bapi\b/.test(normalized)) {
+        return "sdk-custom-ui";
+    }
+    if (/\bfork\b|\bextend\b(?!\s+(?:the\s+)?(?:theme|brand|colou?rs?|styling|palette|look))|\bsource\b(?!\s+(?:the\s+)?(?:brand|colou?rs?|theme|palette|styling|config))/.test(normalized)) {
+        return "fork-and-extend";
+    }
+    if (/\bbehavio[u]?r\b|\bnavigation\b|\broute\b|\btap\b|\bclick\b/.test(normalized)) {
+        return "behavior-overrides";
+    }
+    if (/\blocali[sz](?:e|es|ed|ing|ation|ations)?\b|\blocale\b|\bstrings?\b|\btranslat(?:e|es|ed|ing|ion|ions)\b|\blanguage\b/.test(normalized)) {
+        return "localization";
+    }
+    if (/\b(?:remote|network)\s+config\b|\bdynamic ui\b/.test(normalized)) {
+        return "dynamic-ui";
+    }
+    if (/\bcomponent\b|\bstyling\b|\bconfig\b|\bexclu(?:de|des|ded|ding|sion|sions)\b/.test(normalized)) {
+        return "component-styling";
+    }
+    if (/\bdynamic\b|\bminimal\b|\btheme\b|\bbrand\b/.test(normalized)) {
+        return "dynamic-ui";
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",