@vibecontrols/plugin-sdk 2026.509.1

package/LICENSE

@@ -0,0 +1,22 @@
+Proprietary License
+
+Copyright (c) 2025-2026 Burdenoff Consultancy Services Pvt. Ltd. All rights reserved.
+
+This software and associated documentation files (the "Software") are the proprietary
+property of Burdenoff Consultancy Services Pvt. Ltd. and its affiliates.
+
+UNAUTHORIZED COPYING, MODIFICATION, DISTRIBUTION, OR USE OF THIS SOFTWARE, VIA ANY
+MEDIUM, IS STRICTLY PROHIBITED.
+
+The Software is provided under a proprietary license. You may use the Software only in
+accordance with the terms of your license agreement with Burdenoff Consultancy Services
+Pvt. Ltd.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, contact: contact@vibecontrols.com

package/README.md

@@ -0,0 +1,206 @@
+# @vibecontrols/plugin-sdk
+
+Shared contract, lifecycle, CLI, telemetry, storage, and HTTP helpers consumed by every `@vibecontrols/vibe-plugin-*` package and by the agent itself.
+
+## Install
+
+```bash
+bun add @vibecontrols/plugin-sdk
+# or
+npm install @vibecontrols/plugin-sdk
+```
+
+## Modules
+
+Granular subpath imports so plugins tree-shake aggressively. The most-used helpers are also re-exported from the root barrel `@vibecontrols/plugin-sdk`.
+
+### `contract` — types
+
+The plugin contract v2 surface. `VibePlugin`, `HostServices`, `PluginCapabilities`, `Prerequisite`, `StorageProvider`, `ServiceRegistry`, plus `FULL_TRUST_CAPS`. Every host-side field is optional so plugins keep working against partial hosts.
+
+```ts
+import type { VibePluginFactory, VibePlugin } from "@vibecontrols/plugin-sdk/contract";
+
+export const createPlugin: VibePluginFactory = (ctx) => ({
+  name: "demo",
+  version: "1.0.0",
+  capabilities: { storage: "rw", telemetry: true },
+  tags: ["backend"],
+});
+```
+
+### `lifecycle` — boilerplate-free init / shutdown
+
+`createLifecycleHooks` collapses `onServerStart` / `onServerStop` boilerplate, emits a one-shot `<plugin>.ready` telemetry event, and skips on unsupported platforms.
+
+```ts
+import { createLifecycleHooks } from "@vibecontrols/plugin-sdk/lifecycle";
+
+const { onServerStart, onServerStop } = createLifecycleHooks({
+  name: "demo",
+  telemetryEventName: "demo.ready",
+  onInit: async (hostServices) => {
+    /* ... */
+  },
+});
+```
+
+### `cli` — multimode + redaction + command builder
+
+`runMultimode<T>` selects between JSON / plain / interactive renderers from a single `fetchData` call. `redact(value)` strips secrets recursively. `CliCommandBuilder` registers status sub-commands with `--json` / `--plain` baked in.
+
+```ts
+import { CliCommandBuilder, redact } from "@vibecontrols/plugin-sdk/cli";
+
+new CliCommandBuilder(program).addStatusCommand("status", {
+  description: "Show plugin status",
+  fetchData: () => fetchStatus(),
+  redact: true,
+});
+```
+
+### `routes` — Elysia fluent builder
+
+```ts
+import { RoutesBuilder } from "@vibecontrols/plugin-sdk/routes";
+
+const app = new RoutesBuilder("demo", hostServices)
+  .withPrefix("/api/demo")
+  .withAuth(() => process.env.AGENT_API_KEY ?? "")
+  .withErrorHandler()
+  .withLogging()
+  .build();
+
+app.get("/ping", () => ({ ok: true }));
+```
+
+### `telemetry` — auto-tagged emitter
+
+```ts
+import { TelemetryEmitter } from "@vibecontrols/plugin-sdk/telemetry";
+
+const tel = new TelemetryEmitter("demo", "1.0.0", hostServices);
+tel.emitReady({ port: 3005 });
+tel.emitError(new Error("boom"));
+```
+
+### `log` — source-bound logger
+
+```ts
+import { BoundLogger } from "@vibecontrols/plugin-sdk/log";
+
+const log = new BoundLogger(hostServices.logger, "demo");
+log.info("started", { port: 3005 });
+```
+
+### `storage` — typed JSON-encoded helpers
+
+```ts
+import { TypedStore, NamespaceStore } from "@vibecontrols/plugin-sdk/storage";
+
+const ns = new NamespaceStore(hostServices.storage!, "demo");
+const settings = ns.typed<{ enabled: boolean }>("settings");
+await settings.set({ enabled: true });
+const current = await settings.get();
+```
+
+### `config` — env + host config + defaults
+
+```ts
+import { ConfigManager } from "@vibecontrols/plugin-sdk/config";
+
+const cfg = new ConfigManager("demo", hostServices, hostServices.logger);
+const port = (await cfg.getInt("port", 3005))!;
+const apiKey = await cfg.getRequired("api_key"); // throws if missing
+```
+
+### `subprocess` — cross-platform process helpers
+
+```ts
+import {
+  gracefulKill,
+  isProcessAlive,
+  findAvailablePort,
+  sleep,
+} from "@vibecontrols/plugin-sdk/subprocess";
+
+const port = await findAvailablePort(7000);
+await gracefulKill(child.pid, 3000);
+```
+
+### `http` — HttpClient with retries + timeout
+
+```ts
+import { HttpClient } from "@vibecontrols/plugin-sdk/http";
+
+const client = new HttpClient("https://api.example.com", { timeoutMs: 5000 });
+const data = await client.get<{ ok: boolean }>("/v1/status");
+```
+
+### `providers` — ProviderRegistry façade
+
+```ts
+import { ProviderRegistry } from "@vibecontrols/plugin-sdk/providers";
+
+const reg = new ProviderRegistry(hostServices);
+reg.registerProvider("tunnel", "cloudflare", myCloudflareProvider);
+const all = reg.listProviders("tunnel");
+```
+
+### `audit` — bound source emitter
+
+```ts
+import { AuditLogger } from "@vibecontrols/plugin-sdk/audit";
+
+const audit = new AuditLogger("demo", hostServices);
+audit.emit("started", { port: 3005 });
+```
+
+### `broadcast` — typed WebSocket emitter
+
+```ts
+import { BroadcastEmitter } from "@vibecontrols/plugin-sdk/broadcast";
+
+new BroadcastEmitter(hostServices).broadcast("demo.event", { count: 1 });
+```
+
+### `testing` — Bun-mock factories
+
+Run with `bun test` (depends on the runtime `bun:test` import).
+
+```ts
+import { createMockHostServices, createMockProfileContext } from "@vibecontrols/plugin-sdk/testing";
+
+const hs = createMockHostServices({ getAgentVersion: () => "test" });
+const ctx = createMockProfileContext();
+```
+
+## Compatibility Matrix
+
+| SDK version  | Agent version  | Plugin contract             |
+| ------------ | -------------- | --------------------------- |
+| `2026.509.x` | `>=2026.509.1` | v2 (`createPlugin` factory) |
+
+## Boilerplate
+
+Downstream plugins can extend the shared configs in `boilerplate/`:
+
+- `tsconfig.base.json` — strict TS + ESM
+- `eslint.config.base.js` — no-any, no-eslint-disable, max-warnings 0
+- `lefthook.base.yml` — pre-push sanity gate
+- `bunfig.toml` — Verdaccio scope wiring
+- `.github/workflows/release.template.yml` — CalVer publish pipeline
+- `package.template.json` — minimal starter package.json
+
+See `templates/plugin-scaffold.md` for the recommended layout.
+
+## Contributing
+
+1. `bun install`
+2. `bun run sanity` must be green (0 errors, 0 warnings)
+3. Trunk-based: `main` only. CalVer release via `gh workflow run release.yml -f version=YYYY.MDD.PATCH`.
+4. Spec: `~/products/vibecontrols/vibecontrols-specs/architecture/PLUGIN_SDK_EXTRACTION.md`
+
+## License
+
+Proprietary — Burdenoff Consultancy Services Pvt. Ltd. See `LICENSE`.

