@ericsanchezok/synergy-plugin-kit 2.2.1

package/dist/lib/market-entry.d.ts

@@ -0,0 +1,57 @@
+import { type PluginManifest as PluginManifestType } from "@ericsanchezok/synergy-plugin";
+export interface GithubRegistryEntry {
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    description: string;
+    repo: string;
+    homepage?: string;
+    author: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    verified: boolean;
+    official: boolean;
+    keywords: string[];
+    compatibility: {
+        synergy: string;
+    };
+    versions: Array<{
+        version: string;
+        downloadUrl: string;
+        signatureUrl: string;
+        integrity: string;
+        manifestHash: string;
+        permissionsHash: string;
+        risk: "low" | "medium" | "high";
+        runtimeMode: "in-process" | "worker" | "process";
+        permissionsSummary: Array<{
+            key: string;
+            description: string;
+            risk: string;
+        }>;
+        tools: string[];
+        uiSurfaces: string[];
+        publishedAt: string;
+        changelog?: string;
+    }>;
+    yankedVersions: string[];
+}
+export declare function parseAuthor(input?: string): GithubRegistryEntry["author"];
+export declare function normalizeRepoUrl(input?: string): string | undefined;
+export declare function githubRepoSlug(input?: string): string | undefined;
+export declare function releaseAssetUrl(repo: string | undefined, version: string, filename: string): string | undefined;
+export declare function readTarballManifest(tarballPath: string): PluginManifestType;
+export declare function uiSurfaces(manifest: PluginManifestType): string[];
+export declare function githubEntry(input: {
+    tarballPath: string;
+    repo?: string;
+    downloadUrl?: string;
+    signatureUrl?: string;
+    verified?: boolean;
+    official?: boolean;
+    changelog?: string;
+    publishedAt?: string;
+}): GithubRegistryEntry;
+export declare function writeGithubEntry(filepath: string, next: GithubRegistryEntry): GithubRegistryEntry;

package/dist/lib/market-entry.js

