@vibecontrols/plugin-sdk 2026.509.1

package/dist/cli/index.js

@@ -0,0 +1,104 @@
+// 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;
+  }
+};
+
+export { CliCommandBuilder, maybePrintJson, pickOutputMode, redact, runMultimode };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/config/index.d.ts

@@ -0,0 +1,34 @@
+import { HostServices, SdkLogger } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/config
+ *
+ * `ConfigManager` resolves plugin config in this order:
+ *   1. env var `VIBE_<PLUGIN>_<KEY>` (uppercase, hyphen→underscore)
+ *   2. `hostServices.getConfig(<plugin>.<key>)` — plugin-section config.json
+ *   3. caller-supplied default
+ *
+ * Type coercion helpers (`getInt`, `getBoolean`) parse the resolved string
+ * with sane fallbacks; invalid values warn through the logger and return
+ * the default.
+ */
+
+declare class ConfigManager {
+    private readonly pluginName;
+    private readonly hostServices?;
+    private readonly logger?;
+    private readonly envPrefix;
+    constructor(pluginName: string, hostServices?: HostServices | undefined, logger?: SdkLogger | undefined);
+    private envName;
+    /**
+     * Resolve a string config value. Returns `defaultValue` (or undefined)
+     * when neither env nor host config has it.
+     */
+    get(key: string, defaultValue?: string): Promise<string | undefined>;
+    /** Like `get`, but throw if the key resolves to undefined / empty. */
+    getRequired(key: string): Promise<string>;
+    getInt(key: string, defaultValue?: number): Promise<number | undefined>;
+    getBoolean(key: string, defaultValue?: boolean): Promise<boolean | undefined>;
+}
+
+export { ConfigManager };

package/dist/config/index.js

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

package/dist/contract/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @vibecontrols/plugin-sdk/contract
+ *
+ * The plugin contract v2 surface. Mirrors the agent's `HostServices` /
+ * `ProfileContext` / `PluginCapabilities` types but every host-side field
+ * is **optional** so a plugin author writing against the SDK can rely on
+ * partial host implementations (tests, alt-hosts, future agents that drop
+ * obsolete services). Plugins MUST optional-chain every host-side call.
+ *
+ * Source of truth (READ-ONLY mirror): vibecontrols-agent/src/core/plugin-system.ts:155-242,
+ *                                    vibecontrols-agent/src/core/profile-context.ts:62-151,
+ *                                    vibecontrols-agent/src/core/plugin-capabilities.ts.
+ */
+interface PluginCapabilities {
+    storage?: "none" | "read" | "rw";
+    secrets?: "none" | "read" | "rw";
+    gateway?: boolean;
+    broadcast?: boolean;
+    subprocess?: boolean;
+    audit?: boolean;
+    telemetry?: boolean;
+    singletonOnly?: boolean;
+    requiresIsolation?: boolean;
+}
+declare const FULL_TRUST_CAPS: Required<PluginCapabilities>;
+type PluginTag = "backend" | "frontend" | "cli" | "provider" | "adapter" | "integration";
+type PrerequisiteKind = "binary" | "npm" | "pip" | "cargo" | "manual";
+interface Prerequisite {
+    name: string;
+    kind: PrerequisiteKind;
+    requiresSudo: boolean;
+    version?: string;
+    install?: string;
+}
+interface StorageProvider {
+    get<T = unknown>(namespace: string, key: string): Promise<T | null>;
+    set<T = unknown>(namespace: string, key: string, value: T): Promise<void>;
+    delete(namespace: string, key: string): Promise<boolean>;
+    list?(namespace: string): Promise<string[]>;
+}
+interface ServiceRegistry {
+    registerService<T>(type: string, name: string, instance: T): void;
+    getService<T>(type: string, name: string): T | undefined;
+    listProvidersForType?(type: string): string[];
+}
+interface SdkLogger {
+    debug?(source: string, message: string, metadata?: Record<string, unknown>): void;
+    info?(source: string, message: string, metadata?: Record<string, unknown>): void;
+    warn?(source: string, message: string, metadata?: Record<string, unknown>): void;
+    error?(source: string, message: string, metadata?: Record<string, unknown>): void;
+    setLevel?(level: string): void;
+}
+/**
+ * The host surface a plugin can rely on. Every member is optional —
+ * downstream plugins must defensively use optional chaining or check
+ * presence before invoking. Mirrors agent's `HostServices` (plugin-system.ts:155-242)
+ * but type-loosened so SDK consumers don't need to depend on the agent.
+ */
+interface HostServices {
+    storage?: StorageProvider;
+    logger?: SdkLogger;
+    serviceRegistry?: ServiceRegistry;
+    getProvider?<T = unknown>(type: string): T | undefined;
+    getAgentBaseUrl?(): string;
+    getAgentVersion?(): string;
+    broadcast?(type: string, payload: unknown): void;
+    workspaceQuery?<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>): Promise<{
+        data?: T;
+        errors?: Array<{
+            message: string;
+        }>;
+    }>;
+    isGatewayConfigured?(): boolean;
+    getAgentRecordId?(): Promise<string | null>;
+    getWorkspaceId?(): Promise<string | null>;
+    getConfig?(key: string): Promise<string | undefined>;
+    getPluginRegistry?(): string;
+    getDataDir?(): string;
+    cliContributors?: {
+        addStatusSection?(section: unknown): void;
+        addDoctorCheck?(check: unknown): void;
+    };
+    audit?: {
+        emit(event: string, payload?: Record<string, unknown>): void;
+    };
+    telemetry?: {
+        emit(event: string, payload?: Record<string, unknown>): void;
+    };
+    os?: unknown;
+}
+interface ProfileContext {
+    name: string;
+    dataDir: string;
+    logger?: SdkLogger;
+    audit?: {
+        emit(source: string, event: string, payload?: Record<string, unknown>): void;
+    };
+    telemetry?: {
+        emit(event: string, payload?: Record<string, unknown>): void;
+    };
+}
+interface VibePlugin {
+    name: string;
+    version: string;
+    description?: string;
+    tags?: PluginTag[];
+    capabilities?: PluginCapabilities;
+    prerequisites?: Prerequisite[];
+    cliCommand?: string;
+    apiPrefix?: string;
+    createRoutes?: () => unknown;
+    onServerStart?: (app: unknown, hostServices: HostServices) => void | Promise<void>;
+    onServerStop?: (hostServices: HostServices) => void | Promise<void>;
+    onCliSetup?: (program: unknown, hostServices: HostServices) => void;
+}
+type VibePluginFactory = (ctx: ProfileContext) => VibePlugin;
+
+export { FULL_TRUST_CAPS, type HostServices, type PluginCapabilities, type PluginTag, type Prerequisite, type PrerequisiteKind, type ProfileContext, type SdkLogger, type ServiceRegistry, type StorageProvider, type VibePlugin, type VibePluginFactory };

