@amityco/social-plus-vise 1.1.1 → 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));
@@ -285,12 +288,11 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "plan" || command === "plan-integration") {
-            await printToolResult(planIntegrationTool, {
-                repoPath: positionalRepoPath(args.slice(1)),
-                request: requiredFlagValue(args, "request", "plan requires --request."),
-                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
-                answers: keyValueFlag(args, "answer"),
-            });
+            const input = await planCliInput(args);
+            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") {
@@ -414,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));
@@ -448,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") {
@@ -583,13 +607,17 @@ Create the evidence-backed implementation packet before editing code.
 
 Usage:
   vise plan [repoPath] --request "Add a social feed"
+  vise plan --summary "Use UIKit for a standard feed"
   vise plan apps/web --request "Create posts" --surface apps/web
+  vise plan . --request "Use UIKit for a standard feed" --summary
 
 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
@@ -838,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
@@ -854,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 sdk.init.at-startup`;
+  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 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
@@ -919,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.
@@ -952,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
@@ -993,6 +1050,43 @@ 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");
+    if (requestFromFlag) {
+        return {
+            repoPath: positionalRepoPath(subArgs),
+            request: requestFromFlag,
+            surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+            answers: keyValueFlag(args, "answer"),
+        };
+    }
+    const positional = positionalValues(subArgs);
+    const [first, ...rest] = positional;
+    if (!first) {
+        throw new Error("plan requires --request or a quoted request argument.");
+    }
+    const firstLooksLikePath = await pathExists(first);
+    if (firstLooksLikePath && rest.length === 0) {
+        throw new Error("plan requires --request when the only positional argument is a repository path.");
+    }
+    return {
+        repoPath: firstLooksLikePath ? first : ".",
+        request: firstLooksLikePath ? rest.join(" ").trim() : positional.join(" ").trim(),
+        surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+        answers: keyValueFlag(args, "answer"),
+    };
+}
 function toolResultStatus(printed) {
     try {
         const payload = JSON.parse(printed.text);
@@ -1002,6 +1096,125 @@ function toolResultStatus(printed) {
         return undefined;
     }
 }
+function planSummary(payload) {
+    const solutionPath = objectProp(payload, "solutionPath");
+    const uikitCustomization = objectProp(payload, "uikitCustomization");
+    const intake = objectProp(payload, "intake");
+    const answers = objectProp(intake, "answers") ?? {};
+    const workplan = objectProp(payload, "socialWorkplan");
+    const questions = arrayProp(intake, "questions").map(questionSummary);
+    const decisionsRequired = stringArrayProp(payload, "decisionsRequired");
+    const solutionPathAnswerId = stringProp(solutionPath, "answerId");
+    const uikitCustomizationAnswerId = stringProp(uikitCustomization, "answerId");
+    return stripUndefined({
+        kind: "plan-summary",
+        outcome: stringProp(payload, "outcome"),
+        platform: stringProp(payload, "platform"),
+        supportLevel: stringProp(payload, "supportLevel"),
+        solutionPath: solutionPath
+            ? {
+                recommendation: stringProp(solutionPath, "recommendation"),
+                confidence: stringProp(solutionPath, "confidence"),
+                summary: stringProp(solutionPath, "summary"),
+                answerId: solutionPathAnswerId,
+                decisionRequired: booleanProp(objectProp(solutionPath, "decision"), "requiredBeforeHandRolledUi") === true
+                    && !hasAnswerValue(answers, solutionPathAnswerId),
+            }
+            : undefined,
+        uikitCustomization: uikitCustomization
+            ? {
+                status: stringProp(uikitCustomization, "status"),
+                recommendedLevel: stringProp(uikitCustomization, "recommendedLevel"),
+                confidence: stringProp(uikitCustomization, "confidence"),
+                summary: stringProp(uikitCustomization, "summary"),
+                answerId: uikitCustomizationAnswerId,
+                decisionRequired: booleanProp(objectProp(uikitCustomization, "decision"), "requiredBeforeCustomization") === true
+                    && !hasAnswerValue(answers, uikitCustomizationAnswerId),
+            }
+            : undefined,
+        intake: intake
+            ? {
+                status: stringProp(intake, "status"),
+                remainingBlocking: numberProp(intake, "remainingBlocking"),
+                blockingQuestions: questions.filter((question) => question.blocksImplementationWhenMissing),
+                openQuestions: questions,
+                answers,
+            }
+            : undefined,
+        decisionsRequired,
+        workplan: workplan ? workplanSummary(workplan) : undefined,
+        nextStep: stringProp(payload, "nextStep"),
+    });
+}
+function hasAnswerValue(answers, answerId) {
+    if (!answerId) {
+        return false;
+    }
+    const answer = answers[answerId];
+    return typeof answer === "string" && answer.trim() !== "";
+}
+function workplanSummary(workplan) {
+    return stripUndefined({
+        kind: stringProp(workplan, "kind"),
+        status: stringProp(workplan, "status"),
+        nextStep: stringProp(workplan, "nextStep"),
+        surfaces: arrayProp(workplan, "sequence").map((surface) => {
+            const surfaceObject = asObject(surface);
+            const intake = objectProp(surfaceObject, "intake");
+            return stripUndefined({
+                id: stringProp(surfaceObject, "id"),
+                order: numberProp(surfaceObject, "order"),
+                outcome: stringProp(surfaceObject, "outcome"),
+                label: stringProp(surfaceObject, "label"),
+                remainingBlocking: numberProp(intake, "remainingBlocking"),
+                intakeStatus: stringProp(intake, "status"),
+            });
+        }),
+    });
+}
+function questionSummary(value) {
+    const question = asObject(value);
+    return {
+        id: stringProp(question, "id"),
+        question: stringProp(question, "question"),
+        required: booleanProp(question, "required"),
+        blocksImplementationWhenMissing: booleanProp(question, "blocksImplementationWhenMissing"),
+    };
+}
+function objectProp(value, key) {
+    if (!value) {
+        return undefined;
+    }
+    return asObject(value[key]);
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function arrayProp(value, key) {
+    if (!value) {
+        return [];
+    }
+    const item = value[key];
+    return Array.isArray(item) ? item : [];
+}
+function stringArrayProp(value, key) {
+    return arrayProp(value, key).filter((item) => typeof item === "string");
+}
+function stringProp(value, key) {
+    const item = value?.[key];
+    return typeof item === "string" ? item : undefined;
+}
+function numberProp(value, key) {
+    const item = value?.[key];
+    return typeof item === "number" ? item : undefined;
+}
+function booleanProp(value, key) {
+    const item = value?.[key];
+    return typeof item === "boolean" ? item : undefined;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
 async function installSkill(args) {
     const source = skillSourceDir();
     const instructionInstall = instructionInstallDestination(args);
@@ -1281,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
@@ -1331,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);
@@ -1340,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.`);
     }
@@ -1432,13 +1648,25 @@ 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}.`,
         },
     };
 }
 function positionalRepoPath(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 values = positionalValues(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", "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];
         if (!arg) {
@@ -1454,9 +1682,18 @@ function positionalRepoPath(args) {
         if (arg.startsWith("-")) {
             continue;
         }
-        return arg;
+        values.push(arg);
+    }
+    return values;
+}
+async function pathExists(input) {
+    try {
+        await stat(path.resolve(expandHome(input)));
+        return true;
+    }
+    catch {
+        return false;
     }
-    return ".";
 }
 function requiredPositionalText(args, message) {
     const values = [];
@@ -1609,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,
     };
 }