@amityco/social-plus-vise 0.14.1 → 0.14.2

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@amityco/social-plus-vise` are documented in this file.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.14.2 — 2026-06-03
+
+**Theme:** SDK facts bridge for social.plus Block Factory.
+
+### Added
+- **Bundled SDK surface snapshot** in `sdk-surface/` for offline/npm use across TypeScript, Android, iOS, and Flutter.
+- **Internal `vise sdk-facts` CLI command and `get_sdk_facts` MCP tool** for Block Factory. The tool is projectless and read-only: it proves SDK symbol/capability/model-symbol facts from the normalized SDK surface without inspecting customer code.
+- **TypeScript Comments/Reactions capability facts** for the first Block Factory validation slice, including React Native aliasing to the TypeScript SDK surface.
+
+---
+
 ## 0.14.1 — 2026-06-03
 
 **Theme:** Retract the enumerative DesignBuildBrief from plan output — our own benchmark said so.

package/README.md

@@ -43,9 +43,9 @@ See [Usage Flow](#usage-flow) for the full step-by-step diagram.
 
 ## What Vise Does: Agentic Workflow Governance
 
-Instead of just providing a CLI or AI skills, Vise implements a technique called **Agentic Workflow Governance**. Think of it as building a software factory directly on top of the customer's project. 
+Instead of just providing a CLI or AI skills, Vise implements a technique called **Agentic Workflow Governance**. Think of it as a customer-project integration harness: the governed build loop runs inside the target repo, grounded in the real project, real docs, and real validation signals.
 
-Vise acts as the foreman of this factory, wrapping your local coding agents in compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 300 platform-specific compliance rules, checks the generated UI against the customer's design system, surfaces the full SDK feature surface so nothing is silently dropped, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
+Vise wraps your local coding agents in compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 300 platform-specific compliance rules, checks the generated UI against the customer's design system, surfaces the full SDK feature surface so nothing is silently dropped, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
 
 At a glance, Vise sits between the user's prompt and the agent's code changes. The agent still edits the app; Vise turns the request into a grounded plan, records the local contract, and keeps checking until the integration is ready to ship.
 
@@ -81,6 +81,15 @@ Vise validates on three layers, and the layer is set by the *kind of claim* —
 
 Only correctness is gated (it can be made FP-free); conformance and completeness are surfaced, because "all post types" and "matches the brand" are legitimately scope-dependent. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
+### Relationship to social.plus Block Factory
+
+Vise has two deliberately separate roles:
+
+- **Customer integration helper:** runs inside customer projects to inspect, plan, validate, and sensor-check social.plus SDK integrations.
+- **Block Factory SDK facts provider:** planned internal mode for social.plus Block Factory to verify SDK capabilities, symbols, and model schemas before reusable blocks are generated or released.
+
+Vise owns SDK truth and customer-project governance. social.plus Block Factory owns block contracts, package adapters, previews, conformance tests, and release readiness. See [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md) for the internal provider-side plan.
+
 ### Design-conformant UI
 
 Vise can ingest the customer's aesthetic into a **design contract** and guide generation to match it — from an HTML/CSS prototype (`vise design extract`) or from the host app's own design system across web + Android + Flutter + iOS (`vise design extract --from-project`: CSS vars/Tailwind/token modules, `colors.xml`, Flutter `Color(0x…)`, iOS `.colorset`/Swift). `vise design check` reports token conformance; `vise design preview` writes a visual review; `vise design reference` generates a full visual design-system spec (swatches, type samples, component demos). All advisory.

package/dist/server.js

@@ -14,6 +14,7 @@ import { planIntegrationTool } from "./tools/integration.js";
 import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
 import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
 import { runSensorsTool } from "./tools/sensors.js";
+import { getSdkFactsTool } from "./tools/sdkFacts.js";
 import { debugIssueTool, debugIssue } from "./tools/debug.js";
 import { packageName, packageVersion } from "./version.js";
 const tools = new Map([
@@ -39,6 +40,7 @@ const tools = new Map([
     designPreviewTool,
     designReferenceTool,
     designInitTokensTool,
+    getSdkFactsTool,
 ].map((tool) => [tool.name, tool]));
 const bundledSkillName = "social-plus-vise";
 // Pre-rebrand `install-skill` runs created skill dirs/files under this name. We
@@ -201,6 +203,20 @@ async function handleCli(args) {
             });
             return "exit";
         }
+        if (command === "sdk-facts" || command === "sdk_facts") {
+            assertOnlyKnownFlags(args, ["platform", "capability", "surface-dir", "format", "include-symbols"], "sdk-facts");
+            const format = flagValue(args, "format") ?? "json";
+            if (format !== "json") {
+                throw new Error("sdk-facts currently supports --format json only.");
+            }
+            await printToolResult(getSdkFactsTool, {
+                platform: requiredFlagValue(args, "platform", "sdk-facts requires --platform."),
+                capability: flagValue(args, "capability"),
+                surfaceDir: flagValue(args, "surface-dir"),
+                includeSymbols: hasFlag(args, "include-symbols"),
+            });
+            return "exit";
+        }
         if (command === "init") {
             assertOnlyKnownFlags(args, ["request", "surface", "surface-path"], "init");
             console.log(JSON.stringify(await initCompliance(positionalRepoPath(args.slice(1)), requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path")), null, 2));
@@ -468,6 +484,16 @@ Resolve a natural-language request into the closest supported Vise outcome.
 
 Usage:
   vise resolve [repoPath] --request "Add a social feed"`;
