@ericsanchezok/synergy-util 2.4.4

package/dist/path.js

@@ -0,0 +1,84 @@
+/**
+ * Extract the last path segment (filename / directory name).
+ * Handles both forward slash and backslash separators.
+ */
+export function getFilename(path) {
+    if (!path)
+        return "";
+    const trimmed = path.replace(/[\/\\]+$/, "");
+    const parts = trimmed.split(/[\/\\]/);
+    return parts[parts.length - 1] ?? "";
+}
+/**
+ * Extract the parent directory of a path, with a trailing separator.
+ * Handles both forward slash and backslash — backslashes are normalized to forward slashes in output.
+ *
+ *   "/home/user/projects" → "/home/user/"
+ *   "C:\\Users\\projects" → "C:/Users/"
+ *   "~" → ""
+ *   "/" → "/"
+ */
+export function getDirectory(path) {
+    if (!path)
+        return "";
+    const normalized = path.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    if (parts.length <= 1)
+        return normalized === "/" ? "/" : "";
+    return parts.slice(0, parts.length - 1).join("/") + "/";
+}
+/**
+ * Return the file extension (last dot-segment), or the full path if no dot exists.
+ */
+export function getFileExtension(path) {
+    if (!path)
+        return "";
+    const parts = path.split(".");
+    return parts[parts.length - 1];
+}
+/**
+ * Parse a user-typed path string into a parent-directory + search-query pair.
+ *
+ * Rules (in order):
+ * 1. Empty input → homeDir with no query
+ * 2. Expand "~" and "~/..." using homeDir
+ * 3. Normalize backslashes to forward slashes
+ * 4. Absolute paths (Unix `/`, Windows `C:/`, UNC `//`) → split on last `/`; Windows drive roots stay rooted at `C:/`
+ * 5. Relative paths → homeDir is the parent, the whole input is the query
+ *
+ *   resolvePathInput("~/projects/myapp", "/home/user") → { path: "/home/user/projects", query: "myapp" }
+ *   resolvePathInput("C:\\Users\\me", "/home/user")    → { path: "C:/Users", query: "me" }
+ *   resolvePathInput("D:\\data", "/home/user")         → { path: "D:/", query: "data" }
+ *   resolvePathInput("D:", "/home/user")               → { path: "D:/", query: "" }
+ *   resolvePathInput("myproject", "/home/user")         → { path: "/home/user", query: "myproject" }
+ */
+export function resolvePathInput(input, homeDir) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return { path: homeDir || "/", query: "" };
+    // Bare tilde: browse home directory itself
+    if (trimmed === "~")
+        return { path: homeDir || "/", query: "" };
+    let expanded = trimmed;
+    // Tilde-prefixed path expansion
+    if (expanded.startsWith("~/")) {
+        expanded = (homeDir || "") + expanded.slice(1);
+    }
+    // Normalize all backslashes to forward slashes
+    expanded = expanded.replace(/\\/g, "/");
+    // Bare Windows drive letters are treated as drive roots in browser-style path inputs.
+    const driveRoot = expanded.match(/^([A-Za-z]):(?:\/)?$/);
+    if (driveRoot)
+        return { path: `${driveRoot[1]}:/`, query: "" };
+    const isAbsolute = expanded.startsWith("/") || /^[A-Za-z]:\//.test(expanded);
+    if (isAbsolute) {
+        const lastSlash = expanded.lastIndexOf("/");
+        if (/^[A-Za-z]:\//.test(expanded) && lastSlash <= 2) {
+            return { path: `${expanded[0]}:/`, query: expanded.slice(3) };
+        }
+        const parentDir = expanded.slice(0, lastSlash) || "/";
+        const query = expanded.slice(lastSlash + 1);
+        return { path: parentDir, query };
+    }
+    return { path: homeDir || "/", query: expanded };
+}

package/dist/plugin-policy.d.ts

