@amityco/social-plus-vise 1.2.0 → 1.3.0

package/dist/server.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, experienceReportTool, initCompliance, initComplianceTool, initEngagement, initEngagementTool, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
+import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, experienceReportTool, initCompliance, initComplianceTool, recordBaseline, initEngagement, initEngagementTool, listRules, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
 import { designCheckTool, designExtractTool, designInitTokensTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
 import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
 import { compileExperienceTool } from "./tools/experienceCompiler.js";
@@ -22,7 +22,10 @@ import { addBlockInstall, listRegistryBlocks, planBlockInstall, validateBlockIns
 import { debugIssueTool, debugIssue } from "./tools/debug.js";
 import { creativeAcceptTool, creativeBriefTool } from "./tools/creative.js";
 import { uxHarnessTool } from "./tools/uxHarness.js";
+import { exploreRequest } from "./explore.js";
+import { renderHuman, wantsHumanFormat } from "./humanFormat.js";
 import { packageName, packageVersion } from "./version.js";
+const SUPPORT_URL = "mailto:support@social.plus";
 const tools = new Map([
     searchDocsTool,
     getDocPageTool,
@@ -107,14 +110,14 @@ async function handleCli(args) {
         console.log(helpText(args[1]));
         return "exit";
     }
-    if (command === "doctor" || command === "--doctor") {
-        console.log(JSON.stringify(doctorResult(), null, 2));
-        return "exit";
-    }
     if (isHelpRequest(args)) {
         console.log(helpText(command));
         return "exit";
     }
+    if (command === "doctor" || command === "--doctor") {
+        emitResult("doctor", doctorResult(), args);
+        return "exit";
+    }
     try {
         if (command === "install-skill" || command === "install_skill") {
             console.log(JSON.stringify(await installSkill(args.slice(1)), null, 2));
@@ -286,15 +289,10 @@ async function handleCli(args) {
         }
         if (command === "plan" || command === "plan-integration") {
             const input = await planCliInput(args);
-            if (hasFlag(args, "summary")) {
-                const result = await planIntegrationTool.call(input);
-                const text = result.content.map((item) => item.text).join("\n");
-                const payload = JSON.parse(text);
-                console.log(JSON.stringify(planSummary(payload), null, 2));
-            }
-            else {
-                await printToolResult(planIntegrationTool, input);
-            }
+            const result = await planIntegrationTool.call(input);
+            const text = result.content.map((item) => item.text).join("\n");
+            const payload = JSON.parse(text);
+            emitResult("plan", hasFlag(args, "summary") ? planSummary(payload) : payload, args);
             return "exit";
         }
         if (command === "plan-harness") {
@@ -418,21 +416,30 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "init") {
-            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake"], "init");
-            const result = await initCompliance(positionalRepoPath(args.slice(1)), requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake") });
+            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake", "baseline"], "init");
+            const initRepo = positionalRepoPath(args.slice(1));
+            const result = await initCompliance(initRepo, requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake") });
             if (result.status === "needs-clarification" && typeof result.exitCode === "number") {
                 process.exitCode = result.exitCode;
             }
+            if (hasFlag(args, "baseline") && result.status === "initialized") {
+                result.baseline_recorded = await recordBaseline(initRepo);
+            }
             console.log(JSON.stringify(result, null, 2));
             return "exit";
         }
         if (command === "check") {
-            assertOnlyKnownFlags(args, ["ci"], "check");
-            const result = await checkCompliance(positionalRepoPath(args.slice(1)));
-            console.log(JSON.stringify(hasFlag(args, "ci") ? ciCheckResult(result) : result, null, 2));
+            assertOnlyKnownFlags(args, ["ci", "format", "new-only"], "check");
+            const result = await checkCompliance(positionalRepoPath(args.slice(1)), { newOnly: hasFlag(args, "new-only") });
+            emitResult("check", hasFlag(args, "ci") ? ciCheckResult(result) : result, args);
             process.exitCode = result.exitCode;
             return "exit";
         }
+        if (command === "baseline") {
+            assertOnlyKnownFlags(args, [], "baseline");
+            console.log(JSON.stringify(await recordBaseline(positionalRepoPath(args.slice(1))), null, 2));
+            return "exit";
+        }
         if (command === "sync") {
             assertOnlyKnownFlags(args, [], "sync");
             console.log(JSON.stringify(await syncCompliance(positionalRepoPath(args.slice(1))), null, 2));
@@ -452,13 +459,26 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "explain") {
-            assertOnlyKnownFlags(args, [], "explain");
-            console.log(JSON.stringify(await explainRule(requiredPositionalText(args.slice(1), "explain requires a rule id.")), null, 2));
+            assertOnlyKnownFlags(args, ["format"], "explain");
+            const explainRuleId = positionalValues(args.slice(1))[0];
+            const payload = explainRuleId ? await explainRule(explainRuleId) : await listRules();
+            emitResult("explain", payload, args);
+            return "exit";
+        }
+        if (command === "explore") {
+            assertOnlyKnownFlags(args, ["request", "platform", "format"], "explore");
+            const request = flagValue(args, "request") ??
+                requiredPositionalText(args.slice(1), 'explore requires a request, e.g. `vise explore "add a social feed"`.');
+            emitResult("explore", exploreRequest(request, flagValue(args, "platform")), args);
             return "exit";
         }
         if (command === "status") {
-            assertOnlyKnownFlags(args, [], "status");
-            console.log(JSON.stringify(await statusCompliance(positionalRepoPath(args.slice(1))), null, 2));
+            assertOnlyKnownFlags(args, ["format", "new-only"], "status");
+            const result = await statusCompliance(positionalRepoPath(args.slice(1)), { newOnly: hasFlag(args, "new-only") });
+            emitResult("status", result, args);
+            if (typeof result.exitCode === "number") {
+                process.exitCode = result.exitCode;
+            }
             return "exit";
         }
         if (command === "engagement") {
@@ -595,7 +615,9 @@ Re-plan with collected answers (repeat --answer for each intake question):
   vise plan . --request "Add a social feed" \\
     --answer feed_scope=community \\
     --answer feed_target=existing\\ communityId \\
-    --answer target_screen_or_route=app/feed/page.tsx`;
+    --answer target_screen_or_route=app/feed/page.tsx
+
+Output is JSON by default (for agents/CI). Add --format human for a readable plan summary.`;
     }
     if (command === "creative") {
         return `${packageName} creative
@@ -844,7 +866,9 @@ Usage:
 Check the current source and recorded attestations against the compliance contract. Read-only.
 
 Usage:
-  vise check [repoPath] [--ci]`;
+  vise check [repoPath] [--ci] [--format human]
+
+Output is JSON by default (for agents/CI). Add --format human for a readable verdict summary.`;
     }
     if (command === "sync") {
         return `${packageName} sync
@@ -860,23 +884,45 @@ Usage:
 Record a host-agent or local-human attestation for one compliance rule.
 
 Usage:
-  vise attest [repoPath] --rule sdk.init.at-startup --confidence high --signer host-agent --evidence-file evidence.json --rationale "Why this rule is satisfied."`;
+  vise attest [repoPath] --rule typescript.client.region --confidence high --signer host-agent --evidence-file evidence.json --rationale "Why this rule is satisfied."`;
     }
     if (command === "explain") {
         return `${packageName} explain
 
-Explain one compliance rule.
+Explain one compliance rule, or list every valid rule id when run with no id.
+
+Usage:
+  vise explain [--format human]      List all rule ids (public + contract) with where each applies
+  vise explain typescript.client.region [--format human]`;
+    }
+    if (command === "explore") {
+        return `${packageName} explore
+
+Discover what social.plus offers for a request — before any project or credentials exist. Read-only:
+maps the request to a candidate outcome (or lists the full menu when it can't), and for each shows the
+capabilities involved, the canonical docs, and the command to start. No project, no API key, no writes.
 
 Usage:
-  vise explain sdk.init.at-startup`;
+  vise explore "add a social feed" [--platform typescript] [--format human]`;
+    }
+    if (command === "doctor") {
+        return `${packageName} doctor
+
+Print install diagnostics (Node version, transport, docs source, registered tools).
+Read-only. JSON by default; --format human for a readable summary.
+
+Usage:
+  vise doctor [--format human]
+
+If diagnostics report a problem, see ${SUPPORT_URL}`;
     }
     if (command === "status") {
         return `${packageName} status
 
-Print a compact compliance summary.
+Print a compact compliance summary. JSON by default; --format human for a readable verdict.
 
 Usage:
-  vise status [repoPath]`;
+  vise status [repoPath] [--format human]`;
     }
     if (command === "design") {
         return `${packageName} design
@@ -925,14 +971,17 @@ contractual record of which broad-social outcomes are in scope for this project.
 
 Usage:
   vise engagement init [repoPath] --tier <free|pro|partner> --customer-id <id> --scope <outcome,...>
-  vise engagement init [repoPath] --scope feed,communities --target-completion 2026-12-31 \\
+  vise engagement init [repoPath] --scope add-feed,add-community --target-completion 2026-12-31 \\
     --reviewer-name "Jane Doe" --reviewer-email jane@example.com --evidence-upload-consent
   vise engagement show [repoPath]
 
 Flags (init):
   --tier <free|pro|partner>   Engagement tier (validated).
   --customer-id <id>          Customer identifier recorded in the artifact.
-  --scope <outcome,...>       In-scope broad-social outcomes (repeatable; comma-separated).
+  --scope <outcome,...>       In-scope outcomes, comma-separated. One or more of: setup-sdk,
+                              setup-push, setup-live-data, add-feed, add-comments, add-chat,
+                              add-community, add-follow, add-moderation, add-notifications,
+                              troubleshoot, validate-setup.
   --target-completion <date>  Target completion date, YYYY-MM-DD.
   --reviewer-name <name>      Human reviewer recorded on the engagement.
   --reviewer-email <email>    Human reviewer contact.
@@ -958,10 +1007,12 @@ Usage:
   vise learning record [repoPath] Record a local-only learning event
   vise learning show [repoPath]    Show local learning summary
   vise debug [repoPath] --error ... Debug an SDK-specific runtime error and emit a repair brief
+  vise explore "<request>"         Discover what social.plus offers for a request (no project/credentials needed)
   vise plan [repoPath] --request "..." Create an implementation plan
   vise workplan next [repoPath] --request "..." Get the next broad-social surface to implement
-  vise init [repoPath] --request "..." Initialize compliance sidecar
-  vise check [repoPath]            Check compliance contract
+  vise init [repoPath] --request "..." Initialize compliance sidecar (add --baseline on a brownfield app)
+  vise check [repoPath]            Check compliance contract (add --new-only to gate on findings since the baseline)
+  vise baseline [repoPath]         Snapshot pre-existing findings so check --new-only gates only new ones
   vise sync [repoPath]             Persist deterministic-pass evidence
   vise attest [repoPath] --rule ... Record a compliance attestation
   vise explain <ruleId>            Explain one compliance rule
@@ -999,6 +1050,16 @@ async function printToolResult(tool, input) {
     console.log(text);
     return { result, text };
 }
+function emitResult(command, payload, args) {
+    if (wantsHumanFormat(flagValue(args, "format"))) {
+        const human = renderHuman(command, payload);
+        if (human !== null) {
+            console.log(human);
+            return;
+        }
+    }
+    console.log(JSON.stringify(payload, null, 2));
+}
 async function planCliInput(args) {
     const subArgs = args.slice(1);
     const requestFromFlag = flagValue(args, "request");
@@ -1433,7 +1494,7 @@ async function completeWorkplanSurface(args) {
         throw new Error(`Surface "${surfaceId}" is not in this social workplan. Available surfaces: ${sequence.map((item) => item.id).join(", ") || "(none)"}.`);
     }
     const now = new Date().toISOString();
-    const check = await greenWorkplanCheck(repoRoot, surfaceId);
+    const check = await greenWorkplanCheck(repoRoot, surfaceId, surface.outcome);
     const snapshot = await writeWorkplanSurfaceSnapshot(repoRoot, surfaceId, check, now);
     const existing = await readWorkplanProgress(repoRoot);
     const base = existing?.request === request
@@ -1483,7 +1544,7 @@ async function completeWorkplanSurface(args) {
         nextStep: status.nextStep,
     };
 }
-async function greenWorkplanCheck(repoRoot, surfaceId) {
+async function greenWorkplanCheck(repoRoot, surfaceId, expectedOutcome) {
     let check;
     try {
         check = await checkCompliance(repoRoot);
@@ -1492,6 +1553,9 @@ async function greenWorkplanCheck(repoRoot, surfaceId) {
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(`Cannot mark "${surfaceId}" complete because the current compliance check could not run. Run the focused \`vise init\` command for this surface first, then \`vise check .\`. ${message}`);
     }
+    if (expectedOutcome && check.outcome !== expectedOutcome) {
+        throw new Error(`Cannot mark "${surfaceId}" complete: the sp-vise sidecar is currently scoped to outcome "${check.outcome}", not this surface's outcome "${expectedOutcome}". Each workplan surface has its own sidecar scope — run this surface's focused \`vise init\` command (it sets \`--answer feature_surface=${surfaceId}\`) and \`vise check .\` before recording it. (The check reported "${check.status}" only because it ran against the other surface's contract.)`);
+    }
     if (check.status !== "green") {
         throw new Error(`Cannot mark "${surfaceId}" complete because \`vise check\` returned "${check.status}" (exit ${check.exitCode}). Resolve the check result before recording workplan progress.`);
     }
@@ -1584,7 +1648,14 @@ function ciCheckResult(result) {
             enabled: true,
             passed: result.exitCode === 0,
             exitCode: result.exitCode,
-            blockingResultStatuses: ["contract-drift", "blocked", "deterministic-failures", "needs-attestation"],
+            blockingResultStatuses: [
+                "contract-drift",
+                "blocked",
+                "deterministic-failures",
+                "needs-attestation",
+                "completeness-gap",
+                "selected-capability-failures",
+            ],
             message: result.exitCode === 0 ? "Compliance green for CI." : `Compliance failed for CI with status: ${result.status}.`,
         },
     };
@@ -1594,7 +1665,7 @@ function positionalRepoPath(args) {
     return values[0] ?? ".";
 }
 function positionalValues(args) {
-    const flagsWithValues = new Set(["request", "requirements", "prototype", "variant", "variant-id", "brief", "brief-path", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference", "registry", "block", "package-source", "note", "kind", "sentiment", "metric"]);
+    const flagsWithValues = new Set(["request", "requirements", "prototype", "variant", "variant-id", "brief", "brief-path", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference", "registry", "block", "package-source", "note", "kind", "sentiment", "metric", "tier", "customer-id", "scope", "target-completion", "reviewer-name", "reviewer-email"]);
     const values = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
@@ -1775,5 +1846,6 @@ function doctorResult() {
         docsBaseUrl: process.env.SOCIAL_PLUS_DOCS_BASE_URL ?? "https://learn.social.plus",
         transport: "stdio",
         tools: Array.from(tools.keys()),
+        support: SUPPORT_URL,
     };
 }

package/dist/solutionPath.js

@@ -56,7 +56,7 @@ const SDK_SIGNALS = [
         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|\bnon[-\s]?standard (?:ui|layout|flow|experience)\b|\bpixel[-\s]?perfect\b/i,
+        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",