@paperclipai/plugin-kubernetes 0.1.0 → 2026.620.0-canary.11

package/dist/lease-lifecycle.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Resume + destroy lifecycle helpers for Kubernetes sandbox leases.
+ *
+ * Resume semantics: a lease is resumable only while its workload resource
+ * (Sandbox CR or Job) still exists and its pod is Running/Ready (or becomes
+ * Ready within a short bounded wait). Unlike Daytona — where a stopped sandbox
+ * can be started again by ID — Kubernetes pods are NOT restartable: once the
+ * pod backing a lease is gone or terminally failed, the lease can never be
+ * revived in place. That asymmetry is intentional; the plugin reports the
+ * lease as expired and the server falls back to a fresh acquireLease, which
+ * provisions a new pod.
+ *
+ * Destroy semantics: the forced cleanup path. Deletes every resource
+ * acquireLease created (Sandbox CR / Job, its pod, the per-run Secret),
+ * treating 404s as success so it is idempotent and safe to call against
+ * half-deleted leases.
+ */
+import type { KubeClients } from "./kube-client.js";
+/** True when a Kubernetes API error means "resource not found" (HTTP 404). */
+export declare function isKubeNotFoundError(err: unknown): boolean;
+export type ResumeCheckResult = {
+    resumable: true;
+    podName: string | null;
+    phase: "Pending" | "Running";
+} | {
+    resumable: false;
+    reason: string;
+};
+export interface ResumeCheckInput {
+    namespace: string;
+    /** Workload resource name (Sandbox CR name or Job name) == providerLeaseId. */
+    name: string;
+    backend: "sandbox-cr" | "job";
+    /** Bounded wait for an existing Sandbox pod to report Ready. */
+    readyTimeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * Check whether the workload behind a lease is still alive and exec-able.
+ * Returns `resumable: false` (never throws "expected" states) when the
+ * resource is gone (404), terminally failed, terminating, or doesn't become
+ * Ready within the bounded wait — all of which mean the caller should fall
+ * back to a fresh acquireLease.
+ */
+export declare function checkLeaseResumable(clients: KubeClients, input: ResumeCheckInput): Promise<ResumeCheckResult>;
+export interface DestroyLeaseInput {
+    namespace: string;
+    /** Workload resource name (Sandbox CR name or Job name) == providerLeaseId. */
+    name: string;
+    backend: "sandbox-cr" | "job";
+    podName: string | null;
+    secretName: string | null;
+}
+/**
+ * Forcibly delete every resource acquireLease created for this lease.
+ * Workload first (its deletion cascades to the pod and, via ownerReferences,
+ * the per-run Secret in the normal case); then the pod and Secret explicitly
+ * so a wedged controller or broken ownerRef cannot strand them. Every delete
+ * treats 404 as success — destroy is idempotent.
+ */
+export declare function destroyLeaseResources(clients: KubeClients, input: DestroyLeaseInput): Promise<void>;
+//# sourceMappingURL=lease-lifecycle.d.ts.map

package/dist/lease-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-lifecycle.d.ts","sourceRoot":"","sources":["../src/lease-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQpD,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIzD;AAUD,MAAM,MAAM,iBAAiB,GACzB;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,GACzE;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,GAAG,KAAK,CAAC;IAC9B,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAoF5B;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,GAAG,KAAK,CAAC;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/lease-lifecycle.js

@@ -0,0 +1,155 @@
+/**
+ * Resume + destroy lifecycle helpers for Kubernetes sandbox leases.
+ *
+ * Resume semantics: a lease is resumable only while its workload resource
+ * (Sandbox CR or Job) still exists and its pod is Running/Ready (or becomes
+ * Ready within a short bounded wait). Unlike Daytona — where a stopped sandbox
+ * can be started again by ID — Kubernetes pods are NOT restartable: once the
+ * pod backing a lease is gone or terminally failed, the lease can never be
+ * revived in place. That asymmetry is intentional; the plugin reports the
+ * lease as expired and the server falls back to a fresh acquireLease, which
+ * provisions a new pod.
+ *
+ * Destroy semantics: the forced cleanup path. Deletes every resource
+ * acquireLease created (Sandbox CR / Job, its pod, the per-run Secret),
+ * treating 404s as success so it is idempotent and safe to call against
+ * half-deleted leases.
+ */
+import { deleteJob, findPodForJob, getJobStatus } from "./job-orchestrator.js";
+import { deleteSandboxCr, findPodForSandbox, waitForSandboxReady, } from "./sandbox-cr-orchestrator.js";
+/** True when a Kubernetes API error means "resource not found" (HTTP 404). */
+export function isKubeNotFoundError(err) {
+    const code = err.code
+        ?? err.statusCode;
+    return code === 404;
+}
+async function ignoreNotFound(promise) {
+    try {
+        await promise;
+    }
+    catch (err) {
+        if (!isKubeNotFoundError(err))
+            throw err;
+    }
+}
+/**
+ * Check whether the workload behind a lease is still alive and exec-able.
+ * Returns `resumable: false` (never throws "expected" states) when the
+ * resource is gone (404), terminally failed, terminating, or doesn't become
+ * Ready within the bounded wait — all of which mean the caller should fall
+ * back to a fresh acquireLease.
+ */
+export async function checkLeaseResumable(clients, input) {
+    if (input.backend === "sandbox-cr") {
+        // Bounded wait for the Sandbox to report Ready. waitForSandboxReady fails
+        // fast on Failed/Terminating; a timeout means the pod never came up. None
+        // of those states are resumable — k8s pods cannot be restarted in place.
+        try {
+            await waitForSandboxReady(clients, input.namespace, input.name, {
+                timeoutMs: input.readyTimeoutMs ?? 30_000,
+                pollMs: input.pollMs ?? 1_000,
+            });
+        }
+        catch (err) {
+            if (isKubeNotFoundError(err)) {
+                return { resumable: false, reason: "Sandbox CR no longer exists" };
+            }
+            return {
+                resumable: false,
+                reason: err instanceof Error ? err.message : String(err),
+            };
+        }
+        let podName;
+        try {
+            podName = await findPodForSandbox(clients, input.namespace, input.name);
+        }
+        catch (err) {
+            // CR deleted between the readiness check and the pod lookup.
+            if (isKubeNotFoundError(err)) {
+                return { resumable: false, reason: "Sandbox CR no longer exists" };
+            }
+            throw err;
+        }
+        if (!podName) {
+            return {
+                resumable: false,
+                reason: "Sandbox is Ready but no backing pod was found",
+            };
+        }
+        // Confirm the pod itself is Running and not being torn down — the CR
+        // status can lag pod deletion.
+        let pod;
+        try {
+            pod = await clients.core.readNamespacedPod({
+                namespace: input.namespace,
+                name: podName,
+            });
+        }
+        catch (err) {
+            if (isKubeNotFoundError(err)) {
+                return { resumable: false, reason: `Pod ${podName} no longer exists` };
+            }
+            throw err;
+        }
+        const podPhase = pod.status?.phase;
+        const terminating = Boolean(pod.metadata?.deletionTimestamp);
+        if (podPhase !== "Running" || terminating) {
+            return {
+                resumable: false,
+                reason: `Pod ${podName} is ${terminating ? "terminating" : podPhase ?? "in an unknown phase"}`,
+            };
+        }
+        return { resumable: true, podName, phase: "Running" };
+    }
+    // ── Job backend ───────────────────────────────────────────────────────────
+    let status;
+    try {
+        status = await getJobStatus(clients, input.namespace, input.name);
+    }
+    catch (err) {
+        if (isKubeNotFoundError(err)) {
+            return { resumable: false, reason: "Job no longer exists" };
+        }
+        throw err;
+    }
+    if (status.phase === "Succeeded" || status.phase === "Failed") {
+        // Terminal Jobs cannot be re-run in place.
+        return { resumable: false, reason: `Job is ${status.phase}` };
+    }
+    // Pending/Running Jobs are resumable: execute() waits for completion
+    // itself, so a not-yet-scheduled pod (podName null) is fine here.
+    const podName = await findPodForJob(clients, input.namespace, input.name);
+    return {
+        resumable: true,
+        podName,
+        phase: status.phase === "Running" ? "Running" : "Pending",
+    };
+}
+/**
+ * Forcibly delete every resource acquireLease created for this lease.
+ * Workload first (its deletion cascades to the pod and, via ownerReferences,
+ * the per-run Secret in the normal case); then the pod and Secret explicitly
+ * so a wedged controller or broken ownerRef cannot strand them. Every delete
+ * treats 404 as success — destroy is idempotent.
+ */
+export async function destroyLeaseResources(clients, input) {
+    if (input.backend === "sandbox-cr") {
+        await ignoreNotFound(deleteSandboxCr(clients, input.namespace, input.name));
+    }
+    else {
+        await ignoreNotFound(deleteJob(clients, input.namespace, input.name));
+    }
+    if (input.podName) {
+        await ignoreNotFound(clients.core.deleteNamespacedPod({
+            namespace: input.namespace,
+            name: input.podName,
+        }));
+    }
+    if (input.secretName) {
+        await ignoreNotFound(clients.core.deleteNamespacedSecret({
+            namespace: input.namespace,
+            name: input.secretName,
+        }));
+    }
+}
+//# sourceMappingURL=lease-lifecycle.js.map

package/dist/lease-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-lifecycle.js","sourceRoot":"","sources":["../src/lease-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,4 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+declare const manifest: PaperclipPluginManifestV1;
+export default manifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAKzE,QAAA,MAAM,QAAQ,EAAE,yBAiHf,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,108 @@
+const PLUGIN_ID = "paperclip.kubernetes-sandbox-provider";
+const PLUGIN_VERSION = "0.1.0-alpha.1";
+const manifest = {
+    id: PLUGIN_ID,
+    apiVersion: 1,
+    version: PLUGIN_VERSION,
+    displayName: "Kubernetes Sandbox (alpha)",
+    description: "Built on kubernetes-sigs/agent-sandbox (v1alpha1). ALPHA — expect breaking changes as the upstream CRD evolves. Falls back to stable batch/v1 Job mode for clusters without agent-sandbox installed. First-party Paperclip sandbox-provider plugin for Kubernetes.",
+    author: "Paperclip",
+    categories: ["automation"],
+    capabilities: ["environment.drivers.register"],
+    entrypoints: {
+        worker: "./dist/worker.js",
+    },
+    environmentDrivers: [
+        {
+            driverKey: "kubernetes",
+            kind: "sandbox_provider",
+            displayName: "Kubernetes",
+            description: "Dispatches agent runs in per-tenant Kubernetes namespaces. Default backend (sandbox-cr, alpha) uses kubernetes-sigs/agent-sandbox for multi-command exec; fallback backend (job) uses stable batch/v1 Job for clusters without agent-sandbox installed.",
+            configSchema: {
+                type: "object",
+                properties: {
+                    inCluster: {
+                        type: "boolean",
+                        description: "When true, the plugin uses the in-pod ServiceAccount credentials. Requires paperclip-server to be running inside the target cluster.",
+                    },
+                    kubeconfig: {
+                        type: "string",
+                        format: "secret-ref",
+                        description: "Inline kubeconfig YAML. Paste a kubeconfig or an existing Paperclip secret reference; pasted values are stored as company secrets.",
+                    },
+                    namespacePrefix: {
+                        type: "string",
+                        description: "Prefix for the per-company tenant namespace (default: paperclip-).",
+                    },
+                    companySlug: {
+                        type: "string",
+                        description: "Override the auto-derived company slug used in the tenant namespace name.",
+                    },
+                    imageRegistry: {
+                        type: "string",
+                        description: "Override the default registry for agent runtime images (default: ghcr.io/paperclipai).",
+                    },
+                    imageAllowList: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Glob patterns of allowed `target.imageOverride` values. Empty list = no override permitted.",
+                    },
+                    imagePullSecrets: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Names of pre-created Docker image pull secrets in the tenant namespace.",
+                    },
+                    egressAllowFqdns: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Additional FQDNs to allow egress to from agent pods. Adapter-default FQDNs (e.g. api.anthropic.com) are added automatically.",
+                    },
+                    egressAllowCidrs: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Additional CIDRs to allow egress to from agent pods.",
+                    },
+                    egressMode: {
+                        type: "string",
+                        enum: ["standard", "cilium"],
+                        description: "Network policy mode. `cilium` enables FQDN-based egress filtering via CiliumNetworkPolicy.",
+                    },
+                    runtimeClassName: {
+                        type: "string",
+                        description: "Optional RuntimeClass for pod isolation (e.g. `kata-fc` for Firecracker-backed microVMs). Cluster must have the RuntimeClass installed.",
+                    },
+                    serviceAccountAnnotations: {
+                        type: "object",
+                        additionalProperties: { type: "string" },
+                        description: "Annotations applied to the per-tenant ServiceAccount (e.g. `eks.amazonaws.com/role-arn` for IRSA).",
+                    },
+                    jobTtlSecondsAfterFinished: {
+                        type: "integer",
+                        minimum: 0,
+                        description: "Seconds after a Job completes before it is garbage-collected (default: 900).",
+                    },
+                    podActivityDeadlineSec: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "Hard ceiling on a single run's wall-clock time (default: 3600).",
+                    },
+                    adapterType: {
+                        type: "string",
+                        description: "The adapter type that Jobs in this environment will run (e.g. `claude_local`, `codex_local`). Defaults to `claude_local`. Each environment is bound to one adapter; create multiple environments for different adapters.",
+                    },
+                    backend: {
+                        type: "string",
+                        enum: ["sandbox-cr", "job"],
+                        description: "sandbox-cr (default, alpha — requires kubernetes-sigs/agent-sandbox installed) | job (stable fallback — batch/v1 Job, one-shot entrypoint, no multi-command exec)",
+                    },
+                },
+                anyOf: [
+                    { required: ["inCluster"] },
+                    { required: ["kubeconfig"] },
+                ],
+            },
+        },
+    ],
+};
+export default manifest;
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/network-policy.d.ts

