@amityco/social-plus-vise 0.14.0 → 0.14.2

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.0",
+  "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);
+});