@@ -0,0 +1,181 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { PluginManifest } from "@ericsanchezok/synergy-plugin";
+import { baseCapabilities } from "./capability";
+import { computeManifestHash, computePermissionsHash } from "./hash";
+import { computeRisk } from "./risk";
+import { resolveRuntimeMode } from "./runtime-mode";
+import { readSignatureFile } from "./signature";
+import { sha256File } from "./crypto";
+export function parseAuthor(input) {
+    if (!input)
+        return { name: "unknown" };
+    const email = input.match(/<([^>]+)>/)?.[1];
+    const url = input.match(/\(([^)]+)\)/)?.[1];
+    const name = input
+        .replace(/<[^>]+>/g, "")
+        .replace(/\([^)]+\)/g, "")
+        .trim() || input;
+    return { name, ...(email ? { email } : {}), ...(url ? { url } : {}) };
+}
+export function normalizeRepoUrl(input) {
+    if (!input)
+        return undefined;
+    const trimmed = input.trim();
+    const gitSsh = trimmed.match(/^git@github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
+    if (gitSsh)
+        return `https://github.com/${gitSsh[1]}`;
+    if (/^https:\/\/github\.com\/[^/]+\/[^/]+/.test(trimmed))
+        return trimmed.replace(/\.git$/, "");
+    return trimmed;
+}
+export function githubRepoSlug(input) {
+    const normalized = normalizeRepoUrl(input);
+    if (!normalized)
+        return undefined;
+    const match = normalized.match(/^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\/.*)?$/);
+    if (!match)
+        return undefined;
+    return match[1].replace(/\.git$/, "");
+}
+export function releaseAssetUrl(repo, version, filename) {
+    const normalized = normalizeRepoUrl(repo);
+    if (!normalized || !normalized.startsWith("https://github.com/"))
+        return undefined;
+    return `${normalized}/releases/download/v${version}/${encodeURIComponent(filename)}`;
+}
+function extractArchive(tarballPath) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "synergy-plugin-entry-"));
+    const result = Bun.spawnSync(["tar", "-xzf", tarballPath, "-C", tmp], { stdout: "pipe", stderr: "pipe" });
+    if (result.exitCode !== 0) {
+        const stderr = new TextDecoder().decode(result.stderr);
+        throw new Error(`Failed to inspect tarball${stderr ? `: ${stderr}` : ""}`);
+    }
+    return tmp;
+}
+export function readTarballManifest(tarballPath) {
+    const extractedDir = extractArchive(tarballPath);
+    const manifestPath = path.join(extractedDir, "plugin.json");
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error("Tarball does not contain plugin.json. Run `synergy-plugin build` and `synergy-plugin pack` first.");
+    }
+    return PluginManifest.parse(JSON.parse(fs.readFileSync(manifestPath, "utf-8")));
+}
+export function uiSurfaces(manifest) {
+    const ui = manifest.contributes?.ui;
+    if (!ui)
+        return [];
+    const surfaces = [];
+    if (ui.toolRenderers?.length)
+        surfaces.push("toolRenderers");
+    if (ui.partRenderers?.length)
+        surfaces.push("partRenderers");
+    if (ui.workspacePanels?.length)
+        surfaces.push("workspacePanels");
+    if (ui.globalPanels?.length)
+        surfaces.push("globalPanels");
+    if (ui.settings?.length)
+        surfaces.push("settings");
+    if (ui.chatComponents?.length)
+        surfaces.push("chatComponents");
+    if (ui.themes?.length)
+        surfaces.push("themes");
+    if (ui.icons?.length)
+        surfaces.push("icons");
+    if (ui.routes?.length)
+        surfaces.push("routes");
+    if (ui.commands?.length)
+        surfaces.push("commands");
+    return surfaces;
+}
+function registryPermissions(capabilities) {
+    return capabilities.map((cap) => ({
+        key: cap,
+        description: `Requires ${cap}`,
+        risk: cap.includes("write") || cap === "shell" || cap === "secrets" ? "high" : "medium",
+    }));
+}
+export function githubEntry(input) {
+    const manifest = readTarballManifest(input.tarballPath);
+    const repo = normalizeRepoUrl(input.repo ?? manifest.repository ?? manifest.homepage);
+    if (!repo)
+        throw new Error("GitHub registry entry requires --repo or manifest.repository");
+    const filename = path.basename(input.tarballPath);
+    const downloadUrl = input.downloadUrl ?? releaseAssetUrl(repo, manifest.version, filename);
+    const signatureUrl = input.signatureUrl ?? (downloadUrl ? `${downloadUrl}.sig` : undefined);
+    if (!downloadUrl || !signatureUrl) {
+        throw new Error("GitHub registry entry requires --download-url and --signature-url");
+    }
+    const capabilities = baseCapabilities(manifest);
+    const risk = computeRisk(capabilities, manifest);
+    const runtimeMode = resolveRuntimeMode({
+        source: "local",
+        manifestMode: manifest.runtime?.mode,
+        userTrusted: true,
+        risk,
+    });
+    const integrity = `sha256-${sha256File(input.tarballPath)}`;
+    const manifestHash = computeManifestHash(manifest);
+    const permissionsHash = computePermissionsHash(manifest, capabilities);
+    const signature = readSignatureFile(input.tarballPath);
+    if (!signature)
+        throw new Error(`Signature file not found or invalid: ${input.tarballPath}.sig`);
+    if (signature.pluginId !== manifest.name)
+        throw new Error("Signature pluginId does not match manifest name");
+    if (signature.version !== manifest.version)
+        throw new Error("Signature version does not match manifest version");
+    if (signature.payload.tarballHash !== integrity.slice("sha256-".length)) {
+        throw new Error("Signature tarball hash does not match artifact integrity");
+    }
+    if (signature.payload.manifestHash !== manifestHash)
+        throw new Error("Signature manifest hash does not match manifest");
+    if (signature.payload.permissionsHash !== permissionsHash) {
+        throw new Error("Signature permissions hash does not match manifest capabilities");
+    }
+    return {
+        schemaVersion: 1,
+        id: manifest.name,
+        name: manifest.name,
+        description: manifest.description,
+        repo,
+        ...(manifest.homepage ? { homepage: manifest.homepage } : {}),
+        author: parseAuthor(manifest.author),
+        verified: Boolean(input.verified),
+        official: Boolean(input.official),
+        keywords: [...new Set([...(manifest.keywords ?? []), "synergy-plugin"])].sort(),
+        compatibility: { synergy: manifest.engines?.synergy ?? manifest.minSynergyVersion ?? ">=1.0.0" },
+        versions: [
+            {
+                version: manifest.version,
+                downloadUrl,
+                signatureUrl,
+                integrity,
+                manifestHash,
+                permissionsHash,
+                risk,
+                runtimeMode,
+                permissionsSummary: registryPermissions(capabilities),
+                tools: (manifest.contributes?.tools ?? []).map((tool) => tool.name),
+                uiSurfaces: uiSurfaces(manifest),
+                publishedAt: input.publishedAt ?? new Date().toISOString(),
+                ...(input.changelog ? { changelog: input.changelog } : {}),
+            },
+        ],
+        yankedVersions: [],
+    };
+}
+export function writeGithubEntry(filepath, next) {
+    let merged = next;
+    if (fs.existsSync(filepath)) {
+        const existing = JSON.parse(fs.readFileSync(filepath, "utf-8"));
+        const versions = [
+            ...existing.versions.filter((version) => version.version !== next.versions[0]?.version),
+            ...next.versions,
+        ].sort((a, b) => Date.parse(a.publishedAt) - Date.parse(b.publishedAt));
+        merged = { ...existing, ...next, versions, yankedVersions: existing.yankedVersions ?? [] };
+    }
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, JSON.stringify(merged, null, 2) + "\n");
+    return merged;
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,3 @@
+export declare const SYNERGY_ROOT: string;
+export declare const SIGNING_KEYS_DIR: string;
+export declare const SIGNING_KEY_FILE: string;