package/boilerplate/.github/workflows/release.template.yml

@@ -0,0 +1,57 @@
+# Release — publish a vibe-plugin-* package to npmjs (public) + Verdaccio.
+#
+# Trigger: workflow_dispatch (manual version) or CalVer git-tag push.
+# Replace `@vibecontrols/vibe-plugin-EXAMPLE` with the real package name.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "[0-9][0-9][0-9][0-9].[0-9]*.[0-9]*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "CalVer version (YYYY.MDD.PATCH). Leave empty to auto-compute."
+        required: false
+        type: string
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Release to npmjs + Verdaccio
+    runs-on: org-runners
+    timeout-minutes: 15
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - name: Configure Verdaccio scoped registry
+        run: |
+          AUTH=$(echo -n "ci-publisher:${{ secrets.VERDACCIO_CI_PASSWORD }}" | base64)
+          cat > bunfig.toml << EOF
+          [install]
+          exact = true
+          [install.scopes]
+          vibecontrols = { token = "${AUTH}", url = "https://verdaccio.tooling.internal.burdenoff.com/" }
+          burdenoff = { token = "${AUTH}", url = "https://verdaccio.tooling.internal.burdenoff.com/" }
+          EOF
+      - run: bun install --frozen-lockfile
+      - run: bun run sanity
+      - run: bun run build
+      - name: Publish to npmjs
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPMJS_VIBECONTROLS_TOKEN }}" > ~/.npmrc
+          bunx npm publish --access public
+      - name: Publish to Verdaccio
+        run: |
+          echo "//verdaccio.tooling.internal.burdenoff.com/:_authToken=$(echo -n 'ci-publisher:${{ secrets.VERDACCIO_CI_PASSWORD }}' | base64)" > ~/.npmrc
+          bunx npm publish --registry https://verdaccio.tooling.internal.burdenoff.com/

