@amityco/social-plus-vise 0.11.0 → 0.12.2

package/dist/tools/docs.js

@@ -159,25 +159,30 @@ async function loadLocalDocPages(root) {
     }));
 }
 async function fetchText(url) {
-    const timeoutMs = fetchTimeoutMs();
+    return fetchTextWithTimeout(url, "text/plain, text/markdown, */*");
+}
+// Shared network primitive — same AbortController + env-configurable timeout used for
+// docs fetches. Exported so other plan-layer lookups (e.g. the npm registry SDK-version
+// check) reuse one network path rather than adding a parallel one.
+export async function fetchTextWithTimeout(url, accept = "*/*", timeoutMs = fetchTimeoutMs()) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const response = await fetch(url, {
             headers: {
-                accept: "text/plain, text/markdown, */*",
+                accept,
                 "user-agent": packageUserAgent,
             },
             signal: controller.signal,
         });
         if (!response.ok) {
-            throw new Error(`Failed to fetch docs from ${url}: ${response.status} ${response.statusText}`);
+            throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
         }
         return await response.text();
     }
     catch (error) {
         if (error instanceof Error && error.name === "AbortError") {
-            throw new Error(`Timed out fetching docs from ${url} after ${timeoutMs}ms.`);
+            throw new Error(`Timed out fetching ${url} after ${timeoutMs}ms.`);
         }
         throw error;
     }

package/dist/tools/integration.js

@@ -1,8 +1,11 @@
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { BROAD_SOCIAL_REGEX, DESIGN_REGEX, classifyOutcome, getOutcomeDefinition, hasAnswer, planContextFor, } from "../outcomes.js";
 import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { capabilityChecklist } from "../capabilities.js";
 import { applicableComplianceRuleSummaries } from "./compliance.js";
+import { readDesignContract } from "./design.js";
+import { sdkVersionGuidance } from "./sdkVersion.js";
 import { detectCommandSensors } from "./harness.js";
 import { inspectProject } from "./project.js";
 export const planIntegrationTool = {
@@ -68,24 +71,97 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
         answers,
     });
     const definition = getOutcomeDefinition(outcome);
