@amityco/social-plus-vise 0.4.0

package/dist/tools/docs.js

@@ -0,0 +1,312 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { objectInput, optionalNumberField, stringField, textResult } from "../types.js";
+import { packageUserAgent } from "../version.js";
+const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
+const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000;
+const MIN_EXPECTED_PAGES = 10;
+let hostedCacheEntry;
+let hostedCachePending;
+function localDocsRoot() {
+    return process.env.SOCIAL_PLUS_DOCS_ROOT ? path.resolve(process.env.SOCIAL_PLUS_DOCS_ROOT) : undefined;
+}
+function docsBaseUrl() {
+    return (process.env.SOCIAL_PLUS_DOCS_BASE_URL ?? "https://learn.social.plus").replace(/\/+$/, "");
+}
+function fetchTimeoutMs() {
+    const raw = process.env.SOCIAL_PLUS_DOCS_FETCH_TIMEOUT_MS;
+    if (!raw) {
+        return DEFAULT_FETCH_TIMEOUT_MS;
+    }
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_FETCH_TIMEOUT_MS;
+}
+function cacheTtlMs() {
+    const raw = process.env.SOCIAL_PLUS_DOCS_CACHE_TTL_MS;
+    if (!raw) {
+        return DEFAULT_CACHE_TTL_MS;
+    }
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : DEFAULT_CACHE_TTL_MS;
+}
+export const searchDocsTool = {
+    name: "search_docs",
+    description: "Search social.plus documentation. For implementation requests, call plan_integration first so required inputs and stop conditions are known before docs lookup.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: { type: "string" },
+            limit: { type: "number", default: 5 },
+        },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const query = stringField(args, "query");
+        const limit = optionalNumberField(args, "limit", 5);
+        return textResult({ results: await searchDocs(query, limit) });
+    },
+};
+export const getDocPageTool = {
+    name: "get_doc_page",
+    description: "Read a single social.plus docs page by docs path.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+        },
+        required: ["path"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const requestedPath = stringField(args, "path");
+        const page = await getDocPage(requestedPath);
+        return textResult(page);
+    },
+};
+async function searchDocs(query, limit) {
+    const pages = await loadDocPages();
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const results = [];
+    for (const page of pages) {
+        const lower = page.content.toLowerCase();
+        const pathAndTitle = `${page.path} ${page.title}`.toLowerCase();
+        let score = terms.reduce((sum, term) => {
+            const contentScore = countOccurrences(lower, term);
+            const metadataScore = countOccurrences(pathAndTitle, term) * 25;
+            return sum + contentScore + metadataScore;
+        }, 0);
+        if (terms.every((term) => pathAndTitle.includes(term))) {
+            score += 100;
+        }
+        if (score === 0) {
+            continue;
+        }
+        results.push({
+            path: page.path,
+            title: page.title,
+            snippet: snippetFor(page.content, terms),
+            score,
+        });
+    }
+    return results
+        .sort((a, b) => b.score - a.score)
+        .slice(0, Math.max(1, Math.min(limit, 20)))
+        .map(({ score: _score, ...result }) => result);
+}
+async function getDocPage(requestedPath) {
+    const normalized = normalizeDocsPath(requestedPath);
+    const pages = await loadDocPages();
+    const page = pages.find((candidate) => normalizeDocsPath(candidate.path) === normalized);
+    if (!page) {
+        throw new Error(`Docs page not found: ${requestedPath}. Use search_docs to find the canonical path.`);
+    }
+    return page;
+}
+async function loadDocPages() {
+    const root = localDocsRoot();
+    if (root) {
+        return loadLocalDocPages(root);
+    }
+    const now = Date.now();
+    if (hostedCacheEntry && now - hostedCacheEntry.fetchedAt < cacheTtlMs()) {
+        return hostedCacheEntry.pages;
+    }
+    hostedCachePending ??= loadHostedDocPages()
+        .then((pages) => {
+        hostedCacheEntry = { pages, fetchedAt: Date.now() };
+        return pages;
+    })
+        .finally(() => {
+        hostedCachePending = undefined;
+    });
+    return hostedCachePending;
+}
+async function loadHostedDocPages() {
+    const baseUrl = docsBaseUrl();
+    const fullUrl = `${baseUrl}/llms-full.txt`;
+    const indexUrl = `${baseUrl}/llms.txt`;
+    const failures = [];
+    try {
+        const content = await fetchText(fullUrl);
+        return parseLlmsFull(content, baseUrl);
+    }
+    catch (error) {
+        failures.push(`${fullUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const content = await fetchText(indexUrl);
+        return parseLlmsIndex(content, baseUrl);
+    }
+    catch (error) {
+        failures.push(`${indexUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    throw new Error(`Failed to load social.plus docs from hosted sources.\n${failures.join("\n")}`);
+}
+async function loadLocalDocPages(root) {
+    const files = await findDocFiles(root);
+    return Promise.all(files.map(async (file) => {
+        const raw = await readFile(file, "utf8");
+        const content = cleanMdx(raw);
+        const relativePath = path.relative(root, file);
+        return {
+            path: normalizeDocsPath(relativePath),
+            title: titleFromContent(content, file),
+            content,
+        };
+    }));
+}
+async function fetchText(url) {
+    const timeoutMs = fetchTimeoutMs();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            headers: {
+                accept: "text/plain, text/markdown, */*",
+                "user-agent": packageUserAgent,
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch docs from ${url}: ${response.status} ${response.statusText}`);
+        }
+        return await response.text();
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`Timed out fetching docs from ${url} after ${timeoutMs}ms.`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export function parseLlmsFull(content, baseUrl) {
+    const pageHeading = /^### \[([^\]]+)\]\(([^)]+)\)\s*$/gm;
+    const matches = Array.from(content.matchAll(pageHeading));
+    const pages = [];
+    for (let index = 0; index < matches.length; index += 1) {
+        const match = matches[index];
+        const nextMatch = matches[index + 1];
+        const title = match[1].trim();
+        const url = absolutizeUrl(match[2].trim(), baseUrl);
+        const start = (match.index ?? 0) + match[0].length;
+        const end = nextMatch?.index ?? content.length;
+        const pageContent = content.slice(start, end).trim();
+        pages.push({
+            path: pathFromDocsUrl(url),
+            title,
+            url,
+            content: cleanMdx(`# ${title}\n\n${pageContent}`),
+        });
+    }
+    assertMinimumPages(pages, "llms-full.txt", "### [title](url)");
+    return pages;
+}
+export function parseLlmsIndex(content, baseUrl) {
+    const pageLine = /^- \[([^\]]+)\]\(([^)]+)\)(?::\s*(.*))?\s*$/gm;
+    const pages = [];
+    for (const match of content.matchAll(pageLine)) {
+        const title = match[1].trim();
+        const url = absolutizeUrl(match[2].trim(), baseUrl);
+        const summary = match[3]?.trim() || "No summary available.";
+        pages.push({
+            path: pathFromDocsUrl(url),
+            title,
+            url,
+            content: cleanMdx(`# ${title}\n\n${summary}`),
+        });
+    }
+    assertMinimumPages(pages, "llms.txt", "- [title](url)");
+    return pages;
+}
+function assertMinimumPages(pages, source, expectedFormat) {
+    if (pages.length < MIN_EXPECTED_PAGES) {
+        throw new Error(`Parsed only ${pages.length} pages from ${source}; expected at least ${MIN_EXPECTED_PAGES}. ` +
+            `The hosted docs format may have changed; the parser expects entries shaped like "${expectedFormat}".`);
+    }
+}
+function absolutizeUrl(url, baseUrl) {
+    return new URL(url, baseUrl).toString();
+}
+function pathFromDocsUrl(url) {
+    return normalizeDocsPath(new URL(url).pathname);
+}
+function normalizeDocsPath(docsPath) {
+    let normalized = docsPath.trim();
+    if (normalized.startsWith("http://") || normalized.startsWith("https://")) {
+        normalized = new URL(normalized).pathname;
+    }
+    normalized = normalized.replace(/^\/+/, "").replace(/\/+$/, "");
+    normalized = normalized.replace(/\.(md|mdx)$/i, "");
+    return normalized;
+}
+function safeDocsPath(root, relativePath) {
+    const fullPath = path.resolve(root, relativePath);
+    if (!fullPath.startsWith(root + path.sep)) {
+        throw new Error("Docs path must stay inside social-plus-docs.");
+    }
+    return fullPath;
+}
+async function findDocFiles(root) {
+    const files = [];
+    async function walk(directory) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".next") {
+                continue;
+            }
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+            }
+            else if (entry.name.endsWith(".md") || entry.name.endsWith(".mdx")) {
+                safeDocsPath(root, path.relative(root, entryPath));
+                files.push(entryPath);
+            }
+        }
+    }
+    await walk(root);
+    return files;
+}
+function cleanMdx(content) {
+    return content
+        .replace(/^---[\s\S]*?---\s*/m, "")
+        .replace(/^import .*$/gm, "")
+        .replace(/<[^>\n]+>/g, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function titleFromContent(content, file) {
+    const heading = content.match(/^#\s+(.+)$/m);
+    if (heading) {
+        return heading[1].trim();
+    }
+    return path.basename(file).replace(/\.(md|mdx)$/i, "");
+}
+function snippetFor(content, terms) {
+    const lower = content.toLowerCase();
+    const index = terms.map((term) => lower.indexOf(term)).filter((value) => value >= 0).sort((a, b) => a - b)[0] ?? 0;
+    const start = Math.max(0, index - 120);
+    const end = Math.min(content.length, index + 240);
+    return content.slice(start, end).replace(/\s+/g, " ").trim();
+}
+function countOccurrences(content, term) {
+    let count = 0;
+    let index = content.indexOf(term);
+    while (index >= 0) {
+        count += 1;
+        index = content.indexOf(term, index + term.length);
+    }
+    return count;
+}

package/dist/tools/harness.js

@@ -0,0 +1,229 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { classifyOutcome, getOutcomeDefinition } from "../outcomes.js";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { inspectProject } from "./project.js";
+export function harnessControlsFor(outcome, platforms) {
+    const docsQuery = getOutcomeDefinition(outcome).docsQuery(platforms[0] ?? "sdk");
+    return {
+        guides: [
+            {
+                name: "Resolve request",
+                kind: "guide",
+                execution: "computational",
+                timing: "before-change",
+                action: "resolve_request",
+                purpose: "Narrow the user's request into a known social.plus integration outcome.",
+            },
+            {
+                name: "Canonical docs",
+                kind: "guide",
+                execution: "computational",
+                timing: "before-change",
+                action: `search_docs query=\"${docsQuery}\"`,
+                purpose: "Load source-of-truth setup guidance before proposing code.",
+            },
+            {
+                name: "Integration plan",
+                kind: "guide",
+                execution: "inferential",
+                timing: "during-change",
+                action: "plan_integration",
+                purpose: "Give the coding agent an evidence-backed implementation packet before edits happen.",
+            },
+        ],
+        sensors: [
+            {
+                name: "Project inspection",
+                kind: "sensor",
+                execution: "computational",
+                timing: "before-change",
+                action: "inspect_project",
+                purpose: "Detect platform and framework signals from customer-owned files.",
+            },
+            {
+                name: "Setup validator",
+                kind: "sensor",
+                execution: "computational",
+                timing: "after-change",
+                action: "validate_setup",
+                purpose: "Catch common setup mistakes after the agent inspects or changes the app.",
+            },
+        ],
+        steeringLoop: [
+            "Resolve the request and inspect the project.",
+            "Fetch only the docs needed for the detected platform and outcome.",
+            "Generate a reviewable integration plan before edits.",
+            "Apply edits in the host coding agent, not inside Vise v1.",
+            "Run deterministic sensors first: setup validation and detected project checks.",
+            "Use inferential review only after deterministic signals are available.",
+        ],
+    };
+}
+export const planHarnessTool = {
+    name: "plan_harness",
+    description: "Build the feedforward guides, feedback sensors, and steering loop for a social.plus SDK integration request.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: {
+                type: "string",
+                description: "Absolute or relative path to the customer repository root.",
+            },
+            request: {
+                type: "string",
+                description: "Natural-language integration request.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath", "request"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const request = stringField(args, "request");
+        return textResult(await buildHarnessPlan(repoPath, request, optionalStringField(args, "surfacePath")));
+    },
+};
+async function buildHarnessPlan(repoPath, request, surfacePath) {
+    const inspection = await inspectProject(repoPath, surfacePath);
+    const outcome = classifyOutcome(request);
+    const controls = harnessControlsFor(outcome, inspection.platforms);
+    const commandSensors = await detectCommandSensors(inspection.effectiveRoot, inspection.platforms);
+    const harnessability = assessHarnessability(inspection.platforms, commandSensors, inspection.designSignals.length);
+    return {
+        outcome,
+        surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
+        availableSurfaces: inspection.surfaces.map((surface) => ({ path: surface.path, platforms: surface.platforms })),
+        targetPlatforms: inspection.platforms,
+        harnessability,
+        guides: controls.guides,
+        sensors: [...controls.sensors, ...commandSensors],
+        steeringLoop: controls.steeringLoop,
+    };
+}
+export async function detectCommandSensors(repoPath, platforms) {
+    const root = path.resolve(repoPath);
+    const sensors = [];
+    if (platforms.includes("typescript") || platforms.includes("react-native")) {
+        sensors.push(...(await packageJsonSensors(root)));
+    }
+    if (platforms.includes("android") && (await exists(path.join(root, "gradlew")))) {
+        sensors.push({
+            name: "Android assemble",
+            command: ["./gradlew", "assembleDebug"],
+            timing: "after-change",
+            purpose: "Check Android project compilation after SDK setup changes.",
+            source: "gradlew",
+        }, {
+            name: "Android unit tests",
+            command: ["./gradlew", "test"],
+            timing: "after-change",
+            purpose: "Run available Android JVM tests after integration changes.",
+            source: "gradlew",
+        });
+    }
+    if (platforms.includes("flutter")) {
+        sensors.push({
+            name: "Flutter analyze",
+            command: ["flutter", "analyze"],
+            timing: "after-change",
+            purpose: "Check Dart static analysis after SDK setup changes.",
+            source: "pubspec.yaml",
+        }, {
+            name: "Flutter tests",
+            command: ["flutter", "test"],
+            timing: "after-change",
+            purpose: "Run available Flutter tests after integration changes.",
+            source: "pubspec.yaml",
+        });
+    }
+    return sensors;
+}
+async function packageJsonSensors(root) {
+    const packageJsonPath = path.join(root, "package.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const scripts = parsed.scripts ?? {};
+    const preferredScripts = ["typecheck", "build", "test", "lint"];
+    const sensors = preferredScripts
+        .filter((script) => scripts[script])
+        .map((script) => ({
+        name: `npm ${script}`,
+        command: ["npm", "run", script],
+        timing: "after-change",
+        purpose: `Run the project's ${script} script as a deterministic feedback sensor.`,
+        source: "package.json",
+    }));
+    if (hasPackageDependency(parsed, "@amityco/ts-sdk")) {
+        sensors.push({
+            name: "TypeScript SDK import smoke",
+            command: [
+                "node",
+                "-e",
+                "require.resolve('@amityco/ts-sdk'); console.log('Vise smoke: @amityco/ts-sdk resolves')",
+            ],
+            timing: "after-change",
+            purpose: "Verify the social.plus TypeScript SDK resolves from the host project runtime environment.",
+            source: "package.json",
+        });
+    }
+    return sensors;
+}
+function hasPackageDependency(packageJson, dependencyName) {
+    return Boolean(packageJson.dependencies?.[dependencyName] ??
+        packageJson.devDependencies?.[dependencyName] ??
+        packageJson.peerDependencies?.[dependencyName] ??
+        packageJson.optionalDependencies?.[dependencyName]);
+}
+function assessHarnessability(platforms, commandSensors, designSignalCount) {
+    const affordances = [];
+    const gaps = [];
+    if (platforms.length > 0) {
+        affordances.push(`Detected platform signals: ${platforms.join(", ")}.`);
+    }
+    else {
+        gaps.push("No platform signals detected; ask the user for the app framework or repository root.");
+    }
+    if (platforms.some((platform) => ["typescript", "react-native", "android", "flutter"].includes(platform))) {
+        affordances.push("Detected a platform with deterministic setup checks available in Vise.");
+    }
+    if (commandSensors.length > 0) {
+        affordances.push(`Detected ${commandSensors.length} project command sensor(s).`);
+    }
+    else {
+        gaps.push("No project build/typecheck/test command sensors were detected yet.");
+    }
+    if (designSignalCount > 0) {
+        affordances.push(`Detected ${designSignalCount} design/theme signal(s) for UI integration grounding.`);
+    }
+    if (platforms.includes("ios")) {
+        gaps.push("iOS support is guided until deterministic validators are expanded.");
+    }
+    if (platforms.length === 0) {
+        return { level: "weak", affordances, gaps };
+    }
+    return {
+        level: commandSensors.length > 0 ? "strong" : "moderate",
+        affordances,
+        gaps,
+    };
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}