@ericsanchezok/synergy-plugin-kit 2.2.1

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { PluginBuildCommand, PluginCreateCommand, PluginDevCommand, PluginEntryCommand, PluginPackCommand, PluginPublishMarketCommand, PluginSignCommand, PluginTestCommand, PluginValidateCommand, } from "./commands";
+function assertBunRuntime() {
+    if (!process.versions.bun) {
+        throw new Error("synergy-plugin requires Bun. Install Bun from https://bun.sh and retry.");
+    }
+}
+assertBunRuntime();
+await yargs(hideBin(process.argv))
+    .scriptName("synergy-plugin")
+    .command(PluginCreateCommand)
+    .command(PluginValidateCommand)
+    .command(PluginDevCommand)
+    .command(PluginBuildCommand)
+    .command(PluginPackCommand)
+    .command(PluginSignCommand)
+    .command(PluginTestCommand)
+    .command(PluginPublishMarketCommand)
+    .command(PluginEntryCommand)
+    .demandCommand(1)
+    .strict()
+    .help()
+    .parse();

package/dist/cmd.d.ts

@@ -0,0 +1,6 @@
+import type { CommandModule } from "yargs";
+type WithDoubleDash<T> = T & {
+    "--"?: string[];
+};
+export declare function cmd<T, U>(input: CommandModule<T, WithDoubleDash<U>>): CommandModule<T, WithDoubleDash<U>>;
+export {};

package/dist/cmd.js

@@ -0,0 +1,3 @@
+export function cmd(input) {
+    return input;
+}

package/dist/commands/build.d.ts

@@ -0,0 +1,6 @@
+export declare function buildPluginProject(pluginDir: string): Promise<boolean>;
+export declare const PluginBuildCommand: import("yargs").CommandModule<{}, {
+    path: string | undefined;
+} & {
+    "--"?: string[];
+}>;

package/dist/commands/build.js