@@ -0,0 +1,100 @@
+import { type SynergyCapabilityManifest } from "./capability";
+export type PluginSource = "local" | "official" | "npm" | "git" | "url" | "builtin";
+export type RuntimeMode = "in-process" | "worker" | "process";
+export type TrustTier = "declarative" | "trusted-import" | "sandbox";
+export type PolicyRisk = "low" | "medium" | "high";
+export interface PluginPolicyManifest extends SynergyCapabilityManifest {
+    runtime?: {
+        mode?: RuntimeMode;
+        resources?: unknown;
+    };
+    trust?: {
+        requestedTier?: TrustTier;
+    };
+}
+export interface PluginTrustDecision {
+    tier: TrustTier;
+    source: PluginSource;
+    userTrusted: boolean;
+    verifiedIntegrity: boolean;
+    reason: string;
+}
+export interface RuntimeLimits {
+    startupTimeoutMs: number;
+    toolInvocationTimeoutMs: number;
+    hookInvocationTimeoutMs: number;
+    bridgeRequestTimeoutMs: number;
+    taskRunTimeoutMs: number;
+    shutdownGraceMs: number;
+    maxConcurrentRequests: number;
+    maxLogBytesPerMinute: number;
+    memoryMb: number;
+    memoryPollIntervalMs: number;
+    heartbeatIntervalMs: number;
+    heartbeatMissesBeforeKill: number;
+}
+export type RuntimeLimitOverrides = Partial<RuntimeLimits>;
+export interface PluginRuntimePolicyInput {
+    thirdPartyDefaultMode?: "process" | "worker";
+    highRiskRequiresProcess?: boolean;
+    allowThirdPartyInProcess?: boolean;
+    allowWorkerMode?: boolean;
+    allowLocalInProcess?: boolean;
+}
+export interface PluginPolicyDecision {
+    source: PluginSource;
+    capabilities: string[];
+    risk: PolicyRisk;
+    trust: PluginTrustDecision;
+    runtimeMode: RuntimeMode;
+}
+export declare const DEFAULT_PLUGIN_RUNTIME_POLICY: Required<PluginRuntimePolicyInput>;
+export declare const DEFAULT_PLUGIN_RUNTIME_LIMITS: RuntimeLimits;
+export declare function isTrustedPluginSource(source: PluginSource): boolean;
+export interface ResolveRuntimeModeInput {
+    source: PluginSource;
+    manifestMode?: RuntimeMode;
+    devMode?: boolean;
+    userTrusted?: boolean;
+    risk?: PolicyRisk;
+    forceProcess?: boolean;
+    policy?: PluginRuntimePolicyInput;
+}
+export interface PolicyCheckResult {
+    type: "pass" | "warn" | "error";
+    message: string;
+}
+export declare function resolveRuntimeMode(input: ResolveRuntimeModeInput): RuntimeMode;
+export declare function resolveRuntimeLimits(...overrides: Array<RuntimeLimitOverrides | undefined>): RuntimeLimits;
+export declare function decideTrust(input: {
+    source: PluginSource;
+    userTrusted: boolean;
+    verifiedIntegrity: boolean;
+    devMode: boolean;
+}): PluginTrustDecision;
+export declare function defaultPluginTrustDecision(input: {
+    source: PluginSource;
+    userTrusted?: boolean;
+    verifiedIntegrity?: boolean;
+    devMode?: boolean;
+}): PluginTrustDecision;
+export declare function resolvePluginPolicyDecision(input: {
+    manifest: PluginPolicyManifest;
+    source: PluginSource;
+    userTrusted?: boolean;
+    verifiedIntegrity?: boolean;
+    devMode?: boolean;
+    policy?: PluginRuntimePolicyInput;
+    forceProcess?: boolean;
+    risk?: PolicyRisk;
+}): PluginPolicyDecision;
+export declare function trustReason(decision: PluginTrustDecision): string;
+export declare function trustSummary(decision: PluginTrustDecision): string;
+export declare function validateRuntimePolicy(input: {
+    manifest: PluginPolicyManifest;
+    source: PluginSource;
+    trustTier: TrustTier;
+    risk: PolicyRisk;
+    userTrusted?: boolean;
+    policy?: PluginRuntimePolicyInput;
+}): PolicyCheckResult[];

package/dist/plugin-policy.js

