@nullplatform/plugin 0.0.2

package/README.md

@@ -0,0 +1,85 @@
+<h2 align="center">
+    <a href="https://nullplatform.com" target="blank_">
+        <img height="100" alt="Nullplatform" src="https://nullplatform.com/favicon/android-chrome-192x192.png" />
+    </a>
+    <br>
+    <br>
+    @nullplatform/plugin
+    <br>
+</h2>
+
+TypeScript SDK for building nullplatform plugins. Handles gRPC transport (HashiCorp go-plugin protocol), action routing, `--describe`, and `--publish`.
+
+## Install
+
+```bash
+bun add @nullplatform/plugin
+```
+
+## Usage
+
+### Scope plugin
+
+```typescript
+import { defineScope } from "@nullplatform/plugin/scope";
+
+defineScope({
+  name: "kubernetes-k3d",
+  version: "0.0.1",
+  category: "containers",
+  provider: "kubernetes",
+
+  schema: {
+    type: "object",
+    properties: {
+      memory: { type: "string", default: "2Gi" },
+    },
+  },
+
+  actions: {
+    "create-scope": {
+      input: { type: "object" },
+      handler: async (notification, emit) => {
+        // provision infrastructure
+        return { domain: "app.k3d.local" };
+      },
+    },
+  },
+});
+```
+
+### Simple plugin (custom command)
+
+```typescript
+import { createPlugin, registerManifest } from "@nullplatform/plugin";
+
+registerManifest({ name: "my-plugin", version: "0.0.1", command_types: ["custom"] });
+
+createPlugin({
+  async execute(req) {
+    return { success: true, data: { message: "done" } };
+  },
+}).start();
+```
+
+## Subpath exports
+
+| Import | Description |
+|---|---|
+| `@nullplatform/plugin` | Core: createPlugin, registerManifest, types |
+| `@nullplatform/plugin/scope` | defineScope API |
+| `@nullplatform/plugin/schema` | JSON Schema type inference |
+| `@nullplatform/plugin/testing` | Test harness: startPluginProcess, factories |
+| `@nullplatform/plugin/workflow` | Workflow integration (StreamingExecutionObserver) |
+
+## CLI integration
+
+Plugins are scaffolded with `np plugin init` and managed via mise tasks:
+
+```bash
+mise run dev          # local dev with hot reload
+mise run dev:agent    # dev with np-agent attached
+mise run test         # run tests
+mise run build        # compile to standalone binary
+mise run publish      # publish to platform
+```

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nullplatform/plugin",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schema": "./src/schema.ts",
+    "./scope": "./src/scope/index.ts",
+    "./testing": "./src/testing/index.ts",
+    "./workflow": "./src/workflow.ts"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.13.0",
+    "@grpc/proto-loader": "^0.7.0",
+    "yaml": "^2.7.0"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nullplatform/plugin-libraries.git",
+    "directory": "js"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@nullplatform/workflow-engine": ">=0.0.1 <1.0.0",
+    "@nullplatform/workflow-engine-in-memory": ">=0.0.1 <1.0.0",
+    "@nullplatform/workflow-types": ">=0.0.1 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nullplatform/workflow-engine": {
+      "optional": true
+    },
+    "@nullplatform/workflow-engine-in-memory": {
+      "optional": true
+    },
+    "@nullplatform/workflow-types": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "json-schema-to-ts": "^3.1.1"
+  }
+}

package/src/api.ts

