@amityco/social-plus-vise 0.8.1 → 0.11.0

package/dist/tools/compliance.js

@@ -161,7 +161,7 @@ function stringArray(value) {
     return value.filter((item) => typeof item === "string" && item.trim() !== "");
 }
 const validTiers = new Set(["free", "pro", "partner"]);
-const validOutcomes = new Set(["setup-sdk", "setup-push", "setup-live-data", "add-feed", "troubleshoot", "validate-setup", "unknown"]);
+const validOutcomes = new Set(["setup-sdk", "setup-push", "setup-live-data", "add-feed", "add-comments", "add-moderation", "add-chat", "troubleshoot", "validate-setup", "unknown"]);
 export async function initEngagement(args) {
     const repoRoot = path.resolve(args.repoPath);
     const engagementFile = engagementPath(repoRoot);
@@ -227,23 +227,35 @@ export async function initCompliance(repoPath, request, surfacePath) {
     const inspection = await inspectProject(repoRoot, surfacePath);
     const outcome = classifyOutcome(request);
     const rules = await applicableRules(outcome, inspection.platforms);
-    const refs = rules.map(ruleRef);
+    const refs = rules.map(ruleRef); // minimal shape — stable digest input
+    const fileRefs = rules.map(ruleRefForFile); // adds title for human/agent readers
     const engagement = await readEngagement(repoRoot);
     const compliance = {
         schema_version: schemaVersion,
         foundry_version: packageVersion,
-        ruleset_digest: digestJson(refs),
+        ruleset_digest: digestJson(refs), // hash of minimal refs (no title)
         generated_at: new Date().toISOString(),
         last_synced_at: null,
         outcome,
         engagement_id: engagement?.engagement_id,
         surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
-        rules: refs,
+        rules: fileRefs, // file carries titles
     };
     await mkdir(attestationsDir(repoRoot), { recursive: true });
     await writeJson(compliancePath(repoRoot), compliance);
     await writeJson(path.join(sidecarDir(repoRoot), "inspection.json"), inspection);
     await writeFile(path.join(sidecarDir(repoRoot), "README.md"), sidecarReadme(compliance), "utf8");
+    // Write a frozen check snapshot so agents can see current rule status immediately
+    // without having to run vise check themselves.
+    const checkSnapshot = await checkCompliance(repoPath);
+    await writeJson(path.join(sidecarDir(repoRoot), "findings.json"), {
+        snapshot_at: compliance.generated_at,
+        note: "Snapshot taken at vise init time. Re-run `vise check .` after editing code to see current status.",
+        outcome: checkSnapshot.outcome,
+        status: checkSnapshot.status,
+        summary: checkSnapshot.summary,
+        rules: checkSnapshot.rules,
+    });
     const warnings = [];
     if (engagement && engagement.scope.outcomes.length > 0 && !engagement.scope.outcomes.includes(outcome)) {
         warnings.push(`Outcome "${outcome}" is not in the engagement scope (${engagement.scope.outcomes.join(", ")}). Compliance was still initialized; extend the scope in engagement.json or re-run vise engagement init.`);
@@ -260,7 +272,7 @@ export async function initCompliance(repoPath, request, surfacePath) {
     };
 }
 export async function applicableComplianceRuleSummaries(outcome, platforms) {
-    return (await applicableRules(outcome, platforms)).map(ruleRef);
+    return (await applicableRules(outcome, platforms)).map(ruleRefForFile);
 }
 export async function checkCompliance(repoPath) {
     const repoRoot = path.resolve(repoPath);
@@ -278,8 +290,12 @@ export async function checkCompliance(repoPath) {
         };
     }
     const inspection = await inspectProject(repoRoot, compliance.surface?.path === "." ? undefined : compliance.surface?.path);
-    const platform = inspection.platforms[0] ?? "unknown";
-    const findings = await validateSetup(inspection.effectiveRoot, platform);
+    const detectedPlatforms = inspection.platforms;
+    const recordedPlatforms = compliance.surface?.platforms || [];
+    const platformsToValidate = Array.from(new Set([...detectedPlatforms, ...recordedPlatforms]));
+    const platforms = platformsToValidate.length > 0 ? platformsToValidate : ["unknown"];
+    const allFindings = await Promise.all(platforms.map((p) => validateSetup(inspection.effectiveRoot, p)));
+    const findings = allFindings.flat();
     const findingsById = new Map(findings.map((finding) => [finding.ruleId, finding]));
     const attestations = await readAttestations(repoRoot);
     const results = [];
@@ -295,6 +311,7 @@ export async function checkCompliance(repoPath) {
         // user knows what to provide.
         const blockersFired = await runBlockers(rule, inspection.effectiveRoot);
         if (blockersFired.length > 0) {
+            const attestable = rule.enforcement.attestation.allowed;
             results.push({
                 ruleId: rule.id,
                 title: rule.title,
@@ -303,11 +320,16 @@ export async function checkCompliance(repoPath) {
                 reason: blockersFired.map((blocker) => blocker.reason).join(" "),
                 blockers_fired: blockersFired,
                 current_rule: ruleSummary(rule),
+                ...(attestable && {
+                    next_step: `Provide the file(s) listed in blockers_fired, then run \`vise attest . --rule ${rule.id}\` to record your review decision.`,
+                }),
             });
             continue;
         }
-        const finding = deterministicFinding(rule, findingsById);
-        if (!finding) {
+        const hasDeterministicChecks = (rule.enforcement.deterministic ?? []).length > 0;
+        const isInferential = !hasDeterministicChecks && !!rule.enforcement.inferential;
+        const finding = hasDeterministicChecks ? deterministicFinding(rule, findingsById) : undefined;
+        if (hasDeterministicChecks && !finding) {
             results.push({
                 ruleId: rule.id,
                 title: rule.title,
@@ -332,12 +354,14 @@ export async function checkCompliance(repoPath) {
                         ? "Current deterministic check failed; previously synced deterministic-pass evidence is stale."
                         : "Current deterministic check failed; this rule does not allow attestation.",
                     finding,
-                    recommendation: finding.recommendation,
+                    recommendation: finding?.recommendation,
+                    rationale: rule.rationale,
                     current_rule: ruleSummary(rule),
                 });
                 continue;
             }
-            const exactMatch = attestation.rule_digest === ref.rule_digest && attestation.ruleset_digest === compliance.ruleset_digest;
+            // ruleset_digest is audit metadata; contractDrift above already guarantees the installed ruleset matches compliance.json.
+            const exactMatch = attestation.rule_digest === ref.rule_digest;
             const grandfathered = !exactMatch && isAttestationGrandfathered(rule, attestation);
             if (exactMatch || grandfathered) {
                 const sourceFingerprintStatus = await checkSourceFingerprints(repoRoot, inspection.effectiveRoot, attestation.source_fingerprints ?? []);
@@ -350,7 +374,8 @@ export async function checkCompliance(repoPath) {
                         status: rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
                         reason: "Recorded attestation source fingerprints changed. Re-check the evidence and record a fresh attestation.",
                         finding,
-                        recommendation: finding.recommendation,
+                        recommendation: finding?.recommendation,
+                        rationale: rule.rationale,
                         current_rule: ruleSummary(rule),
                         source_fingerprint_status: sourceFingerprintStatus,
                     });
@@ -375,15 +400,24 @@ export async function checkCompliance(repoPath) {
                 continue;
             }
         }
+        const baseStatus = (rule.enforcement.attestation.allowed || isInferential) ? "attestation-needed" : "deterministic-fail";
+        let fallbackReason = "This rule does not allow attestation.";
+        if (isInferential) {
+            fallbackReason = "Inferential check required. Please provide a host-agent attestation.";
+        }
+        else if (rule.enforcement.attestation.allowed) {
+            fallbackReason = "Deterministic check failed and no valid attestation exists.";
+        }
         results.push({
             ruleId: rule.id,
             title: rule.title,
             severity: rule.severity,
-            status: rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
-            reason: rule.enforcement.attestation.allowed ? "Deterministic check failed and no valid attestation exists." : "This rule does not allow attestation.",
+            status: baseStatus,
+            reason: fallbackReason,
             finding,
-            recommendation: finding.recommendation,
+            recommendation: finding?.recommendation,
             current_rule: ruleSummary(rule),
+            ...(isInferential && { inferential_prompt: rule.enforcement.inferential?.prompt })
         });
     }
     const summary = summarize(results);
@@ -542,7 +576,7 @@ async function loadRuleFiles() {
     }
     return loaded;
 }
-async function rulesById() {
+export async function rulesById() {
     const rules = (await loadRuleFiles()).flatMap((file) => file.rules);
     return new Map(rules.map((rule) => [rule.id, rule]));
 }
@@ -554,6 +588,11 @@ function ruleRef(rule) {
         severity: rule.severity,
     };
 }
+// Extends ruleRef with the human-readable title for file output (compliance.json,
+// applicableRules in integration plans). Not used for digest computation.
+function ruleRefForFile(rule) {
+    return { ...ruleRef(rule), title: rule.title };
+}
 function contractDrift(compliance, rules) {
     const results = [];
     const refs = compliance.rules.map((ref) => {
@@ -860,8 +899,11 @@ async function readAttestations(repoRoot) {
             continue;
         }
         const attestation = await readJsonIfExists(path.join(dir, entry));
-        if (attestation?.rule_id) {
-            result.set(attestation.rule_id, attestation);
+        if (attestation?.rule_id && attestation.payload_hash) {
+            const { payload_hash, ...withoutHash } = attestation;
+            if (digestJson(withoutHash) === payload_hash) {
+                result.set(attestation.rule_id, attestation);
+            }
         }
     }
     return result;
@@ -898,8 +940,14 @@ function sidecarReadme(compliance) {
         `- Rules: ${compliance.rules.length}`,
         `- Generated: ${compliance.generated_at}`,
         "",
-        "Run `vise check` to verify current status and `vise sync` to persist deterministic-pass evidence.",
-        "Host-agent and human attestations include source fingerprints for cited files; `vise check` marks them stale if those files change.",
+        "## Quick start",
+        "",
+        "1. Read `findings.json` — it contains a snapshot of rule status taken at init time, including any violations found in the current code.",
+        "2. Fix the issues listed in `findings.json`, then run `npm run sp-check` (or `vise check .` if vise is on PATH) to verify.",
+        "3. Run `vise sync .` to persist deterministic-pass evidence once rules are green.",
+        "4. Run `vise attest . --rule <rule-id> ...` to sign off on intentional implementation decisions.",
+        "",
+        "Attestations include source fingerprints; `vise check` marks them stale if the cited files change.",
         "",
     ].join("\n");
 }

package/dist/tools/debug.js

@@ -0,0 +1,267 @@
+import { objectInput, optionalBooleanField, stringField, textResult } from "../types.js";
+import { checkCompliance, rulesById } from "./compliance.js";
+import { inspectProject } from "./project.js";
+function sanitizeError(errorMessage) {
+    // Strip out local absolute file paths (e.g., /Users/admin/..., /home/user/...)
+    let sanitized = errorMessage.replace(/(?:\/(?:users|home)\/[^\s:]+)/gi, "[LOCAL_PATH]");
+    // Strip out thread IDs / Hex memory addresses
+    sanitized = sanitized.replace(/0x[0-9a-fA-F]+/g, "[HEX_ADDR]");
+    return sanitized;
+}
+function extractExceptionClass(errorMessage) {
+    // Try to find a Java/Kotlin exception (e.g. java.lang.NullPointerException or com.amity.AmityException)
+    const javaMatch = errorMessage.match(/([a-zA-Z0-9_.]+[A-Z][a-zA-Z0-9_]*Exception)/);
+    if (javaMatch)
+        return javaMatch[1];
+    // Try to find a JS Error (e.g. TypeError, Error)
+    const jsMatch = errorMessage.match(/([A-Z][a-zA-Z0-9]*Error):/);
+    if (jsMatch)
+        return jsMatch[1];
+    return null;
+}
+export async function debugIssue(repoPath, errorMessage, options = {}) {
+    const sanitizedError = sanitizeError(errorMessage);
+    const exceptionClass = extractExceptionClass(errorMessage);
+    // 1. Inspect Context
+    const inspection = await inspectProject(repoPath);
+    // 2. Version-mismatch heuristic (NOT used as benchmark evidence).
+    // This is a keyword-only heuristic, not real dependency inspection.
+    // Version-mismatch scenarios are excluded from the TypeScript pilot
+    // (see DEBUGGING_BENCHMARK_PLAN.md Section 5 "Explicitly excluded from the pilot").
+    // Do not use this branch as measured benchmark evidence.
+    let likelyCause = "";
+    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.";
+    }
+    // 3. Compliance History Correlation
+    const correlatedRules = [];
+    let checkResult = null;
+    try {
+        checkResult = await checkCompliance(repoPath);
+        const rulesMap = await rulesById();
+        for (const rule of checkResult.rules) {
+            if (rule.status === "deterministic-fail" || rule.status === "attestation-needed") {
+                // It failed. Check if symptoms match.
+                const ruleDef = rulesMap.get(rule.ruleId);
+                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.`,
+                    });
+                }
+            }
+            else if (rule.status === "attested") {
+                // Check for false-positive attestations
+                const ruleDef = rulesMap.get(rule.ruleId);
+                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.`,
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        // Ignore error if compliance sidecar doesn't exist yet
+    }
+    if (!likelyCause && correlatedRules.length > 0) {
+        likelyCause = `The crash is likely caused by the non-compliant implementation of ${correlatedRules.map(r => r.ruleId).join(", ")}.`;
+    }
+    else if (!likelyCause) {
+        likelyCause = `An unknown ${exceptionClass || "runtime"} error occurred.`;
+    }
+    // Build rule-specific remediation guidance from rule definitions and validator findings.
+    const suggestedRemediation = buildRemediation(correlatedRules, checkResult);
+    const repairBrief = buildRepairBrief(correlatedRules, checkResult, inspection.platforms, likelyCause);
+    const payload = {
+        correlatedRules,
+        likelyCause,
+        sanitizedErrorSignature: sanitizedError,
+        extractedException: exceptionClass,
+        suggestedRemediation,
+        repairBrief,
+        relevantDocs: [
+            {
+                title: "Troubleshooting",
+                url: "https://learn.social.plus/troubleshooting"
+            }
+        ]
+    };
+    if (options.brief) {
+        return {
+            likelyCause: payload.likelyCause,
+            correlatedRules: payload.correlatedRules,
+            repairBrief: payload.repairBrief,
+            relevantDocs: payload.relevantDocs,
+        };
+    }
+    return payload;
+}
+function buildRemediation(correlatedRules, checkResult) {
+    if (correlatedRules.length === 0) {
+        return { action: "Review the correlated rules and ensure SDK integration matches the required patterns." };
+    }
+    const rules = correlatedRules.map(cr => {
+        const ruleResult = checkResult?.rules.find(r => r.ruleId === cr.ruleId);
+        // Prefer the validator's per-finding recommendation; fall back to a generic note.
+        const guidance = ruleResult?.recommendation
+            ?? "Review the rule implementation and ensure the SDK integration matches the required pattern.";
+        return {
+            ruleId: cr.ruleId,
+            title: ruleResult?.title ?? cr.ruleId,
+            guidance,
+            file: ruleResult?.finding?.file,
+            docRef: `vise explain ${cr.ruleId}`,
+        };
+    });
+    return {
+        action: "Repair the compliance failure(s) identified above.",
+        rules,
+    };
+}
+function buildRepairBrief(correlatedRules, checkResult, platforms, likelyCause) {
+    const primaryRuleId = pickPrimaryRuleId(correlatedRules);
+    const verify = verificationCommands(platforms);
+    if (!primaryRuleId) {
+        return {
+            primaryRuleId: null,
+            why: likelyCause,
+            candidateFiles: [],
+            minimumPatchShape: [
+                "Inspect the SDK integration path mentioned in the symptom.",
+                "Repair only the smallest social.plus code path that explains the runtime failure.",
+            ],
+            preserve: [
+                "Do not widen the patch beyond the failing social.plus integration path.",
+                "Preserve any existing compliant setup, auth, and pagination wiring unless the customer explicitly changes behavior.",
+            ],
+            verify,
+        };
+    }
+    const ruleResult = checkResult?.rules.find((rule) => rule.ruleId === primaryRuleId);
+    const template = repairTemplateForRule(primaryRuleId);
+    return {
+        primaryRuleId,
+        why: template.why ?? likelyCause,
+        candidateFiles: candidateFilesForRule(primaryRuleId, checkResult),
+        minimumPatchShape: template.minimumPatchShape,
+        preserve: template.preserve,
+        verify,
+    };
+}
+function pickPrimaryRuleId(correlatedRules) {
+    const failed = correlatedRules.find((rule) => rule.status === "failed");
+    return failed?.ruleId ?? correlatedRules[0]?.ruleId ?? null;
+}
+function candidateFilesForRule(ruleId, checkResult) {
+    if (!checkResult) {
+        return [];
+    }
+    const matches = checkResult.rules
+        .filter((rule) => rule.ruleId === ruleId)
+        .flatMap((rule) => {
+        const file = rule.finding?.file;
+        return typeof file === "string" && file.length > 0 ? [file] : [];
+    });
+    return Array.from(new Set(matches));
+}
+function verificationCommands(platforms) {
+    const commands = [];
+    if (platforms.includes("typescript") || platforms.includes("react-native")) {
+        commands.push("npm run typecheck");
+    }
+    commands.push("vise check . --ci");
+    commands.push("vise run-sensors .");
+    return commands;
+}
+function repairTemplateForRule(ruleId) {
+    const templates = {
+        "typescript.client.region": {
+            why: "The SDK client is initialized without an explicit region or endpoint, so runtime setup does not match the customer's social.plus project.",
+            minimumPatchShape: [
+                "Edit the existing client setup module or initialization function.",
+                "Pass apiRegion or apiEndpoint into the existing client initialization call, such as Client.create() or Client.createClient().",
+                "Prefer the app's existing config or environment source if one already exists.",
+            ],
+            preserve: [
+                "Preserve the app's existing config or environment source of truth for region or endpoint.",
+                "Do not hardcode a guessed default region if the customer already has a region owner elsewhere in the app.",
+            ],
+        },
+        "typescript.session.renewal": {
+            why: "The login path is missing a renewal handler, so the SDK cannot refresh expiring access tokens.",
+            minimumPatchShape: [
+                "Edit the existing Client.login call in the current login path.",
+                "Add sessionHandler.sessionWillRenewAccessToken(renewal).",
+                "Call renewal.renew() from that callback.",
+            ],
+            preserve: [
+                "Preserve the existing session owner and login flow shape.",
+                "Retain the session handler for the full session lifetime instead of creating a short-lived local object.",
+            ],
+        },
+        "typescript.live-collection.api-mismatch": {
+            why: "The feed is using a one-shot list query instead of a reactive LiveCollection, so new posts do not flow into the UI.",
+            minimumPatchShape: [
+                "Edit the existing feed query function instead of replacing the feed surface.",
+                "Convert the one-shot query into a reactive collection with onData.",
+                "Return cleanup that unsubscribes the collection.",
+            ],
+            preserve: [
+                "Preserve existing pagination and query wiring such as pageToken, hasMore/loadMore, or infinite-query state.",
+                "Do not widen the patch into unrelated rendering or moderation logic while restoring live updates.",
+            ],
+        },
+        "typescript.auth.logout-on-user-switch": {
+            why: "The app switches user identity by logging in directly without clearing the previous SDK session.",
+            minimumPatchShape: [
+                "Edit the existing user-switch flow.",
+                "Await Client.logout() before the next Client.login().",
+                "Keep the login call's existing renewal handler behavior intact.",
+            ],
+            preserve: [
+                "Preserve the current sessionHandler and renewal path while inserting logout-before-login.",
+                "Do not widen the patch into unrelated auth or navigation state.",
+            ],
+        },
+    };
+    return (templates[ruleId] ?? {
+        why: "A compliance rule correlated strongly with the reported social.plus failure.",
+        minimumPatchShape: [
+            "Edit the smallest code path associated with the correlated rule.",
+            "Bring the implementation back into compliance with the rule requirement.",
+        ],
+        preserve: [
+            "Preserve adjacent compliant wiring while repairing the failing rule.",
+        ],
+    });
+}
+export const debugIssueTool = {
+    name: "debug_issue",
+    description: "Debug a runtime crash, build failure, or logic issue against the social.plus SDK's specific context.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            errorMessage: { type: "string" },
+            brief: { type: "boolean" },
+        },
+        required: ["repoPath", "errorMessage"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const errorMessage = stringField(args, "errorMessage");
+        const result = await debugIssue(repoPath, errorMessage, {
+            brief: optionalBooleanField(args, "brief"),
+        });
+        return textResult(result);
+    },
+};

package/dist/tools/harness.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { classifyOutcome, getOutcomeDefinition } from "../outcomes.js";
 import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
 import { inspectProject } from "./project.js";
+import { rulesById } from "./compliance.js";
 export function harnessControlsFor(outcome, platforms) {
     const docsQuery = getOutcomeDefinition(outcome).docsQuery(platforms[0] ?? "sdk");
     return {
@@ -95,6 +96,19 @@ async function buildHarnessPlan(repoPath, request, surfacePath) {
     const controls = harnessControlsFor(outcome, inspection.platforms);
     const commandSensors = await detectCommandSensors(inspection.effectiveRoot, inspection.platforms);
     const harnessability = assessHarnessability(inspection.platforms, commandSensors, inspection.designSignals.length);
+    const rules = await rulesById();
+    const feedforward_instructions = [];
+    for (const rule of rules.values()) {
+        if (rule.feedforward) {
+            const outcomeMatch = !rule.applies_when.outcomes || rule.applies_when.outcomes.includes(outcome);
+            const platformMatch = !rule.applies_when.platforms || rule.applies_when.platforms.some(p => inspection.platforms.includes(p));
+            if (outcomeMatch && platformMatch) {
+                feedforward_instructions.push(`[${rule.id}]: ${rule.feedforward}`);
+            }
+        }
+    }
+    const steeringLoop = [...controls.steeringLoop];
+    steeringLoop.unshift("Fetch and review the capability_matrix_url. If the requested feature is strictly unsupported, short-circuit and emit a 'blocked' status to the user with alternative suggestions.");
     return {
         outcome,
         surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
@@ -103,7 +117,9 @@ async function buildHarnessPlan(repoPath, request, surfacePath) {
         harnessability,
         guides: controls.guides,
         sensors: [...controls.sensors, ...commandSensors],
-        steeringLoop: controls.steeringLoop,
+        steeringLoop,
+        capability_matrix_url: process.env.VISE_FEATURE_MATRIX_URL || "https://learn.social.plus/feature-matrix#feature-matrix",
+        feedforward_instructions,
     };
 }
 export async function detectCommandSensors(repoPath, platforms) {