@@ -0,0 +1,194 @@
+import path from "path";
+import fs from "fs";
+import { EOL } from "os";
+import { PluginManifest } from "@ericsanchezok/synergy-plugin";
+import { cmd } from "../cmd";
+import { UI } from "../ui";
+import { sha256File, sha256JSON } from "../lib/crypto";
+function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+function copyDir(src, dest) {
+    ensureDir(dest);
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory())
+            copyDir(srcPath, destPath);
+        else
+            fs.copyFileSync(srcPath, destPath);
+    }
+}
+function copyFilePreserve(pluginDir, distDir, relativePath) {
+    const normalized = relativePath.replace(/^\.\//, "");
+    const src = path.resolve(pluginDir, normalized);
+    if (!fs.existsSync(src) || !fs.statSync(src).isFile())
+        return;
+    const dest = path.join(distDir, normalized);
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(src, dest);
+}
+function findUiSource(pluginDir) {
+    const candidates = ["src/ui.tsx", "src/ui/index.tsx", "src/ui.ts", "src/ui/index.ts"];
+    return candidates.map((candidate) => path.join(pluginDir, candidate)).find((candidate) => fs.existsSync(candidate));
+}
+function packagedManifest(manifest) {
+    const next = structuredClone(manifest);
+    next.main = "./runtime/index.js";
+    if (next.contributes?.ui?.entry) {
+        next.contributes.ui.entry = next.contributes.ui.entry.replace(/^\.\//, "").replace(/^dist\//, "./");
+        if (!next.contributes.ui.entry.startsWith("."))
+            next.contributes.ui.entry = `./${next.contributes.ui.entry}`;
+    }
+    return next;
+}
+function permissionSummary(manifest) {
+    const perms = manifest.permissions ?? {};
+    const result = {};
+    if (perms.tools)
+        result.tools = perms.tools;
+    if (perms.data)
+        result.data = perms.data;
+    if (perms.network)
+        result.network = perms.network;
+    if (perms.ui)
+        result.ui = perms.ui;
+    if (perms.hooks)
+        result.hooks = perms.hooks;
+    const tools = manifest.contributes?.tools ?? [];
+    if (tools.length > 0) {
+        const toolPerms = {};
+        for (const tool of tools) {
+            if (tool.capabilities)
+                toolPerms[tool.name] = tool.capabilities;
+        }
+        if (Object.keys(toolPerms).length > 0)
+            result.contributedTools = toolPerms;
+    }
+    return result;
+}
+export async function buildPluginProject(pluginDir) {
+    const manifestPath = path.join(pluginDir, "plugin.json");
+    if (!fs.existsSync(manifestPath)) {
+        UI.error(`No plugin.json found at ${manifestPath}`);
+        return false;
+    }
+    let manifest;
+    const raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    const parsed = PluginManifest.safeParse(raw);
+    if (!parsed.success) {
+        UI.error("Invalid plugin manifest:");
+        for (const issue of parsed.error.issues) {
+            UI.println(`  ${UI.Style.TEXT_DIM}${issue.path.join(".")}:${UI.Style.TEXT_NORMAL} ${issue.message}`);
+        }
+        return false;
+    }
+    manifest = parsed.data;
+    const spinner = (message) => {
+        process.stderr.write(`${UI.Style.TEXT_DIM}  ${message}...${UI.Style.TEXT_NORMAL}${EOL}`);
+    };
+    UI.println(`${UI.Style.TEXT_NORMAL_BOLD}Building${UI.Style.TEXT_NORMAL} ${manifest.name} v${manifest.version}`);
+    UI.println(`  ${UI.Style.TEXT_DIM}Source:${UI.Style.TEXT_NORMAL} ${pluginDir}`);
+    const distDir = path.join(pluginDir, "dist");
+    fs.rmSync(distDir, { recursive: true, force: true });
+    ensureDir(distDir);
+    const entryFile = manifest.main ?? "./src/index.ts";
+    const entryPath = path.resolve(pluginDir, entryFile);
+    const runtimeOutdir = path.join(distDir, "runtime");
+    spinner("Building backend");
+    const backendResult = await Bun.build({
+        entrypoints: [entryPath],
+        outdir: runtimeOutdir,
+        target: "bun",
+        naming: "index.js",
+        external: ["@ericsanchezok/synergy-plugin", "@ericsanchezok/synergy-sdk", "@ericsanchezok/synergy-util"],
+    });
+    if (!backendResult.success) {
+        for (const log of backendResult.logs) {
+            UI.println(`  ${UI.Style.TEXT_WARNING}${log.message}${UI.Style.TEXT_NORMAL}`);
+        }
+        UI.error("Backend build failed");
+        return false;
+    }
+    const uiEntry = manifest.contributes?.ui?.entry;
+    if (uiEntry) {
+        const uiSourcePath = findUiSource(pluginDir);
+        const uiOutputPath = path.resolve(pluginDir, uiEntry);
+        if (uiSourcePath) {
+            const uiOutdir = path.dirname(uiOutputPath);
+            spinner("Building frontend");
+            const frontendResult = await Bun.build({
+                entrypoints: [uiSourcePath],
+                outdir: uiOutdir,
+                target: "browser",
+                naming: path.basename(uiOutputPath),
+            });
+            if (!frontendResult.success) {
+                for (const log of frontendResult.logs) {
+                    UI.println(`  ${UI.Style.TEXT_WARNING}${log.message}${UI.Style.TEXT_NORMAL}`);
+                }
+                UI.error("Frontend build failed");
+                return false;
+            }
+        }
+        else if (!fs.existsSync(uiOutputPath)) {
+            UI.error(`UI source not found. Expected one of src/ui.tsx or src/ui/index.tsx for ${uiEntry}`);
+            return false;
+        }
+    }
+    spinner("Normalizing manifest");
+    const distManifest = packagedManifest(manifest);
+    const distManifestPath = path.join(distDir, "plugin.json");
+    fs.writeFileSync(distManifestPath, JSON.stringify(distManifest, null, 2));
+    const normalizedPath = path.join(distDir, "plugin.normalized.json");
+    fs.writeFileSync(normalizedPath, JSON.stringify(distManifest, null, 2));
+    const packageJsonPath = path.join(pluginDir, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+        pkg.main = "./runtime/index.js";
+        pkg.exports = { ".": "./runtime/index.js" };
+        fs.writeFileSync(path.join(distDir, "package.json"), JSON.stringify(pkg, null, 2));
+    }
+    spinner("Generating permission summary");
+    const summary = permissionSummary(manifest);
+    fs.writeFileSync(path.join(distDir, "permissions.summary.json"), JSON.stringify(summary, null, 2));
+    const publicAssetsPath = path.join(pluginDir, "public", "assets");
+    if (fs.existsSync(publicAssetsPath)) {
+        spinner("Copying assets");
+        copyDir(publicAssetsPath, path.join(distDir, "assets"));
+    }
+    for (const theme of manifest.contributes?.ui?.themes ?? [])
+        copyFilePreserve(pluginDir, distDir, theme.path);
+    for (const icon of manifest.contributes?.ui?.icons ?? [])
+        copyFilePreserve(pluginDir, distDir, icon.path);
+    spinner("Computing integrity hashes");
+    const integrity = {
+        manifest: sha256File(distManifestPath),
+        permissions: sha256JSON(summary),
+    };
+    const runtimeIndex = path.join(runtimeOutdir, "index.js");
+    if (fs.existsSync(runtimeIndex))
+        integrity.runtime = sha256File(runtimeIndex);
+    if (uiEntry) {
+        const uiIndex = path.resolve(pluginDir, uiEntry);
+        if (fs.existsSync(uiIndex))
+            integrity.ui = sha256File(uiIndex);
+    }
+    fs.writeFileSync(path.join(distDir, "integrity.json"), JSON.stringify(integrity, null, 2));
+    UI.println(`${UI.Style.TEXT_SUCCESS}✔${UI.Style.TEXT_NORMAL} Built ${manifest.name} v${manifest.version} -> ${distDir}`);
+    UI.println(`  ${UI.Style.TEXT_DIM}Output:${UI.Style.TEXT_NORMAL} ${distDir}`);
+    return true;
+}
+export const PluginBuildCommand = cmd({
+    command: "build [path]",
+    describe: "build a plugin for distribution",
+    builder: (yargs) => yargs.positional("path", {
+        type: "string",
+        describe: "path to plugin directory (defaults to cwd)",
+    }),
+    async handler(args) {
+        const ok = await buildPluginProject(path.resolve(args.path ?? process.cwd()));
+        if (!ok)
+            process.exitCode = 1;
+    },
+});

package/dist/commands/create.d.ts

@@ -0,0 +1,9 @@
+type TemplateName = "tool-ui" | "workspace-panel" | "api-connector" | "theme-icon";
+export declare const PluginCreateCommand: import("yargs").CommandModule<{}, {
+    name: string;
+} & {
+    template: TemplateName;
+} & {
+    "--"?: string[];
+}>;
+export {};

package/dist/commands/create.js

@@ -0,0 +1,416 @@
+import path from "path";
+import fs from "fs";
+import { EOL } from "os";
+import { cmd } from "../cmd";
+import { UI } from "../ui";
+const TEMPLATES = ["tool-ui", "workspace-panel", "api-connector", "theme-icon"];
+function pluginJson(name, extra) {
+    const base = {
+        name,
+        version: "0.1.0",
+        description: `${name} plugin`,
+        permissions: {},
+        contributes: {},
+    };
+    return JSON.stringify({ ...base, ...extra(name) }, null, 2) + EOL;
+}
+function packageJson(name, templateName) {
+    const needsSolid = templateName !== "theme-icon";
+    const pkg = {
+        name,
+        version: "0.1.0",
+        type: "module",
+        scripts: {
+            dev: "synergy-plugin dev",
+            validate: "synergy-plugin validate --runtime-discovery",
+            build: "synergy-plugin build",
+            pack: "synergy-plugin pack",
+            sign: "synergy-plugin sign",
+            "publish:market": "synergy-plugin publish-market",
+            test: "synergy-plugin test",
+        },
+        dependencies: {
+            "@ericsanchezok/synergy-plugin": "latest",
+            zod: "^4.0.0",
+            ...(needsSolid ? { "solid-js": "^1.9.0" } : {}),
+        },
+        devDependencies: {
+            "@ericsanchezok/synergy-plugin-kit": "latest",
+            typescript: "^5.8.0",
+        },
+    };
+    return JSON.stringify(pkg, null, 2) + EOL;
+}
+function tsconfigJson() {
+    return (JSON.stringify({
+        compilerOptions: {
+            target: "ESNext",
+            module: "ESNext",
+            moduleResolution: "bundler",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            outDir: "dist",
+            rootDir: "src",
+            jsx: "preserve",
+            jsxImportSource: "solid-js",
+        },
+        include: ["src"],
+    }, null, 2) + EOL);
+}
+function readmeMd(name) {
+    return `# ${name}
+
+Synergy plugin generated with \`synergy-plugin create\`.
+
+## Commands
+
+\`\`\`bash
+bun install
+bun run validate
+bun run build
+bun run pack
+bun run sign ${name}-0.1.0.synergy-plugin.tgz
+bun run publish:market
+\`\`\`
+`;
+}
+function indexToolUI(name) {
+    return `import type { PluginDescriptor, PluginInput, PluginHooks } from "@ericsanchezok/synergy-plugin"
+import { greet } from "./tools"
+
+export const plugin: PluginDescriptor = {
+  id: "${name}",
+  name: "${name}",
+  async init(_input: PluginInput): Promise<PluginHooks> {
+    return {
+      tool: {
+        greet,
+      },
+    }
+  },
+}
+
+export default plugin
+`;
+}
+function indexWorkspacePanel(name) {
+    return `import type { PluginDescriptor, PluginInput, PluginHooks } from "@ericsanchezok/synergy-plugin"
+
+export const plugin: PluginDescriptor = {
+  id: "${name}",
+  name: "${name}",
+  async init(_input: PluginInput): Promise<PluginHooks> {
+    return {}
+  },
+}
+
+export default plugin
+`;
+}
+function indexApiConnector(name) {
+    return `import type { PluginDescriptor, PluginInput, PluginHooks } from "@ericsanchezok/synergy-plugin"
+import { getJSON, postJSON } from "./tools"
+
+export const plugin: PluginDescriptor = {
+  id: "${name}",
+  name: "${name}",
+  async init(_input: PluginInput): Promise<PluginHooks> {
+    return {
+      tool: {
+        getJSON,
+        postJSON,
+      },
+    }
+  },
+}
+
+export default plugin
+`;
+}
+function indexThemeIcon(name) {
+    return `import type { PluginDescriptor, PluginInput, PluginHooks } from "@ericsanchezok/synergy-plugin"
+
+export const plugin: PluginDescriptor = {
+  id: "${name}",
+  name: "${name}",
+  async init(_input: PluginInput): Promise<PluginHooks> {
+    return {}
+  },
+}
+
+export default plugin
+`;
+}
+function toolsToolUI(_name) {
+    return `import { tool } from "@ericsanchezok/synergy-plugin/tool"
+
+export const greet = tool({
+  description: "Greet a user by name",
+  args: {
+    name: tool.schema.string().describe("The name to greet"),
+  },
+  async execute(args) {
+    return { output: \`Hello, \${args.name}!\` }
+  },
+})
+`;
+}
+function toolsApiConnector(_name) {
+    return `import { tool } from "@ericsanchezok/synergy-plugin/tool"
+
+export const getJSON = tool({
+  description: "Fetch and parse JSON from an API endpoint",
+  args: {
+    url: tool.schema.string().describe("The API endpoint URL"),
+  },
+  async execute(args) {
+    const res = await fetch(args.url)
+    const json = await res.json()
+    return { output: JSON.stringify(json, null, 2) }
+  },
+})
+
+export const postJSON = tool({
+  description: "POST JSON to an API endpoint",
+  args: {
+    url: tool.schema.string().describe("The API endpoint URL"),
+    body: tool.schema.string().describe("The JSON request body"),
+  },
+  async execute(args) {
+    const res = await fetch(args.url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: args.body,
+    })
+    const text = await res.text()
+    return { output: text }
+  },
+})
+`;
+}
+function uiToolUI(_name) {
+    return `import type { Component } from "solid-js"
+
+interface Props {
+  tool: string
+  output: string
+  metadata?: Record<string, unknown>
+}
+
+const ToolRenderer: Component<Props> = (props) => {
+  return <div>{props.output}</div>
+}
+
+export default ToolRenderer
+`;
+}
+function uiWorkspacePanel(_name) {
+    return `import type { Component } from "solid-js"
+
+const WorkspacePanel: Component = () => {
+  return <div>Workspace panel content</div>
+}
+
+export default WorkspacePanel
+`;
+}
+function manifestToolUI(name) {
+    return {
+        permissions: {
+            tools: {
+                invoke: true,
+                shell: false,
+                filesystem: "none",
+                network: false,
+                mcp: "none",
+            },
+        },
+        contributes: {
+            tools: [
+                {
+                    name: "greet",
+                    title: "Greet",
+                    description: "Greet a user by name",
+                    capabilities: {
+                        filesystem: "none",
+                        network: false,
+                        shell: false,
+                    },
+                },
+            ],
+            ui: {
+                entry: "./dist/ui/index.js",
+                toolRenderers: [{ tool: "greet" }],
+            },
+        },
+    };
+}
+function manifestWorkspacePanel(name) {
+    return {
+        contributes: {
+            ui: {
+                entry: "./dist/ui/index.js",
+                workspacePanels: [
+                    {
+                        id: `${name}-panel`,
+                        label: name,
+                        icon: "layout-panel-left",
+                    },
+                ],
+            },
+        },
+    };
+}
+function manifestApiConnector(_name) {
+    return {
+        permissions: {
+            tools: {
+                invoke: true,
+                network: true,
+                shell: false,
+                filesystem: "none",
+                mcp: "none",
+            },
+            network: {
+                connectDomains: ["*"],
+            },
+        },
+        contributes: {
+            tools: [
+                {
+                    name: "getJSON",
+                    title: "Get JSON",
+                    description: "Fetch and parse JSON from an API endpoint",
+                    capabilities: {
+                        network: true,
+                        filesystem: "none",
+                        shell: false,
+                    },
+                },
+                {
+                    name: "postJSON",
+                    title: "Post JSON",
+                    description: "POST JSON to an API endpoint",
+                    capabilities: {
+                        network: true,
+                        filesystem: "none",
+                        shell: false,
+                    },
+                },
+            ],
+            ui: {
+                entry: "./dist/ui/index.js",
+                toolRenderers: [{ tool: "getJSON" }, { tool: "postJSON" }],
+            },
+        },
+    };
+}
+function manifestThemeIcon(name) {
+    return {
+        contributes: {
+            ui: {
+                themes: [{ id: `${name}-theme`, label: name, path: "./themes/default.css" }],
+                icons: [{ name: `${name}-logo`, path: "./icons/logo.svg" }],
+            },
+        },
+    };
+}
+const TEMPLATE_DEFS = {
+    "tool-ui": {
+        label: "Tool UI - tool definitions with Solid tool renderer",
+        manifest: manifestToolUI,
+        files: [
+            { relativePath: "src/index.ts", content: indexToolUI },
+            { relativePath: "src/tools.ts", content: toolsToolUI },
+            { relativePath: "src/ui.tsx", content: uiToolUI },
+        ],
+    },
+    "workspace-panel": {
+        label: "Workspace Panel - Solid workspace panel with no tools",
+        manifest: manifestWorkspacePanel,
+        files: [
+            { relativePath: "src/index.ts", content: indexWorkspacePanel },
+            { relativePath: "src/ui.tsx", content: uiWorkspacePanel },
+        ],
+    },
+    "api-connector": {
+        label: "API Connector - network-enabled tools for API integration",
+        manifest: manifestApiConnector,
+        files: [
+            { relativePath: "src/index.ts", content: indexApiConnector },
+            { relativePath: "src/tools.ts", content: toolsApiConnector },
+            { relativePath: "src/ui.tsx", content: uiToolUI },
+        ],
+    },
+    "theme-icon": {
+        label: "Theme & Icon - themes and icon contributions",
+        manifest: manifestThemeIcon,
+        files: [
+            { relativePath: "src/index.ts", content: indexThemeIcon },
+            { relativePath: "themes/default.css", content: () => ":root { --plugin-accent: #2563eb; }\n" },
+            {
+                relativePath: "icons/logo.svg",
+                content: () => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9" fill="currentColor"/></svg>\n',
+            },
+        ],
+    },
+};
+function scaffold(name, templateName, template, targetDir) {
+    const created = [];
+    fs.mkdirSync(targetDir, { recursive: true });
+    const files = [
+        { relativePath: "plugin.json", content: (pluginName) => pluginJson(pluginName, template.manifest) },
+        { relativePath: "package.json", content: (pluginName) => packageJson(pluginName, templateName) },
+        { relativePath: "tsconfig.json", content: tsconfigJson },
+        { relativePath: "README.md", content: readmeMd },
+        ...template.files,
+    ];
+    for (const file of files) {
+        const filePath = path.join(targetDir, file.relativePath);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, file.content(name));
+        created.push(filePath);
+    }
+    return created;
+}
+export const PluginCreateCommand = cmd({
+    command: "create <name>",
+    describe: "scaffold a new Synergy plugin project",
+    builder: (yargs) => yargs
+        .positional("name", {
+        type: "string",
+        describe: "plugin name (used as directory name and plugin id)",
+        demandOption: true,
+    })
+        .option("template", {
+        type: "string",
+        describe: "template to scaffold",
+        choices: [...TEMPLATES],
+        default: "tool-ui",
+    }),
+    async handler(args) {
+        const name = args.name;
+        const templateName = args.template ?? "tool-ui";
+        const template = TEMPLATE_DEFS[templateName];
+        const targetDir = path.resolve(process.cwd(), name);
+        if (!/^[a-z0-9][-a-z0-9]*$/.test(name)) {
+            UI.error(`Invalid plugin name "${name}". Use lowercase letters, digits, and hyphens.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (fs.existsSync(targetDir)) {
+            UI.error(`Directory "${targetDir}" already exists. Remove it first or use a different name.`);
+            process.exitCode = 1;
+            return;
+        }
+        const created = scaffold(name, templateName, template, targetDir);
+        UI.println(`${UI.Style.TEXT_SUCCESS}✔${UI.Style.TEXT_NORMAL} Created plugin "${name}" (${template.label})`);
+        UI.println();
+        for (const filePath of created) {
+            UI.println(`  ${UI.Style.TEXT_DIM}${path.relative(process.cwd(), filePath)}${UI.Style.TEXT_NORMAL}`);
+        }
+        UI.println();
+        UI.println(`${UI.Style.TEXT_DIM}Next: cd ${name} && bun install && bun run validate${UI.Style.TEXT_NORMAL}`);
+    },
+});

package/dist/commands/dev.d.ts

@@ -0,0 +1,9 @@
+export declare const PluginDevCommand: import("yargs").CommandModule<{}, {
+    path: string | undefined;
+} & {
+    "sandbox-preview": boolean;
+} & {
+    port: number;
+} & {
+    "--"?: string[];
+}>;