package/dist/lib/paths.js

@@ -0,0 +1,5 @@
+import os from "os";
+import path from "path";
+export const SYNERGY_ROOT = process.env.SYNERGY_HOME || path.join(os.homedir(), ".synergy");
+export const SIGNING_KEYS_DIR = path.join(SYNERGY_ROOT, "keys");
+export const SIGNING_KEY_FILE = path.join(SIGNING_KEYS_DIR, "signing-key.json");

package/dist/lib/risk.d.ts

@@ -0,0 +1,2 @@
+import type { PluginManifest } from "@ericsanchezok/synergy-plugin";
+export declare function computeRisk(capabilities: string[], manifest?: PluginManifest): "low" | "medium" | "high";

package/dist/lib/risk.js

@@ -0,0 +1,28 @@
+export function computeRisk(capabilities, manifest) {
+    if (capabilities.length === 0)
+        return "low";
+    let risk = "low";
+    for (const cap of capabilities) {
+        switch (cap) {
+            case "shell":
+            case "filesystem:write":
+            case "secrets":
+            case "hooks.promptTransform":
+                risk = "high";
+                break;
+            case "filesystem:read":
+            case "session_data":
+            case "config:write":
+                if (risk !== "high")
+                    risk = "medium";
+                break;
+            case "network":
+                if (risk !== "high") {
+                    const domains = manifest?.permissions?.network?.connectDomains ?? [];
+                    risk = domains.length > 0 ? "medium" : "high";
+                }
+                break;
+        }
+    }
+    return risk;
+}

package/dist/lib/runtime-discovery.d.ts

@@ -0,0 +1,12 @@
+export interface RuntimeDiscoveryInput {
+    manifestToolNames: string[];
+    runtimeToolNames: string[] | null;
+    pluginId: string;
+}
+export interface RuntimeDiscoveryResult {
+    matched: string[];
+    undeclared: string[];
+    declaredButMissing: string[];
+    loadFailed: boolean;
+}
+export declare function validateRuntimeDiscovery(input: RuntimeDiscoveryInput): RuntimeDiscoveryResult;

package/dist/lib/runtime-discovery.js

@@ -0,0 +1,13 @@
+export function validateRuntimeDiscovery(input) {
+    if (input.runtimeToolNames === null) {
+        return { matched: [], undeclared: [], declaredButMissing: input.manifestToolNames, loadFailed: true };
+    }
+    const manifestTools = new Set(input.manifestToolNames);
+    const runtimeTools = new Set(input.runtimeToolNames);
+    return {
+        matched: input.runtimeToolNames.filter((tool) => manifestTools.has(tool)),
+        undeclared: input.runtimeToolNames.filter((tool) => !manifestTools.has(tool)),
+        declaredButMissing: input.manifestToolNames.filter((tool) => !runtimeTools.has(tool)),
+        loadFailed: false,
+    };
+}

package/dist/lib/runtime-mode.d.ts

@@ -0,0 +1,9 @@
+export type PluginSource = "local" | "official" | "npm" | "git" | "url" | "builtin";
+export type RuntimeMode = "in-process" | "worker" | "process";
+export declare function resolveRuntimeMode(input: {
+    source: PluginSource;
+    manifestMode?: RuntimeMode;
+    userTrusted?: boolean;
+    risk?: "low" | "medium" | "high";
+    forceProcess?: boolean;
+}): RuntimeMode;