package/boilerplate/README.md

@@ -0,0 +1,41 @@
+# Plugin Boilerplate
+
+Extends-able starters for `@vibecontrols/vibe-plugin-*` packages. Copy or extend from a downstream plugin's config files:
+
+| File                                     | Purpose                                                                  |
+| ---------------------------------------- | ------------------------------------------------------------------------ |
+| `tsconfig.base.json`                     | Strict TS + ESM, ES2022, declaration emit. `extends` from your tsconfig. |
+| `eslint.config.base.js`                  | No `any`, no `@ts-ignore`, no `eslint-disable`. Spread into your config. |
+| `lefthook.base.yml`                      | Pre-push sanity gate.                                                    |
+| `bunfig.toml`                            | Verdaccio scope wiring for `@burdenoff` + `@vibecontrols`.               |
+| `package.template.json`                  | Minimal `package.json` starter.                                          |
+| `.github/workflows/release.template.yml` | CalVer release pipeline (npmjs + Verdaccio).                             |
+
+## Quick start
+
+```bash
+mkdir vibe-plugin-myplugin && cd vibe-plugin-myplugin
+cp ../vibecontrols-plugin-sdk/boilerplate/package.template.json package.json
+cp ../vibecontrols-plugin-sdk/boilerplate/bunfig.toml ./
+cp ../vibecontrols-plugin-sdk/boilerplate/lefthook.base.yml lefthook.yml
+mkdir -p .github/workflows
+cp ../vibecontrols-plugin-sdk/boilerplate/.github/workflows/release.template.yml .github/workflows/release.yml
+bun install
+```
+
+Then point your `tsconfig.json` and `eslint.config.js` at the bases:
+
+```jsonc
+// tsconfig.json
+{
+  "extends": "@vibecontrols/plugin-sdk/boilerplate/tsconfig.base.json",
+  "compilerOptions": { "outDir": "./dist", "noEmit": true },
+  "include": ["src/**/*", "tests/**/*"],
+}
+```
+
+```js
+// eslint.config.js
+import base from "@vibecontrols/plugin-sdk/boilerplate/eslint.config.base.js";
+export default [...base];
+```