@@ -0,0 +1,240 @@
+import { baseCapabilities, pluginRisk } from "./capability";
+export const DEFAULT_PLUGIN_RUNTIME_POLICY = {
+    thirdPartyDefaultMode: "process",
+    highRiskRequiresProcess: true,
+    allowThirdPartyInProcess: false,
+    allowWorkerMode: true,
+    allowLocalInProcess: true,
+};
+export const DEFAULT_PLUGIN_RUNTIME_LIMITS = {
+    startupTimeoutMs: 5_000,
+    toolInvocationTimeoutMs: 120_000,
+    hookInvocationTimeoutMs: 120_000,
+    bridgeRequestTimeoutMs: 120_000,
+    taskRunTimeoutMs: 120_000,
+    shutdownGraceMs: 1_500,
+    maxConcurrentRequests: 8,
+    maxLogBytesPerMinute: 128_000,
+    memoryMb: 256,
+    memoryPollIntervalMs: 10_000,
+    heartbeatIntervalMs: 5_000,
+    heartbeatMissesBeforeKill: 3,
+};
+const TRUSTED_SOURCES = new Set(["builtin", "official", "local"]);
+const THIRD_PARTY_SOURCES = new Set(["npm", "git", "url"]);
+export function isTrustedPluginSource(source) {
+    return TRUSTED_SOURCES.has(source);
+}
+function runtimePolicy(input) {
+    return { ...DEFAULT_PLUGIN_RUNTIME_POLICY, ...(input ?? {}) };
+}
+export function resolveRuntimeMode(input) {
+    const policy = runtimePolicy(input.policy);
+    const source = input.source;
+    const manifestMode = input.manifestMode;
+    const userTrusted = input.userTrusted ?? false;
+    const risk = input.risk ?? "low";
+    if (input.forceProcess)
+        return "process";
+    if (policy.highRiskRequiresProcess && risk === "high")
+        return "process";
+    if (manifestMode === "process")
+        return "process";
+    if (manifestMode === "worker") {
+        if (policy.allowWorkerMode && userTrusted)
+            return "worker";
+        return THIRD_PARTY_SOURCES.has(source) ? "process" : defaultTrustedMode(source, policy);
+    }
+    if (manifestMode === "in-process") {
+        if (TRUSTED_SOURCES.has(source))
+            return defaultTrustedMode(source, policy);
+        return policy.allowThirdPartyInProcess ? "in-process" : "process";
+    }
+    if (THIRD_PARTY_SOURCES.has(source)) {
+        if (policy.thirdPartyDefaultMode === "worker" && policy.allowWorkerMode && userTrusted)
+            return "worker";
+        return "process";
+    }
+    return defaultTrustedMode(source, policy);
+}
+export function resolveRuntimeLimits(...overrides) {
+    const resolved = { ...DEFAULT_PLUGIN_RUNTIME_LIMITS };
+    for (const override of overrides) {
+        if (!override)
+            continue;
+        for (const [key, value] of Object.entries(override)) {
+            if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+                continue;
+            resolved[key] = Math.round(value);
+        }
+    }
+    return resolved;
+}
+export function decideTrust(input) {
+    const { source, userTrusted, verifiedIntegrity, devMode } = input;
+    let tier;
+    let reason;
+    switch (source) {
+        case "builtin":
+            tier = "trusted-import";
+            reason = "builtin plugin is always trusted";
+            break;
+        case "official":
+            tier = "trusted-import";
+            reason = "official registry plugin is trusted";
+            break;
+        case "local":
+            tier = "trusted-import";
+            reason = devMode ? "local plugin in dev mode" : "local plugin";
+            break;
+        case "npm":
+            if (userTrusted && verifiedIntegrity) {
+                tier = "trusted-import";
+                reason = "user-trusted npm plugin with verified integrity";
+            }
+            else {
+                tier = "sandbox";
+                reason = "npm plugin requires explicit user trust and verified integrity";
+            }
+            break;
+        case "git":
+            if (userTrusted) {
+                tier = "trusted-import";
+                reason = "user-trusted git plugin";
+            }
+            else {
+                tier = "sandbox";
+                reason = "git plugin requires explicit user trust";
+            }
+            break;
+        case "url":
+            tier = "sandbox";
+            reason = "URL-sourced plugins always run in sandbox";
+            break;
+    }
+    return {
+        tier,
+        source,
+        userTrusted,
+        verifiedIntegrity,
+        reason,
+    };
+}
+export function defaultPluginTrustDecision(input) {
+    return decideTrust({
+        source: input.source,
+        userTrusted: input.userTrusted ?? isTrustedPluginSource(input.source),
+        verifiedIntegrity: input.verifiedIntegrity ?? false,
+        devMode: input.devMode ?? false,
+    });
+}
+export function resolvePluginPolicyDecision(input) {
+    const userTrusted = input.userTrusted ?? isTrustedPluginSource(input.source);
+    const verifiedIntegrity = input.verifiedIntegrity ?? input.source === "official";
+    const capabilities = baseCapabilities(input.manifest);
+    const risk = input.risk ?? pluginRisk(input.manifest, { scope: "install" });
+    const trust = decideTrust({
+        source: input.source,
+        userTrusted,
+        verifiedIntegrity,
+        devMode: input.devMode ?? false,
+    });
+    const runtimeMode = resolveRuntimeMode({
+        source: input.source,
+        manifestMode: input.manifest.runtime?.mode,
+        devMode: input.devMode,
+        userTrusted,
+        risk,
+        forceProcess: input.forceProcess,
+        policy: input.policy,
+    });
+    return {
+        source: input.source,
+        capabilities,
+        risk,
+        trust,
+        runtimeMode,
+    };
+}
+export function trustReason(decision) {
+    const factors = [];
+    if (decision.userTrusted)
+        factors.push("user-trusted");
+    if (decision.verifiedIntegrity)
+        factors.push("integrity verified");
+    const factorText = factors.length > 0 ? ` (${factors.join(", ")})` : "";
+    return `${decision.reason} -> ${decision.tier}${factorText}`;
+}
+export function trustSummary(decision) {
+    const metadata = [];
+    if (decision.userTrusted)
+        metadata.push("trusted");
+    if (decision.verifiedIntegrity)
+        metadata.push("verified");
+    const meta = metadata.length > 0 ? ` [${metadata.join(", ")}]` : "";
+    return `${decision.source} -> ${decision.tier}${meta}`;
+}
+function defaultTrustedMode(source, policy) {
+    if (source === "local" && !policy.allowLocalInProcess)
+        return "process";
+    return "in-process";
+}
+export function validateRuntimePolicy(input) {
+    const results = [];
+    const requestedMode = input.manifest.runtime?.mode;
+    const effectiveMode = resolveRuntimeMode({
+        source: input.source,
+        manifestMode: requestedMode,
+        userTrusted: input.userTrusted,
+        risk: input.risk,
+        policy: input.policy,
+    });
+    if (requestedMode && requestedMode !== effectiveMode) {
+        results.push({
+            type: "warn",
+            message: `Plugin requested runtime mode "${requestedMode}" but Synergy will use "${effectiveMode}" for source=${input.source} and risk=${input.risk}.`,
+        });
+    }
+    const requestedTier = input.manifest.trust?.requestedTier;
+    if (input.trustTier === "sandbox" && requestedTier !== "sandbox") {
+        results.push({
+            type: "warn",
+            message: `Plugin has sandbox trust tier; effective runtime mode is "${effectiveMode}". Use process mode with explicit resource limits for strongest isolation.`,
+        });
+    }
+    if (requestedTier !== undefined && requestedTier !== input.trustTier) {
+        results.push({
+            type: "warn",
+            message: `Plugin requested trust tier "${requestedTier}" but was assigned "${input.trustTier}" (source=${input.source}). Runtime mode is "${effectiveMode}".`,
+        });
+    }
+    if (effectiveMode === "worker") {
+        const tools = input.manifest.permissions?.tools;
+        const hasShell = tools?.shell ?? false;
+        const hasFileWrite = tools?.filesystem === "write";
+        const hasMcpSpawn = tools?.mcp === "spawn";
+        const contributedTools = input.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("file_write");
+            if (hasMcpSpawn)
+                unsupported.push("mcp_spawn");
+            results.push({
+                type: "warn",
+                message: `Worker mode does not fully support: ${unsupported.join(", ")}. Use process mode for these capabilities.`,
+            });
+        }
+    }
+    if (effectiveMode === "process" && !input.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/retry.d.ts

@@ -0,0 +1,8 @@
+export interface RetryOptions {
+    attempts?: number;
+    delay?: number;
+    factor?: number;
+    maxDelay?: number;
+    retryIf?: (error: unknown) => boolean;
+}
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,33 @@
+const TRANSIENT_MESSAGES = [
+    "load failed",
+    "network connection was lost",
+    "network request failed",
+    "failed to fetch",
+    "econnreset",
+    "econnrefused",
+    "etimedout",
+    "socket hang up",
+];
+function isTransientError(error) {
+    if (!error)
+        return false;
+    const message = String(error instanceof Error ? error.message : error).toLowerCase();
+    return TRANSIENT_MESSAGES.some((m) => message.includes(m));
+}
+export async function retry(fn, options = {}) {
+    const { attempts = 3, delay = 500, factor = 2, maxDelay = 10000, retryIf = isTransientError } = options;
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === attempts - 1 || !retryIf(error))
+                throw error;
+            const wait = Math.min(delay * Math.pow(factor, attempt), maxDelay);
+            await new Promise((resolve) => setTimeout(resolve, wait));
+        }
+    }
+    throw lastError;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@ericsanchezok/synergy-util",
+  "version": "2.4.4",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    "./*": {
+      "import": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "4.1.8"
+  }
+}