@vibecontrols/plugin-sdk 2026.509.1

package/dist/index.js

@@ -0,0 +1,595 @@
+import { Elysia } from 'elysia';
+import { createServer } from 'net';
+
+// src/contract/index.ts
+var FULL_TRUST_CAPS = {
+  storage: "rw",
+  secrets: "rw",
+  gateway: true,
+  broadcast: true,
+  subprocess: true,
+  audit: true,
+  telemetry: true,
+  singletonOnly: false,
+  requiresIsolation: false
+};
+
+// src/lifecycle/index.ts
+function createLifecycleHooks(spec) {
+  const { name, onInit, onShutdown, telemetryEventName, skipPlatforms } = spec;
+  return {
+    onServerStart: async (_app, hostServices) => {
+      if (skipPlatforms && skipPlatforms.includes(process.platform)) {
+        process.stderr.write(
+          `[${name}] skipping init on unsupported platform '${process.platform}'
+`
+        );
+        return;
+      }
+      if (onInit) {
+        await onInit(hostServices);
+      }
+      if (telemetryEventName) {
+        hostServices.telemetry?.emit(telemetryEventName, { plugin: name });
+      }
+    },
+    onServerStop: async (hostServices) => {
+      if (onShutdown) {
+        await onShutdown(hostServices);
+      }
+    }
+  };
+}
+
+// src/cli/multimode.ts
+function pickOutputMode(flags) {
+  if (flags.json) return "json";
+  if (flags.plain) return "plain";
+  if (flags.interactive) return "interactive";
+  return "auto";
+}
+function isCi() {
+  return !!process.env.CI || !!process.env.NO_COLOR || process.env.TERM === "dumb";
+}
+function stdoutIsTty() {
+  return Boolean(process.stdout.isTTY);
+}
+async function runMultimode(opts) {
+  const data = await opts.fetchData();
+  const mode = opts.mode ?? "auto";
+  if (mode === "json") {
+    const shaped = opts.json ? opts.json(data) : data;
+    process.stdout.write(`${JSON.stringify(shaped, null, 2)}
+`);
+    return;
+  }
+  if (mode === "plain") {
+    await opts.plain(data);
+    return;
+  }
+  const wantInteractive = (mode === "interactive" || stdoutIsTty() && !isCi()) && !!opts.interactive;
+  if (wantInteractive && opts.interactive) {
+    try {
+      await opts.interactive(data);
+      return;
+    } catch {
+    }
+  }
+  await opts.plain(data);
+}
+function maybePrintJson(flags, data) {
+  if (!flags.json) return false;
+  process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+  return true;
+}
+
+// src/cli/redaction.ts
+var SENSITIVE_KEY_RE = /(token|secret|password|apikey|api_key|key|auth|credential|email)/i;
+function redact(value) {
+  return redactInner(value);
+}
+function redactInner(value) {
+  if (value === null || value === void 0) return value;
+  if (Array.isArray(value)) return value.map(redactInner);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (SENSITIVE_KEY_RE.test(k)) {
+        out[k] = "[redacted]";
+        continue;
+      }
+      out[k] = redactInner(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/cli/command-builder.ts
+var CliCommandBuilder = class {
+  constructor(program) {
+    this.program = program;
+  }
+  program;
+  /**
+   * Register a `<name>` sub-command that fetches once and renders via
+   * `--json` / `--plain` / interactive (when stdout is a TTY).
+   */
+  addStatusCommand(name, spec) {
+    this.program.command(name).description(spec.description).option("--json", "emit JSON for scripting").option("--plain", "force plain text (no opentui)").action(async (opts) => {
+      const mode = pickOutputMode(opts);
+      await runMultimode({
+        mode,
+        fetchData: spec.fetchData,
+        plain: async (data) => {
+          const view = spec.redact ? redact(data) : data;
+          if (spec.format) {
+            await spec.format(view);
+            return;
+          }
+          process.stdout.write(`${JSON.stringify(view, null, 2)}
+`);
+        },
+        json: (data) => spec.redact ? redact(data) : data
+      });
+    });
+    return this;
+  }
+  /** Escape hatch: hand back the underlying commander Command. */
+  command() {
+    return this.program;
+  }
+};
+var RoutesBuilder = class {
+  constructor(pluginName, hostServices) {
+    this.pluginName = pluginName;
+    this.hostServices = hostServices;
+  }
+  pluginName;
+  hostServices;
+  prefix;
+  apiKeyResolver;
+  errorHandlerEnabled = false;
+  loggingEnabled = false;
+  withPrefix(prefix) {
+    this.prefix = prefix;
+    return this;
+  }
+  withAuth(getApiKey) {
+    this.apiKeyResolver = getApiKey;
+    return this;
+  }
+  withErrorHandler() {
+    this.errorHandlerEnabled = true;
+    return this;
+  }
+  withLogging() {
+    this.loggingEnabled = true;
+    return this;
+  }
+  /**
+   * Build the configured Elysia instance. Plugins typically call
+   * `.derive` / `.get` / `.post` on the result before returning it from
+   * `createRoutes()`.
+   */
+  build() {
+    const opts = this.prefix ? { prefix: this.prefix } : void 0;
+    const app = new Elysia(opts);
+    if (this.apiKeyResolver) {
+      const resolver = this.apiKeyResolver;
+      app.onBeforeHandle(async ({ request, set }) => {
+        const supplied = request.headers.get("x-api-key");
+        const expected = await resolver();
+        if (!supplied || supplied !== expected) {
+          set.status = 401;
+          return { error: "unauthorized" };
+        }
+        return;
+      });
+    }
+    if (this.errorHandlerEnabled) {
+      const pluginName = this.pluginName;
+      const logger = this.hostServices?.logger;
+      app.onError(({ error, set }) => {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error?.(pluginName, "route error", { message });
+        set.status = 500;
+        return { error: message };
+      });
+    }
+    if (this.loggingEnabled) {
+      const pluginName = this.pluginName;
+      const logger = this.hostServices?.logger;
+      app.onRequest(({ request }) => {
+        logger?.debug?.(pluginName, "request", {
+          method: request.method,
+          url: request.url
+        });
+      });
+    }
+    return app;
+  }
+};
+
+// src/telemetry/index.ts
+var TelemetryEmitter = class {
+  constructor(pluginName, pluginVersion, hostServices) {
+    this.pluginName = pluginName;
+    this.pluginVersion = pluginVersion;
+    this.hostServices = hostServices;
+  }
+  pluginName;
+  pluginVersion;
+  hostServices;
+  /** Emit `eventName` with auto-tagged plugin/version/timestamp. */
+  emit(eventName, payload) {
+    const target = this.hostServices?.telemetry;
+    if (!target) return;
+    target.emit(eventName, {
+      plugin: this.pluginName,
+      version: this.pluginVersion,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...payload ?? {}
+    });
+  }
+  /** `<pluginName>.ready` shorthand. */
+  emitReady(context) {
+    this.emit(`${this.pluginName}.ready`, context);
+  }
+  /** `<pluginName>.error` shorthand — extracts message from Error. */
+  emitError(error, context) {
+    this.emit(`${this.pluginName}.error`, {
+      message: error.message,
+      ...context ?? {}
+    });
+  }
+  /** Generic event-type emit (alias of emit). */
+  emitEvent(type, payload) {
+    this.emit(type, payload);
+  }
+};
+
+// src/log/index.ts
+var BoundLogger = class {
+  constructor(logger, source) {
+    this.logger = logger;
+    this.source = source;
+  }
+  logger;
+  source;
+  info(message, meta) {
+    this.logger?.info?.(this.source, message, meta);
+  }
+  warn(message, meta) {
+    this.logger?.warn?.(this.source, message, meta);
+  }
+  error(message, meta) {
+    this.logger?.error?.(this.source, message, meta);
+  }
+  debug(message, meta) {
+    this.logger?.debug?.(this.source, message, meta);
+  }
+};
+
+// src/storage/typed-store.ts
+var TypedStore = class {
+  constructor(storage, namespace, key, logger, pluginName = "plugin") {
+    this.storage = storage;
+    this.namespace = namespace;
+    this.key = key;
+    this.logger = logger;
+    this.pluginName = pluginName;
+  }
+  storage;
+  namespace;
+  key;
+  logger;
+  pluginName;
+  async get() {
+    const raw = await this.storage.get(this.namespace, this.key);
+    if (raw === null || raw === void 0) return null;
+    if (typeof raw !== "string") {
+      return raw;
+    }
+    try {
+      return JSON.parse(raw);
+    } catch (err) {
+      this.logger?.error?.(this.pluginName, "TypedStore: corrupt JSON", {
+        namespace: this.namespace,
+        key: this.key,
+        message: err instanceof Error ? err.message : String(err)
+      });
+      return null;
+    }
+  }
+  async set(value) {
+    await this.storage.set(this.namespace, this.key, JSON.stringify(value));
+  }
+  async delete() {
+    return this.storage.delete(this.namespace, this.key);
+  }
+};
+var NamespaceStore = class {
+  constructor(storage, namespace, logger, pluginName = "plugin") {
+    this.storage = storage;
+    this.namespace = namespace;
+    this.logger = logger;
+    this.pluginName = pluginName;
+  }
+  storage;
+  namespace;
+  logger;
+  pluginName;
+  /** Get a typed handle for `(this.namespace, key)`. */
+  typed(key) {
+    return new TypedStore(this.storage, this.namespace, key, this.logger, this.pluginName);
+  }
+  async get(key) {
+    return this.storage.get(this.namespace, key);
+  }
+  async set(key, value) {
+    return this.storage.set(this.namespace, key, value);
+  }
+  async delete(key) {
+    return this.storage.delete(this.namespace, key);
+  }
+};
+
+// src/config/index.ts
+var ConfigManager = class {
+  constructor(pluginName, hostServices, logger) {
+    this.pluginName = pluginName;
+    this.hostServices = hostServices;
+    this.logger = logger;
+    this.envPrefix = `VIBE_${pluginName.toUpperCase().replace(/-/g, "_")}_`;
+  }
+  pluginName;
+  hostServices;
+  logger;
+  envPrefix;
+  envName(key) {
+    return `${this.envPrefix}${key.toUpperCase().replace(/-/g, "_")}`;
+  }
+  /**
+   * Resolve a string config value. Returns `defaultValue` (or undefined)
+   * when neither env nor host config has it.
+   */
+  async get(key, defaultValue) {
+    const fromEnv = process.env[this.envName(key)];
+    if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
+    const fromHost = await this.hostServices?.getConfig?.(`${this.pluginName}.${key}`);
+    if (fromHost !== void 0 && fromHost !== "") return fromHost;
+    return defaultValue;
+  }
+  /** Like `get`, but throw if the key resolves to undefined / empty. */
+  async getRequired(key) {
+    const v = await this.get(key);
+    if (v === void 0 || v === "") {
+      throw new Error(
+        `[${this.pluginName}] required config '${key}' is missing (env ${this.envName(key)} or host config '${this.pluginName}.${key}')`
+      );
+    }
+    return v;
+  }
+  async getInt(key, defaultValue) {
+    const raw = await this.get(key);
+    if (raw === void 0) return defaultValue;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isNaN(parsed)) {
+      this.logger?.warn?.(this.pluginName, "ConfigManager: invalid int", {
+        key,
+        raw
+      });
+      return defaultValue;
+    }
+    return parsed;
+  }
+  async getBoolean(key, defaultValue) {
+    const raw = await this.get(key);
+    if (raw === void 0) return defaultValue;
+    const v = raw.toLowerCase();
+    if (v === "true" || v === "1" || v === "yes" || v === "on") return true;
+    if (v === "false" || v === "0" || v === "no" || v === "off") return false;
+    this.logger?.warn?.(this.pluginName, "ConfigManager: invalid bool", {
+      key,
+      raw
+    });
+    return defaultValue;
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function gracefulKill(pid, timeoutMs = 3e3, logger) {
+  const source = "subprocess";
+  if (!isProcessAlive(pid)) return;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (err) {
+    logger?.warn?.(source, "SIGTERM failed", {
+      pid,
+      message: err instanceof Error ? err.message : String(err)
+    });
+    return;
+  }
+  const pollMs = 50;
+  let elapsed = 0;
+  while (elapsed < timeoutMs) {
+    await sleep(pollMs);
+    elapsed += pollMs;
+    if (!isProcessAlive(pid)) return;
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch (err) {
+    logger?.warn?.(source, "SIGKILL failed", {
+      pid,
+      message: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+async function findAvailablePort(start, range = 200) {
+  for (let i = 0; i < range; i++) {
+    const port = start + i;
+    if (await isPortFree(port)) return port;
+  }
+  throw new Error(`findAvailablePort: no port free in [${start}, ${start + range - 1}]`);
+}
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    try {
+      server.listen({ port, host: "127.0.0.1" });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+// src/http/index.ts
+var HttpClient = class {
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl;
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+    this.maxAttempts = options.maxAttempts ?? 3;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  baseUrl;
+  timeoutMs;
+  maxAttempts;
+  defaultHeaders;
+  fetchImpl;
+  async get(path, options) {
+    return this.request("GET", path, void 0, options);
+  }
+  async post(path, body, options) {
+    return this.request("POST", path, body, options);
+  }
+  async request(method, path, body, options) {
+    const url = `${this.baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+    const headers = {
+      ...this.defaultHeaders,
+      ...options?.headers ?? {}
+    };
+    if (body !== void 0 && headers["content-type"] === void 0) {
+      headers["content-type"] = "application/json";
+    }
+    let lastError;
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      const callerSignal = options?.signal;
+      const onCallerAbort = () => controller.abort();
+      callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+      try {
+        const res = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: body === void 0 ? void 0 : JSON.stringify(body),
+          signal: controller.signal
+        });
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status} ${res.statusText} for ${method} ${url}`);
+        }
+        const text = await res.text();
+        if (!text) return void 0;
+        try {
+          return JSON.parse(text);
+        } catch {
+          return text;
+        }
+      } catch (err) {
+        lastError = err;
+        if (attempt >= this.maxAttempts) break;
+        const backoff = 100 * 2 ** (attempt - 1);
+        await new Promise((r) => setTimeout(r, backoff));
+      } finally {
+        clearTimeout(timer);
+        callerSignal?.removeEventListener("abort", onCallerAbort);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error(`HttpClient: request failed for ${method} ${url}`);
+  }
+};
+
+// src/providers/index.ts
+var ProviderRegistry = class {
+  constructor(hostServices) {
+    this.hostServices = hostServices;
+  }
+  hostServices;
+  getServiceRegistry() {
+    return this.hostServices?.serviceRegistry;
+  }
+  registerProvider(type, name, provider) {
+    this.hostServices?.serviceRegistry?.registerService(type, name, provider);
+  }
+  getProvider(type, name) {
+    return this.hostServices?.serviceRegistry?.getService(type, name);
+  }
+  listProviders(type) {
+    const reg = this.hostServices?.serviceRegistry;
+    return reg?.listProvidersForType?.(type) ?? [];
+  }
+  /**
+   * Register a CLI contribution bundle (status sections + doctor checks).
+   * No-op when the host doesn't expose `cliContributors`.
+   */
+  withCliContribution(contribution) {
+    const contributors = this.hostServices?.cliContributors;
+    if (!contributors) return;
+    for (const section of contribution.statusSections ?? []) {
+      contributors.addStatusSection?.(section);
+    }
+    for (const check of contribution.doctorChecks ?? []) {
+      contributors.addDoctorCheck?.(check);
+    }
+  }
+};
+
+// src/audit/index.ts
+var AuditLogger = class {
+  constructor(source, hostServices) {
+    this.source = source;
+    this.hostServices = hostServices;
+  }
+  source;
+  hostServices;
+  emit(event, payload) {
+    this.hostServices?.audit?.emit(event, {
+      source: this.source,
+      ...payload ?? {}
+    });
+  }
+};
+
+// src/broadcast/index.ts
+var BroadcastEmitter = class {
+  constructor(hostServices) {
+    this.hostServices = hostServices;
+  }
+  hostServices;
+  broadcast(type, payload) {
+    this.hostServices?.broadcast?.(type, payload);
+  }
+};
+
+export { AuditLogger, BoundLogger, BroadcastEmitter, CliCommandBuilder, ConfigManager, FULL_TRUST_CAPS, HttpClient, NamespaceStore, ProviderRegistry, RoutesBuilder, TelemetryEmitter, TypedStore, createLifecycleHooks, findAvailablePort, gracefulKill, isProcessAlive, maybePrintJson, pickOutputMode, redact, runMultimode, sleep };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,31 @@
+import { HostServices } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/lifecycle
+ *
+ * Collapses the boilerplate every plugin re-types around `onServerStart` /
+ * `onServerStop`: emit a one-shot ready telemetry, optionally skip on a
+ * platform list, dispatch user init/shutdown hooks.
+ *
+ * Cross-platform: pure JS, no fs / spawn.
+ */
+
+interface LifecycleSpec {
+    /** Plugin name — used for telemetry tagging + skip log messages. */
+    name: string;
+    /** Optional init handler — called with hostServices on onServerStart. */
+    onInit?: (hostServices: HostServices) => void | Promise<void>;
+    /** Optional shutdown handler — called with hostServices on onServerStop. */
+    onShutdown?: (hostServices: HostServices) => void | Promise<void>;
+    /** Telemetry event name to auto-emit on init (after onInit returns). */
+    telemetryEventName?: string;
+    /** process.platform values the plugin does NOT support — early-return on match. */
+    skipPlatforms?: NodeJS.Platform[];
+}
+interface LifecycleHooks {
+    onServerStart: (app: unknown, hostServices: HostServices) => Promise<void>;
+    onServerStop: (hostServices: HostServices) => Promise<void>;
+}
+declare function createLifecycleHooks(spec: LifecycleSpec): LifecycleHooks;
+
+export { type LifecycleHooks, type LifecycleSpec, createLifecycleHooks };

package/dist/lifecycle/index.js

@@ -0,0 +1,30 @@
+// src/lifecycle/index.ts
+function createLifecycleHooks(spec) {
+  const { name, onInit, onShutdown, telemetryEventName, skipPlatforms } = spec;
+  return {
+    onServerStart: async (_app, hostServices) => {
+      if (skipPlatforms && skipPlatforms.includes(process.platform)) {
+        process.stderr.write(
+          `[${name}] skipping init on unsupported platform '${process.platform}'
+`
+        );
+        return;
+      }
+      if (onInit) {
+        await onInit(hostServices);
+      }
+      if (telemetryEventName) {
+        hostServices.telemetry?.emit(telemetryEventName, { plugin: name });
+      }
+    },
+    onServerStop: async (hostServices) => {
+      if (onShutdown) {
+        await onShutdown(hostServices);
+      }
+    }
+  };
+}
+
+export { createLifecycleHooks };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/log/index.d.ts

@@ -0,0 +1,22 @@
+import { SdkLogger } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/log
+ *
+ * `BoundLogger` binds the `source` field once so plugin code reads
+ * `log.info("started")` instead of `logger.info("my-plugin", "started")`
+ * at every call-site. No-op when the underlying logger is absent.
+ */
+
+type Meta = Record<string, unknown>;
+declare class BoundLogger {
+    private readonly logger;
+    private readonly source;
+    constructor(logger: SdkLogger | undefined, source: string);
+    info(message: string, meta?: Meta): void;
+    warn(message: string, meta?: Meta): void;
+    error(message: string, meta?: Meta): void;
+    debug(message: string, meta?: Meta): void;
+}
+
+export { BoundLogger };

package/dist/log/index.js

@@ -0,0 +1,25 @@
+// src/log/index.ts
+var BoundLogger = class {
+  constructor(logger, source) {
+    this.logger = logger;
+    this.source = source;
+  }
+  logger;
+  source;
+  info(message, meta) {
+    this.logger?.info?.(this.source, message, meta);
+  }
+  warn(message, meta) {
+    this.logger?.warn?.(this.source, message, meta);
+  }
+  error(message, meta) {
+    this.logger?.error?.(this.source, message, meta);
+  }
+  debug(message, meta) {
+    this.logger?.debug?.(this.source, message, meta);
+  }
+};
+
+export { BoundLogger };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map