@vibecontrols/plugin-sdk 2026.509.1

package/dist/providers/index.d.ts

@@ -0,0 +1,29 @@
+import { HostServices, ServiceRegistry } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/providers
+ *
+ * Thin façade over `hostServices.serviceRegistry` — provider plugins call
+ * `register` and consumer plugins call `get` / `list`. Every method is a
+ * graceful no-op when the host has no registry.
+ */
+
+interface CliContribution {
+    statusSections?: unknown[];
+    doctorChecks?: unknown[];
+}
+declare class ProviderRegistry {
+    private readonly hostServices?;
+    constructor(hostServices?: HostServices | undefined);
+    getServiceRegistry(): ServiceRegistry | undefined;
+    registerProvider<T>(type: string, name: string, provider: T): void;
+    getProvider<T>(type: string, name: string): T | undefined;
+    listProviders(type: string): string[];
+    /**
+     * Register a CLI contribution bundle (status sections + doctor checks).
+     * No-op when the host doesn't expose `cliContributors`.
+     */
+    withCliContribution(contribution: CliContribution): void;
+}
+
+export { type CliContribution, ProviderRegistry };

package/dist/providers/index.js

@@ -0,0 +1,38 @@
+// 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);
+    }
+  }
+};
+
+export { ProviderRegistry };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/routes/index.d.ts

@@ -0,0 +1,37 @@
+import { Elysia } from 'elysia';
+import { HostServices } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/routes
+ *
+ * RoutesBuilder — fluent wrapper around an Elysia instance with the four
+ * concerns every plugin reimplements: prefix, API-key auth, error handler,
+ * request logging.
+ *
+ * Elysia is a peer dependency — both type and value come from the consumer.
+ * If a plugin doesn't ship HTTP routes it never imports this module so
+ * elysia stays an optional peer.
+ */
+
+type ApiKeyResolver = () => string | Promise<string>;
+declare class RoutesBuilder {
+    private readonly pluginName;
+    private readonly hostServices?;
+    private prefix?;
+    private apiKeyResolver?;
+    private errorHandlerEnabled;
+    private loggingEnabled;
+    constructor(pluginName: string, hostServices?: HostServices | undefined);
+    withPrefix(prefix: string): this;
+    withAuth(getApiKey: ApiKeyResolver): this;
+    withErrorHandler(): this;
+    withLogging(): this;
+    /**
+     * Build the configured Elysia instance. Plugins typically call
+     * `.derive` / `.get` / `.post` on the result before returning it from
+     * `createRoutes()`.
+     */
+    build(): Elysia;
+}
+
+export { type ApiKeyResolver, RoutesBuilder };

package/dist/routes/index.js

@@ -0,0 +1,77 @@
+import { Elysia } from 'elysia';
+
+// src/routes/index.ts
+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;
+  }
+};
+
+export { RoutesBuilder };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/storage/index.d.ts

@@ -0,0 +1,36 @@
+import { StorageProvider, SdkLogger } from '../contract/index.js';
+
+/**
+ * Typed wrappers over a `StorageProvider`.
+ *
+ * `TypedStore<T>` is a single-key handle: `get/set/delete` against a fixed
+ * (namespace, key) pair, with JSON serialisation + corrupt-payload recovery.
+ * `NamespaceStore` groups multiple typed handles under one namespace and
+ * exposes raw get/set/delete for ad-hoc access.
+ */
+
+declare class TypedStore<T> {
+    private readonly storage;
+    private readonly namespace;
+    private readonly key;
+    private readonly logger?;
+    private readonly pluginName;
+    constructor(storage: StorageProvider, namespace: string, key: string, logger?: SdkLogger | undefined, pluginName?: string);
+    get(): Promise<T | null>;
+    set(value: T): Promise<void>;
+    delete(): Promise<boolean>;
+}
+declare class NamespaceStore {
+    private readonly storage;
+    private readonly namespace;
+    private readonly logger?;
+    private readonly pluginName;
+    constructor(storage: StorageProvider, namespace: string, logger?: SdkLogger | undefined, pluginName?: string);
+    /** Get a typed handle for `(this.namespace, key)`. */
+    typed<T>(key: string): TypedStore<T>;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+
+export { NamespaceStore, TypedStore };

package/dist/storage/index.js

@@ -0,0 +1,67 @@
+// 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);
+  }
+};
+
+export { NamespaceStore, TypedStore };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/subprocess/index.d.ts

