@amityco/social-plus-vise 1.2.0 → 1.4.0

package/dist/requestReadiness.js

@@ -0,0 +1,99 @@
+export function clarifyDimensions(input) {
+    const dims = [];
+    if (!input.platformDetected) {
+        dims.push("platform");
+    }
+    if (input.outcome === "unknown" && !input.creativeSelected && !input.uikitGuidedUnknown) {
+        dims.push("experience");
+    }
+    return dims;
+}
+const PLATFORM_QUESTION = {
+    dimension: "platform",
+    ask: "No social.plus SDK platform was detected in this repo. Which target app/platform should receive social.plus, and where is that app shell?",
+    why: "Vise validates real SDK code, not an abstract idea. A static or platform-unknown repo must be scaffolded or pointed at a real web TypeScript/React, React Native, Flutter, iOS, or Android surface before implementation can be verified.",
+    requiredDecision: "Target platform plus app/surface path to build in.",
+    options: [
+        "web TypeScript/React: package.json with @amityco/ts-sdk and a route/component to mount",
+        "React Native: app package plus screen/component path",
+        "Flutter: pubspec.yaml app plus widget/route path",
+        "iOS: Xcode/Swift package app plus view/module path",
+        "Android: Gradle app module plus Activity/Fragment/Compose screen path",
+    ],
+    answerFormat: "Tell the agent the target platform and app shell path; scaffold the platform first when it does not exist, then re-run `vise inspect` and `vise plan`.",
+    examples: [
+        "web TypeScript/React in apps/web, mount at /social",
+        "Android app module :app, add the surface to MainActivity/Compose navigation",
+        "Flutter app in mobile/, add the surface under lib/features/social/",
+    ],
+    doNot: [
+        "Do not paste SDK code into a static site before a platform has been chosen.",
+        "Do not assume web just because package.json is absent.",
+    ],
+};
+const EXPERIENCE_QUESTION = {
+    dimension: "experience",
+    routeTo: "vise creative",
+    ask: "The request did not name a buildable social experience. Which EI experience should be selected, or is this a no-fit for the current catalog?",
+    why: "A broad request like 'add social.plus features' needs a product direction before planning. Vise must not keyword-guess the experience; the host agent should use the EI candidate menu as advisory data and show the choice before accepting one.",
+    requiredDecision: "Selected EI experience variant, or explicit no-fit.",
+    answerFormat: "Run `vise creative . --request \"<intent>\"`, present the EI choice block, then run `vise creative accept . --variant <id|none> --rationale \"<why>\" --confidence high|medium|low`.",
+    examples: [
+        "community-first because the app needs topic/member spaces before feeds and chat",
+        "discovery-first because the core goal is browsing and finding social content",
+        "none because none of the surfaced candidates match the requested product motion",
+    ],
+    doNot: [
+        "Do not accept a variant before showing the recommendation, alternatives, tradeoffs, expected surfaces, and no-fit option.",
+        "Do not infer the experience from keywords alone.",
+    ],
+};
+export function clarifyGuidance(dims) {
+    if (dims.length === 0) {
+        return undefined;
+    }
+    const resolve = [];
+    if (dims.includes("platform")) {
+        resolve.push(PLATFORM_QUESTION);
+    }
+    if (dims.includes("experience")) {
+        resolve.push(EXPERIENCE_QUESTION);
+    }
+    const reasons = [
+        dims.includes("platform") ? "no SDK platform is detected" : undefined,
+        dims.includes("experience") ? "no buildable social feature is classified" : undefined,
+    ].filter((reason) => Boolean(reason));
+    const decisionChecklist = [
+        dims.includes("platform") ? "target platform/app shell and mount route or screen" : undefined,
+        dims.includes("experience") ? "selected EI experience, alternatives considered, or explicit no-fit" : undefined,
+        "after the request is classifiable: social.plus region (US/EU/SG), API-key env/config placeholder, identity source, feature scope, and route/surface placement",
+        "if the request is prebuilt/standard UI shaped: explicit solution_path=sdk|uikit|hybrid before hand-rolling UI",
+    ].filter((item) => Boolean(item));
+    const nextStepParts = [
+        "Stop before editing code and resolve `clarify.resolve` with the user",
+        dims.includes("experience") ? "run `vise creative`, present the EI choice block, then accept the chosen experience with rationale/confidence" : undefined,
+        dims.includes("platform") ? "confirm + scaffold the target platform/app shell (do not invent an integration on an undetected platform)" : undefined,
+        "then re-run `vise plan`.",
+    ].filter((part) => Boolean(part));
+    return {
+        why: `This request is not yet specific enough to produce a buildable plan (${reasons.join("; ")}).`,
+        resolve,
+        decisionChecklist,
+        unattended: {
+            status: "blocked",
+            mode: "handoff-required",
+            reason: "Blocking clarification is required before implementation can be planned safely.",
+            instruction: "If the user is not available, stop and return the clarify.resolve questions plus decisionChecklist. Do not choose defaults, scaffold speculative code, or proceed to init/build.",
+            allowedActions: [
+                "read-only inspect/plan output",
+                "run `vise creative` only to prepare an EI choice menu when the experience dimension is unresolved",
+            ],
+            resumeWhen: [
+                "the target platform/app shell is selected and scaffolded when required",
+                "the EI experience or no-fit decision is selected when required",
+                "a fresh `vise plan` no longer returns this clarify block",
+            ],
+        },
+        nextStep: nextStepParts.join(" — "),
+    };
+}