package/boilerplate/bunfig.toml

@@ -0,0 +1,13 @@
+# Shared bunfig.toml for vibe-plugin-* packages.
+# Resolves @burdenoff/* and @vibecontrols/* from Verdaccio while public
+# releases also flow through npmjs. CI may overwrite per-environment.
+
+[install]
+exact = true
+
+[run]
+shell = "bun"
+
+[install.scopes]
+burdenoff = { username = "ci-publisher", password = "$VERDACCIO_PASSWORD", url = "https://verdaccio.tooling.internal.burdenoff.com/" }
+vibecontrols = { username = "ci-publisher", password = "$VERDACCIO_PASSWORD", url = "https://verdaccio.tooling.internal.burdenoff.com/" }

package/boilerplate/eslint.config.base.js

@@ -0,0 +1,36 @@
+// Base ESLint config for vibe-plugin-* packages.
+//
+// Usage (downstream eslint.config.js):
+//   import base from "@vibecontrols/plugin-sdk/boilerplate/eslint.config.base.js";
+//   export default [...base, { /* per-package overrides */ }];
+
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import globals from "globals";
+
+export default tseslint.config(
+  {
+    ignores: ["dist/", "node_modules/", "coverage/", ".eslintcache"],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        Bun: "readonly",
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
+);

package/boilerplate/lefthook.base.yml

@@ -0,0 +1,10 @@
+# Shared pre-push sanity gate for vibe-plugin-* packages.
+# Install:
+#   bun add -d lefthook && bunx lefthook install
+# Then either copy this file to lefthook.yml or extend via include.
+
+pre-push:
+  parallel: false
+  commands:
+    sanity:
+      run: bun run sanity

package/boilerplate/package.template.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vibecontrols/vibe-plugin-EXAMPLE",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Replace with the plugin description",
+  "engines": { "bun": ">=1.3.10" },
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/**/*", "!dist/**/*.map", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint ./src ./tests",
+    "lint:sanity": "bun run lint -- --max-warnings 0",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "type:check": "tsc --noEmit",
+    "test": "bun test tests/**/*.test.ts",
+    "clean": "rimraf dist .eslintcache",
+    "prebuild": "bun run clean",
+    "sanity": "bun run format:check && bun run lint:sanity && bun run type:check && bun run test && bun run build"
+  },
+  "dependencies": {
+    "@vibecontrols/plugin-sdk": "^2026.509.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/bun": "^1.3.9",
+    "eslint": "^10.0.1",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.1.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0"
+  },
+  "peerDependencies": {
+    "elysia": ">=1.3.0",
+    "commander": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "elysia": { "optional": true },
+    "commander": { "optional": true }
+  }
+}

package/boilerplate/tsconfig.base.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["bun"],
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": true,
+    "removeComments": false
+  }
+}

package/dist/audit/index.d.ts

@@ -0,0 +1,17 @@
+import { HostServices } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/audit
+ *
+ * `AuditLogger` binds `source` to the plugin name and forwards events to
+ * `hostServices.audit?.emit`. No-op when the host doesn't expose audit.
+ */
+
+declare class AuditLogger {
+    private readonly source;
+    private readonly hostServices?;
+    constructor(source: string, hostServices?: HostServices | undefined);
+    emit(event: string, payload?: Record<string, unknown>): void;
+}
+
+export { AuditLogger };

package/dist/audit/index.js

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

package/dist/broadcast/index.d.ts