@@ -0,0 +1,37 @@
+import { SdkLogger } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/subprocess
+ *
+ * Cross-platform subprocess helpers: graceful kill (SIGTERM → SIGKILL),
+ * liveness check, port-pool probing, sleep.
+ *
+ * Design notes:
+ * - `gracefulKill` uses SIGTERM first, polls `process.kill(pid, 0)` to
+ *   detect exit, then escalates to SIGKILL. On Windows SIGTERM still
+ *   arrives via Node's signal-emulation; we keep the same code path.
+ * - `findAvailablePort` prefers `Bun.listen` (zero-dep, fast) and falls
+ *   back to `node:net` so the helper works under pure Node hosts too.
+ *
+ * Cross-platform: pure Node + optional Bun runtime feature detection.
+ */
+
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Returns true if a process with `pid` is reachable from this process.
+ * Uses signal 0 — POSIX + Node's Windows shim both recognise it.
+ */
+declare function isProcessAlive(pid: number): boolean;
+/**
+ * Send SIGTERM, poll until the process exits or `timeoutMs` elapses, then
+ * escalate to SIGKILL if necessary.
+ */
+declare function gracefulKill(pid: number, timeoutMs?: number, logger?: SdkLogger): Promise<void>;
+/**
+ * Probe ports starting at `start` for `range` consecutive numbers; resolve
+ * with the first one that bind-tests cleanly. Throws if the whole range is
+ * occupied.
+ */
+declare function findAvailablePort(start: number, range?: number): Promise<number>;
+
+export { findAvailablePort, gracefulKill, isProcessAlive, sleep };

package/dist/subprocess/index.js

@@ -0,0 +1,69 @@
+import { createServer } from 'net';
+
+// src/subprocess/index.ts
+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);
+    }
+  });
+}
+
+export { findAvailablePort, gracefulKill, isProcessAlive, sleep };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.d.ts

@@ -0,0 +1,27 @@
+import { HostServices } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/telemetry
+ *
+ * `TelemetryEmitter` auto-tags every event with the plugin name + version
+ * + ISO timestamp before forwarding to `hostServices.telemetry?.emit`.
+ * No-op when the host doesn't expose the telemetry surface (e.g. plugin
+ * loaded without the `telemetry: true` capability).
+ */
+
+declare class TelemetryEmitter {
+    private readonly pluginName;
+    private readonly pluginVersion;
+    private readonly hostServices?;
+    constructor(pluginName: string, pluginVersion: string, hostServices?: HostServices | undefined);
+    /** Emit `eventName` with auto-tagged plugin/version/timestamp. */
+    emit(eventName: string, payload?: Record<string, unknown>): void;
+    /** `<pluginName>.ready` shorthand. */
+    emitReady(context?: Record<string, unknown>): void;
+    /** `<pluginName>.error` shorthand — extracts message from Error. */
+    emitError(error: Error, context?: Record<string, unknown>): void;
+    /** Generic event-type emit (alias of emit). */
+    emitEvent(type: string, payload?: Record<string, unknown>): void;
+}
+
+export { TelemetryEmitter };

package/dist/telemetry/index.js