+    const intake = intakeFor(ctx, definition.intakeQuestions(ctx));
+    const designContract = await readDesignContract(repoRoot);
+    // Advisory SDK-version currency guidance (npm registry for TS/RN; version-agnostic
+    // for native). Best-effort — degrades to greenfield "install latest + pin" if the
+    // registry is unreachable. Never gates.
+    const packageJsonText = await readFile(path.join(root, "package.json"), "utf8").catch(() => undefined);
+    const sdkVersion = await sdkVersionGuidance(platform, packageJsonText);
+    // Scope decisions, hoisted to the top of the output so they survive a `head`
+    // truncation. Blocking questions must be resolved before building; clarifying
+    // questions (e.g. which engagement surfaces are in scope) must be decided and
+    // the decision stated — so an omitted feature like comments is an explicit,
+    // reviewable choice rather than a silent drop. Mirrors the detailed `intake`
+    // block below; placed here because the intake block lands past common `head`
+    // cut points.
+    const decisionsRequired = intake.questions.map((q) => q.blocksImplementationWhenMissing
+        ? `[resolve before building] ${q.question}`
+        : `[decide & state in your summary] ${q.question}`);
+    // Steps-first ordering: implementationSteps + validation lead the object so
+    // that an agent piping `vise plan` through `head` still captures the
+    // actionable guidance. The verbose scaffolding (intake, docs, surfaces, rule
+    // dumps) follows. Do not move implementationSteps back down — feature steps
+    // landing past a `head -120` cut is a documented real-world failure mode.
     return {
         outcome,
         platform,
-        surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
-        availableSurfaces: inspection.surfaces,
         supportLevel,
         intent: intentFor(request, definition.interpretation),
-        intake: intakeFor(ctx, definition.intakeQuestions(ctx)),
-        docs: definition.docs(platform).filter((doc) => doc.path !== "unknown"),
+        decisionsRequired,
+        implementationSteps: definition.implementationSteps(ctx),
+        validation: ["validate_setup", "run_sensors", ...definition.validation(platform)],
+        nextStep: "After implementing every step above, run `vise check .` and fix findings until green. You are not done until the check passes or each finding is explicitly attested.",
         requiredInputs: composeRequiredInputs(ctx, definition.requiredInputs(ctx)),
         targetFiles: await targetFilesFor(root, outcome, platform, inspection.designSignals),
         implementationRules: composeImplementationRules(ctx, definition.implementationRules(ctx)),
-        implementationSteps: definition.implementationSteps(ctx),
-        validation: ["validate_setup", "run_sensors", ...definition.validation(platform)],
+        intake,
+        docs: definition.docs(platform).filter((doc) => doc.path !== "unknown"),
+        surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
+        availableSurfaces: inspection.surfaces,
         applicableRules: await applicableComplianceRuleSummaries(outcome, inspection.platforms),
         sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
         stopConditions: composeStopConditions(ctx, definition.stopConditions(ctx), inspection.surfaces, surfacePath),
         evidencePolicy: "Every implementation step must cite at least one detected file, docs page, validator rule, or required user input. If evidence is missing, stop and ask the user instead of inventing details.",
+        designContract: designContract ? designContractGuidance(designContract) : undefined,
+        completenessChecklist: completenessChecklistFor(outcome),
+        sdkVersion,
+    };
+}
+// Vise-authored capability checklist for the outcome (feed-forward). The agent
+// builds each or opts out with a recorded reason (`// vise: scope-omit <id>
+// <reason>`), which `vise check` reads and reports. Advisory — Vise proposes the
+// set so completeness doesn't depend on the agent remembering it.
+function completenessChecklistFor(outcome) {
+    const items = capabilityChecklist(outcome);
+    if (items.length === 0) {
+        return undefined;
+    }
+    return {
+        note: "Build each capability, or opt out with `// vise: scope-omit <id> <reason>`. `vise check` reports present/missing/opted-out (advisory — never fails the check).",
+        capabilities: items,
+    };
+}
+// Build advisory UI-generation guidance from an extracted design contract.
+// Declared tokens are surfaced with their custom-property name (so the agent
+// references `var(--x)` / maps it per platform); inferred tokens carry their
+// raw value plus a usage count and an explicit "inferred" marker so they are
+// never mistaken for authoritative brand values.
+function designContractGuidance(contract) {
+    const byCategory = (category) => contract.tokens
+        .filter((token) => token.category === category)
+        .map((token) => token.provenance === "declared" && token.name
+        ? `${token.name}: ${token.value}`
+        : `${token.value} (inferred, ${token.uses}×)`);
+    return {
+        digest: contract.digest,
+        strength: contract.stats.strength,
+        source: contract.source,
+        summary: `A design contract was extracted from the customer's prototype (${contract.stats.declared_tokens} declared + ${contract.stats.inferred_tokens} inferred tokens, strength: ${contract.stats.strength}). ` +
+            "Build the social.plus UI using these tokens so it matches the prototype's aesthetic. Prefer the declared tokens; treat inferred tokens as advisory and confirm brand values with the customer when the contract is weak.",
+        tokens: {
+            color: byCategory("color"),
+            spacing: byCategory("space"),
+            radius: byCategory("radius"),
+            shadow: byCategory("shadow"),
+            fontFamily: byCategory("fontFamily"),
+            fontSize: byCategory("fontSize"),
+            motion: byCategory("motion"),
+        },
+        components: contract.components.map((component) => ({ name: component.name, selector: component.selector })),
+        breakpoints: contract.breakpoints.map((breakpoint) => breakpoint.raw),
+        attestation: `When you record a design attestation, cite this contract digest (${contract.digest}) so the generated feed can be claimed conformant to the customer's prototype.`,
+        advisoryOnly: "This contract is advisory generation guidance — it adds no deterministic enforcement and never fails `vise check`.",
     };
 }
 function intentFor(request, interpretation) {