@amityco/social-plus-vise 1.2.0 → 1.4.0

package/dist/tools/creative.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { platformCapabilityAvailability } from "../capabilities.js";
+import { platformFeatureGapsForObjects } from "../outcomes.js";
 import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
 import { inspectProject } from "./project.js";
@@ -195,27 +196,27 @@ export async function buildCreativeBrief(options) {
         candidateSolutions: candidates,
         selectionGuidance: {
             mode: "agent-grounded-selection",
-            instruction: "You (the driving agent) choose the best-fitting variant by reasoning over candidateSolutions and the request. Use each candidate's `description` and `whenToChoose` (self-describing selecting signals) to discriminate between close variants — match the signals present in the request to the variant whose `whenToChoose` they satisfy. The listed order and the `fallbackDefault` flag are advisory keyword-derived hints, not recommendations to follow — keyword matching can point at the wrong variant for off-keyword requests, so decide by semantic fit. Vise will validate (ground) your choice against the catalog; it does not infer the variant for you.",
+            instruction: "You (the driving agent) choose the best-fitting variant by reasoning over candidateSolutions and the request. Use each candidate's `description` and `whenToChoose` (self-describing selecting signals) to discriminate between close variants — match the signals present in the request to the variant whose `whenToChoose` they satisfy. Before accepting a variant, present an EI choice block to the user: recommended experience, 2-3 concrete request/project signals, 2-3 credible alternatives with when-to-choose/tradeoffs, expected blueprint surfaces/objects, and the no-fit option. Do not collapse EI into a one-sentence recommendation or accept before the choice is visible. The listed order and the `fallbackDefault` flag are advisory keyword-derived hints, not recommendations to follow — keyword matching can point at the wrong variant for off-keyword requests, so decide by semantic fit. Vise will validate (ground) your choice against the catalog; it does not infer the variant for you.",
             howToAccept: "vise creative accept <repoPath> --variant <candidate id> --rationale \"<one line, grounded in the request and catalog>\" --confidence high|medium|low",
             contract: {
                 variant: "A candidateSolutions id chosen by best fit to the request (not by listed order or the fallbackDefault flag).",
                 fallbackDefault: "One candidate carries fallbackDefault=true: the keyword top, used as the default ONLY when no agent makes a grounded selection. Do not defer to it; decide by fit.",
                 rationale: "Required: one line explaining, grounded in the request and the candidate's catalog fit, why this variant. A selection without a rationale is rejected.",
                 confidence: "high | medium | low. Use low when the request is vague or genuinely split between variants; low/missing confidence is recorded as a review signal, not a failure.",
-                noFit: "If no candidate genuinely fits the request, do not force one. Record the no-fit instead: `vise creative accept <repoPath> --variant none --rationale \"<what the catalog is missing>\" [--closest <nearest variant id>]`. This writes a local catalog-gap record for human review (it does not change the catalog or upload anything); it is a signal the catalog may need a new variant.",
+                noFit: "If no candidate genuinely fits the request, do not force one. Record the no-fit instead: `vise creative accept <repoPath> --variant none --rationale \"<what the catalog is missing>\" --confidence high|medium|low [--closest <nearest variant id>]`. This writes a local catalog-gap record for human review (it does not change the catalog or upload anything); it is a signal the catalog may need a new variant.",
             },
         },
         questions: [
             {
                 id: "preferred_solution",
-                question: "Which creative variant best fits this request, and why?",
+                question: "Which EI experience should be selected after presenting the recommendation, alternatives, tradeoffs, expected blueprint surfaces, and no-fit option?",
                 why: "Creative mode proposes product/UX directions. The driving agent selects the best-fitting variant and accepts it with a grounded rationale and confidence (see selectionGuidance); normal Vise planning starts only after a variant is accepted.",
                 required: true,
                 blocksImplementationWhenMissing: true,
                 options: candidates.map((candidate) => candidate.id),
             },
         ],
-        nextStep: "Choose the best-fitting variant for the request by reasoning over candidateSolutions (listed order is advisory), then accept it with a grounded rationale and confidence: `vise creative accept <repoPath> --variant <id> --rationale \"<why>\" --confidence high|medium|low`. Vise validates the selection against the catalog. If no candidate genuinely fits, record a no-fit instead of forcing a choice: `vise creative accept <repoPath> --variant none --rationale \"<what is missing>\"`.",
+        nextStep: "Present the EI choice block first: recommended experience, concrete fit signals, credible alternatives/tradeoffs, expected blueprint surfaces/objects, and no-fit option. Then choose the best-fitting variant by reasoning over candidateSolutions (listed order is advisory) and accept it with a grounded rationale and confidence: `vise creative accept <repoPath> --variant <id> --rationale \"<why>\" --confidence high|medium|low`. Vise validates the selection against the catalog. If no candidate genuinely fits, record a no-fit instead of forcing a choice: `vise creative accept <repoPath> --variant none --rationale \"<what is missing>\" --confidence high|medium|low`.",
     };
     if (options.rankingPreview === true) {
         brief.candidateRankingPreview = buildCandidateRankingPreview(brief);
@@ -242,12 +243,9 @@ export async function acceptCreativeVariant(options) {
     if (!selected) {
         throw new Error(`Creative variant "${variantId}" was not found in ${repoRelativePath(repoRoot, briefPath)}. Available variants: ${brief.candidateSolutions.map((candidate) => candidate.id).join(", ") || "(none)"}.`);
     }
-    let grounding;
-    if (options.rationale !== undefined || options.confidence !== undefined) {
-        grounding = groundSelection({ variantId, rationale: options.rationale, confidence: options.confidence }, brief.candidateSolutions.map((candidate) => candidate.id));
-        if (grounding.status === "rejected") {
-            throw new Error(`Grounded selection for "${variantId}" was rejected: ${grounding.signals.filter((signal) => signal.severity === "error").map((signal) => signal.message).join(" ")}`);
-        }
+    const grounding = groundSelection({ variantId, rationale: options.rationale, confidence: options.confidence }, brief.candidateSolutions.map((candidate) => candidate.id));
+    if (grounding.status === "rejected") {
+        throw new Error(`Grounded selection for "${variantId}" was rejected: ${grounding.signals.filter((signal) => signal.severity === "error").map((signal) => signal.message).join(" ")}`);
     }
     const selection = {
         schema_version: CREATIVE_SELECTION_SCHEMA_VERSION,
@@ -263,7 +261,7 @@ export async function acceptCreativeVariant(options) {
         },
         objective: brief.objective,
         selectedVariant: selected,
-        ...(grounding ? { grounding } : {}),
+        grounding,
         implementationContext: {
             planRequest: `${selected.title}: ${brief.request}`,
             surfaceHints: creativeSurfaceHints(selected),
@@ -560,9 +558,13 @@ async function feasibilityForVariant(variant, inspection) {
     if (outcomes.length === 0) {
         notes.push("No current Vise outcome maps directly to this variant yet; treat it as exploratory product guidance.");
     }
+    const objectGaps = platform === "unknown" ? [] : platformFeatureGapsForObjects(variant.experienceObjectIds, platform);
+    for (const { gap, objects } of objectGaps) {
+        notes.push(`References experience object(s) ${objects.join(", ")} not available in the ${platform} SDK (${gap.feature} — available on ${gap.availableOn.join("/")}). See platformAvailability; this variant is not buildable as specified on ${platform}.`);
+    }
     return {
         platform,
-        support: supportFor(outcomeResults, customObjectIds),
+        support: objectGaps.length > 0 ? "references-unavailable-objects" : supportFor(outcomeResults, customObjectIds),
         outcomes: outcomeResults,
         customObjectIds,
         notes,

package/dist/tools/debug.js

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
 import { objectInput, optionalBooleanField, stringField, textResult } from "../types.js";
 import { checkCompliance, rulesById } from "./compliance.js";
 import { inspectProject } from "./project.js";
@@ -23,48 +25,94 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
     if (errorMessage.includes("method not found") || errorMessage.includes("Unresolved reference")) {
         likelyCause = "Potential Version Mismatch: The codebase is using a newer API pattern against an older SDK version installed in the project.";
     }
+    const missingModuleMatch = /Cannot find module ['"]([^'"]+)['"]/.exec(errorMessage)
+        ?? (/\bMODULE_NOT_FOUND\b/.test(errorMessage) ? /['"]([^'"]+)['"]/.exec(errorMessage) : null);
+    const missingModulePkg = missingModuleMatch && missingModuleMatch[1] && !/^[./]/.test(missingModuleMatch[1])
+        ? missingModuleMatch[1]
+        : undefined;
     const correlatedRules = [];
     let checkResult = null;
     try {
         checkResult = await checkCompliance(repoPath);
         const rulesMap = await rulesById();
         for (const rule of checkResult.rules) {
+            const contractRuleId = rule.contractRuleId ?? rule.ruleId;
+            const ruleDef = rulesMap.get(contractRuleId);
+            const symptoms = ruleDef?.symptoms || [];
+            if (symptoms.length === 0 || !symptoms.some((s) => errorMessage.includes(s))) {
+                continue;
+            }
             if (rule.status === "deterministic-fail" || rule.status === "attestation-needed") {
-                const contractRuleId = rule.contractRuleId ?? rule.ruleId;
-                const ruleDef = rulesMap.get(contractRuleId);
-                const symptoms = ruleDef?.symptoms || [];
-                if (symptoms.some(s => errorMessage.includes(s))) {
-                    correlatedRules.push({
-                        ruleId: rule.ruleId,
-                        status: "failed",
-                        impact: `This rule is currently failing and its known symptoms match the crash log.`,
-                    });
-                }
+                correlatedRules.push({
+                    ruleId: rule.ruleId,
+                    status: "failed",
+                    impact: `This rule is currently failing and its known symptoms match the crash log.`,
+                });
             }
             else if (rule.status === "attested") {
-                const contractRuleId = rule.contractRuleId ?? rule.ruleId;
-                const ruleDef = rulesMap.get(contractRuleId);
-                const symptoms = ruleDef?.symptoms || [];
-                if (symptoms.some(s => errorMessage.includes(s))) {
-                    correlatedRules.push({
-                        ruleId: rule.ruleId,
-                        status: "attested",
-                        attestation: rule.attestation,
-                        impact: `Warning: This rule was attested as passing, but a matching runtime exception was detected. The custom implementation may be flawed.`,
-                    });
-                }
+                correlatedRules.push({
+                    ruleId: rule.ruleId,
+                    status: "attested",
+                    attestation: rule.attestation,
+                    impact: `Warning: This rule was attested as passing, but a matching runtime exception was detected. The custom implementation may be flawed.`,
+                });
+            }
+            else {
+                correlatedRules.push({
+                    ruleId: rule.ruleId,
+                    status: rule.status,
+                    impact: `This rule's known symptoms match the crash log even though its compliance status is "${rule.status}". The deterministic check did not catch this, so the failure is likely runtime-only or outside the sensor's reach — review the implementation.`,
+                });
             }
         }
     }
     catch (err) {
     }
-    if (!likelyCause && correlatedRules.length > 0) {
-        likelyCause = `The crash is likely caused by the non-compliant implementation of ${correlatedRules.map(r => r.ruleId).join(", ")}.`;
+    const failingCorrelated = correlatedRules.filter((r) => r.status === "failed" || r.status === "attested");
+    const moduleDiagnosis = missingModulePkg
+        ? (() => {
+            const projectRoot = path.resolve(repoPath);
+            const pkg = missingModulePkg;
+            if (!existsSync(path.join(projectRoot, "node_modules"))) {
+                return {
+                    cause: `Dependencies are not installed — node_modules is absent at ${projectRoot}, so "${pkg}" cannot be resolved. This is a setup/environment issue, not a code defect.`,
+                    hint: `Run \`npm install\` at the project root to install declared dependencies, then retry. If "${pkg}" is not yet a dependency, add it: \`npm install ${pkg}\`.`,
+                };
+            }
+            if (!existsSync(path.join(projectRoot, "node_modules", ...pkg.split("/")))) {
+                return {
+                    cause: `The module "${pkg}" is not present in node_modules, so it cannot be resolved. This is a missing-dependency issue, not a code defect.`,
+                    hint: `Install it at the project root: \`npm install ${pkg}\`, then retry. (If it should already be installed, delete node_modules and re-run \`npm install\`.)`,
+                };
+            }
+            return {
+                cause: `The module "${pkg}" could not be resolved at runtime even though it appears installed. Confirm it is declared in package.json and the install is intact.`,
+                hint: `Re-run \`npm install\` to repair the dependency tree; if "${pkg}" is missing from package.json, add it with \`npm install ${pkg}\`.`,
+            };
+        })()
+        : undefined;
+    let missingModuleHint;
+    let secondaryModuleNote;
+    if (!likelyCause && failingCorrelated.length > 0) {
+        likelyCause = `The crash is likely caused by the non-compliant implementation of ${failingCorrelated.map(r => r.ruleId).join(", ")}.`;
+        if (moduleDiagnosis)
+            secondaryModuleNote = moduleDiagnosis.hint;
+    }
+    else if (!likelyCause && moduleDiagnosis) {
+        likelyCause = moduleDiagnosis.cause;
+        missingModuleHint = moduleDiagnosis.hint;
+    }
+    else if (!likelyCause && correlatedRules.length > 0) {
+        likelyCause = `The crash symptoms match the known signatures of ${correlatedRules.map(r => r.ruleId).join(", ")}, but ${correlatedRules.length === 1 ? "that rule passes its" : "those rules pass their"} compliance check — the cause is likely runtime-only or outside the deterministic sensor's reach.`;
     }
     else if (!likelyCause) {
         likelyCause = `An unknown ${exceptionClass || "runtime"} error occurred.`;
+        if (moduleDiagnosis)
+            secondaryModuleNote = moduleDiagnosis.hint;
     }
-    const suggestedRemediation = buildRemediation(correlatedRules, checkResult);
+    const suggestedRemediation = missingModuleHint
+        ? { action: missingModuleHint }
+        : buildRemediation(correlatedRules, checkResult);
     const repairBrief = buildRepairBrief(correlatedRules, checkResult, inspection.platforms, likelyCause);
     const payload = {
         correlatedRules,
@@ -73,6 +121,7 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
         extractedException: exceptionClass,
         suggestedRemediation,
         repairBrief,
+        ...(secondaryModuleNote ? { secondaryNotes: [secondaryModuleNote] } : {}),
         relevantDocs: [
             {
                 title: "Troubleshooting",
@@ -85,6 +134,7 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
             likelyCause: payload.likelyCause,
             correlatedRules: payload.correlatedRules,
             repairBrief: payload.repairBrief,
+            ...(secondaryModuleNote ? { secondaryNotes: [secondaryModuleNote] } : {}),
             relevantDocs: payload.relevantDocs,
         };
     }
@@ -106,8 +156,12 @@ function buildRemediation(correlatedRules, checkResult) {
             docRef: `vise explain ${cr.ruleId}`,
         };
     });
+    const failing = correlatedRules.filter((cr) => cr.status === "failed" || cr.status === "attested");
+    const action = failing.length > 0
+        ? "Repair the compliance failure(s) identified above."
+        : "The correlated rule(s) pass their deterministic compliance checks; investigate the runtime behavior of the listed rule(s). The failure is likely runtime-only or outside the sensor's reach — do not change the compliant code paths.";
     return {
-        action: "Repair the compliance failure(s) identified above.",
+        action,
         rules,
     };
 }
@@ -143,7 +197,10 @@ function buildRepairBrief(correlatedRules, checkResult, platforms, likelyCause)
 }
 function pickPrimaryRuleId(correlatedRules) {
     const failed = correlatedRules.find((rule) => rule.status === "failed");
-    return failed?.ruleId ?? correlatedRules[0]?.ruleId ?? null;
+    if (failed)
+        return failed.ruleId;
+    const attested = correlatedRules.find((rule) => rule.status === "attested");
+    return attested?.ruleId ?? null;
 }
 function candidateFilesForRule(ruleId, checkResult) {
     if (!checkResult) {