@@ -0,0 +1,206 @@
+/**
+ * Platform API helpers — typed wrappers around nullplatform REST API.
+ *
+ * Generic helpers usable by any plugin type (scope, service, etc.).
+ * Replicates what `np service workflow build-context` does in the Go CLI.
+ *
+ * Usage:
+ *   import { api } from "@nullplatform/plugin";
+ *
+ *   const scope = await api.scope("12345");
+ *   const deployment = await api.deployment("67890");
+ *   const providers = await api.providers(scope.nrn, ["cloud-providers"]);
+ */
+
+// ─── Configuration ───────────────────────────────────────────────────
+
+const TIMEOUT_MS = 30_000;
+
+function getConfig() {
+  const apiUrl = process.env.NP_API_URL ?? "https://api.nullplatform.com";
+  const apiKey = process.env.NULLPLATFORM_APIKEY ?? "";
+  if (!apiKey) {
+    throw new Error("NULLPLATFORM_APIKEY environment variable is not set");
+  }
+  return { apiUrl, apiKey };
+}
+
+async function fetchJson<T>(path: string, params?: Record<string, string>): Promise<T> {
+  const { apiUrl, apiKey } = getConfig();
+  const url = new URL(path, apiUrl);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== "") url.searchParams.set(k, v);
+    }
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+  try {
+    const res = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json",
+      },
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`API ${res.status} ${res.statusText}: ${path}${body ? ` — ${body}` : ""}`);
+    }
+
+    return res.json() as Promise<T>;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// ─── Entity types ────────────────────────────────────────────────────
+
+export interface ScopeInfo {
+  id: string;
+  slug: string;
+  nrn: string;
+  domain: string;
+  asset_name: string;
+  current_active_deployment: string;
+  capabilities: Record<string, unknown>;
+  dimensions: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export interface DeploymentInfo {
+  id: string;
+  status: string;
+  release_id: string;
+  strategy_data: {
+    desired_switched_traffic?: number;
+  };
+  [key: string]: unknown;
+}
+
+export interface ApplicationInfo {
+  id: string;
+  slug: string;
+  [key: string]: unknown;
+}
+
+export interface NamespaceInfo {
+  id: string;
+  slug: string;
+  [key: string]: unknown;
+}
+
+export interface AccountInfo {
+  id: string;
+  slug: string;
+  [key: string]: unknown;
+}
+
+export interface AssetInfo {
+  type: string;
+  url: string;
+  [key: string]: unknown;
+}
+
+export interface ParameterResult {
+  variable: string;
+  values: Array<{ value: string }>;
+}
+
+export type ProvidersMap = Record<string, Record<string, unknown>>;
+
+// ─── API functions ───────────────────────────────────────────────────
+
+export async function scope(id: string): Promise<ScopeInfo> {
+  return fetchJson<ScopeInfo>(`/scope/${id}`);
+}
+
+export async function deployment(id: string): Promise<DeploymentInfo> {
+  return fetchJson<DeploymentInfo>(`/deployment/${id}`);
+}
+
+export async function application(id: string): Promise<ApplicationInfo> {
+  return fetchJson<ApplicationInfo>(`/application/${id}`);
+}
+
+export async function namespace(id: string): Promise<NamespaceInfo> {
+  return fetchJson<NamespaceInfo>(`/namespace/${id}`);
+}
+
+export async function account(id: string): Promise<AccountInfo> {
+  return fetchJson<AccountInfo>(`/account/${id}`);
+}
+
+/**
+ * Fetch asset by following the release → build → asset chain.
+ * Mirrors the Go CLI's fetchAndStoreAsset logic.
+ */
+export async function asset(releaseId: string, assetName: string): Promise<AssetInfo> {
+  const release = await fetchJson<{ build_id: string }>(`/release/${releaseId}`);
+  const result = await fetchJson<{ results: AssetInfo[] }>("/asset", {
+    build_id: release.build_id,
+    name: assetName,
+  });
+
+  if (!result.results?.length) {
+    throw new Error(`No asset found for build_id=${release.build_id}, name=${assetName}`);
+  }
+
+  return result.results[0];
+}
+
+/**
+ * Fetch parameters for a scope by NRN.
+ * Mirrors --include-secrets flag from build-context.
+ */
+export async function parameters(
+  nrn: string,
+  opts: { includeSecrets?: boolean } = {},
+): Promise<Record<string, string>> {
+  const result = await fetchJson<{ results: ParameterResult[] }>("/parameter", {
+    nrn,
+    show_secret_values: String(opts.includeSecrets ?? false),
+    interpolate: "true",
+    limit: "500",
+  });
+
+  const params: Record<string, string> = {};
+  for (const p of result.results ?? []) {
+    if (p.variable && p.values?.[0]?.value !== undefined) {
+      params[p.variable] = p.values[0].value;
+    }
+  }
+  return params;
+}
+
+/**
+ * Fetch providers by NRN and categories.
+ * Mirrors --provider-categories flag from build-context.
+ * Returns providers keyed by category slug with their attributes.
+ */
+export async function providers(
+  nrn: string,
+  categories: string[],
+  dimensions?: Record<string, string>,
+): Promise<ProvidersMap> {
+  const dimensionFilter = dimensions
+    ? Object.entries(dimensions).map(([k, v]) => `${k}:${v}`).join(",")
+    : undefined;
+
+  const result = await fetchJson<{
+    results: Array<{ category: string; attributes: Record<string, unknown> }>;
+  }>("/provider", {
+    nrn,
+    categories: categories.join(","),
+    ...(dimensionFilter ? { dimensions: dimensionFilter } : {}),
+  });
+
+  const map: ProvidersMap = {};
+  for (const provider of result.results ?? []) {
+    map[provider.category] = provider.attributes ?? {};
+  }
+  return map;
+}

package/src/create-plugin.ts

@@ -0,0 +1,24 @@
+/**
+ * createPlugin() — the public entry point for building np-agent plugins.
+ *
+ * Usage:
+ *   createPlugin({
+ *     async execute(req) {
+ *       // do work
+ *       return { success: true, data: { ... } };
+ *     }
+ *   }).start();
+ */
+
+import type { PluginHandler, Plugin } from "./types";
+import { loadManifest } from "./internal/manifest";
+import { startGrpcServer } from "./internal/grpc-server";
+
+export function createPlugin(handler: PluginHandler): Plugin {
+  return {
+    start() {
+      const manifest = loadManifest();
+      startGrpcServer(handler, manifest);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @nullplatform/plugin — gRPC transport for np-agent plugins.
+ *
+ * This SDK is ONLY the transport layer. It handles:
+ * - go-plugin handshake
+ * - gRPC Execute/Capabilities/Health/Version
+ * - Plugin manifest loading
+ *
+ * For progress tracking, use @nullplatform/workflow.
+ * For orchestration, use @nullplatform/workflow.
+ * They compose — a plugin CAN use the workflow SDK, but doesn't have to.
+ */
+
+export { createPlugin } from "./create-plugin";
+export { registerManifest } from "./internal/manifest";
+
+export type {
+  PluginHandler,
+  Plugin,
+  ExecuteRequest,
+  ExecuteResult,
+  ExecuteOutput,
+  PluginManifest,
+} from "./types";
+
+export * as api from "./api";
+
+export type { NpJSONSchema, NpKeywords } from "./schema";
+export type { infer as InferSchema } from "./schema";