@@ -0,0 +1,18 @@
+export interface BuildNetworkPolicyInput {
+    namespace: string;
+    paperclipServerNamespace: string;
+    egressAllowCidrs: string[];
+    /**
+     * Adapter-configured FQDNs (e.g. `api.anthropic.com`). Standard
+     * NetworkPolicy cannot express FQDNs natively — only Cilium can.
+     * When this list is non-empty AND no explicit `egressAllowCidrs`
+     * was provided, the standard NetworkPolicy falls back to "public
+     * IPv4 except RFC1918/link-local/loopback/multicast" so the
+     * configured FQDNs at least become reachable. This is broader
+     * than the operator probably wants — switch to `egressMode:
+     * "cilium"` for exact FQDN allow-listing in production.
+     */
+    egressAllowFqdns?: string[];
+}
+export declare function buildNetworkPolicyManifests(input: BuildNetworkPolicyInput): Record<string, unknown>[];
+//# sourceMappingURL=network-policy.d.ts.map

package/dist/network-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-policy.d.ts","sourceRoot":"","sources":["../src/network-policy.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB,EAAE,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AA2BD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAyFrG"}

package/dist/network-policy.js

@@ -0,0 +1,113 @@
+/**
+ * IPv4 ranges to carve out of `0.0.0.0/0` when we apply the
+ * public-internet fallback. Keeps agent pods from reaching cluster
+ * internals (RFC1918), node link-local + AWS IMDS (169.254.0.0/16),
+ * cluster loopback (127.0.0.0/8), CGNAT (100.64.0.0/10), this-network
+ * (0.0.0.0/8), and multicast (224.0.0.0/4).
+ */
+const PRIVATE_AND_LINK_LOCAL_EXCEPT_CIDRS = [
+    "0.0.0.0/8",
+    "10.0.0.0/8",
+    "100.64.0.0/10",
+    "127.0.0.0/8",
+    "169.254.0.0/16",
+    "172.16.0.0/12",
+    "192.168.0.0/16",
+    "224.0.0.0/4",
+];
+// Design note: the deny-all baseline blocks all ingress to agent pods.
+// Paperclip-server does NOT push to agent pods — the agent shim makes
+// outbound calls to paperclip-server via the egress allow-list (port 3100).
+// This pull/callback model means no ingress rule is needed. If a future
+// feature requires server→agent push (e.g. forced shutdown, live exec),
+// add a targeted ingress rule here scoped to the paperclip-server pod
+// selector.
+export function buildNetworkPolicyManifests(input) {
+    const denyAll = {
+        apiVersion: "networking.k8s.io/v1",
+        kind: "NetworkPolicy",
+        metadata: {
+            name: "paperclip-deny-all",
+            namespace: input.namespace,
+            labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+        },
+        spec: {
+            podSelector: {},
+            policyTypes: ["Ingress", "Egress"],
+        },
+    };
+    const egressAllow = {
+        apiVersion: "networking.k8s.io/v1",
+        kind: "NetworkPolicy",
+        metadata: {
+            name: "paperclip-egress-allow",
+            namespace: input.namespace,
+            labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+        },
+        spec: {
+            podSelector: { matchLabels: { "paperclip.io/role": "agent" } },
+            policyTypes: ["Egress"],
+            egress: [
+                {
+                    to: [
+                        {
+                            namespaceSelector: { matchLabels: { "kubernetes.io/metadata.name": "kube-system" } },
+                            podSelector: { matchLabels: { "k8s-app": "kube-dns" } },
+                        },
+                    ],
+                    ports: [
+                        { protocol: "UDP", port: 53 },
+                        { protocol: "TCP", port: 53 },
+                    ],
+                },
+                {
+                    to: [
+                        {
+                            namespaceSelector: { matchLabels: { "kubernetes.io/metadata.name": input.paperclipServerNamespace } },
+                            podSelector: { matchLabels: { app: "paperclip-server" } },
+                        },
+                    ],
+                    ports: [{ protocol: "TCP", port: 3100 }],
+                },
+                // NOTE: operator-supplied CIDRs are intentionally NOT port-scoped —
+                // operators may need them for non-HTTP services (e.g. private VCS
+                // mirrors, S3 endpoints, internal artifact registries). Operators
+                // should keep CIDRs as specific as possible. For HTTP/HTTPS-only
+                // LLM endpoints, the public-IPv4 fallback below is port-scoped
+                // (TCP 80/443).
+                ...input.egressAllowCidrs.map((cidr) => ({
+                    to: [{ ipBlock: { cidr } }],
+                })),
+                // Standard-NetworkPolicy fallback for FQDN-based egress. If the
+                // adapter requires FQDNs (e.g. api.anthropic.com) and the
+                // operator didn't supply explicit CIDRs, allow public IPv4 with
+                // private/link-local/loopback/multicast carved out. This makes
+                // the default `egressMode: "standard"` config functional out of
+                // the box for cloud LLM APIs without inadvertently exposing
+                // cluster internals or link-local metadata endpoints. Operators
+                // who want exact FQDN enforcement should use `egressMode: "cilium"`.
+                ...(input.egressAllowCidrs.length === 0 &&
+                    (input.egressAllowFqdns?.length ?? 0) > 0
+                    ? [
+                        {
+                            to: [
+                                {
+                                    ipBlock: {
+                                        cidr: "0.0.0.0/0",
+                                        except: PRIVATE_AND_LINK_LOCAL_EXCEPT_CIDRS,
+                                    },
+                                },
+                            ],
+                            ports: [
+                                { protocol: "TCP", port: 443 },
+                                { protocol: "TCP", port: 80 },
+                            ],
+                        },
+                    ]
+                    : []),
+            ],
+        },
+    };
+    return [denyAll, egressAllow];
+}
+//# sourceMappingURL=network-policy.js.map

package/dist/network-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-policy.js","sourceRoot":"","sources":["../src/network-policy.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+declare const plugin: import("@paperclipai/plugin-sdk").PaperclipPlugin;
+export default plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AA+GA,QAAA,MAAM,MAAM,mDA8uBV,CAAC;AAEH,eAAe,MAAM,CAAC"}