@@ -0,0 +1,41 @@
+// 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);
+  }
+};
+
+export { TelemetryEmitter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/testing/index.d.ts

@@ -0,0 +1,31 @@
+import { HostServices, ProfileContext, VibePluginFactory } from '../contract/index.js';
+
+/**
+ * Mock factories for unit-testing plugins built on the SDK.
+ *
+ * The mocks return concrete `HostServices` / `ProfileContext` shapes with
+ * every function backed by Bun's built-in `mock()`. Consumers must run
+ * tests with `bun test` (the SDK is Bun-native by design).
+ */
+
+type DeepPartial<T> = T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Build a fully-stubbed `HostServices`. Every function is a Bun `mock()`,
+ * so tests can assert call counts / args. Pass `overrides` to replace
+ * specific fields (e.g. `{ telemetry: { emit: customMock } }`).
+ */
+declare function createMockHostServices(overrides?: DeepPartial<HostServices>): HostServices;
+declare function createMockProfileContext(overrides?: DeepPartial<ProfileContext>): ProfileContext;
+
+/**
+ * Test fixtures for downstream plugin authors.
+ *
+ * Currently exports a minimal `samplePlugin` factory that satisfies
+ * `VibePluginFactory` — handy as a baseline plugin object in tests.
+ */
+
+declare const samplePlugin: VibePluginFactory;
+
+export { createMockHostServices, createMockProfileContext, samplePlugin };

package/dist/testing/index.js

@@ -0,0 +1,97 @@
+import { mock } from 'bun:test';
+
+// src/testing/mocks.ts
+function createMockHostServices(overrides = {}) {
+  const storage = {
+    get: mock(async () => null),
+    set: mock(async () => void 0),
+    delete: mock(async () => true),
+    list: mock(async () => [])
+  };
+  const serviceRegistry = {
+    registerService: mock(() => void 0),
+    getService: mock(() => void 0),
+    listProvidersForType: mock(() => [])
+  };
+  const base = {
+    storage,
+    logger: {
+      debug: mock(() => void 0),
+      info: mock(() => void 0),
+      warn: mock(() => void 0),
+      error: mock(() => void 0),
+      setLevel: mock(() => void 0)
+    },
+    serviceRegistry,
+    getProvider: mock(() => void 0),
+    getAgentBaseUrl: mock(() => "http://localhost:3005"),
+    getAgentVersion: mock(() => "test"),
+    broadcast: mock(() => void 0),
+    // workspaceQuery's runtime contract is generic over T; the mock returns
+    // a permissive empty data shape that satisfies any caller-chosen T at
+    // runtime. The cast is the standard pattern for representing a generic
+    // method via a non-generic mock.
+    workspaceQuery: mock(async () => ({ data: {} })),
+    isGatewayConfigured: mock(() => false),
+    getAgentRecordId: mock(async () => null),
+    getWorkspaceId: mock(async () => null),
+    getConfig: mock(async () => void 0),
+    getPluginRegistry: mock(() => "https://verdaccio.tooling.internal.burdenoff.com/"),
+    getDataDir: mock(() => "/tmp/sdk-test"),
+    cliContributors: {
+      addStatusSection: mock(() => void 0),
+      addDoctorCheck: mock(() => void 0)
+    },
+    audit: { emit: mock(() => void 0) },
+    telemetry: { emit: mock(() => void 0) },
+    os: void 0
+  };
+  return mergeDeep(base, overrides);
+}
+function createMockProfileContext(overrides = {}) {
+  const base = {
+    name: "test-profile",
+    dataDir: "/tmp/sdk-test/profile",
+    logger: {
+      debug: mock(() => void 0),
+      info: mock(() => void 0),
+      warn: mock(() => void 0),
+      error: mock(() => void 0)
+    },
+    audit: { emit: mock(() => void 0) },
+    telemetry: { emit: mock(() => void 0) }
+  };
+  return mergeDeep(base, overrides);
+}
+function mergeDeep(base, overrides) {
+  if (overrides === void 0 || overrides === null) return base;
+  if (typeof overrides !== "object" || Array.isArray(overrides)) {
+    return overrides;
+  }
+  if (typeof base !== "object" || base === null || Array.isArray(base)) {
+    return overrides;
+  }
+  const out = { ...base };
+  for (const [k, v] of Object.entries(overrides)) {
+    const baseVal = base[k];
+    if (v !== null && typeof v === "object" && !Array.isArray(v) && baseVal !== null && typeof baseVal === "object" && !Array.isArray(baseVal)) {
+      out[k] = mergeDeep(baseVal, v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+// src/testing/fixtures.ts
+var samplePlugin = (_ctx) => ({
+  name: "sample-plugin",
+  version: "0.0.0",
+  description: "Sample plugin for SDK fixture use",
+  tags: ["backend"],
+  capabilities: { storage: "rw", telemetry: true }
+});
+
+export { createMockHostServices, createMockProfileContext, samplePlugin };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map