package/dist/contract/index.js

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

package/dist/http/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @vibecontrols/plugin-sdk/http
+ *
+ * Minimal `HttpClient` with timeout (AbortController), retries with
+ * exponential backoff, and JSON parse helpers. Wraps the platform-native
+ * `fetch` (Bun + Node 24 both ship it). No third-party HTTP deps so this
+ * module stays peerless.
+ */
+interface HttpClientOptions {
+    /** Per-request timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+    /** Total attempts (initial + retries). Default 3. */
+    maxAttempts?: number;
+    /** Default headers merged into every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Override fetch implementation (tests). */
+    fetchImpl?: typeof fetch;
+}
+interface RequestOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxAttempts;
+    private readonly defaultHeaders;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, options?: HttpClientOptions);
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private request;
+}
+
+export { HttpClient, type HttpClientOptions, type RequestOptions };

package/dist/http/index.js

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { FULL_TRUST_CAPS, HostServices, PluginCapabilities, PluginTag, Prerequisite, PrerequisiteKind, ProfileContext, SdkLogger, ServiceRegistry, StorageProvider, VibePlugin, VibePluginFactory } from './contract/index.js';
+export { LifecycleHooks, LifecycleSpec, createLifecycleHooks } from './lifecycle/index.js';
+export { CliCommandBuilder, MultimodeOptions, OutputFlags, OutputMode, StatusCommandSpec, maybePrintJson, pickOutputMode, redact, runMultimode } from './cli/index.js';
+export { ApiKeyResolver, RoutesBuilder } from './routes/index.js';
+export { TelemetryEmitter } from './telemetry/index.js';
+export { BoundLogger } from './log/index.js';
+export { NamespaceStore, TypedStore } from './storage/index.js';
+export { ConfigManager } from './config/index.js';
+export { findAvailablePort, gracefulKill, isProcessAlive, sleep } from './subprocess/index.js';
+export { HttpClient, HttpClientOptions, RequestOptions } from './http/index.js';
+export { CliContribution, ProviderRegistry } from './providers/index.js';
+export { AuditLogger } from './audit/index.js';
+export { BroadcastEmitter } from './broadcast/index.js';
+import 'commander';
+import 'elysia';