@@ -0,0 +1,15 @@
+import { HostServices } from '../contract/index.js';
+
+/**
+ * @vibecontrols/plugin-sdk/broadcast
+ *
+ * Type-safe wrapper over `hostServices.broadcast` — no-op when absent.
+ */
+
+declare class BroadcastEmitter {
+    private readonly hostServices?;
+    constructor(hostServices?: HostServices | undefined);
+    broadcast<T>(type: string, payload: T): void;
+}
+
+export { BroadcastEmitter };

package/dist/broadcast/index.js

@@ -0,0 +1,14 @@
+// src/broadcast/index.ts
+var BroadcastEmitter = class {
+  constructor(hostServices) {
+    this.hostServices = hostServices;
+  }
+  hostServices;
+  broadcast(type, payload) {
+    this.hostServices?.broadcast?.(type, payload);
+  }
+};
+
+export { BroadcastEmitter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/cli/index.d.ts

@@ -0,0 +1,75 @@
+import { Command } from 'commander';
+
+/**
+ * Multi-mode output dispatcher.
+ *
+ * Lifted from vibecontrols-agent/src/cli/utils/multimode.ts but trimmed:
+ * the SDK doesn't ship the agent's `isInteractive()` helper since plugins
+ * can't depend on opentui from the SDK. Instead we use a stdout-isTTY +
+ * env CI/NO_COLOR check inline.
+ */
+type OutputMode = "auto" | "interactive" | "plain" | "json";
+interface OutputFlags {
+    json?: boolean;
+    plain?: boolean;
+    interactive?: boolean;
+}
+interface MultimodeOptions<T> {
+    fetchData: () => Promise<T> | T;
+    plain: (data: T) => void | Promise<void>;
+    interactive?: (data: T) => Promise<void>;
+    json?: (data: T) => unknown;
+    mode?: OutputMode;
+}
+/** Resolve user-supplied CLI flags into an OutputMode. */
+declare function pickOutputMode(flags: OutputFlags): OutputMode;
+declare function runMultimode<T>(opts: MultimodeOptions<T>): Promise<void>;
+/**
+ * Convenience: emit `data` as JSON if `--json` is set; return `true` when
+ * something was printed. Mutating commands (start/stop/install/...) reach
+ * for this when they want a scriptable JSON opt-in.
+ */
+declare function maybePrintJson(flags: OutputFlags, data: unknown): boolean;
+
+/**
+ * Recursive sensitive-field stripper. Replaces values for keys matching the
+ * sensitive regex with the literal string "[redacted]". Walks arrays, plain
+ * objects, and leaves primitives / null / undefined untouched.
+ */
+declare function redact<T>(value: T): T;
+
+/**
+ * CliCommandBuilder — fluent helper that wires the standard `--json` /
+ * `--plain` flags onto a Commander command and routes the action through
+ * `runMultimode`. Removes the ~30-line boilerplate every plugin author
+ * pastes for status/list commands.
+ *
+ * commander is a peerDep — this module imports `Command` as a *type* from
+ * "commander" so the SDK builds without commander present, and runs only
+ * when the consumer installed it.
+ */
+
+interface StatusCommandSpec<T> {
+    description: string;
+    fetchData: () => Promise<T> | T;
+    /** Plain renderer override. Defaults to `JSON.stringify` if absent. */
+    format?: (data: T) => void | Promise<void>;
+    /**
+     * Apply redaction before any renderer. Strips sensitive keys recursively
+     * (see ./redaction.ts).
+     */
+    redact?: boolean;
+}
+declare class CliCommandBuilder {
+    private readonly program;
+    constructor(program: Command);
+    /**
+     * Register a `<name>` sub-command that fetches once and renders via
+     * `--json` / `--plain` / interactive (when stdout is a TTY).
+     */
+    addStatusCommand<T>(name: string, spec: StatusCommandSpec<T>): this;
+    /** Escape hatch: hand back the underlying commander Command. */
+    command(): Command;
+}
+
+export { CliCommandBuilder, type MultimodeOptions, type OutputFlags, type OutputMode, type StatusCommandSpec, maybePrintJson, pickOutputMode, redact, runMultimode };