+    }
+    if (command === "sdk-facts" || command === "sdk_facts") {
+        return `${packageName} sdk-facts
+
+Read bundled SDK surface facts for social.plus Block Factory planning. Internal, projectless, and read-only.
+
+Usage:
+  vise sdk-facts --platform typescript --capability comments --format json
+  vise sdk-facts --platform react-native --capability reactions --include-symbols
+  vise sdk-facts --platform android --surface-dir ./sdk-surface --format json`;
     }
     if (command === "init") {
         return `${packageName} init
@@ -577,6 +603,7 @@ Usage:
   vise status [repoPath]           Print compliance summary
   vise validate [repoPath]         Validate setup and common risks
   vise run-sensors [repoPath]      Run detected project sensors
+  vise sdk-facts --platform ...    Internal SDK surface facts for Block Factory
   vise design extract <prototype>  Extract a design contract from an HTML/CSS prototype
   vise design check [repoPath]     Advisory (non-blocking) UI-vs-contract conformance report
   vise design preview [repoPath]   Write an HTML visual review of the contract + conformance
@@ -830,7 +857,7 @@ function ciCheckResult(result) {
     };
 }
 function positionalRepoPath(args) {
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
+    const flagsWithValues = new Set(["request", "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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -852,7 +879,7 @@ function positionalRepoPath(args) {
 }
 function requiredPositionalText(args, message) {
     const values = [];
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
+    const flagsWithValues = new Set(["request", "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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {

package/dist/tools/sdkFacts.js

@@ -0,0 +1,364 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
+const PLATFORM_ALIASES = {
+    ios: "ios",
+    swift: "ios",
+    android: "android",
+    kotlin: "android",
+    typescript: "typescript",
+    ts: "typescript",
+    javascript: "typescript",
+    "react-native": "typescript",
+    reactnative: "typescript",
+    flutter: "flutter",
+    dart: "flutter",
+};
+const CAPABILITIES = {
+    comments: {
+        required: [
+            { name: "CommentRepository", kind: "type" },
+            { name: "getComments", kind: "member", owner: "CommentRepository" },
+            { name: "createComment", kind: "member", owner: "CommentRepository" },
+        ],
+        optional: [
+            { name: "updateComment", kind: "member", owner: "CommentRepository" },
+            { name: "deleteComment", kind: "member", owner: "CommentRepository" },
+            { name: "flagComment", kind: "member", owner: "CommentRepository" },
+            { name: "unflagComment", kind: "member", owner: "CommentRepository" },
+            { name: "isCommentFlaggedByMe", kind: "member", owner: "CommentRepository" },
+        ],
+        models: [{ name: "Comment", kind: "model", owner: "Amity" }],
+    },
+    reactions: {
+        required: [
+            { name: "ReactionRepository", kind: "type" },
+            { name: "addReaction", kind: "member", owner: "ReactionRepository" },
+            { name: "removeReaction", kind: "member", owner: "ReactionRepository" },
+        ],
+        optional: [
+            { name: "getReactions", kind: "member", owner: "ReactionRepository" },
+            { name: "onReactionAdded", kind: "member", owner: "ReactionRepository" },
+            { name: "onReactionRemoved", kind: "member", owner: "ReactionRepository" },
+            { name: "myReactions", kind: "member", owner: "ReactionRepository" },
+        ],
+        models: [{ name: "Reaction", kind: "model", owner: "Amity" }],
+    },
+};
+export const getSdkFactsTool = {
+    name: "get_sdk_facts",
+    description: "Read bundled social.plus SDK surface facts for Block Factory planning. Projectless and read-only; answers symbol existence, not semantic correctness.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            platform: {
+                type: "string",
+                description: "SDK platform or alias: typescript, react-native, android, ios, flutter.",
+            },
+            capability: {
+                type: "string",
+                description: "Optional capability filter. Current MVP supports comments and reactions for the TypeScript/React Native surface.",
+            },
+            surfaceDir: {
+                type: "string",
+                description: "Optional directory containing manifest.json and platform JSON files. Defaults to SP_SDK_SURFACE_DIR, then bundled sdk-surface/.",
+            },
+            includeSymbols: {
+                type: "boolean",
+                description: "Include compact type/member symbol arrays. Defaults to false.",
+            },
+        },
+        required: ["platform"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await getSdkFacts({
+            platform: stringField(args, "platform"),
+            capability: optionalStringField(args, "capability"),
+            surfaceDir: optionalStringField(args, "surfaceDir"),
+            includeSymbols: optionalBooleanField(args, "includeSymbols"),
+        }));
+    },
+};
+export function canonicalPlatform(platform) {
+    return PLATFORM_ALIASES[platform.trim().toLowerCase()] ?? null;
+}
+export async function getSdkFacts(options) {
+    const platform = canonicalPlatform(options.platform);
+    if (!platform) {
+        throw new Error(`Unsupported SDK platform: ${options.platform}. Supported platforms: typescript, react-native, android, ios, flutter.`);
+    }
+    const surfaceLocation = resolveSurfaceDirectory(options.surfaceDir);
+    const manifest = await readJson(path.join(surfaceLocation.directory, "manifest.json"));
+    const entry = manifest.surfaces?.[platform];
+    const surfaceFile = entry?.file ?? `${platform}.json`;
+    const surface = await readJson(path.join(surfaceLocation.directory, surfaceFile));
+    const symbols = collectSymbols(platform, surface);
+    const capabilityIds = requestedCapabilityIds(platform, options.capability);
+    const capabilities = capabilityIds.map((id) => buildCapabilityFact(id, platform, symbols));
+    const result = {
+        source: "social-plus-vise",
+        mode: "block-factory-sdk-facts",
+        requestedPlatform: options.platform,
+        platform,
+        surfaceSource: {
+            kind: surfaceLocation.kind,
+            directory: surfaceLocation.directory,
+            manifestSource: manifest.source,
+            manifestSchemaVersion: manifest.schemaVersion,
+            upstreamGit: manifest.upstreamGit,
+            importedAt: manifest.importedAt,
+            remoteUrlStatus: "not-implemented",
+        },
+        sdkProduct: entry?.sdkProduct ?? stringProperty(surface, "sdk_product") ?? stringProperty(surface, "sdk_package"),
+        sdkVersion: entry?.sdkVersion ?? null,
+        extractor: entry?.extractor ?? stringProperty(surface, "extractor"),
+        extractorVersion: entry?.extractorVersion ?? stringProperty(surface, "extractor_version"),
+        extractedAt: entry?.extractedAt ?? stringProperty(surface, "extracted_at"),
+        symbolSummary: {
+            typeCount: symbols.types.length,
+            memberCount: symbols.members.length,
+        },
+        capabilities,
+        notes: [
+            "Existence-only facts: Vise confirms public symbols in the normalized SDK surface, but semantic correctness and idiomatic usage still require rules, docs, and sensors.",
+            "Remote SP_SDK_SURFACE_URL resolution is recorded in the manifest for a future online snapshot source; this MVP uses local override/env/bundled directories only.",
+        ],
+    };
+    if (options.includeSymbols) {
+        result.symbols = {
+            types: symbols.types,
+            members: symbols.members,
+        };
+    }
+    return result;
+}
+function resolveSurfaceDirectory(surfaceDir) {
+    if (surfaceDir) {
+        return { kind: "override", directory: path.resolve(surfaceDir) };
+    }
+    if (process.env.SP_SDK_SURFACE_DIR) {
+        return { kind: "env", directory: path.resolve(process.env.SP_SDK_SURFACE_DIR) };
+    }
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    return { kind: "bundled", directory: path.resolve(moduleDir, "..", "..", "sdk-surface") };
+}
+async function readJson(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to read SDK surface file ${filePath}: ${detail}`);
+    }
+}
+function requestedCapabilityIds(platform, capability) {
+    const available = Object.keys(CAPABILITIES);
+    if (!capability) {
+        return platform === "typescript" ? available : [];
+    }
+    const normalized = capability.trim().toLowerCase();
+    if (!available.includes(normalized)) {
+        throw new Error(`Unsupported SDK capability: ${capability}. Supported capabilities: ${available.join(", ")}.`);
+    }
+    if (platform !== "typescript") {
+        return [];
+    }
+    return [normalized];
+}
+function buildCapabilityFact(id, platform, symbols) {
+    const definition = CAPABILITIES[id];
+    const requiredSymbols = definition.required.map((symbol) => checkSymbol(symbols, { ...symbol, required: true }));
+    const optionalSymbols = definition.optional.map((symbol) => checkSymbol(symbols, { ...symbol, required: false }));
+    const models = definition.models.map((symbol) => checkSymbol(symbols, { ...symbol, required: false }));
+    const missingRequired = requiredSymbols.filter((symbol) => !symbol.exists);
+    return {
+        id,
+        support: missingRequired.length > 0 ? "missing-symbols" : "supported",
+        platform,
+        requiredSymbols,
+        optionalSymbols,
+        models,
+        notes: [
+            "Model facts are symbol-only in this MVP; field-level schemas need richer extractor output before they become contract-grade.",
+            ...(missingRequired.length > 0 ? [`Missing required symbol(s): ${missingRequired.map((symbol) => symbol.owner ? `${symbol.owner}.${symbol.name}` : symbol.name).join(", ")}.`] : []),
+        ],
+    };
+}
+function checkSymbol(symbols, spec) {
+    const haystack = spec.kind === "type" ? symbols.types : spec.kind === "member" ? symbols.members : symbols.types;
+    const match = haystack.find((symbol) => symbol.name === spec.name && (!spec.owner || symbol.owner === spec.owner || symbol.namespace === spec.owner));
+    return {
+        name: spec.name,
+        kind: spec.kind,
+        owner: spec.owner,
+        required: spec.required,
+        exists: Boolean(match),
+        source: match ? { file: match.file, line: match.line } : undefined,
+    };
+}
+function collectSymbols(platform, surface) {
+    if (platform === "typescript") {
+        return collectTypeScriptSymbols(surface);
+    }
+    return collectNativeSymbols(surface);
+}
+function collectTypeScriptSymbols(surface) {
+    const root = objectRecord(surface);
+    const types = [];
+    const members = [];
+    const namespaces = objectRecord(root.namespaces);
+    for (const [name, namespace] of Object.entries(namespaces)) {
+        collectTypeScriptNamespace(name, objectRecord(namespace), types, members);
+    }
+    for (const exportEntry of arrayRecords(root.root_exports)) {
+        if (typeof exportEntry.name === "string") {
+            types.push({
+                name: exportEntry.name,
+                kind: typeof exportEntry.kind === "string" ? exportEntry.kind : "export",
+                file: typeof exportEntry.file === "string" ? exportEntry.file : undefined,
+                line: typeof exportEntry.line === "number" ? exportEntry.line : null,
+            });
+        }
+    }
+    return sortSymbols(dedupeSymbols({ types, members }));
+}
+function collectTypeScriptNamespace(name, namespace, types, members) {
+    const sourceModule = typeof namespace.source_module === "string" ? namespace.source_module : undefined;
+    types.push({ name, kind: "namespace", file: sourceModule });
+    for (const member of arrayRecords(namespace.members)) {
+        const memberName = typeof member.name === "string" ? member.name : undefined;
+        if (!memberName) {
+            continue;
+        }
+        const symbol = {
+            name: memberName,
+            kind: typeof member.kind === "string" ? member.kind : "member",
+            owner: name,
+            namespace: typeof member.namespace === "string" ? member.namespace : name,
+            file: typeof member.file === "string" ? member.file : undefined,
+            line: typeof member.line === "number" ? member.line : null,
+        };
+        if (symbol.kind === "type" || symbol.kind === "interface" || symbol.kind === "enum" || symbol.kind === "class") {
+            types.push(symbol);
+        }
+        else {
+            members.push(symbol);
+        }
+    }
+    const subNamespaces = objectRecord(namespace.sub_namespaces);
+    for (const [subName, subNamespace] of Object.entries(subNamespaces)) {
+        collectTypeScriptNamespace(`${name}.${subName}`, objectRecord(subNamespace), types, members);
+    }
+}
+function collectNativeSymbols(surface) {
+    const root = objectRecord(surface);
+    const types = [];
+    const members = [];
+    for (const collectionName of ["types", "interfaces", "protocols", "mixins", "extensions", "typedefs", "typealiases", "global_typealiases"]) {
+        collectTypeMap(objectRecord(root[collectionName]), types, members);
+    }
+    for (const collectionName of ["global_funcs", "global_consts"]) {
+        for (const symbol of arrayRecords(root[collectionName])) {
+            const name = typeof symbol.name === "string" ? symbol.name : undefined;
+            if (name) {
+                members.push({
+                    name,
+                    kind: typeof symbol.kind === "string" ? symbol.kind : collectionName,
+                    file: sourceFile(symbol),
+                    line: sourceLine(symbol),
+                });
+            }
+        }
+    }
+    return sortSymbols(dedupeSymbols({ types, members }));
+}
+function collectTypeMap(typeMap, types, members) {
+    for (const [name, rawType] of Object.entries(typeMap)) {
+        const typeInfo = objectRecord(rawType);
+        types.push({
+            name,
+            kind: typeof typeInfo.kind === "string" ? typeInfo.kind : "type",
+            file: sourceFile(typeInfo),
+            line: sourceLine(typeInfo),
+        });
+        for (const member of arrayRecords(typeInfo.members)) {
+            const memberName = typeof member.name === "string" ? member.name : undefined;
+            if (!memberName) {
+                continue;
+            }
+            members.push({
+                name: memberName,
+                kind: typeof member.kind === "string" ? member.kind : "member",
+                owner: name,
+                file: sourceFile(member),
+                line: sourceLine(member),
+            });
+        }
+        for (const nestedType of arrayRecords(typeInfo.nested_types)) {
+            const nestedName = typeof nestedType.name === "string" ? nestedType.name : undefined;
+            if (!nestedName) {
+                continue;
+            }
+            const qualifiedName = `${name}.${nestedName}`;
+            types.push({
+                name: qualifiedName,
+                kind: typeof nestedType.kind === "string" ? nestedType.kind : "nested_type",
+                owner: name,
+                file: sourceFile(nestedType),
+                line: sourceLine(nestedType),
+            });
+        }
+    }
+}
+function sourceFile(value) {
+    if (typeof value.file === "string") {
+        return value.file;
+    }
+    const primaryDecl = objectRecord(value.primary_decl);
+    return typeof primaryDecl.file === "string" ? primaryDecl.file : undefined;
+}
+function sourceLine(value) {
+    if (typeof value.line === "number") {
+        return value.line;
+    }
+    const primaryDecl = objectRecord(value.primary_decl);
+    return typeof primaryDecl.line === "number" ? primaryDecl.line : null;
+}
+function stringProperty(value, property) {
+    const record = objectRecord(value);
+    return typeof record[property] === "string" ? record[property] : undefined;
+}
+function objectRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function arrayRecords(value) {
+    return Array.isArray(value) ? value.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)) : [];
+}
+function dedupeSymbols(symbols) {
+    return {
+        types: dedupeSymbolList(symbols.types),
+        members: dedupeSymbolList(symbols.members),
+    };
+}
+function dedupeSymbolList(symbols) {
+    const byKey = new Map();
+    for (const symbol of symbols) {
+        const key = `${symbol.owner ?? ""}:${symbol.namespace ?? ""}:${symbol.kind ?? ""}:${symbol.name}`;
+        if (!byKey.has(key)) {
+            byKey.set(key, symbol);
+        }
+    }
+    return [...byKey.values()];
+}
+function sortSymbols(symbols) {
+    return {
+        types: symbols.types.sort(compareSymbols),
+        members: symbols.members.sort(compareSymbols),
+    };
+}
+function compareSymbols(a, b) {
+    return `${a.owner ?? ""}.${a.name}`.localeCompare(`${b.owner ?? ""}.${b.name}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -40,11 +40,14 @@
     "CHANGELOG.md",
     "social.plus-vise.png",
     "rules",
-    "skills"
+    "skills",
+    "scripts",
+    "sdk-surface"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "postbuild": "chmod +x dist/server.js",
+    "sdk-surface:import": "node scripts/import-sdk-surface.mjs",
     "pack:check": "npm pack --dry-run --cache /tmp/social-plus-foundry-npm-cache",
     "publish:check": "npm run validate && npm publish --dry-run --access public --cache /tmp/social-plus-foundry-npm-cache",
     "start": "node dist/server.js",
@@ -60,9 +63,11 @@
     "test:fixture-symmetry": "npm run build && node test/run-fixture-symmetry.mjs",
     "test:nonui-skip": "npm run build && node test/run-nonui-layer-skip.mjs",
     "test:sdk-version": "npm run build && node test/run-sdk-version.mjs",
+    "test:sdk-surface": "node test/run-sdk-surface-snapshot.mjs",
+    "test:sdk-facts": "npm run build && node test/run-sdk-facts.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:e2e-package": "npm run build && node test/run-e2e-package.mjs",
-    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:design-brief && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run pack:check",
+    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:design-brief && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:sdk-surface && npm run test:sdk-facts && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run pack:check",
     "test:ast": "node test/run-ast-helpers.mjs",
     "test:design-extract": "npm run build && node test/run-design-extract.mjs",
     "test:design-brief": "npm run build && node test/run-design-brief.mjs",

package/scripts/import-sdk-surface.mjs

@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = path.join(repoRoot, "sdk-surface");
+const platforms = ["typescript", "android", "ios", "flutter"];
+const execFileAsync = promisify(execFile);
+
+function argValue(name) {
+  const idx = process.argv.indexOf(name);
+  return idx >= 0 ? process.argv[idx + 1] : undefined;
+}
+
+function defaultSourceDir() {
+  const candidates = [
+    process.env.SP_SDK_SURFACE_DIR,
+    path.resolve(repoRoot, "..", "..", "sp-sdks", "social-plus-docs", ".docs-ops", "sdk-surface"),
+    path.resolve(repoRoot, "..", "social-plus-docs", ".docs-ops", "sdk-surface"),
+  ].filter(Boolean);
+  return candidates.find((candidate) => existsSync(candidate)) || candidates[0];
+}
+
+function sourceMetadata(surface) {
+  return {
+    sdkProduct: surface.sdk_product || surface.sdk_package || null,
+    sdkVersion: surface.sdk_version || null,
+    extractor: surface.extractor || null,
+    extractorVersion: surface.extractor_version || null,
+    extractedAt: surface.extracted_at || null,
+    sourceUrl: surface.source_url || null,
+  };
+}
+
+function validateSurface(platform, surface) {
+  if (!surface || typeof surface !== "object" || Array.isArray(surface)) {
+    throw new Error(`${platform}.json must contain a JSON object`);
+  }
+  if (!surface.extractor || !surface.extractor_version || !surface.extracted_at) {
+    throw new Error(`${platform}.json is missing extractor, extractor_version, or extracted_at`);
+  }
+  const hasSymbols =
+    surface.types ||
+    surface.namespaces ||
+    surface.root_exports ||
+    surface.protocols ||
+    surface.interfaces ||
+    surface.extensions ||
+    surface.typedefs;
+  if (!hasSymbols) {
+    throw new Error(`${platform}.json does not look like a normalized SDK surface`);
+  }
+}
+
+async function gitMetadata(sourceDir) {
+  try {
+    const root = (await execFileAsync("git", ["-C", sourceDir, "rev-parse", "--show-toplevel"])).stdout.trim();
+    const commit = (await execFileAsync("git", ["-C", root, "rev-parse", "HEAD"])).stdout.trim();
+    const status = (await execFileAsync("git", ["-C", root, "status", "--short", "--", sourceDir])).stdout.trim();
+    return {
+      repo: path.basename(root),
+      commit,
+      dirty: Boolean(status),
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function readJson(file) {
+  return JSON.parse(await readFile(file, "utf8"));
+}
+
+async function sha256(file) {
+  return createHash("sha256").update(await readFile(file)).digest("hex");
+}
+
+async function main() {
+  const sourceDir = path.resolve(argValue("--from") || defaultSourceDir());
+  if (!sourceDir || !existsSync(sourceDir)) {
+    throw new Error(`SDK surface source dir does not exist: ${sourceDir}`);
+  }
+
+  await mkdir(outDir, { recursive: true });
+
+  const manifest = {
+    schemaVersion: "0.1.0",
+    source: "social-plus-docs/.docs-ops/sdk-surface",
+    upstreamGit: await gitMetadata(sourceDir),
+    importedAt: new Date().toISOString(),
+    resolutionOrder: [
+      "--surface-dir",
+      "SP_SDK_SURFACE_DIR",
+      "SP_SDK_SURFACE_URL",
+      "bundled sdk-surface/",
+    ],
+    surfaces: {},
+  };
+
+  for (const platform of platforms) {
+    const src = path.join(sourceDir, `${platform}.json`);
+    const dest = path.join(outDir, `${platform}.json`);
+    if (!existsSync(src)) {
+      throw new Error(`Missing SDK surface file: ${src}`);
+    }
+    const surface = await readJson(src);
+    validateSurface(platform, surface);
+    await copyFile(src, dest);
+    const bytes = (await readFile(dest)).byteLength;
+    manifest.surfaces[platform] = {
+      file: `${platform}.json`,
+      bytes,
+      sha256: await sha256(dest),
+      ...sourceMetadata(surface),
+    };
+  }
+
+  const manifestPath = path.join(outDir, "manifest.json");
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log(`imported ${platforms.length} SDK surfaces into ${path.relative(repoRoot, outDir)}`);
+}
+
+main().catch((error) => {
+  console.error(`sdk-surface import failed: ${error.message}`);
+  process.exit(1);
+});