@amityco/social-plus-vise 1.2.0 → 1.4.0

package/dist/flow.js

@@ -0,0 +1,382 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { sidecarDir } from "./sidecar.js";
+export function blueprintDigest(input) {
+    const canonical = JSON.stringify({
+        path: input.path ?? null,
+        stages: input.stages.map((stage) => ({ id: stage.id, outcome: stage.outcome })),
+        design: input.design ?? null,
+    });
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
+}
+export function flowStatePath(repoRoot) {
+    return path.join(sidecarDir(repoRoot), "flow.json");
+}
+export function flowBlueprintPath(repoRoot) {
+    return path.join(sidecarDir(repoRoot), "flow-blueprint.html");
+}
+export async function readFlowState(repoRoot) {
+    try {
+        return JSON.parse(await readFile(flowStatePath(repoRoot), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeFlowState(repoRoot, state) {
+    const target = flowStatePath(repoRoot);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+export async function readOmittedSurfaces(repoRoot, request) {
+    const state = await readFlowState(repoRoot);
+    if (!state || state.request !== request) {
+        return [];
+    }
+    return state.blueprint?.omitted ?? [];
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function surfaceReadiness(stage) {
+    const id = stage.id || stage.outcome;
+    const label = stage.label ?? stage.id;
+    const base = {
+        id,
+        label,
+        seedGuidance: "If tenant data is missing, create safe dogfood data through Console or SDK seed functions, then use the returned SDK object in the running app instead of copying its ID into source/config.",
+    };
+    switch (id) {
+        case "community":
+            return {
+                ...base,
+                smokeExpectation: "populated",
+                smokeReason: "Community discovery is only proven when at least one readable community renders.",
+                targetSources: [
+                    "SDK community discovery/search/recommended query scoped to the current user.",
+                    "Host route or user selection when the product already has a community picker/detail route.",
+                    "SDK create-community seed flow; use the returned community object immediately for the dogfood journey.",
+                ],
+                tenantData: ["At least one public or dogfood-readable community exists and is discoverable by the current user."],
+                consolePrep: ["Confirm community visibility, membership permissions, moderation/review mode, and role access for the dogfood user."],
+                noDataFallback: [
+                    "Ask whether to create a dogfood community in Console or through the SDK create-community flow.",
+                    "After creating it, re-run discovery and select the rendered/returned community naturally.",
+                    "If seeding is declined, only a resolved empty-state proof is possible; do not claim populated community proof.",
+                ],
+                evidenceToRecord: ["Selected community display name and resolved communityId in smoke evidence, not source/config."],
+            };
+        case "feed":
+            return {
+                ...base,
+                smokeExpectation: "populated",
+                smokeReason: "A feed integration is only product-proven when visible posts render, not just an empty shell.",
+                targetSources: [
+                    "Current-user or global feed when the selected product story supports it.",
+                    "Selected community returned by the community discovery/create flow.",
+                    "Selected profile/user object from host auth, profile, member, follower, or search state.",
+                ],
+                tenantData: ["A target global, community, or user feed is known, and it contains at least one visible post for the current user."],
+                consolePrep: ["Confirm post permissions, community privacy, review mode, and any selected post-type availability."],
+                noDataFallback: [
+                    "Ask whether to create a visible dogfood post in the selected runtime feed target through Console or SDK post creation.",
+                    "Use the SDK return value or the next feed query result as the target for composer/comment proof.",
+                    "If no post can be created or discovered, record that populated feed proof was not run.",
+                ],
+                evidenceToRecord: ["Rendered feed target type, target display name, resolved target ID, and visible post count."],
+            };
+        case "comments":
+            return {
+                ...base,
+                smokeExpectation: "populated",
+                smokeReason: "Comments need a known parent post/thread so read and write affordances can be verified.",
+                targetSources: [
+                    "Selected or first rendered post from the SDK-backed feed list.",
+                    "Thread/comment composer receives the parent post object or postId from its parent post card.",
+                    "SDK seed post/comment flow; use returned post/comment objects during the same run.",
+                ],
+                tenantData: ["A visible parent post exists; seed at least one comment when the smoke should prove thread rendering."],
+                consolePrep: ["Confirm comment permissions, moderation settings, and whether flagged/reviewed comments should be visible."],
+                noDataFallback: [
+                    "Ask whether to create a dogfood parent post and comment through the SDK, then pass the returned post/comment object through app state.",
+                    "If the feed is empty and seeding is declined, skip populated comment proof and state that no natural parent post existed.",
+                    "Do not ask the user to paste a postId; the parent post must come from the rendered feed, route state, or the seed return value.",
+                ],
+                evidenceToRecord: ["Parent post title/text excerpt, resolved postId, and rendered comment count."],
+            };
+        case "chat":
+            return {
+                ...base,
+                smokeExpectation: "populated",
+                smokeReason: "Chat is only proven when the current user can open a real channel and see/send messages.",
+                targetSources: [
+                    "Current user's channel inbox/list query, selecting a rendered channel.",
+                    "SDK create-channel flow from selected users/community; use the returned channel object immediately.",
+                    "Host route or app state when the product already owns channel selection.",
+                ],
+                tenantData: ["A target channel exists, the current user is a member, and seed messages/unread state exist when those states are in scope."],
+                consolePrep: ["Confirm channel type, membership rules, message permissions, moderation, and read/unread expectations."],
+                noDataFallback: [
+                    "Ask whether to create a dogfood channel and seed at least one message through the SDK using selected dogfood users.",
+                    "Use the returned channel object or inbox query result immediately; do not put channelId into config.",
+                    "If channel creation is declined and the inbox is empty, record that only empty inbox resolution can be proven.",
+                ],
+                evidenceToRecord: ["Selected channel display name/type, resolved channelId, membership state, and visible message count."],
+            };
+        case "profile":
+            return {
+                ...base,
+                smokeExpectation: "populated",
+                smokeReason: "Profile/follow work should prove SDK-backed identity and relationship data, not static profile chrome.",
+                targetSources: [
+                    "Current Social+ user from host auth/session/current profile.",
+                    "Selected user from member, follower/following, chat participant, or search state.",
+                    "SDK seed/search flow that creates or finds a dogfood peer user, then uses the returned user object.",
+                ],
+                tenantData: ["The current user exists in Social+, and at least one other dogfood user exists for follow/follower state when in scope."],
+                consolePrep: ["Confirm user profile visibility, relationship/follow permissions, and any role/ban restrictions."],
+                noDataFallback: [
+                    "Ask whether to create/find a safe dogfood peer user through SDK search/create flows.",
+                    "If no peer exists and seeding is declined, prove only current-user profile resolution and mark relationship proof unavailable.",
+                    "Do not ask the user to paste targetId; select the peer through app search, member lists, followers, chat participants, or seed return values.",
+                ],
+                evidenceToRecord: ["Current user display name, selected peer display name, resolved user IDs, and relationship counts/states."],
+            };
+        case "notifications":
+            return {
+                ...base,
+                smokeExpectation: "resolved",
+                smokeReason: "Notification settings can be proven with readable settings; live push delivery needs separate device/provider setup.",
+                targetSources: [
+                    "Current logged-in Social+ user and the platform notification permission state.",
+                    "Push token/provider callback when live delivery is explicitly in scope.",
+                ],
+                tenantData: ["A current Social+ user exists; push tokens/provider credentials are required only when push delivery is in scope."],
+                consolePrep: ["Confirm notification settings, push provider setup, token ownership, and logout cleanup expectations."],
+                noDataFallback: [
+                    "If push/provider data is missing, ask whether runtime proof should stop at settings resolution or include provider setup.",
+                    "Do not synthesize device tokens or provider credentials; use the platform callback and local-only config.",
+                ],
+                evidenceToRecord: ["Notification settings read result, permission state, and token presence as set/missing only."],
+            };
+        default:
+            return {
+                ...base,
+                smokeExpectation: "resolved",
+                smokeReason: "Empty state may be legitimate unless the selected product story requires seeded data.",
+                targetSources: [
+                    "Host route/app state, SDK query result, or SDK create flow that returns the target object at runtime.",
+                ],
+                tenantData: ["Identify the natural target source and minimum dogfood records this surface needs before runtime smoke."],
+                consolePrep: ["Confirm tenant permissions and moderation settings let the dogfood user exercise the selected surface."],
+                noDataFallback: [
+                    "If discovery returns no data, ask whether to prepare Console data, seed safe SDK data, or downgrade to resolved empty-state proof.",
+                ],
+                evidenceToRecord: ["Resolved target display label, target type, and target ID in smoke evidence only."],
+            };
+    }
+}
+export function runtimeReadinessForStages(stages) {
+    return {
+        status: "needs-review",
+        placement: "before-dogfood",
+        summary: "Review identity, credential source, natural target discovery, tenant data, Console prep, runtime-proof consent, and populated-vs-resolved smoke expectations before feeding this workplan to a dogfood agent.",
+        identity: {
+            source: "host-auth-or-local-env",
+            blockingWhenUnknown: true,
+            localEnv: ["AMITY_USER_ID", "AMITY_DISPLAY_NAME"],
+            guidance: [
+                "Derive userId from the host app's auth/session/current profile whenever one exists.",
+                "For dogfood-only projects, use an explicit local env/config userId and label it as dogfood data.",
+                "Do not invent or hardcode userId, object IDs, reaction names, or region in source code.",
+                "Resolve community, feed, post, comment, channel, and target-user IDs from SDK queries, create flows, route state, or user selection.",
+            ],
+        },
+        credentials: {
+            source: "local-only-env-or-host-config",
+            localEnv: ["AMITY_API_KEY", "AMITY_REGION"],
+            guidance: [
+                "Keep API keys, auth tokens, and provider credentials in ignored local env/config or existing host configuration.",
+                "Commit only templates/placeholders; never log or echo secret-shaped values.",
+            ],
+        },
+        targetDiscovery: {
+            mode: "natural-runtime-discovery",
+            doNotRequire: ["communityId", "channelId", "targetId", "postId", "feedId", "commentId"],
+            order: [
+                "Prefer an existing host-app object: current auth/session user, route state, selected item, profile/member list, content detail, inbox, or composer context.",
+                "If the host app has no selected object, use SDK discovery/list/search queries for the current user and select a rendered result by display label.",
+                "Skip discovered objects whose display labels/descriptions are raw IDs, numeric-only labels, short random strings such as `rand2`, lorem/test data, `sampleapp` fixtures, or unrelated generated business copy; keep searching or create product-native seed data instead of rendering them.",
+                "Prefer a product-owned namespace/allowlist: app-created names, metadata tags, session/program identifiers, or cached IDs returned by the app's own create flow. If a broad SDK query returns mixed tenant data, render only product-safe matches and never let an unsafe object become the active selected target.",
+                "Deduplicate discovered/seeded targets by stable SDK ID or normalized product label, and prioritize populated product-owned targets before empty clones. A long rail of repeated zero-post targets is not polished populated proof.",
+                "Do not rewrite unsafe tenant labels/descriptions into product copy to make them look acceptable. Exclude those objects from every visible rail/list/card and author fallback.",
+                "Apply product-safe filtering to every visible rail/list/card and author fallback, not just the selected target. A hidden bad target is acceptable; a visible random tenant label is not populated product proof.",
+                "If discovery is empty, ask whether to prepare tenant data in Console or create safe dogfood seed data through SDK functions.",
+                "Use SDK-returned objects or subsequent query results in normal app state; do not copy object IDs into source, config, fixtures, or env files.",
+            ],
+            noData: {
+                status: "prepare-or-seed-before-populated-proof",
+                options: [
+                    "prepare data in Console and re-run discovery",
+                    "create safe dogfood data through SDK functions in the current tenant, then use the returned object",
+                    "decline data setup and run only resolved empty-state proof where that is a legitimate product state",
+                ],
+                ifDeclined: "Tell the user that populated runtime proof cannot be claimed. Static Vise checks and build sensors may pass, but empty tenant data can still hide route, session, permission, and rendering gaps.",
+            },
+            evidencePolicy: [
+                "Record resolved IDs only in sp-vise evidence, screenshots/log summaries, or local dogfood reports.",
+                "Evidence should include human-readable labels, source path (host state, SDK query, or seed function), visible counts, and whether data was pre-existing or created for dogfood.",
+                "Visible labels in product UI should be product-relevant; raw object IDs, random strings, numeric-only names, and unrelated tenant fixtures belong only in evidence, not the default screen.",
+                "Runtime screenshots must be product-clean. Flutter/React Native overflow banners, red error boxes, clipped action rows, or `BOTTOM OVERFLOWED BY ... PIXELS` are runtime failures to fix before claiming proof.",
+                "For any surface whose smokeExpectation is populated, an empty state is a failed populated proof even when the empty state is well-designed; seed or prepare data before claiming the surface is product-proven.",
+            ],
+        },
+        runtimeProof: {
+            consent: {
+                required: true,
+                question: "Runtime proof can boot browsers, simulators, emulators, or devices and consume local resources plus agent tokens. Ask the user before running it.",
+                yes: [
+                    "Run the target app, capture screenshot/log evidence, and run `vise smoke` when a smoke contract exists.",
+                    "Record natural target discovery or seed provenance, visible counts, platform, region, and runtime user display name.",
+                ],
+                no: [
+                    "Stop after static Vise checks and project sensors, then state that runtime behavior is unproven.",
+                    "Explain the remaining risks: cold-launch session races, empty or mis-permissioned tenant data, route wiring gaps, and native packaging issues.",
+                ],
+            },
+            cost: [
+                "May require browser automation, simulator/emulator boot, native build/install time, device permissions, network access, and additional agent context.",
+                "May require temporary tenant data creation if natural discovery returns empty results.",
+            ],
+        },
+        surfaces: stages.map(surfaceReadiness),
+        nextStep: "Confirm this runtime readiness packet before spawning a dogfood agent. Ask for runtime-proof consent; if the user says yes, discover natural targets first, prepare Console/SDK seed data when discovery is empty, then run runtime smoke with the listed expectation and record resolved runtime targets as evidence. Do not accept a polished empty state as populated proof. If the user says no, explain the expected unproven runtime risks instead of claiming product proof.",
+    };
+}
+function renderList(items) {
+    return `<ul>${items.map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>`;
+}
+function renderRuntimeReadiness(readiness) {
+    const surfaceRows = readiness.surfaces
+        .map((surface) => `<div class="ready-surface">
+<div class="ready-head"><span class="lbl">${escapeHtml(surface.label)}</span><span class="pill">${escapeHtml(surface.smokeExpectation)}</span></div>
+<p class="why">${escapeHtml(surface.smokeReason)}</p>
+<div class="cols"><div><b>target sources</b>${renderList(surface.targetSources)}</div><div><b>tenant data</b>${renderList(surface.tenantData)}</div></div>
+<div class="cols"><div><b>console prep</b>${renderList(surface.consolePrep)}</div><div><b>no data fallback</b>${renderList(surface.noDataFallback)}</div></div>
+<div><b>runtime evidence</b>${renderList(surface.evidenceToRecord)}<p class="seed">${escapeHtml(surface.seedGuidance)}</p></div>
+</div>`)
+        .join("\n");
+    return `<div class="card"><p class="h">runtime readiness · before dogfood</p>
+<p class="note">${escapeHtml(readiness.summary)}</p>
+<div class="cols"><div><b>identity env</b>${renderList(readiness.identity.localEnv)}</div><div><b>credential env</b>${renderList(readiness.credentials.localEnv)}</div></div>
+<div class="cols"><div><b>identity</b>${renderList(readiness.identity.guidance)}</div><div><b>credentials</b>${renderList(readiness.credentials.guidance)}</div></div>
+<div class="cols"><div><b>natural target discovery</b>${renderList(readiness.targetDiscovery.order)}<p class="seed">Do not require ${escapeHtml(readiness.targetDiscovery.doNotRequire.join(", "))} as setup inputs.</p></div><div><b>if no data exists</b>${renderList(readiness.targetDiscovery.noData.options)}<p class="seed">${escapeHtml(readiness.targetDiscovery.noData.ifDeclined)}</p></div></div>
+<div class="cols"><div><b>ask before runtime proof</b><p class="seed">${escapeHtml(readiness.runtimeProof.consent.question)}</p>${renderList(readiness.runtimeProof.consent.yes)}</div><div><b>if user declines proof</b>${renderList(readiness.runtimeProof.consent.no)}<p class="seed">${escapeHtml(readiness.runtimeProof.cost.join(" "))}</p></div></div>
+${surfaceRows}
+<p class="note">${escapeHtml(readiness.nextStep)}</p></div>`;
+}
+export function renderFlowBlueprint(input) {
+    const exp = input.experience;
+    const runtimeReadiness = input.runtimeReadiness ?? runtimeReadinessForStages(input.stages);
+    const stageRows = input.stages
+        .map((stage, index) => `<li><span class="n">${index + 1}</span><span class="lbl">${escapeHtml(stage.label ?? stage.id)}</span><span class="meta">${escapeHtml(stage.id)} · ${escapeHtml(stage.outcome)}</span></li>`)
+        .join("\n");
+    const omitted = input.omitted ?? [];
+    const pathSummary = input.pathDecision ? "choose sdk / uikit / hybrid" : input.path ?? "undecided";
+    const experienceSummary = exp?.selected ? `${exp.selected.title} (${exp.selected.id})` : "no EI selection provided";
+    const surfaceSummary = `${input.stages.length} active surface${input.stages.length === 1 ? "" : "s"}`;
+    const designSummary = input.design ? `contract ${input.design}` : "no accepted design contract";
+    const trimSummary = omitted.length ? `${omitted.length} surface${omitted.length === 1 ? "" : "s"} trimmed` : "none";
+    const summaryCard = `
+	<div class="card priority"><p class="h">approval checklist · confirm these before build</p>
+	<div class="row"><b>path</b><span>${escapeHtml(pathSummary)}</span></div>
+	<div class="row"><b>experience</b><span>${escapeHtml(experienceSummary)}</span></div>
+	<div class="row"><b>surfaces</b><span>${escapeHtml(surfaceSummary)}</span></div>
+	<div class="row"><b>design</b><span>${escapeHtml(designSummary)}</span></div>
+	<div class="row"><b>trimmed</b><span>${escapeHtml(trimSummary)}</span></div>
+	</div>`;
+    const omittedCard = omitted.length
+        ? `
+	<div class="card warning"><p class="h">out of scope · deliberately omitted, not built</p><ol>
+	${omitted
+            .map((o) => `<li><span class="lbl" style="text-decoration:line-through;opacity:.7">${escapeHtml(o.label ?? o.id)}</span><span class="meta">${escapeHtml(o.id)} · ${escapeHtml(o.outcome)}</span></li><li style="border-top:0;padding-top:0"><span class="row" style="opacity:.7">${escapeHtml(o.reason)}</span></li>`)
+            .join("\n")}
+</ol></div>`
+        : "";
+    const pathCard = input.pathDecision
+        ? `
+	<div class="card"><p class="h">1 · solution path · choose one</p><ol>
+	${input.pathDecision.options
+            .map((opt) => `<li><span class="lbl">${escapeHtml(opt)}</span></li>`)
+            .join("\n")}
+	</ol><p class="note">${escapeHtml(input.pathDecision.question)} The agent records your pick with <code>--answer solution_path=&lt;sdk|uikit|hybrid&gt;</code>, then re-confirms.</p></div>`
+        : `
+	<div class="card"><p class="h">1 · solution path</p><div class="row"><b>path</b><span>${escapeHtml(input.path ?? "undecided")}</span></div></div>`;
+    const experienceCard = exp && exp.selected
+        ? `
+	<div class="card"><p class="h">2 · EI experience · confirm or switch</p><ol>
+	<li><span class="lbl">${escapeHtml(exp.selected.title)}</span><span class="meta">recommended · ${escapeHtml(exp.selected.id)}</span></li>
+	${exp.alternatives
+            .map((a) => `<li><span class="lbl" style="opacity:.75">${escapeHtml(a.title)}</span><span class="meta">${escapeHtml(a.id)}</span></li>`)
+            .join("\n")}
+	</ol>${exp.alternatives.length ? `<p class="note">To build a different experience, re-run <code>vise creative accept . --variant &lt;id&gt; --rationale "&lt;why&gt;" --confidence high</code> and re-confirm the updated blueprint.</p>` : ""}</div>`
+        : "";
+    return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Vise — build blueprint</title>
+<style>
+:root{color-scheme:light dark}
+body{margin:0;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;line-height:1.5;padding:28px 20px 48px;max-width:740px;margin:0 auto}
+h1{font-size:20px;font-weight:500;margin:0 0 12px}
+.kicker{font-size:12px;opacity:.6;margin:0 0 8px}
+.req{font-size:14px;opacity:.85;background:rgba(127,127,127,.12);padding:11px 13px;border-radius:8px;margin:0 0 18px}
+	.card{border:0.5px solid rgba(127,127,127,.35);border-radius:12px;padding:14px 16px;margin:0 0 12px}
+	.card.priority{border-color:rgba(32,128,96,.55);background:rgba(32,128,96,.08)}
+	.card.warning{border-color:rgba(180,120,20,.55);background:rgba(180,120,20,.08)}
+	.h{font-size:13px;opacity:.65;margin:0 0 10px}
+ol{list-style:none;margin:0;padding:0}
+ol>li{display:flex;align-items:baseline;gap:10px;padding:7px 0;border-top:0.5px solid rgba(127,127,127,.2)}
+ol>li:first-child{border-top:0}
+.n{font-size:12px;opacity:.6;min-width:16px}
+.lbl{font-weight:500;font-size:14px}
+.meta{font-size:12px;opacity:.55;margin-left:auto;font-family:ui-monospace,Menlo,Consolas,monospace}
+	.row{display:flex;gap:8px;font-size:13px;opacity:.85;margin:4px 0}
+	.row b{font-weight:500;opacity:.6;min-width:70px}
+	.note,.why,.seed{font-size:13px;opacity:.78;margin:0 0 10px}
+	.note{margin:10px 0 0}
+	.seed{margin:8px 0 0}
+	.cols{display:grid;grid-template-columns:1fr 1fr;gap:12px}
+	.cols b{display:block;font-size:12px;font-weight:500;opacity:.6;margin:0 0 5px}
+	.cols ul{margin:0;padding-left:18px}
+	.cols li{line-height:1.45}
+	.ready-surface{border-top:0.5px solid rgba(127,127,127,.2);padding:10px 0 0;margin:10px 0 0}
+	.ready-head{display:flex;align-items:center;gap:8px;justify-content:space-between;margin:0 0 6px}
+	.pill{font-family:ui-monospace,Menlo,Consolas,monospace;font-size:11px;padding:2px 6px;border-radius:999px;background:rgba(127,127,127,.14);opacity:.75}
+	.digest{font-family:ui-monospace,Menlo,Consolas,monospace;font-size:12px;opacity:.6;margin-top:16px}
+code{font-family:ui-monospace,Menlo,Consolas,monospace}
+@media (max-width:640px){.cols{grid-template-columns:1fr}.meta{display:none}}
+</style></head><body>
+	<p class="kicker">vise · build blueprint · sp-vise/flow-blueprint.html</p>
+	<h1>Review and confirm before build</h1>
+	<div class="req">${escapeHtml(input.request)}</div>${summaryCard}${pathCard}${experienceCard}
+	<div class="card"><p class="h">3 · surfaces in scope · built and verified in order</p><ol>
+	${stageRows}
+	</ol></div>${omittedCard}${renderRuntimeReadiness(runtimeReadiness)}
+	<div class="card priority"><p class="h">sign-off · blocked until approved</p>
+	<p style="font-size:13.5px;opacity:.85;margin:0">${input.pathDecision ? `Choose the solution path first (the agent re-runs with <code>--answer solution_path=&lt;choice&gt;</code>); the journey below is built and verified in order on the chosen path. ` : ""}Build cannot start until this blueprint is signed off. After review, the agent records your approval with <code>--answer blueprint_confirmation=${escapeHtml(input.digest)}</code>. You'll only be asked again if the path, journey, or design source changes.</p>
+<p class="digest">blueprint digest ${escapeHtml(input.digest)}</p></div>
+</body></html>
+`;
+}
+export async function writeFlowBlueprintHtml(repoRoot, html) {
+    const target = flowBlueprintPath(repoRoot);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, html, "utf8");
+    return target;
+}

package/dist/humanFormat.js

@@ -0,0 +1,251 @@
+const STATUS_GLOSS = {
+    green: "All applicable rules pass.",
+    "needs-attestation": "Some rules need a host-agent or human attestation before they can pass.",
+    "deterministic-failures": "A deterministic sensor found a violation in the source.",
+    blocked: "An external prerequisite the customer must provide is missing.",
+    "contract-drift": "The recorded ruleset no longer matches the installed Vise — re-run init.",
+    "completeness-gap": "Required capabilities are neither built nor opted out (scope-omit) yet.",
+    "selected-capability-failures": "A selected optional capability's sensor failed.",
+    "needs-clarification": "Blocking intake questions are unresolved.",
+};
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function bullet(lines, indent = "  ") {
+    return lines.map((line) => `${indent}- ${line}`).join("\n");
+}
+function renderCompliance(payload) {
+    const status = asString(payload.status) ?? "unknown";
+    const exitCode = typeof payload.exitCode === "number" ? payload.exitCode : undefined;
+    const outcome = asString(payload.outcome);
+    const surface = asString(payload.surfacePath);
+    const out = [];
+    const head = `social.plus compliance: ${status.toUpperCase()}${exitCode !== undefined ? ` (exit ${exitCode})` : ""}`;
+    const scope = [outcome ? `outcome: ${outcome}` : null, surface ? `surface: ${surface}` : null].filter(Boolean).join(", ");
+    out.push(scope ? `${head} — ${scope}` : head);
+    if (STATUS_GLOSS[status])
+        out.push(STATUS_GLOSS[status]);
+    const summary = payload.summary;
+    if (summary && Object.keys(summary).length > 0) {
+        const parts = Object.entries(summary).map(([key, count]) => `${count} ${key}`);
+        out.push("", `Rules: ${parts.join(", ")}`);
+    }
+    const basisNote = asString(payload.evidence_basis_note);
+    if (basisNote)
+        out.push(`Evidence: ${basisNote}`);
+    const blocking = asArray(payload.rules)
+        .filter((r) => typeof r === "object" && r !== null)
+        .filter((r) => {
+        const s = asString(r.status);
+        return s !== undefined && s !== "deterministic-pass" && s !== "attested" && s !== "advisory";
+    });
+    if (blocking.length > 0) {
+        out.push("", "Needs action:");
+        out.push(bullet(blocking.slice(0, 20).map((r) => {
+            const id = asString(r.ruleId) ?? asString(r.contractRuleId) ?? "(rule)";
+            const reason = asString(r.reason) ?? asString(r.status) ?? "";
+            return reason ? `${id} [${asString(r.status)}]: ${reason}` : `${id} [${asString(r.status)}]`;
+        })));
+        if (blocking.length > 20)
+            out.push(`  …and ${blocking.length - 20} more`);
+    }
+    const completeness = payload.completeness;
+    const missing = asArray(completeness?.missing).filter((m) => typeof m === "object" && m !== null);
+    if (missing.length > 0) {
+        out.push("", "Missing capabilities (build, or `// vise: scope-omit <id> — <reason>`):");
+        out.push(bullet(missing.map((m) => `${asString(m.id) ?? "(capability)"}: ${asString(m.hint) ?? asString(m.label) ?? ""}`.trim())));
+    }
+    const next = asString(payload.nextStep);
+    if (next)
+        out.push("", `Next: ${next}`);
+    return out.join("\n");
+}
+function renderPlan(payload) {
+    const out = [];
+    const outcome = asString(payload.outcome) ?? "(unrouted)";
+    const platform = asString(payload.platform);
+    out.push(`Plan: ${outcome}${platform ? ` — ${platform}` : ""}`);
+    const sp = payload.solutionPath;
+    if (sp) {
+        const rec = asString(sp.recommendation);
+        const conf = asString(sp.confidence);
+        const summary = asString(sp.summary);
+        out.push(`Solution path: ${rec ?? "(n/a)"}${conf ? ` (${conf})` : ""}${summary ? ` — ${summary}` : ""}`);
+    }
+    const uikit = payload.uikitCustomization;
+    if (uikit) {
+        out.push(`UIKit customization: ${asString(uikit.recommendedLevel) ?? "(n/a)"} (${asString(uikit.status) ?? "n/a"})`);
+    }
+    const decisions = asArray(payload.decisionsRequired);
+    if (decisions.length > 0) {
+        out.push("", "Decisions required:");
+        out.push(bullet(decisions.map((d) => (typeof d === "string" ? d : asString(d.question) ?? JSON.stringify(d)))));
+    }
+    const steps = asArray(payload.implementationSteps);
+    if (steps.length > 0) {
+        out.push("", "Build steps:");
+        out.push(steps
+            .slice(0, 30)
+            .map((s, i) => `  ${i + 1}. ${typeof s === "string" ? s : asString(s.step) ?? asString(s.description) ?? JSON.stringify(s)}`)
+            .join("\n"));
+    }
+    const inputs = asArray(payload.requiredInputs).filter((i) => typeof i === "string");
+    if (inputs.length > 0) {
+        out.push("", "Required inputs:");
+        out.push(bullet(inputs));
+    }
+    const engagement = payload.engagement;
+    if (engagement) {
+        const baseline = asArray(engagement.baselineLevers).filter((l) => typeof l === "string");
+        const optional = asArray(engagement.optionalLevers).filter((l) => typeof l === "string");
+        if (baseline.length > 0 || optional.length > 0) {
+            out.push("", "Engagement levers (advisory):");
+            if (baseline.length > 0)
+                out.push(`  baseline: ${baseline.join(", ")}`);
+            if (optional.length > 0)
+                out.push(`  optional: ${optional.join(", ")}`);
+            const deepen = asString(engagement.deepenWith);
+            if (deepen)
+                out.push(`  ${deepen}`);
+        }
+    }
+    const intake = payload.intake;
+    const questions = asArray(intake?.questions).filter((q) => typeof q === "object" && q !== null);
+    const blockingQs = questions.filter((q) => q.blocksImplementationWhenMissing === true);
+    if (blockingQs.length > 0) {
+        out.push("", "Open intake (blocking):");
+        out.push(bullet(blockingQs.map((q) => `${asString(q.id) ?? "?"}: ${asString(q.prompt) ?? asString(q.question) ?? ""}`.trim())));
+    }
+    const next = asString(payload.nextStep);
+    if (next)
+        out.push("", `Next: ${next}`);
+    return out.join("\n");
+}
+function renderDoctor(payload) {
+    const out = [];
+    out.push(`${asString(payload.package) ?? "vise"} ${asString(payload.version) ?? ""} — ${asString(payload.status) ?? "?"}`.trim());
+    const buildSource = asString(payload.buildSource);
+    if (buildSource === "local") {
+        out.push(`⚠ build: LOCAL source build (npm link / dev checkout) — NOT the published npm package`);
+        const root = asString(payload.packageRoot);
+        if (root)
+            out.push(`  root: ${root}`);
+    }
+    else if (buildSource === "published") {
+        out.push(`build: published npm package`);
+    }
+    if (payload.node)
+        out.push(`node: ${asString(payload.node)} (requires ${asString(payload.requiredNodeMajor) ?? "?"})`);
+    out.push(`docs: ${asString(payload.docsSource) ?? "?"}${payload.docsRoot ? ` (${asString(payload.docsRoot)})` : ""}`);
+    if (payload.transport)
+        out.push(`transport: ${asString(payload.transport)}`);
+    const tools = asArray(payload.tools);
+    if (tools.length > 0)
+        out.push(`tools: ${tools.length} registered`);
+    const support = asString(payload.support);
+    if (support)
+        out.push(`support: ${support}`);
+    return out.join("\n");
+}
+function renderExplain(payload) {
+    if (payload.kind === "rule-index") {
+        const out = [`${payload.count} compliance rules. Run \`vise explain <id>\` for the full rule.`, ""];
+        for (const entry of asArray(payload.rules).filter((e) => typeof e === "object" && e !== null)) {
+            const id = asString(entry.id) ?? "(rule)";
+            const sev = asString(entry.severity);
+            const outcomes = asArray(entry.outcomes).join(", ");
+            out.push(`  ${id}${sev ? `  (${sev})` : ""}${outcomes ? `  — ${outcomes}` : ""}`);
+        }
+        return out.join("\n");
+    }
+    if (payload.kind === "product_expectation") {
+        const out = [`${asString(payload.id) ?? "(rule)"} — validated by ${asArray(payload.contract_rules).length} contract rule(s):`];
+        for (const c of asArray(payload.contract_rules).filter((e) => typeof e === "object" && e !== null)) {
+            out.push(`  ${asString(c.contract_rule_id) ?? "?"} — ${asString(c.title) ?? ""}`.trimEnd());
+        }
+        return out.join("\n");
+    }
+    const out = [];
+    const id = asString(payload.id) ?? "(rule)";
+    const contractId = asString(payload.contract_rule_id);
+    const title = asString(payload.title);
+    const sev = asString(payload.severity);
+    const version = payload.version;
+    out.push(`${id}${contractId ? ` (${contractId})` : ""}${title ? ` — ${title}` : ""}${sev ? `  [${sev}${version !== undefined ? `, v${version}` : ""}]` : ""}`);
+    const rationale = asString(payload.rationale);
+    if (rationale)
+        out.push(rationale);
+    const applies = payload.applies_when;
+    if (applies) {
+        const o = asArray(applies.outcomes).join(", ");
+        const p = asArray(applies.platforms).join(", ");
+        const parts = [o ? `outcomes: ${o}` : null, p ? `platforms: ${p}` : null].filter(Boolean).join("; ");
+        if (parts)
+            out.push(`Applies — ${parts}`);
+    }
+    const feedforward = asString(payload.feedforward);
+    if (feedforward)
+        out.push(`Feedforward: ${feedforward}`);
+    const symptoms = asArray(payload.symptoms).filter((s) => typeof s === "string");
+    if (symptoms.length > 0)
+        out.push(`Symptoms: ${symptoms.join(" | ")}`);
+    const attestation = payload.attestation;
+    if (attestation)
+        out.push(`Attestation: ${attestation.allowed ? "allowed" : "not allowed"}${attestation.host_agent_min_confidence ? ` (host-agent min ${asString(attestation.host_agent_min_confidence)})` : ""}`);
+    const digest = asString(payload.rule_digest);
+    if (digest)
+        out.push(`digest: ${digest}`);
+    return out.join("\n");
+}
+function renderExplore(payload) {
+    const out = [];
+    const request = asString(payload.request) ?? "";
+    const matched = asString(payload.matched_outcome);
+    out.push(matched
+        ? `social.plus — best match for "${request}": ${matched}`
+        : `social.plus — what you can build (no single match for "${request}"):`);
+    for (const route of asArray(payload.routes).filter((r) => typeof r === "object" && r !== null)) {
+        out.push("", `▸ ${asString(route.outcome) ?? "(outcome)"} — ${asString(route.summary) ?? ""}`.trimEnd());
+        const caps = asArray(route.capabilities).filter((c) => typeof c === "object" && c !== null);
+        if (caps.length > 0)
+            out.push(`    capabilities: ${caps.map((c) => asString(c.id)).filter(Boolean).join(", ")}`);
+        const start = asString(route.start);
+        if (start)
+            out.push(`    start: ${start}`);
+    }
+    const also = asArray(payload.also_available).filter((a) => typeof a === "object" && a !== null);
+    if (also.length > 0) {
+        out.push("", "Also available:");
+        out.push(bullet(also.map((a) => `${asString(a.outcome) ?? "?"} — ${asString(a.summary) ?? ""}`.trimEnd())));
+    }
+    const note = asString(payload.note);
+    if (note)
+        out.push("", note);
+    return out.join("\n");
+}
+const RENDERERS = {
+    check: renderCompliance,
+    status: renderCompliance,
+    plan: renderPlan,
+    doctor: renderDoctor,
+    explain: renderExplain,
+    explore: renderExplore,
+};
+export function wantsHumanFormat(format) {
+    return format === "human";
+}
+export function renderHuman(command, payload) {
+    const renderer = RENDERERS[command];
+    if (!renderer || typeof payload !== "object" || payload === null) {
+        return null;
+    }
+    try {
+        return renderer(payload);
+    }
+    catch {
+        return null;
+    }
+}