package/dist/lib/runtime-mode.js

@@ -0,0 +1,15 @@
+const TRUSTED_SOURCES = new Set(["builtin", "official", "local"]);
+export function resolveRuntimeMode(input) {
+    const { source, manifestMode, userTrusted = false, risk = "low", forceProcess = false } = input;
+    if (forceProcess)
+        return "process";
+    if (risk === "high")
+        return "process";
+    if (manifestMode === "process")
+        return "process";
+    if (manifestMode === "worker" && userTrusted)
+        return "worker";
+    if (manifestMode === "in-process")
+        return TRUSTED_SOURCES.has(source) ? "in-process" : "process";
+    return TRUSTED_SOURCES.has(source) ? "in-process" : "process";
+}

package/dist/lib/runtime-policy.d.ts

@@ -0,0 +1,12 @@
+import type { PluginManifest } from "@ericsanchezok/synergy-plugin";
+import type { PluginSource } from "./runtime-mode";
+export interface CheckResult {
+    type: "pass" | "warn" | "error";
+    message: string;
+}
+export declare function validateRuntimePolicy(input: {
+    manifest: PluginManifest;
+    source: PluginSource;
+    trustTier: "declarative" | "trusted-import" | "sandbox";
+    risk: "low" | "medium" | "high";
+}): CheckResult[];

package/dist/lib/runtime-policy.js

@@ -0,0 +1,62 @@
+export function validateRuntimePolicy(input) {
+    const results = [];
+    const { manifest, source, trustTier, risk } = input;
+    const effectiveMode = manifest.runtime?.mode ?? "in-process";
+    const isThirdParty = source !== "local" && source !== "builtin";
+    if (isThirdParty && effectiveMode === "in-process") {
+        results.push({
+            type: "error",
+            message: `Third-party plugin (source=${source}) cannot run in-process. Use worker or process isolation.`,
+        });
+    }
+    if (risk === "high" && effectiveMode === "in-process") {
+        results.push({
+            type: "error",
+            message: "High-risk plugin cannot run in-process. Use worker or process isolation.",
+        });
+    }
+    const requestedTier = manifest.trust?.requestedTier;
+    if (trustTier === "sandbox" && requestedTier !== "sandbox") {
+        results.push({
+            type: "warn",
+            message: `Plugin has sandbox trust tier but effective runtime mode "${effectiveMode}" may not provide full sandbox isolation. ` +
+                "Consider using process mode with explicit resource limits.",
+        });
+    }
+    if (requestedTier !== undefined && requestedTier !== trustTier) {
+        results.push({
+            type: "warn",
+            message: `Plugin requested trust tier "${requestedTier}" but was assigned "${trustTier}" ` +
+                `(source=${source}). Runtime mode is "${effectiveMode}".`,
+        });
+    }
+    if (effectiveMode === "worker") {
+        const tools = manifest.permissions?.tools;
+        const hasShell = tools?.shell ?? false;
+        const hasFileWrite = tools?.filesystem === "write";
+        const hasMcpSpawn = tools?.mcp === "spawn";
+        const contributedTools = manifest.contributes?.tools ?? [];
+        const toolShell = contributedTools.some((tool) => tool.capabilities?.shell);
+        const toolFileWrite = contributedTools.some((tool) => tool.capabilities?.filesystem === "write");
+        if (hasShell || toolShell || hasFileWrite || toolFileWrite || hasMcpSpawn) {
+            const unsupported = [];
+            if (hasShell || toolShell)
+                unsupported.push("shell");
+            if (hasFileWrite || toolFileWrite)
+                unsupported.push("filesystem:write");
+            if (hasMcpSpawn)
+                unsupported.push("mcp:spawn");
+            results.push({
+                type: "warn",
+                message: `Worker mode does not fully support: ${unsupported.join(", ")}. Consider process mode for these capabilities.`,
+            });
+        }
+    }
+    if (effectiveMode === "process" && !manifest.runtime?.resources) {
+        results.push({
+            type: "warn",
+            message: "Process mode used without resource limits. Specify runtime.resources to prevent resource exhaustion.",
+        });
+    }
+    return results;
+}

package/dist/lib/signature.d.ts

@@ -0,0 +1,15 @@
+export interface SignatureMetadata {
+    signatureVersion: 1;
+    pluginId: string;
+    version: string;
+    algorithm: "ed25519";
+    signer: string;
+    signature: string;
+    signedAt: number;
+    payload: {
+        tarballHash: string;
+        manifestHash: string;
+        permissionsHash: string;
+    };
+}
+export declare function readSignatureFile(tarballPath: string): SignatureMetadata | null;

