@amityco/social-plus-vise 0.4.0

package/dist/server.js

@@ -0,0 +1,810 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, initCompliance, initComplianceTool, initEngagement, initEngagementTool, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
+import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
+import { planHarnessTool } from "./tools/harness.js";
+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 { packageName, packageVersion } from "./version.js";
+const tools = new Map([
+    searchDocsTool,
+    getDocPageTool,
+    inspectProjectTool,
+    planHarnessTool,
+    planIntegrationTool,
+    initComplianceTool,
+    checkComplianceTool,
+    syncComplianceTool,
+    attestRuleTool,
+    explainRuleTool,
+    initEngagementTool,
+    showEngagementTool,
+    resolveRequestTool,
+    runSensorsTool,
+    validateSetupTool,
+    suggestPatchTool,
+].map((tool) => [tool.name, tool]));
+const bundledSkillName = "social-plus-vise";
+const cliResult = await handleCli(process.argv.slice(2));
+if (cliResult === "exit") {
+    process.exitCode = process.exitCode ?? 0;
+}
+else {
+    const server = new Server({
+        name: "social-plus-vise",
+        version: packageVersion,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: Array.from(tools.values()).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const tool = tools.get(request.params.name);
+        if (!tool) {
+            throw new Error(`Unknown tool: ${request.params.name}`);
+        }
+        return tool.call(request.params.arguments);
+    });
+    await server.connect(new StdioServerTransport());
+}
+async function handleCli(args) {
+    const command = args[0];
+    if (!command) {
+        return "serve";
+    }
+    if (command === "mcp" || command === "serve" || command === "start") {
+        return "serve";
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(`${packageName} ${packageVersion}`);
+        return "exit";
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        console.log(helpText(args[1]));
+        return "exit";
+    }
+    if (command === "doctor" || command === "--doctor") {
+        console.log(JSON.stringify(doctorResult(), null, 2));
+        return "exit";
+    }
+    if (isHelpRequest(args)) {
+        console.log(helpText(command));
+        return "exit";
+    }
+    try {
+        if (command === "install-skill" || command === "install_skill") {
+            console.log(JSON.stringify(await installSkill(args.slice(1)), null, 2));
+            return "exit";
+        }
+        if (command === "print-skill" || command === "print_skill") {
+            console.log(await readFile(path.join(skillSourceDir(), "SKILL.md"), "utf8"));
+            return "exit";
+        }
+        if (command === "skill-path" || command === "skill_path") {
+            console.log(JSON.stringify(skillPathResult(), null, 2));
+            return "exit";
+        }
+        if (command === "search-docs" || command === "search_docs") {
+            await printToolResult(searchDocsTool, {
+                query: flagValue(args, "query") ?? requiredPositionalText(args.slice(1), "search-docs requires a query."),
+                limit: optionalNumberFlag(args, "limit"),
+            });
+            return "exit";
+        }
+        if (command === "get-doc-page" || command === "get_doc_page") {
+            await printToolResult(getDocPageTool, {
+                path: flagValue(args, "path") ?? requiredPositionalText(args.slice(1), "get-doc-page requires a docs path."),
+            });
+            return "exit";
+        }
+        if (command === "inspect") {
+            await printToolResult(inspectProjectTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+            });
+            return "exit";
+        }
+        if (command === "plan" || command === "plan-integration") {
+            await printToolResult(planIntegrationTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                request: requiredFlagValue(args, "request", "plan requires --request."),
+                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+                answers: keyValueFlag(args, "answer"),
+            });
+            return "exit";
+        }
+        if (command === "plan-harness") {
+            await printToolResult(planHarnessTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                request: requiredFlagValue(args, "request", "plan-harness requires --request."),
+                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+            });
+            return "exit";
+        }
+        if (command === "validate" || command === "validate-setup") {
+            await printToolResult(validateSetupTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                platform: flagValue(args, "platform"),
+                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+            });
+            return "exit";
+        }
+        if (command === "run-sensors" || command === "run_sensor" || command === "run-sensor") {
+            await printToolResult(runSensorsTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                request: flagValue(args, "request"),
+                include: flagValues(args, "include"),
+                timeoutMs: optionalNumberFlag(args, "timeout-ms"),
+                dryRun: hasFlag(args, "dry-run"),
+                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+            });
+            return "exit";
+        }
+        if (command === "resolve") {
+            await printToolResult(resolveRequestTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                request: requiredFlagValue(args, "request", "resolve requires --request."),
+                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+            });
+            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));
+            return "exit";
+        }
+        if (command === "check") {
+            assertOnlyKnownFlags(args, ["ci"], "check");
+            const result = await checkCompliance(positionalRepoPath(args.slice(1)));
+            console.log(JSON.stringify(hasFlag(args, "ci") ? ciCheckResult(result) : result, null, 2));
+            process.exitCode = result.exitCode;
+            return "exit";
+        }
+        if (command === "sync") {
+            assertOnlyKnownFlags(args, [], "sync");
+            console.log(JSON.stringify(await syncCompliance(positionalRepoPath(args.slice(1))), null, 2));
+            return "exit";
+        }
+        if (command === "attest") {
+            assertOnlyKnownFlags(args, ["rule", "confidence", "signer", "identity", "rationale", "evidence-file"], "attest");
+            console.log(JSON.stringify(await attestRule({
+                repoPath: positionalRepoPath(args.slice(1)),
+                ruleId: requiredFlagValue(args, "rule", "attest requires --rule."),
+                confidence: requiredConfidence(args),
+                signer: requiredSigner(args),
+                identity: flagValue(args, "identity"),
+                rationale: requiredFlagValue(args, "rationale", "attest requires --rationale."),
+                evidence: await evidenceFromArgs(args),
+            }), null, 2));
+            return "exit";
+        }
+        if (command === "explain") {
+            assertOnlyKnownFlags(args, [], "explain");
+            console.log(JSON.stringify(await explainRule(requiredPositionalText(args.slice(1), "explain requires a rule id.")), null, 2));
+            return "exit";
+        }
+        if (command === "status") {
+            assertOnlyKnownFlags(args, [], "status");
+            console.log(JSON.stringify(await statusCompliance(positionalRepoPath(args.slice(1))), null, 2));
+            return "exit";
+        }
+        if (command === "engagement") {
+            const sub = args[1];
+            const subArgs = args.slice(2);
+            if (sub === "init") {
+                assertOnlyKnownFlags(subArgs, ["tier", "customer-id", "scope", "target-completion", "reviewer-name", "reviewer-email", "evidence-upload-consent"], "engagement init");
+                console.log(JSON.stringify(await initEngagement({
+                    repoPath: positionalRepoPath(subArgs),
+                    tier: flagValue(subArgs, "tier"),
+                    customerId: flagValue(subArgs, "customer-id"),
+                    scope: flagValues(subArgs, "scope").flatMap((value) => value.split(",").map((entry) => entry.trim()).filter(Boolean)),
+                    targetCompletionDate: flagValue(subArgs, "target-completion"),
+                    reviewerName: flagValue(subArgs, "reviewer-name"),
+                    reviewerEmail: flagValue(subArgs, "reviewer-email"),
+                    evidenceUploadConsent: hasFlag(subArgs, "evidence-upload-consent"),
+                }), null, 2));
+                return "exit";
+            }
+            if (sub === "show") {
+                assertOnlyKnownFlags(subArgs, [], "engagement show");
+                console.log(JSON.stringify(await showEngagement(positionalRepoPath(subArgs)), null, 2));
+                return "exit";
+            }
+            console.error(`Unknown engagement subcommand: ${sub ?? "(none)"}. Expected "init" or "show".`);
+            process.exitCode = 1;
+            return "exit";
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return "exit";
+    }
+    if (command.startsWith("-")) {
+        console.error(`Unknown option: ${command}`);
+        console.error("Run with --help for usage.");
+        process.exitCode = 1;
+        return "exit";
+    }
+    console.error(`Unknown command: ${command}`);
+    console.error("Run with --help for usage.");
+    process.exitCode = 1;
+    return "exit";
+}
+function helpText(command) {
+    if (command === "inspect") {
+        return `${packageName} inspect
+
+Inspect a customer repository and detect platform, app surface, and design-system signals.
+
+Usage:
+  vise inspect [repoPath] [--surface apps/web]
+  vise inspect [repoPath] [--surface apps/web]`;
+    }
+    if (command === "plan" || command === "plan-integration") {
+        return `${packageName} plan
+
+Create the evidence-backed implementation packet before editing code.
+
+Usage:
+  vise plan [repoPath] --request "Add a social feed"
+  vise plan apps/web --request "Create posts" --surface apps/web
+
+Re-plan with collected answers (repeat --answer for each intake question):
+  vise plan . --request "Add a social feed" \\
+    --answer feed_scope=community \\
+    --answer feed_target=existing\\ communityId \\
+    --answer target_screen_or_route=app/feed/page.tsx`;
+    }
+    if (command === "plan-harness") {
+        return `${packageName} plan-harness
+
+Create a harness guide/sensor plan for the requested SDK integration.
+
+Usage:
+  vise plan-harness [repoPath] --request "Add a social feed"
+  vise plan-harness apps/web --request "Set up notifications" --surface apps/web`;
+    }
+    if (command === "search-docs" || command === "search_docs") {
+        return `${packageName} search-docs
+
+Search social.plus documentation from the hosted llms source, or SOCIAL_PLUS_DOCS_ROOT for maintainers.
+
+Usage:
+  vise search-docs "create text post"
+  vise search-docs --query "Live Collection cleanup" --limit 3`;
+    }
+    if (command === "install-skill" || command === "install_skill") {
+        return `${packageName} install-skill
+
+Install the bundled social.plus Vise skill for a host AI coding tool.
+
+Usage:
+  vise install-skill --target codex
+  vise install-skill --target claude
+  vise install-skill --target claude-project .
+  vise install-skill --target agents .
+  vise install-skill --target cursor .
+  vise install-skill --target cursor-rules .
+  vise install-skill --target vscode .
+  vise install-skill --target copilot .
+  vise install-skill --dest ~/.codex/skills
+  vise install-skill --dest ~/.codex/skills --force
+
+Targets:
+  codex   Installs to ~/.codex/skills/social-plus-vise
+  claude  Installs to ~/.claude/skills/social-plus-vise
+  claude-project Installs to <repoPath>/.claude/skills/social-plus-vise
+  agents  Installs to <repoPath>/.agents/skills/social-plus-vise
+  cursor  Installs to <repoPath>/.cursor/skills/social-plus-vise
+  vscode  Installs to <repoPath>/.github/skills/social-plus-vise
+  copilot Installs to <repoPath>/.github/skills/social-plus-vise
+  cursor-rules Writes <repoPath>/.cursor/rules/social-plus-vise.mdc
+  custom  Use --dest <skillsRoot or exact skill directory>`;
+    }
+    if (command === "print-skill" || command === "print_skill") {
+        return `${packageName} print-skill
+
+Print the bundled social.plus Vise skill markdown to stdout.
+
+Usage:
+  vise print-skill`;
+    }
+    if (command === "skill-path" || command === "skill_path") {
+        return `${packageName} skill-path
+
+Print the bundled skill source path and supported install targets.
+
+Usage:
+  vise skill-path`;
+    }
+    if (command === "get-doc-page" || command === "get_doc_page") {
+        return `${packageName} get-doc-page
+
+Read one social.plus documentation page by canonical docs path.
+
+Usage:
+  vise get-doc-page social-plus-sdk/social/content-management/posts/creation/text-post
+  vise get-doc-page --path uikit/getting-started/installation`;
+    }
+    if (command === "validate" || command === "validate-setup") {
+        return `${packageName} validate
+
+Run deterministic social.plus setup validation for the current project.
+
+Usage:
+  vise validate [repoPath] [--platform typescript] [--surface apps/web]`;
+    }
+    if (command === "run-sensors" || command === "run-sensor" || command === "run_sensor") {
+        return `${packageName} run-sensors
+
+Run detected project command sensors such as typecheck, test, build, Flutter, or Gradle checks.
+
+Usage:
+  vise run-sensors [repoPath] [--dry-run] [--include "npm test"] [--timeout-ms 120000]`;
+    }
+    if (command === "resolve") {
+        return `${packageName} resolve
+
+Resolve a natural-language request into the closest supported Vise outcome.
+
+Usage:
+  vise resolve [repoPath] --request "Add a social feed"`;
+    }
+    if (command === "init") {
+        return `${packageName} init
+
+Initialize the local sp-vise compliance sidecar for one integration request.
+
+Usage:
+  vise init [repoPath] --request "Add a social feed" [--surface apps/web]`;
+    }
+    if (command === "check") {
+        return `${packageName} check
+
+Check the current source and recorded attestations against the compliance contract. Read-only.
+
+Usage:
+  vise check [repoPath] [--ci]`;
+    }
+    if (command === "sync") {
+        return `${packageName} sync
+
+Persist deterministic-pass compliance evidence into sp-vise/attestations.
+
+Usage:
+  vise sync [repoPath]`;
+    }
+    if (command === "attest") {
+        return `${packageName} attest
+
+Record a host-agent or local-human attestation for one compliance rule.
+
+Usage:
+  vise attest [repoPath] --rule sdk.init.at-startup --confidence high --signer host-agent --evidence-file evidence.json --rationale "Why this rule is satisfied."`;
+    }
+    if (command === "explain") {
+        return `${packageName} explain
+
+Explain one compliance rule.
+
+Usage:
+  vise explain sdk.init.at-startup`;
+    }
+    if (command === "status") {
+        return `${packageName} status
+
+Print a compact compliance summary.
+
+Usage:
+  vise status [repoPath]`;
+    }
+    return `${packageName}
+
+Skill-guided deterministic CLI for social.plus SDK integration assistance.
+
+Usage:
+  vise mcp                         Start the stdio MCP server
+  vise search-docs "query"         Search hosted social.plus docs
+  vise get-doc-page "path"         Read a canonical docs page
+  vise install-skill --target codex Install bundled skill guidance
+  vise print-skill                 Print bundled skill markdown
+  vise inspect [repoPath]          Inspect platform and design signals
+  vise plan [repoPath] --request "..." Create an implementation plan
+  vise init [repoPath] --request "..." Initialize compliance sidecar
+  vise check [repoPath]            Check compliance contract
+  vise sync [repoPath]             Persist deterministic-pass evidence
+  vise attest [repoPath] --rule ... Record a compliance attestation
+  vise explain <ruleId>            Explain one compliance rule
+  vise status [repoPath]           Print compliance summary
+  vise validate [repoPath]         Validate setup and common risks
+  vise run-sensors [repoPath]      Run detected project sensors
+  vise doctor                      Print install diagnostics
+  vise --help                      Show this help
+  vise --version                   Show package version
+
+Compatibility aliases:
+  spf, social-plus-vise, foundry, social-plus-foundry, foundry-mcp
+
+MCP config:
+  {
+    "mcpServers": {
+      "social-plus": {
+        "command": "vise",
+        "args": ["mcp"]
+      }
+    }
+  }
+
+Customers do not need environment variables. Maintainers may set
+SOCIAL_PLUS_DOCS_ROOT to test against a local social-plus-docs checkout.`;
+}
+async function printToolResult(tool, input) {
+    const result = await tool.call(input);
+    console.log(result.content.map((item) => item.text).join("\n"));
+}
+async function installSkill(args) {
+    const source = skillSourceDir();
+    const instructionInstall = instructionInstallDestination(args);
+    if (instructionInstall) {
+        return installInstructionFile(instructionInstall, args);
+    }
+    const destination = skillInstallDestination(args);
+    const force = hasFlag(args, "force");
+    const installedFiles = await copyDirectory(source, destination, force);
+    return {
+        status: installedFiles.length > 0 ? "installed" : "already-current",
+        skill: bundledSkillName,
+        source,
+        destination,
+        force,
+        installedFiles,
+        nextStep: "Restart or reload the host AI coding tool so it discovers the installed skill.",
+    };
+}
+async function installInstructionFile(target, args) {
+    const force = hasFlag(args, "force");
+    const source = path.join(skillSourceDir(), "SKILL.md");
+    const content = await readFile(source, "utf8");
+    if (await fileExists(target.destination)) {
+        const existing = await readFile(target.destination, "utf8");
+        if (existing === content) {
+            return {
+                status: "already-current",
+                skill: bundledSkillName,
+                host: target.host,
+                source,
+                destination: target.destination,
+                force,
+                installedFiles: [],
+                nextStep: "Restart or reload the host AI coding tool so it discovers the updated project instructions.",
+            };
+        }
+        if (!force) {
+            throw new Error(`Instruction file already exists with different content: ${target.destination}. Re-run with --force to overwrite.`);
+        }
+    }
+    await mkdir(path.dirname(target.destination), { recursive: true });
+    await writeFile(target.destination, content, "utf8");
+    return {
+        status: "installed",
+        skill: bundledSkillName,
+        host: target.host,
+        source,
+        destination: target.destination,
+        force,
+        installedFiles: [target.destination],
+        nextStep: "Restart or reload the host AI coding tool so it discovers the updated project instructions.",
+    };
+}
+function instructionInstallDestination(args) {
+    const target = flagValue(args, "target");
+    if (target !== "cursor-rules" && target !== "cursor-rule") {
+        return undefined;
+    }
+    const repoRoot = path.resolve(positionalRepoPath(args));
+    return {
+        host: "cursor-rules",
+        destination: path.join(repoRoot, ".cursor", "rules", "social-plus-vise.mdc"),
+    };
+}
+function skillInstallDestination(args) {
+    const destArg = flagValue(args, "dest") ?? flagValue(args, "destination") ?? flagValue(args, "path");
+    if (destArg) {
+        const resolved = path.resolve(expandHome(destArg));
+        return path.basename(resolved) === bundledSkillName ? resolved : path.join(resolved, bundledSkillName);
+    }
+    const target = flagValue(args, "target") ?? "codex";
+    if (target === "codex") {
+        return path.join(os.homedir(), ".codex", "skills", bundledSkillName);
+    }
+    if (target === "claude") {
+        return path.join(os.homedir(), ".claude", "skills", bundledSkillName);
+    }
+    if (target === "claude-project") {
+        return path.resolve(positionalRepoPath(args), ".claude", "skills", bundledSkillName);
+    }
+    if (target === "agents" || target === "project") {
+        return path.resolve(positionalRepoPath(args), ".agents", "skills", bundledSkillName);
+    }
+    if (target === "cursor") {
+        return path.resolve(positionalRepoPath(args), ".cursor", "skills", bundledSkillName);
+    }
+    if (target === "vscode" || target === "copilot") {
+        return path.resolve(positionalRepoPath(args), ".github", "skills", bundledSkillName);
+    }
+    if (target === "custom") {
+        throw new Error("install-skill --target custom requires --dest <skillsRoot or exact skill directory>.");
+    }
+    throw new Error(`Unsupported skill target: ${target}. Supported targets: codex, claude, claude-project, agents, cursor, cursor-rules, vscode, copilot, custom.`);
+}
+function skillPathResult() {
+    return {
+        skill: bundledSkillName,
+        source: skillSourceDir(),
+        files: ["SKILL.md"],
+        installExamples: [
+            "vise install-skill --target codex",
+            "vise install-skill --target claude",
+            "vise install-skill --target claude-project .",
+            "vise install-skill --target agents .",
+            "vise install-skill --target cursor .",
+            "vise install-skill --target cursor-rules .",
+            "vise install-skill --target vscode .",
+            "vise install-skill --target copilot .",
+            "vise install-skill --dest ~/.codex/skills",
+            "vise print-skill",
+        ],
+    };
+}
+function skillSourceDir() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(moduleDir, "..", "skills", bundledSkillName);
+}
+async function copyDirectory(source, destination, force) {
+    const installedFiles = [];
+    await mkdir(destination, { recursive: true });
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(source, entry.name);
+        const destinationPath = path.join(destination, entry.name);
+        if (entry.isDirectory()) {
+            installedFiles.push(...(await copyDirectory(sourcePath, destinationPath, force)));
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (await fileExists(destinationPath)) {
+            const [sourceContent, destinationContent] = await Promise.all([readFile(sourcePath, "utf8"), readFile(destinationPath, "utf8")]);
+            if (sourceContent === destinationContent) {
+                continue;
+            }
+            if (!force) {
+                throw new Error(`Skill file already exists with different content: ${destinationPath}. Re-run with --force to overwrite.`);
+            }
+        }
+        await copyFile(sourcePath, destinationPath);
+        installedFiles.push(destinationPath);
+    }
+    return installedFiles;
+}
+async function fileExists(filePath) {
+    try {
+        return (await stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function expandHome(input) {
+    if (input === "~") {
+        return os.homedir();
+    }
+    if (input.startsWith("~/")) {
+        return path.join(os.homedir(), input.slice(2));
+    }
+    return input;
+}
+function isHelpRequest(args) {
+    return args.includes("--help") || args.includes("-h");
+}
+function assertOnlyKnownFlags(args, allowed, commandName) {
+    const allowedSet = new Set(allowed);
+    const unknown = [];
+    for (const arg of args) {
+        if (!arg.startsWith("--")) {
+            continue;
+        }
+        const flagName = arg.slice(2).split("=")[0];
+        if (!flagName) {
+            continue;
+        }
+        if (!allowedSet.has(flagName)) {
+            unknown.push(`--${flagName}`);
+        }
+    }
+    if (unknown.length === 0) {
+        return;
+    }
+    const allowedList = allowed.length > 0 ? `Allowed flags: ${allowed.map((flag) => `--${flag}`).join(", ")}.` : "This command takes no flags.";
+    throw new Error(`${commandName} does not accept ${unknown.join(", ")}. ${allowedList} Run \`vise ${commandName} --help\` for usage.`);
+}
+function ciCheckResult(result) {
+    return {
+        ...result,
+        ci: {
+            enabled: true,
+            passed: result.exitCode === 0,
+            exitCode: result.exitCode,
+            blockingResultStatuses: ["contract-drift", "blocked", "deterministic-failures", "needs-attestation"],
+            message: result.exitCode === 0 ? "Compliance green for CI." : `Compliance failed for CI with status: ${result.status}.`,
+        },
+    };
+}
+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"]);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const flagName = arg.slice(2).split("=")[0];
+            if (!arg.includes("=") && flagsWithValues.has(flagName)) {
+                index += 1;
+            }
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            continue;
+        }
+        return arg;
+    }
+    return ".";
+}
+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"]);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const flagName = arg.slice(2).split("=")[0];
+            if (!arg.includes("=") && flagsWithValues.has(flagName)) {
+                index += 1;
+            }
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            values.push(arg);
+        }
+    }
+    const text = values.join(" ").trim();
+    if (!text) {
+        throw new Error(message);
+    }
+    return text;
+}
+function flagValue(args, name) {
+    const equalsPrefix = `--${name}=`;
+    const equalsArg = args.find((arg) => arg.startsWith(equalsPrefix));
+    if (equalsArg) {
+        return equalsArg.slice(equalsPrefix.length);
+    }
+    const index = args.indexOf(`--${name}`);
+    const value = index >= 0 ? args[index + 1] : undefined;
+    return value && !value.startsWith("-") ? value : undefined;
+}
+function flagValues(args, name) {
+    const values = [];
+    const equalsPrefix = `--${name}=`;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg?.startsWith(equalsPrefix)) {
+            values.push(arg.slice(equalsPrefix.length));
+        }
+        else if (arg === `--${name}`) {
+            const value = args[index + 1];
+            if (value && !value.startsWith("-")) {
+                values.push(value);
+            }
+        }
+    }
+    return values;
+}
+function requiredFlagValue(args, name, message) {
+    const value = flagValue(args, name);
+    if (!value) {
+        throw new Error(message);
+    }
+    return value;
+}
+function optionalNumberFlag(args, name) {
+    const value = flagValue(args, name);
+    if (!value) {
+        return undefined;
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        throw new Error(`--${name} must be a number.`);
+    }
+    return number;
+}
+function hasFlag(args, name) {
+    return args.includes(`--${name}`);
+}
+function keyValueFlag(args, name) {
+    const pairs = flagValues(args, name);
+    const result = {};
+    for (const pair of pairs) {
+        const equalsIndex = pair.indexOf("=");
+        if (equalsIndex <= 0) {
+            throw new Error(`--${name} must be key=value (got "${pair}").`);
+        }
+        const key = pair.slice(0, equalsIndex).trim();
+        const value = pair.slice(equalsIndex + 1).trim();
+        if (!key || !value) {
+            throw new Error(`--${name} must be key=value (got "${pair}").`);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function requiredConfidence(args) {
+    const value = requiredFlagValue(args, "confidence", "attest requires --confidence high|medium|low.");
+    if (value === "high" || value === "medium" || value === "low") {
+        return value;
+    }
+    throw new Error("--confidence must be high, medium, or low.");
+}
+function requiredSigner(args) {
+    const value = requiredFlagValue(args, "signer", "attest requires --signer host-agent|human.");
+    if (value === "host-agent" || value === "human") {
+        return value;
+    }
+    throw new Error("--signer must be host-agent or human.");
+}
+async function evidenceFromArgs(args) {
+    const evidenceFile = flagValue(args, "evidence-file");
+    if (!evidenceFile) {
+        throw new Error("attest requires --evidence-file.");
+    }
+    const parsed = JSON.parse(await readFile(path.resolve(evidenceFile), "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("--evidence-file must contain a JSON object.");
+    }
+    return parsed;
+}
+function doctorResult() {
+    const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    return {
+        package: packageName,
+        version: packageVersion,
+        status: nodeMajor >= 18 ? "ok" : "unsupported-node",
+        node: process.versions.node,
+        requiredNodeMajor: ">=18",
+        docsSource: process.env.SOCIAL_PLUS_DOCS_ROOT ? "local" : "hosted",
+        docsRoot: process.env.SOCIAL_PLUS_DOCS_ROOT,
+        docsBaseUrl: process.env.SOCIAL_PLUS_DOCS_BASE_URL ?? "https://learn.social.plus",
+        transport: "stdio",
+        tools: Array.from(tools.keys()),
+    };
+}