package/dist/lib/signature.js

@@ -0,0 +1,15 @@
+import fs from "fs";
+export function readSignatureFile(tarballPath) {
+    const sigPath = `${tarballPath}.sig`;
+    if (!fs.existsSync(sigPath))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(sigPath, "utf-8"));
+        if (parsed.signatureVersion !== 1 || parsed.algorithm !== "ed25519")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/spec.d.ts

@@ -0,0 +1,7 @@
+import type { PluginDescriptor, PluginManifest as PluginManifestType } from "@ericsanchezok/synergy-plugin";
+export declare function resolveEntryFromPluginDir(pluginDir: string, manifest: PluginManifestType | null): string;
+export declare function importUrlForEntry(entryPath: string, nonce?: number): string;
+export declare function assertCanonicalPluginIdentity(input: {
+    manifest: PluginManifestType | null;
+    descriptor: PluginDescriptor;
+}): void;

package/dist/lib/spec.js

@@ -0,0 +1,21 @@
+import path from "path";
+import { pathToFileURL } from "url";
+export function resolveEntryFromPluginDir(pluginDir, manifest) {
+    const main = manifest?.main ?? "./src/index.ts";
+    return path.resolve(pluginDir, main);
+}
+export function importUrlForEntry(entryPath, nonce) {
+    const url = pathToFileURL(entryPath);
+    if (nonce !== undefined)
+        url.searchParams.set("t", String(nonce));
+    return url.toString();
+}
+export function assertCanonicalPluginIdentity(input) {
+    const manifestId = input.manifest?.name;
+    const descriptorId = input.descriptor.id;
+    if (!descriptorId)
+        throw new Error("PluginDescriptor.id is required");
+    if (manifestId && manifestId !== descriptorId) {
+        throw new Error(`Plugin identity mismatch: plugin.json.name "${manifestId}" does not match descriptor id "${descriptorId}"`);
+    }
+}

package/dist/ui.d.ts

@@ -0,0 +1,15 @@
+export declare namespace UI {
+    const Style: {
+        readonly TEXT_NORMAL: "\u001B[0m";
+        readonly TEXT_NORMAL_BOLD: "\u001B[1m";
+        readonly TEXT_DIM: "\u001B[2m";
+        readonly TEXT_SUCCESS: "\u001B[32m";
+        readonly TEXT_WARNING: "\u001B[33m";
+        readonly TEXT_DANGER: "\u001B[31m";
+        readonly TEXT_HIGHLIGHT: "\u001B[36m";
+        readonly TEXT_HIGHLIGHT_BOLD: "\u001B[1;36m";
+    };
+    function println(message?: string): void;
+    function print(message: string): void;
+    function error(message: string): void;
+}

package/dist/ui.js

@@ -0,0 +1,26 @@
+import { EOL } from "os";
+export var UI;
+(function (UI) {
+    UI.Style = {
+        TEXT_NORMAL: "\x1b[0m",
+        TEXT_NORMAL_BOLD: "\x1b[1m",
+        TEXT_DIM: "\x1b[2m",
+        TEXT_SUCCESS: "\x1b[32m",
+        TEXT_WARNING: "\x1b[33m",
+        TEXT_DANGER: "\x1b[31m",
+        TEXT_HIGHLIGHT: "\x1b[36m",
+        TEXT_HIGHLIGHT_BOLD: "\x1b[1;36m",
+    };
+    function println(message = "") {
+        process.stdout.write(message + EOL);
+    }
+    UI.println = println;
+    function print(message) {
+        process.stdout.write(message);
+    }
+    UI.print = print;
+    function error(message) {
+        process.stderr.write(`${UI.Style.TEXT_DANGER}${message}${UI.Style.TEXT_NORMAL}${EOL}`);
+    }
+    UI.error = error;
+})(UI || (UI = {}));

package/package.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@ericsanchezok/synergy-plugin-kit",
+  "version": "2.2.1",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SII-Holos/synergy.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "bin": {
+    "synergy-plugin": "./dist/cli.js",
+    "synergy-plugin-kit": "./dist/cli.js"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "build": "tsc"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./commands": {
+      "import": "./dist/commands/index.js",
+      "types": "./dist/commands/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ericsanchezok/synergy-plugin": "2.2.0",
+    "yargs": "18.0.0"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  }
+}